opencodekit 0.16.14 → 0.16.17

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

@@ -1,558 +1,106 @@
 ---
-description: Create implementation plan for a bead with subtask hierarchy
-argument-hint: "<bead-id> [--create-beads] [--parallel]"
+description: Create detailed implementation plan with TDD steps for a bead
+argument-hint: "<bead-id> [--create-beads]"
 agent: plan
 ---
 
 # Plan: $ARGUMENTS
 
-You're creating an implementation plan with proper Epic → Task → Subtask hierarchy and subagent research.
+Create a detailed implementation plan with TDD steps. Optional deep-planning between `/start` and `/ship`.
 
-> **Lifecycle context:** Ideation → Design → Specification → Task Conversion → **Planning** → Implementation → Verification
+> **Workflow:** `/create` → `/start <id>` → **`/plan <id>`** (optional) → `/ship <id>`
+>
+> ⛔ Bead MUST be `in_progress` with `prd.md`. Use `/start` first.
+>
+> **When to use:** Complex tasks where PRD verification steps aren't enough guidance. Skip for simple tasks.
 
-## Parse Arguments
-
-| Argument         | Default  | Description                               |
-| ---------------- | -------- | ----------------------------------------- |
-| `<bead-id>`      | required | The bead to plan                          |
-| `--create-beads` | false    | Create child beads after planning         |
-| `--parallel`     | false    | Run aggressive parallel subagent research |
-
-## Load Skills & Context
+## Load Skills
 
 ```typescript
-skill({ name: "development-lifecycle" }); // Phase guidance
 skill({ name: "beads" });
-skill({ name: "deep-research" });
-skill({ name: "executing-plans" });
-skill({ name: "writing-plans" });
-skill({ name: "subagent-driven-development" });
-skill({ name: "memory-system" });
-```
-
-```bash
-br show $ARGUMENTS
-```
-
-Check for existing artifacts:
-
-```bash
-cat .beads/artifacts/$ARGUMENTS/prd.md 2>/dev/null || echo "No PRD found"
-cat .beads/artifacts/$ARGUMENTS/research.md 2>/dev/null || echo "No research found"
-```
-
-**If prd.md missing:** "Create a PRD first using `/create \"description\"` command."
-
-**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 |
-| ----------- | ----------------------------- | ---------- |
-| `prd.md`    | Goal, scope, success criteria | 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]", limit: 3 });
-
-// Find related patterns and decisions
-memory_search({ query: "[domain keywords] gotchas patterns", limit: 3 });
-```
-
-Review findings for:
-
-- Similar plans that worked well (reuse structure)
-- Patterns and decisions already made
-- Gotchas to avoid in planning
-
-If memory search fails (Ollama not running), continue to subagent research.
-
----
-
-## Phase 1: Parallel Subagent Research
-
-Gather context before designing. Run both in parallel:
-
-```typescript
-// Codebase patterns - run in parallel with scout
-Task({
-  subagent_type: "explore",
-  description: "Explore codebase for planning",
-  prompt: `For planning $ARGUMENTS, research the codebase:
-    1. Find similar implementations or patterns
-    2. Identify affected files and their structure
-    3. Find related tests and testing patterns
-    4. Check for potential conflicts with in-progress work
-    Return: File paths, code patterns, test approach, conflicts`,
-});
-
-// External best practices - run in parallel with explore
-Task({
-  subagent_type: "scout",
-  description: "Research implementation approaches",
-  prompt: `Research implementation approaches for $ARGUMENTS:
-    1. Best practices from official documentation
-    2. Common patterns in open source projects
-    3. Pitfalls and anti-patterns to avoid
-    Return: Recommendations, code examples, warnings`,
-});
-
-// Both run in parallel, results available immediately
-```
-
-**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
-
-Determine the right level of granularity.
-
-### Hierarchy Decision Tree
-
-```
-Is this work...
-├── Single domain, 2-3 files, ~50 tool calls?
-│   └── Keep as single bead → Skip to "Generate Design Options"
-│
-├── Crosses domains (frontend + backend)?
-│   └── Create task per domain
-│
-├── Has natural phases (setup → implement → test)?
-│   └── Create task per phase
-│
-├── Could benefit from parallel agents?
-│   └── Create independent tasks
-│
-└── Would take multiple sessions?
-    └── Create epic with task breakdown
-```
-
-### Size Estimation Guide
-
-| Size | Tool Calls | Duration  | Hierarchy Level |
-| ---- | ---------- | --------- | --------------- |
-| S    | ~10        | 30 min    | Subtask         |
-| M    | ~30        | 1-2 hours | Task            |
-| L    | ~100       | 4-8 hours | Task (or Epic)  |
-| XL   | 100+       | Days      | Epic required   |
-
-**If XL detected:** "This requires epic-level decomposition. Creating subtasks is mandatory."
-
----
-
-## Phase 3: Generate Design Options
-
-Present 2-3 implementation approaches:
-
-```markdown
-## Design Options for $ARGUMENTS
-
-### Option A: [Name]
-
-**Approach:** [1-2 sentences]
-
-**Changes:**
-
-- `src/foo.ts` - [what]
-- `src/bar.ts` - [what]
-
-**Pros:** [list]
-**Cons:** [list]
-**Effort:** [S/M/L] (~N tool calls)
-
----
-
-### Option B: [Name]
-
-**Approach:** [1-2 sentences]
-
-**Changes:**
-
-- `src/different.ts` - [what]
-
-**Pros:** [list]
-**Cons:** [list]
-**Effort:** [S/M/L] (~N tool calls)
-
----
-
-### Recommendation
-
-Option [X] because [reason].
-
-Decomposition: [Single bead | X tasks | X tasks with subtasks]
-```
-
-Save to `.beads/artifacts/$ARGUMENTS/design.md`.
-
-**STOP. Use question tool to ask user to pick an option:**
-
-```typescript
-question({
-  questions: [
-    {
-      header: "Design",
-      question: "Which implementation approach should I use for $ARGUMENTS?",
-      options: [
-        { label: "Option A (Recommended)", description: "[Option A summary]" },
-        { label: "Option B", description: "[Option B summary]" },
-        { label: "Option C", description: "[Option C summary]" },
-      ],
-    },
-  ],
-});
-```
-
-Wait for user's answer before proceeding.
-
----
-
-## Phase 4: Create Task Hierarchy
-
-After user approval, design the hierarchy.
-
-### For Single Bead (S/M size)
-
-Skip hierarchy, go directly to plan.md.
-
-### For Multi-Task Work (L/XL size)
-
-Design the decomposition:
-
-```markdown
-## Task Breakdown
-
-### Task 1: [Foundation/Setup] [S]
-
-**Domain:** [backend/frontend/infra]
-**Blocked by:** None
-**Work:**
-
-- [Specific deliverable]
-- [Specific deliverable]
-
-### Task 2: [Core Implementation] [M]
-
-**Domain:** [backend/frontend/infra]
-**Blocked by:** Task 1
-**Work:**
-
-- [Specific deliverable]
-
-**Subtasks (if complex):**
-
-- 2.1: [Atomic unit of work] [S]
-- 2.2: [Atomic unit of work] [S] → blocked by 2.1
-
-### Task 3: [Integration/Testing] [S]
-
-**Domain:** [testing]
-**Blocked by:** Task 2
-**Work:**
-
-- [Specific deliverable]
-```
-
----
-
-## Phase 5: Create Child Beads (if --create-beads)
-
-With user approval or `--create-beads` flag:
-
-```bash
-# Get parent bead ID
-PARENT=$ARGUMENTS
-
-# Task 1 (no blockers - starts immediately)
-br create "[Task 1 title]" --type task --priority 2
-# Capture: br-xxx1
-
-# Link to parent
-br dep add br-xxx1 $PARENT
-
-# Task 2 (blocked by Task 1)
-br create "[Task 2 title]" --type task --priority 2
-# Capture: br-xxx2
-
-br dep add br-xxx2 $PARENT
-br dep add br-xxx2 br-xxx1  # br-xxx2 blocked by br-xxx1
-
-# Task 3 (blocked by Task 2)
-br create "[Task 3 title]" --type task --priority 2
-# Capture: br-xxx3
-
-br dep add br-xxx3 $PARENT
-br dep add br-xxx3 br-xxx2  # br-xxx3 blocked by br-xxx2
+skill({ name: "writing-plans" }); // TDD plan format
 ```
 
-### Create Subtasks (for complex tasks)
-
-```bash
-# For Task 2, create subtasks:
-br create "[Subtask 2.1 title]" --type subtask --priority 2
-# Capture: br-xxx2.1
-
-br dep add br-xxx2.1 br-xxx2
-
-br create "[Subtask 2.2 title]" --type subtask --priority 2
-# Capture: br-xxx2.2
+## Parse Arguments
 
