opencodekit 0.7.0 → 0.9.0

package/dist/template/.opencode/skill/beads/references/DEPENDENCIES.md

@@ -0,0 +1,130 @@
+# Dependency Types Guide
+
+Beads supports task dependencies for ordering work.
+
+## Overview
+
+Dependencies affect what work is "ready" - tasks with unmet dependencies won't appear in `bd_claim()` or `bd_priority()`.
+
+## Creating Dependencies
+
+```typescript
+bd_add({
+  title: "Implement API endpoint",
+  deps: ["task:setup-db"], // depends on setup-db task
+});
+```
+
+## Dependency Patterns
+
+### Sequential Work
+
+```
+setup-db → implement-api → add-tests → deploy
+```
+
+Each task depends on the previous. `bd_claim()` shows only the current step.
+
+### Parallel Then Merge
+
+```
+research-a ─┐
+research-b ─┼→ decision
+research-c ─┘
+```
+
+Multiple parallel tasks, then one that needs all of them.
+
+### Foundation First
+
+```
+setup ─┬→ feature-a
+       ├→ feature-b
+       └→ feature-c
+```
+
+One foundational task blocks multiple features.
+
+## Epic with Children
+
+```typescript
+// Create epic
+bd_add({ title: "OAuth Integration", type: "epic" });
+// Returns: { id: "oauth-abc" }
+
+// Create children with parent
+bd_add({ title: "Setup credentials", parent: "oauth-abc" });
+bd_add({
+  title: "Implement flow",
+  parent: "oauth-abc",
+  deps: ["task:credentials"],
+});
+bd_add({ title: "Add UI", parent: "oauth-abc", deps: ["task:flow"] });
+```
+
+## Automatic Unblocking
+
+When you close a task that's blocking others:
+
+```
+1. bd_done({ id: "setup-db" })
+2. Beads automatically updates: implement-api is now ready
+3. bd_claim() returns implement-api
+4. No manual unblocking needed
+```
+
+## Common Mistakes
+
+### Using Dependencies for Preferences
+
+**Wrong:**
+
+```
+docs depends on feature  // "prefer to update docs after"
+```
+
+**Problem:** Documentation doesn't actually need feature complete.
+
+**Right:** Only use dependencies for actual blockers.
+
+### Wrong Direction
+
+**Wrong:**
+
+```
+bd_add({ title: "API", deps: ["task:tests"] })  // API depends on tests?
+```
+
+**Problem:** Usually tests depend on API, not the other way.
+
+**Right:** Think "X needs Y complete first" → X depends on Y.
+
+### Over-Using Dependencies
+
+**Problem:** Everything depends on everything. No parallel work possible.
+
+**Right:** Only add dependencies for actual technical blockers.
+
+## Decision Guide
+
+**Add dependency when:**
+
+- Task literally cannot start without other task complete
+- Code won't compile/run without prerequisite
+- Data/schema must exist first
+
+**Skip dependency when:**
+
+- Just a preference for order
+- Both can proceed independently
+- Just want to note relationship
+
+## Viewing Dependencies
+
+```typescript
+bd_show({ id: "task-abc" });
+// Shows what blocks this task and what this task blocks
+
+bd_insights();
+// Shows bottlenecks and blocked work across project
+```

package/dist/template/.opencode/skill/beads/references/RESUMABILITY.md

