opencodekit 0.9.2 → 0.11.0

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

@@ -26,11 +26,24 @@ 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.
 
+Reserve files while planning:
+
+```typescript
+bd_reserve({
+  paths: [
+    ".beads/artifacts/<bead-id>/design.md",
+    ".beads/artifacts/<bead-id>/plan.md",
+  ],
+  reason: "Planning $ARGUMENTS",
+  ttl: 1200,
+});
+```
+
 ## Phase 2: Generate Design Options
 
-Present 2-3 approaches:
+Present 2-3 approaches with this format:
 
-```
+```markdown
 ## Design Options
 
 ### Option A: [Name]
@@ -38,191 +51,200 @@ Present 2-3 approaches:
 **Approach:** [1-2 sentence description]
 
 **Changes:**
+
 - `src/foo.ts` - [what changes]
 - `src/bar.ts` - [what changes]
 
-**Pros:**
-- [pro 1]
-- [pro 2]
+**Pros:** [bullet list]
+**Cons:** [bullet list]
 
-**Cons:**
-- [con 1]
+**Estimation:**
 
-**Effort:** [S/M/L]
+- Tool calls: ~[N] (S=5-20, M=20-50, L=50-100, XL=needs decomposition)
+- Files touched: [N]
+- Risk: [low/medium/high]
 
 ---
 
 ### Option B: [Name]
 
-**Approach:** [1-2 sentence description]
+[Same format]
 
-**Changes:**
-- `src/baz.ts` - [what changes]
+---
 
-**Pros:**
-- [pro 1]
+**Recommendation:** Option [A/B] because [reason].
+```
 
-**Cons:**
-- [con 1]
-- [con 2]
+Save to `.beads/artifacts/<bead-id>/design.md` with status `Pending Approval`.
 
-**Effort:** [S/M/L]
+## Phase 3: Get Approval
 
----
+**STOP and wait for human response.**
 
-**Recommendation:** Option [A/B] because [reason].
+```
+Pick an option (A/B/C), modify, or "none" to propose alternatives.
 ```
 
-## Phase 3: Save Design Document
+Do not proceed until user confirms.
 
-Save design options to `.beads/artifacts/<bead-id>/design.md`:
+## Phase 4: Create Plan with Task Contracts
+
+After approval, write `.beads/artifacts/<bead-id>/plan.md`:
 
 ```markdown
-# Design Options: [Title]
+# Implementation Plan: [Title]
 
 **Bead:** <bead-id>
 **Date:** <date>
