This commit is contained in:
2026-03-10 13:09:47 +00:00
parent e0c4c2ed7b
commit ffd0d31fa5
43 changed files with 532 additions and 749 deletions

View File

@@ -1,27 +1,35 @@
# Bootstrap Project Memory Files
---
title: bootstrap-memory
type: note
permalink: opencode-config/commands/bootstrap-memory
---
# Bootstrap Project Memory
RUN { git ls-files; git ls-files --others --exclude-standard; } 2>/dev/null | sort -u
READ README.md
You are bootstrapping `.memory/` files for this project.
You are bootstrapping basic-memory project notes for this project.
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
Your job is to inspect the codebase and create an initial knowledge baseline in
basic-memory. Capture architecture, core modules, conventions, and key decisions
so future sessions can resume quickly.
## Step 1: Create `.memory/` structure
## Step 0: Ensure a dedicated per-repo basic-memory project exists
Create (if missing):
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`.
```
.memory/
knowledge.md
decisions.md
plans/
research/
```
All subsequent `write_note`, `search_notes`, and `build_context` calls in this
command must pass `project="<repo-project-name>"` for project-specific notes, or
`project="main"` for cross-project reusable knowledge.
`.memory/` is tracked in git.
## Step 1: Check existing basic-memory state
Use `search_notes` and `build_context` (with `project="<repo-project-name>"`) to
check whether this project already has notes in basic-memory. Understanding
current state prevents duplication and helps you decide what to create vs update.
## Step 2: Inspect project structure
@@ -37,35 +45,45 @@ Identify:
- Core modules/subsystems and responsibilities
- Key patterns/conventions (naming, layering, testing, config)
## Step 3: Write initial `knowledge.md`
## Step 3: Write initial knowledge notes
Populate `.memory/knowledge.md` with:
Use `write_note` (with `project="<repo-project-name>"`) to create project
knowledge notes under the `knowledge/` folder:
- Project purpose and scope
- Architecture overview
- Key modules with file paths
- Important implementation patterns/conventions
Use markdown sections with max 2 heading levels.
## Step 4: Seed decisions notes
## Step 4: Seed `decisions.md`
Use `write_note` (with `project="<repo-project-name>"`) to create a `decisions/`
note with any clear, durable decisions found in docs or code patterns (for
example: stack choices, testing strategy, architectural constraints). Include
rationale when known.
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 notes
## Step 5: Initialize plans/research folders
- If active in-progress work is discoverable, use `write_note` (with
`project="<repo-project-name>"`) to create a `plans/<feature>` note with scope,
tasks, and acceptance criteria.
- If research artifacts are discovered, use `write_note` (with
`project="<repo-project-name>"`) to create a `research/<topic>` note with
findings and references.
- If active in-progress work is discoverable, create `.memory/plans/<feature>.md`
with scope, tasks, and acceptance criteria.
- If research artifacts are discovered, create `.memory/research/<topic>.md`
with findings and references.
## Step 6: Record cross-project reusable knowledge
## Step 6: Update instruction file
If you discover patterns, conventions, or tech knowledge that would benefit other
projects, use `write_note` with `project="main"` to record them as global notes.
Do not store project-specific plans, decisions, or session state in `main`.
## Step 7: Update instruction file
If `AGENTS.md` exists, update it with any new project knowledge discovered
during bootstrap (architecture, conventions, commands). The symlinks
(`CLAUDE.md`, `.cursorrules`, `.github/copilot-instructions.md`) will
automatically reflect changes.
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.
If the instruction file doesn't exist, note that `/init` should be run to create it.
@@ -74,5 +92,6 @@ If the instruction file doesn't exist, note that `/init` should be run to create
- 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).
- 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.

View File

@@ -2,6 +2,7 @@
description: Documentation coverage workflow using librarian subagent
agent: librarian
subtask: true
permalink: opencode-config/commands/docs
---
Review the implemented change set and ensure required documentation coverage is complete.
@@ -11,10 +12,10 @@ $ARGUMENTS
Requirements:
- Read relevant `.memory/*.md` files first for prior workflow and documentation decisions.
- Read relevant basic-memory project notes first for prior workflow and documentation decisions (use `project="<repo-project-name>"`).
- 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.
- Report what changed, what remains (if anything), and any explicitly deferred documentation debt.

View File

@@ -1,5 +1,7 @@
---
description: Initialize or update a project with scaffold, docs, and .memory files — adapts to both new and existing projects.
description: Initialize or update a project with scaffold, docs, and basic-memory
notes — adapts to both new and existing projects.
permalink: opencode-config/commands/init
---
You are initializing or updating a project. Follow these steps in order.
@@ -51,7 +53,6 @@ Delegate to the `coder` subagent with explicit mode (`new_project` or `existing_
- `.github/copilot-instructions.md` — symlink to `../AGENTS.md`
- `docs/architecture.md` — stub with title + purpose
- `.gitignore` — add stack-appropriate ignores (e.g., `node_modules/`, `__pycache__/`, `target/`)
- `.memory/` — create and/or update `knowledge.md`, `decisions.md`, `plans/`, `research/`
- other stack-specific scaffold files if clearly implied (e.g., `package.json`, `pyproject.toml`)
- If `new_project`:
- create all required scaffold files/directories
@@ -65,7 +66,6 @@ Delegate to the `coder` subagent with explicit mode (`new_project` or `existing_
- `ln -s AGENTS.md .cursorrules`
- `ln -s ../AGENTS.md .github/copilot-instructions.md`
- if `AGENTS.md` is missing but `.github/copilot-instructions.md` exists as a real file, move its content into `AGENTS.md`, then recreate `.github/copilot-instructions.md` as a symlink
- if `.memory/` is missing, create the full `.memory/` directory structure
- examples:
- if `README.md` exists and only `CLAUDE.md` is missing, create `CLAUDE.md` as a symlink to `AGENTS.md`
- if `docs/` is missing, create it and add `docs/architecture.md`
@@ -80,17 +80,19 @@ Always delegate to the `librarian` subagent, for both new and existing projects.
- Ensure stubs are explicitly marked for later completion.
- Keep edits additive and non-destructive for existing projects.
## Step 5 — Initialize or update `.memory` project overview (Lead)
## Step 5 — Initialize or update basic-memory project notes (Lead)
Always create or update `.memory/knowledge.md` for this project.
Always create or update basic-memory project notes for this project.
- Read existing `.memory/knowledge.md` (if present) to avoid duplicate sections.
- Create or update a project overview section with:
- **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`.
- All subsequent note operations in this step must pass `project="<repo-project-name>"`.
- 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:
- 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.
- Add WikiLink cross-references to related notes (e.g., `[[decisions/...]]`).
## Step 6 — Git handling (delegate to `coder`)
@@ -112,4 +114,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).
- What the user should fill in next (stubs, open questions, follow-up documentation).

View File

@@ -1,12 +1,14 @@
---
description: Trigger phased planning for a new task — enters CLARIFY mode and walks through DISCOVER → PLAN → CRITIC-GATE
description: Trigger phased planning for a new task — enters CLARIFY mode and walks
through DISCOVER → PLAN → CRITIC-GATE
permalink: opencode-config/commands/plan
---
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 the relevant plan file.
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 note (per-repo basic-memory project `plans/`).
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,12 +18,12 @@ 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 the relevant `.memory/` files.
3. **DISCOVER**: Delegate to `explorer` to map relevant parts of the codebase. Delegate to `researcher` for any technical unknowns. Record findings in per-repo basic-memory project notes (`research/` or `knowledge/`). Record reusable cross-project findings in `main`.
4. **CONSULT** (if needed): For domain-specific questions, check `.memory/decisions.md` for cached SME guidance first. If not cached, delegate to `sme`.
4. **CONSULT** (if needed): For domain-specific questions, check per-repo project `decisions/` notes and `main` 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 the plan in `.memory/plans/<feature>.md`.
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 the per-repo basic-memory project `plans/<feature>` note.
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.
Present the final approved plan to the user before starting EXECUTE.

View File

@@ -2,6 +2,7 @@
description: Deep research workflow using researcher subagent
agent: researcher
subtask: true
permalink: opencode-config/commands/research
---
Research the following topic deeply and return a concise, evidence-backed report.
@@ -11,7 +12,7 @@ $ARGUMENTS
Requirements:
- Read relevant `.memory/*.md` files first for existing related research and decisions.
- Read relevant basic-memory notes first (`search_notes` with `project="<repo-project-name>"`) for existing related research and decisions. Also check `project="main"` for cross-project guidance.
- If scope is ambiguous, ask one focused clarification question using the question tool.
- Provide findings, tradeoffs, and recommended approach.
- Record durable insights in the relevant `.memory/` files with markdown sections and cross-references.
- Record durable project-specific insights in per-repo project notes (`write_note` with `project="<repo-project-name>"`). Record cross-project reusable insights with `project="main"`. Use tags and WikiLink cross-references.

View File

@@ -2,6 +2,7 @@
description: Code review workflow using reviewer subagent
agent: reviewer
subtask: true
permalink: opencode-config/commands/review
---
Review the requested scope and provide actionable feedback.
@@ -11,7 +12,7 @@ $ARGUMENTS
Requirements:
- Read relevant `.memory/*.md` files first for project conventions and prior decisions.
- Read relevant basic-memory project notes first for project conventions and prior decisions (use `project="<repo-project-name>"`).
- 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.
- Include concrete file references and rationale.

View File

@@ -1,22 +1,32 @@
---
title: save-memory
type: note
permalink: opencode-config/commands/save-memory
---
# Save Session Knowledge
You are saving what you learned this session into the project's `.memory/` directory.
You are saving what you learned this session into basic-memory notes.
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 memory files
## Step 1: Identify the per-repo basic-memory project
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`
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`.
Understanding current state prevents duplication and helps you decide what to update.
All project-specific notes must target `project="<repo-project-name>"`.
Cross-project reusable knowledge must target `project="main"`.
## Step 2: Reflect on this session
## Step 2: Load existing notes
Use `search_notes` and `build_context` (with the correct `project`) to see
what's already recorded. Understanding current state prevents duplication and
helps you decide what to update.
## Step 3: Reflect on this session
Think about what happened this session. Consider:
- What did you learn about the project's purpose or intent?
@@ -26,38 +36,37 @@ Think about what happened this session. Consider:
- What research findings are worth keeping?
- Did anything get removed, replaced, or deprecated?
## Step 3: Map learnings to memory files
## Step 4: Map learnings to notes (with correct project target)
For each thing worth remembering, update the right file:
For each thing worth remembering, write or update the right note in the right project:
- **Project architecture/patterns/conventions** → `.memory/knowledge.md`
- **Decisions and rationale** → `.memory/decisions.md`
- **Ongoing feature plans and acceptance criteria** → `.memory/plans/<feature>.md`
- **Deep research findings** → `.memory/research/<topic>.md`
- **Project architecture/patterns/conventions** → per-repo project `knowledge/` notes (`project="<repo-project-name>"`)
- **Decisions and rationale** → per-repo project `decisions/` notes (`project="<repo-project-name>"`)
- **Ongoing feature plans and acceptance criteria** → per-repo project `plans/<feature>` notes (`project="<repo-project-name>"`)
- **Deep research findings** → per-repo project `research/<topic>` notes (`project="<repo-project-name>"`)
- **Reusable cross-project patterns, conventions, tech knowledge, lessons learned** → `project="main"` with appropriate tags
Prefer updating existing sections over creating duplicates.
**Hard rule:** Never store project-specific plans, decisions, research, gates, or sessions in `main`. Never store cross-project reusable knowledge in a per-repo project.
## Step 4: Write updates using markdown sections
Prefer updating existing notes over creating duplicates.
Use standard markdown headings (`##`) and concise subsections when needed.
Do not use concept IDs or graph-style metadata.
## Step 5: Write updates
Use `write_note` with appropriate folder, tags, WikiLinks, and **always the correct `project` parameter**.
When writing, be specific:
- include parameter names, defaults, file paths, behavior details
- include rationale (`why`) for decisions
- include cross-references to related memory entries
- include WikiLink cross-references to related notes
Example cross-reference:
- `See [Decision: Auth token TTL](../decisions.md#decision-auth-token-ttl)`
## Step 6: Verify and report
## Step 5: Verify and report
Use `search_notes` (with `project`) to confirm notes reflect current understanding.
Report what was added/updated, where, and in which project.
Re-read updated `.memory/` files to confirm they reflect current understanding.
Report what was added/updated and where.
## Step 7: Update instruction file if project knowledge changed
## Step 6: Update instruction file if project knowledge changed
If `.memory/knowledge.md` was **materially** updated (architecture, conventions,
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.
@@ -67,7 +76,8 @@ If updates were only plans/research/tracking details, skip this step.
- Record what a future you (with no memory of this session) would need to know.
- Outcomes and rationale are more valuable than ceremony.
- Dont log process-only updates like "started phase X".
- 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.
- Always pass the `project` parameter on every MCP call.

View File

@@ -1,18 +1,24 @@
---
description: Invoke the SME (Subject Matter Expert) agent for deep domain consultation — guidance is cached in .memory/decisions.md
description: Invoke the SME (Subject Matter Expert) agent for deep domain consultation
— guidance is cached in basic-memory project decisions notes
permalink: opencode-config/commands/sme
---
You are the lead agent. The user has invoked `/sme` to consult a domain expert.
## Steps
1. Check `.memory/decisions.md` for existing SME guidance on the requested domain. If found, return the cached guidance immediately with its section heading.
1. Check the per-repo basic-memory project's `decisions/` notes (`search_notes` with `project="<repo-project-name>"`) for existing SME guidance on the requested domain. Also check `project="main"` for cross-project cached guidance. If found, return the cached guidance immediately.
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
- The per-repo basic-memory project name for project-specific caching
3. Once SME responds, record or update the guidance in `.memory/decisions.md`. Present the guidance to the user.
3. Once SME responds, record or update the guidance:
- Project-specific guidance → `write_note` with `project="<repo-project-name>"` under `decisions/`
- Reusable cross-project guidance → `write_note` with `project="main"` with domain tags
Present the guidance to the user.
4. Add cross-references between the SME guidance section and any active plan file in `.memory/plans/`.
4. Add WikiLink cross-references between the SME guidance note and any active plan notes.

View File

@@ -1,18 +1,20 @@
---
description: Show persistent cross-session work status from .memory files
description: Show persistent cross-session work status from basic-memory project notes
agent: lead
permalink: opencode-config/commands/status
---
Load persistent project status from `.memory/` and provide a resume-oriented status report.
Load persistent project status from basic-memory and provide a resume-oriented status report.
Requirements:
- 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.
- Identify the per-repo basic-memory project for this repo (use `list_memory_projects`). All queries must pass `project="<repo-project-name>"`.
- Use `search_notes` and `build_context` (with `project`) to find project-specific notes.
- Read `plans/*` notes for in-progress and recently completed work.
- Read `decisions/*` notes for pending or unresolved decisions.
- If present, read `knowledge/*` notes for additional context.
- Summarize:
1. What is currently in progress
2. What was completed recently
3. What decisions are still pending
4. Recommended next actions
4. Recommended next actions

View File

@@ -2,6 +2,7 @@
description: Test execution workflow using tester subagent
agent: tester
subtask: true
permalink: opencode-config/commands/test
---
Run the relevant test scope and report results.
@@ -11,7 +12,7 @@ $ARGUMENTS
Requirements:
- Read relevant `.memory/*.md` files first for testing context.
- Read relevant basic-memory project notes first for testing context (use `project="<repo-project-name>"`).
- 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.
- Report commands run, pass/fail results, and likely root causes for failures.