From 038250ec83d27fa7734832f04f235aa693c910f7 Mon Sep 17 00:00:00 2001 From: danielmeppiel Date: Tue, 2 Jun 2026 14:25:16 +0200 Subject: [PATCH 1/3] docs(compile): document target: to pin the committed generated set (#1342) Adds a 'Pinning the committed generated set' section to the apm compile reference page explaining that omitting target: in apm.yml causes the committed generated files to silently track whoever last ran apm compile. The recommended fix -- set target: [claude, cursor] (or whichever agents the team uses) -- is now documented with a concrete example. Also adds a 'Deterministic committed output' callout to the manifest-schema target: section (3.6) with a cross-link to the new compile section. No source code changes. Maintainer-endorsed docs-only resolution of #1342. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../src/content/docs/reference/cli/compile.md | 30 +++++++++++++++++++ .../content/docs/reference/manifest-schema.md | 9 ++++++ 2 files changed, 39 insertions(+) diff --git a/docs/src/content/docs/reference/cli/compile.md b/docs/src/content/docs/reference/cli/compile.md index 6bf479a22..02072b215 100644 --- a/docs/src/content/docs/reference/cli/compile.md +++ b/docs/src/content/docs/reference/cli/compile.md @@ -53,6 +53,36 @@ The compiled output is scanned for hidden Unicode before any file is written. Critical findings cause the command to exit non-zero. See [Drift and secure by default](../../../consumer/drift-and-secure-by-default/). +## Pinning the committed generated set + +`apm compile` generates derived files: `AGENTS.md`, `CLAUDE.md`, +`.claude/commands/`, `.cursor/rules/`, `.github/copilot-instructions.md`, +`.agents/`, and similar. Teams that commit these files into source +control face a consistency problem: without `target:` set in `apm.yml`, +auto-detection decides which files to produce based on which tool folders +exist on the current machine. A developer with `.github/` and `.claude/` +locally produces `copilot` + `claude` output; a contributor with only +`.claude/` produces `claude` output only. The committed set silently +tracks whoever last ran `apm compile`. + +Set `target:` in `apm.yml` to declare exactly which agent formats the +project supports. Every run of `apm compile` -- local developer, CI, +cloud agent -- then writes the same files regardless of which tool +folders exist on that machine: + +```yaml +# apm.yml +target: [claude, cursor] # compile writes exactly these two sets; nothing else +``` + +This makes the committed generated files deterministic for humans, +cloud agents, and contributors who do not run `apm compile` locally +and rely on the checked-in artifacts. + +Accepted values: `copilot`, `claude`, `cursor`, `opencode`, `codex`, +`gemini`, `windsurf`, `all`. Full reference: +[manifest schema -- target](../../../reference/manifest-schema/#36-target). + ## Options ### Target selection diff --git a/docs/src/content/docs/reference/manifest-schema.md b/docs/src/content/docs/reference/manifest-schema.md index 2d5a027eb..f1ec2b6cd 100644 --- a/docs/src/content/docs/reference/manifest-schema.md +++ b/docs/src/content/docs/reference/manifest-schema.md @@ -159,6 +159,15 @@ A plural alias `targets:` (YAML list only) is also accepted and takes precedence | `all` | All targets. Cannot be combined with other values in a list. | | `minimal` | `AGENTS.md` only at project root. **Auto-detected only**: this value MUST NOT be set explicitly in manifests; it is an internal fallback when no target folder is detected. | +**Deterministic committed output.** Teams that commit the files `apm compile` +generates face a consistency problem: without `target:` set, auto-detection +decides which files to produce based on which tool folders exist on the local +machine. The committed set silently tracks whoever last ran `apm compile`. +Setting `target:` makes the output deterministic for every developer, CI +runner, and cloud agent that relies on the checked-in generated files without +running `apm compile` locally. See +[Pinning the committed generated set](./cli/compile/#pinning-the-committed-generated-set). + ### 3.7. `type` | | | From 1449db6320b3fdfc2ea6b25701eec185d316e744 Mon Sep 17 00:00:00 2001 From: danielmeppiel Date: Tue, 2 Jun 2026 14:49:42 +0200 Subject: [PATCH 2/3] docs(compile): fix auto-detect accuracy and file-list in target-pinning section - Correct the auto-detect example: two or more detected tool folders resolve to 'all' (not a copilot+claude union); single folder resolves to that one target only - Remove .claude/commands/, .cursor/rules/, .agents/ from the compile output list -- those are apm install outputs; compile writes only root context files (AGENTS.md, CLAUDE.md, GEMINI.md, .github/copilot-instructions.md) - Switch example from target: to targets: (the preferred spelling per manifest-schema 3.6 guidance) - Add cross-reference to Output layout per target table Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../src/content/docs/reference/cli/compile.md | 24 ++++++++++--------- .../content/docs/reference/manifest-schema.md | 4 ++-- 2 files changed, 15 insertions(+), 13 deletions(-) diff --git a/docs/src/content/docs/reference/cli/compile.md b/docs/src/content/docs/reference/cli/compile.md index 02072b215..b4ff99b75 100644 --- a/docs/src/content/docs/reference/cli/compile.md +++ b/docs/src/content/docs/reference/cli/compile.md @@ -55,24 +55,26 @@ written. Critical findings cause the command to exit non-zero. See ## Pinning the committed generated set -`apm compile` generates derived files: `AGENTS.md`, `CLAUDE.md`, -`.claude/commands/`, `.cursor/rules/`, `.github/copilot-instructions.md`, -`.agents/`, and similar. Teams that commit these files into source -control face a consistency problem: without `target:` set in `apm.yml`, +`apm compile` generates root context files: `AGENTS.md`, `CLAUDE.md`, +`GEMINI.md`, `.github/copilot-instructions.md` (see +[Output layout per target](#output-layout-per-target) below for the +full per-target breakdown). Teams that commit these files into source +control face a consistency problem: without `targets:` set in `apm.yml`, auto-detection decides which files to produce based on which tool folders -exist on the current machine. A developer with `.github/` and `.claude/` -locally produces `copilot` + `claude` output; a contributor with only -`.claude/` produces `claude` output only. The committed set silently -tracks whoever last ran `apm compile`. +exist on the current machine. A contributor with only `.claude/` locally +produces `claude` output only; a developer who also has `.github/` +triggers the two-or-more-folders rule and gets the full `all` expansion +-- including `GEMINI.md` and every other target. The committed set +silently tracks whoever last ran `apm compile`. -Set `target:` in `apm.yml` to declare exactly which agent formats the +Set `targets:` in `apm.yml` to declare exactly which agent formats the project supports. Every run of `apm compile` -- local developer, CI, cloud agent -- then writes the same files regardless of which tool folders exist on that machine: ```yaml # apm.yml -target: [claude, cursor] # compile writes exactly these two sets; nothing else +targets: [claude, cursor] # compile writes exactly these two sets; nothing else ``` This makes the committed generated files deterministic for humans, @@ -81,7 +83,7 @@ and rely on the checked-in artifacts. Accepted values: `copilot`, `claude`, `cursor`, `opencode`, `codex`, `gemini`, `windsurf`, `all`. Full reference: -[manifest schema -- target](../../../reference/manifest-schema/#36-target). +[manifest schema -- targets](../../../reference/manifest-schema/#36-target). ## Options diff --git a/docs/src/content/docs/reference/manifest-schema.md b/docs/src/content/docs/reference/manifest-schema.md index f1ec2b6cd..60369cac7 100644 --- a/docs/src/content/docs/reference/manifest-schema.md +++ b/docs/src/content/docs/reference/manifest-schema.md @@ -160,10 +160,10 @@ A plural alias `targets:` (YAML list only) is also accepted and takes precedence | `minimal` | `AGENTS.md` only at project root. **Auto-detected only**: this value MUST NOT be set explicitly in manifests; it is an internal fallback when no target folder is detected. | **Deterministic committed output.** Teams that commit the files `apm compile` -generates face a consistency problem: without `target:` set, auto-detection +generates face a consistency problem: without `targets:` set, auto-detection decides which files to produce based on which tool folders exist on the local machine. The committed set silently tracks whoever last ran `apm compile`. -Setting `target:` makes the output deterministic for every developer, CI +Setting `targets:` makes the output deterministic for every developer, CI runner, and cloud agent that relies on the checked-in generated files without running `apm compile` locally. See [Pinning the committed generated set](./cli/compile/#pinning-the-committed-generated-set). From 7a7aabc6d94b88fefadbd686568662b388038afe Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 2 Jun 2026 13:18:35 +0000 Subject: [PATCH 3/3] docs(compile): act on review panel deferred recommendations - Rename section heading to 'Pin committed output with targets:' for better ToC scannability - Move pinning section after Options (before Examples) to follow CLI reference scan pattern - Replace bold-text callout in manifest-schema.md with Starlight :::tip admonition for visual weight - Update link anchor in manifest-schema.md to match renamed heading - Add breadcrumb in first-package.md step 4 pointing to pinning guidance - Expand 'all' expansion description to explicitly name all root context files (GEMINI.md etc.) Co-authored-by: danielmeppiel <51440732+danielmeppiel@users.noreply.github.com> --- .../docs/getting-started/first-package.md | 3 + .../src/content/docs/reference/cli/compile.md | 65 ++++++++++--------- .../content/docs/reference/manifest-schema.md | 17 ++--- 3 files changed, 45 insertions(+), 40 deletions(-) diff --git a/docs/src/content/docs/getting-started/first-package.md b/docs/src/content/docs/getting-started/first-package.md index 1d62e8169..f92418586 100644 --- a/docs/src/content/docs/getting-started/first-package.md +++ b/docs/src/content/docs/getting-started/first-package.md @@ -225,6 +225,9 @@ in the current directory. To target explicitly, see the > plain `agents`-protocol hosts). Gemini also receives commands, skills, > hooks, and MCP via `apm install`. Copilot, Claude Code, and Cursor read > the per-skill directories directly -- no compile step needed. +> If your project commits those generated files, set `targets:` in `apm.yml` +> to keep the committed set consistent across machines. See +> [Pin committed output with targets:](/apm/reference/cli/compile/#pin-committed-output-with-targets). Now open Copilot or Claude in this project. Ask "draft a PR description for my last commit". The `pr-description` skill activates on its own. To get the diff --git a/docs/src/content/docs/reference/cli/compile.md b/docs/src/content/docs/reference/cli/compile.md index b4ff99b75..51de31abf 100644 --- a/docs/src/content/docs/reference/cli/compile.md +++ b/docs/src/content/docs/reference/cli/compile.md @@ -53,38 +53,6 @@ The compiled output is scanned for hidden Unicode before any file is written. Critical findings cause the command to exit non-zero. See [Drift and secure by default](../../../consumer/drift-and-secure-by-default/). -## Pinning the committed generated set - -`apm compile` generates root context files: `AGENTS.md`, `CLAUDE.md`, -`GEMINI.md`, `.github/copilot-instructions.md` (see -[Output layout per target](#output-layout-per-target) below for the -full per-target breakdown). Teams that commit these files into source -control face a consistency problem: without `targets:` set in `apm.yml`, -auto-detection decides which files to produce based on which tool folders -exist on the current machine. A contributor with only `.claude/` locally -produces `claude` output only; a developer who also has `.github/` -triggers the two-or-more-folders rule and gets the full `all` expansion --- including `GEMINI.md` and every other target. The committed set -silently tracks whoever last ran `apm compile`. - -Set `targets:` in `apm.yml` to declare exactly which agent formats the -project supports. Every run of `apm compile` -- local developer, CI, -cloud agent -- then writes the same files regardless of which tool -folders exist on that machine: - -```yaml -# apm.yml -targets: [claude, cursor] # compile writes exactly these two sets; nothing else -``` - -This makes the committed generated files deterministic for humans, -cloud agents, and contributors who do not run `apm compile` locally -and rely on the checked-in artifacts. - -Accepted values: `copilot`, `claude`, `cursor`, `opencode`, `codex`, -`gemini`, `windsurf`, `all`. Full reference: -[manifest schema -- targets](../../../reference/manifest-schema/#36-target). - ## Options ### Target selection @@ -129,6 +97,39 @@ use `apm install` or `apm deps update` when you want shared | `--dry-run` | Show placement decisions without writing files. | | `-v, --verbose` | Show source attribution and optimizer analysis. | +## Pin committed output with targets: + +`apm compile` generates root context files: `AGENTS.md`, `CLAUDE.md`, +`GEMINI.md`, `.github/copilot-instructions.md` (see +[Output layout per target](#output-layout-per-target) below for the +full per-target breakdown). Teams that commit these files into source +control face a consistency problem: without `targets:` set in `apm.yml`, +auto-detection decides which files to produce based on which tool folders +exist on the current machine. A contributor with only `.claude/` locally +produces `claude` output only; a developer who also has `.github/` +triggers the two-or-more-folders rule and gets the full `all` expansion +-- producing `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, +`.github/copilot-instructions.md`, and every other target. The committed +set silently tracks whoever last ran `apm compile`. + +Set `targets:` in `apm.yml` to declare exactly which agent formats the +project supports. Every run of `apm compile` -- local developer, CI, +cloud agent -- then writes the same files regardless of which tool +folders exist on that machine: + +```yaml +# apm.yml +targets: [claude, cursor] # compile writes exactly these two sets; nothing else +``` + +This makes the committed generated files deterministic for humans, +cloud agents, and contributors who do not run `apm compile` locally +and rely on the checked-in artifacts. + +Accepted values: `copilot`, `claude`, `cursor`, `opencode`, `codex`, +`gemini`, `windsurf`, `all`. Full reference: +[manifest schema -- targets](../../../reference/manifest-schema/#36-target). + ## Examples Compile for whatever the project is set up for: diff --git a/docs/src/content/docs/reference/manifest-schema.md b/docs/src/content/docs/reference/manifest-schema.md index 60369cac7..924261784 100644 --- a/docs/src/content/docs/reference/manifest-schema.md +++ b/docs/src/content/docs/reference/manifest-schema.md @@ -159,14 +159,15 @@ A plural alias `targets:` (YAML list only) is also accepted and takes precedence | `all` | All targets. Cannot be combined with other values in a list. | | `minimal` | `AGENTS.md` only at project root. **Auto-detected only**: this value MUST NOT be set explicitly in manifests; it is an internal fallback when no target folder is detected. | -**Deterministic committed output.** Teams that commit the files `apm compile` -generates face a consistency problem: without `targets:` set, auto-detection -decides which files to produce based on which tool folders exist on the local -machine. The committed set silently tracks whoever last ran `apm compile`. -Setting `targets:` makes the output deterministic for every developer, CI -runner, and cloud agent that relies on the checked-in generated files without -running `apm compile` locally. See -[Pinning the committed generated set](./cli/compile/#pinning-the-committed-generated-set). +:::tip[Deterministic committed output] +Teams that commit the files `apm compile` generates face a consistency problem: +without `targets:` set, auto-detection decides which files to produce based on +which tool folders exist on the local machine. The committed set silently tracks +whoever last ran `apm compile`. Setting `targets:` makes the output deterministic +for every developer, CI runner, and cloud agent that relies on the checked-in +generated files without running `apm compile` locally. See +[Pin committed output with targets:](./cli/compile/#pin-committed-output-with-targets). +::: ### 3.7. `type`