opencodekit 0.6.7 → 0.8.0

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

@@ -5,7 +5,7 @@
 1. Security constraints (always first)
 2. Anti-hallucination rule (overrides all except security)
 3. Delegation rules (check before tool calls)
-4. Skills check (`find_skills` → `use_skill`)
+4. Skills check (native `skill` tool)
 5. User explicit requests
 6. Base prompt behaviors
 7. Global rules (this file)
@@ -296,15 +296,103 @@ 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 Tools (Multi-Agent Coordination)
+
+Native plugin tools for task coordination and file locking between agents.
+
+### When to Use
+
+- **Multi-agent work**: Multiple agents on same codebase
+- **File conflict prevention**: Reserve files before editing
+- **Cross-workspace coordination**: FE/BE/Mobile agents communicating
+
+### Core Workflow
+
+```
+bd_init() → bd_claim() → bd_reserve(paths) → [work] → bd_done(id, msg) → RESTART
+```
+
+### Tool Reference
+
+**Lifecycle Tools**
+
+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.
+
+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.
+
+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.
+
+**Task Management Tools**
+
+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.
+
+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.
+
+**File Reservation Tools**
+
+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.
+
+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.
+
+**Messaging Tools**
+
+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 `bd_init()` first** in any session using beads tools
+- **Reserve before edit** to prevent conflicts
+- **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
 
-Use `find_skills` → `use_skill` when:
+OpenCode has a native `skill` tool that auto-discovers skills from `.opencode/skill/` and `~/.config/opencode/skill/`. Use `skill({ name: "skill-name" })` when:
 
 - Creating something new → `brainstorming`
 - Bug or unexpected behavior → `systematic-debugging`
@@ -321,16 +409,12 @@ Use `find_skills` → `use_skill` when:
 
 Skip for simple questions, quick edits, or conversations.
 
-### Progressive Skill Loading
-
-Skills consume context. Manage them actively:
-
-1. **Load on-demand**: Only load skills when starting relevant work
-2. **Read linked files lazily**: Don't load all skill references immediately—read only when needed
-3. **Unload after completion**: When task completes, skill context is no longer needed
-4. **One skill at a time**: Avoid loading multiple skills unless task requires it
+### How It Works
 
-**IMPORTANT**: Always unload irrelevant skills to free context space. Loaded skills that aren't actively needed are context debt.
+1. Available skills are listed in the `skill` tool description (auto-discovered)
+2. Load a skill: `skill({ name: "brainstorming" })`
+3. Skills consume context - load on-demand, one at a time
+4. Skill permissions can be configured in `opencode.json` (`allow`/`deny`/`ask`)
 
 ## Core Constraints
 

package/dist/template/.opencode/README.md

@@ -41,7 +41,7 @@ opencode
 │
 ├── agent/                 # Custom agents (5 total)
 ├── command/               # Custom commands (26 workflows)
-├── superpowers/skills/    # Domain expertise (16 skills)
+├── skill/                 # Domain expertise (27 skills)
 ├── tool/                  # Custom MCP tools (memory-*, observation, ast-grep)
 ├── plugin/                # Background plugins (enforcer, compactor, truncator)
 └── memory/                # Persistent context
@@ -105,22 +105,23 @@ GOOGLE_APPLICATION_CREDENTIALS=/path/to/key.json
 
 - `/commit` - Intelligent git commits
 - `/pr` - Create pull requests
-- `/design` - Thoughtful design with brainstorming
-- `/fix` - Systematic debugging
-- `/research` - Deep documentation search
-- `/review-codebase` - Comprehensive audit
+- `/design` - Thoughtful design with brainstorming expertise
+- `/fix` - Systematic debugging with root-cause analysis
+- `/implement` - High-quality implementation with TDD and subagents
+- `/finish` - Verified completion with structured integration options
 
 **See:** `.opencode/command/` for all commands
 
 ---
 
-## Skills System (16 skills)
+## Skills System (27 skills)
 
