opencodekit 0.17.1 → 0.17.2

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

@@ -41,7 +41,44 @@ Verify:
 - `prd.md` exists
 - If `plan.md` already exists, ask user: overwrite or skip?
 
-## Phase 2: Research
+## Phase 2: Discovery Assessment
+
+Before research, determine discovery level based on PRD:
+
+| Level | Scope                | When to Use                                                       | Action                                      |
+| ----- | -------------------- | ----------------------------------------------------------------- | ------------------------------------------- |
+| **0** | Skip                 | Pure internal work, existing patterns only (grep confirms)        | Skip research, proceed to decomposition     |
+| **1** | Quick (2-5 min)      | Single known library, confirming syntax/version                   | `context7 resolve-library-id + query-docs`  |
+| **2** | Standard (15-30 min) | Choosing between 2-3 options, new external integration            | Spawn `@scout` for research                 |
+| **3** | Deep (1+ hour)       | Architectural decision, novel problem, multiple external services | Full research with parallel `@scout` agents |
+
+**Depth indicators:**
+
+- Level 2+: New library not in package.json, external API, "choose/select/evaluate"
+- Level 3: "architecture/design/system", data modeling, auth design
+
+**Decision:** Ask user to confirm or adjust:
+
+```typescript
+const suggestedLevel = assessDiscoveryLevel(prdContent);
+
+question({
+  questions: [
+    {
+      header: "Discovery Level",
+      question: `Suggested: Level ${suggestedLevel} (${getLevelDescription(suggestedLevel)}). Proceed?`,
+      options: [
+        { label: `Yes, Level ${suggestedLevel} (Recommended)` },
+        { label: "Lower (less research)", description: "If you know the patterns" },
+        { label: "Higher (more research)", description: "If uncertain about approach" },
+        { label: "Skip research", description: "I know the codebase" },
+      ],
+    },
+  ],
+});
+```
+
+## Phase 3: Research (if Level 1-3)
 
 Read the PRD and extract tasks, success criteria, affected files, scope.
 
@@ -52,20 +89,163 @@ Spawn parallel agents to gather implementation context:
 | `explore` | Codebase patterns, affected file structure, test patterns, conflicts |
 | `scout`   | Best practices, common patterns, pitfalls                            |
 
-## Phase 3: Decompose
+## Phase 4: Goal-Backward Analysis
+
+**Forward planning:** "What should we build?" → produces tasks
+**Goal-backward:** "What must be TRUE for the goal to be achieved?" → produces requirements
+
+### Step 1: Extract Goal from PRD
+
+Take success criteria from PRD. Must be outcome-shaped, not task-shaped.
+
+- Good: "Working chat interface" (outcome)
+- Bad: "Build chat components" (task)
+
+### Step 2: Derive Observable Truths
+
+"What must be TRUE for this goal to be achieved?" List 3-7 truths from USER's perspective.
+
+Example for "working chat interface":
+
+- User can see existing messages
+- User can type a new message
+- User can send the message
+- Sent message appears in the list
+- Messages persist across page refresh
+
+**Test:** Each truth verifiable by a human using the application.
+
+### Step 3: Derive Required Artifacts
+
+For each truth: "What must EXIST for this to be true?"
+
+| Truth                          | Required Artifacts                                              |
+| ------------------------------ | --------------------------------------------------------------- |
+| User can see existing messages | Message list component, Messages state, API route, Message type |
+| User can send a message        | Input component, Send handler, POST API                         |
+
+**Test:** Each artifact = a specific file or database object.
+
+### Step 4: Identify Key Links
+
+"Where is this most likely to break?" Critical connections where breakage causes cascading failures.
+
+| From      | To        | Via                 | Risk                                |
+| --------- | --------- | ------------------- | ----------------------------------- |
+| Input     | API       | `fetch` in onSubmit | Handler not wired                   |
+| API       | Database  | `prisma.query`      | Query returns static, not DB result |
+| Component | Real data | `useEffect` fetch   | Shows placeholder, not messages     |
+
+## Phase 5: Decompose with Context Budget
+
+**Quality Degradation Rule:** Target ~50% context per execution. More plans, smaller scope = consistent quality.
+
+| Task Complexity | Max Tasks | Context/Task | Total   |
+| --------------- | --------- | ------------ | ------- |
+| Simple (CRUD)   | 3         | ~10-15%      | ~30-45% |
+| Complex (auth)  | 2         | ~20-30%      | ~40-50% |
+| Very complex    | 1-2       | ~30-40%      | ~30-50% |
+
+**Split signals (create child plans):**
+
+- More than 3 tasks
+- Multiple subsystems (DB + API + UI)
+- Any task with >5 file modifications
+- Checkpoint + implementation in same plan
+- Discovery + implementation in same plan
 
 Assess size to determine plan structure:
 
