opencodekit 0.7.0 → 0.8.0

package/dist/template/.opencode/plugin/compaction.ts

@@ -0,0 +1,80 @@
+import type { Plugin } from "@opencode-ai/plugin";
+
+/**
+ * Compaction Plugin - Customizes session compaction for context continuity
+ *
+ * This plugin injects additional context into the compaction process,
+ * including beads state and memory file references.
+ */
+export const CompactionPlugin: Plugin = async (ctx) => {
+	const { $, directory } = ctx;
+
+	return {
+		"experimental.session.compacting": async (input, output) => {
+			// Inject beads state if available
+			let beadsContext = "";
+			try {
+				const result =
+					await $`cd ${directory} && bd list --status in_progress --json 2>/dev/null`.quiet();
+				if (result.stdout) {
+					const inProgress = JSON.parse(result.stdout.toString());
+					if (inProgress.length > 0) {
+						beadsContext = `\n## Active Beads\n${inProgress.map((b: { id: string; title: string }) => `- ${b.id}: ${b.title}`).join("\n")}`;
+					}
+				}
+			} catch {
+				// Beads not available, skip
+			}
+
+			// Inject custom context
+			output.context.push(`## Session Context
+${beadsContext}
+## Memory Files to Check
+- .opencode/memory/project/gotchas.md - Non-obvious behaviors discovered
+- .opencode/memory/project/commands.md - Build/test commands learned
+- .opencode/memory/project/conventions.md - Code patterns observed
+
+## Persistence Rules
+- PRESERVE: Bead IDs, todo items, file paths, line numbers, user constraints
+- DROP: Failed attempts, superseded info, verbose tool outputs, exploration dead-ends
+- Include enough context that a new session can continue seamlessly`);
+
+			// Replace the entire compaction prompt for more control
+			output.prompt = `You are summarizing a coding session for context continuity.
+
+## Output Structure
+
+Use these sections:
+
+### COMPLETED
+- What was done (with file paths)
+- Bead IDs closed and why
+
+### IN PROGRESS
+- Current task and bead ID (if any)
+- Files being modified (exact paths)
+- Current todo state (preserve TodoWrite items)
+
+### NEXT
+- What needs to be done next
+- Blockers or pending decisions
+
+### CONSTRAINTS
+- User preferences that must persist
+- Rules or requirements stated by user
+- Technical decisions and rationale
+
+### PERSIST TO MEMORY
+- Gotchas discovered → suggest for project/gotchas.md
+- Commands learned → suggest for project/commands.md
+- Patterns observed → suggest for project/conventions.md
+
+## Rules
+
+- PRESERVE: Bead IDs, todo items, file paths, line numbers, user constraints
+- DROP: Failed attempts, superseded info, verbose tool outputs, exploration dead-ends
+- Be concise but complete - this summary replaces the full conversation
+- Include enough context that a new session can continue seamlessly`;
+		},
+	};
+};

package/dist/template/.opencode/skill/beads/SKILL.md