-**Core:** brainstorming, writing-plans, executing-plans, verification-before-completion
-**Code:** requesting-code-review, receiving-code-review, root-cause-tracing
-**Advanced:** gemini-large-context, subagent-driven-development, dispatching-parallel-agents
+**Core:** brainstorming, writing-plans, executing-plans, verification-before-completion, using-superpowers, finishing-a-development-branch
+**Code:** requesting-code-review, receiving-code-review, root-cause-tracing, test-driven-development, testing-anti-patterns, condition-based-waiting, defense-in-depth, systematic-debugging
+**UI/UX:** frontend-aesthetics, mockup-to-code, visual-analysis, ui-ux-research, accessibility-audit, design-system-audit
+**Workflow:** gemini-large-context, subagent-driven-development, dispatching-parallel-agents, using-git-worktrees, sharing-skills, writing-skills, testing-skills-with-subagents
 
-**Note:** Skills load via `use_skill()` in commands
+**Note:** Skills load via native `skill()` tool. Commands auto-load relevant expertise.
 
 ---
 
@@ -287,9 +288,10 @@ fi
 
 **"Skills not loading":**
 
-- Skills load via commands with `use_skill()`
+- Skills load via native `skill()` tool (auto-discovered)
 - Use /design to load brainstorming
-- Use /fix to load debugging skills
+- Use /fix to load systematic-debugging
+- Check `.opencode/skill/` directory exists
 
 ---
 
@@ -324,12 +326,12 @@ fi
 - **OpenCode Docs:** https://opencode.ai/docs
 - **Context7 API:** https://context7.com
 - **Exa API:** https://exa.ai
-- **Skills Documentation:** `superpowers/skills/`
+- **Skills Documentation:** `.opencode/skill/`
 - **Architecture Guide:** `AGENTS.md`
 
 ---
 
-**OpenCodeKit v0.3.0**  
+**OpenCodeKit v0.7.0**  
 **Architecture:** Two-Layer (Memory + Beads + Git)  
-**New in v0.3.0:** Background plugins (enforcer, compactor, truncator) + ast-grep tool  
-**Last Updated:** December 17, 2025
+**New in v0.7.0:** Native skill tool integration, Beads Village MCP, 27 skills, enhanced commands  
+**Last Updated:** December 30, 2025

package/dist/template/.opencode/command/accessibility-check.md

@@ -7,7 +7,7 @@ model: proxypal/gemini-3-flash-preview
 
 # Accessibility Check: $ARGUMENTS
 
-use_skill("accessibility-audit")
+skill({ name: "accessibility-audit" })
 
 Perform WCAG accessibility audit.
 

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

@@ -7,7 +7,7 @@ model: proxypal/gemini-3-flash-preview
 
 # Analyze Mockup: $ARGUMENTS
 
-use_skill("visual-analysis")
+skill({ name: "visual-analysis" })
 
 Analyze the provided UI mockup or screenshot.
 

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

@@ -5,10 +5,12 @@ agent: planner
 
 # Analyze Project
 
+**For large codebases:** `skill({ name: "gemini-large-context" })`
+
 ## 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
 
@@ -16,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.
@@ -26,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`
@@ -37,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.
@@ -53,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/brainstorm.md

@@ -6,7 +6,7 @@ agent: build
 
 # Brainstorm: $ARGUMENTS
 
-use_skill("brainstorming")
+skill({ name: "brainstorming" })
 
 Follow the skill for ideation, then explore the codebase to validate feasibility. Create quick prototypes or code spikes if helpful.
 

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

@@ -5,7 +5,7 @@ argument-hint: "[bead-id]"
 
 # Commit
 
-use_skill("verification-before-completion")
+skill({ name: "verification-before-completion" })
 
 ## Workflow
 

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

@@ -40,16 +40,30 @@ Creating:
   Type: [type]
   Priority: [0-4]
   Complexity: [quick/deep]
+  Role: [fe/be/mobile/devops/qa] (optional, for multi-agent)
 
 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:
+
+```typescript
+bd_add({ title: "[title]", type: "[type]", pri: [priority], tags: ["[role]"] });
+```
+
+This makes the task claimable by agents with matching roles.
+
 ## Phase 4: Create Spec
 
 ```bash

package/dist/template/.opencode/command/design-audit.md

@@ -7,7 +7,7 @@ model: proxypal/gemini-3-pro-preview
 
 # Design Audit: $ARGUMENTS
 
-use_skill("design-system-audit")
+skill({ name: "design-system-audit" })
 
 Perform a comprehensive design system audit.
 

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

@@ -6,7 +6,7 @@ agent: vision
 
 # Design: $ARGUMENTS
 
-use_skill("frontend-aesthetics")
+skill({ name: "frontend-aesthetics" })
 
 Focus on visual design: typography, color, spacing, layout, accessibility. Avoid AI slop aesthetics.
 

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

