opencodekit 0.7.0 → 0.8.0

package/dist/index.js

@@ -750,7 +750,7 @@ var cac = (name = "") => new CAC(name);
 // package.json
 var package_default = {
   name: "opencodekit",
-  version: "0.7.0",
+  version: "0.8.0",
   description: "CLI tool for bootstrapping and managing OpenCodeKit projects",
   type: "module",
   repository: {

package/dist/template/.opencode/AGENTS.md

@@ -296,15 +296,15 @@ Use all three:
 
 ## Beads Usage
 
-**Session start**: `bd doctor --fix` then `bd ready`
+**Session start**: `bd_doctor()` then `bd_claim()`
 **Session end**: Complete one bead fully before starting next
-**Weekly**: `bd cleanup --older-than 7d` then `bd sync`
+**Weekly**: `bd_cleanup(days=7)` then `bd_sync()`
 
 **Philosophy**: Beads is execution, not planning. Plan elsewhere, track in Beads.
 
-## Beads Village (Multi-Agent Coordination)
+## Beads Tools (Multi-Agent Coordination)
 
-MCP server for task coordination and file locking between agents.
+Native plugin tools for task coordination and file locking between agents.
 
 ### When to Use
 
@@ -315,41 +315,80 @@ MCP server for task coordination and file locking between agents.
 ### Core Workflow
 
 ```
-init() → claim() → reserve(paths) → [work] → done(id, msg) → RESTART
+bd_init() → bd_claim() → bd_reserve(paths) → [work] → bd_done(id, msg) → RESTART
 ```
 
-### Key Tools
+### Tool Reference
 
-**Session Management**
+**Lifecycle Tools**
 
-Start every session by calling `init` with your team name and role. This registers you in the workspace and enables role-based task filtering. For example, `init(team="project", role="fe")` joins as a frontend agent.
+Start every session by calling `bd_init` with your team name and role. This registers you in the workspace and enables role-based task filtering. For example, `bd_init({ team: "project", role: "fe" })` joins as a frontend agent.
 
-Check workspace state with `status(include_agents=true)` to see active agents, file locks, and pending messages.
+Call `bd_claim` to get the next ready task assigned to your role. It auto-filters based on task tags matching your role and marks the task as in_progress.
 
-**Task Operations**
+When work is complete, call `bd_done` with the task ID and completion message. This closes the task, releases all file reservations, and syncs with git. After `bd_done`, restart your session for fresh context.
 
-Call `claim` to get the next ready task assigned to your role. It auto-filters based on task tags matching your role.
+**Task Management Tools**
 
-When work is complete, call `done(id="bd-42", msg="Implemented feature X")` to close the task and notify other agents. After `done`, restart your session for a fresh context.
+Use `bd_add` to create new tasks for discovered work. Specify title, optional description, and priority (0=critical through 4=backlog). Use `bd_assign` to assign tasks to specific roles like fe, be, mobile, devops, or qa.
 
-**File Reservations**
+Call `bd_ls` to list tasks filtered by status: open, closed, in_progress, ready, or all. Use `bd_show` with a task ID to get full details including description, notes, and history.
 
-Before editing files, call `reserve(paths=["src/auth.ts"])` to lock them. This prevents other agents from modifying the same files. Call `release` when finished to unlock.
+**File Reservation Tools**
 
-**Messaging**
+Before editing any file, call `bd_reserve` with the file paths you need. This creates locks that prevent other agents from modifying the same files. Locks expire after 600 seconds by default.
 
-Send messages with `msg(subj="API Ready", global=true, to="all")` for cross-workspace announcements. Check incoming messages with `inbox(unread=true)`.
+Call `bd_release` to unlock files early, or let `bd_done` release them automatically. Use `bd_reservations` to see all active locks across the workspace before editing.
 
-### Integration with Commands
+**Messaging Tools**
 
-Use `/create` for the full spec workflow instead of the Village `add` tool. When implementing, `claim` gets your task and `reserve` locks files - Village handles the coordination while your `/implement` command handles the actual work. When finishing, `done` syncs state and notifies other agents.
+Send messages with `bd_msg` using a subject and optional body. Set `to: "all"` for broadcast messages visible to all agents. Check incoming messages with `bd_inbox`, optionally filtering to unread only.
+
+**Status and Maintenance Tools**
+
+Call `bd_status` to get workspace overview including ready task count, in-progress tasks, and active locks. Use `bd_sync` to manually sync with git.
+
+Run `bd_cleanup` periodically to remove old closed issues. Use `bd_doctor` to check and repair database health.
+
+**Analysis Tools**
+
+Call `bd_insights` for graph analysis showing bottlenecks and high-priority keystones. Use `bd_plan` to see a parallel execution plan with tasks grouped by priority tracks.
+
+Get `bd_priority` recommendations for what to work on next based on graph analysis. Use `bd_diff` to compare issue changes between git revisions.
+
+### Quick Start
+
+```typescript
+// 1. Join workspace
+bd_init({ team: "project", role: "fe" });
+
+// 2. Get next task
+const task = bd_claim();
+
+// 3. Lock files before editing
+bd_reserve({ paths: ["src/auth.ts", "src/types.ts"] });
+
+// 4. Do the work...
+
+// 5. Complete and restart
+bd_done({ id: task.id, msg: "Implemented auth" });
+// RESTART SESSION
+```
 
 ### Rules
 
-- **Always `init()` first** in any session using Village tools
+- **Always `bd_init()` first** in any session using beads tools
 - **Reserve before edit** to prevent conflicts
-- **One task per session** - restart after `done()`
-- **Use `msg(global=true)`** for cross-workspace announcements
+- **One task per session** - restart after `bd_done()`
+- **Use `bd_msg(to="all")`** for team-wide announcements
+
+### Skill
+
+Load `beads` skill for detailed workflow guidance:
+
+```
+skill({ name: "beads" })
+```
 
 ## Skills System
 

package/dist/template/.opencode/command/analyze-project.md

@@ -10,7 +10,7 @@ agent: planner
 ## Quick Status
 
 1. **Git:** `git status` - current branch, changes
-2. **Tasks:** `bd list` - active beads
+2. **Tasks:** `bd_ls({ status: "open" })` - active beads
 3. **CI:** Check build status
 4. **Dependencies:** Check for outdated packages
 
@@ -18,8 +18,8 @@ agent: planner
 
 Find actionable tasks with no blockers:
 
-```bash
-bd ready
+```typescript
+bd_ls({ status: "ready", limit: 10, offset: 0 });
 ```
 
 This shows beads that are unblocked and ready to start. Use `/implement <bead-id>` to begin work on any of these.
@@ -28,9 +28,9 @@ This shows beads that are unblocked and ready to start. Use `/implement <bead-id
 
 ### Task Overview
 
-```bash
-bd list --status open
-bd ready
+```typescript
+bd_ls({ status: "open", limit: 10, offset: 0 });
+bd_ls({ status: "ready", limit: 10, offset: 0 });
 ```
 
 For active beads, read spec from `.beads/artifacts/<bead-id>/spec.md`
@@ -39,8 +39,8 @@ For active beads, read spec from `.beads/artifacts/<bead-id>/spec.md`
 
 Check what's blocking progress:
 
-```bash
-bd list --status blocked
+```typescript
+bd_ls({ status: "blocked", limit: 10, offset: 0 });
 ```
 
 For each blocked bead, identify the blocker and either resolve it or escalate.
@@ -55,7 +55,7 @@ For each blocked bead, identify the blocker and either resolve it or escalate.
 
 ### Recommendations
 
-- **Immediate:** Tasks from `bd ready` to start now
+- **Immediate:** Tasks from `bd_ls({ status: "ready" })` to start now
 - **Blocked:** Dependencies preventing progress
 - **Attention:** Areas needing cleanup or refactoring
 - **Updates:** Dependency updates needed

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

@@ -47,14 +47,19 @@ Approve? (yes/modify)
 
 On approval:
 
-```bash
-bd create "[title]" -t [type] -p [priority] -d "[description]" --json
+```typescript
+bd_add({
+  title: "[title]",
+  type: "[type]",
+  pri: [priority],
+  desc: "[description]",
+});
 ```
 
 **If using Beads Village for multi-agent coordination:** Add role tags so tasks can be auto-assigned to the right agent:
 
-```
-add(title="[title]", tags=["[role]"], priority=[0-4])
+```typescript
+bd_add({ title: "[title]", type: "[type]", pri: [priority], tags: ["[role]"] });
 ```
 
 This makes the task claimable by agents with matching roles.

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

@@ -13,8 +13,8 @@ agent: build
 
 ## Phase 1: Load Bead
 
-```bash
-bd show $ARGUMENTS --json
+```typescript
+bd_show({ id: "$ARGUMENTS" });
 ```
 
 Verify status is `in-progress` or `open`.
@@ -175,31 +175,25 @@ Closes: <bead-id>"
 
 ## Phase 7: Close Bead
 
-**If using Beads Village:** Complete the task and notify other agents:
+Complete the task and release any file reservations:
 
-```
-done(id="$ARGUMENTS", msg="Implemented: [1-liner summary]")
+```typescript
+bd_done({ id: "$ARGUMENTS", msg: "Implemented: [1-liner summary]" });
 ```
 
-This closes the bead, releases any file reservations, and broadcasts completion to the workspace.
-
-**Otherwise:** Close via CLI:
-
-```bash
-bd close $ARGUMENTS --reason "Implemented: [1-liner summary]"
-```
+This closes the bead, releases file locks, and syncs with git.
 
 ## Phase 8: Database Health Check
 
 Check issue count:
 
-```bash
-bd list --status all 2>/dev/null | wc -l
+```typescript
+bd_ls({ status: "all", limit: 1 });
 ```
 
 **If >200 issues:** Warn about performance.
 
-**If >500 issues:** Strongly recommend cleanup.
+**If >500 issues:** Strongly recommend cleanup with `bd_cleanup({ days: 7 })`.
 
 ## Output
 
@@ -224,7 +218,8 @@ Branch: <bead-id>
 
 ```
 ⚠️  Database has [count] issues. Consider running:
-    bd cleanup --older-than 7d && bd sync
+    bd_cleanup({ days: 7 })
+    bd_sync()
 ```
 
 **Session recommendation:**
@@ -238,7 +233,7 @@ Task complete. For best performance:
 Next: Create PR or merge to main
 ```
 
-**If using Beads Village:** After calling `done()`, restart your session for a fresh context. The one-task-per-session pattern keeps agents fast and focused.
+After calling `bd_done()`, restart your session for a fresh context. The one-task-per-session pattern keeps agents fast and focused.
 
 **If work was interrupted or partially complete:**
 

package/dist/template/.opencode/command/fix-ci.md

@@ -15,15 +15,16 @@ For deep tracing: `skill({ name: "root-cause-tracing" })`
 
 CI failures are P0 bugs. Create a bead to track:
 
-```bash
-bd create --title "Fix CI: <failure summary>" --type bug --priority p0 --json
+```typescript
+bd_add({
+  title: "Fix CI: <failure summary>",
+  type: "task",
+  pri: 0,
+  tags: ["bug"],
+});
 ```
 
-Save the bead ID for tracking. Add the CI run reference:
-
-```bash
-bd edit <bead-id> --note "CI Run: $ARGUMENTS"
-```
+Save the bead ID for tracking. Add the CI run reference via `bd_msg` or notes.
 
 ## Workflow
 
@@ -41,8 +42,8 @@ bd edit <bead-id> --note "CI Run: $ARGUMENTS"
 
 Once CI passes:
 
-```bash
-bd close <bead-id> --reason "CI fixed: <summary of fix>"
+```typescript
+bd_done({ id: "<bead-id>", msg: "CI fixed: <summary of fix>" });
 ```
 
 ## Notes

package/dist/template/.opencode/command/fix-types.md

@@ -19,19 +19,12 @@ Run `bun run typecheck` and fix all type errors.
 
 If a bead ID is provided (`$ARGUMENTS`), track the type fixing work:
 
-1. **Before fixing:** Note the initial error count
+1. **Before fixing:** Note the initial error count via `bd_msg` or notes
 
-   ```bash
-   bd edit $ARGUMENTS --note "Type errors found: <count>"
-   ```
-
-2. **After fixing:** Update with resolution
-   ```bash
-   bd edit $ARGUMENTS --note "Type errors resolved: <summary of fixes>"
-   ```
+2. **After fixing:** Update with resolution summary
 
 If type errors reveal deeper issues requiring refactoring, create a follow-up bead:
 
-```bash
-bd create --title "Refactor: <type issue summary>" --type task --related $ARGUMENTS
+```typescript
+bd_add({ title: "Refactor: <type issue summary>", type: "task", pri: 2 });
 ```

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

@@ -10,10 +10,12 @@ agent: build
 
 ## Phase 1: Gather State
 
-```bash
-# Bead info
-bd show $ARGUMENTS --json
+```typescript
+// Bead info
+bd_show({ id: "$ARGUMENTS" });
+```
 
+```bash
 # Git state
 git remote get-url origin 2>/dev/null
 git branch --show-current
@@ -123,9 +125,7 @@ read_session("last", project="current")
 
 ## Phase 4: Update Bead
 
-```bash
-bd edit <bead-id> --note "Handoff created. Resume with /resume <bead-id>"
-```
+Add a note about the handoff via `bd_msg` or update spec with handoff reference.
 
 ## Output
 

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

@@ -12,8 +12,8 @@ For large tasks with 3+ phases, also load: `skill({ name: "subagent-driven-devel
 
 ## Phase 1: Setup Workspace
 
-```bash
-bd show $ARGUMENTS --json
+```typescript
+bd_show({ id: "$ARGUMENTS" });
 ```
 
 Check git state:
@@ -31,12 +31,12 @@ Create branch if not on bead branch:
 git checkout -b <bead-id>
 ```
 
-**Multi-agent coordination (if Beads Village available):**
+**Multi-agent coordination:**
 
 Initialize your agent session and claim the task:
 
-```
-init(team="project", role="<your-role>")
+```typescript
+bd_init({ team: "project", role: "<your-role>" });
 ```
 
 This registers you in the workspace. If another agent is working on the same task, you'll be notified.
@@ -110,12 +110,12 @@ Mode: [Quick/Planned]
 
 ## Phase 4: Implementation
 
-**Reserve files before editing (if Beads Village available):**
+**Reserve files before editing:**
 
 Before making changes, lock the files you'll modify to prevent conflicts with other agents:
 
-```
-reserve(paths=["src/auth.ts", "src/utils/**"])
+```typescript
+bd_reserve({ paths: ["src/auth.ts", "src/utils/**"] });
 ```
 
 This creates an advisory lock. Other agents will see your reservation and avoid those files.
@@ -163,10 +163,10 @@ If "pause" or "stop": Run `/handoff <bead-id>`.
 
 ## Phase 6: Complete
 
-When done, release any file reservations (if Beads Village available):
+When done, release any file reservations:
 
-```
-release()
+```typescript
+bd_release();
 ```
 
 Then report:

package/dist/template/.opencode/command/import-plan.md

@@ -55,8 +55,13 @@ Proceed with import? (yes/modify/cancel)
 
 For each epic (top-level section):
 
-```bash
-bd create "[Epic title]" -t epic -p 2 -d "[description from plan]" --json
+```typescript
+bd_add({
+  title: "[Epic title]",
+  type: "epic",
+  pri: 2,
+  desc: "[description from plan]",
+});
 ```
 
 Store epic IDs for dependency linking.
@@ -65,8 +70,14 @@ Store epic IDs for dependency linking.
 
 For each issue under an epic:
 
-```bash
-bd create "[Issue title]" -t task -p 2 -d "[description]" --epic <epic-id> --json
+```typescript
+bd_add({
+  title: "[Issue title]",
+  type: "task",
+  pri: 2,
+  desc: "[description]",
+  parent: "<epic-id>",
+});
 ```
 
 **Infer type from content:**
@@ -85,10 +96,15 @@ bd create "[Issue title]" -t task -p 2 -d "[description]" --epic <epic-id> --jso
 
 ## Phase 5: Link Dependencies
 
-For issues with dependencies:
+For issues with dependencies, use the `deps` parameter when creating:
 
-```bash
-bd link <issue-id> --blocks <dependent-id>
+```typescript
+bd_add({
+  title: "[title]",
+  type: "task",
+  pri: 2,
+  deps: ["<blocking-issue-id>"],
+});
 ```
 
 Common patterns to detect:
@@ -125,12 +141,7 @@ Apply suggestions? (yes/no/select)
 
 ## Phase 7: Polish (Optional)
 
-If user approves suggestions:
-
-```bash
-bd edit <bead-id> --title "[improved title]"
-bd edit <bead-id> -d "[improved description]"
-```
+If user approves suggestions, update the spec files in `.beads/artifacts/<bead-id>/` directly.
 
 Iterate up to 5 times if user requests more refinement.
 
@@ -152,7 +163,7 @@ Created:
 │   └── <issue-3-id>: [title]
 └── ...
 
-Start work: bd ready
+Start work: `bd_ls({ status: "ready", limit: 10, offset: 0 })`
 First task: /implement <first-unblocked-id>
 ```
 

package/dist/template/.opencode/command/integration-test.md

@@ -14,7 +14,7 @@ agent: build
 
 ## Task Validation
 
-1. **Check bead exists:** `bd show $ARGUMENTS`
+1. **Check bead exists:** `bd_show({ id: "$ARGUMENTS" })`
 2. **Read constraints:** `.beads/artifacts/$ARGUMENTS/spec.md` Testing Notes section
 3. **If missing:** STOP. Create with `/create` first.
 

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

@@ -23,15 +23,11 @@ gh issue view $ARGUMENTS
 
 Create a bead to track this work, linking it to the GitHub issue:
 
-```bash
-bd create --title "<issue title>" --type task --priority <p1|p2|p3> --json
+```typescript
+bd_add({ title: "<issue title>", type: "task", pri: 2 });
 ```
 
-Save the bead ID for subsequent commands. Add the GitHub issue reference:
-
-```bash
-bd edit <bead-id> --note "GitHub issue: #$ARGUMENTS"
-```
+Save the bead ID for subsequent commands. Add the GitHub issue reference via `bd_msg` or in the spec.
 
 ## Create Spec from PRD Template
 
@@ -87,8 +83,13 @@ Save to `.beads/artifacts/<bead-id>/spec.md`:
 
 If analysis reveals additional issues, create child beads:
 
-```bash
-bd create --title "<discovered issue>" --type discovered --parent <parent-bead-id>
+```typescript
+bd_add({
+  title: "<discovered issue>",
+  type: "task",
+  pri: 2,
+  parent: "<parent-bead-id>",
+});
 ```
 
 **Next:** Use `/implement <bead-id>` to start implementation.

package/dist/template/.opencode/command/new-feature.md

@@ -23,8 +23,8 @@ Parse from `$ARGUMENTS`:
 
 ### Step 1: Create Bead
 
-```bash
-bd new [type] "[feature-name]" --priority [priority]
+```typescript
+bd_add({ title: "[feature-name]", type: "[type]", pri: [priority] });
 ```
 
 Capture the bead ID from output.
@@ -112,9 +112,7 @@ Tasks:
 
 ### Step 4: Update Bead
 
-```bash
-bd update [bead-id] --status planning
-```
+Update bead status by adding a note via `bd_msg` or updating the spec.
 
 ## Output
 
@@ -129,7 +127,7 @@ Report:
 
 ```bash
 # View the feature
-bd show [bead-id]
+bd_show({ id: "[bead-id]" })
 
 # Start implementation
 /implement [bead-id]

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

@@ -10,8 +10,8 @@ agent: planner
 
 ## Phase 1: Load Context
 
-```bash
-bd show $ARGUMENTS --json
+```typescript
+bd_show({ id: "$ARGUMENTS" });
 ```
 
 Read artifacts:
@@ -221,9 +221,7 @@ After approval, write `.beads/artifacts/<bead-id>/plan.md`:
 
 ## Phase 7: Update Bead
 
-```bash
-bd edit <bead-id> --note "Plan approved: [option name]. [step count] steps."
-```
+Add a note about plan approval via `bd_msg` or update the spec with the approved approach.
 
 ## Output
 

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

@@ -18,7 +18,7 @@ Create a pull request following these steps:
 2. **Push branch**: `!git push -u origin $(git branch --show-current)`
 
 3. **Check for bead context:**
-   - If `$ARGUMENTS` contains a bead ID, fetch bead details: `bd show $ARGUMENTS --json`
+   - If `$ARGUMENTS` contains a bead ID, fetch bead details: `bd_show({ id: "$ARGUMENTS" })`
    - Use bead title and spec to inform PR content
    - Reference the bead in the PR body for traceability
 
@@ -50,6 +50,4 @@ Closes: bd-XXXXX (if applicable)
 
 If a bead ID was provided, update the bead with PR link:
 
-```bash
-bd edit $ARGUMENTS --note "PR created: <pr-url>"
-```
+Update the bead with a note about the PR using the beads messaging or note system.

package/dist/template/.opencode/command/research-and-implement.md

@@ -12,7 +12,7 @@ Fix directly with clear comments. Commit.
 
 ## Structured work (bead-based)
 
-1. Validate bead exists: `bd show $ARGUMENTS`
+1. Validate bead exists: `bd_show({ id: "$ARGUMENTS" })`
 2. Load constraints from `.beads/artifacts/$ARGUMENTS/spec.md`
 3. Research within scope: `/research $ARGUMENTS`
 4. Plan approach: `/plan $ARGUMENTS`

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

@@ -8,8 +8,8 @@ agent: build
 
 ## Phase 1: Load Bead Context
 
-```bash
-bd show $ARGUMENTS --json
+```typescript
+bd_show({ id: "$ARGUMENTS" });
 ```
 
 **Check for previous research:**
@@ -130,9 +130,7 @@ Existing code that informs implementation:
 
 ## Phase 5: Update Bead
 
-```bash
-bd edit <bead-id> --note "Research complete. Key findings: [1-liner]"
-```
+Add a note about research completion via `bd_msg` or update the spec with key findings.
 
 ## Output
 

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

@@ -30,8 +30,8 @@ Review:
 
 ## Phase 2: Load Bead
 
-```bash
-bd show $ARGUMENTS --json
+```typescript
+bd_show({ id: "$ARGUMENTS" });
 ```
 
 ## Phase 3: Find Latest Handoff