-**Status:** Pending Approval
-
-## Problem Statement
-
-[What we're solving - from spec.md]
-
-## Options Considered
+**Approach:** [selected option name]
+**Estimation:** ~[N] tool calls, [N] files
 
-### Option A: [Name]
+## Dependency Graph
+```
 
-**Approach:** [1-2 sentence description]
+[Step 1] ──┬──> [Step 2a] ──┬──> [Step 4]
+│ │
+└──> [Step 2b] ──┘
+│
+└──> [Step 3] (can run parallel)
 
-**Changes:**
+````
 
-- `src/foo.ts` - [what changes]
-- `src/bar.ts` - [what changes]
+**Parallel Tracks:**
+- Track A: Steps 1 → 2a → 4
+- Track B: Steps 1 → 2b → 3 (independent after Step 1)
 
-**Pros:**
+## Tasks
 
-- [pro 1]
-- [pro 2]
+### Task 1: [Title]
 
-**Cons:**
+| Field         | Value                              |
+| ------------- | ---------------------------------- |
+| **Files**     | `src/foo.ts`                       |
+| **Input**     | [What this task receives/needs]    |
+| **Output**    | [What this task produces]          |
+| **Success**   | [Concrete verification criteria]   |
+| **Rollback**  | [How to undo if this fails]        |
+| **Depends**   | None                               |
+| **Effort**    | S (~10 tool calls)                 |
 
-- [con 1]
+**Changes:**
+- [ ] [Specific change 1]
+- [ ] [Specific change 2]
 
-**Effort:** [S/M/L]
+**Verification:**
+```bash
+[Actual command to verify success]
+````
 
 ---
 
-### Option B: [Name]
+### Task 2a: [Title]
 
-**Approach:** [1-2 sentence description]
+| Field        | Value                            |
+| ------------ | -------------------------------- |
+| **Files**    | `src/bar.ts`                     |
+| **Input**    | Output from Task 1               |
+| **Output**   | [What this produces]             |
+| **Success**  | [Test passes, type checks, etc.] |
+| **Rollback** | `git checkout src/bar.ts`        |
+| **Depends**  | Task 1                           |
+| **Effort**   | M (~30 tool calls)               |
 
 **Changes:**
 
-- `src/baz.ts` - [what changes]
-
-**Pros:**
-
-- [pro 1]
-
-**Cons:**
+- [ ] [Specific change]
 
-- [con 1]
-- [con 2]
+**Verification:**
 
-**Effort:** [S/M/L]
+```bash
+npm run test -- src/bar.test.ts
+```
 
 ---
 
-## Recommendation
-
-Option [A/B] because [reason].
-
-## Decision
+[Continue for all tasks...]
 
-**Chosen:** [To be filled after approval]
-**Rationale:** [To be filled after approval]
-```
+## Escape Hatches
 
-## Phase 4: Get Approval
+- **Max iterations per task:** 3 attempts before human intervention
+- **Checkpoint after:** Tasks 2a, 3 (high-risk points)
+- **Abort if:** [Condition that means we should stop]
 
-**STOP and wait for human response.**
-
-```
-Pick an option (A/B/C), modify, or "none" to propose alternatives.
-```
+## Final Verification
 
-Do not proceed until user confirms.
+- [ ] All task verifications pass
+- [ ] `npm run type-check` passes
+- [ ] `npm run test` passes
+- [ ] Manual smoke test: [specific action]
 
-## Phase 5: Update Design Decision
+## Risks
 
-After approval, update `.beads/artifacts/<bead-id>/design.md`:
+| Risk     | Likelihood | Impact | Mitigation      |
+| -------- | ---------- | ------ | --------------- |
+| [Risk 1] | Medium     | High   | [How to handle] |
+| [Risk 2] | Low        | Medium | [How to handle] |
 
-- Change **Status:** to `Approved`
-- Fill in **Chosen:** with selected option
-- Fill in **Rationale:** with user's reasoning
+````
 
-## Phase 6: Create Plan
+## Phase 5: Generate ADR & Sync
 
-After approval, write `.beads/artifacts/<bead-id>/plan.md`:
+Create `.beads/artifacts/<bead-id>/adr.md`:
 
 ```markdown
-# Implementation Plan: [Title]
+# ADR: [Decision Title]
 
-**Bead:** <bead-id>
+**Status:** Accepted
 **Date:** <date>
-**Approach:** [selected option name]
-
-## Overview
-
-[1-2 paragraph description of approach]
-
-## Steps
-
-### Step 1: [Title]
-
-**Files:** `src/foo.ts`
-
-**Changes:**
-
-- [ ] [Specific change 1]
-- [ ] [Specific change 2]
-
-**Tests:** [What to verify]
+**Bead:** <bead-id>
 
----
+## Context
 
-### Step 2: [Title]
+[Problem statement from spec.md - why we needed to decide]
 
-**Files:** `src/bar.ts`, `src/baz.ts`
+## Decision
 
-**Changes:**
+We chose **[Option Name]** because:
+- [Reason 1]
+- [Reason 2]
 
-- [ ] [Specific change]
+## Alternatives Considered
 
-**Tests:** [What to verify]
+- **[Option B]:** Rejected because [reason]
+- **[Option C]:** Rejected because [reason]
 
----
+## Consequences
 
-### Step 3: [Title]
+**Positive:**
+- [Benefit 1]
+- [Benefit 2]
 
-...
+**Negative:**
+- [Tradeoff 1]
+- [Tradeoff 2]
 
-## Verification
+## Confirmation
 
-- [ ] Unit tests pass
-- [ ] Integration tests pass
-- [ ] Type check passes
-- [ ] [Custom verification from spec]
+This decision is confirmed when:
+- [ ] Implementation complete per plan.md
+- [ ] All verification steps pass
+````
 
-## Risks
+Update bead and sync:
 
-- [Risk 1] - [mitigation]
+```typescript
+bd_msg({
+  subj: "Plan approved",
+  body: "Approach: [selected option]\nTasks: [count]\nEstimate: ~[N] tool calls",
+  to: "all",
+  importance: "normal",
+  global: true,
+});
+
+bd_release({ _: true });
+bd_sync({ reason: "Plan approved for $ARGUMENTS" });
 ```
 
-## Phase 7: Update Bead
-
-Add a note about plan approval via `bd_msg` or update the spec with the approved approach.
-
 ## Output
 
 ```
@@ -230,10 +252,14 @@ Plan Approved: <bead-id>
 ━━━━━━━━━━━━━━━━━━━━━━━━
 
 Approach: [selected option]
-Steps: [count]
-Effort: [S/M/L]
-
-Plan saved: .beads/artifacts/<bead-id>/plan.md
+Tasks: [count]
+Parallel tracks: [count]
+Estimate: ~[N] tool calls
+
+Artifacts:
+- .beads/artifacts/<bead-id>/design.md (approved)
+- .beads/artifacts/<bead-id>/plan.md
+- .beads/artifacts/<bead-id>/adr.md
 
 Next: /implement <bead-id>
 ```

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

@@ -1,53 +1,254 @@
 ---
 description: Create and submit pull request with bead traceability
-argument-hint: "[bead-id]"
+argument-hint: "<bead-id> [--draft] [--wait]"
+agent: build
 ---
 
+# Pull Request
+
 **Load skill:** `skill({ name: "verification-before-completion" })`
 
-## Create Pull Request
+## Options
+
+- `--draft`: Create as draft PR (for WIP or early feedback)
+- `--wait`: Wait for CI checks to pass after creation
+
+## Phase 1: Pre-PR Verification
+
+Before creating PR, run verification gates:
+
+```bash
+git status --porcelain  # Check for uncommitted changes
+```
+
+If uncommitted changes exist, ask: "Commit these changes first?"
+
+Run project gates:
+
+```bash
+npm run build 2>&1 | tail -5
+npm test 2>&1 | tail -10
+npm run lint 2>&1 | tail -5
+```
+
+```
+Pre-PR Gates:
+━━━━━━━━━━━━━
+
+Build: [✓/✗]
+Tests: [✓/✗]
+Lint:  [✓/✗]
+```
+
+**If any gate fails: STOP.**
+
+```
+Cannot create PR: [gate] failed.
+
+Fix errors first, then run /pr again.
+```
+
+## Phase 2: Check for Conflicts
+
+```bash
+git fetch origin main
+git merge-base --is-ancestor origin/main HEAD || git diff origin/main...HEAD --name-only
+```
 
-**Current Branch:** `!git branch --show-current`
-**Changes Summary:** `!git diff main...HEAD --stat`
-**Commits:** `!git log main...HEAD --oneline`
+Check for merge conflicts:
 
-Create a pull request following these steps:
+```bash
+git merge --no-commit --no-ff origin/main 2>&1 || true
+git merge --abort 2>/dev/null || true
+```
 
-1. **Format code** (if formatters available): `!command -v prettier > /dev/null && npm run format || echo "No formatter configured"`
+If conflicts detected:
 
-2. **Push branch**: `!git push -u origin $(git branch --show-current)`
+```
+⚠️  Merge conflicts detected with main:
+- [file1]
+- [file2]
+
+Resolve conflicts before creating PR:
+  git fetch origin main
+  git rebase origin/main
+  # Fix conflicts, then /pr again
+```
 
-3. **Check for bead context:**
-   - If `$ARGUMENTS` contains a bead ID, fetch bead details: `bd_show({ id: "$ARGUMENTS" })`
-   - Use bead title and spec to inform PR content
-   - Reference the bead in the PR body for traceability
+## Phase 3: Gather Context
 
-4. **Generate PR content:**
-   - Title: Clear, descriptive (under 60 chars)
-   - Summary: What and why this change matters
-   - Testing: How to verify the changes
-   - Breaking changes: Note any API/behavior changes
+**Current state:**
 
-5. **Create PR**: `!gh pr create --title "Generated Title" --body "Generated Description"`
+```bash
+git branch --show-current
+git diff main...HEAD --stat
+git log main...HEAD --oneline
+```
 
-**Template format:**
+**Load bead context (if provided):**
 
+```typescript
+bd_show({ id: "$ARGUMENTS" });
 ```
+
+**Load artifacts:**
+
+```bash
+ls .beads/artifacts/<bead-id>/ 2>/dev/null
+cat .beads/artifacts/<bead-id>/spec.md 2>/dev/null | head -30
+cat .beads/artifacts/<bead-id>/review.md 2>/dev/null | head -30
+```
+
+Extract from artifacts:
+
+- **Goal** from spec.md
+- **Changes Made** from review.md
+- **Estimation Accuracy** from review.md
+- **Success Criteria** verification
+
+## Phase 4: Push Branch
+
+```bash
+git push -u origin $(git branch --show-current)
+```
+
+## Phase 5: Create PR
+
+Generate PR content from context:
+
+```bash
+gh pr create --title "<title>" --body "$(cat <<'EOF'
 ## Summary
-- Brief description of changes
 
-## Bead Reference
-Closes: bd-XXXXX (if applicable)
+[1-2 sentence description of what this PR does and why]
+
+## Changes
+
+| File | Change |
+| ---- | ------ |
+| `src/foo.ts` | [description] |
+| `src/bar.ts` | [description] |
 
 ## Testing
-- How to test these changes
 
-## Breaking Changes
-- None / List any breaking changes
+**Automated:**
+- All tests pass ✓
+- Lint passes ✓
+- Type check passes ✓
+
+**Manual verification:**
+- [ ] [How to test manually]
+
+## Screenshots
+
+[If UI changes, include before/after screenshots]
+
+## Estimation
+
+| Metric | Value |
+| ------ | ----- |
+| Estimated | [S/M/L] (~N calls) |
+| Actual | N calls |
+| Accuracy | [+/-N%] |
+
+## Checklist
+
+- [x] Tests added/updated
+- [x] All gates pass
+- [ ] Docs updated (if applicable)
+- [ ] Breaking changes documented (if any)
+
+## Artifacts
+
+- [spec.md](.beads/artifacts/<bead-id>/spec.md)
+- [review.md](.beads/artifacts/<bead-id>/review.md)
+[- research.md, plan.md, adr.md if they exist]
+
+## Bead Reference
+
+Closes: <bead-id>
+EOF
+)"
 ```
 
-## After PR Created
+**For draft PRs (--draft):**
+
+```bash
+gh pr create --draft --title "<title>" --body "..."
+```
+
+## Phase 6: Wait for CI (if --wait)
+
+```bash
+gh pr checks --watch
+```
+
+Report CI status:
+
+```
+CI Status:
+━━━━━━━━━━
+
+- build: [✓/✗/pending]
+- test: [✓/✗/pending]
+- lint: [✓/✗/pending]
+
+[If all pass] CI passed ✓
+[If any fail] CI failed: [which check]
+```
 
-If a bead ID was provided, update the bead with PR link:
+## Phase 7: Update Bead & Sync
 
-Update the bead with a note about the PR using the beads messaging or note system.
+```typescript
+bd_msg({
+  subj: "PR created",
+  body: "PR: <pr-url>\nStatus: [ready/draft]\nCI: [passing/pending]",
+  to: "all",
+  importance: "normal",
+  global: true,
+});
+
+bd_sync({ reason: "PR created for $ARGUMENTS" });
+```
+
+## Output
+
+```
+PR Created: <bead-id>
+━━━━━━━━━━━━━━━━━━━━
+
+URL: <pr-url>
+Status: [Ready for Review / Draft]
+Branch: <branch> → main
+
+Pre-PR Gates: All passed ✓
+Conflicts: None ✓
+[CI: Passed ✓ (if --wait)]
+
+Artifacts linked:
+- spec.md ✓
+- review.md ✓
+[- research.md, plan.md, adr.md]
+```
+
+**Next steps:**
+
+```
+━━━━━━━━━━━━━━━━━━━━
+
+Request review:
+  gh pr edit <pr-number> --add-reviewer <username>
+
+Check CI:
+  gh pr checks
+
+Merge when approved:
+  gh pr merge --squash
+```
+
+**If draft PR:**
+
+```
+Draft PR created. When ready:
+  gh pr ready
+```