-| 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` |
+| Size          | Files     | Approach                                 |
+| ------------- | --------- | ---------------------------------------- |
+| S (1-3 files) | 2-4 tasks | Single plan, no phases                   |
+| M (3-8 files) | 5-8 tasks | 2-3 phases                               |
+| L (8+ files)  | 9+ tasks  | Create child beads with `--create-beads` |
+
+## Phase 6: Dependency Graph & Wave Assignment
+
+**For each task, record:**
 
-## Phase 4: Write Plan
+- `needs`: What must exist before this runs
+- `creates`: What this produces
+- `has_checkpoint`: Requires user interaction?
+
+**Example:**
+
+```
+Task A (User model): needs nothing, creates src/models/user.ts
+Task B (User API): needs Task A, creates src/api/users.ts
+Task C (User UI): needs Task B, creates src/components/UserList.tsx
+
+Wave 1: A (independent)
+Wave 2: B (depends on A)
+Wave 3: C (depends on B)
+```
+
+**Wave assignment enables parallel execution in `/ship`.**
+
+**Vertical slices preferred:** Each plan covers one feature end-to-end (model + API + UI)
+**Avoid horizontal layers:** Don't create "all models" then "all APIs" then "all UI"
+
+## Phase 7: Write Plan
 
 Write `.beads/artifacts/$ARGUMENTS/plan.md` following the `writing-plans` skill format:
 
+### Required Plan Header
+
+```markdown
+# [Feature] Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use skill({ name: "executing-plans" }) to implement this plan task-by-task.
+
+**Goal:** [Outcome-shaped goal from PRD]
+
+**Discovery Level:** [0-3] - [Rationale]
+
+**Context Budget:** [Estimated context usage, target ~50%]
+
+---
+
+## Must-Haves
+
+### Observable Truths
+
+(What must be TRUE for the goal to be achieved?)
+
+1. [Truth 1]
+2. [Truth 2]
+3. [Truth 3]
+
+### Required Artifacts
+
+| Artifact         | Provides       | Path                  |
+| ---------------- | -------------- | --------------------- |
+| [File/component] | [What it does] | `src/path/to/file.ts` |
+
+### Key Links
+
+| From        | To    | Via     | Risk           |
+| ----------- | ----- | ------- | -------------- |
+| [Component] | [API] | `fetch` | [Failure mode] |
+
+## Dependency Graph
+```
+
+Task A: needs nothing, creates src/models/X.ts
+Task B: needs Task A, creates src/api/X.ts
+Task C: needs Task B, has_checkpoint, creates src/components/X.tsx
+
+Wave 1: A
+Wave 2: B
+Wave 3: C
+
+```
+
+## Tasks
+```
+
+### Task Standards:
+
 - **Exact file paths** — never "add to the relevant file"
 - **Complete code** — never "add validation logic here"
 - **Exact commands with expected output**
@@ -73,7 +253,7 @@ Write `.beads/artifacts/$ARGUMENTS/plan.md` following the `writing-plans` skill
 - **Each step is 2-5 minutes** — one action per step
 - **Tasks map to PRD tasks**
 
-## Phase 5: Create Child Beads (if --create-beads or L size)
+## Phase 8: Create Child Beads (if --create-beads or L size)
 
 For large work, create child beads for each plan phase:
 
@@ -82,18 +262,22 @@ CHILD=$(br create "[Phase title]" --type task --json | jq -r '.id')
 br dep add $CHILD $ARGUMENTS
 ```
 
