opencodekit 0.15.21 → 0.16.1

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

@@ -1,171 +1,311 @@
 ---
-description: Create a tracked task with spec
-argument-hint: "[title or description]"
-agent: build
+description: Create a specification for a bead using templates
+argument-hint: "<bead-id> [--prd] [--proposal]"
+agent: plan
+subtask: true
 ---
 
 # Create: $ARGUMENTS
 
-You're creating a new tracked task. Keep it simple unless complexity demands otherwise.
+Create structured artifacts for a bead using templates. This is the first step before planning.
 
-## Check For Duplicates First
+## Parse Arguments
 
-!`bd list --status=all | grep -i "[keywords]"`
+| Argument     | Default  | Description                          |
+| ------------ | -------- | ------------------------------------ |
+| `<bead-id>`  | required | The bead to create artifacts for     |
+| `--prd`      | false    | Use PRD template (combined format)   |
+| `--proposal` | false    | Create proposal.md first (for epics) |
 
-If similar work exists, link to it or extend it instead of creating duplicate.
+## Load Skills
 
-## Gather Requirements
-
-If `$ARGUMENTS` is clear, use it directly. If vague, ask:
+```typescript
+skill({ name: "beads" });
+skill({ name: "brainstorming" });
+skill({ name: "memory-system" });
+```
 
-1. What problem are we solving?
-2. Bug, feature, or task?
-3. What's the acceptance criteria?
-4. Any constraints?
+## Check Memory First
 
-Keep it brief. Don't over-engineer the interview.
+Search for similar specs and patterns before creating:
 
-## Assess Complexity
+```typescript
+// Find similar past specs
+memory_search({ query: "[bead title/description]", limit: 3 });
 
-**Simple** (single bead): One file, one clear action, ~30 min or less
-**Complex** (needs decomposition): Multiple domains, natural phases, hours of work
+// Find related patterns and conventions
+memory_search({ query: "[domain keywords] spec requirements", limit: 3 });
+```
 
-If complex, ask: "This looks like it needs decomposition. Create an epic with subtasks?"
+Review findings for:
 
-## Create The Bead
+- Similar specs that worked well (reuse structure)
+- Patterns and conventions already established
+- Gotchas to avoid in this domain
 
-Simple task:
+## Load Bead Context
 
 ```bash
-bd create "[title]" -t task -p 2
+bd show $ARGUMENTS
 ```
 
-Bug:
+Check what artifacts already exist:
 
 ```bash
-bd create "[title]" -t bug -p 1
+ls .beads/artifacts/$ARGUMENTS/ 2>/dev/null || echo "No artifacts yet"
 ```
 
-Feature:
+---
+
+## Phase 1: Setup Artifact Directory
 
 ```bash
-bd create "[title]" -t feature -p 2
+BEAD_DIR=".beads/artifacts/$ARGUMENTS"
+mkdir -p "$BEAD_DIR"
 ```
 
-Epic (if decomposing):
+---
+
+## Phase 2: Choose Template
+
+Based on flags and bead type:
+
+| Flag         | Template Used | Best For                      |
+| ------------ | ------------- | ----------------------------- |
+| `--prd`      | `prd.md`      | Quick features, smaller scope |
+| `--proposal` | `proposal.md` | Epics, major changes          |
+| (default)    | `spec.md`     | Standard task specifications  |
+
+### Copy Template
 
 ```bash
-bd create "[title]" -t epic -p 1
+# Default: Copy spec template
+cp .opencode/memory/_templates/spec.md "$BEAD_DIR/spec.md"
+
+# If --prd flag
+cp .opencode/memory/_templates/prd.md "$BEAD_DIR/prd.md"
+
+# If --proposal flag (for epics)
+cp .opencode/memory/_templates/proposal.md "$BEAD_DIR/proposal.md"
+cp .opencode/memory/_templates/spec.md "$BEAD_DIR/spec.md"
 ```
 
