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

@@ -45,10 +45,10 @@ Delegate to the `coder` subagent with explicit mode (`new_project` or `existing_
- Required scaffold targets:
- `README.md` — title, purpose, tech stack, quick-start, project structure overview
- `AGENTS.md` — project-specific workflow notes (code style, test commands, linting, build commands, commit conventions); do **not** duplicate global `AGENTS.md` policies — only add project-specific details
- `CLAUDE.md`project instructions for Claude Code (same core content as `AGENTS.md`, adapted for Claude)
- `.github/copilot-instructions.md` — project instructions for GitHub Copilot
- `.cursorrules`project instructions for Cursor
- `.github/copilot-instructions.md` — real instruction file containing shared project guidance
- `AGENTS.md`symlink to `.github/copilot-instructions.md`
- `CLAUDE.md` — symlink to `.github/copilot-instructions.md`
- `.cursorrules`symlink to `.github/copilot-instructions.md`
- `docs/architecture.md` — stub with title + purpose
- `.gitignore` — add stack-appropriate ignores (e.g., `node_modules/`, `__pycache__/`, `target/`)
- `.memory/` — create and/or update `knowledge.md`, `decisions.md`, `plans/`, `research/`
@@ -59,11 +59,15 @@ Delegate to the `coder` subagent with explicit mode (`new_project` or `existing_
- create or fill in only missing pieces
- **do not overwrite existing files**
- explicitly instruct coder to check existence before creating each target
- if any cross-tool instruction files are missing (`AGENTS.md`, `CLAUDE.md`, `.github/copilot-instructions.md`, `.cursorrules`), create them
- if they exist, verify they are in sync with `AGENTS.md` for core project knowledge (purpose, stack, conventions, commands, structure)
- ensure `.github/copilot-instructions.md` exists as the real instruction file
- create missing symlinks:
- `ln -s .github/copilot-instructions.md AGENTS.md`
- `ln -s .github/copilot-instructions.md CLAUDE.md`
- `ln -s .github/copilot-instructions.md .cursorrules`
- if `.github/copilot-instructions.md` is missing but `AGENTS.md` exists as a real file, move AGENTS content into `.github/copilot-instructions.md`, then recreate `AGENTS.md` as a symlink
- if `.memory/` is missing, create the full `.memory/` directory structure
- examples:
- if `README.md` exists and `AGENTS.md` is missing, create only `AGENTS.md`
- if `README.md` exists and only `AGENTS.md` is missing, create `AGENTS.md` as a symlink to `.github/copilot-instructions.md`
- if `docs/` is missing, create it and add `docs/architecture.md`
## Step 4 — Documentation review (delegate to `librarian`)
@@ -71,8 +75,8 @@ Delegate to the `coder` subagent with explicit mode (`new_project` or `existing_
Always delegate to the `librarian` subagent, for both new and existing projects.
- Ensure `README.md` is accurate and complete for the current project state.
- Ensure `AGENTS.md` captures project-specific workflow decisions from Step 2.
- Verify cross-tool instruction files are consistent with each other (`AGENTS.md`, `CLAUDE.md`, `.github/copilot-instructions.md`, `.cursorrules`).
- Ensure `.github/copilot-instructions.md` exists and captures project-specific workflow decisions from Step 2.
- Verify `AGENTS.md`, `CLAUDE.md`, and `.cursorrules` are symlinks to `.github/copilot-instructions.md`.
- Ensure stubs are explicitly marked for later completion.
- Keep edits additive and non-destructive for existing projects.