From 17d45dd1f29bb46c45cb049d559fa5bf731f3a63 Mon Sep 17 00:00:00 2001 From: danielmeppiel Date: Fri, 13 Mar 2026 22:28:22 +0100 Subject: [PATCH 1/3] docs: clarify that .github/ deployed files should be committed Expand the quick-start 'What to commit' section to explicitly address .github/ and .claude/ deployed files, and add a CI drift check example to the CI/CD guide. Closes #288 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../content/docs/getting-started/quick-start.md | 10 ++++++++-- docs/src/content/docs/integrations/ci-cd.md | 15 +++++++++++++++ 2 files changed, 23 insertions(+), 2 deletions(-) diff --git a/docs/src/content/docs/getting-started/quick-start.md b/docs/src/content/docs/getting-started/quick-start.md index d9f3f5de..f89f5db7 100644 --- a/docs/src/content/docs/getting-started/quick-start.md +++ b/docs/src/content/docs/getting-started/quick-start.md @@ -125,8 +125,14 @@ apm install github/awesome-copilot/skills/review-and-refactor ``` **What to commit:** -- `apm.yml` and `apm.lock.yaml` -- version-controlled, shared with the team. -- `apm_modules/` -- add to `.gitignore`. Rebuilt from the lockfile on install. +- `apm.yml` and `apm.lock.yaml` — version-controlled, shared with the team. +- `.github/` deployed files (`prompts/`, `agents/`, `instructions/`, `skills/`, `hooks/`) — commit them so every contributor (and [Copilot on github.com](https://docs.github.com/en/copilot)) gets agent context without running `apm install`. +- `.claude/` deployed files (`agents/`, `commands/`, `skills/`, `hooks/`) — same rationale, for Claude Code users. +- `apm_modules/` — add to `.gitignore`. Rebuilt from the lockfile on install. + +:::tip[Keeping deployed files in sync] +When you update `apm.yml`, re-run `apm install` and commit the changed `.github/` and `.claude/` files. A [CI drift check](../../integrations/ci-cd/#verify-deployed-primitives) catches stale files automatically. +::: :::note[Using Cursor, Codex, or Gemini?] These tools use different configuration formats. Run `apm compile` after installing to generate their native files. See the [Compilation guide](../../guides/compilation/) for details. diff --git a/docs/src/content/docs/integrations/ci-cd.md b/docs/src/content/docs/integrations/ci-cd.md index 187815cb..c5a638db 100644 --- a/docs/src/content/docs/integrations/ci-cd.md +++ b/docs/src/content/docs/integrations/ci-cd.md @@ -63,6 +63,20 @@ If your project uses `apm compile` to target tools like Cursor, Codex, or Gemini This step is not needed if your team only uses GitHub Copilot and Claude, which read deployed primitives natively. +### Verify Deployed Primitives + +To ensure `.github/` and `.claude/` integration files stay in sync with `apm.yml`, add a drift check: + +```yaml + - name: Check APM integration drift + run: | + apm install + git diff --exit-code .github/ .claude/ || \ + (echo "APM integration files are out of date. Run 'apm install' and commit." && exit 1) +``` + +This catches cases where a developer updates `apm.yml` but forgets to re-run `apm install`. + ## Azure Pipelines ```yaml @@ -153,5 +167,6 @@ See the [Pack & Distribute guide](../../guides/pack-distribute/) for the full wo - **Pin APM version** in CI to avoid unexpected changes: `pip install apm-cli==0.7.7` - **Commit `apm.lock.yaml`** so CI resolves the same dependency versions as local development +- **Commit `.github/` and `.claude/` deployed files** so contributors and cloud-based Copilot get agent context without running `apm install` - **If using `apm compile`** (for Cursor, Codex, Gemini), run it in CI and fail the build if the output differs from what's committed - **Use `GITHUB_APM_PAT`** for private dependencies; never use the default `GITHUB_TOKEN` for cross-repo access From c52fbba2f21b8495540d7f69df6af6ab26cd33f0 Mon Sep 17 00:00:00 2001 From: Daniel Meppiel <51440732+danielmeppiel@users.noreply.github.com> Date: Fri, 13 Mar 2026 22:33:48 +0100 Subject: [PATCH 2/3] Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- docs/src/content/docs/getting-started/quick-start.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/src/content/docs/getting-started/quick-start.md b/docs/src/content/docs/getting-started/quick-start.md index f89f5db7..29ca7eef 100644 --- a/docs/src/content/docs/getting-started/quick-start.md +++ b/docs/src/content/docs/getting-started/quick-start.md @@ -126,8 +126,8 @@ apm install github/awesome-copilot/skills/review-and-refactor **What to commit:** - `apm.yml` and `apm.lock.yaml` — version-controlled, shared with the team. -- `.github/` deployed files (`prompts/`, `agents/`, `instructions/`, `skills/`, `hooks/`) — commit them so every contributor (and [Copilot on github.com](https://docs.github.com/en/copilot)) gets agent context without running `apm install`. -- `.claude/` deployed files (`agents/`, `commands/`, `skills/`, `hooks/`) — same rationale, for Claude Code users. +- `.github/` deployed files (`prompts/`, `agents/`, `instructions/`, `skills/`, `hooks/`) — commit them so every contributor (and [Copilot on github.com](https://docs.github.com/en/copilot)) gets agent context immediately after cloning, before they run `apm install` to sync and regenerate files. +- `.claude/` deployed files (`agents/`, `commands/`, `skills/`, `hooks/`) — same rationale for Claude Code users: committed files give instant context on clone, while `apm install` remains the way to refresh them from `apm.yml`. - `apm_modules/` — add to `.gitignore`. Rebuilt from the lockfile on install. :::tip[Keeping deployed files in sync] From 97a7a771295925aff31c20cf730937cf83f6f665 Mon Sep 17 00:00:00 2001 From: danielmeppiel Date: Fri, 13 Mar 2026 22:36:04 +0100 Subject: [PATCH 3/3] fix: use git status --porcelain for CI drift checks git diff --exit-code misses new untracked files (the most common drift case when adding dependencies). git status --porcelain catches both modified and untracked files. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- docs/src/content/docs/integrations/ci-cd.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/docs/src/content/docs/integrations/ci-cd.md b/docs/src/content/docs/integrations/ci-cd.md index c5a638db..d4a6982f 100644 --- a/docs/src/content/docs/integrations/ci-cd.md +++ b/docs/src/content/docs/integrations/ci-cd.md @@ -57,8 +57,10 @@ If your project uses `apm compile` to target tools like Cursor, Codex, or Gemini - name: Check for drift run: | apm compile - git diff --exit-code AGENTS.md CLAUDE.md || \ - (echo "Compiled output is out of date. Run 'apm compile' locally." && exit 1) + if [ -n "$(git status --porcelain -- AGENTS.md CLAUDE.md)" ]; then + echo "Compiled output is out of date. Run 'apm compile' locally and commit." + exit 1 + fi ``` This step is not needed if your team only uses GitHub Copilot and Claude, which read deployed primitives natively. @@ -71,8 +73,10 @@ To ensure `.github/` and `.claude/` integration files stay in sync with `apm.yml - name: Check APM integration drift run: | apm install - git diff --exit-code .github/ .claude/ || \ - (echo "APM integration files are out of date. Run 'apm install' and commit." && exit 1) + if [ -n "$(git status --porcelain -- .github/ .claude/)" ]; then + echo "APM integration files are out of date. Run 'apm install' and commit." + exit 1 + fi ``` This catches cases where a developer updates `apm.yml` but forgets to re-run `apm install`.