opencodekit 0.17.0 → 0.17.2

package/dist/template/.opencode/agent/build.md

@@ -147,6 +147,146 @@ Load contextually when needed:
 - **Parallel** for 3+ independent, file-disjoint tasks using `task(...)`
 - Use `swarm({ op: "plan", ... })` when decomposition is unclear
 
+### Wave-Based Parallel Execution (GSD-Style)
+
+When executing plans with multiple tasks, pre-compute execution waves:
+
+```
+Wave 1: Independent tasks (no dependencies) → Run in parallel
+Wave 2: Tasks depending only on Wave 1 → Run in parallel after Wave 1
+Wave 3: Tasks depending on Wave 2 → And so on
+```
+
+**Dependency analysis before execution:**
+
+1. For each task, identify `needs` (prerequisites) and `creates` (outputs)
+2. Build dependency graph
+3. Assign wave numbers: `wave = max(dependency.waves) + 1`
+4. Execute wave-by-wave, parallel within wave
+
+### Task Commit Protocol (Per-Task Commits)
+
+After each task completes (verification passed):
+
+1. **Check modified files:** `git status --short`
+2. **Stage task-related files individually** (NEVER `git add .`):
+   ```bash
+   git add src/specific/file.ts
+   git add tests/file.test.ts
+   ```
+3. **Commit with descriptive message:**
+
+   ```bash
+   git commit -m "feat(bead-XX): [task description]
+
+   - [key change 1]
+   - [key change 2]"
+   ```
+
+4. **Record commit hash** for progress tracking
+
+**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 |
+
+## 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)
+
+## Checkpoint Protocol
+
+When plan has checkpoint tasks, follow this protocol:
+
+**Checkpoint types:**
+| Type | Use For | Action |
+|------|---------|--------|
+| `checkpoint:human-verify` | Visual/functional verification | Execute automation first, then pause for user |
+| `checkpoint:decision` | Implementation choice | Present options, wait for selection |
+| `checkpoint:human-action` | Unavoidable manual step | Request specific action, verification command |
+
+**Automation-first rule:** If you CAN automate it (CLI/API), you MUST automate it. Checkpoints verify AFTER automation, not replace it.
+
+**Checkpoint return format:**
+
+```markdown
+## CHECKPOINT REACHED
+
+**Type:** [human-verify | decision | human-action]
+**Progress:** X/Y tasks complete
+
+### Completed Tasks
+
+| Task | Commit | Files   |
+| ---- | ------ | ------- |
+| 1    | [hash] | [files] |
+
+### Current Task
+
+**Task N:** [name]
+**Blocked by:** [specific blocker]
+
+### Awaiting
+
+[What user needs to do/provide]
+```
+
+## TDD Execution Flow
+
+When executing TDD tasks, follow RED→GREEN→REFACTOR:
+
+**RED Phase:**
+
+1. Create test file with failing test
+2. Run test → MUST fail
+3. Commit: `test(bead-XX): add failing test for [feature]`
+
+**GREEN Phase:**
+
+1. Write minimal code to make test pass
+2. Run test → MUST pass
+3. Commit: `feat(bead-XX): implement [feature]`
+
+**REFACTOR Phase:** (if needed)
+
+1. Clean up code
+2. Run tests → MUST still pass
+3. Commit only if changes: `refactor(bead-XX): clean up [feature]`
+
 ## Pressure Handling
 
 When constraints tighten:

package/dist/template/.opencode/agent/general.md

@@ -55,6 +55,95 @@ Execute clear, low-complexity coding tasks quickly (typically 1-3 files) and rep
 - Keep changes minimal and in-scope
 - Ask before irreversible actions (commit, push, destructive ops)
 
