diff --git a/.config/opencode/.megamemory/knowledge.db b/.config/opencode/.megamemory/knowledge.db deleted file mode 100644 index 3da46ff..0000000 Binary files a/.config/opencode/.megamemory/knowledge.db and /dev/null differ diff --git a/.config/opencode/AGENTS.md b/.config/opencode/AGENTS.md index 35ea2ce..e3df3c1 100644 --- a/.config/opencode/AGENTS.md +++ b/.config/opencode/AGENTS.md @@ -1,30 +1,56 @@ -## Project Knowledge Graph +## Project Memory -You have access to a project knowledge graph via the `megamemory` MCP server and skill tool. You have no implicit memory of this project between sessions, so this graph is your only continuity for concepts, architecture, decisions, and relationships. +Use markdown files in `.memory/` as the persistent project memory across sessions. This is the source of truth for architecture, decisions, plans, research, and implementation state. -**Workflow: understand → work → update** +**Directory structure:** -1. **Session start:** You must call `megamemory` with action `overview` (or `megamemory:list_roots` directly) before you begin work. -2. **Before each task:** You must call `megamemory` with action `query` (or `megamemory:understand` directly) before reading source files for project understanding. -3. **After each task:** You must call `megamemory` with action `record` to create/update/link concepts for what you built. +```text +.memory/ + knowledge.md # Persistent project knowledge (architecture, patterns, key concepts) + decisions.md # Architecture decisions, SME guidance, design choices + plans/ # One file per active plan/feature + .md # Plan with tasks, statuses, acceptance criteria + research/ # Research findings + .md # Research on a specific topic +``` -Be specific in summaries: include parameter names, defaults, file locations, and rationale. Keep concepts max 3 levels deep. +**Workflow: read files → work → update files** -**Recording discipline:** Only record outcomes, decisions, and discoveries — never phase transitions, status changes, or ceremony checkpoints. If a concept would only say "we started phase X", don't create it. Megamemory exists to preserve *knowledge*, not to log *activity*. +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. -**Query discipline:** -- Use `top_k=3` for `megamemory:understand` calls unless you have a specific reason to retrieve more. Large result sets bloat context without proportional value. -- **Skip `understand` when the graph has no relevant content.** If `list_roots` already showed no concepts in the relevant domain, do not call `understand` with rephrased queries hoping for different results. -- **Never re-query concepts you just created.** After calling `create_concept`, you already know the content — do not immediately call `understand` to retrieve it. -- Treat megamemory as a **tool**, not a ritual. Every query should have a specific information need; if you cannot articulate what you expect to find, skip the query. +Be specific in summaries: include parameter names, defaults, file locations, and rationale. Keep concepts organized as markdown sections (`## Heading`) and keep hierarchy shallow. -**Linking is required.** When creating or updating concepts, always create edges (`megamemory:link`) to related existing concepts. A concept with no edges is a dead end — always ask: *"What existing concept does this depend on, implement, or connect to?"* and link accordingly. +**Recording discipline:** Only record outcomes, decisions, and discoveries — never phase transitions, status changes, or ceremony checkpoints. If an entry would only say "we started phase X", don't add it. Memory files preserve *knowledge*, not *activity logs*. + +**Read discipline:** +- Read only the `.memory/` files relevant to the current task; avoid broad re-reads that add no new signal. +- **Skip redundant reads** when `.memory/` already has no relevant content in that domain this session. +- **Do not immediately re-read content you just wrote.** You already have that context from the update. +- Treat `.memory/` as a **tool**, not a ritual. Every read should have a specific information need. + +**Linking is required.** When recording related knowledge across files, add markdown cross-references (for example: `See [Decision: Auth](decisions.md#auth-approach)`). A section with no references becomes a dead end. + +## 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. ## Session Continuity -- Treat megamemory as the persistent tracking system for work across sessions. +- Treat `.memory/` files as the persistent tracking system for work across sessions. - At session start, identify prior in-progress work items and pending decisions before doing new implementation. -- After implementation, record what changed, why it changed, and what remains next. +- After implementation, update `.memory/` files with what changed, why it changed, and what remains next. ## Clarification Rule @@ -49,7 +75,7 @@ Be specific in summaries: include parameter names, defaults, file locations, and ## Parallelization -- **Always parallelize independent work.** Any tool calls that do not depend on each other's output must be issued in the same message as parallel calls — never sequentially. This applies to bash commands, file reads, subagent delegations, and megamemory queries alike. +- **Always parallelize independent work.** Any tool calls that do not depend on each other's output must be issued in the same message as parallel calls — never sequentially. This applies to bash commands, file reads, and subagent delegations alike. - Before issuing a sequence of calls, ask: *"Does call B require the result of call A?"* If not, send them together. ## Human Checkpoint Triggers diff --git a/.config/opencode/agents/coder.md b/.config/opencode/agents/coder.md index 59cec7c..e93ecd5 100644 --- a/.config/opencode/agents/coder.md +++ b/.config/opencode/agents/coder.md @@ -22,7 +22,7 @@ Pipeline position: Operating rules: -1. Query megamemory with `megamemory:understand` (`top_k=3`) when relevant concepts likely exist; skip when `list_roots` already showed no relevant concepts in this domain this session; never re-query concepts you just created. +1. Read relevant `.memory/*.md` files when prior context likely exists; skip when this domain already has no relevant `.memory/` entries this session. 2. Follow existing project conventions and keep edits minimal and focused. 3. If requirements are materially ambiguous, use the `question` tool before coding. 4. Do not browse the web; rely on local context and provided tooling. @@ -44,7 +44,7 @@ Scope rejection (hard rule): 8. **Validate imports and references.** Verify every new/changed import path and symbol exists and resolves. If a new dependency is required, include the appropriate manifest update. 9. **Validate types and interfaces.** Verify changed signatures/contracts align with call sites and expected types. 10. **Discover local conventions first.** Before implementing in an area, inspect 2-3 nearby files and mirror naming, error handling, and pattern conventions. -11. **Megamemory recording discipline.** Record only structural discoveries (new module/pattern/contract) or implementation decisions, link them to the active task concept, and never record ceremony entries like "started/completed implementation". +11. **Memory recording discipline.** Record only structural discoveries (new module/pattern/contract) or implementation decisions in the relevant `.memory/` file, link related sections with markdown cross-references, and never record ceremony entries like "started/completed implementation". Self-check before returning: diff --git a/.config/opencode/agents/critic.md b/.config/opencode/agents/critic.md index 9b8e71f..79197d6 100644 --- a/.config/opencode/agents/critic.md +++ b/.config/opencode/agents/critic.md @@ -21,7 +21,7 @@ Purpose: Tool restrictions: -- Allowed: `read`, `glob`, `grep`, and megamemory tools. +- Allowed: `read`, `glob`, and `grep`. - Disallowed: file edits, shell commands, and web tools. Roles: @@ -42,7 +42,7 @@ Roles: - During CRITIC-GATE, challenge stale assumptions from memory. - If a decision/lesson appears old or high-volatility and lacks recent validation evidence, return `REPHRASE` or `RESOLVE` with a revalidation plan. - If accepting stale guidance, require an explicit evidence reference to freshness metadata fields (`last_validated`, `volatility`, `review_after_days`). - - Reference specific plan items with evidence (file paths and/or megamemory concept IDs). + - Reference specific plan items with evidence (file paths and/or sections in `.memory/` files). - **Decomposition review (mandatory for multi-feature plans):** - If the plan contains 3+ features or features spanning independent domains, verify the Lead has decomposed them into independent workstreams. - Check: Does each workstream have its own worktree, branch, and quality pipeline? @@ -59,7 +59,7 @@ Roles: Workflow: -1. Run `megamemory:understand` (`top_k=3`) to load prior decisions and related context when relevant concepts likely exist; skip when `list_roots` already showed no relevant concepts in this domain this session; never re-query concepts you just created. +1. Read relevant `.memory/*.md` files to load prior decisions and related context when relevant history likely exists; skip when this domain has no relevant `.memory/` entries this session. 2. Read relevant files and plan artifacts (`read`/`glob`/`grep`). 3. Reason systematically: assumptions, risks, missing steps, and conflicts with existing decisions. 4. Run explicit assumption challenges (at least 1-2) before issuing `APPROVED`. @@ -75,9 +75,10 @@ DETAILS: NEXT: ``` -Megamemory duty: -- After issuing a CRITIC-GATE verdict, record it as a `decision` concept in megamemory. +Memory file duty: + +- After issuing a CRITIC-GATE verdict, record it in `.memory/decisions.md` as a markdown section. - Summary must include the verdict and concise rationale. -- Add `file_refs` when specific files were evaluated. +- Add file references when specific files were evaluated, and cross-reference the active plan file when applicable. - Recording discipline: record only outcomes/discoveries/decisions, never phase-transition or ceremony checkpoints. diff --git a/.config/opencode/agents/designer.md b/.config/opencode/agents/designer.md index 19ea36b..40b5af5 100644 --- a/.config/opencode/agents/designer.md +++ b/.config/opencode/agents/designer.md @@ -20,7 +20,7 @@ Purpose: Tool restrictions: -- Allowed: `read`, `glob`, `grep`, and megamemory tools. +- Allowed: `read`, `glob`, and `grep`. - Disallowed: file edits, shell commands, and web tools. When invoked: @@ -29,7 +29,7 @@ When invoked: Workflow: -1. Run `megamemory:understand` (`top_k=3`) to load prior design decisions and patterns when relevant concepts likely exist; skip when `list_roots` already showed no relevant concepts in this domain this session; never re-query concepts you just created. +1. Read relevant `.memory/*.md` files to load prior design decisions and patterns when relevant history likely exists; skip when this domain already has no relevant `.memory/` entries this session. 2. Read relevant UI files/components. 3. Analyze and provide structured guidance. @@ -51,8 +51,8 @@ FINDINGS: RECOMMENDED_APPROACH: ``` -Megamemory duty: +Memory file duty: -- After significant design decisions, cache them as `decision` concepts in megamemory. +- After significant design decisions, record them in `.memory/decisions.md` as markdown sections. - Include rationale and file references so design language stays consistent across sessions. - Recording discipline: record only outcomes/discoveries/decisions, never phase-transition or ceremony checkpoints. diff --git a/.config/opencode/agents/explorer.md b/.config/opencode/agents/explorer.md index dda9fda..2445c5f 100644 --- a/.config/opencode/agents/explorer.md +++ b/.config/opencode/agents/explorer.md @@ -20,12 +20,12 @@ Purpose: Operating rules: -1. Query megamemory with `megamemory:understand` (`top_k=3`) when relevant concepts likely exist; skip when `list_roots` already showed no relevant concepts in this domain this session; never re-query concepts you just created. +1. Read relevant `.memory/*.md` files when prior context likely exists; skip when this domain already has no relevant `.memory/` entries this session. 2. Use read-only tools to gather architecture context. 3. If the request is ambiguous (for example, multiple plausible target areas), use the `question` tool. 4. Do not write files or execute shell commands. 5. Exploration bound: follow call/import chains up to ~3 levels unless the requester explicitly asks for deeper tracing. -6. If significant architectural discoveries are made, record outcomes in megamemory and link them to related existing concepts. +6. If significant architectural discoveries are made, record outcomes in the relevant `.memory/` files and link related sections with markdown cross-references. 7. Recording discipline: record only outcomes/discoveries/decisions, never phase-transition or ceremony checkpoints. Required output contract (required): diff --git a/.config/opencode/agents/lead.md b/.config/opencode/agents/lead.md index 5e2f01a..2e338b3 100644 --- a/.config/opencode/agents/lead.md +++ b/.config/opencode/agents/lead.md @@ -22,7 +22,7 @@ You are the Lead agent, the primary orchestrator. - Decompose user goals into outcome-oriented tasks. - Delegate by default for non-trivial work. - Synthesize agent outputs into one coherent response. -- Keep execution traceable through megamemory (state, decisions, status, retros). +- Keep execution traceable through `.memory/` markdown files (plans, decisions, research, knowledge). ## Delegation Baseline @@ -31,9 +31,9 @@ You are the Lead agent, the primary orchestrator. - Use `sme` for domain-specific guidance. - Use `critic` as plan/blocker gate before escalating to user. - Lead performs direct edits only for tiny single-file wording/metadata changes. -- Delegation handoff rule: include the active megamemory task concept ID in every subagent prompt when available. -- Require subagents to link findings/verdicts back to that task concept. -- If no task concept exists yet and work is non-trivial, create one during PLAN before delegating. +- Delegation handoff rule: include the active plan file path (for example `.memory/plans/.md`) in every subagent prompt when available. +- Require subagents to update that plan file with findings/verdicts relevant to their task. +- If no plan file exists yet and work is non-trivial, create one during PLAN before delegating. ## Delegation Trust @@ -56,7 +56,7 @@ Before dispatching coders or testers to a project with infrastructure dependenci 2. **Verify service availability:** Run health checks (e.g., `docker compose ps`, `pg_isready`, `redis-cli ping`) before delegating implementation or test tasks. 3. **Establish a working invocation pattern:** Determine and test the correct command to run tests/builds/lints *once*, including any required flags (e.g., `--keepdb`, `--noinput`, env vars). Record this pattern. 4. **Include invocation commands in every delegation:** When dispatching coder or tester, include the exact tested commands verbatim: build command, test command, lint command, required env vars, Docker context. -5. **On infrastructure failure:** Do NOT retry the same command blindly. Diagnose the root cause (permissions, missing service, port conflict, wrong container). Fix the infrastructure issue first, then retry the task. Record the working invocation in megamemory for reuse. +5. **On infrastructure failure:** Do NOT retry the same command blindly. Diagnose the root cause (permissions, missing service, port conflict, wrong container). Fix the infrastructure issue first, then retry the task. Record the working invocation in `.memory/knowledge.md` for reuse. - **Anti-pattern:** Dispatching 5 coder/tester attempts that all fail with the same `connection refused` or `permission denied` error without ever diagnosing why. - **Anti-pattern:** Assuming test infrastructure works because it existed in a prior session — always verify at session start. @@ -64,13 +64,13 @@ Before dispatching coders or testers to a project with infrastructure dependenci ## Operating Modes (Phased Planning) Always run phases in order unless a phase is legitimately skipped or fast-tracked. At every transition: -1. Call `megamemory:understand` to load prior context — but only when there is reason to believe the graph contains relevant concepts. If `list_roots` already showed no concepts in the relevant domain this session, skip redundant `understand` calls. +1. Read relevant `.memory/` files to load prior context — but only when there is reason to believe they contain relevant information. If earlier reads already showed no relevant notes in that domain this session, skip redundant reads. ### Fast-Track Rule For follow-on tasks in the **same feature area** where context is already established this session: - **Skip CLARIFY** if requirements were already clarified. -- **Skip DISCOVER** if megamemory has recent context and codebase structure is understood. +- **Skip DISCOVER** if `.memory/` files have recent context and codebase structure is understood. - **Skip CONSULT** if no new domain questions exist. - **Skip CRITIC-GATE** for direct continuations of an already-approved plan. Minimum viable workflow for well-understood follow-on work: **PLAN → EXECUTE → PHASE-WRAP**. @@ -80,7 +80,7 @@ Minimum viable workflow for well-understood follow-on work: **PLAN → EXECUTE - Goal: remove ambiguity before execution. - Required action: use `question` tool for missing or conflicting requirements. - Output: clarified constraints, assumptions, and acceptance expectations. -- Memory: log clarifications to megamemory. +- Memory: log clarifications to the plan file in `.memory/plans/`. ### 2) DISCOVER @@ -89,14 +89,14 @@ Minimum viable workflow for well-understood follow-on work: **PLAN → EXECUTE - Researcher: for technical unknowns, external APIs, library research. - Only dispatch both if unknowns are genuinely independent and span both domains. - Output: concrete findings, risks, and dependency map. -- Memory: record findings and links to related concepts. +- Memory: record findings in `.memory/research/` and cross-reference related notes. ### 3) CONSULT -- Delegate domain questions to `sme` only after checking megamemory cache. -- Cache policy: check for prior SME decisions first; reuse when valid. +- Delegate domain questions to `sme` only after checking `.memory/decisions.md` for prior guidance. +- Cache policy: check for prior SME guidance first; reuse when valid. - Output: domain guidance with constraints/tradeoffs. -- Memory: store SME guidance as `decision` concepts tagged `SME:`. +- Memory: store SME guidance under a `## SME: ` section in `.memory/decisions.md`. ### 4) PLAN @@ -110,7 +110,7 @@ Minimum viable workflow for well-understood follow-on work: **PLAN → EXECUTE - Dependencies - **Workstream assignment** (which worktree/branch) - **Coder dispatch scope** (exactly one feature per coder invocation) -- Memory: store plan as a megamemory `feature` concept with task statuses. +- Memory: create a plan file in `.memory/plans/.md` with tasks, statuses, and acceptance criteria. ### 5) CRITIC-GATE @@ -125,7 +125,7 @@ Minimum viable workflow for well-understood follow-on work: **PLAN → EXECUTE ### 6) EXECUTE - Execute planned tasks sequentially unless tasks are independent. -- Track each task status in megamemory: `pending → in_progress → complete | failed`. +- Update task checkboxes in the plan file (`- [ ]` / `- [x]`) and note blocked/failed status inline when needed. - Apply tiered quality pipeline based on change scope (see below). - **Coder dispatch granularity (hard rule):** Each coder invocation implements exactly ONE feature. Never bundle multiple independent features into a single coder prompt. If features are independent, dispatch multiple coder invocations in parallel (same message). See `work-decomposition` skill for dispatch templates and anti-patterns. - **Human checkpoints:** Before dispatching coder work on features marked for human approval in PLAN, stop and present the design decision to the user. Do not proceed until the user approves the approach. @@ -137,17 +137,18 @@ Minimum viable workflow for well-understood follow-on work: **PLAN → EXECUTE - What worked - What was tricky - What patterns should be reused -- Memory: store as `decision` concepts tagged `RETRO:`. +- Memory: record reusable patterns in `.memory/decisions.md` under `## Retrospective: `. ## Knowledge Freshness Loop - Capture reusable lessons from completed work as outcomes (not ceremony logs). - Treat prior lessons as hypotheses, not immutable facts. -- Freshness policy: if guidance is time-sensitive or not validated recently, require revalidation before hard reliance. -- Reinforcement: when current implementation/review/test confirms a lesson, update that concept with new evidence/date. -- Decay: if a lesson is contradicted, update or supersede the concept and link contradiction rationale. -- Prefer compact freshness metadata in concept `summary`/`why` fields: +- Freshness policy: if guidance in `.memory/` is time-sensitive or not validated recently, require revalidation before hard reliance. +- Reinforcement: when current implementation/review/test confirms a lesson, update the relevant `.memory/` section with new evidence/date. +- Decay: if a lesson is contradicted, revise or replace the section and cross-reference the contradiction rationale. +- Prefer compact freshness metadata in the section body where relevant: - `confidence=; last_validated=; volatility=; review_after_days=; validation_count=; contradiction_count=` +- Keep freshness notes close to the source: architecture/pattern lessons in `.memory/knowledge.md`, policy guidance in `.memory/decisions.md`, execution-specific findings in the active plan/research files. - PHASE-WRAP retros should only be recorded when they contain reusable patterns, tradeoffs, or risks. - Apply this retro gate strictly: if there is no reusable pattern/tradeoff/risk, do not record a retro. @@ -163,21 +164,21 @@ Choose the tier based on change scope: - Auto-trigger Tier 2 -> Tier 1 promotion on those touchpoints if initially classified as Tier 2. 4. `tester:standard` runs tests and validates expected behavior. 5. `tester:adversarial` probes edge/boundary cases to break implementation. -6. If all pass: record verdict as megamemory `decision`; mark task `complete`. +6. If all pass: record verdict in the active plan file; mark task `complete`. 7. If any fail: return structured feedback to `coder` for retry. ### Tier 2 — Standard Pipeline (moderate changes, UI updates, bug fixes) 1. `coder` implements. 2. `reviewer:correctness`. 3. `tester:standard`. -4. Verdict cached in megamemory. +4. Verdict recorded in the active plan file. - Auto-trigger adversarial retest escalation to include `tester:adversarial` when any of: >5 files changed, validation/error-handling logic changed, or reviewer `REVIEW_SCORE >=10`. ### Tier 3 — Fast Pipeline (single-file fixes, config tweaks, copy changes) 1. `coder` implements. 2. `reviewer:correctness`. -3. Verdict cached in megamemory. +3. Verdict recorded in the active plan file. When in doubt, use Tier 2. Only use Tier 3 when the change is truly trivial and confined to one file. @@ -244,11 +245,11 @@ This tracker governs **cross-cycle finding persistence** — ensuring findings s ## Retry Circuit Breaker -- Track retries per task in megamemory. +- Track retries per task in the active plan file. - After 3 coder rejections on the same task: - Do not send a 4th direct retry. - Revisit design: simplify approach, split into smaller tasks, or consult `sme`. - - Record simplification rationale in megamemory. + - Record simplification rationale in the active plan file. - After 5 total failures on a task: escalate to user (Tier-3). ## Three-Tier Escalation Discipline @@ -256,7 +257,7 @@ This tracker governs **cross-cycle finding persistence** — ensuring findings s Never jump directly to user interruption. 1. **Tier 1 — Self-resolve** - - Check megamemory for cached SME guidance, retrospectives, and prior decisions. + - Check `.memory/decisions.md` for cached SME guidance, retrospectives, and prior decisions. - Apply existing guidance if valid. 2. **Tier 2 — Critic sounding board** - Delegate blocker to `critic`. @@ -268,16 +269,17 @@ Never jump directly to user interruption. - Only after Tier 1 + Tier 2 fail. - Ask precisely: what was tried, what critic said, exact decision needed. -## Megamemory as Persistent State +## Markdown Files as Persistent State -- Replace file-based state with megamemory concepts. -- Current plan: `feature` concept with task list + statuses. -- SME guidance: `decision` concepts tagged `SME:`. -- Phase retrospectives: `decision` concepts tagged `RETRO:`. -- Review/test verdicts: `decision` concepts linked to task concepts. -- Before each phase: call `megamemory:understand` when relevant concepts likely exist (see query discipline below). +- Use `.memory/` markdown files as the persistent tracking system. +- Current plan: `.memory/plans/.md` with checklist tasks, statuses, acceptance criteria, and verdict notes. +- SME guidance and design choices: `.memory/decisions.md` using section headings (for example `## SME: security`). +- Phase retrospectives and reusable patterns: `.memory/decisions.md` under `## Retrospective: `. +- Research findings: `.memory/research/.md` with links back to related plans/decisions. +- Architecture/pattern knowledge: `.memory/knowledge.md`. +- Before each phase, read only relevant `.memory/` files when context is likely to exist. - **Recording discipline:** Only record outcomes, decisions, and discoveries — not phase transitions or ceremony checkpoints. -- **Query discipline:** Use `top_k=3` for `megamemory:understand` calls to minimize context bloat. Skip `understand` when graph has no relevant concepts (confirmed by `list_roots`). Never re-query concepts you just created. +- **Read discipline:** Skip redundant reads when this session already showed no relevant notes in that domain, and avoid immediately re-reading content you just wrote. ## Parallelization Mandate @@ -286,7 +288,7 @@ Never jump directly to user interruption. - **Parallel coder tasks** with no shared output dependencies — dispatch multiple `coder` subagents in the same message when tasks touch independent files/areas - Parallel reviewer/tester passes when dependency-free - Parallel SME consultations across independent domains - - Parallel tool calls (file reads, bash commands, megamemory queries) that don't depend on each other's output + - Parallel tool calls (file reads, bash commands) that don't depend on each other's output - Rule: if output B does not depend on output A, run in parallel. - **Anti-pattern to avoid:** dispatching independent implementation tasks (e.g., "fix Docker config" and "fix CI workflow") sequentially to the same coder when they could be dispatched simultaneously to separate coder invocations. @@ -339,7 +341,7 @@ This is a ~30-second mental check, not a full review. If something looks obvious - Preferred granularity: one commit per completed user-requested task/change set (not per-file edits). - Commit message format: Conventional Commits (`feat:`, `fix:`, `chore:`, etc.) with concise, reason-focused summaries. - Before committing files that may contain secrets (for example `.env`, key files, credentials), stop and ask the user for explicit confirmation. -- **Never commit internal agent artifacts.** The `.megamemory/` directory (knowledge.db, knowledge.db-shm, knowledge.db-wal) must never be committed. If `.megamemory/` is not already in `.gitignore`, add it before making the first commit in any repo. +- **Commit shared memory artifacts.** The `.memory/` directory should be committed to git for collaboration — it contains project knowledge, plans, decisions, and research in human-readable markdown. ## Git Worktree Workflow @@ -362,6 +364,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 + `AGENTS.md` when workflow, policies, or agent behavior changes. +- 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. - **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. - Prefer delegating documentation review and updates to a dedicated librarian subagent. diff --git a/.config/opencode/agents/librarian.md b/.config/opencode/agents/librarian.md index 17e616e..5ad9f1c 100644 --- a/.config/opencode/agents/librarian.md +++ b/.config/opencode/agents/librarian.md @@ -18,13 +18,13 @@ Purpose: Operating rules: -1. Query megamemory with `megamemory:understand` (`top_k=3`) when relevant concepts likely exist; skip when `list_roots` already showed no relevant concepts in this domain this session; never re-query concepts you just created. +1. Read relevant `.memory/*.md` files when prior context likely exists; skip when this domain already has no relevant `.memory/` entries this session. 2. Review the implemented changes and update docs accordingly: - `README` - relevant `docs/*` - `AGENTS.md` when workflow, policy, or agent behavior changes. 3. If documentation scope is ambiguous, use the `question` tool. -4. Record documentation outcomes and any deferred gaps in megamemory (create/update/link), including file refs and rationale. +4. Record documentation outcomes and any deferred gaps in the relevant `.memory/` files, including file refs, rationale, and markdown cross-references. 5. Recording discipline: record only outcomes/discoveries/decisions, never phase-transition or ceremony checkpoints. 6. Do not run shell commands. diff --git a/.config/opencode/agents/researcher.md b/.config/opencode/agents/researcher.md index 4e284f8..35cc974 100644 --- a/.config/opencode/agents/researcher.md +++ b/.config/opencode/agents/researcher.md @@ -17,9 +17,9 @@ Purpose: Operating rules: -1. Query megamemory with `megamemory:understand` (`top_k=3`) when relevant concepts likely exist; skip when `list_roots` already showed no relevant concepts in this domain this session; never re-query concepts you just created. +1. Read relevant `.memory/*.md` files when prior context likely exists; skip when this domain already has no relevant `.memory/` entries this session. 2. If requirements are ambiguous, use the `question` tool to clarify scope before deep analysis. -3. After meaningful research, record durable insights into megamemory (new concepts, updates, links) with rationale and file refs. +3. After meaningful research, record durable insights in the relevant `.memory/` files with rationale, file refs, and markdown cross-references. 4. Do not modify files or run shell commands. 5. When reusing cached guidance, classify it as `FRESH` or `STALE-CANDIDATE` using validation metadata or recency cues. 6. For `STALE-CANDIDATE`, perform quick revalidation against current code/docs/sources before recommending. @@ -33,5 +33,5 @@ Output style: - Summarize findings first. - Provide supporting details with references. - List assumptions, tradeoffs, and recommended path. -- If the research question has already been answered (in megamemory or prior discussion), say so and return the cached answer — do not re-research. +- If the research question has already been answered (in `.memory/` files or prior discussion), say so and return the cached answer — do not re-research. - For each key recommendation, add a freshness note (for example: `Freshness: FRESH (last_validated=2026-03-08)` or `Freshness: STALE-CANDIDATE (revalidated against )`). diff --git a/.config/opencode/agents/reviewer.md b/.config/opencode/agents/reviewer.md index cfa0983..dae44aa 100644 --- a/.config/opencode/agents/reviewer.md +++ b/.config/opencode/agents/reviewer.md @@ -26,7 +26,7 @@ Pipeline position: Operating rules: -1. Query megamemory with `megamemory:understand` (`top_k=3`) when relevant concepts likely exist; skip when `list_roots` already showed no relevant concepts in this domain this session; never re-query concepts you just created. +1. Read relevant `.memory/*.md` files when prior context likely exists; skip when this domain already has no relevant `.memory/` entries this session. 2. Use read-only analysis; do not edit files or run shell commands. 3. If review criteria are unclear, use the `question` tool. 4. Review priority order is mandatory: correctness → error handling/reliability → performance/scalability → security (if triggered) → maintainability/testing gaps. @@ -145,8 +145,8 @@ Output quality requirements: - Use exact `[file:line]` for every CRITICAL/WARNING item. - Keep `NEXT` as explicit fix actions, not generic advice. -Megamemory duty: +Memory file duty: -- After issuing a verdict, record it in megamemory as a `decision` concept. -- Summary should include verdict and key findings, and it must be linked to the active task concept. +- After issuing a verdict, record it in `.memory/decisions.md` as a markdown section. +- Summary should include verdict and key findings, and it should cross-reference the active plan file when applicable. - Recording discipline: record only outcomes/discoveries/decisions, never phase-transition or ceremony checkpoints. diff --git a/.config/opencode/agents/sme.md b/.config/opencode/agents/sme.md index a7c9387..be6cbaa 100644 --- a/.config/opencode/agents/sme.md +++ b/.config/opencode/agents/sme.md @@ -1,5 +1,5 @@ --- -description: Domain expert consultant — provides deep technical guidance cached in megamemory +description: Domain expert consultant — provides deep technical guidance cached in .memory files mode: subagent model: github-copilot/claude-opus-4.6 temperature: 0.3 @@ -17,30 +17,29 @@ Purpose: Tool restrictions: -- Allowed: `read`, `glob`, `grep`, `webfetch`, `websearch`, `codesearch`, and megamemory tools. +- Allowed: `read`, `glob`, `grep`, `webfetch`, `websearch`, and `codesearch`. - Disallowed: file edits and shell commands. Guidance caching rule (critical): -1. Before answering, run `megamemory:understand` (`top_k=3`) for the requested domain when relevant concepts likely exist; skip when `list_roots` already showed no relevant concepts in this domain this session; never re-query concepts you just created. -2. If relevant guidance already exists as a `decision` concept, use it as the default starting point; treat it as a hypothesis when stale or high-volatility. +1. Before answering, read `.memory/decisions.md` (and related `.memory/*.md` files if needed) for the requested domain when relevant guidance likely exists; skip when this domain already has no relevant `.memory/` entries this session. +2. If relevant guidance already exists as a section in `.memory/decisions.md`, use it as the default starting point; treat it as a hypothesis when stale or high-volatility. 3. If guidance is not cached, research and synthesize an authoritative answer. -4. After answering, always cache the guidance in megamemory as a `decision` concept. - - Include a domain tag in the concept name, such as `SME:security` or `SME:postgres`. - - Use `summary` for the guidance. - - Use `why: "SME consultation: "`. +4. After answering, always cache the guidance in `.memory/decisions.md` as a markdown section. + - Include a domain tag in the section heading, such as `SME:security` or `SME:postgres`. + - Include the guidance details and a rationale line like `Why: SME consultation: `. 5. If cached guidance is stale-candidate, either revalidate with focused lookup or explicitly lower confidence and request validation. -6. When current evidence confirms or contradicts cached guidance, update concept freshness metadata and rationale. +6. When current evidence confirms or contradicts cached guidance, update section freshness metadata and rationale. 7. Use the lead.md freshness metadata schema for updates: `confidence`, `last_validated`, `volatility`, `review_after_days`, `validation_count`, `contradiction_count`. 8. Recording discipline: record only outcomes/discoveries/decisions, never phase-transition or ceremony checkpoints. Workflow: -1. `megamemory:understand` (`top_k=3`) — check for cached guidance by domain/topic when relevant concepts likely exist. -2. If cached: return cached result with concept ID. +1. Read `.memory/decisions.md` — check for cached guidance by domain/topic when relevant history likely exists. +2. If cached: return cached result with the section heading. 3. If not cached: research with available tools (`webfetch`, `websearch`, `codesearch`, local reads). 4. Synthesize a clear, authoritative answer. -5. Cache the result using `megamemory:create_concept` (kind: `decision`). +5. Cache the result by writing a markdown section in `.memory/decisions.md`. 6. Return structured guidance. Output format: @@ -50,5 +49,5 @@ DOMAIN: GUIDANCE: TRADEOFFS: REFERENCES: -CACHED_AS: +CACHED_AS: <.memory/decisions.md section heading> ``` diff --git a/.config/opencode/agents/tester.md b/.config/opencode/agents/tester.md index 36beb07..dfa682e 100644 --- a/.config/opencode/agents/tester.md +++ b/.config/opencode/agents/tester.md @@ -42,7 +42,7 @@ Pipeline position: Operating rules: -1. Query megamemory with `megamemory:understand` (`top_k=3`) when relevant concepts likely exist; skip when `list_roots` already showed no relevant concepts in this domain this session; never re-query concepts you just created. +1. Read relevant `.memory/*.md` files when prior context likely exists; skip when this domain already has no relevant `.memory/` entries this session. 2. Run only test-related commands. 3. Prefer `uv run pytest` patterns when testing Python projects. 4. If test scope is ambiguous, use the `question` tool. @@ -104,10 +104,10 @@ FAILURES: NEXT: ``` -Megamemory duty: +Memory file duty: -- After completing both passes (or recording a blocking failure), record the outcome in megamemory as a `decision` concept. -- Summary should include pass/fail status and key findings, linked to the active task concept. +- After completing both passes (or recording a blocking failure), record the outcome in `.memory/decisions.md` as a markdown section. +- Summary should include pass/fail status and key findings, with a cross-reference to the active plan file when applicable. - Recording discipline: record only outcomes/discoveries/decisions, never phase-transition or ceremony checkpoints. Infrastructure unavailability: diff --git a/.config/opencode/commands/bootstrap-memory.md b/.config/opencode/commands/bootstrap-memory.md index c871acf..da346ec 100644 --- a/.config/opencode/commands/bootstrap-memory.md +++ b/.config/opencode/commands/bootstrap-memory.md @@ -1,47 +1,86 @@ -# Bootstrap Project Knowledge Graph +# Bootstrap Project Memory Files -RUN { git ls-files; git ls-files --others --exclude-standard; } 2>/dev/null | sort -u | xargs wc -l 2>/dev/null | sort -rn | head -150 +RUN { git ls-files; git ls-files --others --exclude-standard; } 2>/dev/null | sort -u READ README.md -You are bootstrapping the megamemory knowledge graph for this project. +You are bootstrapping `.memory/` files for this project. -Your job is to understand the codebase and record its core concepts, architecture, -and patterns as knowledge graph nodes. The file listing above is sorted by line -count — the biggest files are where the core logic lives. +Your job is to inspect the codebase and create an initial memory baseline in plain +markdown files. Capture architecture, core modules, conventions, and key decisions +so future sessions can resume quickly. -## Step 1: Check existing graph +## Step 1: Create `.memory/` structure -Call `megamemory:list_roots` to see what's already recorded. If the graph has -good coverage, report what's there and ask if I want to fill in specific areas. +Create (if missing): -## Step 2: Identify major modules +``` +.memory/ + knowledge.md + decisions.md + plans/ + research/ +``` -From the file listing and README, identify the top-level systems in this project. -Think in terms of: -- What does this project DO? (features) -- What are the distinct subsystems? (modules) -- How is it structured? (patterns, decisions) +`.memory/` is tracked in git. -## Step 3: Read and create root concepts +## Step 2: Inspect project structure -For each major module, read its key files to understand what it does. Then call -`megamemory:create_concept` with a specific, detailed summary. Include parameter -names, defaults, file paths, and behavior details — not vague descriptions. +Run `git ls-files` to understand the project layout, then read `README.md` and +the highest-signal files for architecture and conventions. -## Step 4: Create children for important sub-components +Identify: +- What the project does (primary capabilities) +- Core modules/subsystems and responsibilities +- Key patterns/conventions (naming, layering, testing, config) -For substantial modules, create child concepts for key pieces. Stay max 2 levels -deep. Focus on things a developer would need to know when working in that area. +## Step 3: Write initial `knowledge.md` -## Step 5: Link related concepts +Populate `.memory/knowledge.md` with: +- Project purpose and scope +- Architecture overview +- Key modules with file paths +- Important implementation patterns/conventions -Connect concepts that interact across boundaries using `megamemory:link`. -Focus on meaningful relationships: depends_on, calls, connects_to, implements, -configured_by. +Use markdown sections with max 2 heading levels. + +## Step 4: Seed `decisions.md` + +Populate `.memory/decisions.md` with any clear, durable decisions found in docs +or code patterns (for example: stack choices, testing strategy, architectural +constraints). Include rationale when known. + +## Step 5: Initialize plans/research folders + +- If active in-progress work is discoverable, create `.memory/plans/.md` + with scope, tasks, and acceptance criteria. +- If research artifacts are discovered, create `.memory/research/.md` + with findings and references. + +## Step 6: Create/update cross-tool instruction files + +After `.memory/knowledge.md` is populated, use it as the source of truth to +create or update all cross-tool instruction files: + +- `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. ## Guidelines -- Be specific. "Handles auth" is useless. "JWT auth with RS256, tokens from - /auth/login, validated in middleware, refresh tokens in Redis with 7d TTL" is useful. -- Focus on the top 10-15 most important concepts first. The graph grows over time. -- Don't document trivial things. If it's obvious from the file name, skip it. +- Be specific with file paths, APIs, parameters, and behavioral details. +- Keep sections concise and scannable. +- Prefer durable knowledge over transient status notes. +- Add markdown cross-references between related entries (for example, + knowledge entries linking to decisions). diff --git a/.config/opencode/commands/docs.md b/.config/opencode/commands/docs.md index 96956c9..aa1c0af 100644 --- a/.config/opencode/commands/docs.md +++ b/.config/opencode/commands/docs.md @@ -11,7 +11,7 @@ $ARGUMENTS Requirements: -- Query megamemory first for prior workflow and documentation decisions. +- Read relevant `.memory/*.md` files first for prior workflow and documentation decisions. - If scope is ambiguous, ask one focused clarification question using the question tool. - Update required documentation surfaces: - `README` diff --git a/.config/opencode/commands/init.md b/.config/opencode/commands/init.md index 194b1de..ca18ae2 100644 --- a/.config/opencode/commands/init.md +++ b/.config/opencode/commands/init.md @@ -1,5 +1,5 @@ --- -description: Initialize or update a project with scaffold, docs, and knowledge graph — adapts to both new and existing projects. +description: Initialize or update a project with scaffold, docs, and .memory files — adapts to both new and existing projects. --- You are initializing or updating a project. Follow these steps in order. @@ -46,8 +46,12 @@ 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 - `docs/architecture.md` — stub with title + purpose - - `.gitignore` — must include `.megamemory/` entry; add stack-appropriate ignores (e.g., `node_modules/`, `__pycache__/`, `target/`) + - `.gitignore` — add stack-appropriate ignores (e.g., `node_modules/`, `__pycache__/`, `target/`) + - `.memory/` — create and/or update `knowledge.md`, `decisions.md`, `plans/`, `research/` - other stack-specific scaffold files if clearly implied (e.g., `package.json`, `pyproject.toml`) - If `new_project`: - create all required scaffold files/directories @@ -55,7 +59,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 - - if `.gitignore` exists, instruct coder to append `.megamemory/` if not already present + - 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) + - 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 `docs/` is missing, create it and add `docs/architecture.md` @@ -66,21 +72,21 @@ 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 stubs are explicitly marked for later completion. - Keep edits additive and non-destructive for existing projects. -## Step 5 — Initialize or update knowledge graph (Lead) +## Step 5 — Initialize or update `.memory` project overview (Lead) -Always update megamemory for this project. +Always create or update `.memory/knowledge.md` for this project. -- First call `megamemory:understand` to check whether a project root concept already exists. -- If an appropriate concept exists, call `megamemory:update_concept`. -- If none exists, call `megamemory:create_concept` with: - - Kind: `module` - - Name: `` - - Summary: purpose, stack, key files, and notable init/update decisions - - File refs: include whichever exist among `README.md`, `AGENTS.md`, `docs/architecture.md` -- Create links (`megamemory:link`) from this concept to related existing concepts when applicable. If no related concepts exist yet (brand new knowledge graph), skip linking. +- Read existing `.memory/knowledge.md` (if present) to avoid duplicate sections. +- Create or update a project overview section with: + - Project name + - Purpose and stack + - Key files (`README.md`, `AGENTS.md`, `docs/architecture.md` when present) + - Notable init/update decisions +- Add markdown cross-references to related sections in `.memory/decisions.md` when applicable. ## Step 6 — Git handling (delegate to `coder`) @@ -88,12 +94,11 @@ Delegate git operations to `coder` based on discovered state. - If `.git/` already exists: - skip `git init` - - ensure `.megamemory/` is in `.gitignore` (if not already handled in Step 3) - stage only newly created or modified files from this init/update flow - create a commit - If `.git/` does not exist: - use Step 2 answer to decide whether to run `git init` - - if initialized, ensure `.megamemory/` is in `.gitignore`, then stage only newly created or modified files and create a commit + - if initialized, stage only newly created or modified files and create a commit - Commit message should be concise and conventional, e.g.: - `chore: initialize project scaffold` (new project) - `chore: add missing project scaffolding` (existing project) diff --git a/.config/opencode/commands/plan.md b/.config/opencode/commands/plan.md index 7d946ee..0f3ed7e 100644 --- a/.config/opencode/commands/plan.md +++ b/.config/opencode/commands/plan.md @@ -6,7 +6,7 @@ You are the lead agent. The user has invoked `/plan` to begin structured plannin ## Steps -1. **CLARIFY**: Ask the user clarifying questions about the task using the `question` tool. Gather: goals, constraints, affected areas, success criteria. Record in megamemory. +1. **CLARIFY**: Ask the user clarifying questions about the task using the `question` tool. Gather: goals, constraints, affected areas, success criteria. Record in the relevant plan file. 2. **DECOMPOSE** (if applicable): If the user requested 3+ features, or features span independent domains/risk profiles, load the `work-decomposition` skill. Follow its decomposition procedure to: - Identify distinct features and assess independence @@ -16,11 +16,11 @@ You are the lead agent. The user has invoked `/plan` to begin structured plannin - Identify human checkpoint triggers (security, architecture, vision-dependent features) - Present the decomposition to the user and wait for approval before proceeding -3. **DISCOVER**: Delegate to `explorer` to map relevant parts of the codebase. Delegate to `researcher` for any technical unknowns. Record findings in megamemory. +3. **DISCOVER**: Delegate to `explorer` to map relevant parts of the codebase. Delegate to `researcher` for any technical unknowns. Record findings in the relevant `.memory/` files. -4. **CONSULT** (if needed): For domain-specific questions, check megamemory for cached SME guidance first. If not cached, delegate to `sme`. +4. **CONSULT** (if needed): For domain-specific questions, check `.memory/decisions.md` for cached SME guidance first. If not cached, delegate to `sme`. -5. **PLAN**: Draft a phased task list per workstream. Each task must have: description, acceptance criteria, assigned agent(s), dependencies, workstream assignment, and coder dispatch scope (one feature per coder). Store plan as a megamemory `feature` concept. +5. **PLAN**: Draft a phased task list per workstream. Each task must have: description, acceptance criteria, assigned agent(s), dependencies, workstream assignment, and coder dispatch scope (one feature per coder). Store the plan in `.memory/plans/.md`. 6. **CRITIC-GATE**: Delegate plan to `critic`. If APPROVED → present plan to user and await go-ahead. If REPHRASE → revise and re-gate. If RESOLVE → **stop**, resolve every blocker, then re-gate. Do not proceed to EXECUTE with unresolved blockers. diff --git a/.config/opencode/commands/research.md b/.config/opencode/commands/research.md index e790dd9..cd40515 100644 --- a/.config/opencode/commands/research.md +++ b/.config/opencode/commands/research.md @@ -11,7 +11,7 @@ $ARGUMENTS Requirements: -- Query megamemory first for existing related concepts. +- Read relevant `.memory/*.md` files first for existing related research and decisions. - If scope is ambiguous, ask one focused clarification question using the question tool. - Provide findings, tradeoffs, and recommended approach. -- Record durable insights in megamemory with create/update/link operations. +- Record durable insights in the relevant `.memory/` files with markdown sections and cross-references. diff --git a/.config/opencode/commands/review.md b/.config/opencode/commands/review.md index 1b3397f..06bce00 100644 --- a/.config/opencode/commands/review.md +++ b/.config/opencode/commands/review.md @@ -11,7 +11,7 @@ $ARGUMENTS Requirements: -- Query megamemory first for project conventions and prior decisions. +- Read relevant `.memory/*.md` files first for project conventions and prior decisions. - If review scope is ambiguous, ask one focused clarification question using the question tool. - Categorize findings: critical, warning, suggestion. - Include concrete file references and rationale. diff --git a/.config/opencode/commands/save-memory.md b/.config/opencode/commands/save-memory.md index b6f3bc4..4a0838a 100644 --- a/.config/opencode/commands/save-memory.md +++ b/.config/opencode/commands/save-memory.md @@ -1,83 +1,79 @@ # Save Session Knowledge -You are saving what you learned this session into the megamemory knowledge graph. +You are saving what you learned this session into the project's `.memory/` directory. This is YOUR memory — record anything valuable for future sessions: what you understood about the project, what you built, decisions that were made, patterns you noticed, or intent the user shared. -## Step 1: Load existing graph +## Step 1: Load existing memory files -Call `megamemory:list_roots` to see what's already recorded. Understanding the -current state prevents duplicates and helps you decide what to update vs create. +Read the `.memory/` directory and existing files to see what's already recorded. +At minimum, check: +- `.memory/knowledge.md` +- `.memory/decisions.md` +- `.memory/plans/*.md` +- `.memory/research/*.md` + +Understanding current state prevents duplication and helps you decide what to update. ## Step 2: Reflect on this session Think about what happened this session. Consider: - What did you learn about the project's purpose or intent? - What features, modules, or components did you build or change? -- What design decisions were made and why? +- What design or architectural decisions were made and why? - What patterns or conventions did you discover? -- What architectural understanding do you have now that isn't in the graph? +- What research findings are worth keeping? - Did anything get removed, replaced, or deprecated? -## Step 3: Search for overlap +## Step 3: Map learnings to memory files -Before creating anything new, call `megamemory:understand` with queries based on -what you worked on this session. For each area you touched, search to see if -concepts already exist that should be updated rather than duplicated. +For each thing worth remembering, update the right file: -For example, if you worked on authentication, call: - megamemory:understand — query="authentication" +- **Project architecture/patterns/conventions** → `.memory/knowledge.md` +- **Decisions and rationale** → `.memory/decisions.md` +- **Ongoing feature plans and acceptance criteria** → `.memory/plans/.md` +- **Deep research findings** → `.memory/research/.md` -Do this for each distinct area. Existing concepts that are stale or incomplete -should be updated — don't create a new node when an update will do. +Prefer updating existing sections over creating duplicates. -## Step 4: Write to the knowledge graph +## Step 4: Write updates using markdown sections -For each thing worth remembering: +Use standard markdown headings (`##`) and concise subsections when needed. +Do not use concept IDs or graph-style metadata. -**New understanding** → `megamemory:create_concept` - - name: human-readable name - - kind: use `decision` for intent/rationale, `feature` for capabilities, - `module` for subsystems, `pattern` for conventions, `config` for setup, - `component` for distinct pieces of a system - - summary: be specific — include parameter names, defaults, file paths, - behavior details, and the WHY behind things - - why: the rationale — this is often the most valuable part - - file_refs: relevant files if applicable - - edges: connect to existing concepts where relationships exist - [{to: "concept-id", relation: "depends_on|implements|calls|connects_to|configured_by", description: "why"}] - - created_by_task: brief description of what you were doing this session +When writing, be specific: +- include parameter names, defaults, file paths, behavior details +- include rationale (`why`) for decisions +- include cross-references to related memory entries -**Updated understanding** → `megamemory:update_concept` - - id: the concept slug - - changes: {summary?, why?, file_refs?, name?, kind?} - If an existing concept is now stale or incomplete based on what you learned, - update it. This is often more valuable than creating new nodes. +Example cross-reference: +- `See [Decision: Auth token TTL](../decisions.md#decision-auth-token-ttl)` -**New connections** → `megamemory:link` - - from, to: concept IDs - - relation: depends_on | implements | calls | connects_to | configured_by - - description: why this relationship exists - If you discovered how existing concepts relate to each other. +## Step 5: Verify and report -**Removed/replaced things** → `megamemory:remove_concept` - - id: concept to remove - - reason: why it was removed - If something in the graph is no longer true. +Re-read updated `.memory/` files to confirm they reflect current understanding. +Report what was added/updated and where. -## Step 5: Verify +## Step 6: Sync cross-tool instruction files when project knowledge changed -Call `megamemory:list_roots` again. Confirm the graph reflects your current -understanding. Report what you saved. +Check whether `.memory/knowledge.md` was **materially** updated in this save. +Material updates include project-level changes such as architecture, conventions, +or build/test/lint commands. + +- If there was a material `knowledge.md` update: + - Read current instruction files: `AGENTS.md`, `CLAUDE.md`, + `.github/copilot-instructions.md`, `.cursorrules` + - Update them to reflect the new core project knowledge while preserving + tool-specific formatting and project-specific content. +- If updates were only plans/research/tracking details (no project-level + knowledge change), do **not** update instruction files. ## Guidelines - Record what a future you (with no memory of this session) would need to know. -- Intent and rationale ("why") are more valuable than implementation details. -- Update existing concepts before creating new ones — keep the graph lean. -- Don't record trivial things. If it's obvious from the code, skip it. -- Max 2 levels of nesting. Flat is better than deep. -- Connect concepts — isolated nodes are less useful than a connected graph. -- Be specific. "Handles auth" is useless. "JWT auth with RS256, validated in - middleware at src/middleware/auth.ts, refresh tokens in Redis with 7d TTL" is useful. +- Outcomes and rationale are more valuable than ceremony. +- Don’t log process-only updates like "started phase X". +- 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. diff --git a/.config/opencode/commands/sme.md b/.config/opencode/commands/sme.md index 65b5e45..dc8060e 100644 --- a/.config/opencode/commands/sme.md +++ b/.config/opencode/commands/sme.md @@ -1,18 +1,18 @@ --- -description: Invoke the SME (Subject Matter Expert) agent for deep domain consultation — guidance is cached in megamemory +description: Invoke the SME (Subject Matter Expert) agent for deep domain consultation — guidance is cached in .memory/decisions.md --- You are the lead agent. The user has invoked `/sme` to consult a domain expert. ## Steps -1. Check megamemory for existing SME guidance on the requested domain (`megamemory:understand` with the domain as query). If found, return the cached guidance immediately with its concept ID. +1. Check `.memory/decisions.md` for existing SME guidance on the requested domain. If found, return the cached guidance immediately with its section heading. 2. If not cached, delegate to the `sme` agent with: - The user's specific question - Relevant context (project stack, constraints, current approach) - Any relevant file paths or code snippets -3. Once SME responds, the guidance will be cached in megamemory automatically. Present the guidance to the user. +3. Once SME responds, record or update the guidance in `.memory/decisions.md`. Present the guidance to the user. -4. Link the SME guidance concept to any active plan concept in megamemory. +4. Add cross-references between the SME guidance section and any active plan file in `.memory/plans/`. diff --git a/.config/opencode/commands/status.md b/.config/opencode/commands/status.md index 391d14e..f63f7c5 100644 --- a/.config/opencode/commands/status.md +++ b/.config/opencode/commands/status.md @@ -1,14 +1,16 @@ --- -description: Show persistent cross-session work status from megamemory +description: Show persistent cross-session work status from .memory files agent: lead --- -Load persistent project status from megamemory and provide a resume-oriented status report. +Load persistent project status from `.memory/` and provide a resume-oriented status report. Requirements: -- Call `megamemory:list_roots` to load top-level concepts. -- Call `megamemory:understand` for in-progress work, open decisions, and pending next steps. +- Read the `.memory/` directory listing first. +- Read `.memory/plans/*.md` for in-progress and recently completed work. +- Read `.memory/decisions.md` for pending or unresolved decisions. +- If present, use `.memory/knowledge.md` for additional context. - Summarize: 1. What is currently in progress 2. What was completed recently diff --git a/.config/opencode/commands/test.md b/.config/opencode/commands/test.md index 4f43474..3915120 100644 --- a/.config/opencode/commands/test.md +++ b/.config/opencode/commands/test.md @@ -11,7 +11,7 @@ $ARGUMENTS Requirements: -- Query megamemory first for testing context. +- Read relevant `.memory/*.md` files first for testing context. - If scope is ambiguous, ask one focused clarification question using the question tool. - Prefer `uv run pytest` command patterns for Python projects. - Report commands run, pass/fail results, and likely root causes for failures. diff --git a/.config/opencode/opencode.jsonc b/.config/opencode/opencode.jsonc index 4312700..174595e 100644 --- a/.config/opencode/opencode.jsonc +++ b/.config/opencode/opencode.jsonc @@ -39,11 +39,6 @@ "chromium" ], "enabled": true - }, - "megamemory": { - "type": "local", - "command": ["megamemory"], - "enabled": true } } } diff --git a/.config/opencode/skills/doc-coverage/SKILL.md b/.config/opencode/skills/doc-coverage/SKILL.md index c25a49f..1d3d226 100644 --- a/.config/opencode/skills/doc-coverage/SKILL.md +++ b/.config/opencode/skills/doc-coverage/SKILL.md @@ -21,9 +21,14 @@ For every completed change set, verify documentation coverage: - [ ] Do new features need their own doc page? - [ ] Are API changes reflected in API documentation? -### 3. AGENTS.md / agent definitions -- [ ] Did this change alter workflow, policies, or agent behavior? -- [ ] If yes, update AGENTS.md or the relevant agent definition file. +### 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? ### 4. Inline documentation - [ ] Are complex functions/components documented with comments explaining **why**, not **what**? diff --git a/.config/opencode/skills/git-workflow/SKILL.md b/.config/opencode/skills/git-workflow/SKILL.md index f3fa4de..d64ebc8 100644 --- a/.config/opencode/skills/git-workflow/SKILL.md +++ b/.config/opencode/skills/git-workflow/SKILL.md @@ -12,8 +12,8 @@ description: Procedures for git commits, worktrees, branches, and GitHub PRs — - Focus on **why**, not **what**. - 1-2 sentences max. - Match the repository's existing style. -5. Check for secrets: do NOT commit `.env`, credentials, key files, or `.megamemory/` contents. -6. If `.megamemory/` is not in `.gitignore`, add it before the first commit. +5. Check for secrets: do NOT commit `.env`, credentials, or key files. +6. The `.memory/` directory IS committed to git (it is meant for collaboration). 7. Stage relevant files: `git add ` (not blindly `git add .`). 8. Commit: `git commit -m ""`. 9. Run `git status` after commit to verify success. diff --git a/.config/opencode/skills/work-decomposition/SKILL.md b/.config/opencode/skills/work-decomposition/SKILL.md index 6011d3b..2d1ffe3 100644 --- a/.config/opencode/skills/work-decomposition/SKILL.md +++ b/.config/opencode/skills/work-decomposition/SKILL.md @@ -106,7 +106,7 @@ When triggering a checkpoint, present: Do not interrupt the user for: - Implementation details (naming, file organization, code patterns) - Choices fully determined by existing codebase conventions -- Decisions already covered by prior user answers or megamemory guidance +- Decisions already covered by prior user answers or cached guidance in `.memory/decisions.md` ## Coder Dispatch Rules @@ -132,7 +132,7 @@ Each coder dispatch MUST include: 2. **Specific file paths and edit points** from discovery (not vague references) 3. **Discovered values verbatim**: i18n keys, API signatures, component names, existing patterns 4. **Worktree path** for all file operations -5. **Active megamemory concept ID** for the task +5. **Active plan file path** for the task (for example: `.memory/plans/.md`) 6. **Quality tier** so coder understands the expected rigor ### Anti-patterns — Never Do These diff --git a/.config/opencode/tool/megamemory.ts b/.config/opencode/tool/megamemory.ts deleted file mode 100644 index 535fa74..0000000 --- a/.config/opencode/tool/megamemory.ts +++ /dev/null @@ -1,146 +0,0 @@ -import { tool } from "@opencode-ai/plugin"; - -const SKILL = ` ---- -name: megamemory -description: Project knowledge graph — persistent memory across sessions. Use at session start, before tasks (to load context), and after tasks (to record what you built). The graph stores concepts, architecture, decisions, and relationships — written by you, for you. -allowed-tools: "megamemory:*" ---- - -# Megamemory — Project Knowledge Graph - -Your persistent memory of the codebase. You have no implicit memory of this project between sessions, so this graph is your continuity. You write concepts as you work, and you query them before starting tasks. - -## When to Use - -- **Session start** → You must call \`list_roots\` before beginning work -- **Before any task** → You must call \`understand\` before reading source files for project understanding -- **After any task** → You must call \`create_concept\` / \`update_concept\` / \`link\` to record what you did -- **Refactoring or removing features** → You must call \`remove_concept\` to mark things as gone (with reason) - -## Core Principles - -1. **Query before work, update after work.** This is required, not optional. -2. **Concepts, not code.** Nodes are features, patterns, decisions — not files or symbols. -3. **Be specific.** Include parameter names, defaults, file paths, rationale. -4. **Keep it shallow.** Max 3 levels deep. Useful beats exhaustive. - -## Concept Kinds - -\`feature\` | \`module\` | \`pattern\` | \`config\` | \`decision\` | \`component\` - -## Relationship Types - -- \`depends_on\` — A requires B to function -- \`implements\` — A is the concrete implementation of B -- \`calls\` — A invokes B at runtime -- \`connects_to\` — A and B interact or share data -- \`configured_by\` — A's behavior is controlled by B - -## MCP Tools Reference - -| Tool | When | What it does | -|---|---|---| -| \`megamemory:understand\` | Before tasks | Semantic search — returns matching concepts with children, edges, parent | -| \`megamemory:create_concept\` | After tasks | Add new concept with summary, kind, edges, file refs | -| \`megamemory:update_concept\` | After tasks | Patch existing concept fields | -| \`megamemory:link\` | After tasks | Create relationship between two concepts | -| \`megamemory:remove_concept\` | On refactor/delete | Soft-delete with reason (history preserved) | -| \`megamemory:list_roots\` | Session start | All top-level concepts with children + stats | -| \`megamemory:list_conflicts\` | After merge | Lists unresolved merge conflicts grouped by merge_group | -| \`megamemory:resolve_conflict\` | During /merge | Resolve a conflict by providing verified, correct content | -`; - -export default tool({ - description: SKILL, - args: { - action: tool.schema - .enum(["query", "record", "overview", "merge"]) - .describe( - "Workflow action: query (before task — understand context), record (after task — create/update/link), overview (session start — list roots), merge (resolve merge conflicts)", - ), - query: tool.schema - .string() - .optional() - .describe("Natural language query for the 'query' action"), - concepts: tool.schema - .string() - .optional() - .describe( - "For 'record' action: brief description of what concepts to create/update/link", - ), - }, - async execute({ action, query, concepts }) { - switch (action) { - case "overview": - return `To get a project overview, call: - -1. megamemory:list_roots — Returns all top-level concepts with their children and graph stats. - -Use this at the start of every session to orient yourself. If the graph is empty, proceed normally and create concepts as you work.`; - - case "query": - if (!query) { - return "Error: query is required for the query action. Describe what you need to understand about the project."; - } - return `To load context for "${query}", call: - -1. megamemory:understand — query="${query}" - Returns: matched concepts ranked by relevance, each with: - - summary, why, file_refs - - children (1 level) - - outgoing and incoming edges - - parent context - -Use the returned context instead of re-reading source files when possible. If no relevant results come back, proceed normally — the graph may not cover this area yet.`; - - case "record": - return `After completing your task, update the knowledge graph: - -1. **New concepts** → megamemory:create_concept - - name: human-readable name - - kind: feature | module | pattern | config | decision | component - - summary: specific — include param names, defaults, file paths, behavior - - why: rationale for this design - - parent_id: parent concept slug (for nesting) - - file_refs: relevant file paths + line ranges - - edges: [{to: "concept-id", relation: "depends_on|implements|calls|connects_to|configured_by", description: "why"}] - - created_by_task: what task/prompt created this - -2. **Changed concepts** → megamemory:update_concept - - id: the concept slug - - changes: {summary?, why?, file_refs?, name?, kind?} - -3. **New relationships** → megamemory:link - - from, to: concept IDs - - relation: depends_on | implements | calls | connects_to | configured_by - - description: why this relationship exists - -4. **Removed features** → megamemory:remove_concept - - id: concept to remove - - reason: why it was removed${concepts ? `\n\nContext about what to record: "${concepts}"` : ""}`; - - case "merge": - return `To resolve merge conflicts in the knowledge graph: - -1. **List conflicts** → megamemory:list_conflicts - - Returns all unresolved conflicts grouped by merge_group - - Each group has competing versions with summaries, file_refs, edges - -2. **For each conflict:** - a. Read both versions' summaries, file_refs, and edges - b. Read the actual source files referenced in file_refs to determine what the code ACTUALLY does now - c. Write the correct resolved content based on the current codebase — do NOT just pick a side - -3. **Resolve** → megamemory:resolve_conflict - - merge_group: the UUID of the conflict - - resolved: {summary, why?, file_refs?} — the verified, correct content - - reason: what you verified and why this resolution is correct - -The goal is accuracy: the resolved concept should describe the code as it actually exists. If referenced files no longer exist, the concept may be outdated — update or remove accordingly.`; - - default: - return `Unknown action: ${action}. Use: overview (session start), query (before task), record (after task), merge (resolve conflicts).`; - } - }, -});