Docs: Clarify whether `.github/` agent files should be committed to version control

[dsayling]

Problem

The quick-start docs state clearly what to commit after running apm install:

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.

However, it is silent on the .github/ directory — specifically the files APM deploys there during install, such as:

• .github/instructions/
• .github/prompts/
• .github/skills/
• .github/agents/
• .github/hooks/

This creates ambiguity for teams, particularly around the contributor onboarding scenario: if a contributor clones the repo and does NOT run apm install, will the agent context files already be present in .github/?

The Gap

Unlike apm_modules/, APM does not automatically add .github/ APM-managed files to .gitignore. This means:

• Teams may accidentally commit these files (treating them like source), or
• Teams may accidentally not commit them (assuming they're ephemeral like apm_modules/), leaving contributors without the necessary context until they run apm install.

Questions Needing Clarification

1. Should the files APM places in .github/ be committed to version control?

   • If yes (commit them): contributors don't need to run apm install to get agent context, but the files may drift out of sync if someone updates apm.yml without re-running apm install.
   • If no (gitignore them): the workflow is consistent with apm_modules/, but contributors must always run apm install for Copilot/Claude to pick up the configured skills/prompts/instructions.

2. Is there a recommended pattern (e.g., a CI step or pre-commit hook) to keep .github/ integration files in sync?

3. Should the docs or apm init suggest adding .github/instructions/, .github/prompts/, .github/skills/ etc. (the APM-managed subdirectories) to .gitignore, similar to how APM automatically adds apm_modules/ to .gitignore via _update_gitignore_for_apm_modules()?

Suggested Doc Fix

At minimum, the "What to commit" section in the quick-start should be expanded to address .github/ explicitly, e.g.:

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.
• .github/instructions/, .github/prompts/, .github/skills/, .github/agents/, .github/hooks/ — [commit OR gitignore — clarification needed]

[danielmeppiel]

Great issue @dsayling — this is a real gap in the docs and you're right that teams need a clear answer here.

Stance: commit them ✅

The files APM deploys to .github/ (and .claude/) should be committed to version control. Here's why:

1. Zero-friction onboarding

Clone → open IDE → Copilot/Claude has full context immediately. Contributors who don't know about APM (or haven't run apm install yet) still get the working agent setup. This is the whole point of using .github/ — it's a well-known convention for committed tool config, same as .github/workflows/, CODEOWNERS, or issue templates.

2. Cloud Copilot reads from the committed tree

When Copilot runs on github.com — PR reviews, issue triage, the coding agent — it reads .github/prompts/, .github/agents/, etc. from the repo's committed files. If these are gitignored, cloud-based Copilot loses all context entirely. This isn't a convenience thing, it's a functionality gap.

3. The right analogy isn't apm_modules/

apm_modules/ is like node_modules/ — a local cache, potentially large, fully rebuildable. The .github/ deployed files are small, deterministic, and read directly by tooling. The better analogy is go.sum or committed protobuf stubs — derived artifacts that belong in the repo.

Answering your three questions

1. Should the files APM places in .github/ be committed?

Yes. Commit .github/prompts/, .github/agents/, .github/instructions/, .github/skills/, .github/hooks/, and the equivalent .claude/ paths.

2. Is there a recommended pattern to keep .github/ integration files in sync?

CI drift check. After running apm install in CI, fail the build if the working tree is dirty:

- 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)

A pre-commit hook works too — we already document an apm audit --drift hook pattern in the governance guide.

3. Should apm init suggest adding .github/ subdirectories to .gitignore?

No. That would go against the commit stance. apm_modules/ is the only directory that should be gitignored.

---

We're updating the quick-start docs and CI/CD guide to make this explicit. Thanks for flagging it — the "What to commit" section will now cover .github/ and .claude/ alongside the manifest and lockfile.

[danielmeppiel]

Edit to the CI snippet above — git diff --exit-code only catches modifications to tracked files. In a fresh CI checkout, new files created by apm install (e.g., adding a dependency) would be untracked and silently missed. The correct check is:

- name: Check APM integration drift
  run: |
    apm install
    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 new files, modified files, and deleted files — ensuring the committed .github/ state matches what apm.yml declares. Updated in #290.