feat: adopt symlink approach for cross-tool instruction files

Replace 4 separate instruction files with 1 real file + symlinks:
- .github/copilot-instructions.md is the canonical instruction file
- CLAUDE.md and .cursorrules are symlinks to it
- AGENTS.md stays as global config (not a project instruction file)

This eliminates all sync/merge logic - changes propagate automatically.

Changes:
- AGENTS.md: rewrite Cross-Tool Instruction Files section for symlink convention
- librarian.md: simplify to maintain single instruction file + verify symlinks
- lead.md: simplify PHASE-WRAP and Documentation Completion Gate
- commands (init, bootstrap-memory, save-memory): update for symlink model
- doc-coverage skill: verify symlinks exist and point correctly
This commit is contained in:
2026-03-08 23:48:42 +00:00
parent 9830f6f01c
commit e9074646b7
12 changed files with 121 additions and 195 deletions

View File

@@ -14,3 +14,19 @@
**Risk:** Agents could theoretically edit non-memory files since the config-level permission is `allow`. Mitigation is instruction-level enforcement, which is effective but not mechanical.
See [Plan: Agent Memory Write Access](plans/agent-memory-write-access.md) | See [Knowledge: Permission Model](knowledge.md#permission-model)
## Cross-Tool Instruction File Symlink Strategy
**Decision:** Use `.github/copilot-instructions.md` as the single source-of-truth instruction file and represent `AGENTS.md`, `CLAUDE.md`, and `.cursorrules` as symlinks to it.
**Rationale:** The previous multi-file sync model required manual propagation/merge logic and could drift. Symlinks remove synchronization overhead and guarantee tool-level consistency by construction.
**Implementation:**
- Updated `AGENTS.md` “Cross-Tool Instruction Files” guidance to document the symlink pattern and initialization/joining workflow.
- Removed session-start instruction in `AGENTS.md` that required reading additional tool-specific instruction files for merge reconciliation.
- Updated `agents/librarian.md` responsibilities from multi-file sync/merge to maintaining `.github/copilot-instructions.md` plus symlink verification.
- Updated `agents/lead.md` PHASE-WRAP and Documentation Completion Gate to reference `.github/copilot-instructions.md` instead of syncing four files.
**Affected files:** `AGENTS.md`, `agents/librarian.md`, `agents/lead.md`, `.memory/knowledge.md`.
See [Knowledge: Project Overview](knowledge.md#project-overview)