opencodekit 0.15.20 → 0.16.0

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

@@ -0,0 +1,277 @@
+---
+description: Create a specification for a bead using templates
+argument-hint: "<bead-id> [--prd] [--proposal]"
+agent: plan
+subtask: true
+---
+
+# Create: $ARGUMENTS
+
+Create structured artifacts for a bead using templates. This is the first step before planning.
+
+## Parse Arguments
+
+| 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) |
+
+## Load Skills
+
+```typescript
+skill({ name: "beads" });
+skill({ name: "brainstorming" });
+```
+
+## Load Bead Context
+
+```bash
+bd show $ARGUMENTS
+```
+
+Check what artifacts already exist:
+
+```bash
+ls .beads/artifacts/$ARGUMENTS/ 2>/dev/null || echo "No artifacts yet"
+```
+
+---
+
+## Phase 1: Setup Artifact Directory
+
+```bash
+BEAD_DIR=".beads/artifacts/$ARGUMENTS"
+mkdir -p "$BEAD_DIR"
+```
+
+---
+
+## 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
+# 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"
+```
+
+---
+
+## 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.
+
+#### Scenarios
+
+**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
+# Beads PRD Template
+
+**Bead:** $ARGUMENTS
+**Created:** [today]
+**Status:** Draft
+
+## Goal
+
+[From user input - what are we building and why]
+
+## Scope
+
+### In-Scope
+
+- [From user input]
+
+### Out-of-Scope
+
+- [Explicitly excluded]
+
+## Success Criteria
+
+- [ ] [Measurable criterion]
+  - Verify: `[command]`
+
+## Tasks
+
+### [Task Title] [category]
+
+[End state description]
+
+**Verification:**
+
+- [Command or check]
+```
+
+---
+
+## 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.
+
+---
+
+## Phase 6: Save and Report
+
+Save the filled template to the bead artifacts folder.
+
+```bash
+# Verify file was created
+cat "$BEAD_DIR/spec.md"
+```
+
+Update bead with note:
+
+```bash
+bd note $ARGUMENTS "Created spec.md with [N] requirements"
+```
+
+---
+
+## Output
+
+```
+Created: $ARGUMENTS
+━━━━━━━━━━━━━━━━━━━
+
+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
+```
+
+---
+
+## 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/{commands → 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/{commands → 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
@@ -46,6 +53,36 @@ git commit -m "WIP: $ARGUMENTS - [where you stopped]"
 
 Don't leave uncommitted work. The next session needs a clean starting point.
 
+## Persist Swarm State (If Active)
+
+If a swarm is active for this task, note its state for recovery:
+
+```typescript
+const teamName = "$ARGUMENTS-swarm";
+
+// Check if swarm is active
+const status = await swarm_monitor({
+  operation: "status",
+  team_name: teamName,
+});
+
+const stats = JSON.parse(status);
+if (stats.summary?.total_workers > 0) {
+  // Render current state for handoff
+  const ui = await swarm_monitor({
+    operation: "render_block",
+    team_name: teamName,
+  });
+  console.log(`✓ Swarm active (${stats.summary.total_workers} workers)`);
+  console.log(ui);
+
+  // Note in handoff that swarm was active
+  console.log("⚠️ Swarm is active - next session can resume with /resume");
+}
+```
+
+````
+
 ## Record Key Learnings (Before Handoff)
 
 If you discovered important patterns or gotchas during this session:
@@ -59,7 +96,7 @@ observation({
   files: "[affected files]",
   concepts: "[keywords for semantic search]",
 });
-```
+````
 
 **This auto-embeds** into the vector store. The next `/resume` will find it.
 
@@ -105,6 +142,11 @@ Decisions made:
 
 - [decision]: [why]
 
+## Swarm State
+
+[If swarm was active: "Swarm persisted - workers and progress will be restored"]
+[Otherwise: "No active swarm"]
+
 ## Blockers
 
 [If any blockers, list them. Otherwise "None"]

package/dist/template/.opencode/{commands → 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/{commands → 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/{commands → command}/research.md

@@ -85,29 +85,23 @@ grepsearch({ query: "<pattern>", language: "TypeScript" });
 
 // Option B: Swarm mode for complex multi-domain research
 // Use when researching 3+ different areas simultaneously
-const teamName = `research-${Date.now()}`;
 
-// Spawn research workers
+// Spawn research workers (results returned when all complete)
 Task({
   subagent_type: "explore",
   description: "Research domain A",
   prompt: `Research [domain A] for ${$ARGUMENTS}...
-Report via swarm-monitor: progress_update + mail_send to team ${teamName}`,
+Return: Key findings, file paths, patterns discovered`,
 });
 
 Task({
   subagent_type: "scout",
   description: "Research domain B",
   prompt: `Research [domain B] for ${$ARGUMENTS}...
-Report via swarm-monitor: progress_update + mail_send to team ${teamName}`,
+Return: Documentation, code examples, best practices`,
 });
 
-// Monitor progress
-const ui = await swarm_monitor({
-  operation: "render_block",
-  team_name: teamName,
-});
-console.log(ui);
+// Results available immediately when all workers complete
 ```
 
 ## Load Context

package/dist/template/.opencode/{commands → command}/resume.md

@@ -12,6 +12,7 @@ You're picking up where a previous session left off. Recover context, verify sta
 
 ```typescript
 skill({ name: "beads" });
+skill({ name: "beads-bridge" }); // For cross-session recovery
 ```
 
 ## Verify The Task Exists
@@ -77,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:
@@ -110,6 +100,36 @@ Read all available context:
 !`cat .beads/artifacts/$ARGUMENTS/plan.md 2>/dev/null`
 !`cat .beads/artifacts/$ARGUMENTS/research.md 2>/dev/null`
 
+## Recover Swarm State (If Active)
+
+Check if there was an active swarm for this task:
+
+```typescript
+// Check for active swarm state
+const teamName = "$ARGUMENTS-swarm";
+const status = await swarm_monitor({
+  operation: "status",
+  team_name: teamName,
+});
+
+const stats = JSON.parse(status);
+if (stats.summary?.total_workers > 0) {
+  console.log(`✓ Found active swarm with ${stats.summary.total_workers} workers`);
+
+  // Show current progress
+  const ui = await swarm_monitor({
+    operation: "render_block",
+    team_name: teamName,
+  });
+  console.log(ui);
+} else {
+  console.log("No active swarm session");
+}
+
+// Sync beads to OpenCode todos for subagent visibility
+beads_sync({ operation: "push" });
+```
+
 ## Check For Stale Context
 
 If handoff is more than 3 days old, things may have changed:
@@ -152,15 +172,11 @@ bd update $ARGUMENTS --status in_progress
 
 Then continue with implementation:
 
-```
-/implement $ARGUMENTS
-```
-
-Or if you 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