-## Create Spec
+---
+
+## Phase 3: Gather Context for Spec
+
+### Ask Clarifying Questions
+
+Before writing the spec, understand what needs to be built:
+
+```typescript
+question({
+  questions: [
+    {
+      header: "Scope",
+      question: "What should this feature do? Describe the core functionality.",
+      options: [], // Free text
+    },
+    {
+      header: "Users",
+      question: "Who will use this? (developers, end users, API consumers, etc.)",
+      options: [
+        { label: "Developers", description: "Internal tooling or API" },
+        { label: "End users", description: "Customer-facing feature" },
+        { label: "Both", description: "Used by developers and users" },
+      ],
+    },
+    {
+      header: "Constraints",
+      question: "Any constraints? (performance, compatibility, security)",
+      options: [], // Free text
+    },
+  ],
+});
+```
+
+### Research Existing Patterns (Optional)
+
+If user provides enough context, delegate to explore agent:
+
+```typescript
+Task({
+  subagent_type: "explore",
+  description: "Find similar patterns",
+  prompt: `Find patterns in codebase related to: [bead title/description]
+    - Similar implementations
+    - Existing conventions
+    - Test patterns used
+    Return: File paths and patterns found`,
+});
+```
+
+---
+
+## Phase 4: Fill In Template
+
+### For spec.md (default)
+
+Fill in the template with WHEN/THEN scenarios:
+
+```markdown
+# Specification
+
+**Bead:** $ARGUMENTS
+**Proposal:** N/A
+**Date:** [today]
+
+## Requirements
+
+### [Requirement from user input]
+
+Brief description of what must be true.
 
-Write `.beads/artifacts/<bead-id>/spec.md`.
+#### Scenarios
 
-Treat `spec.md` as a **short task card** (one screen): goal + success criteria + constraints. Put the detailed plan and task breakdown in `prd.md`.
+**WHEN** [user/system does action]
+**THEN** [expected outcome]
+
+**WHEN** [edge case condition]
+**THEN** [expected behavior]
+
+## Non-Functional Requirements
+
+- **Performance:** [from constraints]
+- **Security:** [from constraints]
+- **Compatibility:** [from constraints]
+
+## Out of Scope
+
+- [Explicitly excluded capability]
+```
+
+### For prd.md (--prd flag)
+
+Fill in the PRD template with goal, scope, and tasks:
 
 ```markdown
-# [Title]
+# Beads PRD Template
 
-**Bead:** <bead-id>
-**Created:** [date]
+**Bead:** $ARGUMENTS
+**Created:** [today]
+**Status:** Draft
 
 ## Goal
 
-[1-2 sentences: What and why]
+[From user input - what are we building and why]
 
-## Success Criteria
+## Scope
 
-- [ ] [Criterion 1]
-  - Verify: `[command]`
-- [ ] [Criterion 2]
-  - Verify: `[command]`
+### In-Scope
 
-## Constraints
+- [From user input]
 
-**Must:** [required]
-**Never:** [forbidden]
+### Out-of-Scope
 
-## PRD (Optional)
+- [Explicitly excluded]
 
-If this task has a PRD, keep details there:
+## Success Criteria
 
-- `.beads/artifacts/<bead-id>/prd.md`
-- `.beads/artifacts/<bead-id>/prd.json` (generated)
+- [ ] [Measurable criterion]
+  - Verify: `[command]`
 
-## Notes
+## Tasks
 
-[only brief context here; details belong in prd.md]
-```
+### [Task Title] [category]
 
-## If Epic: Create Subtasks
+[End state description]
 
-```bash
-# First task (no blockers)
-bd create "[subtask 1]" -t task -p 2
+**Verification:**
 
-# Second task (blocked by first)
-bd create "[subtask 2]" -t task -p 2
-bd dep add bd-[second] bd-[first] --type blocks
+- [Command or check]
 ```
 
-Visualize:
+---
 
