docs: rewrite first-package tutorial, fix anatomy hallucination#866
docs: rewrite first-package tutorial, fix anatomy hallucination#866danielmeppiel merged 1 commit intomainfrom
Conversation
The first-package tutorial was prompts-led with cat-heredoc snippets and mis-framed apm compile as a Codex/Gemini fallback. Rewrite it skills-first to match how APM is actually used: - Lead with a real skill (pr-description) using path-header code blocks - Pair it with a custom agent (team-reviewer.agent.md) - Show apm install deploying .apm/ -> .github/ side-by-side - Clarify apm install vs apm compile (different concerns, not nested) - Add apm pack --format plugin as a first-class step (with --plugin scaffold tip), shielding against plugin-skeptic readers - Link to real microsoft/apm and microsoft/apm-sample-package primitives instead of inventing ones Anatomy page: replace the hallucinated writing-skills/SKILL.md example with the real python-architecture/SKILL.md and doc-writer.agent.md, with GitHub permalinks readers can click. Soften the byte-identical claim -- deploy can augment per-runtime when targets need it. All commands, paths, and outputs verified end-to-end against the CLI. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
There was a problem hiding this comment.
Pull request overview
Docs-only update that rewrites the “Your First Package” tutorial to reflect current APM usage (skills/agents first, install vs compile clarified, plugin export included) and fixes a broken/hallucinated reference in the package anatomy page.
Changes:
- Rewrites
getting-started/first-package.mdwith a new end-to-end flow: scaffold -> add skill -> add agent -> install/deploy -> publish -> optional plugin pack. - Fixes the anatomy page’s example tree and replaces a nonexistent skill reference with real repo paths + GitHub links.
- Updates wording around deploy output to treat
.github/as generated output and softens “byte-identical” claims.
Show a summary per file
| File | Description |
|---|---|
| docs/src/content/docs/getting-started/first-package.md | Full tutorial rewrite; adds skill/agent authoring, clarifies apm install vs apm compile, and documents apm pack --format plugin. |
| docs/src/content/docs/introduction/anatomy-of-an-apm-package.md | Fixes the concrete example layout and replaces the hallucinated skill reference with real paths + GitHub links. |
Copilot's findings
- Files reviewed: 2/2 changed files
- Comments generated: 3
| ``` | ||
| [+] <project root> (local) | ||
| |-- 1 agent integrated -> .github/agents/ | ||
| |-- 1 skill(s) integrated -> .github/skills/ | ||
| [i] Added apm_modules/ to .gitignore | ||
| ``` |
There was a problem hiding this comment.
The documented apm install output snippet does not match the current CLI output formatting. download_complete() emits " [+] <project root> (local)" (indented) and the integration logger currently prints "{n} agents integrated" (plural label), so "1 agent integrated" will not appear. Suggest updating this block to either match the exact strings produced by the CLI or wording it as illustrative output (so readers are not looking for exact lines).
| ```bash | ||
| git init | ||
| git add . | ||
| git commit -m "Initial APM package" | ||
| git remote add origin https://github.com/you/my-coding-standards.git | ||
| git add apm.yml .apm/ | ||
| git commit -m "Initial team-skills package" | ||
| git remote add origin https://github.com/your-handle/team-skills.git | ||
| git push -u origin main |
There was a problem hiding this comment.
After running apm install in step 4, the repo now contains .github/ (deployed primitives) and apm.lock.yaml (deployment + pin record), but step 5 tells users to commit only apm.yml and .apm/. This conflicts with other docs that recommend committing deployed runtime dirs and the lockfile for reproducibility and for hosted runtimes that read from the repo without running apm install first. Suggest either adding .github/ + apm.lock.yaml to the commit command or explicitly calling out why this tutorial is intentionally source-only and what readers should do in real repos.
| The deploy step can also augment files for runtime-specific concerns (e.g. | ||
| adding diagnostic guidance for a particular target), so treat `.github/` | ||
| as build output: never edit it by hand, always re-deploy from `.apm/`. |
There was a problem hiding this comment.
The statement that deploy "can also augment files" with an example of "adding diagnostic guidance" looks speculative; the concrete behavior in the CLI is mainly format/target-specific transformations (e.g., instructions to Claude/Cursor rule formats, prompts to commands) and otherwise byte-for-byte copies for agents/skills. Suggest replacing the example with a behavior that is definitely implemented, or removing the parenthetical example to avoid implying a feature that may not exist.
| The deploy step can also augment files for runtime-specific concerns (e.g. | |
| adding diagnostic guidance for a particular target), so treat `.github/` | |
| as build output: never edit it by hand, always re-deploy from `.apm/`. | |
| For some targets, APM generates runtime-specific formats from the source, so | |
| treat `.github/` as build output: never edit it by hand, always re-deploy | |
| from `.apm/`. |
* chore: prepare v0.9.2 release Bumps version to 0.9.2 and finalizes CHANGELOG with one-line summaries for each PR merged since 0.9.1. Highlights: - ADO AAD bearer-token auth (#856) - Governance Guide + enterprise docs IA refactor (#851, #858) - Merge Gate orchestrator + single-authority aggregation (#865, #867) - Landing + first-package docs rewrite (#855, #866) - gh-aw imports migration (#864) - Custom-port surfacing fix (#804) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * ci: simplify merge-gate to single pull_request trigger The dual-trigger pattern (pull_request + pull_request_target with concurrency cancel-in-progress) shipped in #865 was over-engineered. It produced TWO 'gate' check-runs per SHA -- one SUCCESS, one CANCELLED -- and branch protection's status-check rollup treats CANCELLED as failure, so PRs were silently BLOCKED unless an admin overrode (which masked the bug on #867). GitHub Actions has no primitive for 'either of these events succeeded'. World-class OSS projects (kubernetes, rust, deno, next.js) accept this and use a single trigger. The cost: a dropped 'pull_request' webhook (rare; observed once on PR #856) requires manual recovery. Recovery paths now documented at top of file: - push empty commit - gh workflow run merge-gate.yml -f pr_number=NNN - close + reopen PR Replaces the dual-trigger + bootstrap-fetch dance with a clean two-job flow: resolve-sha (handles workflow_dispatch input or PR head) then gate (sparse checkout + run script). Same script, same exit codes, same EXPECTED_CHECKS env. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * ci: collapse merge-gate into a single job (one check-run in PR UI) The two-job split (resolve-sha + gate) created two visible check-runs. Inlining the SHA resolution as a step within the gate job leaves only one check-run -- 'Merge Gate / gate' -- on the PR. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Summary
Rewrites
getting-started/first-package.mdto be skills-first, agent-second, plugin-aware -- matching how APM is actually used today. Also fixes a hallucinated example in the recently-merged anatomy page (#864).Why
The previous tutorial:
cat <<EOFheredocs for every code blockapm compileas a Codex/Gemini fallback stepapm pack --format plugin-- leaving plugin-skeptical readers unconvincedThe anatomy page referenced a
writing-skills/SKILL.mdthat does not exist in this repo.Changes
first-package.md(full rewrite)New 7-section structure:
apm init -y+ editapm.ymltogether (no deferral)pr-descriptionskill with the path-header code-block pattern, callout linking to the realpython-architectureskill in this repoteam-reviewer.agent.md, callout linking to the realdoc-writer.agent.mdapm install(no args), side-by-side ASCII tree of.apm/source vs.github/deployed, honest one-paragraph clarification ofapm installvsapm compile(different concerns, not nested)microsoft/apm-sample-package@v1.0.0as a real working exampleapm pack --format pluginwith verified output tree, plus theapm init --pluginscaffold path. Frames APM packages as plugin source, fending off plugin-skeptic readers without disparaging plugins.Decisions:
anatomy-of-an-apm-package.md(surgical fix)writing-skills/SKILL.mdreference with the realpython-architecture/SKILL.mdpython-architecture/SKILL.mdanddoc-writer.agent.mdso readers can click throughVerification
Every command, path, and output snippet was verified end-to-end against the CLI:
apm init -y team-skills-> creates onlyapm.yml(matches docs)apm install-> deploys to.github/skills/and.github/agents/with the exact output strings shownapm pack --format plugin-> outputs tobuild/team-skills-1.0.0/withplugin.json+agents/+skills/(matches the documented tree)apm init --plugin-> createsapm.yml+plugin.json(matches the optional scaffold tip)apm installdoes NOT invokeAgentsCompiler(verified by grep) -- the docs no longer claim it doesmicrosoft/apm-sample-package#v1.0.0tag existsdocs && npm run buildpasses with "All internal links are valid"Risk
Docs-only. No code changes. No behavioral impact.
Related
shared/apm.mdintegration narrative also from docs(gh-aw): replace deprecated dependencies: with shared/apm.md import #864