+## Deviation Rules (Executor Autonomy)
+
+As an executor subagent, you WILL discover issues not in your task spec. Apply these automatically:
+
+**RULE 1: Auto-fix bugs** (broken behavior, errors, logic issues)
+
+- Wrong queries, type errors, null pointer exceptions, logic errors
+- **Action:** Fix inline → add test if applicable → verify → report deviation
+- **No permission needed**
+
+**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, no CSRF/CORS, no rate limiting
+- **Action:** Add minimal fix → verify → report as "[Rule 2] Added missing validation"
+- **No permission needed**
+
+**RULE 3: Auto-fix blocking issues** (missing deps, wrong types, broken imports)
+
+- Missing dependency, wrong types, broken imports, missing env var
+- **Action:** Fix to unblock task → verify → report deviation
+- **No permission needed**
+
+**RULE 4: STOP and report architectural changes** (new tables, library switches)
+
+- New DB table, major schema changes, switching libraries/frameworks
+- Breaking API changes, new infrastructure, new service layer
+- **Action:** STOP → report to parent: "Found [issue] requiring architectural change. Proposed: [solution]. Impact: [scope]"
+- **User decision required**
+
+**Rule Priority:**
+
+1. Rule 4 applies → STOP and report
+2. Rules 1-3 apply → Fix automatically, document in output
+3. Genuinely unsure → Treat as Rule 4
+
+## TDD Execution (When Task Specifies TDD)
+
+Follow strict RED→GREEN→REFACTOR:
+
+**RED Phase:**
+
+1. Read task's `<behavior>` or test specification
+2. Create test file with failing test
+3. Run test → MUST fail (if passes, test is wrong)
+4. Commit: `test: add failing test for [feature]`
+
+**GREEN Phase:**
+
+1. Write minimal code to pass test
+2. Run test → MUST pass
+3. Commit: `feat: implement [feature]`
+
+**REFACTOR Phase:** (only if needed)
+
+1. Clean up code while keeping tests green
+2. Run tests → MUST still pass
+3. Commit if changes made: `refactor: clean up [feature]`
+
+**TDD Verification:**
+
+- Can you write `expect(fn(input)).toBe(output)` before writing `fn`?
+- If YES → Use TDD flow above
+- If NO → Standard implementation (UI layout, config, glue code)
+
+## Self-Check Before Reporting Complete
+
+Before claiming task done:
+
+1. **Verify files exist:**
+
+   ```bash
+   [ -f "path/to/file" ] && echo "FOUND" || echo "MISSING"
+   ```
+
+2. **Verify tests pass:**
+
+   ```bash
+   [run test command]
+   ```
+
+3. **Check for obvious stubs:**
+   - Search for `TODO`, `FIXME`, `placeholder`, `return null`
+   - If found and NOT specified in task → fix or flag
+
+4. **Document deviations:**
+   - List any Rule 1-3 fixes applied
+   - Explain why each was needed
+
 ## Workflow
 
 1. Read relevant files

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

@@ -62,6 +62,181 @@ Planning follows a five-phase arc. Each phase has purpose; silence pockets allow
 | **Release**   | Write the actionable plan                   | Exact file paths, specific commands, verification steps                         | Review: "Can a stranger execute this?"              |
 | **Reset**     | Handoff and checkpoint                      | Save to `.opencode/plans/`, update memory, recommend next command               | Silent: "What was learned for next time?"           |
 
