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:
@@ -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.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user