opencodekit 0.2.2 → 0.2.4

package/README.md

@@ -247,6 +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, 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.1",
+  version: "0.2.4",
   description: "CLI tool for bootstrapping and managing OpenCodeKit projects",
   type: "module",
   repository: {

package/dist/template/.opencode/.env.example

@@ -5,7 +5,7 @@
 # ============================================================================
 
 # Configure bash command timeout (default: 120000ms = 2 minutes)
-OPENCODE_EXPERIMENTAL_BASH_DEFAULT_TIMEOUT_MS=300000
+export OPENCODE_EXPERIMENTAL_BASH_DEFAULT_TIMEOUT_MS=300000
 export OPENCODE_DISABLE_AUTOCOMPACT=0  # Disable broken compaction
 export OPENCODE_DISABLE_PRUNE=0        # Disable potentially buggy pruning
 export OPENCODE_EXPERIMENTAL_TURN_SUMMARY=1

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,43 +56,86 @@ bd create "[title]" -t [type] -p [priority] -d "[description]" --json
 mkdir -p .beads/artifacts/<bead-id>
 ```
 
+Use the PRD template from `.opencode/memory/_templates/prd.md` as the base structure.
+
 Write `.beads/artifacts/<bead-id>/spec.md`:
 
 ```markdown
 # [Title]
 
 **Bead:** <bead-id>
-**Mode:** [Quick/Deep]
+**Created:** [date]
+**Status:** To Do
+
+## Goal
+
+[1-2 sentences: What exactly are we building and why?]
+
+## Scope
+
+### In-Scope:
+
+- [What we ARE doing]
 
-## Problem
+### Out-of-Scope:
 
-[1-2 sentences]
+- [What we are NOT doing]
 
-## Requirements
+## User Flow
 
-- [Requirement 1]
-- [Requirement 2]
+1. [Step 1: What user sees/does]
+2. [Step 2]
+3. [Step 3]
 
 ## Success Criteria
 
-- [ ] [Criterion 1]
-- [ ] [Criterion 2]
+- [ ] [Specific, measurable criterion 1]
+- [ ] [Specific, measurable criterion 2]
+- [ ] [Specific, measurable criterion 3]
+
+## Dependencies
+
+- [List any prerequisites or blocking tasks]
+
+## Notes
+
+[Additional context or constraints]
 ```
 
+For **Quick** mode, simplify: Goal, Success Criteria, Notes only.
+
 For **Deep** mode, add:
 
 ```markdown
-## Scope
-
-**In:** [What we ARE doing]
-**Out:** [What we are NOT doing]
-
 ## Open Questions
 
 - [Question for research phase]
+
+## Technical Approach
+
+[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

@@ -33,26 +33,55 @@ Save the bead ID for subsequent commands. Add the GitHub issue reference:
 bd edit <bead-id> --note "GitHub issue: #$ARGUMENTS"
 ```
 
-## Implementation Plan
+## Create Spec from PRD Template
+
+Use `.opencode/memory/_templates/prd.md` as the base structure.
 
 Save to `.beads/artifacts/<bead-id>/spec.md`:
 
-1. **Files to change:** Identify affected code
-2. **Testing strategy:** How to verify fix
-3. **Risks/edge cases:** What could go wrong
+```markdown
+# [Issue Title]
+
+**Bead:** <bead-id>
+**Created:** [date]
+**Status:** To Do
+**GitHub Issue:** #$ARGUMENTS
+
+## Goal
+
+[What exactly are we fixing/building and why?]
+
+## Scope
+
+### In-Scope:
+
+- [Files to change]
+- [Specific functionality to fix/add]
 
-## Action Plan
+### Out-of-Scope:
 
-1. Create branch: `git checkout -b issue-$ARGUMENTS`
-2. Implementation steps (ordered)
-3. Testing approach
-4. Documentation updates
+- [What we are NOT touching]
 
-## Acceptance Criteria
+## User Flow
 
-- [ ] Concrete deliverables
-- [ ] Test cases to verify
-- [ ] Performance considerations
+1. [How user encounters the issue]
+2. [Expected behavior after fix]
+
+## Success Criteria
+
+- [ ] [Specific fix verified]
+- [ ] [Test cases pass]
+- [ ] [No regression]
+
+## Dependencies
+
+- [List any prerequisites or blocking tasks]
+
+## Notes
+
+- **Risks/edge cases:** [What could go wrong]
+- **Testing strategy:** [How to verify fix]
+```
 
 ## Discovered Work
 

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           |