+## Goal-Backward Methodology
+
+**Forward planning:** "What should we build?" → produces tasks
+**Goal-backward:** "What must be TRUE for the goal to be achieved?" → produces requirements tasks must satisfy
+
+### The Process
+
+**Step 1: State the Goal**
+Take goal 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?"
+
+"User can see existing messages" requires:
+
+- Message list component (renders Message[])
+- Messages state (loaded from somewhere)
+- API route or data source (provides messages)
+- Message type definition (shapes the data)
+
+**Test:** Each artifact = a specific file or database object.
+
+**Step 4: Derive Required Wiring**
+For each artifact: "What must be CONNECTED for this to function?"
+
+Message list component wiring:
+
+- Imports Message type (not using `any`)
+- Receives messages prop or fetches from API
+- Maps over messages to render (not hardcoded)
+- Handles empty state (not just crashes)
+
+**Step 5: Identify Key Links**
+"Where is this most likely to break?" Key links = critical connections where breakage causes cascading failures.
+
+For chat interface:
+
+- Input onSubmit -> API call (if broken: typing works but sending doesn't)
+- API save -> database (if broken: appears to send but doesn't persist)
+- Component -> real data (if broken: shows placeholder, not messages)
+
+### Must-Haves Documentation
+
+Document in plan frontmatter:
+
+```yaml
+must_haves:
+  truths:
+    - "User can see existing messages"
+    - "User can send a message"
+  artifacts:
+    - path: "src/components/Chat.tsx"
+      provides: "Message list rendering"
+      min_lines: 30
+  key_links:
+    - from: "src/components/Chat.tsx"
+      to: "/api/chat"
+      via: "fetch in useEffect"
+```
+
+## Discovery Levels
+
+**Level 0 - Skip** (pure internal work, existing patterns only)
+
+- ALL work follows established codebase patterns (grep confirms)
+- No new external dependencies
+- Examples: Add delete button, add field to model, create CRUD endpoint
+
+**Level 1 - Quick Verification** (2-5 min)
+
+- Single known library, confirming syntax/version
+- Action: `context7 resolve-library-id + query-docs`
+
+**Level 2 - Standard Research** (15-30 min)
+
+- Choosing between 2-3 options, new external integration
+- Action: Spawn `@scout` for research, document findings
+
+**Level 3 - Deep Dive** (1+ hour)
+
+- Architectural decision with long-term impact, novel problem
+- Action: Full research with parallel `@scout` agents, document decisions
+
+**Depth indicators:**
+
+- Level 2+: New library not in package.json, external API, "choose/select/evaluate" in description
+- Level 3: "architecture/design/system", multiple external services, data modeling, auth design
+
+## Context Budget Rules
+
+**Quality Degradation Curve:**
+| Context Usage | Quality | Claude's State |
+|---------------|---------|----------------|
+| 0-30% | PEAK | Thorough, comprehensive |
+| 30-50% | GOOD | Confident, solid work |
+| 50-70% | DEGRADING | Efficiency mode begins |
+| 70%+ | POOR | Rushed, minimal |
+
+**Rule:** Plans should target ~50% context per execution. More plans, smaller scope = consistent quality.
+
+**Each plan: 2-3 tasks maximum.**
+
+| Task Complexity | Tasks/Plan | 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:**
+
+- More than 3 tasks → Split
+- Multiple subsystems (DB + API + UI) → Separate plans
+- Any task with >5 file modifications → Split
+- Checkpoint + implementation in same plan → Split
+- Discovery + implementation in same plan → Split
+
+## Dependency Graph Construction
+
+**For each task, record:**
+
+- `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 (Product model): needs nothing, creates src/models/product.ts
+Task C (User API): needs Task A, creates src/api/users.ts
+Task D (Product API): needs Task B, creates src/api/products.ts
+Task E (Dashboard): needs Task C + D, creates src/components/Dashboard.tsx
+
+Graph:
+  A --> C --\
+              --> E
+  B --> D --/
+
+Wave analysis:
+  Wave 1: A, B (independent)
+  Wave 2: C, D (depend on Wave 1)
+  Wave 3: E (depends on Wave 2)
+```
+
+**Vertical slices preferred:**
+
+```
+Plan 01: User feature (model + API + UI)     ← Can run parallel
+Plan 02: Product feature (model + API + UI)  ← Can run parallel
+```
+
+**Avoid horizontal layers:**
+
+```
+Plan 01: All models (User + Product + Order)  ← Sequential
+Plan 02: All APIs (User + Product + Order)    ← Depends on Plan 01
+Plan 03: All UI (User + Product + Order)      ← Depends on Plan 02
+```
+
 ## Memory Ritual
 
 Planning requires understanding what came before. Follow this ritual every session:

package/dist/template/.opencode/agent/review.md

@@ -53,6 +53,102 @@ Only report issues that meet **all** of these:
 3. Is fixable without requiring unrealistic rigor for this codebase
 4. Is likely something the author would actually want to fix
 
+## Goal-Backward Verification Mode
+
+When reviewing implementation against PRD/plan (not just code changes), verify goal achievement:
+
+**Task completion ≠ Goal achievement**
+
+A task "create chat component" can be marked complete when the component is a placeholder. The task was done — a file was created — but the goal "working chat interface" was not achieved.
+
+### Three-Level Verification
+
+**Level 1: Exists**
+
+- File is present at expected path
+- Check: `ls path/to/file.ts`
+
+**Level 2: Substantive (not a stub)**
+
+- Contains actual implementation, not placeholders
+- Red flags: `TODO`, `FIXME`, `return null`, `return <div>Component</div>`, empty handlers
+- Check: `grep -n "TODO\|FIXME\|return null" path/to/file.ts`
+
+**Level 3: Wired (connected/used)**
+
+- Component is imported and used
+- API is called and response is handled
+- State is rendered, not just defined
+- Check: `grep -r "import.*ComponentName" src/`
+
+### Artifact Status Matrix
+
+| Exists | Substantive | Wired | Status      | Action              |
+| ------ | ----------- | ----- | ----------- | ------------------- |
+| ✓      | ✓           | ✓     | ✓ VERIFIED  | None                |
+| ✓      | ✓           | ✗     | ⚠️ ORPHANED | Flag as unused code |
+| ✓      | ✗           | -     | ✗ STUB      | Flag as incomplete  |
+| ✗      | -           | -     | ✗ MISSING   | Flag as missing     |
+
+### Key Link Verification
+
+Verify critical connections (where stubs hide):
+
+**Pattern: Component → API**
+
+- Component calls API: `grep -E "fetch.*api/|axios" Component.tsx`
+- Response is handled: Check for `.then`, `await`, or state update
+
+**Pattern: API → Database**
+
+- API queries DB: `grep -E "prisma\.|db\." route.ts`
+- Query result is returned: Check for `return Response.json(result)`
+
+**Pattern: Form → Handler**
+
+- Form has onSubmit: `grep "onSubmit" Component.tsx`
+- Handler calls API: Check handler implementation
+
+**Pattern: State → Render**
+
+- State defined: `grep "useState" Component.tsx`
+- State rendered: `grep "{stateVar}" Component.tsx`
+
+### Stub Detection Patterns
+
+**React Component Stubs:**
+
+```javascript
+return <div>Component</div>      // Placeholder
+return <div>Placeholder</div>    // Placeholder
+return <div>{/* TODO */}</div>    // Empty
+return null                       // Empty
+onClick={() => {}}                // No-op handler
+onChange={() => console.log('')}  // Log-only handler
+```
+
+**API Route Stubs:**
+
+```typescript
+export async function POST() {
+  return Response.json({ message: "Not implemented" }); // Stub
+}
+export async function GET() {
+  return Response.json([]); // Empty array, no DB query
+}
+```
+
+**Wiring Red Flags:**
+
+```typescript
+fetch('/api/messages')  // No await, no .then, no assignment (ignored)
+await prisma.message.findMany()
+return Response.json({ ok: true })  // Returns static, not query result
+onSubmit={(e) => e.preventDefault()}  // Only prevents default
+const [messages] = useState([])
+return <div>No messages</div>  // State exists but not used
+```
+
 ## Workflow
 
 1. Read changed files and nearby context

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

@@ -45,30 +45,72 @@ If `--type` was provided, use it directly. Otherwise, suggest a type based on th
 - **bug**: Something broken (fix, error, crash, not working)
 - **task**: Tactical change, clear scope (everything else)
 
-## Phase 3: Gather Context
+## Phase 3: Choose Research Depth
 
-Spawn parallel subagents to understand the codebase before writing any spec:
+Ask user before spawning agents:
 
-| Agent                       | Purpose                             | Returns                               |
-| --------------------------- | ----------------------------------- | ------------------------------------- |
-| `explore`                   | Affected files and patterns         | File paths, conventions, architecture |
-| `explore`                   | Test patterns and coverage gaps     | Test files, patterns, gaps            |
-| `explore`                   | Dependencies and integration points | Dependency graph, risk areas          |
-| `scout` (feature/epic only) | Best practices and approaches       | Recommendations, warnings             |
-| `review` (epic only)        | Architecture impact                 | Breaking changes, decomposition       |
+```typescript
+question({
+  questions: [
+    {
+      header: "Research Depth",
+      question: "How much codebase research do you need?",
+      options: [
+        {
+          label: "Deep (Recommended for complex work)",
+          description: "3-5 agents: patterns, tests, deps, best practices (~2 min)",
+        },
+        {
+          label: "Standard",
+          description: "2 agents: patterns + tests (~1 min)",
+        },
+        {
+          label: "Minimal",
+          description: "1 agent: quick file scan (~30 sec)",
+        },
+        {
+          label: "Skip",
+          description: "I know the codebase, use existing knowledge",
+        },
+      ],
+    },
+  ],
+});
+```
+
+## Phase 4: Gather Context
+
+Based on research depth choice, spawn agents:
+
+**If Deep:**
+
+- 3x `explore` (patterns, tests, deps)
+- 1x `scout` (feature/epic)
+- 1x `review` (epic)
+
+**If Standard:**
+
+- 2x `explore` (patterns, tests)
+- 1x `scout` (feature/epic only)
+
+**If Minimal:**
+
+- 1x `explore` (patterns)
+
+**If Skip:**
 
-All agents launch in ONE message — they run concurrently.
+- No agents, use existing AGENTS.md context
 
-**While agents run**, ask clarifying questions if the description lacks scope or expected outcome. For bugs, also ask for reproduction steps and expected vs actual behavior. Skip questions if the description is already specific.
+**While agents run**, ask clarifying questions if the description lacks scope or expected outcome. For bugs, also ask for reproduction steps and expected vs actual behavior.
 
-## Phase 4: Create Bead
+## Phase 5: Create Bead
 
 ```bash
 BEAD_ID=$(br create "$DESCRIPTION" --type $BEAD_TYPE --json | jq -r '.id')
 mkdir -p ".beads/artifacts/$BEAD_ID"
 ```
 
-## Phase 5: Write PRD
+## Phase 6: Write PRD
 
 Copy and fill the PRD template using context from Phase 3:
 
@@ -99,7 +141,7 @@ Tasks must follow the `prd-task` skill format:
 - Metadata block: `depends_on`, `parallel`, `conflicts_with`, `files`
 - At least one verification command per task
 
-## Phase 6: Validate PRD
+## Phase 7: Validate PRD
 
 Before saving, verify:
 
@@ -113,7 +155,7 @@ Before saving, verify:
 
 If any check fails, fix it — don't ask the user.
 
-## Phase 7: Report
+## Phase 8: Report
 
 Output: