opencodekit 0.10.0 → 0.11.1

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

@@ -1,56 +1,192 @@
 ---
-description: Resume work on a bead from handoff
+description: Resume work on a bead from handoff with full context recovery
 argument-hint: "<bead-id>"
 agent: build
 ---
 
-# Resume
+# Resume: $ARGUMENTS
 
-**Load skill:** `skill({ name: "executing-plans" })`
+Recover full context from a previous session and continue work on an in-progress task.
 
-## Phase 1: Load Previous Session Context
+## Load Beads Skill
 
-**Check recent sessions:**
+```typescript
+skill({ name: "beads" });
+```
 
-```bash
-list_sessions(project="current", limit=5)
+This skill provides the session protocol for proper context recovery.
+
+## Prerequisites
+
+- Bead ID must exist
+- Handoff file should be present (created by `/handoff`)
+- Previous session context should be accessible
+
+## Phase 1: Initialize Environment
+
+```typescript
+bd_init({ _: true, team: "project", role: "builder" });
 ```
 
-**Load last session context:**
+## Phase 2: Validate Bead Exists
 
-```bash
-read_session("last", project="current")
+```typescript
+bd_show({ id: "$ARGUMENTS" });
 ```
 
-Review:
+**If bead not found:**
 
-- What was implemented
-- File changes made
-- Where work stopped
+```
+ERROR: Bead '$ARGUMENTS' not found
+
+Available beads:
+[list from bd_ls]
+
+Did you mean:
+- bd-abc12 (similar prefix)
+- bd-xyz99 (in progress)
 
-## Phase 2: Load Bead
+Commands:
+- /status     # See all beads
+- /start <id> # Start a new bead
+```
+
+## Phase 3: Check Messages and Blockers
+
+Before diving in, check for coordination updates:
 
 ```typescript
-bd_show({ id: "$ARGUMENTS" });
+bd_inbox({ n: 10, unread: true, global: true });
+bd_reservations({ reason: "Check for conflicting locks" });
 ```
 
-## Phase 3: Find Latest Handoff
+**If blocking messages found:**
 
-```bash
-ls -t .beads/artifacts/<bead-id>/handoffs/ 2>/dev/null | head -1
 ```
+⚠️  ATTENTION REQUIRED
+━━━━━━━━━━━━━━━━━━━━━
 
-If no handoffs: "No handoff found. Use `/start <bead-id>` instead."
+Message from qa-agent (2h ago):
+"Found regression in auth flow - hold on bd-abc12 until fixed"
 
-Read latest handoff:
+Options:
+1. Acknowledge and continue anyway
+2. Switch to different task (/triage)
+3. Reply for clarification
+```
+
+**If conflicting file locks:**
+
+```
+⚠️  FILE CONFLICT
+━━━━━━━━━━━━━━━━
+
+Files you need are locked:
+
+src/auth/service.ts - locked by be-agent (expires 8m)
+src/auth/types.ts   - locked by be-agent (expires 8m)
+
+Options:
+1. Wait for lock to expire
+2. Message be-agent to coordinate
+3. Work on non-conflicting files first
+```
+
+## Phase 4: Load Previous Session Context
+
+### Step 1: Find Related Sessions
+
+```typescript
+list_sessions({ project: "current", limit: 10, _: true });
+```
+
+### Step 2: Identify Relevant Session
+
+Look for sessions that:
+
+- Mention the bead ID
+- Modified files in the bead's scope
+- Have handoff mentions
+
+```typescript
+read_session("last", { project: "current", focus: "$ARGUMENTS" });
+```
+
+### Step 3: Extract Key Context
+
+From session, note:
+
+- Files modified
+- Decisions made
+- Where work stopped
+- Blockers encountered
+
+## Phase 5: Find and Load Handoff
+
+### Locate Handoff File
 
 ```bash
