diff --git a/.config/opencode/.cursorrules b/.config/opencode/.cursorrules deleted file mode 100644 index 8950fe7..0000000 --- a/.config/opencode/.cursorrules +++ /dev/null @@ -1,52 +0,0 @@ -# OpenCode Agent Configuration - -This repository contains the multi-agent configuration for OpenCode, defining agent roles, permissions, quality pipelines, and project memory conventions. - -## Project Structure - -``` -opencode.jsonc # Main config: default agent, plugins, permissions, MCP servers -agents/ # Agent definitions (one .md per agent) - lead.md # Primary orchestrator - coder.md # Implementation agent - reviewer.md # Code review (read-only code, writes .memory/*) - tester.md # Test validation (writes .memory/*) - explorer.md # Codebase mapping (read-only code, writes .memory/*) - researcher.md # Technical investigation (writes .memory/*) - librarian.md # Documentation specialist (full edit) - critic.md # Plan review gate (writes .memory/*) - sme.md # Domain expert (writes .memory/*) - designer.md # UI/UX guidance (writes .memory/*) -.memory/ # Persistent project memory (knowledge, decisions, plans, research) -AGENTS.md # OpenCode instruction file -CLAUDE.md # Claude Code instruction file -.github/copilot-instructions.md # GitHub Copilot instruction file -.cursorrules # This file (Cursor instruction file) -``` - -## Agent Permission Model - -- **Full edit access:** `lead`, `coder`, `librarian`. -- **Memory-only edit access:** `reviewer`, `tester`, `explorer`, `researcher`, `critic`, `sme`, `designer` — `permission.edit: allow` in config, but instructions restrict edits to `.memory/*` only. Code/source edits remain read-only. -- OpenCode does not support path-scoped `permission.edit`, so guardrails are instruction-level. - -## Memory System - -`.memory/` is the persistent project knowledge store: -- `knowledge.md` — architecture, patterns, key concepts -- `decisions.md` — architecture decisions, design choices -- `plans/.md` — active plans with tasks and statuses -- `research/.md` — research findings - -Workflow: read relevant `.memory/` files → work → update `.memory/` files with outcomes. - -## Quality Pipeline - -Standard flow: `explorer/researcher → coder → reviewer → tester → librarian`. -Three tiers based on change scope (Tier 1: full, Tier 2: standard, Tier 3: fast). - -## Conventions - -- Cross-tool instruction files (`AGENTS.md`, `CLAUDE.md`, `.github/copilot-instructions.md`, `.cursorrules`) must stay synchronized. -- `.memory/knowledge.md` is the canonical source of truth; instruction files are derived views. -- Recording discipline: record only outcomes/decisions/discoveries in `.memory/`, never ceremony checkpoints. diff --git a/.config/opencode/.cursorrules b/.config/opencode/.cursorrules new file mode 120000 index 0000000..02dd134 --- /dev/null +++ b/.config/opencode/.cursorrules @@ -0,0 +1 @@ +.github/copilot-instructions.md \ No newline at end of file diff --git a/.config/opencode/.github/copilot-instructions.md b/.config/opencode/.github/copilot-instructions.md index 944cc73..fb993bc 100644 --- a/.config/opencode/.github/copilot-instructions.md +++ b/.config/opencode/.github/copilot-instructions.md @@ -18,10 +18,9 @@ agents/ # Agent definitions (one .md per agent) sme.md # Domain expert (writes .memory/*) designer.md # UI/UX guidance (writes .memory/*) .memory/ # Persistent project memory (knowledge, decisions, plans, research) -AGENTS.md # OpenCode instruction file -CLAUDE.md # Claude Code instruction file -.github/copilot-instructions.md # This file (GitHub Copilot instruction file) -.cursorrules # Cursor instruction file +AGENTS.md # Global OpenCode config (not a symlink in this repo) +CLAUDE.md -> .github/copilot-instructions.md +.cursorrules -> .github/copilot-instructions.md ``` ## Agent Permission Model @@ -47,6 +46,6 @@ Three tiers based on change scope (Tier 1: full, Tier 2: standard, Tier 3: fast) ## Conventions -- Cross-tool instruction files (`AGENTS.md`, `CLAUDE.md`, `.github/copilot-instructions.md`, `.cursorrules`) must stay synchronized. -- `.memory/knowledge.md` is the canonical source of truth; instruction files are derived views. +- This repo uses symlinks for cross-tool instruction files: `CLAUDE.md` and `.cursorrules` point to this file. +- `.memory/knowledge.md` is the canonical source of truth for deep project knowledge. - Recording discipline: record only outcomes/decisions/discoveries in `.memory/`, never ceremony checkpoints. diff --git a/.config/opencode/.memory/decisions.md b/.config/opencode/.memory/decisions.md index a7bf530..2cf9848 100644 --- a/.config/opencode/.memory/decisions.md +++ b/.config/opencode/.memory/decisions.md @@ -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) diff --git a/.config/opencode/.memory/knowledge.md b/.config/opencode/.memory/knowledge.md index ad26a48..d6a0914 100644 --- a/.config/opencode/.memory/knowledge.md +++ b/.config/opencode/.memory/knowledge.md @@ -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`) diff --git a/.config/opencode/AGENTS.md b/.config/opencode/AGENTS.md index d832512..a58252b 100644 --- a/.config/opencode/AGENTS.md +++ b/.config/opencode/AGENTS.md @@ -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 diff --git a/.config/opencode/CLAUDE.md b/.config/opencode/CLAUDE.md deleted file mode 100644 index 6b458d4..0000000 --- a/.config/opencode/CLAUDE.md +++ /dev/null @@ -1,52 +0,0 @@ -# OpenCode Agent Configuration - -This repository contains the multi-agent configuration for OpenCode, defining agent roles, permissions, quality pipelines, and project memory conventions. - -## Project Structure - -``` -opencode.jsonc # Main config: default agent, plugins, permissions, MCP servers -agents/ # Agent definitions (one .md per agent) - lead.md # Primary orchestrator - coder.md # Implementation agent - reviewer.md # Code review (read-only code, writes .memory/*) - tester.md # Test validation (writes .memory/*) - explorer.md # Codebase mapping (read-only code, writes .memory/*) - researcher.md # Technical investigation (writes .memory/*) - librarian.md # Documentation specialist (full edit) - critic.md # Plan review gate (writes .memory/*) - sme.md # Domain expert (writes .memory/*) - designer.md # UI/UX guidance (writes .memory/*) -.memory/ # Persistent project memory (knowledge, decisions, plans, research) -AGENTS.md # OpenCode instruction file -CLAUDE.md # This file (Claude Code instruction file) -.github/copilot-instructions.md # GitHub Copilot instruction file -.cursorrules # Cursor instruction file -``` - -## Agent Permission Model - -- **Full edit access:** `lead`, `coder`, `librarian`. -- **Memory-only edit access:** `reviewer`, `tester`, `explorer`, `researcher`, `critic`, `sme`, `designer` — `permission.edit: allow` in config, but instructions restrict edits to `.memory/*` only. Code/source edits remain read-only. -- OpenCode does not support path-scoped `permission.edit`, so guardrails are instruction-level. - -## Memory System - -`.memory/` is the persistent project knowledge store: -- `knowledge.md` — architecture, patterns, key concepts -- `decisions.md` — architecture decisions, design choices -- `plans/.md` — active plans with tasks and statuses -- `research/.md` — research findings - -Workflow: read relevant `.memory/` files → work → update `.memory/` files with outcomes. - -## Quality Pipeline - -Standard flow: `explorer/researcher → coder → reviewer → tester → librarian`. -Three tiers based on change scope (Tier 1: full, Tier 2: standard, Tier 3: fast). - -## Conventions - -- Cross-tool instruction files (`AGENTS.md`, `CLAUDE.md`, `.github/copilot-instructions.md`, `.cursorrules`) must stay synchronized. -- `.memory/knowledge.md` is the canonical source of truth; instruction files are derived views. -- Recording discipline: record only outcomes/decisions/discoveries in `.memory/`, never ceremony checkpoints. diff --git a/.config/opencode/CLAUDE.md b/.config/opencode/CLAUDE.md new file mode 120000 index 0000000..02dd134 --- /dev/null +++ b/.config/opencode/CLAUDE.md @@ -0,0 +1 @@ +.github/copilot-instructions.md \ No newline at end of file diff --git a/.config/opencode/agents/lead.md b/.config/opencode/agents/lead.md index 1e83fd3..62a8484 100644 --- a/.config/opencode/agents/lead.md +++ b/.config/opencode/agents/lead.md @@ -140,9 +140,8 @@ Minimum viable workflow for well-understood follow-on work: **PLAN → EXECUTE - Memory: record reusable patterns in `.memory/decisions.md` under `## Retrospective: `. - **Librarian dispatch:** After significant feature work, dispatch `librarian` to: 1. Update project documentation (README, docs/*) - 2. Sync cross-tool instruction files (`AGENTS.md`, `CLAUDE.md`, `.github/copilot-instructions.md`, `.cursorrules`) + 2. Update `.github/copilot-instructions.md` if project conventions/architecture changed 3. Update `.memory/knowledge.md` with new architecture/pattern knowledge - 4. Merge any knowledge from instruction files that other tools may have added ## Knowledge Freshness Loop @@ -370,6 +369,6 @@ This is a ~30-second mental check, not a full review. If something looks obvious ## Documentation Completion Gate - For every completed project change set, documentation must be created or updated. -- Minimum required documentation coverage: `README` + relevant `docs/*` files + cross-tool instruction files (`AGENTS.md`, `CLAUDE.md`, `.github/copilot-instructions.md`, `.cursorrules`) when project conventions, commands, architecture, workflow, policies, or agent behavior changes. +- Minimum required documentation coverage: `README` + relevant `docs/*` files + `.github/copilot-instructions.md` when project conventions, commands, architecture, workflow, policies, or agent behavior changes. - **Documentation is a completion gate, not a follow-up task.** Do not declare a task done, ask "what's next?", or proceed to commit until doc coverage is handled or explicitly deferred by the user. Waiting for the user to ask is a failure. - **Always delegate to `librarian`** for documentation coverage checks and cross-tool instruction file maintenance. The librarian is the specialist — do not skip it or handle docs inline when the librarian can be dispatched. diff --git a/.config/opencode/agents/librarian.md b/.config/opencode/agents/librarian.md index 6fa8c9d..6a7e7ae 100644 --- a/.config/opencode/agents/librarian.md +++ b/.config/opencode/agents/librarian.md @@ -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). diff --git a/.config/opencode/commands/bootstrap-memory.md b/.config/opencode/commands/bootstrap-memory.md index c507465..44e7d4f 100644 --- a/.config/opencode/commands/bootstrap-memory.md +++ b/.config/opencode/commands/bootstrap-memory.md @@ -60,26 +60,13 @@ constraints). Include rationale when known. - If research artifacts are discovered, create `.memory/research/.md` with findings and references. -## Step 6: Delegate instruction file creation to librarian +## Step 6: Update instruction file -After `.memory/knowledge.md` is populated, dispatch the `librarian` subagent to -create or update all cross-tool instruction files from `.memory/knowledge.md`: +If `.github/copilot-instructions.md` exists, update it with any new project knowledge +discovered during bootstrap (architecture, conventions, commands). The symlinks +(`AGENTS.md`, `CLAUDE.md`, `.cursorrules`) will automatically reflect changes. -- `AGENTS.md` -- `CLAUDE.md` -- `.github/copilot-instructions.md` -- `.cursorrules` - -Each file should include the same core project guidance: -- project overview and purpose -- tech stack -- architecture summary -- coding conventions/patterns -- build/test/lint commands -- project structure overview - -If any of these files already exist, preserve existing project-specific content -and merge in new knowledge instead of overwriting wholesale. +If the instruction file doesn't exist, note that `/init` should be run to create it. ## Guidelines diff --git a/.config/opencode/commands/init.md b/.config/opencode/commands/init.md index ca18ae2..6cd9f3b 100644 --- a/.config/opencode/commands/init.md +++ b/.config/opencode/commands/init.md @@ -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. diff --git a/.config/opencode/commands/save-memory.md b/.config/opencode/commands/save-memory.md index f816cbc..fae096f 100644 --- a/.config/opencode/commands/save-memory.md +++ b/.config/opencode/commands/save-memory.md @@ -55,18 +55,11 @@ Example cross-reference: Re-read updated `.memory/` files to confirm they reflect current understanding. Report what was added/updated and where. -## Step 6: Delegate instruction file sync to librarian +## Step 6: Update instruction file if project knowledge changed -If `.memory/knowledge.md` was **materially** updated in this save (architecture, -conventions, commands — not just plans/research), dispatch the `librarian` -subagent to: - -1. Read all cross-tool instruction files (`AGENTS.md`, `CLAUDE.md`, - `.github/copilot-instructions.md`, `.cursorrules`) -2. Check for knowledge in instruction files not yet in `.memory/knowledge.md` - and merge it inward -3. Update instruction files to reflect new `.memory/knowledge.md` content -4. Report sync status +If `.memory/knowledge.md` was **materially** updated (architecture, conventions, +commands — not just plans/research), update `.github/copilot-instructions.md` to +reflect the changes. The symlinks automatically propagate to all tools. If updates were only plans/research/tracking details, skip this step. diff --git a/.config/opencode/skills/doc-coverage/SKILL.md b/.config/opencode/skills/doc-coverage/SKILL.md index 1d3d226..1eb8056 100644 --- a/.config/opencode/skills/doc-coverage/SKILL.md +++ b/.config/opencode/skills/doc-coverage/SKILL.md @@ -21,14 +21,27 @@ For every completed change set, verify documentation coverage: - [ ] Do new features need their own doc page? - [ ] Are API changes reflected in API documentation? -### 3. Agent/Tool Instruction Files -- [ ] Did this change alter workflow, policies, conventions, commands, or architecture guidance? -- [ ] `AGENTS.md` (OpenCode instructions) is updated if needed. -- [ ] `CLAUDE.md` (Claude Code instructions) is updated if needed. -- [ ] `.github/copilot-instructions.md` (GitHub Copilot instructions) is updated if needed. -- [ ] `.cursorrules` (Cursor instructions) is updated if needed. -- [ ] Are all instruction files consistent with each other? -- [ ] Do instruction files reflect the current project state? +### 3. Instruction File + +Check `.github/copilot-instructions.md` and its symlinks: + +- Does `.github/copilot-instructions.md` exist and contain current project info? +- Do symlinks exist and point correctly? + - `AGENTS.md -> .github/copilot-instructions.md` + - `CLAUDE.md -> .github/copilot-instructions.md` + - `.cursorrules -> .github/copilot-instructions.md` +- Does the instruction file contain: + - Project purpose and overview + - Tech stack and architecture + - Coding conventions + - Build/test/lint commands + - Project structure +- Is the instruction file in sync with current project state? + +**Anti-patterns:** +- Symlinks missing or pointing to wrong location +- Instruction file is stale or empty +- Instruction file duplicates `.memory/` tracking content (plans, research) ### 4. Inline documentation - [ ] Are complex functions/components documented with comments explaining **why**, not **what**?