diff --git a/.config/opencode/.gitignore b/.config/opencode/.gitignore new file mode 100644 index 0000000..adbac3e --- /dev/null +++ b/.config/opencode/.gitignore @@ -0,0 +1,6 @@ +node_modules +package.json +bun.lock +.megamemory/ +.memory/ +.worktrees/ diff --git a/.config/opencode/AGENTS.md b/.config/opencode/AGENTS.md index 6785f5d..d5a20c9 100644 --- a/.config/opencode/AGENTS.md +++ b/.config/opencode/AGENTS.md @@ -9,9 +9,9 @@ permalink: opencode-config/agents Memory uses one persistent system: **basic-memory**. - All persistent knowledge is stored in basic-memory notes, split across a **`main` project** (global/shared) and **per-repo projects** (project-specific). -- Repo-local `.memory/` files are legacy artifacts and are **not** the active source of truth. -- Do not create, update, or rely on `.memory/*` for current work tracking. -- **Migration note:** Existing repo-local `.memory/` directories (or `.memory.legacy/`) in projects are non-authoritative and should be ignored unless you are explicitly migrating historical content into basic-memory. Do not delete them automatically — they may contain useful historical context for one-time migration. +- The managed per-repo basic-memory project directory is `/.memory/`. +- Do not edit managed `.memory/*` files directly; use basic-memory MCP tools for all reads/writes. +- **Migration note:** Older repo-local memory workflow artifacts (including `.memory.legacy/` and legacy contents from prior workflows) are non-authoritative and should not be edited unless you are explicitly migrating historical content into basic-memory. ### basic-memory @@ -44,12 +44,12 @@ Every code repository must have its own dedicated basic-memory project. This is **Creating a new per-repo project:** Use `basic-memory_create_memory_project` (or the equivalent MCP tool) with: - `project_name`: a short, kebab-case identifier for the repo (e.g., `opencode-config`, `my-web-app`, `data-pipeline`) -- `project_path`: the repo's root directory on disk +- `project_path`: the repo's `.memory/` subdirectory on disk (i.e., `/.memory`) Example for this repo: ``` project_name: opencode-config -project_path: /home/alex/dotfiles/.config/opencode +project_path: /home/alex/dotfiles/.config/opencode/.memory ``` **Checking if a project exists:** diff --git a/.config/opencode/agents/lead.md b/.config/opencode/agents/lead.md index be9db98..28481ae 100644 --- a/.config/opencode/agents/lead.md +++ b/.config/opencode/agents/lead.md @@ -379,4 +379,4 @@ This is a ~30-second mental check, not a full review. If something looks obvious - For every completed project change set, documentation must be created or updated. - 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. \ No newline at end of file +- **Always delegate to `librarian`** for documentation coverage checks and `AGENTS.md` 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 dfd562f..1313836 100644 --- a/.config/opencode/agents/librarian.md +++ b/.config/opencode/agents/librarian.md @@ -15,7 +15,7 @@ You are the Librarian subagent. Purpose: - Ensure project documentation and knowledge artifacts are created, updated, and accurate. -- Maintain the instruction file (`AGENTS.md`) and its symlinks. +- Maintain the instruction file (`AGENTS.md`) as the single source of truth. - Keep basic-memory guidance and project notes accurate and useful as the project evolves. - Ensure all memory references use the `main` vs per-repo project split correctly. @@ -35,7 +35,7 @@ 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**: `CLAUDE.md`, `.cursorrules`, `.github/copilot-instructions.md` should all point to `AGENTS.md` +- **Keep guidance centralized**: repo instruction guidance belongs in `AGENTS.md` only - **Do NOT duplicate memory project contents** — instruction file is for "how to work here", not "what we're doing" - **Ensure the repo's basic-memory project name is documented** in `AGENTS.md` (e.g., `opencode-config`) @@ -63,4 +63,4 @@ Ensure memory guidance consistently reflects the `main` vs per-repo project spli - Summarize documentation changes first. - List updated files and why each was changed. - Explicitly call out any deferred documentation debt. -- Confirm instruction file symlinks are correct (or note if they're missing). \ No newline at end of file +- Confirm repo instruction guidance lives in `AGENTS.md` only. diff --git a/.config/opencode/commands/bootstrap-memory.md b/.config/opencode/commands/bootstrap-memory.md index a0b7e4d..ebcfe72 100644 --- a/.config/opencode/commands/bootstrap-memory.md +++ b/.config/opencode/commands/bootstrap-memory.md @@ -19,7 +19,8 @@ so future sessions can resume quickly. Use `list_memory_projects` to check whether this repo already has a basic-memory project. If not, create one with `create_memory_project` using a short kebab-case -name (e.g., `my-web-app`) and the repo's root directory as `project_path`. +name (e.g., `my-web-app`) and the repo's `.memory/` subdirectory as `project_path` +(e.g., `/path/to/repo/.memory`). All subsequent `write_note`, `search_notes`, and `build_context` calls in this command must pass `project=""` for project-specific notes, or @@ -36,9 +37,9 @@ current state prevents duplication and helps you decide what to create vs update 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`, -`.cursorrules`, `.github/copilot-instructions.md`) — they may contain project -knowledge from other tools or team members that should be incorporated. +Also check whether any legacy tool-specific instruction files exist alongside +`AGENTS.md` — they may contain project knowledge from other tools or team +members that should be consolidated into `AGENTS.md`. Identify: - What the project does (primary capabilities) @@ -81,9 +82,9 @@ Do not store project-specific plans, decisions, or session state in `main`. If `AGENTS.md` exists, update it with any new project knowledge discovered during bootstrap (architecture, conventions, commands). Add the repo's basic-memory project name (e.g., `opencode-config`) to `AGENTS.md` so -agents know which project to target. The symlinks (`CLAUDE.md`, -`.cursorrules`, `.github/copilot-instructions.md`) will automatically -reflect changes. +agents know which project to target. If legacy tool-specific instruction files +exist, consolidate any durable repo guidance into `AGENTS.md` and stop +maintaining duplicate copies. If the instruction file doesn't exist, note that `/init` should be run to create it. @@ -94,4 +95,4 @@ If the instruction file doesn't exist, note that `/init` should be run to create - Prefer durable knowledge over transient status notes. - Use WikiLinks `[[Topic]]` to create relations between related notes. - Use tags for categorization: `#pattern`, `#convention`, `#decision`, `#architecture`. -- Always pass the `project` parameter on every MCP call. \ No newline at end of file +- Always pass the `project` parameter on every MCP call. diff --git a/.config/opencode/commands/init.md b/.config/opencode/commands/init.md index db1e3d5..c3544ef 100644 --- a/.config/opencode/commands/init.md +++ b/.config/opencode/commands/init.md @@ -47,10 +47,7 @@ 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` — 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` + - `AGENTS.md` — instruction file containing shared project guidance - `docs/architecture.md` — stub with title + purpose - `.gitignore` — add stack-appropriate ignores (e.g., `node_modules/`, `__pycache__/`, `target/`) - other stack-specific scaffold files if clearly implied (e.g., `package.json`, `pyproject.toml`) @@ -60,14 +57,9 @@ 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 `AGENTS.md` exists as the real instruction file - - create missing symlinks: - - `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 + - ensure `AGENTS.md` exists as the project instruction file + - if legacy tool-specific instruction files exist, consolidate any repo-specific guidance into `AGENTS.md` and stop maintaining duplicate copies - examples: - - 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`) @@ -76,7 +68,7 @@ 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` 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 repo instruction guidance lives in `AGENTS.md` only. - Ensure stubs are explicitly marked for later completion. - Keep edits additive and non-destructive for existing projects. @@ -84,7 +76,7 @@ Always delegate to the `librarian` subagent, for both new and existing projects. Always create or update basic-memory project notes for this project. -- **Ensure a dedicated per-repo basic-memory project exists.** Use `list_memory_projects` to check. If not found, create one with `create_memory_project` using a short kebab-case name (e.g., `my-web-app`) and the repo's root directory as `project_path`. +- **Ensure a dedicated per-repo basic-memory project exists.** Use `list_memory_projects` to check. If not found, create one with `create_memory_project` using a short kebab-case name (e.g., `my-web-app`) and the repo's `.memory/` subdirectory as `project_path` (e.g., `/path/to/repo/.memory`). - All subsequent note operations in this step must pass `project=""`. - Use `search_notes` (with `project`) to check for existing project notes to avoid duplicates. - Use `write_note` (with `project`) to create or update a `knowledge/overview` note with: @@ -114,4 +106,4 @@ Delegate git operations to `coder` based on discovered state. Summarize: - Files created and files updated, with purpose. - Decisions made and decisions deferred. -- What the user should fill in next (stubs, open questions, follow-up documentation). \ No newline at end of file +- What the user should fill in next (stubs, open questions, follow-up documentation). diff --git a/.config/opencode/commands/save-memory.md b/.config/opencode/commands/save-memory.md index bdb40e7..b3a7a95 100644 --- a/.config/opencode/commands/save-memory.md +++ b/.config/opencode/commands/save-memory.md @@ -15,7 +15,8 @@ you noticed, or intent the user shared. Use `list_memory_projects` to find this repo's dedicated basic-memory project. If it doesn't exist, create one with `create_memory_project` using a short -kebab-case name and the repo's root directory as `project_path`. +kebab-case name and the repo's `.memory/` subdirectory as `project_path` +(e.g., `/path/to/repo/.memory`). All project-specific notes must target `project=""`. Cross-project reusable knowledge must target `project="main"`. @@ -68,7 +69,7 @@ Report what was added/updated, where, and in which project. If project `knowledge/` notes were **materially** updated (architecture, conventions, commands — not just plans/research), update `AGENTS.md` to reflect the changes. -The symlinks automatically propagate to all tools. +Keep repo instruction guidance in `AGENTS.md` only. If updates were only plans/research/tracking details, skip this step. @@ -80,4 +81,4 @@ If updates were only plans/research/tracking details, skip this step. - Keep hierarchy shallow (max 2 heading levels preferred). - Be specific. "Handles auth" is weak. "JWT auth with RS256, validated in `src/middleware/auth.ts`, refresh tokens in Redis with 7d TTL" is useful. -- Always pass the `project` parameter on every MCP call. \ No newline at end of file +- Always pass the `project` parameter on every MCP call. diff --git a/.config/opencode/decisions/Instruction File Policy.md b/.config/opencode/decisions/Instruction File Policy.md deleted file mode 100644 index 74b97cc..0000000 --- a/.config/opencode/decisions/Instruction File Policy.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: Instruction File Policy -type: note -permalink: opencode-config/decisions/instruction-file-policy -tags: -- instructions -- convention ---- - -# Instruction File Policy - -## Decision -- [decision] `AGENTS.md` is the only instruction file maintained in this repo. #convention -- [decision] Do not create or maintain mirrored instruction files or symlinks for other agent tools. #convention -- [decision] If a tool needs repo instructions, point it at `AGENTS.md` directly. #convention - -## Rationale -- [lesson] Keeping a single source of truth removes cross-tool instruction maintenance overhead and avoids duplicated or stale guidance. #lesson diff --git a/.config/opencode/decisions/Memory System Main vs Per-Repo Project Split.md b/.config/opencode/decisions/Memory System Main vs Per-Repo Project Split.md deleted file mode 100644 index 0074135..0000000 --- a/.config/opencode/decisions/Memory System Main vs Per-Repo Project Split.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -title: Memory System Main vs Per-Repo Project Split -type: note -permalink: opencode-config/decisions/memory-system-main-vs-per-repo-project-split -tags: -- memory -- convention -- decision -- architecture ---- - -# Memory System: Main vs Per-Repo Project Split - -## Decision -Adopted a strict two-project split for basic-memory: -- `main` is reserved exclusively for global/shared knowledge (reusable patterns, conventions, tech knowledge, user preferences, cross-project lessons) -- Each code repository gets its own dedicated basic-memory project for project-specific knowledge (plans, decisions, research, gates, sessions, architecture) - -## Observations -- [decision] `main` is global-only; never store project plans/decisions/research/gates/sessions in `main` #memory #convention -- [decision] Every repo must have a per-repo basic-memory project created via `create_memory_project` #memory #convention -- [decision] Session-start protocol requires identifying and selecting the per-repo project before any reads/writes #memory #convention -- [decision] All MCP calls must pass the `project` parameter explicitly — `project="main"` for global, `project=""` for project-specific #memory #convention -- [decision] Repo-local `.memory/` directories are legacy artifacts, renamed to `.memory.legacy/` #memory - -## Affected Files (opencode-config repo) -- `AGENTS.md` — core memory system section rewritten with main/per-repo split, session-start protocol, project setup instructions -- `commands/init.md` — Step 5 creates per-repo basic-memory project -- `commands/bootstrap-memory.md` — Step 0 ensures per-repo project, all steps pass project parameter -- `commands/save-memory.md` — distinguishes main vs per-repo targets -- `commands/status.md` — requires per-repo project identification -- `commands/plan.md` — per-repo project targeting for plans/decisions/research -- `commands/sme.md` — split guidance caching between main and per-repo -- `commands/research.md` — split project targeting -- `commands/review.md` — per-repo project targeting -- `commands/test.md` — per-repo project targeting -- `commands/docs.md` — per-repo project targeting -- `agents/lead.md` — session-start project identification, all note sections updated -- `agents/sme.md` — explicit main vs per-repo caching workflow -- `agents/librarian.md` — updated to enforce main/per-repo split in docs -- `agents/reviewer.md` — per-repo project recording -- `agents/tester.md` — per-repo project recording -- `agents/critic.md` — per-repo project recording -- `agents/designer.md` — per-repo project recording -- `skills/git-workflow/SKILL.md` — clarified per-repo/main in legacy note - -## Relations -- related_to [[opencode-config Knowledge Overview]] \ No newline at end of file diff --git a/.config/opencode/gates/Review- Main vs Per-Repo Project Split Consistency.md b/.config/opencode/gates/Review- Main vs Per-Repo Project Split Consistency.md deleted file mode 100644 index 03311f9..0000000 --- a/.config/opencode/gates/Review- Main vs Per-Repo Project Split Consistency.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -title: 'Review: Main vs Per-Repo Project Split Consistency' -type: note -permalink: opencode-config/gates/review-main-vs-per-repo-project-split-consistency -tags: -- review -- memory -- approved -- consistency ---- - -# Review: Main vs Per-Repo Project Split Consistency - -## Verdict -- [decision] APPROVED — all instruction files consistently enforce the main/per-repo basic-memory project split #review #memory - -## Scope Reviewed -- `AGENTS.md` — core memory system section -- All 10 command files (`commands/*.md`) -- All 10 agent definition files (`agents/*.md`) -- All 3 skill files (`skills/*/SKILL.md`) -- Legacy `.memory.legacy/` directory (confirmed non-authoritative) -- `decisions/Memory System Main vs Per-Repo Project Split.md` (migration decision note) - -## Key Findings -- [finding] Zero files instruct agents to store project-specific notes in `main` — hard rule at AGENTS.md:32 is consistently enforced #confirmed -- [finding] Session-start protocol is documented in 6 locations with consistent create-if-missing pattern #confirmed -- [finding] All `project="main"` references correctly scope to cross-project reusable knowledge only #confirmed -- [finding] No contradictions between any files — migration decision note lists all affected files, all verified updated #confirmed -- [finding] Minor precision gap: explorer.md and researcher.md use generic "relevant basic-memory project notes" without explicit project parameter guidance, but behavior is practically correct #suggestion - -## Relations -- related_to [[Memory System Main vs Per-Repo Project Split]] diff --git a/.config/opencode/skills/doc-coverage/SKILL.md b/.config/opencode/skills/doc-coverage/SKILL.md index dd102c9..03aa69b 100644 --- a/.config/opencode/skills/doc-coverage/SKILL.md +++ b/.config/opencode/skills/doc-coverage/SKILL.md @@ -25,13 +25,10 @@ For every completed change set, verify documentation coverage: ### 3. Instruction File -Check `AGENTS.md` and its symlinks: +Check `AGENTS.md` as the single instruction source: - Does `AGENTS.md` exist and contain current project info? -- Do symlinks exist and point correctly? - - `CLAUDE.md -> AGENTS.md` - - `.cursorrules -> AGENTS.md` - - `.github/copilot-instructions.md -> ../AGENTS.md` +- If legacy tool-specific instruction files exist, has their durable repo guidance been consolidated into `AGENTS.md`? - Does the instruction file contain: - Project purpose and overview - Tech stack and architecture @@ -41,7 +38,7 @@ Check `AGENTS.md` and its symlinks: - Is the instruction file in sync with current project state? **Anti-patterns:** -- Symlinks missing or pointing to wrong location +- Mirrored instruction files requiring parallel maintenance - Instruction file is stale or empty - Instruction file duplicates basic-memory project note content (plans, research) @@ -69,4 +66,4 @@ Check `AGENTS.md` and its symlinks: - The **librarian** subagent is the specialist for documentation work. - Lead should delegate doc coverage review to librarian after coder completes implementation. -- Librarian reads the changes, identifies doc gaps, and writes/updates documentation. \ No newline at end of file +- Librarian reads the changes, identifies doc gaps, and writes/updates documentation. diff --git a/.config/opencode/skills/git-workflow/SKILL.md b/.config/opencode/skills/git-workflow/SKILL.md index 9eac407..e064125 100644 --- a/.config/opencode/skills/git-workflow/SKILL.md +++ b/.config/opencode/skills/git-workflow/SKILL.md @@ -15,7 +15,7 @@ permalink: opencode-config/skills/git-workflow/skill - 1-2 sentences max. - Match the repository's existing style. 5. Check for secrets: do NOT commit `.env`, credentials, or key files. -6. Repo-local `.memory/` directories are legacy artifacts and should not be relied upon. Do not commit new `.memory/` content — use basic-memory notes (in the per-repo project or `main`) instead. +6. The managed per-repo basic-memory project directory is `/.memory/`; do not edit managed `.memory/*` files directly. Older repo-local memory workflow artifacts (including `.memory.legacy/` and legacy contents from prior workflows) are non-authoritative and should not be edited unless explicitly migrating historical content into basic-memory. 7. Stage relevant files: `git add ` (not blindly `git add .`). 8. Commit: `git commit -m ""`. 9. Run `git status` after commit to verify success. @@ -101,4 +101,4 @@ gh issue comment -b "" # Add comment - **Never `git push --force` to `main`/`master`** unless the user explicitly confirms. - **Never skip hooks** (`--no-verify`) unless the user explicitly requests it. - **Never `git commit --amend`** unless: (1) explicitly requested OR pre-commit hook auto-modified files, (2) HEAD was created in this session, AND (3) commit has NOT been pushed to remote. -- If commit fails due to pre-commit hook, fix the issue and create a NEW commit. \ No newline at end of file +- If commit fails due to pre-commit hook, fix the issue and create a NEW commit.