opencodekit 0.15.21 → 0.16.0

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

@@ -1,171 +1,277 @@
 ---
-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:
-
-1. What problem are we solving?
-2. Bug, feature, or task?
-3. What's the acceptance criteria?
-4. Any constraints?
+```typescript
+skill({ name: "beads" });
+skill({ name: "brainstorming" });
+```
 
-Keep it brief. Don't over-engineer the interview.
+## Load Bead Context
 
-## Assess Complexity
+```bash
+bd show $ARGUMENTS
+```
 
-**Simple** (single bead): One file, one clear action, ~30 min or less
-**Complex** (needs decomposition): Multiple domains, natural phases, hours of work
+Check what artifacts already exist:
 
-If complex, ask: "This looks like it needs decomposition. Create an epic with subtasks?"
+```bash
+ls .beads/artifacts/$ARGUMENTS/ 2>/dev/null || echo "No artifacts yet"
+```
 
-## Create The Bead
+---
 
-Simple task:
+## Phase 1: Setup Artifact Directory
 
 ```bash
-bd create "[title]" -t task -p 2
+BEAD_DIR=".beads/artifacts/$ARGUMENTS"
+mkdir -p "$BEAD_DIR"
 ```
 
-Bug:
+---
+
+## 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 bug -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"
 ```
 
-Feature:
+---
 
-```bash
-bd create "[title]" -t feature -p 2
+## 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
+    },
+  ],
+});
 ```
 
-Epic (if decomposing):
+### Research Existing Patterns (Optional)
 
-```bash
-bd create "[title]" -t epic -p 1
+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`,
+});
 ```
 
-## Create Spec
+---
 
-Write `.beads/artifacts/<bead-id>/spec.md`.
+## Phase 4: Fill In Template
 
-Treat `spec.md` as a **short task card** (one screen): goal + success criteria + constraints. Put the detailed plan and task breakdown in `prd.md`.
+### For spec.md (default)
 
-```markdown
-# [Title]
+Fill in the template with WHEN/THEN scenarios:
 
-**Bead:** <bead-id>
-**Created:** [date]
+```markdown
+# Specification
 
-## Goal
+**Bead:** $ARGUMENTS
+**Proposal:** N/A
+**Date:** [today]
 
-[1-2 sentences: What and why]
+## Requirements
 
-## Success Criteria
+### [Requirement from user input]
 
-- [ ] [Criterion 1]
-  - Verify: `[command]`
-- [ ] [Criterion 2]
-  - Verify: `[command]`
+Brief description of what must be true.
 
-## Constraints
+#### Scenarios
 
-**Must:** [required]
-**Never:** [forbidden]
+**WHEN** [user/system does action]
+**THEN** [expected outcome]
 
-## PRD (Optional)
+**WHEN** [edge case condition]
+**THEN** [expected behavior]
 
-If this task has a PRD, keep details there:
+## Non-Functional Requirements
 
-- `.beads/artifacts/<bead-id>/prd.md`
-- `.beads/artifacts/<bead-id>/prd.json` (generated)
+- **Performance:** [from constraints]
+- **Security:** [from constraints]
+- **Compatibility:** [from constraints]
 
-## Notes
+## Out of Scope
 
-[only brief context here; details belong in prd.md]
+- [Explicitly excluded capability]
 ```
 
-## If Epic: Create Subtasks
+### For prd.md (--prd flag)
 
-```bash
-# First task (no blockers)
-bd create "[subtask 1]" -t task -p 2
+Fill in the PRD template with goal, scope, and tasks:
 
-# Second task (blocked by first)
-bd create "[subtask 2]" -t task -p 2
-bd dep add bd-[second] bd-[first] --type blocks
-```
+```markdown
+# Beads PRD Template
 
-Visualize:
+**Bead:** $ARGUMENTS
+**Created:** [today]
+**Status:** Draft
 
-!`bd dep tree bd-[epic]`
+## Goal
 
-## Optional: Create a PRD (Recommended for features)
+[From user input - what are we building and why]
 
-If the work is more than a small one-off change, create a PRD alongside the spec.
+## Scope
 
-- Template: `.opencode/memory/_templates/prd.md`
-- Output: `.beads/artifacts/<bead-id>/prd.md`
+### In-Scope
 
-```typescript
-skill({ name: "prd" });
-```
+- [From user input]
 
-Write the PRD so it includes a `## Tasks` section (each `### ... [category]` with `**Verification:**` bullets).
+### Out-of-Scope
 