@@ -0,0 +1,419 @@
+---
+name: beads
+description: >
+  Multi-agent task coordination using Beads Village plugin tools. Use when work spans multiple
+  sessions, has dependencies, needs file locking, or requires agent coordination. Covers
+  claim/reserve/done cycle, dependency management, and session protocols.
+version: "1.0.0"
+license: MIT
+---
+
+# Beads Workflow - Multi-Agent Task Coordination
+
+Graph-based task tracker with file locking for multi-agent coordination. Persists across sessions.
+
+## Overview
+
+**Beads plugin tools** (`bd_*`) replace MCP beads-village with native tools for lower token overhead.
+
+**Key Distinction**:
+
+- **bd\_\* tools**: Multi-session work, dependencies, file locking, agent coordination
+- **TodoWrite**: Single-session tasks, linear execution, conversation-scoped
+
+**When to Use bd\_\* vs TodoWrite**:
+
+- "Will I need this context in 2 weeks?" → **YES** = bd\_\*
+- "Does this have blockers/dependencies?" → **YES** = bd\_\*
+- "Multiple agents editing same codebase?" → **YES** = bd\_\*
+- "Will this be done in this session?" → **YES** = TodoWrite
+
+**Decision Rule**: If resuming in 2 weeks would be hard without beads, use beads.
+
+## Session Start Protocol
+
+**Every session, follow these steps:**
+
+### Step 1: Initialize
+
+```typescript
+bd_init({ team: "project", role: "fe" });
+```
+
+Joins workspace, enables role-based task filtering. Roles: fe, be, mobile, devops, qa.
+
+### Step 2: Check Health (Weekly)
+
+```typescript
+bd_doctor();
+```
+
+Repairs database issues. Run at start of week or after sync problems.
+
+### Step 3: Find Ready Work
+
+```typescript
+bd_claim();
+```
+
+Returns highest priority task with no blockers, marks it in_progress.
+
+If no tasks returned, check all open work:
+
+```typescript
+bd_ls({ status: "open" });
+```
+
+### Step 4: Get Full Context
+
+```typescript
+bd_show({ id: "task-abc" });
+```
+
+Shows full description, dependencies, notes, history.
+
+### Step 5: Reserve Files Before Editing
+
+```typescript
+bd_reserve({ paths: ["src/auth.ts", "src/types.ts"] });
+```
+
+**Critical**: Always reserve before editing. Prevents conflicts with other agents.
+
+Check existing locks first:
+
+```typescript
+bd_reservations();
+```
+
+### Step 6: Add Notes as You Work
+
+Use `bd_show` output's notes field. Write notes as if explaining to a future agent with zero conversation context.
+
+**Note Format** (best practice):
+
+```
+COMPLETED: Specific deliverables (e.g., "implemented JWT refresh endpoint")
+IN PROGRESS: Current state + next immediate step
+BLOCKERS: What's preventing progress
+KEY DECISIONS: Important context or user guidance
+```
+
+### Step 7: Complete and Restart
+
+```typescript
+bd_done({ id: "task-abc", msg: "Implemented auth with JWT tokens" });
+// RESTART SESSION - fresh context
+```
+
+Always restart session after `bd_done()`. One task per session.
+
+## Task Creation
+
+### When to Create Tasks
+
+Create tasks when:
+
+- User mentions tracking work across sessions
+- User says "we should fix/build/add X"
+- Work has dependencies or blockers
+- Discovered work while implementing (>2 min effort)
+
+### Basic Task Creation
+
+```typescript
+bd_add({
+  title: "Fix authentication bug",
+  pri: 0, // 0=critical, 1=high, 2=normal, 3=low, 4=backlog
+  type: "bug", // task, bug, feature, epic, chore
+});
+```
+
+### With Description and Tags
+
+```typescript
+bd_add({
+  title: "Implement OAuth",
+  desc: "Add OAuth2 support for Google, GitHub. Use passport.js.",
+  pri: 1,
+  type: "feature",
+  tags: ["be", "security"], // Role tags for assignment
+});
+```
+
+### Epic with Children
+
+```typescript
+// Create parent epic
+bd_add({ title: "Epic: OAuth Implementation", pri: 0, type: "epic" });
+// Returns: { id: "oauth-abc" }
+
+// Create child tasks with parent
+bd_add({ title: "Research OAuth providers", pri: 1, parent: "oauth-abc" });
+bd_add({ title: "Implement auth endpoints", pri: 1, parent: "oauth-abc" });
+bd_add({ title: "Add frontend login UI", pri: 2, parent: "oauth-abc" });
+```
+
+## File Reservation
+
+### Reserve Before Edit
+
+```typescript
+bd_reserve({
+  paths: ["src/auth.ts", "src/middleware/jwt.ts"],
+  reason: "Implementing auth feature",
+  ttl: 600, // seconds until expiry (default)
+});
+```
+
+**Returns**:
+
+```json
+{
+  "granted": ["src/auth.ts"],
+  "conflicts": [{ "path": "src/middleware/jwt.ts", "holder": "agent-xyz" }]
+}
+```
+
+### Check Active Locks
+
+```typescript
+bd_reservations();
+```
+
+Shows all locks across workspace with agent IDs and expiry times.
+
+### Handle Conflicts
+
+If file reserved by another agent:
+
+1. **Can wait** → Work on different files first
+2. **Urgent** → Message the agent:
+
+```typescript
+bd_msg({
+  subj: "Need src/middleware/jwt.ts",
+  body: "Working on auth, can you release?",
+  to: "agent-xyz",
+});
+```
+
+3. **Alternative** → Refactor to avoid that file
+
+### Release Early
+
+```typescript
+bd_release({ paths: ["src/auth.ts"] }); // Specific files
+bd_release(); // All your reservations
+```
+
+Note: `bd_done()` auto-releases all your reservations.
+
+## Messaging
+
+### Send Message
+
+```typescript
+bd_msg({
+  subj: "API Ready",
+  body: "Auth endpoints deployed to staging",
+  to: "all", // or specific agent ID
+  importance: "high", // low, normal, high
+});
+```
+
+### Team Broadcast
+
+```typescript
+bd_msg({
+  subj: "Breaking Change",
+  body: "User schema updated, run migrations",
+  to: "all",
+  global: true, // Cross-workspace
+});
+```
+
+### Check Inbox
+
+```typescript
+bd_inbox({ unread: true, n: 10 });
+```
+
+## Status and Analysis
+
+### Workspace Overview
+
+```typescript
+bd_status({ include_agents: true });
+```
+
+Shows ready tasks, in-progress count, active locks, agent info.
+
+### Find Bottlenecks
+
+```typescript
+bd_insights();
+```
+
+Returns blocked tasks, high-priority keystones, dependency analysis.
+
+### Priority Recommendations
+
+```typescript
+bd_priority({ limit: 5 });
+```
+
+Suggests what to work on next based on priority and dependencies.
+
+### Execution Plan
+
+```typescript
+bd_plan();
+```
+
+Groups ready tasks by priority into parallel execution tracks.
+
+## Git Sync
+
+### Manual Sync
+
+```typescript
+bd_sync();
+```
+
+Commits `.beads/` changes, pulls from remote, pushes local commits.
+
+**Use when**: End of session, before handoff, after major progress.
+
+### Cleanup Old Issues
+
+```typescript
+bd_cleanup({ days: 7 });
+```
+
+Removes closed issues older than N days. Run weekly.
+
+## Error Handling
+
+### Common Issues
+
+**"Call bd_init() first"**
+
+- Always call `bd_init()` at session start
+
+**File conflicts**
+
+- Check `bd_reservations()` before editing
+- Message holder or work on other files
+
+**No ready tasks**
+
+- Run `bd_ls({ status: "open" })` to see all tasks
+- Some may be blocked - check dependencies
+
+**Sync failures**
+
+- Run `bd_doctor()` to repair database
+- Check git remote access
+
+## Examples
+
+### Example 1: Standard Session
+
+```typescript
+// 1. Join and claim
+bd_init({ team: "project", role: "fe" });
+const task = bd_claim();
+// { id: "auth-123", t: "Implement login form", p: 1 }
+
+// 2. Get context
+bd_show({ id: "auth-123" });
+
+// 3. Reserve files
+bd_reserve({ paths: ["src/components/Login.tsx", "src/hooks/useAuth.ts"] });
+
+// 4. Do the work...
+// [implementation]
+
+// 5. Complete
+bd_done({
+  id: "auth-123",
+  msg: "Login form with validation, hooks for auth state",
+});
+// RESTART SESSION
+```
+
+### Example 2: Discovered Work
+
+```typescript
+// Working on task, found more work
+bd_add({
+  title: "Fix edge case in validation",
+  desc: "Empty strings bypass email check - discovered while implementing login",
+  pri: 1,
+  type: "bug",
+});
+// Continue current task, new task tracked for later
+```
+
+### Example 3: Blocked Work
+
+```typescript
+// API is down, can't continue
+bd_release(); // Free files for others
+
+// Message team
+bd_msg({
+  subj: "Blocked: API 503",
+  body: "Auth endpoint returning 503, switching tasks",
+  to: "all",
+});
+
+// Claim different task
+const newTask = bd_claim();
+```
+
+### Example 4: Multi-Agent Coordination
+
+```typescript
+// Agent A (backend)
+bd_init({ team: "project", role: "be" });
+bd_reserve({ paths: ["src/api/auth.ts"] });
+// ... implements API ...
+bd_msg({ subj: "Auth API Ready", to: "all" });
+bd_done({ id: "api-task", msg: "Auth endpoints complete" });
+
+// Agent B (frontend) - sees message
+bd_inbox({ unread: true });
+// { msgs: [{ subj: "Auth API Ready", from: "agent-a" }] }
+bd_claim(); // Gets frontend task that was waiting on API
+```
+
+## Rules
+
+1. **Always `bd_init()` first** - Required before any other bd\_\* tool
+2. **Reserve before edit** - Prevents conflicts with other agents
+3. **One task per session** - Restart after `bd_done()`
+4. **Write notes for future agents** - Assume zero conversation context
+5. **Use `bd_msg(to="all")`** - For team-wide announcements
+6. **Sync regularly** - `bd_sync()` at session end
+
+## Quick Reference
+
+```
+SESSION START:
+  bd_init() → bd_claim() → bd_show() → bd_reserve()
+
+DURING WORK:
+  bd_reserve() additional files
+  bd_add() for discovered work (>2min)
+  bd_msg() to coordinate
+
+SESSION END:
+  bd_done() → RESTART SESSION
+
+MAINTENANCE:
+  bd_doctor() - weekly health check
+  bd_cleanup() - remove old issues
+  bd_sync() - git sync
+```

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

