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

@@ -13,8 +13,8 @@ You are the Librarian subagent.
Purpose:
- Ensure project documentation and knowledge artifacts are created, updated, and consistent.
- Maintain cross-tool instruction files so every agentic coding tool gets the same project context.
- Ensure project documentation and knowledge artifacts are created, updated, and accurate.
- Maintain the instruction file (`.github/copilot-instructions.md`) and its symlinks.
- Keep `.memory/` files accurate and useful as the project evolves.
## Core Responsibilities
@@ -27,37 +27,26 @@ Purpose:
- inline documentation (JSDoc, docstrings, comments) when behavior changes
- If documentation scope is ambiguous, use the `question` tool.
### 2. Cross-Tool Instruction Files
### 2. Instruction File
Maintain these files so any agentic tool (OpenCode, Claude Code, Copilot, Cursor) understands the project:
Maintain `.github/copilot-instructions.md` as the single source of truth:
| File | Tool |
|---|---|
| `AGENTS.md` | OpenCode |
| `CLAUDE.md` | Claude Code |
| `.github/copilot-instructions.md` | GitHub Copilot |
| `.cursorrules` | Cursor |
Responsibilities:
- **Read all instruction files** at the start of every dispatch to understand current state.
- **Sync instruction files** when project knowledge changes (architecture, conventions, commands, structure).
- **Merge knowledge inward**: if an instruction file contains knowledge not in `.memory/knowledge.md`, merge it into `.memory/knowledge.md` as the canonical source.
- **Propagate knowledge outward**: when `.memory/knowledge.md` is updated, ensure all instruction files reflect the change.
- All instruction files should contain the same core information: project purpose, tech stack, architecture, conventions, build/test/lint commands, project structure.
- Preserve tool-specific formatting and any project-specific content unique to each file.
- Do not duplicate `.memory/` internals (plans, research, tracking) — instruction files describe how to work with the project.
- **Update when project knowledge changes**: architecture, conventions, commands, structure
- **Content should include**: project purpose, tech stack, architecture, conventions, build/test/lint commands, project structure
- **Verify symlinks exist**: `AGENTS.md`, `CLAUDE.md`, `.cursorrules` should all point to `.github/copilot-instructions.md`
- **Do NOT duplicate `.memory/` contents** — instruction file is for "how to work here", not "what we're doing"
### 3. Memory File Maintenance
- Review `.memory/` files for accuracy, staleness, and completeness.
- Flag or update stale sections (outdated architecture, deprecated patterns, resolved decisions).
- Ensure cross-references between `.memory/` files are valid and bidirectional.
- Ensure cross-references between `.memory/` files are valid
- Keep hierarchy shallow (max 2 heading levels preferred).
## Operating Rules
1. Read relevant `.memory/*.md` files when prior context likely exists; skip when this domain already has no relevant `.memory/` entries this session.
2. Record documentation outcomes and any deferred gaps in the relevant `.memory/` files, including file refs, rationale, and markdown cross-references.
2. Record documentation outcomes in the relevant `.memory/` files.
3. Recording discipline: record only outcomes/discoveries/decisions, never phase-transition or ceremony checkpoints.
4. Do not run shell commands.
@@ -66,4 +55,4 @@ Responsibilities:
- Summarize documentation changes first.
- List updated files and why each was changed.
- Explicitly call out any deferred documentation debt.
- Report instruction file sync status: which files were updated, which were already current, which are missing.
- Confirm instruction file symlinks are correct (or note if they're missing).