-## Phase 6: Report
+## Phase 9: Report
 
 Output:
 
-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`
+1. **Discovery Level:** [0-3] with rationale
+2. **Must-Haves:** [N] observable truths, [M] required artifacts, [K] key links
+3. **Context Budget:** [Estimated usage]
+4. **Dependency Waves:** [N] waves for parallel execution
+5. **Task count:** [N] tasks, [M] TDD steps
+6. **Files affected:** [List]
+7. **Plan location:** `.beads/artifacts/$ARGUMENTS/plan.md`
+8. **Child bead hierarchy:** (if created)
+9. **Next step:** `/ship $ARGUMENTS`
 
 ```bash
-br comments add $ARGUMENTS "Created plan.md with [N] tasks, [M] TDD steps"
+br comments add $ARGUMENTS "Created plan.md: Level [N] discovery, [X] waves, [Y] tasks, [Z] TDD steps"
 ```
 
 ## Related Commands

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

@@ -19,6 +19,40 @@ skill({ name: "beads" });
 skill({ name: "verification-before-completion" });
 ```
 
+## Deviation Rules (Auto-Fix Without Permission)
+
+While executing, you WILL discover work not in the plan. Apply these rules automatically:
+
+**RULE 1: Auto-fix bugs** (broken behavior, errors, logic issues)
+
+- Wrong queries, type errors, null pointer exceptions
+- Fix inline → verify → continue task
+
+**RULE 2: Auto-add missing critical functionality** (validation, auth, error handling)
+
+- Missing input validation, no auth on protected routes
+- No error handling, missing null checks
+- These are correctness requirements, not features
+
+**RULE 3: Auto-fix blocking issues** (missing deps, wrong types, broken imports)
+
+- Missing dependency, wrong types, broken imports
+- Missing env var, DB connection error
+- Fix to unblock task completion
+
+**RULE 4: ASK about architectural changes** (new tables, library switches, major refactors)
+
+- New DB table (not column), major schema changes
+- Switching libraries/frameworks, changing auth approach
+- Breaking API changes, new infrastructure
+- STOP → report to user with: what found, proposed change, impact
+
+**Rule Priority:**
+
+1. Rule 4 applies → STOP (user decision required)
+2. Rules 1-3 apply → Fix automatically, track deviation
+3. Genuinely unsure → Treat as Rule 4 (ask)
+
 ## Phase 1: Guards
 
 ```bash
@@ -44,27 +78,164 @@ ls .beads/artifacts/$ARGUMENTS/
 | `prd.json`      | Proceed to PRD task loop below                           |
 | Only `prd.md`   | Load `prd-task` skill to create `prd.json`, then proceed |
 
-## Phase 3: PRD Task Loop
+## Phase 3: Wave-Based Execution
+
+If `plan.md` exists with dependency graph:
+
+1. **Parse waves** from plan header (Wave 1, Wave 2, etc.)
+2. **Execute Wave 1** (independent tasks) in parallel using `task()` subagents
+3. **Wait for Wave 1 completion** — all tasks pass or report failures
+4. **Execute Wave 2** (depends on Wave 1) in parallel
+5. **Continue** until all waves complete
 
-For each task in `prd.json` (respecting `depends_on` ordering):
+**Parallel safety:** Only tasks within same wave run in parallel. Tasks in Wave N+1 wait for Wave N.
+
+### Phase 3A: PRD Task Loop (Sequential Fallback)
+
+For each task (wave-based or sequential fallback):
 
 1. **Read** the task description, verification steps, and affected files
 2. **Read** the affected files before editing
 3. **Implement** the changes — stay within the task's `files` list
-4. **Verify** — run each verification step from the task
-5. **If verification fails**, fix and retry (max 2 attempts per task)
-6. **Mark** `passes: true` in `prd.json`
-7. **Append** progress to `.beads/artifacts/$ARGUMENTS/progress.txt`
+4. **Handle Deviations:** Apply deviation rules 1-4 as discovered
+5. **Checkpoint Protocol:** If task has `checkpoint:*`, stop and request user input
+6. **Verify** — run each verification step from the task
+7. **If verification fails**, fix and retry (max 2 attempts per task)
+8. **Commit** — per-task commit (see below)
+9. **Mark** `passes: true` in `prd.json`
+10. **Append** progress to `.beads/artifacts/$ARGUMENTS/progress.txt`
+
+### Checkpoint Protocol
+
+When task has `checkpoint:*` type:
+
+| Type                      | Action                                                     |
+| ------------------------- | ---------------------------------------------------------- |
+| `checkpoint:human-verify` | Execute automation first, then pause for user verification |
+| `checkpoint:decision`     | Present options, wait for selection                        |
+| `checkpoint:human-action` | Request specific action with verification command          |
+
+**Automation-first:** If verification CAN be automated, MUST automate it before requesting human check.
+
+**Checkpoint return format:**
+
+```markdown
+## CHECKPOINT REACHED
+
+**Type:** [human-verify | decision | human-action]
+**Progress:** X/Y tasks complete
+
+### Completed
+
+| Task | Commit | Status |
+| ---- | ------ | ------ |
+| [N]  | [hash] | [✓/✗]  |
+
+### Current Task
+
+**Task:** [name]
+**Blocked by:** [specific blocker]
+
+### Awaiting
+
+[What user needs to do/provide]
+```
+
+### TDD Execution Flow
+
+When task specifies TDD:
+
+**RED Phase:**
+
+1. Create test file with failing test
+2. Run test → MUST fail
+3. Commit: `test: add failing test for [feature]`
+
+**GREEN Phase:**
+
+1. Write minimal code to make test pass
+2. Run test → MUST pass
+3. Commit: `feat: implement [feature]`
+
+**REFACTOR Phase:** (if needed)
+
+1. Clean up code
+2. Run tests → MUST still pass
+3. Commit if changes: `refactor: clean up [feature]`
+
+### Task Commit Protocol
+
+After each task completes (verification passed):
+
+1. **Check modified files:** `git status --short`
+2. **Stage individually** (NEVER `git add .`):
+   ```bash
+   git add src/specific/file.ts
+   git add tests/file.test.ts
+   ```
+3. **Commit with type prefix:**
+
+   ```bash
+   git commit -m "feat(bead-$ARGUMENTS): [task description]
+
+   - [key change 1]
+   - [key change 2]"
+   ```
+
+4. **Record hash** in progress log
+
+**Commit types:**
+| Type | Use For |
+|------|---------|
+| `feat` | New feature, endpoint, component |
+| `fix` | Bug fix, error correction |
+| `test` | Test-only changes (TDD RED phase) |
+| `refactor` | Code cleanup, no behavior change |
+| `chore` | Config, tooling, dependencies |
 
 ### Stop Conditions
 
 - Verification fails 2x on same task → stop, report blocker
 - Blocked by unfinished dependency → stop, report which one
 - Modifying files outside task scope → stop, ask user
+- Rule 4 deviation encountered → stop, present options
+
+## Phase 4: Choose Verification Gates
+
+Ask user which gates to run:
+
+```typescript
+question({
+  questions: [
+    {
+      header: "Verification Gates",
+      question: "Which verification gates should run?",
+      options: [
+        {
+          label: "All (Recommended)",
+          description: "build + test + lint + typecheck — full validation",
+        },
+        {
+          label: "Essential only",
+          description: "build + test — faster, basic validation",
+        },
+        {
+          label: "Test only",
+          description: "Just run tests",
+        },
+        {
+          label: "Skip gates",
+          description: "Trust my changes, skip verification",
+        },
+      ],
+    },
+  ],
+});
+```
 
-## Phase 4: Verification Gates
+## Phase 5: Run Verification Gates
 
-After all PRD tasks pass, detect project type and run the appropriate verification gates:
+Based on selection, run appropriate gates. Detect project type:
 
 | Project Type    | Detect Via                    | Build            | Test            | Lint                          | Typecheck                             |
 | --------------- | ----------------------------- | ---------------- | --------------- | ----------------------------- | ------------------------------------- |
@@ -73,13 +244,15 @@ After all PRD tasks pass, detect project type and run the appropriate verificati
 | Python          | `pyproject.toml` / `setup.py` | —                | `pytest`        | `ruff check .`                | `mypy .`                              |
 | Go              | `go.mod`                      | `go build ./...` | `go test ./...` | `golangci-lint run`           | (included in build)                   |
 
-Check `package.json` scripts, `Makefile`, or `justfile` for project-specific commands first — prefer those over generic defaults.
+Check `package.json` scripts, `Makefile`, or `justfile` for project-specific commands first.
 
-Also read the PRD's success criteria and run each `Verify:` command.
+Also run PRD `Verify:` commands.
 
 If any gate fails, fix before proceeding.
 
-## Phase 5: Review
+## Phase 6: Review
+
+### 5A: Code Review
 
 Spawn review agent to check changes against the PRD:
 
@@ -103,7 +276,40 @@ Return: findings by severity, whether success criteria are met.`,
 
 If review finds critical issues → fix → re-run Phase 4 → re-review.
 