@@ -0,0 +1,218 @@
+# Boundaries: When to Use bd\_\* vs TodoWrite
+
+Decision criteria for choosing between beads tools and TodoWrite.
+
+## The Core Question
+
+**"Could I resume this work after 2 weeks away?"**
+
+- If beads would help you resume → **use bd\_\***
+- If markdown skim would suffice → **TodoWrite is fine**
+
+## Decision Matrix
+
+### Use bd\_\* for:
+
+**Multi-Session Work**
+
+- Strategic document development
+- Feature implementation across sessions
+- Bug investigation over time
+- Architecture design iterations
+
+**Complex Dependencies**
+
+- OAuth integration requiring DB, endpoints, frontend
+- Research with parallel investigation threads
+- Refactoring with dependencies between areas
+- Migration requiring sequential steps
+
+**Knowledge Work**
+
+- Architecture decisions requiring research
+- API design with multiple options
+- Performance optimization experiments
+- Documentation requiring system understanding
+
+**Side Quests**
+
+- Found better pattern during feature work
+- Noticed architectural issue while debugging
+- Identified improvement during code review
+- Edge case requiring research during tests
+
+**Multi-Agent Coordination**
+
+- Multiple agents editing same codebase
+- File locking needed
+- Cross-team communication
+
+### Use TodoWrite for:
+
+**Single-Session Tasks**
+
+- Implementing single function from spec
+- Fixing bug with known root cause
+- Adding unit tests for existing code
+- Updating documentation
+
+**Linear Execution**
+
+- Database migration with clear sequence
+- Deployment checklist
+- Code style cleanup
+- Dependency updates
+
+**Immediate Context**
+
+- User provides complete spec
+- Bug report with reproduction and fix
+- Refactoring with clear before/after
+- Config changes from preferences
+
+**Simple Tracking**
+
+- Breaking down implementation
+- Showing validation progress
+- Demonstrating systematic approach
+
+## Detailed Comparison
+
+| Aspect           | bd\_\*                            | TodoWrite              |
+| ---------------- | --------------------------------- | ---------------------- |
+| **Persistence**  | Git-backed, survives compaction   | Session-only           |
+| **Dependencies** | Graph-based, auto ready detection | Manual                 |
+| **File Locking** | Yes, prevents conflicts           | No                     |
+| **Multi-Agent**  | Yes, coordination tools           | No                     |
+| **Visibility**   | Background structure              | Visible in chat        |
+| **Best for**     | Complex, multi-session            | Simple, single-session |
+
+## Integration Patterns
+
+### Pattern 1: bd\_\* as Strategic, TodoWrite as Tactical
+
+```
+bd task: "Implement user authentication" (epic)
+  ├─ Child: "Create login endpoint"
+  ├─ Child: "Add JWT validation"  ← Currently working
+  └─ Child: "Implement logout"
+
+TodoWrite (for JWT validation):
+- [ ] Install JWT library
+- [ ] Create validation middleware
+- [ ] Add tests for expiry
+- [ ] Update docs
+```
+
+### Pattern 2: TodoWrite as Working Copy
+
+```
+Session start:
+- bd_claim() gets "Add JWT validation"
+- Extract acceptance criteria into TodoWrite
+- Work through TodoWrite items
+- Update bd notes as you learn
+- bd_done() when TodoWrite complete
+```
+
+### Pattern 3: Transition Mid-Session
+
+**From TodoWrite to bd\_\*:**
+
+Trigger signals:
+
+- Discovering blockers or dependencies
+- Work won't complete this session
+- Finding side quests
+- Need to pause and resume later
+
+**How to transition:**
+
+```
+1. bd_add() with current TodoWrite content
+2. Note: "Discovered multi-session work"
+3. Add dependencies as discovered
+4. Keep TodoWrite for current session
+5. Update bd notes before session ends
+```
+
+## Common Mistakes
+
+### Mistake 1: TodoWrite for Multi-Session Work
+
+**What happens:**
+
+- Next session, forget what was done
+- Scroll history to reconstruct
+- Lose design decisions
+- Duplicate work
+
+**Solution:** Use bd\_\* instead.
+
+### Mistake 2: bd\_\* for Simple Linear Tasks
+
+**What happens:**
+
+- Overhead not justified
+- User can't see progress
+- Extra tool use for no benefit
+
+**Solution:** Use TodoWrite.
+
+### Mistake 3: Not Transitioning When Complexity Emerges
+
+**What happens:**
+
+- Start with TodoWrite
+- Discover blockers mid-way
+- Keep using TodoWrite despite poor fit
+- Lose context when session ends
+
+**Solution:** Transition to bd\_\* when complexity appears.
+
+### Mistake 4: Creating Too Many bd Issues
+
+**What happens:**
+
+- Every tiny task gets an issue
+- Database cluttered
+- Hard to find meaningful work
+
+**Solution:** Use 2-week test. Would bd help after 2 weeks? If no, skip.
+
+## The Transition Point
+
+**Transition signals:**
+
+- "This is taking longer than expected"
+- "I've discovered a blocker"
+- "This needs more research"
+- "I should investigate X first"
+- "User might not continue today"
+- "Found three related issues"
+
+When you notice these: Create bd issue, preserve context.
+
+## Summary Heuristics
+
+**Time horizon:**
+
+- Same session → TodoWrite
+- Multiple sessions → bd\_\*
+
+**Dependency structure:**
+
+- Linear steps → TodoWrite
+- Blockers/prerequisites → bd\_\*
+
+**Scope clarity:**
+
+- Well-defined → TodoWrite
+- Exploratory → bd\_\*
+
+**Multi-agent:**
+
+- Single agent → Either
+- Multiple agents → bd\_\*
+
+**When in doubt:** Use the 2-week test.