-!`bd dep tree bd-[epic]`
+## Phase 5: Validate Spec
 
-## Optional: Create a PRD (Recommended for features)
+Before saving, validate the spec:
 
-If the work is more than a small one-off change, create a PRD alongside the spec.
+- [ ] All requirements have WHEN/THEN scenarios?
+- [ ] Scenarios are testable (not vague)?
+- [ ] Out of scope is defined?
+- [ ] Non-functional requirements addressed?
 
-- Template: `.opencode/memory/_templates/prd.md`
-- Output: `.beads/artifacts/<bead-id>/prd.md`
+If validation fails, ask user for missing information.
 
-```typescript
-skill({ name: "prd" });
-```
+---
 
-Write the PRD so it includes a `## Tasks` section (each `### ... [category]` with `**Verification:**` bullets).
+## Phase 6: Save and Report
 
-After PRD is written, convert it to executable tasks:
+Save the filled template to the bead artifacts folder.
 
-```typescript
-skill({ name: "prd-task" });
+```bash
+# Verify file was created
+cat "$BEAD_DIR/spec.md"
 ```
 
-This generates:
+Update bead with note:
 
-- `.beads/artifacts/<bead-id>/prd.json`
-- `.beads/artifacts/<bead-id>/progress.txt`
+```bash
+bd note $ARGUMENTS "Created spec.md with [N] requirements"
+```
 
-## Sync
+## Record Learning (If Significant)
 
-```bash
-bd sync
+If you discovered patterns or made decisions worth remembering:
+
+```typescript
+observation({
+  type: "pattern", // or "decision"
+  title: "[Domain] spec pattern for [type of feature]",
+  narrative: "When creating specs for [this type], include...",
+  concepts: "[domain keywords]",
+  bead_id: "$ARGUMENTS",
+  confidence: "medium",
+});
 ```
 
+---
+
 ## Output
 
 ```
-Created: bd-[id]
+Created: $ARGUMENTS
+━━━━━━━━━━━━━━━━━━━
 
-Type: [task/bug/feature/epic]
-Priority: [0-4]
-Spec: .beads/artifacts/bd-[id]/spec.md
+Artifacts:
+├── .beads/artifacts/$ARGUMENTS/spec.md [NEW]
+└── .beads/artifacts/$ARGUMENTS/proposal.md [if --proposal]
 
-Next:
-- `/start bd-[id]` (recommended)
-- or `/implement bd-[id]` (direct implementation)
+Requirements: [N] defined
+Scenarios: [N] WHEN/THEN pairs
+
+Next: /research $ARGUMENTS (optional)
+      /plan $ARGUMENTS
 ```
 
-If epic with subtasks:
+---
 
-```
-Created: bd-[epic] (Epic)
+## Examples
+
+```bash
+# Create standard spec
+/create bd-feat-auth
 
-Subtasks:
-├── bd-[epic].1: [title] ← READY
-├── bd-[epic].2: [title] ← blocked by .1
-└── bd-[epic].3: [title] ← blocked by .2
+# Create PRD (combined format)
+/create bd-feat-auth --prd
 
-Next: /implement bd-[epic].1
+# Create proposal first (for epics)
+/create bd-epic-redesign --proposal
 ```
+
+---
+
+## Related Commands
+
+| Need               | Command                |
+| ------------------ | ---------------------- |
+| Research first     | `/research $ARGUMENTS` |
+| Plan after spec    | `/plan $ARGUMENTS`     |
+| Create bead itself | `bd create "Title"`    |

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

@@ -11,8 +11,27 @@ subtask: true
 
 ```typescript
 skill({ name: "beads" });