-cat .beads/artifacts/<bead-id>/handoffs/<latest>.md
+ls -t .beads/artifacts/$ARGUMENTS/handoffs/ 2>/dev/null | head -1
+```
+
+**If no handoffs directory:**
+
+```
+No handoff found for $ARGUMENTS
+
+This bead may not have been started with /start, or
+no handoff was created before the previous session ended.
+
+Fallback: Loading from bead spec and plan...
+```
+
+### Load Handoff Content
+
+```typescript
+read({ filePath: ".beads/artifacts/$ARGUMENTS/handoffs/<latest>.md" });
+```
+
+### Parse Handoff Structure
+
+Expected format:
+
+```markdown
+# Handoff: $ARGUMENTS
+
+## Summary
+
+[What was accomplished]
+
+## Progress
+
+- [x] Step 1
+- [x] Step 2
+- [ ] Step 3 ← STOPPED HERE
+- [ ] Step 4
+
+## Current State
+
+- Branch: feature/auth
+- Commit: abc1234
+- Working: src/auth/service.ts
+
+## Resume Instructions
+
+[Specific next actions]
+
+## Blockers
+
+[Any known issues]
+
+## Files Modified
+
+- src/auth/service.ts (+45/-12)
+- src/auth/types.ts (+8/-0)
 ```
 
-## Phase 4: Verify Git State
+## Phase 6: Verify Git State
 
-Check current state matches handoff:
+### Check Current State
 
 ```bash
 git branch --show-current
@@ -58,72 +194,320 @@ git rev-parse HEAD
 git status --porcelain
 ```
 
-**If branch mismatch:**
+### Compare with Handoff
+
+```typescript
+const handoffCommit = parseHandoff().commit;
+const currentCommit = getCurrentCommit();
+
+if (handoffCommit !== currentCommit) {
+  // Check if we're ahead or behind
+  const isAhead = isAncestor(handoffCommit, currentCommit);
+  const isBehind = isAncestor(currentCommit, handoffCommit);
+
+  if (isAhead) {
+    console.log(
+      "Current branch is ahead of handoff - new commits since handoff",
+    );
+  } else if (isBehind) {
+    console.log(
+      "WARNING: Current branch is behind handoff - commits may be lost",
+    );
+  } else {
+    console.log("WARNING: Branches have diverged");
+  }
+}
+```
+
+**Mismatch Handling:**
+
+```
+⚠️  GIT STATE MISMATCH
+━━━━━━━━━━━━━━━━━━━━━
+
+Handoff Commit: abc1234 "feat: add auth middleware"
+Current Commit: def5678 "fix: typo in readme"
+Branch:         main (expected: feature/auth)
+
+Options:
+1. Switch to correct branch:
+   git checkout feature/auth
+
+2. Continue on current branch:
+   [Work may not align with handoff]
+
+3. View diff between commits:
+   git diff abc1234..def5678
+```
+
+### Branch Checkout (if needed)
 
 ```bash
