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