chore(compile): remove legacy `.chatmode.md` primitive type

[sergio-sisternes-epam]

Context

Follow-up to the dogfooding PR (closes #695 / #792). The repo's own agent primitives have been migrated to .apm/agents/*.agent.md and the legacy .chatmode.md format is no longer used anywhere in microsoft/apm.

Primitive discovery still scans for the legacy format everywhere:

# src/apm_cli/primitives/discovery.py
LOCAL_PRIMITIVE_PATTERNS = {
    'chatmode': [
        "**/.apm/agents/*.agent.md",
        "**/.github/agents/*.agent.md",
        "**/*.agent.md",
        # Legacy support (.chatmode.md)
        "**/.apm/chatmodes/*.chatmode.md",
        "**/.github/chatmodes/*.chatmode.md",
        "**/*.chatmode.md",
    ],
    ...
}

Matching legacy patterns also exist in DEPENDENCY_PRIMITIVE_PATTERNS and DEPENDENCY_GITHUB_PRIMITIVE_PATTERNS, plus any related parsing / integrator / test fixtures.

Proposal

1. Deprecation notice -- one release cycle. Emit a [!] warning when any .chatmode.md file is discovered, pointing contributors at .agent.md.
2. Ecosystem sweep -- audit the public marketplace / known APM packages for any consumer still shipping .chatmode.md. Publish a migration guide if found.
3. Removal PR -- drop the legacy patterns from discovery.py, remove the chatmode integrator fallback, and update tests / docs.

Removing the format simplifies discovery, shrinks the test surface, and removes the chatmode / agent naming confusion for new contributors.

Open questions

• Do we want the deprecation warning gated on target=all / target=copilot specifically, or unconditional?
• Is there data on how many published packages still use .chatmode.md? If zero, we can skip straight to removal.

Labels

breaking-change, compilation, tech-debt

[github-actions]

Triage decision

accept

Proposed labels

area/package-authoring
area/cli
area/docs-site
type/refactor
status/accepted
priority/low

Note: breaking-change is proposed for this issue but is not in the current label taxonomy allow-list; a maintainer should manually apply it if desired.

Milestone

0.9.4

Suggested next action

Open a deprecation-warning PR that emits [!] at .chatmode.md discovery and links to a migration guide; run the ecosystem sweep in parallel to determine if full removal can follow in the same milestone.

Suggested issue comment

The proposal is accepted. Removing the `.chatmode.md` legacy format is the right cleanup now that `microsoft/apm` has fully migrated to `.apm/agents/*.agent.md`.

Suggested approach:
1. **Deprecation warning PR** -- emit a `[!]` warning when any `.chatmode.md` file is discovered, pointing contributors to `.agent.md`. This can ship to 0.9.4.
2. **Ecosystem sweep** -- audit the public marketplace for any consumer still shipping `.chatmode.md`. If the sweep finds zero, skip the deprecation cycle and go straight to removal.
3. **Removal PR** -- drop legacy patterns from `discovery.py`, integrator fallbacks, and test fixtures.

On the open questions:
- The deprecation warning should be unconditional (not gated on a specific target) -- if a file is discovered, the warning fires regardless of target.
- Run the marketplace sweep as part of the deprecation PR review; results go in the PR description.

Please also manually apply `breaking-change` (outside the auto-triage taxonomy) and add a migration note to `docs/src/content/docs/`. CHANGELOG entry under `Deprecated`.

Per-lens notes (collapsed)

DevX UX Expert -- User-Need Reviewer

The deprecation and removal of .chatmode.md is the correct developer experience lifecycle. The 3-step approach (warn -> sweep -> remove) follows the standard package manager breaking-change pattern. The [!] discovery warning is idiomatic and gives external packages a clear migration path. The APM repo itself has already migrated, so the internal impact is zero.

Supply Chain Security Expert -- Risk-Surface Reviewer

No risk-surface implication. Removing a legacy parsing path slightly reduces attack surface by eliminating a dead code path. No theme/security label needed; the issue is purely internal cleanup.

OSS Growth Hacker -- Contributor-Tone Reviewer

Not activated -- author is a core collaborator; this is internal cleanup tracking with no first-time contributor angle.

Python Architect -- Architecture Reviewer

The removal spans discovery.py, DEPENDENCY_PRIMITIVE_PATTERNS, DEPENDENCY_GITHUB_PRIMITIVE_PATTERNS, integrator fallbacks, and test fixtures -- a well-understood scope. The 3-step plan is sound and does not require a separate design document. The open questions (unconditional vs gated deprecation; ecosystem data) are minor implementation decisions for the PR author. status/accepted is appropriate.

Doc Writer -- Documentation Reviewer

A migration guide is implied if the ecosystem sweep finds external consumers of .chatmode.md. area/docs-site rides as secondary to remind the implementing PR to add a migration note to the docs site. The suggested comment is clear and grounded in user vocabulary.

APM CEO -- Triage Arbiter

Accepted. The cleanup is overdue and the deprecation cycle is the right approach for a breaking change. priority/low -- the APM repo has migrated; external ecosystem impact is unknown but the deprecation warning gives consumers time to adapt. Note that breaking-change should be applied manually since it is outside the triage taxonomy allow-list. Milestone: 0.9.4 for the deprecation warning step.

{
  "decision": "accept",
  "decision_detail": "",
  "theme": null,
  "areas": ["area/package-authoring", "area/cli", "area/docs-site"],
  "type": "type/refactor",
  "status": "status/accepted",
  "priority": "priority/low",
  "preserved_labels": [],
  "milestone": "0.9.4",
  "next_action": "Open a deprecation-warning PR emitting [!] at .chatmode.md discovery with a migration guide pointer; run the ecosystem sweep in parallel to determine if removal can follow in the same milestone.",
  "comment_markdown": "The proposal is accepted. Removing the `.chatmode.md` legacy format is the right cleanup now that `microsoft/apm` has fully migrated to `.apm/agents/*.agent.md`.\n\nSuggested approach:\n1. Deprecation warning PR -- emit a [!] warning at .chatmode.md discovery, pointing to .agent.md. Ships to 0.9.4.\n2. Ecosystem sweep -- audit the public marketplace. If zero consumers found, skip deprecation cycle.\n3. Removal PR -- drop legacy patterns from discovery.py, integrator fallbacks, and test fixtures.\n\nDeprecation warning should be unconditional (not gated on a specific target). Please also manually apply `breaking-change` and add a migration note to docs/src/content/docs/. CHANGELOG entry under `Deprecated`."
}

---

Triage status: agentic proposal pending human ratification.
Silence is approval. Maintainers can:

• Override any label or milestone above by editing it directly --
  human edits are authoritative and will not be reverted on
  subsequent runs.
• Re-trigger triage by applying the status/needs-triage label, or
  by removing status/triaged to enroll the issue in the next
  daily sweep.

Posted by the Triage Panel workflow. See .apm/skills/apm-triage-panel for the panel skill.

Generated by Triage Panel · ● 2.2M · ◷