-After PRD is written, convert it to executable tasks:
+- [Explicitly excluded]
 
-```typescript
-skill({ name: "prd-task" });
+## Success Criteria
+
+- [ ] [Measurable criterion]
+  - Verify: `[command]`
+
+## Tasks
+
+### [Task Title] [category]
+
+[End state description]
+
+**Verification:**
+
+- [Command or check]
 ```
 
-This generates:
+---
+
+## Phase 5: Validate Spec
+
+Before saving, validate the spec:
+
+- [ ] All requirements have WHEN/THEN scenarios?
+- [ ] Scenarios are testable (not vague)?
+- [ ] Out of scope is defined?
+- [ ] Non-functional requirements addressed?
+
+If validation fails, ask user for missing information.
 
-- `.beads/artifacts/<bead-id>/prd.json`
-- `.beads/artifacts/<bead-id>/progress.txt`
+---
+
+## Phase 6: Save and Report
 
-## Sync
+Save the filled template to the bead artifacts folder.
 
 ```bash
-bd sync
+# Verify file was created
+cat "$BEAD_DIR/spec.md"
 ```
 
-## Output
+Update bead with note:
 
+```bash
+bd note $ARGUMENTS "Created spec.md with [N] requirements"
 ```
-Created: bd-[id]
 
-Type: [task/bug/feature/epic]
-Priority: [0-4]
-Spec: .beads/artifacts/bd-[id]/spec.md
+---
+
+## Output
 
-Next:
-- `/start bd-[id]` (recommended)
-- or `/implement bd-[id]` (direct implementation)
 ```
+Created: $ARGUMENTS
+━━━━━━━━━━━━━━━━━━━
 
-If epic with subtasks:
+Artifacts:
+├── .beads/artifacts/$ARGUMENTS/spec.md [NEW]
+└── .beads/artifacts/$ARGUMENTS/proposal.md [if --proposal]
 
+Requirements: [N] defined
+Scenarios: [N] WHEN/THEN pairs
+
+Next: /research $ARGUMENTS (optional)
+      /plan $ARGUMENTS
 ```
-Created: bd-[epic] (Epic)
 
-Subtasks:
-├── bd-[epic].1: [title] ← READY
-├── bd-[epic].2: [title] ← blocked by .1
-└── bd-[epic].3: [title] ← blocked by .2
+---
 
-Next: /implement bd-[epic].1
+## Examples
+
+```bash
+# Create standard spec
+/create bd-feat-auth
+
+# Create PRD (combined format)
+/create bd-feat-auth --prd
+
+# 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

@@ -602,10 +602,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,13 @@ 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" });
+```
+
 ## Why Handoff?
 
 - Context window getting full

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

@@ -9,6 +9,13 @@ subtask: true
 
 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.
@@ -173,61 +180,32 @@ updated: [today]
 [from Phase 1]
 ```
 
-### .opencode/memory/project/commands.md
+### .opencode/memory/project/tech-stack.md
 
 ```markdown
 ---
-purpose: Build, test, lint, deploy commands
+purpose: Tech stack, constraints, and integrations for AI context injection
 updated: [today]
 ---
 
-# Commands
+# Tech Stack
 
-## Build
+## Framework & Language
 
-`[detected and validated]`
+- **Framework:** [detected, e.g., Next.js 15]
+- **Language:** [detected, e.g., TypeScript]
+- **Runtime:** [detected, e.g., Node.js 22]
 
-## Test
+## Key Dependencies
 
-`[detected]`
-Single test: `[syntax with example]`
+- [detected from package.json/go.mod/etc.]
 
-## Lint
+## Key Constraints
 
-`[detected]`
-
-## Dev Server
-
-`[detected]`
+- [detected or ask user]
 ```
 
-### .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 from the codebase and saves learnings via the `observation` tool. No need for static template files.
 
 ## Phase 6: Initialize Beads (if requested)
 
@@ -262,13 +240,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
@@ -281,10 +261,8 @@ 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/project/tech-stack.md   # Tech stack for context injection (created)
+.opencode/memory/observations/           # Learnings captured organically by AI
 [packages/*/AGENTS.md]                   # Subsystem rules (--deep, if requested)
 ```
 

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