+skill({ name: "memory-system" });
 ```
 
+## Check Memory First
+
+Search for existing design decisions and patterns:
+
+```typescript
+// Find similar design work
+memory_search({ query: "[component/page name] design UI", limit: 3 });
+
+// Find design system decisions
+memory_search({ query: "design system colors typography", limit: 3 });
+```
+
+Review findings for:
+
+- Existing aesthetic direction decisions
+- Color and typography choices already made
+- UI patterns that worked well
+
 ## Phase 1: Context Discovery
 
 Parse `$ARGUMENTS` to determine design task:
@@ -565,6 +584,22 @@ Before finalizing, verify design does NOT have ALL of these together:
 **Quick design:** Output inline, no save needed
 **Full design:** Save to `.opencode/memory/design/specs/[YYYY-MM-DD]-[topic].md`
 
+### Record Design Decisions
+
+For significant design choices, create an observation:
+
+```typescript
+observation({
+  type: "decision",
+  title: "Design direction for [component/page]",
+  narrative: "Chose [aesthetic direction] because [rationale]...",
+  facts: "[key design tokens, colors, typography choices]",
+  concepts: "design, ui, [component type], [aesthetic]",
+  bead_id: "$ARGUMENTS", // if applicable
+  confidence: "high",
+});
+```
+
 ### Create Implementation Tasks
 
 For component/page designs:
@@ -602,10 +637,8 @@ If bead exists in `$ARGUMENTS`, design within `.beads/artifacts/<bead-id>/spec.m
 
 ## Related Commands
 
-| Need                  | Command                |
-| --------------------- | ---------------------- |
-| Audit existing system | `/design-audit`        |
-| Analyze mockup        | `/analyze-mockup`      |
-| Implement design      | `/implement`           |
-| Check accessibility   | `/accessibility-check` |
-| Fix UI issues         | `/fix-ui`              |
+| Need                 | Command         |
+| -------------------- | --------------- |
+| Review existing UI   | `/ui-review`    |
+| Start implementation | `/start <bead>` |
+| Ship implementation  | `/ship <bead>`  |

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

@@ -8,6 +8,28 @@ agent: build
 
 You're pausing work on a task. Save state so the next session can pick up cleanly.
 
+## Load Skills
+
+```typescript
+skill({ name: "beads" });
+skill({ name: "session-management" });
+skill({ name: "memory-system" });
+```
+
+## Check Memory for Context
+
+Before creating handoff, search for related work:
+
+```typescript
+// Find previous handoffs and sessions for this bead
+memory_search({ query: "$ARGUMENTS handoff progress", limit: 3 });
+
+// Find related decisions and learnings
+memory_search({ query: "[bead description keywords]", limit: 3 });
+```
+
+Review findings to include relevant context in the handoff.
+
 ## Why Handoff?
 
 - Context window getting full

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

@@ -1,14 +1,20 @@
 ---
 description: Initialize project for AI-assisted development (creates AGENTS.md + memory files)
 argument-hint: "[--deep] [--skip-questions]"
-agent: plan
-subtask: true
+agent: build
 ---
 
 # Init: $ARGUMENTS
 
 One command to onboard a project. Creates project-root AGENTS.md and populates memory files.
 
+## Load Skills
+
+```typescript
+skill({ name: "memory-system" });
+skill({ name: "index-knowledge" });
+```
+
 ## Options
 
 - `--deep`: Comprehensive research (~100+ tool calls). Git history, patterns, contributors, subsystem detection.
@@ -148,86 +154,49 @@ If the repo is large or keeps changing (monorepos especially), generate/refresh
 
 ## Phase 5: Populate Memory Files
 
-### .opencode/memory/user.md
-
-```markdown
----
-purpose: User identity, preferences, communication style
-updated: [today]
----
-
-# User Profile
-
-## Identity
+Read templates, then use `write` tool to create actual markdown files:
 
-- Name: [from git/questions]
-- Git contributor: [email/username]
+```typescript
+// 1. Read templates to understand structure
+read({ filePath: ".opencode/memory/_templates/user.md" });
+read({ filePath: ".opencode/memory/_templates/tech-stack.md" });
 
