initial commit

.config/opencode/commands/bootstrap-memory.md

@@ -0,0 +1,47 @@
+# Bootstrap Project Knowledge Graph
+
+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
+READ README.md
+
+You are bootstrapping the megamemory knowledge graph 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.
+
+## Step 1: Check existing graph
+
+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.
+
+## Step 2: Identify major modules
+
+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)
+
+## Step 3: Read and create root concepts
+
+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.
+
+## Step 4: Create children for important sub-components
+
+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 5: Link related concepts
+
+Connect concepts that interact across boundaries using `megamemory:link`.
+Focus on meaningful relationships: depends_on, calls, connects_to, implements,
+configured_by.
+
+## 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.

.config/opencode/commands/docs.md

@@ -0,0 +1,20 @@
+---
+description: Documentation coverage workflow using librarian subagent
+agent: librarian
+subtask: true
+---
+
+Review the implemented change set and ensure required documentation coverage is complete.
+
+Change set scope:
+$ARGUMENTS
+
+Requirements:
+
+- Query megamemory 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`
+  - relevant `docs/*`
+  - `AGENTS.md` when workflow, policy, or agent behavior changes.
+- Report what changed, what remains (if anything), and any explicitly deferred documentation debt.

.config/opencode/commands/init.md

@@ -0,0 +1,106 @@
+---
+description: Initialize or update a project with scaffold, docs, and knowledge graph — adapts to both new and existing projects.
+---
+
+You are initializing or updating a project. Follow these steps in order.
+
+Project hint (may be empty):
+$ARGUMENTS
+
+## Step 1 — Explore current project state (delegate to `explorer`)
+
+Delegate to the `explorer` subagent first, before any questions, to determine whether this is a new or existing project.
+
+- Ask explorer to inspect the working tree for project-defining artifacts, including:
+  - source files and source directories
+  - `README.md`, `AGENTS.md`, `docs/`
+  - stack markers such as `package.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`, `composer.json`
+  - git markers such as `.git/`
+  - any similar files that strongly indicate an existing project
+- Ask explorer to return:
+  - classification: `new_project` or `existing_project`
+  - inferred project name, purpose, and tech stack (with confidence)
+  - which required scaffold files already exist vs are missing
+  - whether `.git/` exists
+
+## Step 2 — Clarify (Lead, one round max)
+
+Use the `question` tool for at most one round, adapting to Step 1 findings.
+
+- If explorer's classification confidence is low (e.g., directory has only a few ambiguous files), include the classification itself as a question to confirm.
+- If classification is `existing_project`:
+  - confirm or correct explorer inferences (name, one-sentence purpose, stack)
+  - ask only for unknown or low-confidence fields
+  - do **not** ask whether to initialize git if `.git/` already exists
+  - do **not** ask for files/details that are already present and clear
+- If classification is `new_project`:
+  - ask:
+    - project name and one-sentence purpose
+    - primary language / framework / tech stack
+    - whether to initialize a git repository
+
+## Step 3 — Scaffold (delegate to `coder`)
+
+Delegate to the `coder` subagent with explicit mode (`new_project` or `existing_project`) and the file existence map from Step 1.
+
+- 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
+  - `docs/architecture.md` — stub with title + purpose
+  - `.gitignore` — must include `.megamemory/` entry; add stack-appropriate ignores (e.g., `node_modules/`, `__pycache__/`, `target/`)
+  - other stack-specific scaffold files if clearly implied (e.g., `package.json`, `pyproject.toml`)
+- If `new_project`:
+  - create all required scaffold files/directories
+- If `existing_project`:
+  - 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
+  - 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`
+
+## Step 4 — Documentation review (delegate to `librarian`)
+
+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.
+- 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)
+
+Always update megamemory 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: `<project 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.
+
+## Step 6 — Git handling (delegate to `coder`)
+
+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
+- Commit message should be concise and conventional, e.g.:
+  - `chore: initialize project scaffold` (new project)
+  - `chore: add missing project scaffolding` (existing project)
+
+## Completion report
+
+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).

.config/opencode/commands/plan.md

@@ -0,0 +1,27 @@
+---
+description: Trigger phased planning for a new task — enters CLARIFY mode and walks through DISCOVER → PLAN → CRITIC-GATE
+---
+
+You are the lead agent. The user has invoked `/plan` to begin structured planning for a task.
+
+## 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.
+
+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
+   - Group into independent workstreams
+   - Classify risk profiles and assign quality tiers
+   - Allocate worktrees (one per independent workstream)
+   - 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.
+
+4. **CONSULT** (if needed): For domain-specific questions, check megamemory 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.
+
+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.
+
+Present the final approved plan to the user before starting EXECUTE.

.config/opencode/commands/research.md

@@ -0,0 +1,17 @@
+---
+description: Deep research workflow using researcher subagent
+agent: researcher
+subtask: true
+---
+
+Research the following topic deeply and return a concise, evidence-backed report.
+
+Topic:
+$ARGUMENTS
+
+Requirements:
+
+- Query megamemory first for existing related concepts.
+- 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.

.config/opencode/commands/review.md

@@ -0,0 +1,17 @@
+---
+description: Code review workflow using reviewer subagent
+agent: reviewer
+subtask: true
+---
+
+Review the requested scope and provide actionable feedback.
+
+Scope:
+$ARGUMENTS
+
+Requirements:
+
+- Query megamemory 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.

.config/opencode/commands/save-memory.md

@@ -0,0 +1,83 @@
+# Save Session Knowledge
+
+You are saving what you learned this session into the megamemory knowledge graph.
+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
+
+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.
+
+## 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 patterns or conventions did you discover?
+- What architectural understanding do you have now that isn't in the graph?
+- Did anything get removed, replaced, or deprecated?
+
+## Step 3: Search for overlap
+
+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 example, if you worked on authentication, call:
+  megamemory:understand — query="authentication"
+
+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.
+
+## Step 4: Write to the knowledge graph
+
+For each thing worth remembering:
+
+**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
+
+**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.
+
+**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.
+
+**Removed/replaced things** → `megamemory:remove_concept`
+  - id: concept to remove
+  - reason: why it was removed
+  If something in the graph is no longer true.
+
+## Step 5: Verify
+
+Call `megamemory:list_roots` again. Confirm the graph reflects your current
+understanding. Report what you saved.
+
+## 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.

.config/opencode/commands/sme.md

@@ -0,0 +1,18 @@
+---
+description: Invoke the SME (Subject Matter Expert) agent for deep domain consultation — guidance is cached in megamemory
+---
+
+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.
+
+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.
+
+4. Link the SME guidance concept to any active plan concept in megamemory.

.config/opencode/commands/status.md

@@ -0,0 +1,16 @@
+---
+description: Show persistent cross-session work status from megamemory
+agent: lead
+---
+
+Load persistent project status from megamemory 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.
+- Summarize:
+  1. What is currently in progress
+  2. What was completed recently
+  3. What decisions are still pending
+  4. Recommended next actions

.config/opencode/commands/test.md

@@ -0,0 +1,17 @@
+---
+description: Test execution workflow using tester subagent
+agent: tester
+subtask: true
+---
+
+Run the relevant test scope and report results.
+
+Requested scope:
+$ARGUMENTS
+
+Requirements:
+
+- Query megamemory 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.