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

@@ -16,7 +16,7 @@ Use markdown files in `.memory/` as the persistent project memory across session
**Workflow: read files → work → update files**
1. **Session start:** Read `.memory/` directory contents and skim `.memory/knowledge.md`. Also check for cross-tool instruction files (`CLAUDE.md`, `.github/copilot-instructions.md`, `.cursorrules`) — they may contain project knowledge added by other tools.
1. **Session start:** Read `.memory/` directory contents and skim `.memory/knowledge.md`.
2. **Before each task:** Read relevant `.memory/*.md` files before reading source files for project understanding.
3. **After each task:** Update the appropriate `.memory/*.md` files with what was built.
@@ -34,18 +34,39 @@ Be specific in summaries: include parameter names, defaults, file locations, and
## Cross-Tool Instruction Files
- Maintain tool-specific instruction files so multiple agentic coding tools share the same project working context.
- Required instruction files:
- `AGENTS.md` (OpenCode)
- `CLAUDE.md` (Claude Code)
- `.github/copilot-instructions.md` (GitHub Copilot)
- `.cursorrules` (Cursor)
- These files should contain the same core project knowledge: purpose, stack, conventions, commands, and structure.
- `.memory/knowledge.md` is the source of truth; instruction files are derived views for tool consumption.
- When project knowledge changes significantly, update **all** cross-tool instruction files.
- When initializing or bootstrapping a project, create **all** cross-tool instruction files.
- Do not duplicate `.memory/` internals in these files; they describe how to work with the project, not project tracking state.
- **Read existing instruction files** at session start or when joining a new project. Other tools/people may have added project knowledge to `CLAUDE.md` or `.cursorrules` that isn't yet in `.memory/`. Merge any new knowledge into `.memory/knowledge.md` as the canonical source.
Use symlinks to share ONE instruction file across all agentic coding tools:
```text
project/
├── .github/
└── copilot-instructions.md # Real file (edit this one)
├── AGENTS.md -> .github/copilot-instructions.md
├── CLAUDE.md -> .github/copilot-instructions.md
└── .cursorrules -> .github/copilot-instructions.md
```
**Rules:**
- Edit `.github/copilot-instructions.md` — changes propagate automatically via symlinks
- Never edit symlinked files directly (changes would be lost)
- Symlinks are committed to git (git tracks them natively)
**Content of the instruction file:**
- Project overview and purpose
- Tech stack and architecture
- Coding conventions and patterns
- Build/test/lint commands
- Project structure overview
**Do NOT duplicate `.memory/` contents** — instruction files describe how to work with the project, not active plans, research, or decisions.
**When initializing a project:**
1. Create `.github/copilot-instructions.md` with project basics
2. Create symlinks: `ln -s .github/copilot-instructions.md AGENTS.md` (etc.)
3. Commit the real file and symlinks to git
**When joining an existing project:**
- Read `.github/copilot-instructions.md` (or any of the symlinked files) to understand the project
- If instruction file is missing, create it and the symlinks
## Session Continuity