opencodekit 0.2.3 → 0.2.5

package/README.md

@@ -247,7 +247,8 @@ You've successfully set up OpenCodeKit when:
 - **Custom Commands**: `.opencode/command/` - All 45+ workflow commands
 - **Skills System**: `.opencode/skills/` - 24 skills (8 core, 7 stack, 9 specialized)
 - **Memory System**: `.opencode/memory/` - Persistent cross-session knowledge
-- **Templates**: `.opencode/memory/_templates/` - PRD and task templates for `/create` and `/issue` commands
+- **Templates**: `.opencode/memory/_templates/` - PRD, observation, and session-summary templates
+- **Memory Tools**: `.opencode/tool/` - memory-read, memory-update, memory-search, observation
 
 ---
 

package/dist/index.js

@@ -750,7 +750,7 @@ var cac = (name = "") => new CAC(name);
 // package.json
 var package_default = {
   name: "opencodekit",
-  version: "0.2.3",
+  version: "0.2.5",
   description: "CLI tool for bootstrapping and managing OpenCodeKit projects",
   type: "module",
   repository: {

package/dist/template/.opencode/AGENTS.md

@@ -100,13 +100,53 @@
 
 ```
 .opencode/memory/
-  _templates/     # Task templates
+  _templates/     # Task templates (prd, observation, session-summary)
   handoffs/       # Phase transitions
   research/       # Research findings
+  observations/   # Structured observations
+```
+
+### Memory Tools
+
+| Tool            | Use For                          |
+| --------------- | -------------------------------- |
+| `memory-read`   | Load previous context, templates |
+| `memory-update` | Save learnings, handoffs         |
+| `memory-search` | Search across all memory files   |
+| `observation`   | Create structured observations   |
+
+### Observations
+
+Record important findings with structured metadata:
+
+```
+observation(
+  type: "decision",     # decision, bugfix, feature, pattern, discovery, learning, warning
+  title: "Use JWT auth",
+  content: "Decided to use JWT because...",
+  concepts: "auth, security",
+  files: "src/auth.ts",
+  bead_id: "bd-abc123"
+)
+```
+
+**When to create observations:**
+
+- Major architectural decisions
+- Bug root causes discovered
+- Patterns worth reusing
+- Gotchas and warnings for future
+
+### Memory Search
+
+Find past decisions, research, or handoffs:
+
+```
+memory-search(query: "authentication")
+memory-search(query: "bugfix", type: "observations")
+memory-search(query: "session", type: "handoffs")
 ```
 
-- `memory-read` - Load previous context
-- `memory-update` - Save learnings
 - Task tracking uses Beads (`bd` CLI)
 
 ## Session Management

package/dist/template/.opencode/command/create.md

@@ -56,7 +56,7 @@ bd create "[title]" -t [type] -p [priority] -d "[description]" --json
 mkdir -p .beads/artifacts/<bead-id>
 ```
 
-Use the PRD template from `.opencode/memory/_templates/task-prd.md` as the base structure.
+Use the PRD template from `.opencode/memory/_templates/prd.md` as the base structure.
 
 Write `.beads/artifacts/<bead-id>/spec.md`:
 
@@ -116,7 +116,26 @@ For **Deep** mode, add:
 [To be filled during /research phase]
 ```
 
-## Phase 5: Report
+## Phase 5: Review Spec
+
+Present the spec for approval:
+
+```
+Spec Preview:
+━━━━━━━━━━━━━
+
+[Show full spec.md content]
+
+━━━━━━━━━━━━━
+Approve spec? (yes/modify)
+```
+
+**STOP and wait for human response.**
+
+If "modify": Iterate on spec based on feedback until approved.
+If "yes": Proceed to report.
+
+## Phase 6: Report
 
 ```
 Created: <bead-id>

package/dist/template/.opencode/command/issue.md

@@ -35,7 +35,7 @@ bd edit <bead-id> --note "GitHub issue: #$ARGUMENTS"
 
 ## Create Spec from PRD Template
 
-Use `.opencode/memory/_templates/task-prd.md` as the base structure.
+Use `.opencode/memory/_templates/prd.md` as the base structure.
 
 Save to `.beads/artifacts/<bead-id>/spec.md`:
 

package/dist/template/.opencode/command/plan.md

@@ -17,9 +17,12 @@ Read artifacts:
 ```bash
 cat .beads/artifacts/<bead-id>/spec.md
 cat .beads/artifacts/<bead-id>/research.md
+cat .beads/artifacts/<bead-id>/design.md 2>/dev/null
 ```
 
-If missing: "Run `/research <bead-id>` first."
+If spec.md missing: "Run `/create <bead-id>` first."
+If research.md missing: "Run `/research <bead-id>` first."
+If design.md exists: Resume from saved design options.
 
 ## Phase 2: Generate Design Options
 
@@ -68,7 +71,77 @@ Present 2-3 approaches:
 **Recommendation:** Option [A/B] because [reason].
 ```
 
-## Phase 3: Get Approval
+## Phase 3: Save Design Document
+
+Save design options to `.beads/artifacts/<bead-id>/design.md`:
+
+```markdown
+# Design Options: [Title]
+
+**Bead:** <bead-id>
+**Date:** <date>
+**Status:** Pending Approval
+
+## Problem Statement
+
+[What we're solving - from spec.md]
+
+## Options Considered
+
+### Option A: [Name]
+
+**Approach:** [1-2 sentence description]
+
+**Changes:**
+
+- `src/foo.ts` - [what changes]
+- `src/bar.ts` - [what changes]
+
+**Pros:**
+
+- [pro 1]
+- [pro 2]
+
+**Cons:**
+
+- [con 1]
+
+**Effort:** [S/M/L]
+
+---
+
+### Option B: [Name]
+
+**Approach:** [1-2 sentence description]
+
+**Changes:**
+
+- `src/baz.ts` - [what changes]
+
+**Pros:**
+
+- [pro 1]
+
+**Cons:**
+
+- [con 1]
+- [con 2]
+
+**Effort:** [S/M/L]
+
+---
+
+## Recommendation
+
+Option [A/B] because [reason].
+
+## Decision
+
+**Chosen:** [To be filled after approval]
+**Rationale:** [To be filled after approval]
+```
+
+## Phase 4: Get Approval
 
 **STOP and wait for human response.**
 
@@ -78,7 +151,15 @@ Pick an option (A/B/C), modify, or "none" to propose alternatives.
 
 Do not proceed until user confirms.
 
-## Phase 4: Create Plan
+## Phase 5: Update Design Decision
+
+After approval, update `.beads/artifacts/<bead-id>/design.md`:
+
+- Change **Status:** to `Approved`
+- Fill in **Chosen:** with selected option
+- Fill in **Rationale:** with user's reasoning
+
+## Phase 6: Create Plan
 
 After approval, write `.beads/artifacts/<bead-id>/plan.md`:
 
@@ -136,7 +217,7 @@ After approval, write `.beads/artifacts/<bead-id>/plan.md`:
 - [Risk 1] - [mitigation]
 ```
 
-## Phase 5: Update Bead
+## Phase 7: Update Bead
 
 ```bash
 bd edit <bead-id> --note "Plan approved: [option name]. [step count] steps."

package/dist/template/.opencode/memory/_templates/observation.md

@@ -0,0 +1,39 @@
+# Observation Template
+
+**Type:** [decision | bugfix | feature | pattern | discovery | learning | warning]
+**Created:** [timestamp]
+**Bead:** [optional bead-id]
+**Concepts:** `tag1`, `tag2`, `tag3`
+**Files:** `path/to/file1.ts`, `path/to/file2.ts`
+
+---
+
+## Context
+
+[What situation prompted this observation? What were you working on?]
+
+## Observation
+
+[The core insight, decision, or learning. Be specific and actionable.]
+
+## Rationale
+
+[Why is this important? What alternatives were considered?]
+
+## Future Reference
+
+[How should this inform future decisions? Any follow-up actions?]
+
+---
+
+## Type Definitions
+
+| Type      | Icon | Use For                              |
+| --------- | ---- | ------------------------------------ |
+| decision  | 🎯   | Architectural or design choices made |
+| bugfix    | 🐛   | Bug root causes and solutions        |
+| feature   | ✨   | Feature implementation notes         |
+| pattern   | 🔄   | Recurring patterns or conventions    |
+| discovery | 💡   | Unexpected findings or insights      |
+| learning  | 📚   | Lessons learned from experience      |
+| warning   | ⚠️   | Pitfalls to avoid, gotchas           |

package/dist/template/.opencode/package.json

@@ -11,7 +11,7 @@
   "author": "",
   "license": "ISC",
   "dependencies": {
-    "@opencode-ai/plugin": "1.0.153"
+    "@opencode-ai/plugin": "1.0.155"
   },
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.13",