-## Phase 6: Close
+### 5B: Goal-Backward Verification (if plan.md exists)
+
+Verify that tasks completed ≠ goals achieved:
+
+**Three-Level Verification:**
+
+| Level              | Check                  | Command/Action                                                    |
+| ------------------ | ---------------------- | ----------------------------------------------------------------- |
+| **1: Exists**      | File is present        | `ls path/to/file.ts`                                              |
+| **2: Substantive** | Not a stub/placeholder | `grep -v "TODO\|FIXME\|return null\|placeholder" path/to/file.ts` |
+| **3: Wired**       | Connected and used     | `grep -r "import.*ComponentName" src/`                            |
+
+**Key Link Verification:**
+
+- Component → API: `grep -E "fetch.*api/|axios" Component.tsx`
+- API → Database: `grep -E "prisma\.|db\." route.ts`
+- Form → Handler: `grep "onSubmit" Component.tsx`
+- State → Render: `grep "{stateVar}" Component.tsx`
+
+**Stub Detection:**
+Red flags indicating incomplete implementation:
+
+```javascript
+return <div>Component</div>      // Placeholder
+return <div>{/* TODO */}</div>    // Empty
+return null                       // Empty
+onClick={() => {}}                // No-op handler
+fetch('/api/...')                 // No await, ignored
+return Response.json({ok: true})  // Static, not query result
+```
+
+If any artifact fails Level 2 or 3 → fix → re-verify.
+
+## Phase 7: Close
 
 Ask user before closing:
 
