opencodekit 0.10.0 → 0.11.1

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

@@ -6,12 +6,32 @@ agent: build
 
 # Handoff
 
-**Load skill:** `skill({ name: "verification-before-completion" })`
+**Load skills:**
 
-## Phase 1: Gather State
+```typescript
+skill({ name: "beads" }); // Session protocol
+skill({ name: "verification-before-completion" });
+```
+
+## Phase 1: Check Messages
+
+Check for any messages that might affect handoff:
+
+```typescript
+bd_inbox({ n: 5, unread: true, global: true });
+```
+
+## Phase 2: Release Locks
+
+Release any file reservations you hold:
+
+```typescript
+bd_release({ _: true });
+```
+
+## Phase 3: Gather State
 
 ```typescript
-// Bead info
 bd_show({ id: "$ARGUMENTS" });
 ```
 
@@ -26,7 +46,33 @@ git status --porcelain
 git diff --stat
 ```
 
-## Phase 2: Commit WIP (if needed)
+## Phase 4: Verify Artifacts
+
+Check what artifacts exist and are valid:
+
+```bash
+ls -la .beads/artifacts/<bead-id>/ 2>/dev/null
+```
+
+For each artifact, verify it's not empty:
+
+```bash
+wc -l .beads/artifacts/<bead-id>/spec.md 2>/dev/null
+wc -l .beads/artifacts/<bead-id>/research.md 2>/dev/null
+wc -l .beads/artifacts/<bead-id>/plan.md 2>/dev/null
+```
+
+```
+Artifact Check:
+━━━━━━━━━━━━━━
+
+- spec.md: [exists/missing] ([N] lines)
+- research.md: [exists/missing] ([N] lines)
+- plan.md: [exists/missing] ([N] lines)
+- review.md: [exists/missing] ([N] lines)
+```
+
+## Phase 5: Commit WIP (if needed)
 
 If uncommitted changes exist:
 
@@ -35,7 +81,23 @@ git add -A
 git commit -m "WIP: <bead-id> - [current step]"
 ```
 
-## Phase 3: Create Handoff
+## Phase 6: Calculate Session Stats
+
+Track estimation accuracy:
+
+```
+Session Stats:
+━━━━━━━━━━━━━━
+
+Estimate: [S/M/L] (~[N] tool calls)
+Actual: [N] tool calls
+Variance: [+/-N%]
+
+Progress: [N]% complete
+Time in session: [estimated duration]
+```
+
+## Phase 7: Create Handoff
 
 Write `.beads/artifacts/<bead-id>/handoffs/<timestamp>.md`:
 
@@ -47,15 +109,26 @@ Write `.beads/artifacts/<bead-id>/handoffs/<timestamp>.md`:
 
 ## Provenance
 
-- **Repo:** [git remote URL]
-- **Branch:** [branch name]
-- **Commit:** [commit hash]
-- **Clean:** [yes/no]
+| Field  | Value            |
+| ------ | ---------------- |
+| Repo   | [git remote URL] |
+| Branch | [branch name]    |
+| Commit | [commit hash]    |
+| Clean  | [yes/no]         |
+
+## Session Stats
+
+| Metric   | Value         |
+| -------- | ------------- |
+| Estimate | [S/M/L]       |
+| Budget   | ~[N] calls    |
+| Actual   | [N] calls     |
+| Variance | [+/-N%]       |
+| Progress | [N]% complete |
 
 ## Session Context
 