-br dep add br-xxx2.2 br-xxx2
-br dep add br-xxx2.2 br-xxx2.1  # Sequential dependency
-```
+| Argument         | Default  | Description                       |
+| ---------------- | -------- | --------------------------------- |
+| `<bead-id>`      | required | The bead to plan                  |
+| `--create-beads` | false    | Create child beads for each phase |
 
-### Verify Hierarchy
+## Phase 1: Guards
 
 ```bash
-br dep tree $ARGUMENTS
-```
-
----
-
-## Phase 6: Create Plan Document
-
-Write `.beads/artifacts/$ARGUMENTS/plan.md`:
-
-```markdown
-# Implementation Plan: [Title]
-
-**Bead:** $ARGUMENTS
-**Approach:** [Selected option]
-**Total estimate:** ~N tool calls ([X-Y hours])
-
-## Hierarchy
-```
-
-$ARGUMENTS (Epic/Task)
-├── br-xxx1: [Title] [S] ← READY
-├── br-xxx2: [Title] [M] → blocked by br-xxx1
-│ ├── br-xxx2.1: [Subtask] [S]
-│ └── br-xxx2.2: [Subtask] [S] → blocked by br-xxx2.1
-└── br-xxx3: [Title] [S] → blocked by br-xxx2
-
+br show $ARGUMENTS
+ls .beads/artifacts/$ARGUMENTS/
 ```
 
----
-
-## Task 1: [Title] [S]
-
-**Bead:** br-xxx1
-**Estimate:** ~10 tool calls (30 min)
-**Blocked by:** None
-
-**Files:**
-- `src/foo.ts`
-
-**Changes:**
-- [ ] [Specific change with detail]
-- [ ] [Specific change with detail]
-
-**Verify:** `npm test -- foo.test.ts`
-
----
-
-## Task 2: [Title] [M]
-
-**Bead:** br-xxx2
-**Estimate:** ~30 tool calls (1-2 hours)
-**Blocked by:** Task 1
-
-**Subtasks:**
-
-### 2.1: [Subtask Title] [S]
-
-**Bead:** br-xxx2.1
-**Files:** `src/bar.ts`
-**Changes:**
-- [ ] [Specific change]
-
-**Verify:** `npm test -- bar.test.ts`
-
-### 2.2: [Subtask Title] [S]
-
-**Bead:** br-xxx2.2
-**Blocked by:** 2.1
-**Files:** `src/baz.ts`
-**Changes:**
-- [ ] [Specific change]
-
-**Verify:** `npm test -- baz.test.ts`
-
----
+Verify:
 
-## Task 3: [Title] [S]
+- Bead is `in_progress`
+- `prd.md` exists
+- If `plan.md` already exists, ask user: overwrite or skip?
 
-**Bead:** br-xxx3
-**Estimate:** ~10 tool calls (30 min)
-**Blocked by:** Task 2
+## Phase 2: Research
 
-**Files:**
-- `tests/integration/`
+Read the PRD and extract tasks, success criteria, affected files, scope.
 
-**Changes:**
-- [ ] [Specific change]
+Spawn parallel agents to gather implementation context:
 
-**Verify:** `npm run test:integration`
+| Agent     | Purpose                                                              |
+| --------- | -------------------------------------------------------------------- |
+| `explore` | Codebase patterns, affected file structure, test patterns, conflicts |
+| `scout`   | Best practices, common patterns, pitfalls                            |
 
----
+## Phase 3: Decompose
 
-## Final Verification
+Assess size to determine plan structure:
 
-- [ ] All acceptance criteria from prd.md met
-- [ ] Full test suite: `npm test`
-- [ ] Type check: `npm run typecheck`
-- [ ] Lint: `npm run lint`
+| Size          | Files                                    | Approach |
+| ------------- | ---------------------------------------- | -------- |
+| S (1-3 files) | Single plan, no phases                   |
+| M (3-8 files) | 2-3 phases                               |
+| L (8+ files)  | Create child beads with `--create-beads` |
 
-## Rollback Plan
+## Phase 4: Write Plan
 
