instructions-sync-discipline

name	instructions-sync-discipline
description	Use when: creating, editing, reviewing, or deleting any agent customization file — SKILL.md, .instructions.md, .prompt.md, .agent.md, copilot-instructions.md, AGENTS.md, CLAUDE.md, or anything under .github/instructions/, .github/skills/, .agents/skills/, .claude/skills/. Always edit the source under docs/ and run the sync script; never hand-edit the generated targets.

Instructions / Skills Sync Discipline

This repository has a single source of truth for every agent customization file and a generator that fans it out to the locations Copilot, Codex, Claude Code, and other agents read. Hand-editing the generated targets causes silent drift between agents.

Source of Truth

What	Source path
Per-area instruction rules	docs/instructions/<name>.instructions.md
Skills	docs/skills/<dir>/SKILL.md
Sync manifest	docs/instructions/sync-manifest.json
Generator	scripts/dev/sync-agent-instructions.mjs

Generated targets — do not hand-edit:

• .github/instructions/*.instructions.md
• .github/skills/<dir>/SKILL.md
• .agents/skills/<dir>/SKILL.md
• .claude/skills/<dir>/SKILL.md
• .github/copilot-instructions.md
• AGENTS.md
• CLAUDE.md

Each generated file carries this banner at the top so reviewers can spot mistakes:

<!-- Generated by scripts/dev/sync-agent-instructions.mjs. -->
<!-- Source: <docs/...> -->
<!-- DO NOT EDIT this generated target. Edit the source file instead. -->

Required Procedure

When adding or modifying instructions / skills:

1. Edit only the source under docs/instructions/ or docs/skills/.

2. If you added a new file, register it in docs/instructions/sync-manifest.json:

   • New instruction → push to sources with { "file": "<name>.instructions.md", "summary": "..." }.
   • New skill → push to skills with { "dir": "<dir>", "summary": "..." }.

3. Run the sync (writes targets and stages them):

   pnpm run sync:instructions
   # or, when invoking inside a hook / pre-commit pipeline:
   node scripts/dev/sync-agent-instructions.mjs --stage
   

4. Verify nothing else changed unexpectedly:

   node scripts/dev/sync-agent-instructions.mjs --check
   

   Exit 0 = in sync. Exit 1 = drift; re-run without --check.

5. Commit the source file and the regenerated targets together. Never split them across commits.

Forbidden Actions

• Editing any file under .github/instructions/, .github/skills/, .agents/skills/, or .claude/skills/ directly.
• Hand-writing .github/copilot-instructions.md, AGENTS.md, or CLAUDE.md.
• Adding a new skill folder under .github/skills/, .agents/skills/, or .claude/skills/ without a corresponding docs/skills/<dir>/SKILL.md source.
• Skipping sync-manifest.json after adding a new source file (the file will exist in docs/ but never reach the agents).
• Disabling the pre-commit --check invocation to push uncommitted drift.

Why

• Copilot reads .github/. Codex reads AGENTS.md and .agents/. Claude Code reads CLAUDE.md and .claude/. Without a generator they drift, and each agent will be told different rules.
• The --check mode runs in pre-commit (via agentils-quality-gate precommit) so CI / commits fail fast on drift.
• The banner + manifest make it trivial for reviewers to confirm a PR did not bypass the generator.

Quick Reference

docs/instructions/foo.instructions.md   ──┐
docs/skills/bar/SKILL.md                  ├── edit here
docs/instructions/sync-manifest.json    ──┘
                |
                v   pnpm run sync:instructions
                |
.github/instructions/foo.instructions.md
.github/skills/bar/SKILL.md
.agents/skills/bar/SKILL.md
.claude/skills/bar/SKILL.md
.github/copilot-instructions.md
AGENTS.md                                 <-- generated, never hand-edit
CLAUDE.md                                 <-- generated, never hand-edit