@@ -0,0 +1,180 @@
+# Making Tasks Resumable Across Sessions
+
+## When Resumability Matters
+
+**Use enhanced notes for:**
+
+- Multi-session features with API integration
+- Complex algorithms requiring code examples
+- Features with specific output format requirements
+- Work with undocumented APIs
+
+**Skip for:**
+
+- Simple bug fixes with clear scope
+- Well-understood patterns (CRUD, etc.)
+- Single-session tasks
+- Work with obvious criteria
+
+**The test:** Would a fresh agent (or you after 2 weeks) struggle to resume from the notes alone? If yes, add detail.
+
+## Anatomy of Resumable Notes
+
+### Minimal (Always Include)
+
+```
+COMPLETED: What's done
+IN PROGRESS: Current state
+NEXT: Concrete next step
+```
+
+### Enhanced (Complex Work)
+
+````
+COMPLETED: Specific deliverables
+IN PROGRESS: Current state + what's working
+NEXT: Concrete next step (not "continue")
+BLOCKERS: What's preventing progress
+KEY DECISIONS: Important context with rationale
+
+WORKING CODE:
+```python
+# Tested code that works
+result = api.query(fields='importFormats')
+# Returns: {'text/markdown': ['application/vnd.google-apps.document']}
+````
+
+DESIRED OUTPUT:
+
+```markdown
+# Example of what output should look like
+
+Actual structure, not just "return markdown"
+```
+
+```
+
+## Example: Before vs After
+
+### Not Resumable
+
+```
+
+Title: Add dynamic capabilities
+Notes: Working on it. Made some progress.
+
+```
+
+**Problem:** Future agent doesn't know:
+- Which API endpoints to call
+- What responses look like
+- What format to return
+
+### Resumable
+
+```
+
+Title: Add dynamic capabilities resources
+
+Notes:
+COMPLETED: API connection verified. Query working.
+IN PROGRESS: Formatting response as markdown.
+NEXT: Add caching for API responses.
+
+WORKING CODE:
+
+```python
+service = build('drive', 'v3', credentials=creds)
+about = service.about().get(fields='importFormats').execute()
+# Returns dict with 49 entries
+```
+
+DESIRED OUTPUT:
+
+```markdown
+# Drive Import Formats
+
+- **text/markdown** → Google Docs
+- text/plain → Google Docs
+```
+
+KEY DECISION: Using live API query because text/markdown support (July 2024) not in static docs.
+
+```
+
+**Result:** Fresh agent can:
+1. See working API code
+2. Understand response structure
+3. Know desired output format
+4. Implement with context
+
+## When to Add Detail
+
+**During task creation:**
+- Already have working code? Include it.
+- Clear output format? Show example.
+
+**During work:**
+- Got API working? Add to notes.
+- Discovered important context? Document it.
+- Made key decision? Explain rationale.
+
+**Session end:**
+- If resuming will be hard, add implementation guide.
+- If obvious, skip it.
+
+## Anti-Patterns
+
+### Over-Documenting Simple Work
+
+```
+
+Title: Fix typo in README
+Notes: IMPLEMENTATION GUIDE
+WORKING CODE: Open README.md, change "teh" to "the"...
+
+```
+
+**Problem:** Wastes tokens on obvious work.
+
+### Vague Progress
+
+```
+
+Notes: Made progress. Will continue later.
+
+```
+
+**Problem:** No context for resumption.
+
+### Raw Data Dumps
+
+```
+
+API RESPONSE:
+{giant unformatted JSON blob spanning 100 lines}
+
+```
+
+**Problem:** Hard to read. Extract relevant parts.
+
+### Right Balance
+
+```
+
+API returns dict with 49 entries. Examples:
+
+- 'text/markdown': ['application/vnd.google-apps.document']
+- 'text/plain': ['application/vnd.google-apps.document']
+
+```
+
+## The Principle
+
+Help your future self (or next agent) resume without rediscovering everything.
+
+Write notes as if explaining to someone with:
+- Zero conversation context
+- No memory of previous sessions
+- Only the task description and notes
+```

package/dist/template/.opencode/skill/beads/references/WORKFLOWS.md

@@ -0,0 +1,222 @@
+# Workflows and Checklists
+
+Detailed step-by-step workflows for common beads usage patterns.
+
+## Session Start Workflow
+
+**Every session when beads is available:**
+
+```
+Session Start:
+- [ ] bd_init({ team: "project", role: "fe" })
+- [ ] bd_claim() to get ready work
+- [ ] If none ready, bd_ls({ status: "open" })
+- [ ] bd_show({ id }) for full context
+- [ ] bd_reserve({ paths }) before editing
+```
+
+## Compaction Survival
+
+**Critical**: After compaction, conversation history is deleted but beads state persists.
+
+**Post-compaction recovery:**
+
+```
+After Compaction:
+- [ ] bd_ls({ status: "in_progress" }) to see active work
+- [ ] bd_show({ id }) for each in_progress task
+- [ ] Read notes: COMPLETED, IN PROGRESS, BLOCKERS, KEY DECISIONS
+- [ ] Reconstruct TodoWrite from notes if needed
+```
+
+**Writing notes for compaction survival:**
+
+**Good note (enables recovery):**
+
+```
+COMPLETED: User auth - JWT tokens with 1hr expiry, refresh endpoint.
+IN PROGRESS: Password reset flow. Email service working.
+NEXT: Add rate limiting to reset endpoint.
+KEY DECISION: Using bcrypt 12 rounds per OWASP.
+```
+
+**Bad note:**
+
+```
+Working on auth. Made some progress.
+```
+
+## Discovery Workflow
+
+**When encountering new work during implementation:**
+
+```
+Discovery:
+- [ ] Notice bug, improvement, or follow-up
+- [ ] Assess: blocker or deferrable?
+- [ ] bd_add({ title, desc, pri })
+- [ ] If blocker: pause and switch
+- [ ] If deferrable: continue current work
+```
+
+## Epic Planning
+
+**For complex multi-step features, think in Ready Fronts.**
+
+A **Ready Front** is the set of tasks with all dependencies satisfied.
+
+**Walk backward from goal:**
+
+```
+"What's the final deliverable?"
+  ↓
+"Integration tests passing" → task-integration
+  ↓
+"What does that need?"
+  ↓
+"Streaming support" → task-streaming
+"Header display" → task-header
+  ↓
+"What do those need?"
+  ↓
+"Message rendering" → task-messages
+  ↓
+"Buffer layout" → task-buffer (foundation)
+```
+
+**Example: OAuth Integration**
+
+```typescript
+// Create epic
+bd_add({ title: "OAuth integration", type: "epic" });
+
+// Walk backward: What does OAuth need?
+bd_add({ title: "Login/logout endpoints", parent: "oauth-abc" });
+bd_add({ title: "Token storage and refresh", parent: "oauth-abc" });
+bd_add({ title: "Authorization code flow", parent: "oauth-abc" });
+bd_add({ title: "OAuth client credentials", parent: "oauth-abc" }); // foundation
+```
+
+## Side Quest Handling
+
+```
+Side Quest:
+- [ ] During main work, discover problem
+- [ ] bd_add() for side quest
+- [ ] Assess: blocker or deferrable?
+- [ ] If blocker: bd_release(), switch to side quest
+- [ ] If deferrable: note it, continue main work
+```
+
+## Session Handoff
+
+**At Session End:**
+
+```
+Session End:
+- [ ] Work reaching stopping point
+- [ ] Update notes with COMPLETED/IN PROGRESS/NEXT
+- [ ] bd_done() if task complete
+- [ ] Otherwise leave in_progress with notes
+- [ ] RESTART SESSION
+```
+
+**At Session Start:**
+
+```
+Session Start with in_progress:
+- [ ] bd_ls({ status: "in_progress" })
+- [ ] bd_show({ id }) for each
+- [ ] Read notes field
+- [ ] Continue from notes context
+```
+
+## Unblocking Work
+
+**When ready list is empty:**
+
+```
+Unblocking:
+- [ ] bd_ls({ status: "open" }) to see all tasks
+- [ ] bd_insights() to find bottlenecks
+- [ ] Identify blocker tasks
+- [ ] Work on blockers first
+- [ ] Closing blocker unblocks dependent work
+```
+
+## Integration with TodoWrite
+
+**Using both tools:**
+
+```
+Hybrid:
+- [ ] bd_claim() for high-level task
+- [ ] Create TodoWrite from acceptance criteria
+- [ ] Work through TodoWrite items
+- [ ] Update bd notes as you learn
+- [ ] When TodoWrite complete, bd_done()
+```
+
+**Why hybrid**: bd provides persistent structure, TodoWrite provides visible progress.
+
+## Common Patterns
+
+### Systematic Exploration
+
+```
+1. Create research task
+2. Update notes with findings
+3. bd_add() for discoveries
+4. Close research with conclusion
+```
+
+### Bug Investigation
+
+```
+1. Create bug task
+2. Reproduce: note steps
+3. Investigate: track hypotheses in notes
+4. Fix: implement solution
+5. Close with root cause explanation
+```
+
+### Refactoring with Dependencies
+
+```
+1. Create tasks for each step
+2. Work through in dependency order
+3. bd_claim() shows next step
+4. Each completion unblocks next
+```
+
+## Checklist Templates
+
+### Starting Any Session
+
+```
+- [ ] bd_init()
+- [ ] bd_claim() or bd_ls()
+- [ ] bd_show() for context
+- [ ] bd_reserve() files
+- [ ] Begin work
+```
+
+### Creating Tasks During Work
+
+```
+- [ ] Notice new work needed
+- [ ] bd_add() with clear title
+- [ ] Add context in desc
+- [ ] Assess blocker vs deferrable
+- [ ] Update statuses
+```
+
+### Completing Work
+
+```
+- [ ] Implementation done
+- [ ] Tests passing
+- [ ] bd_done() with summary
+- [ ] bd_claim() for next work
+- [ ] RESTART SESSION
+```