-If issues detected after deployment:
-1. [Rollback step 1]
-2. [Rollback step 2]
-```
+Write `.beads/artifacts/$ARGUMENTS/plan.md` following the `writing-plans` skill format:
 
----
+- **Exact file paths** — never "add to the relevant file"
+- **Complete code** — never "add validation logic here"
+- **Exact commands with expected output**
+- **TDD order** — test first, then implementation
+- **Each step is 2-5 minutes** — one action per step
+- **Tasks map to PRD tasks**
 
-## Phase 7: Parallel Task Execution (if --parallel)
+## Phase 5: Create Child Beads (if --create-beads or L size)
 
-After creating hierarchy, execute READY tasks in parallel:
+For large work, create child beads for each plan phase:
 
 ```bash
-# Check what's ready to start
-br ready --json
+CHILD=$(br create "[Phase title]" --type task --json | jq -r '.id')
+br dep add $CHILD $ARGUMENTS
 ```
 
-```typescript
-// Fire all READY tasks in parallel with beads integration
-for (const task of readyTasks) {
-  background_start({
-    agent: "build",
-    prompt: `Execute ${task.id}: ${task.title}
-
-      Context: Part of plan for $ARGUMENTS
-      Spec: See .beads/artifacts/$ARGUMENTS/plan.md
-
-      Requirements:
-      - Complete work items for this task
-      - Run verification commands from plan
-      - Commit with bead ID in message
+## Phase 6: Report
 
-      Return: Changes made, verification results`,
-    beadId: task.id,
-    autoCloseBead: true,
-    title: `exec-${task.id}`
-  })
-}
-
-// Collect results
-for (const taskId of backgroundTaskIds) {
-  background_output({ taskId })  // → beadClosed: true
-}
-
-// Check newly unblocked tasks
-br ready  // → Next wave of tasks now READY
-
-// Cleanup
-background_cancel({ all: true })
-```
-
----
+Output:
 
-## Phase 8: Sync and Report
+1. Task count and total TDD steps
+2. Files affected
+3. Plan location (`.beads/artifacts/$ARGUMENTS/plan.md`)
+4. Child bead hierarchy (if created)
+5. Next step: `/ship $ARGUMENTS`
 
 ```bash
-br sync --flush-only
+br comments add $ARGUMENTS "Created plan.md with [N] tasks, [M] TDD steps"
 ```
 
-### Output (without child beads)
-
-```
-Plan Complete: $ARGUMENTS
-━━━━━━━━━━━━━━━━━━━━━━━━
-
-Approach: [Selected option]
-Tasks: 1 (single bead)
-Estimate: ~N tool calls
-
-Artifacts:
-├── .beads/artifacts/$ARGUMENTS/design.md
-└── .beads/artifacts/$ARGUMENTS/plan.md
-
-Next: /implement $ARGUMENTS
-```
-
-### Output (with child beads)
-
-```
-Plan Complete: $ARGUMENTS (Epic)
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-Approach: [Selected option]
-Total estimate: ~N tool calls ([X-Y hours])
-
-Hierarchy:
-├── br-xxx1: [Title] [S] ← READY
-├── br-xxx2: [Title] [M] → blocked by br-xxx1
-│   ├── br-xxx2.1: [Subtask] [S]
-│   └── br-xxx2.2: [Subtask] [S]
-└── br-xxx3: [Title] [S] → blocked by br-xxx2
-
-Artifacts:
-├── .beads/artifacts/$ARGUMENTS/design.md
-└── .beads/artifacts/$ARGUMENTS/plan.md
-
-Ready to start: br-xxx1
-
-Next: /start br-xxx1
-```
-
----
-
-## Subagent Delegation Summary
-
-| Phase              | Subagent   | Purpose                         |
-| ------------------ | ---------- | ------------------------------- |
-| Research           | `@explore` | Find codebase patterns          |
-| Research           | `@scout`   | Find best practices             |
-| Design options     | None       | Planner creates                 |
-| Hierarchy creation | None       | Planner uses `br` CLI           |
-| Implementation     | `@build`   | Delegated via `/start`, `/ship` |
-
-**Key Rule:** Planner is read-only. Creates structure and artifacts. Build agent executes.
-
----
-
 ## Related Commands
 
-| Need                 | Command                  |
-| -------------------- | ------------------------ |
-| Research before plan | `/research <bead-id>`    |
-| Start first task     | `/start <first-task-id>` |
-| Ship the work        | `/ship <bead-id>`        |
-| View hierarchy       | `br dep tree <bead-id>`  |
+| Need           | Command       |
+| -------------- | ------------- |
+| Create spec    | `/create`     |
+| Start working  | `/start <id>` |
+| Execute plan   | `/ship <id>`  |
+| Research first | `/research`   |