-**Current Session:** [session ID from OpenCode]
-**Token Usage:** [if available]
+**Current Session:** [session ID]
 
 Next session can load context with:
 ```
@@ -66,10 +139,12 @@ read_session("last", project="current")
 
 ## Bead State
 
-- **ID:** <bead-id>
-- **Title:** [title]
-- **Status:** [status]
-- **Priority:** [priority]
+| Field    | Value      |
+| -------- | ---------- |
+| ID       | <bead-id>  |
+| Title    | [title]    |
+| Status   | [status]   |
+| Priority | [priority] |
 
 ## Progress
 
@@ -80,7 +155,7 @@ read_session("last", project="current")
 
 ### In Progress
 
-- [ ] [Current step] - [where stopped]
+- [ ] [Current step] - [where stopped, what's next]
 
 ### Remaining
 
@@ -91,8 +166,10 @@ read_session("last", project="current")
 
 ### Key Files
 
-- `src/foo.ts:42` - [why relevant]
-- `src/bar.ts` - [why relevant]
+| File              | Relevance        |
+| ----------------- | ---------------- |
+| `src/foo.ts:42`   | [why relevant]   |
+| `src/bar.ts`      | [why relevant]   |
 
 ### Decisions Made
 
@@ -101,7 +178,22 @@ read_session("last", project="current")
 
 ### Blockers/Issues
 
-- [Issue 1] - [status]
+- [Issue 1] - [status: resolved/pending/blocked]
+
+## Lessons Learned
+
+### What Went Well
+
+- [Thing that worked smoothly]
+
+### What Was Harder Than Expected
+
+- [Challenge encountered]
+- [Why it was harder]
+
+### Patterns Discovered
+
+- [Pattern worth remembering]
 
 ## Resume Instructions
 
@@ -109,36 +201,121 @@ read_session("last", project="current")
 
 1. [First thing to do]
 2. [Second thing to do]
+3. [Third thing to do]
 
-**Recommended:** Start next session with `/resume <bead-id>` to auto-load this handoff + previous session context.
+**Recommended:** Start next session with `/resume <bead-id>`
 
 ## Artifacts
 
-- spec.md: [exists/missing]
-- research.md: [exists/missing]
-- plan.md: [exists/missing]
+| Artifact     | Status  | Lines |
+| ------------ | ------- | ----- |
+| spec.md      | [✓/✗]   | [N]   |
+| research.md  | [✓/✗]   | [N]   |
+| plan.md      | [✓/✗]   | [N]   |
+| review.md    | [✓/✗]   | [N]   |
+```
+
+## Phase 8: Create Observation (if notable learnings)
+
+If session revealed patterns or gotchas:
+
+```typescript
+observation({
+  type: "learning",
+  title: "Session learning: [topic]",
+  content: `
+## What Happened
+[Brief description]
+
+## Lesson
+[What we learned]
+
+## Application
+[When to apply this learning]
+  `,
+  concepts: "[keywords]",
+  bead_id: "<bead-id>",
+});
+```
+
+## Phase 9: Update Memory (if gotchas found)
+
+If you discovered issues worth remembering:
+
+```typescript
+memory -
+  update({
+    file: "project/gotchas",
+    content: `
+## [Gotcha Title]
+
+**Symptom:** [What you see]
+**Cause:** [Root cause]
+**Fix:** [How to resolve]
+  `,
+    mode: "append",
+  });
 ```
 
-## Phase 4: Update Bead
+## Phase 10: Notify Blockers (if any)
 