-git checkout <bead-id>
+# Check if branch exists
+git branch --list "feature/$ARGUMENTS" "$ARGUMENTS"
+
+# Checkout if found
+git checkout "$ARGUMENTS" 2>/dev/null || git checkout "feature/$ARGUMENTS"
 ```
 
-**If commit mismatch:**
+## Phase 7: Load All Artifacts
+
+Read all bead context in parallel:
 
+```typescript
+read({ filePath: ".beads/artifacts/$ARGUMENTS/spec.md" });
+read({ filePath: ".beads/artifacts/$ARGUMENTS/research.md" });
+read({ filePath: ".beads/artifacts/$ARGUMENTS/plan.md" });
+read({ filePath: ".beads/artifacts/$ARGUMENTS/review.md" });
 ```
-Warning: Current commit differs from handoff.
-Handoff: [hash from handoff]
-Current: [current hash]
 
-Continue anyway? (yes/no)
+**If files missing, note gaps:**
+
+```
+Artifact Status:
+✓ spec.md     - loaded
+✓ plan.md     - loaded
+✗ research.md - not found (may not be needed)
+✗ review.md   - not found (will create during work)
 ```
 
-## Phase 5: Load Context
+## Phase 8: Stale Handoff Detection
 
-Read all artifacts:
+Check if handoff is too old:
 
-```bash
-cat .beads/artifacts/<bead-id>/spec.md
-cat .beads/artifacts/<bead-id>/research.md 2>/dev/null
-cat .beads/artifacts/<bead-id>/plan.md 2>/dev/null
+```typescript
+const handoffAge = Date.now() - new Date(handoff.timestamp);
+const hoursOld = handoffAge / (1000 * 60 * 60);
+
+if (hoursOld > 72) {
+  // 3 days
+  console.warn(`⚠️ Handoff is ${Math.floor(hoursOld / 24)} days old`);
+  console.warn("Context may be outdated. Consider:");
+  console.warn("1. Re-reading current file state");
+  console.warn("2. Checking for changes by others");
+  console.warn("3. Re-running /research if needed");
+}
+```
+
+**Stale Handoff Warning:**
+
+```
+⚠️  STALE HANDOFF DETECTED
+━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Handoff created: 5 days ago
+Last commit on branch: 5 days ago
+
+Since then:
+- 12 commits on main
+- 3 files modified that you touched
+
+Recommendation:
+1. Check for merge conflicts: git merge --no-commit main
+2. Re-read key files to refresh context
+3. Update plan if approach changed
+```
+
+## Phase 9: Reserve Required Files
+
+Based on handoff and plan, reserve files for editing:
+
+```typescript
+const filesToEdit = extractFilesFromPlan(plan);
+bd_reserve({ paths: filesToEdit, ttl: 600, reason: "Resuming $ARGUMENTS" });
 ```
 
-## Phase 6: Report & Continue
+## Phase 10: Generate Resume Report
 
 ```
-Resuming: <bead-id>
+╔══════════════════════════════════════════════════════════════════════════╗
+║                         RESUMING: $ARGUMENTS                             ║
+╠══════════════════════════════════════════════════════════════════════════╣
+
+TASK INFO
+━━━━━━━━━
+Title:    [from bead]
+Priority: [P0-P4]
+Status:   In Progress
+Created:  [date]
+
+
+CONTEXT SOURCES
+━━━━━━━━━━━━━━━
+Source              │ Status │ Age
+────────────────────┼────────┼────────
+Handoff             │ ✓      │ 2 days
+Previous Session    │ ✓      │ 2 days
+Spec                │ ✓      │ -
+Plan                │ ✓      │ -
+
+
+PREVIOUS SESSION SUMMARY
+━━━━━━━━━━━━━━━━━━━━━━━━
+Session: ses_abc123 (2 days ago)
+Duration: 45 min
+Messages: 34
+Focus: Implementing auth middleware
+
+Key Actions:
+- Created AuthMiddleware class
+- Added token validation
+- Stopped at: refresh token logic
+
+
+PROGRESS
+━━━━━━━━
+[x] Set up project structure
+[x] Create base service class
+[x] Add authentication logic
+[ ] Implement refresh tokens     ← RESUME HERE
+[ ] Add rate limiting
+[ ] Write tests
+[ ] Update documentation
+
+Completed: 3/7 (43%)
+
+
+GIT STATE
+━━━━━━━━━
+Branch: feature/auth
+Commit: abc1234 "feat: add auth middleware"
+Status: Clean ✓
+
+
+RESUME INSTRUCTIONS
+━━━━━━━━━━━━━━━━━━━
+From handoff:
+
+"Left off implementing refresh token rotation. The TokenService
+is ready but needs the rotateToken() method. See TODO in
+src/auth/token-service.ts:45. Tests are set up but empty."
+
+
+FILES TO MODIFY
+━━━━━━━━━━━━━━━
+src/auth/token-service.ts (add rotateToken method)
+src/auth/token-service.test.ts (add tests)
+
+
+FILE LOCKS ACQUIRED
+━━━━━━━━━━━━━━━━━━━
+✓ src/auth/token-service.ts (10 min)
+✓ src/auth/token-service.test.ts (10 min)
+
+
+BLOCKERS
+━━━━━━━━
+[If any blockers from handoff:]
+- Waiting on API spec for refresh endpoint (ask be-agent)
+
+[If no blockers:]
+No known blockers
+
+
+READY TO CONTINUE
 ━━━━━━━━━━━━━━━━━
 
-Title: [title]
-Branch: [branch]
-Handoff: [timestamp]
-Last Session: [from read_session]
+Load skill: skill({ name: "executing-plans" })
 
-## Progress
+Then continue with:
+/implement $ARGUMENTS
 
-Completed:
-- [x] [from handoff]
+Or if you need to re-orient:
+- Read src/auth/token-service.ts to see current state
+- Check plan.md for detailed steps
 
-In Progress:
-- [ ] [from handoff] - [where stopped]
+╚══════════════════════════════════════════════════════════════════════════╝
+```
 
