From 33180d6e04d1148c92cb78417821244ea3f43134 Mon Sep 17 00:00:00 2001 From: alex Date: Mon, 9 Mar 2026 12:34:26 +0000 Subject: [PATCH] fix: flip symlink structure - AGENTS.md is the real file AGENTS.md is now the canonical instruction file, with CLAUDE.md, .cursorrules, and .github/copilot-instructions.md as symlinks to it. This is simpler and more intuitive - the main file is at the root, not buried in .github/. Updated all references across agents, commands, skills, and .memory/. --- .config/opencode/.cursorrules | 2 +- .../opencode/.github/copilot-instructions.md | 52 +------------------ .config/opencode/.memory/decisions.md | 8 +-- .config/opencode/.memory/knowledge.md | 4 +- .config/opencode/AGENTS.md | 22 ++++---- .config/opencode/CLAUDE.md | 2 +- .config/opencode/agents/lead.md | 4 +- .config/opencode/agents/librarian.md | 6 +-- .config/opencode/commands/bootstrap-memory.md | 9 ++-- .config/opencode/commands/init.md | 24 ++++----- .config/opencode/commands/save-memory.md | 4 +- .config/opencode/skills/doc-coverage/SKILL.md | 10 ++-- 12 files changed, 49 insertions(+), 98 deletions(-) mode change 100644 => 120000 .config/opencode/.github/copilot-instructions.md diff --git a/.config/opencode/.cursorrules b/.config/opencode/.cursorrules index 02dd134..47dc3e3 120000 --- a/.config/opencode/.cursorrules +++ b/.config/opencode/.cursorrules @@ -1 +1 @@ -.github/copilot-instructions.md \ No newline at end of file +AGENTS.md \ No newline at end of file diff --git a/.config/opencode/.github/copilot-instructions.md b/.config/opencode/.github/copilot-instructions.md deleted file mode 100644 index fb993bc..0000000 --- a/.config/opencode/.github/copilot-instructions.md +++ /dev/null @@ -1,51 +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 # Global OpenCode config (not a symlink in this repo) -CLAUDE.md -> .github/copilot-instructions.md -.cursorrules -> .github/copilot-instructions.md -``` - -## 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 - -- 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/.github/copilot-instructions.md b/.config/opencode/.github/copilot-instructions.md new file mode 120000 index 0000000..be77ac8 --- /dev/null +++ b/.config/opencode/.github/copilot-instructions.md @@ -0,0 +1 @@ +../AGENTS.md \ No newline at end of file diff --git a/.config/opencode/.memory/decisions.md b/.config/opencode/.memory/decisions.md index 2cf9848..fcf1f3c 100644 --- a/.config/opencode/.memory/decisions.md +++ b/.config/opencode/.memory/decisions.md @@ -17,15 +17,15 @@ See [Plan: Agent Memory Write Access](plans/agent-memory-write-access.md) | See ## 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. +**Decision:** Use `AGENTS.md` as the single source-of-truth instruction file and represent `CLAUDE.md`, `.cursorrules`, and `.github/copilot-instructions.md` 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. +- 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. +- Updated `agents/librarian.md` responsibilities from multi-file sync/merge to maintaining `AGENTS.md` plus symlink verification. +- Updated `agents/lead.md` PHASE-WRAP and Documentation Completion Gate to reference `AGENTS.md` instead of syncing four files. **Affected files:** `AGENTS.md`, `agents/librarian.md`, `agents/lead.md`, `.memory/knowledge.md`. diff --git a/.config/opencode/.memory/knowledge.md b/.config/opencode/.memory/knowledge.md index d6a0914..7315b3b 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:** `.github/copilot-instructions.md` is the single real instruction file; `AGENTS.md`, `CLAUDE.md`, and `.cursorrules` should be symlinks to it. +- **Cross-tool instruction files:** `AGENTS.md` is the single real instruction file; `CLAUDE.md`, `.cursorrules`, and `.github/copilot-instructions.md` are symlinks to it. ## Agent Architecture @@ -34,7 +34,7 @@ Tiered pipeline (Tier 1/2/3) defined in `agents/lead.md`. Standard flow: `explor ## 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. +- `skills/doc-coverage/SKILL.md` section `### 3. Instruction File` validates one canonical instruction file (`AGENTS.md`) plus symlink correctness for `CLAUDE.md`, `.cursorrules`, and `.github/copilot-instructions.md`, 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). diff --git a/.config/opencode/AGENTS.md b/.config/opencode/AGENTS.md index bdbcfb8..d869546 100644 --- a/.config/opencode/AGENTS.md +++ b/.config/opencode/AGENTS.md @@ -34,23 +34,23 @@ Be specific in summaries: include parameter names, defaults, file locations, and ## Cross-Tool Instruction Files -Use symlinks to share ONE instruction file across all agentic coding tools: +Use symlinks to share this 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 +├── AGENTS.md # Real file (edit this one) +├── CLAUDE.md -> AGENTS.md +├── .cursorrules -> AGENTS.md +└── .github/ + └── copilot-instructions.md -> ../AGENTS.md ``` **Rules:** -- Edit `.github/copilot-instructions.md` — changes propagate automatically via symlinks +- Edit `AGENTS.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:** +**Content of this file:** - Project overview and purpose - Tech stack and architecture - Coding conventions and patterns @@ -60,12 +60,12 @@ project/ **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.) +1. Create `AGENTS.md` with project basics +2. Create symlinks: `ln -s AGENTS.md CLAUDE.md`, `ln -s AGENTS.md .cursorrules`, `ln -s ../AGENTS.md .github/copilot-instructions.md` 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 +- Read `AGENTS.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 index 02dd134..47dc3e3 120000 --- a/.config/opencode/CLAUDE.md +++ b/.config/opencode/CLAUDE.md @@ -1 +1 @@ -.github/copilot-instructions.md \ No newline at end of file +AGENTS.md \ No newline at end of file diff --git a/.config/opencode/agents/lead.md b/.config/opencode/agents/lead.md index 62a8484..12b980c 100644 --- a/.config/opencode/agents/lead.md +++ b/.config/opencode/agents/lead.md @@ -140,7 +140,7 @@ 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. Update `.github/copilot-instructions.md` if project conventions/architecture changed + 2. Update `AGENTS.md` if project conventions/architecture changed 3. Update `.memory/knowledge.md` with new architecture/pattern knowledge ## Knowledge Freshness Loop @@ -369,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 + `.github/copilot-instructions.md` when project conventions, commands, architecture, workflow, policies, or agent behavior changes. +- Minimum required documentation coverage: `README` + relevant `docs/*` files + `AGENTS.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 6a7e7ae..712cc46 100644 --- a/.config/opencode/agents/librarian.md +++ b/.config/opencode/agents/librarian.md @@ -14,7 +14,7 @@ You are the Librarian subagent. Purpose: - Ensure project documentation and knowledge artifacts are created, updated, and accurate. -- Maintain the instruction file (`.github/copilot-instructions.md`) and its symlinks. +- Maintain the instruction file (`AGENTS.md`) and its symlinks. - Keep `.memory/` files accurate and useful as the project evolves. ## Core Responsibilities @@ -29,11 +29,11 @@ Purpose: ### 2. Instruction File -Maintain `.github/copilot-instructions.md` as the single source of truth: +Maintain `AGENTS.md` as the single source of truth: - **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` +- **Verify symlinks exist**: `CLAUDE.md`, `.cursorrules`, `.github/copilot-instructions.md` should all point to `AGENTS.md` - **Do NOT duplicate `.memory/` contents** — instruction file is for "how to work here", not "what we're doing" ### 3. Memory File Maintenance diff --git a/.config/opencode/commands/bootstrap-memory.md b/.config/opencode/commands/bootstrap-memory.md index 44e7d4f..57b55f7 100644 --- a/.config/opencode/commands/bootstrap-memory.md +++ b/.config/opencode/commands/bootstrap-memory.md @@ -29,7 +29,7 @@ Run `git ls-files` to understand the project layout, then read `README.md` and the highest-signal files for architecture and conventions. Also check for existing cross-tool instruction files (`AGENTS.md`, `CLAUDE.md`, -`.github/copilot-instructions.md`, `.cursorrules`) — they may contain project +`.cursorrules`, `.github/copilot-instructions.md`) — they may contain project knowledge from other tools or team members that should be incorporated. Identify: @@ -62,9 +62,10 @@ constraints). Include rationale when known. ## Step 6: Update instruction file -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. +If `AGENTS.md` exists, update it with any new project knowledge discovered +during bootstrap (architecture, conventions, commands). The symlinks +(`CLAUDE.md`, `.cursorrules`, `.github/copilot-instructions.md`) will +automatically reflect changes. If the instruction file doesn't exist, note that `/init` should be run to create it. diff --git a/.config/opencode/commands/init.md b/.config/opencode/commands/init.md index 6cd9f3b..1927884 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 - - `.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` + - `AGENTS.md` — real instruction file containing shared project guidance + - `CLAUDE.md` — symlink to `AGENTS.md` + - `.cursorrules` — symlink to `AGENTS.md` + - `.github/copilot-instructions.md` — symlink to `../AGENTS.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,15 +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 - - ensure `.github/copilot-instructions.md` exists as the real instruction file + - ensure `AGENTS.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 + - `ln -s AGENTS.md CLAUDE.md` + - `ln -s AGENTS.md .cursorrules` + - `ln -s ../AGENTS.md .github/copilot-instructions.md` + - if `AGENTS.md` is missing but `.github/copilot-instructions.md` exists as a real file, move its content into `AGENTS.md`, then recreate `.github/copilot-instructions.md` as a symlink - if `.memory/` is missing, create the full `.memory/` directory structure - examples: - - if `README.md` exists and only `AGENTS.md` is missing, create `AGENTS.md` as a symlink to `.github/copilot-instructions.md` + - if `README.md` exists and only `CLAUDE.md` is missing, create `CLAUDE.md` as a symlink to `AGENTS.md` - if `docs/` is missing, create it and add `docs/architecture.md` ## Step 4 — Documentation review (delegate to `librarian`) @@ -75,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 `.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 `AGENTS.md` exists and captures project-specific workflow decisions from Step 2. +- Verify `CLAUDE.md`, `.cursorrules`, and `.github/copilot-instructions.md` are symlinks to `AGENTS.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 fae096f..1256e6a 100644 --- a/.config/opencode/commands/save-memory.md +++ b/.config/opencode/commands/save-memory.md @@ -58,8 +58,8 @@ Report what was added/updated and where. ## Step 6: Update instruction file if project knowledge changed 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. +commands — not just plans/research), update `AGENTS.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 1eb8056..308fdc8 100644 --- a/.config/opencode/skills/doc-coverage/SKILL.md +++ b/.config/opencode/skills/doc-coverage/SKILL.md @@ -23,13 +23,13 @@ For every completed change set, verify documentation coverage: ### 3. Instruction File -Check `.github/copilot-instructions.md` and its symlinks: +Check `AGENTS.md` and its symlinks: -- Does `.github/copilot-instructions.md` exist and contain current project info? +- Does `AGENTS.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` + - `CLAUDE.md -> AGENTS.md` + - `.cursorrules -> AGENTS.md` + - `.github/copilot-instructions.md -> ../AGENTS.md` - Does the instruction file contain: - Project purpose and overview - Tech stack and architecture