-## Preferences
+// 2. Use WRITE tool to create/update actual markdown files
+// ⚠️ IMPORTANT: memory-update writes to SQLite, NOT markdown files!
+// Use write() for .md files, memory-update() for SQLite storage
 
-- Communication: [terse/detailed]
-- Workflow: [auto-commit/ask-first]
+write({
+  filePath: ".opencode/memory/project/user.md",
+  content: "..." // Populated from Phase 1 answers
+});
 
-## Rules
-
-[from Phase 1]
+write({
+  filePath: ".opencode/memory/project/tech-stack.md",
+  content: "..." // Populated from Phase 2 detection
+});
 ```
 
-### .opencode/memory/project/commands.md
-
-```markdown
----
-purpose: Build, test, lint, deploy commands
-updated: [today]
----
+**Critical distinction:**
+- `write()` → Updates **markdown files** on disk
+- `memory-update()` → Writes to **SQLite database** (memory system)
 
-# Commands
+### .opencode/memory/project/user.md
 
-## Build
+Populate from Phase 1 answers:
+- Identity (name, git contributor)
+- Communication preferences (terse/detailed)
+- Workflow preferences (auto-commit/ask-first)
+- Custom rules
 
-`[detected and validated]`
+### .opencode/memory/project/tech-stack.md
 
-## Test
+Populate from Phase 2 detection:
+- Framework & version
+- Language & runtime
+- Key dependencies with versions
+- Key constraints
 
-`[detected]`
-Single test: `[syntax with example]`
-
-## Lint
-
-`[detected]`
-
-## Dev Server
-
-`[detected]`
-```
-
-### .opencode/memory/project/architecture.md
-
-```markdown
----
-purpose: Key modules, directory structure
-updated: [today]
----
-
-# Architecture
-
-## Structure
-
-[detected directory layout with purpose annotations]
-
-## Key Modules
-
-[identified entry points, core modules, their responsibilities]
-
-## Data Flow
-
-[how data moves through the system - if detectable]
-```
-
-### With --deep, also create:
-
-- `project/conventions.md` - from git log analysis
-- `project/gotchas.md` - from bug-fix patterns in history
+**Note:** AI discovers commands, architecture, conventions, and gotchas organically and saves via `observation` tool.
 
 ## Phase 6: Initialize Beads (if requested)
 
@@ -262,13 +231,15 @@ Initialization Complete
 Files created:
 - ./AGENTS.md ([N] lines)
 - .opencode/memory/user.md
-- .opencode/memory/project/commands.md
-- .opencode/memory/project/architecture.md
+- .opencode/memory/project/tech-stack.md
 [- .beads/ (if initialized)]
 
 Tech stack: [detected]
 Commands validated: [yes/no]
 
+Note: Commands, architecture, conventions, and gotchas are discovered
+organically and saved via the observation tool as the AI works.
+
 Suggested next steps:
 1. Review AGENTS.md and adjust boundaries
 2. Run /review-codebase to check conventions
@@ -280,11 +251,11 @@ Suggested next steps:
 ```
 ./AGENTS.md                              # Project-specific rules (created, <60 lines)
 .opencode/AGENTS.md                      # Global rules (untouched)
-.opencode/memory/user.md                 # User preferences (created)
-.opencode/memory/project/commands.md     # Build commands (created)
-.opencode/memory/project/architecture.md # Structure (created)
-.opencode/memory/project/conventions.md  # Patterns (--deep only)
-.opencode/memory/project/gotchas.md      # Warnings (--deep only)
+.opencode/memory/_templates/user.md      # User template
+.opencode/memory/_templates/tech-stack.md # Tech stack template
+.opencode/memory/project/user.md         # User preferences (created from template)
+.opencode/memory/project/tech-stack.md   # Tech stack (created from template)
+.opencode/memory/observations/           # Learnings captured organically by AI
 [packages/*/AGENTS.md]                   # Subsystem rules (--deep, if requested)
 ```