@@ -135,11 +341,39 @@ Record significant learnings with `observation()`.
 
 Report:
 
-1. PRD task results (completed/total, each task status)
-2. Verification gate results (typecheck, build, test, lint)
-3. Success criteria results
-4. Review summary
-5. Next steps: commit changes or create PR
+1. **Execution Summary:**
+   - Tasks completed/total
+   - Waves executed (if plan.md with waves)
+   - Deviations applied (Rules 1-3)
+   - Checkpoints encountered (human-verify/decision/human-action)
+   - Commits made
+
+2. **PRD Task Results:**
+   - Each task status (✓ pass, ✗ fail, ⏸ checkpoint)
+   - Files modified per task
+   - Commit hashes
+
+3. **Verification Gate Results:**
+   - Build: [pass/fail]
+   - Test: [pass/fail]
+   - Lint: [pass/fail]
+   - Typecheck: [pass/fail]
+
+4. **Goal-Backward Verification:**
+   - Artifacts verified: [N] exists, [M] substantive, [K] wired
+   - Key links checked: [pass/fail per link]
+   - Stubs detected: [N] (if any)
+
+5. **Review Summary:**
+   - Critical issues: [N]
+   - Important issues: [N]
+   - Minor issues: [N]
+   - Overall assessment: [pass/needs work]
+
+6. **Next Steps:**
+   - `/pr` to create pull request
+   - Manual commits if not already done
+   - Create follow-up beads for deferred work
 
 ## Related Commands
 

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