-Add a note about the handoff via `bd_msg` or update spec with handoff reference.
+If there are blockers for next session:
+
+```typescript
+bd_msg({
+  subj: "Handoff: <bead-id> - Blocked",
+  body: `
+Blockers:
+- [Blocker 1]
+- [Blocker 2]
+
+Needs: [what's required to unblock]
+  `,
+  to: "all",
+  importance: "high",
+  global: true,
+});
+```
+
+## Phase 11: Update Bead & Sync
+
+```typescript
+bd_msg({
+  subj: "Handoff created",
+  body: "Progress: [N]%\nNext: [what needs to happen]",
+  to: "all",
+  importance: "normal",
+  global: false,
+});
+
+bd_sync({ reason: "Handoff created for $ARGUMENTS" });
+```
 
 ## Output
 
 ```
 Handoff Created: <bead-id>
-━━━━━━━━━━━━━━━━━━━━━━━━
+━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 Commit: [hash]
 Branch: [branch]
+Progress: [N]% complete
+
+Session Stats:
+- Estimate: [S/M/L] (~[N] calls)
+- Actual: [N] calls
+- Variance: [+/-N%]
 
+Artifacts verified: [N]/[N]
 Saved: .beads/artifacts/<bead-id>/handoffs/<timestamp>.md
 
-━━━━━━━━━━━━━━━━━━━━━━━━
-🔄 Press Ctrl+K to compact session with handoff context
-━━━━━━━━━━━━━━━━━━━━━━━━
+━━━━━━━━━━━━━━━━━━━━━━━━━━
+To continue: /resume <bead-id>
+━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-The handoff plugin will automatically inject this context into the new session.
+The handoff is saved. Start a fresh session for best performance.
 
-Alternatively, resume manually: /resume <bead-id>
+Next session will auto-load:
+- This handoff document
+- Previous session context via read_session("last")
 ```

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

@@ -6,16 +6,31 @@ agent: build
 
 # Implement
 
-**Load skill:** `skill({ name: "test-driven-development" })`
+**Load skills:**
+
+```typescript
+skill({ name: "beads" }); // Session protocol and hierarchy
+skill({ name: "test-driven-development" });
+skill({ name: "verification-before-completion" });
+```
 
 For large tasks with 3+ phases, also load: `skill({ name: "subagent-driven-development" })`
 
 ## Phase 1: Setup Workspace
 
 ```typescript
+bd_init({ team: "project", role: "<your-role>" });
 bd_show({ id: "$ARGUMENTS" });
 ```
 
+**Check for messages from other agents:**
+
+```typescript
+bd_inbox({ n: 5, unread: true, global: true });
+```
+
+Review any coordination messages before starting.
+
 Check git state:
 
 ```bash
@@ -31,45 +46,62 @@ Create branch if not on bead branch:
 git checkout -b <bead-id>
 ```
 
-**Multi-agent coordination:**
-
-Initialize your agent session and claim the task:
+**Claim the task:**
 
 ```typescript
-bd_init({ team: "project", role: "<your-role>" });
+bd_claim({ reason: "Starting implementation of <bead-id>" });
 ```
 
 This registers you in the workspace. If another agent is working on the same task, you'll be notified.
 
-## Phase 2: Load Context
+## Phase 2: Load Context & Estimation
 
 **Check for previous session work:**
 
-```bash
-list_sessions(project="current", limit=3)
+```typescript
+list_sessions({ project: "current", limit: 3 });
 ```
 
 If recent session exists:
 
-```bash
-read_session("last", project="current")
+```typescript
+read_session({ session_reference: "last", project: "current" });
 ```
 
 Review what was already attempted/completed.
 
-Check what artifacts exist:
+**Load artifacts:**
 
 ```bash
 ls .beads/artifacts/<bead-id>/ 2>/dev/null || echo "No artifacts yet"
 ```
 
-**If `plan.md` exists:** Follow the plan step-by-step (Phase 4).
+**Extract estimation from spec/plan:**
+
+Look for estimate tag (S/M/L/XL) and set budget:
 
-**If `research.md` exists but no plan:** Ask user "Create plan first? Or implement directly?"
+| Estimate | Tool Call Budget | Checkpoint Frequency |
+| -------- | ---------------- | -------------------- |
+| S        | ~10              | End only             |
+| M        | ~30              | Every 10 calls       |
+| L        | ~100             | Every 20 calls       |
+| XL       | Decomposed       | Every step           |
 
-**If only `spec.md` exists (Quick Mode):** Read spec and implement directly based on requirements. No plan needed for simple tasks.
+```
+Implementation Budget:
+━━━━━━━━━━━━━━━━━━━━━
+
+Estimate: [S/M/L] (~[N] tool calls)
+Budget: [N] tool calls
+Checkpoint: Every [N] calls
+```
+
+**Determine mode:**
 
-**If no artifacts:** Read bead description and implement based on that.
+- **If `plan.md` exists:** Follow the plan step-by-step (Planned Mode)
+- **If `research.md` exists but no plan:** Ask user "Create plan first? Or implement directly?"
+- **If only `spec.md` exists:** Read spec and implement directly (Quick Mode)
+- **If no artifacts:** Read bead description and implement based on that
 
 Check for handoffs:
 
@@ -87,71 +119,104 @@ Check which project files exist:
 ls package.json Cargo.toml pyproject.toml setup.py Makefile go.mod 2>/dev/null || true
 ```
 
-**Node.js/TypeScript** (`package.json`): `npm test`, `npm run lint`, `npm run type-check`
-
-**Rust** (`Cargo.toml`): `cargo test`, `cargo clippy -- -D warnings`
-
-**Python** (`pyproject.toml` or `setup.py`): `pytest`, `ruff check .`, `mypy .`
-
-**Go** (`go.mod`): `go test ./...`, `golangci-lint run`
-
-**Make-based** (`Makefile`): `make test`, `make lint`
-
-**No recognized files:** Skip automated verification.
+| Project Type       | Test Command    | Lint Command                         |
+| ------------------ | --------------- | ------------------------------------ |
+| Node.js/TypeScript | `npm test`      | `npm run lint && npm run type-check` |
+| Rust               | `cargo test`    | `cargo clippy -- -D warnings`        |
+| Python             | `pytest`        | `ruff check . && mypy .`             |
+| Go                 | `go test ./...` | `golangci-lint run`                  |
+| Make-based         | `make test`     | `make lint`                          |
 
 Report:
 
 ```
 Implementing: <bead-id>
 ━━━━━━━━━━━━━━━━━━━━━━
+
 Project: [detected type]
 Mode: [Quick/Planned]
+Estimate: [S/M/L] (~[N] tool calls)
 ```
 
 ## Phase 4: Implementation
 
-**Reserve files before editing:**
+### Check Locks & Reserve Files
+
+```typescript
+bd_reservations({ reason: "Checking for conflicts before implementation" });
+```
+
+If files you need are locked:
 
-Before making changes, lock the files you'll modify to prevent conflicts with other agents:
+- Wait for lock to expire, or
+- Coordinate via `bd_msg`, or
+- Work on different files
+
+Reserve files before editing:
 
 ```typescript
-bd_reserve({ paths: ["src/auth.ts", "src/utils/**"] });
+bd_reserve({
+  paths: ["src/auth.ts", "src/utils/**"],
+  reason: "Implementing <bead-id>",
+  ttl: 600,
+});
 ```
 
-This creates an advisory lock. Other agents will see your reservation and avoid those files.
+### Escape Hatches
+
+Set limits before starting:
+
+| Condition                      | Action                                |
+| ------------------------------ | ------------------------------------- |
+| Step fails 3x                  | Stop, analyze, try different approach |
+| Tests fail 5x consecutively    | Pause, ask human for guidance         |
+| Budget 80% exhausted           | Checkpoint commit, reassess scope     |
+| Budget exhausted               | `/handoff` with progress summary      |
+| Blocked on external dependency | Create blocker bead, move on          |
 
 ### With Plan (Planned Mode)
 
 For each unchecked step in plan.md:
 
-1. Make changes to listed files
-2. Run verification (test/lint/type-check)
-3. Mark step complete: `- [x]`
-4. Commit if significant
+1. **Check rollback point** from plan (if exists)
+2. Make changes to listed files
+3. Run step verification command
+4. If fails 3x: Use rollback, try different approach
+5. Mark step complete: `- [x]`
+6. **Checkpoint commit** (if L/XL or significant change)
+
+```bash
+git add <files> && git commit -m "WIP: <bead-id> - Step N complete"
+```
 
 ### Without Plan (Quick Mode)
 
-1. Read spec requirements
+1. Read spec requirements and success criteria
 2. Identify files to change
 3. Make minimal, focused changes
 4. Run verification after each logical change
 5. Keep changes atomic and reviewable
 
-**Gate rules:**
+### Gate Rules
 
-- Type check fails → Fix before proceeding
-- Tests fail → Fix before proceeding
-- Lint fails → Fix if auto-fixable, else note
+| Gate       | On Failure                          |
+| ---------- | ----------------------------------- |
+| Type check | Fix before proceeding               |
+| Tests      | Fix before proceeding (max 3 tries) |
+| Lint       | Auto-fix if possible, else note     |
 
-## Phase 5: Progress Report
+### Track Progress
 
-After each change:
+After every 10 tool calls (or per checkpoint frequency):
 
 ```
 Progress: <bead-id>
 ━━━━━━━━━━━━━━━━━━
 
-Changes:
+Tool calls: [N]/[budget]
+Steps: [completed]/[total]
+
+Recent changes:
 - src/foo.ts:15 - [what changed]
 
 Verification: Test ✓ | Lint ✓ | Types ✓
@@ -161,29 +226,76 @@ Continue? (yes/pause/stop)
 
 If "pause" or "stop": Run `/handoff <bead-id>`.
 
-## Phase 6: Complete
+## Phase 5: Pre-Completion Verification
+
+Before claiming done, verify against spec success criteria:
+
+```bash
+cat .beads/artifacts/<bead-id>/spec.md | grep -A 20 "Success Criteria"
+```
+
+For each criterion:
+
+- [ ] Run the verification command listed
+- [ ] Confirm it passes
+- [ ] Document result
+
+```
+Success Criteria Check:
+━━━━━━━━━━━━━━━━━━━━━━
+
+- [x] [Criterion 1] - Verify: `npm test auth` ✓
+- [x] [Criterion 2] - Verify: `curl localhost:3000/health` ✓
+- [ ] [Criterion 3] - Verify: [command] ✗ (needs fix)
+```
 
-When done, release any file reservations:
+**Do not proceed until all criteria pass.**
+
+## Phase 6: Update Memory (if needed)
+
+If you encountered unexpected issues:
 
 ```typescript
-bd_release();
+memory -
+  update({
+    file: "project/gotchas",
+    content: "## [Issue Title]\n\n[What happened and how to avoid it]",
+    mode: "append",
+  });
 ```
 
-Then report:
+## Phase 7: Complete
 
+Release file reservations:
+
+```typescript
+bd_release({ _: true });
 ```
-Implementation Complete: <bead-id>
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-Final verification running...
+Run full verification suite:
+
+```bash
+[project-specific test command]
+[project-specific lint command]
 ```
 
-Run full verification suite.
+Sync with other agents:
+
+```typescript
+bd_sync({ reason: "Implementation complete for <bead-id>" });
+```
+
+**Final report:**
 
 If all pass:
 
 ```
+Implementation Complete: <bead-id>
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Tool calls: [actual]/[budget] ([over/under] by [N])
 All gates passed ✓
+All success criteria verified ✓
 
 Next: /finish <bead-id>
 ```
@@ -192,6 +304,7 @@ If any fail:
 
 ```
 Gate failed: [which one]
+Retries: [N]/3
 
 Fix issues before running /finish.
 ```