docs: narrative redesign for accuracy and cohesion#258
Conversation
Sweep compile messaging to reflect that apm install is the primary command for Copilot and Claude (which read deployed primitives natively), while apm compile is only needed for Cursor, Codex, Gemini, and other tools without native APM integration. Pages updated: - why-apm: qualify compile as bridge feature, not core - how-it-works: clarify native vs compiled tool support - first-package: mark compile step as optional - ci-cd: comment out compile in CI examples, add opt-in notes - ide-tool-integration: reframe compile sections as optional - github-rulesets: qualify compile CI steps - teams: clarify compile role in mid-size team workflows - adoption-playbook: comment out compile in CI phase Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- Rewrite quick-start as 3-minute install-focused flow (no compile step) - Rewrite installation page from 527 to 119 lines (install-only) - Reconceptualize migration page as lightweight adoption guide - Create agent-workflows.md consolidating apm run/runtime (experimental) - Rewrite gh-aw integration with real frontmatter dependencies syntax - Reposition apm compile as optional bridge for non-Copilot/Claude tools - Fix tools support claims: Full (Copilot/Claude) vs Instructions-only - Add pack/unpack to lifecycle, fix governance/making-the-case commands - Clean up apm run/runtime references across 6 pages - Remove emojis from all documentation pages - Refactor prompts guide to focus on primitive, not execution - Sweep compile messaging across enterprise/CI/integration pages - Update sidebar: rename Migration to Existing Projects, add Agent Workflows - Fix landing CTA to point to quick-start Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
There was a problem hiding this comment.
Pull request overview
Holistic rewrite of the Starlight documentation narrative to improve accuracy and cohesion around APM’s core value (apm install), reposition apm compile as an optional bridge for non-native tools, and consolidate experimental workflow/runtime content into a dedicated guide.
Changes:
- Reframes “install-first” across intro, getting-started, integrations, and enterprise pages; marks
apm run/apm runtimeas experimental and centralizes details in a new “Agent Workflows” guide. - Updates tool compatibility messaging/tables and refreshes examples (gh-aw integration, CI/rulesets guidance, lifecycle mentions of pack/unpack).
- Simplifies and de-duplicates content (shorter Installation + Quick Start; reduced scattered
apm runreferences; emoji removal in docs).
Reviewed changes
Copilot reviewed 26 out of 26 changed files in this pull request and generated 9 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/src/content/docs/reference/examples.md | Adds a note pointing apm run examples to the experimental Agent Workflows guide. |
| docs/src/content/docs/reference/cli-commands.md | Marks apm run / apm runtime sections as experimental and links to Agent Workflows. |
| docs/src/content/docs/introduction/why-apm.md | Repositions apm compile as an optional bridge for non-native tools; adjusts examples and principles accordingly. |
| docs/src/content/docs/introduction/what-is-apm.md | Adds pack/unpack narrative and replaces the tool support table with install-vs-compile semantics. |
| docs/src/content/docs/introduction/key-concepts.md | Removes emoji headings; updates examples to emphasize install/compile over run. |
| docs/src/content/docs/introduction/how-it-works.md | Removes emojis and rewrites compatibility narrative (native primitives vs compiled instruction files). |
| docs/src/content/docs/integrations/runtime-compatibility.md | Adds a note clarifying runtime management is experimental and linking to Agent Workflows. |
| docs/src/content/docs/integrations/ide-tool-integration.md | Updates Spec-kit/IDE guidance to an install-first flow and routes workflow execution to Agent Workflows. |
| docs/src/content/docs/integrations/github-rulesets.md | Adjusts CI snippets to make compile optional and clarifies when to split checks. |
| docs/src/content/docs/integrations/gh-aw.md | Rewrites gh-aw integration around real dependencies: frontmatter support + bundle approach + isolated mode. |
| docs/src/content/docs/integrations/ci-cd.md | Makes compile optional and simplifies CI guidance to install-first. |
| docs/src/content/docs/index.mdx | Updates landing CTA to point to Quick Start instead of Installation. |
| docs/src/content/docs/guides/prompts.md | Refocuses prompts guide on .prompt.md as a deployable primitive and routes execution to Agent Workflows. |
| docs/src/content/docs/guides/dependencies.md | Removes a stray apm run example reference from dependency workflow section. |
| docs/src/content/docs/guides/compilation.md | Clarifies compilation is optional; removes emojis from sample output; updates compatibility framing. |
| docs/src/content/docs/guides/agent-workflows.md | New guide consolidating apm run / apm runtime usage as an experimental feature area. |
| docs/src/content/docs/getting-started/quick-start.md | Rewrites Quick Start into a shorter install-first flow (no compile step for Copilot/Claude). |
| docs/src/content/docs/getting-started/migration.md | Reconceptualizes migration as an “Existing Projects” adoption guide (additive, minimal steps). |
| docs/src/content/docs/getting-started/installation.md | Significantly shortens installation page to install-only plus basic troubleshooting and contributor setup. |
| docs/src/content/docs/getting-started/first-package.md | Makes compile step explicitly optional for non-native tools. |
| docs/src/content/docs/getting-started/authentication.md | Reframes Copilot token as runtime/Agent Workflows-related rather than core install. |
| docs/src/content/docs/enterprise/teams.md | Updates enterprise narrative to distinguish install-native vs compile-bridge behavior. |
| docs/src/content/docs/enterprise/making-the-case.md | Removes/updates references to non-existent CI flags; reframes audit as planned. |
| docs/src/content/docs/enterprise/governance.md | Adds “planned feature” callouts for audit commands and clarifies current enforcement reality. |
| docs/src/content/docs/enterprise/adoption-playbook.md | Makes compilation optional in CI phase guidance while keeping the audit step referenced. |
| docs/astro.config.mjs | Renames “Migrating Projects” to “Existing Projects” and adds the new Agent Workflows page to the sidebar. |
Comments suppressed due to low confidence (1)
docs/src/content/docs/enterprise/adoption-playbook.md:129
- The CI example still includes
apm audit --ci, but the CLI currently doesn’t implement anauditcommand. Consider adding a “planned feature” note here or commenting out the audit step (similar to how compile is handled) so the playbook remains runnable today.
- name: Audit for drift
run: apm audit --ci
</details>
| commands: | | ||
| apm install | ||
| apm audit --ci | ||
| apm compile | ||
| git diff --exit-code AGENTS.md || \ | ||
| (echo "Compiled output is out of date. Run 'apm compile' locally." && exit 1) | ||
| # Optional: only needed if targeting Cursor, Codex, Gemini, or similar | ||
| # apm compile | ||
| # git diff --exit-code AGENTS.md || \ |
There was a problem hiding this comment.
This page uses apm audit --ci in the GitHub Actions example, but the current CLI doesn’t include an audit command. Add a “planned feature” note (like in the Governance docs) or replace the snippet with the current recommended drift-check approach so teams don’t copy/paste a failing workflow.
| apm-sample-package/ | ||
| design-standards.instructions.md | ||
| prompts/ | ||
| apm-sample-package/ | ||
| accessibility-audit.prompt.md | ||
| design-review.prompt.md | ||
| .claude/ | ||
| commands/ | ||
| apm-sample-package/ | ||
| ... |
There was a problem hiding this comment.
This tree layout doesn’t match how apm install currently deploys primitives. APM copies instructions/prompts/commands directly into .github/instructions/, .github/prompts/, and .claude/commands/ (no per-package subdirectory), so the shown apm-sample-package/ subfolders are inaccurate. Update the example to reflect the real on-disk paths so new users can find the deployed files.
| apm-sample-package/ | |
| design-standards.instructions.md | |
| prompts/ | |
| apm-sample-package/ | |
| accessibility-audit.prompt.md | |
| design-review.prompt.md | |
| .claude/ | |
| commands/ | |
| apm-sample-package/ | |
| ... | |
| design-standards.instructions.md | |
| prompts/ | |
| accessibility-audit.prompt.md | |
| design-review.prompt.md | |
| .claude/ | |
| commands/ | |
| ... |
| --- | ||
|
|
||
| :::caution[Experimental Feature] | ||
| APM's core value is dependency management — `apm install`, `apm.lock`, `apm audit`. The workflow execution features described on this page are experimental and may change. For most users, `apm install` is all you need. |
There was a problem hiding this comment.
The caution callout lists apm audit as part of APM’s current “core value”, but the CLI does not currently implement an audit command. Consider removing it here or labeling it as planned (consistent with the Governance docs) to avoid implying it’s available today.
| APM's core value is dependency management — `apm install`, `apm.lock`, `apm audit`. The workflow execution features described on this page are experimental and may change. For most users, `apm install` is all you need. | |
| APM's core value is dependency management — `apm install`, `apm.lock`, and (planned) `apm audit`. The workflow execution features described on this page are experimental and may change. For most users, `apm install` is all you need. |
| ```bash | ||
| git clone https://github.com/microsoft/apm.git | ||
| cd apm | ||
|
|
||
| # Install uv (if not already installed) | ||
| # Install uv if not already installed | ||
| curl -LsSf https://astral.sh/uv/install.sh | sh | ||
|
|
||
| # Create virtual environment and install in development mode | ||
| # Create environment and install in development mode | ||
| uv venv | ||
| uv pip install -e ".[dev]" | ||
|
|
||
| # Activate the environment for development | ||
| source .venv/bin/activate # On macOS/Linux | ||
| # .venv\Scripts\activate # On Windows | ||
| source .venv/bin/activate |
There was a problem hiding this comment.
The “from source” setup here uses uv venv + uv pip install -e, but the rest of the repo’s contributor docs standardize on uv sync --extra dev and uv run ... (which also creates the venv automatically). Align this page with the established workflow to avoid conflicting setup instructions.
| @@ -233,14 +235,14 @@ apm compile | |||
| apm compile --verbose | |||
|
|
|||
| # Example detailed output: | |||
| 🔬 Mathematical Analysis: | |||
| ├─ Distribution Scores: | |||
| │ ├─ **/*.py: 0.23 → Single-Point Strategy | |||
| │ ├─ **/*.tsx: 0.67 → Selective Multi Strategy | |||
| │ └─ **/*.md: 0.81 → Distributed Strategy | |||
| ├─ Coverage Verification: ✓ Complete (100%) | |||
| ├─ Constraint Satisfaction: All 8 constraints satisfied | |||
| └─ Generation Time: 127ms | |||
| Mathematical Analysis: | |||
| |- Distribution Scores: | |||
| | |- **/*.py: 0.23 -> Single-Point Strategy | |||
| | |- **/*.tsx: 0.67 -> Selective Multi Strategy | |||
| | +- **/*.md: 0.81 -> Distributed Strategy | |||
| |- Coverage Verification: Complete (100%) | |||
| |- Constraint Satisfaction: All 8 constraints satisfied | |||
| +- Generation Time: 127ms | |||
There was a problem hiding this comment.
The example apm compile --verbose output shown here doesn’t match the current CLI formatter output (different headings and structure; verbose mode uses a “Mathematical Optimization Analysis” section and rich tables/tree formatting). Either update the sample to mirror actual output or label it as simplified/pseudocode so readers don’t expect these exact lines.
| ## Next steps | ||
|
|
||
| - [Compilation guide](../../guides/compilation/) — understand how `apm compile` assembles output | ||
| - [Quick start](../quickstart/) — first-time setup walkthrough |
There was a problem hiding this comment.
The “Quick start” link target looks incorrect: ../quickstart/ doesn’t match the actual page slug (getting-started/quick-start). This will 404 in the Starlight site; update it to the correct relative path (e.g. ../quick-start/).
| - [Quick start](../quickstart/) — first-time setup walkthrough | |
| - [Quick start](../quick-start/) — first-time setup walkthrough |
| ```bash | ||
| # 1. Set up APM contextual foundation | ||
| apm init my-project && apm compile | ||
| apm init my-project && apm install |
There was a problem hiding this comment.
This workflow snippet is misleading in a shell: apm init my-project creates the directory but cannot change the parent shell’s working directory. apm init my-project && apm install will run apm install in the current directory, not in my-project; add cd my-project (or show the two commands separately).
| apm init my-project && apm install | |
| apm init my-project | |
| cd my-project | |
| apm install |
| 1. **Prompts** (`.prompt.md` files) contain AI instructions with parameter placeholders | ||
| 2. **Packages** bundle prompts for sharing via `apm publish` and `apm install` | ||
| 3. **Deployment** places prompts into well-known directories (e.g., `.github/prompts/`) where tools like GitHub Copilot can discover and use them | ||
| 4. **Compilation** resolves parameter placeholders, cross-file references, and link transforms at install time |
There was a problem hiding this comment.
This section references apm publish, but there is no publish command in the current CLI, so this is misleading. Also, apm install deploys .prompt.md files verbatim (with link resolution) — parameter substitution happens when running/previewing workflows (e.g., apm run / apm preview), not “at install time”.
| Define scripts in your `apm.yml` to map names to prompt files and runtimes: | ||
|
|
||
| ```yaml | ||
| scripts: | ||
| start: | ||
| description: "Default workflow" | ||
| prompt: .apm/prompts/start.prompt.md | ||
| runtime: copilot | ||
| review: | ||
| description: "Code review" | ||
| prompt: .apm/prompts/review.prompt.md | ||
| runtime: copilot | ||
| analyze: | ||
| description: "Log analysis" | ||
| prompt: .apm/prompts/analyze-logs.prompt.md | ||
| runtime: llm | ||
| ``` |
There was a problem hiding this comment.
The “explicit scripts” example uses a structured object form (description, prompt, runtime), but apm.yml scripts are currently parsed as a simple name: "<command string>" mapping. As written, this config won’t run with apm run; either change the example to the supported string format or clearly mark the structured form as future/planned.
Documentation Narrative Redesign
Holistic redesign of the APM documentation site to fix positioning, accuracy, and cohesiveness issues identified after the initial Starlight migration (PR #243).
Accuracy fixes
apm compilerepositioned as optional bridge across all pages — not a required step for Copilot/Claude usersapm audit --cimarked as Planned with callouts,apm install --checkreplacedapm migrate/apm importcommands)dependencies:frontmatter syntax from gh-aw docsapm pack/apm unpackContent consolidation
guides/agent-workflows.mdconsolidating allapm run/apm runtimecontent into one experimental pageapm runreferences from 6 scattered pages (authentication, IDE integration, dependencies, examples, CLI commands, runtime compatibility).prompt.mdprimitive format, not executionUX improvements
/quick-start/instead of/installation/Stats
Session artifact
A
gh-aw-advisory.mdwith cross-linking and documentation suggestions for the gh-aw team was created as a session artifact (not committed).