alex/dotfiles
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: adopt symlink approach for cross-tool instruction files

Browse Source 
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:
alex
2026-03-08 23:48:42 +00:00
parent 9830f6f01c
commit e9074646b7
12 changed files with 121 additions and 195 deletions
Download Patch File Download Diff File Expand all files Collapse all files

52
.config/opencode/.cursorrules
View File

@@ -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/<feature>.md` — active plans with tasks and statuses
- `research/<topic>.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.

1
.config/opencode/.cursorrules Symbolic link
View File

@@ -0,0 +1 @@
.github/copilot-instructions.md

11
.config/opencode/.github/copilot-instructions.md vendored
View File

@@ -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.

16
.config/opencode/.memory/decisions.md
View File

@@ -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)

9
.config/opencode/.memory/knowledge.md
View File

@@ -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`)

47
.config/opencode/AGENTS.md
View File

@@ -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

52
.config/opencode/CLAUDE.md
View File

@@ -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/<feature>.md` — active plans with tasks and statuses
- `research/<topic>.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.

1
.config/opencode/CLAUDE.md Symbolic link
View File

@@ -0,0 +1 @@
.github/copilot-instructions.md

5
.config/opencode/agents/lead.md
View File

@@ -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: <topic>`.
- **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.

33
.config/opencode/agents/librarian.md
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).

23
.config/opencode/commands/bootstrap-memory.md
View File

@@ -60,26 +60,13 @@ constraints). Include rationale when known.
- If research artifacts are discovered, create `.memory/research/<topic>.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

22
.config/opencode/commands/init.md
View File

@@ -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.

15
.config/opencode/commands/save-memory.md
View File

@@ -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.

29
.config/opencode/skills/doc-coverage/SKILL.md
View File

@@ -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**?