@@ -46,24 +46,55 @@ ls .beads/artifacts/$ARGUMENTS/
 
 Verify `prd.md` exists and has real content (not just placeholders). If missing or incomplete, tell user to run `/create` first.
 
-## Phase 3: Claim and Branch
+## Phase 3: Claim
 
 ```bash
 br update $ARGUMENTS --status in_progress
 ```
 
-Create a feature branch:
+## Phase 4: Prepare Workspace
+
+Ask user how to handle workspace:
+
+```typescript
+question({
+  questions: [
+    {
+      header: "Workspace",
+      question: "How do you want to set up the workspace?",
+      options: [
+        {
+          label: "Create feature branch (Recommended)",
+          description: "git checkout -b feat/<bead-id>-<title>",
+        },
+        {
+          label: "Use current branch",
+          description: "Work on current branch",
+        },
+        {
+          label: "Create worktree",
+          description: "Isolated git worktree for this bead",
+        },
+      ],
+    },
+  ],
+});
+```
+
+**If feature branch selected:**
 
 ```bash
-git checkout -b feat/$ARGUMENTS-<short-title>
+git checkout -b feat/$ARGUMENTS-$(echo "$TITLE" | tr '[:upper:]' '[:lower:]' | tr ' ' '-')
 ```
 
-If `--worktree`:
+**If worktree selected:**
 
 ```typescript
 skill({ name: "using-git-worktrees" });
 ```
 
+**If current branch:** Continue without branch creation.
+
 ## Phase 4: Convert PRD to Tasks
 
 If `prd.json` doesn't exist yet, use `prd-task` skill to convert PRD markdown → executable JSON.

package/dist/template/.opencode/memory/_templates/PROJECT.md

@@ -0,0 +1,58 @@
+---
+purpose: Project vision, goals, and success criteria (loaded into all AI contexts)
+updated: 2024-12-21
+---
+
+# Project Vision
+
+## The Goal
+
+<!-- One sentence: What does this project achieve? Outcome-shaped, not task-shaped. -->
+<!-- Good: "A real-time chat application with persistent message history" -->
+<!-- Bad: "Build chat components and API endpoints" -->
+
+## Success Criteria
+
+<!-- How do we know the project is successful? List 3-7 observable outcomes. -->
+<!-- Each should be verifiable by using the application, not by checking code. -->
+
+1. **[Criterion 1]** - [Specific, measurable outcome]
+2. **[Criterion 2]** - [Specific, measurable outcome]
+3. **[Criterion 3]** - [Specific, measurable outcome]
+
+## Target Users
+
+<!-- Who will use this? What do they need? -->
+
+- **Primary:** [User type and their core need]
+- **Secondary:** [User type and their core need]
+
+## Core Principles
+
+<!-- Non-negotiable principles that guide all decisions -->
+
+1. **[Principle 1]** - [Explanation]
+2. **[Principle 2]** - [Explanation]
+3. **[Principle 3]** - [Explanation]
+
+## Current Phase
+
+<!-- Where are we in the project lifecycle? -->
+
+- **Status:** [Discovery / Planning / Implementation / Polish / Maintenance]
+- **Milestone:** [Current milestone name]
+- **Next Milestone:** [Next milestone name]
+
+## Key Links
+
+<!-- Important references -->
+
+- **Repository:** [URL]
+- **Documentation:** [URL]
+- **Staging:** [URL]
+- **Production:** [URL]
+
+---
+
+_Update this file when project direction or phase changes._
+_AI uses this to maintain context across sessions and make decisions aligned with project goals._