-Remaining:
-- [ ] [from handoff]
+## Phase 11: Determine Next Action
 
-## Previous Session Summary
+Based on state, recommend action:
 
-[Key points from read_session output]
+```typescript
+const nextAction = determineNextAction({
+  hasSpec: !!spec,
+  hasResearch: !!research,
+  hasPlan: !!plan,
+  planProgress: calculateProgress(plan),
+  hasBlockers: blockers.length > 0,
+});
+
+switch (nextAction) {
+  case "NEEDS_SPEC":
+    return "/create $ARGUMENTS - Add specification";
+  case "NEEDS_RESEARCH":
+    return "/research $ARGUMENTS - Research required";
+  case "NEEDS_PLAN":
+    return "/plan $ARGUMENTS - Create implementation plan";
+  case "CONTINUE_IMPLEMENTATION":
+    return "/implement $ARGUMENTS - Continue building";
+  case "BLOCKED":
+    return "Address blockers first, then /implement";
+  case "READY_TO_FINISH":
+    return "/finish $ARGUMENTS - Complete and close";
+}
+```
 
-## Resume Instructions
+**Decision Table:**
+
+| State                         | Action                  |
+| ----------------------------- | ----------------------- |
+| No spec.md                    | `/create $ARGUMENTS`    |
+| No research.md (complex task) | `/research $ARGUMENTS`  |
+| No plan.md                    | `/plan $ARGUMENTS`      |
+| Plan < 100% complete          | `/implement $ARGUMENTS` |
+| Plan 100% + tests pass        | `/finish $ARGUMENTS`    |
+| Has blockers                  | Address blockers first  |
+
+## Error Recovery
 
-[Instructions from handoff]
+### No Bead Found
 
-## Next Action
+```
+ERROR: Bead not found
+
+Possible causes:
+1. Typo in bead ID
+2. Bead was closed/deleted
+3. Using wrong project
+
+Check: bd_ls({ status: "all", limit: 20, offset: 0 })
+```
+
+### No Session Context
+
+```
+WARNING: No previous session found for this bead
+
+Proceeding with spec and plan only.
+Context may be limited.
+
+Recommendation: Read key files manually before continuing.
+```
 
-[Based on progress, suggest next command]
+### Corrupted Handoff
+
+```
+ERROR: Handoff file is corrupted or incomplete
+
+Missing required sections:
+- Progress checklist
+- Resume instructions
+
+Fallback: Using plan.md for progress tracking
+```
+
+## Integration
+
+After resume, the loaded skill will guide execution:
+
+```typescript
+skill({ name: "executing-plans" });
 ```
 
-**Determine next action:**
+This ensures:
 
-| State                      | Action                 |
-| -------------------------- | ---------------------- |
-| No research.md             | `/research <bead-id>`  |
-| No plan.md                 | `/plan <bead-id>`      |
-| Has plan, incomplete steps | `/implement <bead-id>` |
-| All steps complete         | `/finish <bead-id>`    |
+- Plan is followed step-by-step
+- Progress is tracked in plan.md
+- Handoff is created before context limit