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:
@@ -14,3 +14,19 @@
|
||||
**Risk:** Agents could theoretically edit non-memory files since the config-level permission is `allow`. Mitigation is instruction-level enforcement, which is effective but not mechanical.
|
||||
|
||||
See [Plan: Agent Memory Write Access](plans/agent-memory-write-access.md) | See [Knowledge: Permission Model](knowledge.md#permission-model)
|
||||
|
||||
## Cross-Tool Instruction File Symlink Strategy
|
||||
|
||||
**Decision:** Use `.github/copilot-instructions.md` as the single source-of-truth instruction file and represent `AGENTS.md`, `CLAUDE.md`, and `.cursorrules` as symlinks to it.
|
||||
|
||||
**Rationale:** The previous multi-file sync model required manual propagation/merge logic and could drift. Symlinks remove synchronization overhead and guarantee tool-level consistency by construction.
|
||||
|
||||
**Implementation:**
|
||||
- Updated `AGENTS.md` “Cross-Tool Instruction Files” guidance to document the symlink pattern and initialization/joining workflow.
|
||||
- Removed session-start instruction in `AGENTS.md` that required reading additional tool-specific instruction files for merge reconciliation.
|
||||
- Updated `agents/librarian.md` responsibilities from multi-file sync/merge to maintaining `.github/copilot-instructions.md` plus symlink verification.
|
||||
- Updated `agents/lead.md` PHASE-WRAP and Documentation Completion Gate to reference `.github/copilot-instructions.md` instead of syncing four files.
|
||||
|
||||
**Affected files:** `AGENTS.md`, `agents/librarian.md`, `agents/lead.md`, `.memory/knowledge.md`.
|
||||
|
||||
See [Knowledge: Project Overview](knowledge.md#project-overview)
|
||||
|
||||
@@ -6,7 +6,7 @@ This is the OpenCode agentic configuration for a multi-agent coding workflow. It
|
||||
- **Config file:** `opencode.jsonc` — defines default agent, plugins, global permissions, and MCP servers.
|
||||
- **Agent definitions:** `agents/*.md` — one file per agent with YAML frontmatter (model, permissions, temperature) and markdown instructions.
|
||||
- **Memory system:** `.memory/` — persistent project knowledge, decisions, plans, and research in markdown.
|
||||
- **Cross-tool instruction files:** `AGENTS.md`, `CLAUDE.md`, `.github/copilot-instructions.md`, `.cursorrules` — derived views of project knowledge for different agentic tools.
|
||||
- **Cross-tool instruction files:** `.github/copilot-instructions.md` is the single real instruction file; `AGENTS.md`, `CLAUDE.md`, and `.cursorrules` should be symlinks to it.
|
||||
|
||||
## Agent Architecture
|
||||
|
||||
@@ -32,6 +32,13 @@ Agents with memory-only edit access are constrained by instruction-level guardra
|
||||
|
||||
Tiered pipeline (Tier 1/2/3) defined in `agents/lead.md`. Standard flow: `explorer/researcher → coder → reviewer → tester → librarian`.
|
||||
|
||||
## Documentation Skill Conventions
|
||||
|
||||
- `skills/doc-coverage/SKILL.md` section `### 3. Instruction File` validates one canonical instruction file (`.github/copilot-instructions.md`) plus symlink correctness for `AGENTS.md`, `CLAUDE.md`, and `.cursorrules`, rather than treating all four as independently edited files.
|
||||
- The checklist explicitly flags duplication of `.memory/` tracking content (plans/research) inside instruction files as an anti-pattern.
|
||||
|
||||
See [Cross-Tool Instruction Files](../AGENTS.md#cross-tool-instruction-files) and [Doc coverage checklist section 3](../skills/doc-coverage/SKILL.md#3-instruction-file).
|
||||
|
||||
## MCP Servers
|
||||
|
||||
- **Context7:** Remote documentation lookup (`https://mcp.context7.com/mcp`)
|
||||
|
||||
Reference in New Issue
Block a user