feat(init): detect agentrc and suggest it in Next Steps

[danielmeppiel]

Why

APM and agentrc are complementary tools: agentrc generates tailored agent instructions from real code analysis, APM distributes and governs them across teams. The agentrc side already bridges to APM — agentrc init detects APM and offers to run apm init (agentrc PR #94, merged).

The reverse bridge is missing. Developers who discover APM first should learn about agentrc at the right moment: when they just initialized a project and have no agent instructions yet.

What

After apm init creates apm.yml, the "Next Steps" panel should contextually suggest agentrc — not as a prompt or subprocess call, but as an informational next step alongside the existing ones.

Behavior matrix

State	What changes
agentrc in PATH + no instructions exist	First next step becomes: Generate agent instructions: agentrc init
agentrc not in PATH + no instructions exist	Tip line after the panel: Tip: use agentrc to generate tailored agent instructions from your codebase. https://github.com/microsoft/agentrc
Instructions already exist (.github/copilot-instructions.md, AGENTS.md, etc.)	No mention — we do not presume how they got there
--yes mode	Next step text included in output (informational, no interaction)

Why "Next Steps" and not a prompt

APM init is fast and deterministic — no LLM calls, no network beyond git config detection. Running agentrc init as a subprocess would take 30-60s (Copilot SDK calls) and break the flow. A next step is a suggestion the user acts on when ready. Same pattern as npm scaffolders printing what to do next.

How

~30 lines in src/apm_cli/commands/init.py:

1. Add detection helper:

import shutil
from pathlib import Path

def _detect_agentrc(project_root: Path) -> tuple[bool, bool]:
    """Returns (agentrc_installed, has_instructions)."""
    installed = shutil.which("agentrc") is not None
    has_instructions = any([
        (project_root / ".github" / "copilot-instructions.md").exists(),
        (project_root / "AGENTS.md").exists(),
        (project_root / ".github" / "instructions").is_dir(),
    ])
    return installed, has_instructions

2. Modify next steps building (around line 134-157) to conditionally prepend the agentrc step.

3. Add tip after the panel when agentrc not installed and no instructions found.

No new dependencies, no prompts, no subprocess calls.

Related

• agentrc epic: microsoft/agentrc#96
• agentrc-side init bridge (merged): microsoft/agentrc#94
• Cross-docs (merged): microsoft/apm#509

[github-actions]

Triage decision

accept

Proposed labels

area/cli
type/feature
status/accepted
priority/low

Milestone

0.9.4

Suggested next action

Implement the _detect_agentrc helper and the behavior matrix in src/apm_cli/commands/init.py (approximately 30 lines), following the code sketch in the issue body -- no new dependencies or prompts required.

Suggested issue comment

This closes the APM-side of the agentrc integration loop cleanly. The agentrc-to-APM bridge already shipped ([microsoft/agentrc#94](https://github.com/microsoft/agentrc/pull/94)); this adds the reverse.

The behavior matrix in the issue body is the spec -- implement it as written. A few notes for the PR:

- `shutil.which("agentrc")` and the instruction-file existence checks are the right detection approach.
- The "Next Steps" panel is the right surface -- this is informational text, not a prompt or subprocess.
- In `--yes` mode, the next step text should still appear in output (it is non-interactive by design).
- No new dependencies, no network calls, no prompts.

See the existing `apm init` Next Steps panel at [src/apm_cli/commands/init.py](https://github.com/microsoft/apm/tree/main/src/apm_cli/commands/init.py) around line 134-157.

Per-lens notes (collapsed)

DevX UX Expert -- User-Need Reviewer

This closes the APM-side of the agentrc integration loop. The behavior matrix is well-specified (four distinct states, correct handling of --yes mode). The "Next Steps" panel placement is exactly right -- npm and other package scaffolders use this pattern to suggest complementary tools without interrupting the primary flow. No prompts, no subprocess calls -- purely informational. The user task (discover agentrc at the right moment after APM init) is well-served.

Supply Chain Security Expert -- Risk-Surface Reviewer

No risk-surface implication. shutil.which("agentrc") is a local PATH lookup -- no network calls, no credential access. The instruction-file existence checks are local filesystem reads. area/cli only.

OSS Growth Hacker -- Contributor-Tone Reviewer

Not activated -- author is the project maintainer (COLLABORATOR); standard implementation discussion tone is appropriate.

Python Architect -- Architecture Reviewer

Not activated -- the change is small (~30 lines in commands/init.py), additive (new helper + conditional text in Next Steps panel), and requires no cross-cutting design decisions. No new modules, no schema changes, no interface changes. The code sketch in the issue body is the implementation guide.

Doc Writer -- Documentation Reviewer

Not activated -- this is a CLI output text addition (informational next step), not a new CLI flag or new feature requiring new doc pages. The behavior is self-explanatory from the output itself. No new documentation pages needed; the implementing PR may include a brief update to the apm init reference help text.

APM CEO -- Triage Arbiter

Clean, small, high-value quality-of-life feature that closes a stated integration goal. Accept with priority/low (nice DX improvement, not blocking). No theme label needed -- this is pure CLI infra with no product surface implication beyond the init command. Milestone: 0.9.4 for the next patch release.

{
  "decision": "accept",
  "decision_detail": "",
  "theme": null,
  "areas": ["area/cli"],
  "type": "type/feature",
  "status": "status/accepted",
  "priority": "priority/low",
  "preserved_labels": [],
  "milestone": "0.9.4",
  "next_action": "Implement _detect_agentrc helper and behavior matrix in src/apm_cli/commands/init.py following the code sketch in the issue body.",
  "comment_markdown": "This closes the APM-side agentrc integration loop. Implement the behavior matrix as written (~30 lines in commands/init.py). Informational next step text only -- no prompts, no subprocess, no new dependencies. Works in --yes mode. See init.py around line 134-157."
}

---

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 · ● 1.6M · ◷