@@ -6,10 +6,15 @@ agent: build
 
 # Finish
 
+**Load skills:**
+
+- `skill({ name: "verification-before-completion" })`
+- `skill({ name: "finishing-a-development-branch" })`
+
 ## Phase 1: Load Bead
 
-```bash
-bd show $ARGUMENTS --json
+```typescript
+bd_show({ id: "$ARGUMENTS" });
 ```
 
 Verify status is `in-progress` or `open`.
@@ -170,21 +175,25 @@ Closes: <bead-id>"
 
 ## Phase 7: Close Bead
 
-```bash
-bd close $ARGUMENTS --reason "Implemented: [1-liner summary]"
+Complete the task and release any file reservations:
+
+```typescript
+bd_done({ id: "$ARGUMENTS", msg: "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
 
@@ -209,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:**
@@ -223,6 +233,8 @@ Task complete. For best performance:
 Next: Create PR or merge to main
 ```
 
+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

@@ -3,6 +3,10 @@ description: Analyze Github Actions logs and fix issues with bead tracking
 argument-hint: "[github-actions-url]"
 ---
 
+**Load skill:** `skill({ name: "systematic-debugging" })`
+
+For deep tracing: `skill({ name: "root-cause-tracing" })`
+
 ## Github Actions URL
 
 <url>$ARGUMENTS</url>
@@ -11,15 +15,16 @@ argument-hint: "[github-actions-url]"
 
 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
 
@@ -37,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

@@ -5,6 +5,8 @@ argument-hint: "[bead-id]"
 
 # Fix Type Errors
 
+**Load skill:** `skill({ name: "systematic-debugging" })`
+
 Run `bun run typecheck` and fix all type errors.
 
 ## Rules
@@ -17,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
-
-   ```bash
-   bd edit $ARGUMENTS --note "Type errors found: <count>"
-   ```
+1. **Before fixing:** Note the initial error count via `bd_msg` or notes
 
-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/fix-ui.md

@@ -6,7 +6,7 @@ agent: build
 
 # Fix UI: $ARGUMENTS
 
-use_skill("frontend-aesthetics")
+skill({ name: "frontend-aesthetics" })
 
 1. **Analyze:** Delegate to @vision for initial assessment
    - If screenshots/videos provided, @vision describes issue in detail

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

@@ -10,7 +10,7 @@ agent: build
 
 **Complex (unclear cause, multiple files):**
 
-use_skill("systematic-debugging")
+skill({ name: "systematic-debugging" })
 
 Follow four phases:
 

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

@@ -6,12 +6,16 @@ agent: build
 
 # Handoff
 
+**Load skill:** `skill({ name: "verification-before-completion" })`
+
 ## 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
@@ -121,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

@@ -6,10 +6,14 @@ agent: build
 
 # Implement
 
+**Load skill:** `skill({ name: "test-driven-development" })`
+
+For large tasks with 3+ phases, also load: `skill({ name: "subagent-driven-development" })`
+
 ## Phase 1: Setup Workspace
 
-```bash
-bd show $ARGUMENTS --json
+```typescript
+bd_show({ id: "$ARGUMENTS" });
 ```
 
 Check git state:
@@ -27,6 +31,16 @@ Create branch if not on bead branch:
 git checkout -b <bead-id>
 ```
 
+**Multi-agent coordination:**
+
+Initialize your agent session and claim the task:
+
+```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.
+
 ## Phase 2: Load Context
 
 **Check for previous session work:**
@@ -96,6 +110,16 @@ Mode: [Quick/Planned]
 
 ## Phase 4: Implementation
 
+**Reserve files before editing:**
+
+Before making changes, lock the files you'll modify to prevent conflicts with other agents:
+
+```typescript
+bd_reserve({ paths: ["src/auth.ts", "src/utils/**"] });
+```
+
+This creates an advisory lock. Other agents will see your reservation and avoid those files.
+
 ### With Plan (Planned Mode)
 
 For each unchecked step in plan.md:
@@ -139,7 +163,13 @@ If "pause" or "stop": Run `/handoff <bead-id>`.
 
 ## Phase 6: Complete
 
-When done:
+When done, release any file reservations:
+
+```typescript
+bd_release();
+```
+
+Then report:
 
 ```
 Implementation Complete: <bead-id>