@@ -20,6 +20,10 @@ You're creating an implementation plan with proper Epic → Task → Subtask hie
 
 ```typescript
 skill({ name: "beads" });
+skill({ name: "deep-research" });
+skill({ name: "executing-plans" });
+skill({ name: "writing-plans" });
+skill({ name: "subagent-driven-development" });
 ```
 
 ```bash
@@ -37,28 +41,38 @@ cat .beads/artifacts/$ARGUMENTS/research.md 2>/dev/null || echo "No research fou
 
 **If complexity > M and no research:** "Consider `/research $ARGUMENTS` first for better planning."
 
+## Templates Reference
+
+Copy templates from `.opencode/memory/_templates/` to bead artifacts folder:
+
+```bash
+# Copy templates to bead folder
+BEAD_DIR=".beads/artifacts/$ARGUMENTS"
+mkdir -p "$BEAD_DIR"
+
+# Copy design template (we'll fill it in Phase 3)
+cp .opencode/memory/_templates/design.md "$BEAD_DIR/design.md"
+
+# Copy tasks template (we'll fill it in Phase 6)
+cp .opencode/memory/_templates/tasks.md "$BEAD_DIR/tasks.md"
+```
+
+| Template    | Purpose                        | Phase Used |
+| ----------- | ------------------------------ | ---------- |
+| `spec.md`   | WHEN/THEN behavioral scenarios | Input      |
+| `design.md` | Architecture decision records  | Phase 3    |
+| `tasks.md`  | Numbered implementation steps  | Phase 6    |
+
 ## Check Memory First (Semantic Search)
 
 Before subagent research, check what we already know:
 
 ```typescript
 // Find similar past plans
-memory -
-  search({
-    query: "[bead title/description]",
-    mode: "semantic",
-    type: "bead",
-    limit: 3,
-  });
+memory_search({ query: "[bead title/description]", limit: 3 });
 
 // Find related patterns and decisions
-memory -
-  search({
-    query: "[domain keywords]",
-    mode: "semantic",
-    type: "observation",
-    limit: 3,
-  });
+memory_search({ query: "[domain keywords] gotchas patterns", limit: 3 });
 ```
 
 Review findings for:
@@ -104,6 +118,12 @@ Task({
 
 **Integrate findings into your plan.**
 
+## Skill Routing
+
+- Use **deep-research** when the domain is unfamiliar or ambiguous.
+- Use **writing-plans** when producing a detailed, step-by-step implementation plan.
+- Use **executing-plans** only when a complete plan already exists and needs execution.
+
 ---
 
 ## Phase 2: Analyze for Decomposition
@@ -528,8 +548,7 @@ Next: /start bd-xxx1
 
 | Need                 | Command                  |
 | -------------------- | ------------------------ |
-| Create spec first    | `/create <bead-id>`      |
 | Research before plan | `/research <bead-id>`    |
 | Start first task     | `/start <first-task-id>` |
+| Ship the work        | `/ship <bead-id>`        |
 | View hierarchy       | `bd dep tree <bead-id>`  |
-| Import external plan | `/import-plan`           |

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

@@ -78,21 +78,10 @@ Search for relevant observations and past work:
 
 ```typescript
 // Find observations related to this bead
-memory -
-  search({
-    query: "$ARGUMENTS [bead title/description]",
-    mode: "semantic",
-    type: "observation",
-    limit: 5,
-  });
+memory_search({ query: "$ARGUMENTS [bead title/description]", limit: 5 });
 
 // Find similar past work
-memory -
-  search({
-    query: "[bead description keywords]",
-    mode: "semantic",
-    limit: 3,
-  });
+memory_search({ query: "[bead description keywords]", limit: 3 });
 ```
 
 **Review findings** - past observations may contain:
@@ -183,11 +172,11 @@ bd update $ARGUMENTS --status in_progress
 
 Then continue with implementation:
 
-| Condition               | Command                                                  |
-| ----------------------- | -------------------------------------------------------- |
-| Swarm was restored      | Continue monitoring with `/implement $ARGUMENTS --swarm` |
-| No swarm, standard work | `/implement $ARGUMENTS`                                  |
-| Need to re-plan         | `/plan $ARGUMENTS`                                       |
+| Condition               | Command                                  |
+| ----------------------- | ---------------------------------------- |
+| Swarm was restored      | Continue with `/ship $ARGUMENTS --swarm` |
+| No swarm, standard work | `/ship $ARGUMENTS`                       |
+| Need to re-plan         | `/plan $ARGUMENTS`                       |
 
 ## If Context Is Too Stale