opencodekit 0.12.6 → 0.13.0

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

@@ -1,6 +1,6 @@
 ---
 description: AI-powered task triage, prioritization, and workload analysis
-argument-hint: "[--auto-assign] [--sla] [--bottleneck]"
+argument-hint: "[--quick] [--auto-assign] [--sla] [--bottleneck]"
 agent: build
 ---
 
@@ -14,11 +14,54 @@ skill({ name: "beads" });
 
 Analyze open tasks and optimize prioritization using dependency graph analysis, SLA tracking, and multi-agent coordination.
 
-## Phase 1: Initialize Beads Connection
+## Quick Mode
+
+If `--quick` flag is passed, skip deep analysis and provide immediate actionable output:
+
+```bash
+bd ready --json
+bd list --status=in_progress --json
+```
+
+**Quick Output:**
+
+```
+Quick Triage
+━━━━━━━━━━━━
+
+Ready to start:
+• bd-abc12: "Task title" (P1)
+• bd-def34: "Task title" (P2)
+
+In progress:
+• bd-ghi56: "Task title" - claimed by [agent]
+
+Next: /start <bead-id>
+```
+
+Then stop. Don't run full analysis phases.
+
+## Full Triage (Default)
+
+## Phase 1: Health Check
+
+Run `bd doctor` to ensure database integrity (recommended weekly):
+
+```bash
+bd doctor --fix 2>/dev/null || bd doctor
+```
+
+This detects and auto-fixes:
+
+- Orphaned issues (work committed but issue not closed)
+- Database/JSONL sync issues
+- Migration updates
+
+## Phase 2: Initialize Beads Connection
 
 !`bd status`
 
-## Phase 2: Gather Workspace State
+## Phase 3: Gather Workspace State
 
 Run in parallel:
 
@@ -27,8 +70,8 @@ Run in parallel:
 
 ```typescript
 // Custom tools (not shell commands)
-bd-release(); // Lists active locks when called with no args
-bd-inbox({ n: 10, unread: true, to: "all" });
+bd - release(); // Lists active locks when called with no args
+bd - inbox({ n: 10, unread: true, to: "all" });
 
 // Search for past discussions on recurring issues
 search_session({ query: "blocked OR regression OR urgent", limit: 10 });
@@ -43,7 +86,7 @@ Capture:
 - Pending messages
 - Past context on recurring issues
 
-## Phase 3: Analyze Dependencies
+## Phase 4: Analyze Dependencies
 
 Use `bd dep tree` to understand blocking relationships:
 
@@ -55,7 +98,7 @@ This provides:
 - **Keystones**: High-impact tasks that unlock multiple paths
 - **Cycles**: Circular dependencies (must break)
 
-## Phase 4: Priority Classification
+## Phase 5: Priority Classification
 
 ### Priority Matrix
 
@@ -112,7 +155,7 @@ const slaStatus =
       : "OK";
 ```
 
-## Phase 5: Bottleneck Analysis
+## Phase 6: Bottleneck Analysis
 
 Identify blocking patterns:
 
@@ -154,7 +197,7 @@ Resolution Options:
 Run: bd update <id> --remove-dep <dep-id>
 ```
 
-## Phase 6: Generate Triage Report
+## Phase 7: Generate Triage Report
 
 ```
 ╔══════════════════════════════════════════════════════════════════════════╗
@@ -210,7 +253,7 @@ RECOMMENDATIONS
 ╚══════════════════════════════════════════════════════════════════════════╝
 ```
 
-## Phase 7: Auto-Assignment (Optional)
+## Phase 8: Auto-Assignment (Optional)
 
 If `--auto-assign` flag:
 
@@ -261,7 +304,7 @@ Skipped:
 - bd-old88: No matching role detected (manual assignment needed)
 ```
 
-## Phase 8: Batch Operations
+## Phase 9: Batch Operations
 
 ### Bulk Priority Update
 
@@ -286,7 +329,18 @@ console.log("2. Move to P4 backlog");
 console.log("3. Review individually");
 ```
 
-## Phase 9: Sync and Notify
+### Database Cleanup (Weekly Maintenance)
+
+Keep database small for performance (target: under 200-500 issues):
+
+```bash
+bd cleanup --days 7  # Remove closed issues older than 7 days
+bd list --status=closed --json | wc -l  # Check closed count
+```
+
+**Best Practice (from Steve Yegge):** Run `bd cleanup` every few days to prevent database bloat.
+
+## Phase 10: Sync and Notify
 
 ```typescript
 

package/dist/template/.opencode/command/ui-review.md

@@ -3,6 +3,7 @@ description: Review UI/UX design for quality, aesthetics, and best practices
 argument-hint: "<image-or-component-path> [--bead=<id>] [--responsive] [--dark-mode]"
 agent: vision
 model: proxypal/gemini-3-pro-preview
+subtask: true
 ---
 
 # UI Review: $ARGUMENTS

package/dist/template/.opencode/memory/project/architecture.md

@@ -1,26 +1,79 @@
 ---
 purpose: Key modules, directory structure, architectural decisions
-updated: 2024-12-21
+updated: 2025-01-06
 ---
 
 # Project Architecture
 
 ## Directory Structure
 
-<!-- Key directories and their purpose -->
+```
+src/
+  index.ts              # CLI entry point (cac-based)
+  commands/
+    init.ts             # ock init - scaffolds .opencode/
+    agent.ts            # ock agent - manage agents
+    skill.ts            # ock skill - manage skills
+    config.ts           # ock config - edit opencode.json
+    upgrade.ts          # ock upgrade - update templates
+    menu.ts             # Interactive menu, doctor, status
+    completion.ts       # Shell completions
+  utils/
+    logger.ts           # Logging utilities
+    errors.ts           # Error handling
+    safe-prompts.ts     # @clack/prompts wrappers
+
+dist/
+  index.js              # Built CLI bundle
+  template/.opencode/   # Template files copied during init
+
+.opencode/              # OpenCode configuration (source of truth)
+  agent/                # Agent definitions
+  command/              # Workflow commands
+  skills/               # Skills library
+  tool/                 # Custom tools (memory-*, bd-*)
+  plugin/               # OpenCode plugins
+  memory/               # Persistent knowledge
+
+.beads/                 # Task tracking database
+```
 
 ## Key Modules
 
-<!-- Core files/modules and what they do -->
+### CLI (src/index.ts)
+
+Entry point using `cac` library. Registers commands, parses args, handles errors.
+
+### Init Command (src/commands/init.ts)
+
+Core command - copies `.opencode/` template from dist to target project.
+
+### Build Process
+
+1. `bun build` bundles src/index.ts → dist/index.js
+2. rsync copies .opencode/ → dist/template/.opencode/
+3. Published package includes dist/ only
 
 ## Data Flow
 
-<!-- How data moves through the system -->
+```
+User runs: npx opencodekit init
+  → dist/index.js executes
+  → init command copies dist/template/.opencode/ to ./.opencode/
+  → User has full OpenCode setup
+```
 
 ## External Dependencies
 
-<!-- Critical third-party services, APIs -->
+- **cac**: CLI framework
+- **@clack/prompts**: Interactive prompts
+- **zod**: Schema validation
+- **beads-village**: Task tracking integration
+- **@opencode-ai/plugin**: Plugin SDK
 
 ## Architectural Decisions
 
-<!-- Why things are structured this way -->
+1. **Bun-first**: Uses Bun for speed, but builds to Node-compatible output
+2. **Template bundling**: .opencode/ copied at build time, not runtime
+3. **No transpilation**: TypeScript bundled directly by Bun
+4. **Colocated tests**: Tests live next to source files (*.test.ts)

package/dist/template/.opencode/memory/project/beads-workflow.md

@@ -0,0 +1,278 @@
+---
+purpose: Complete beads workflow mapping for OpenCodeKit commands
+updated: 2025-01-07
+---
+
+# Beads Workflow Best Practices
+
+Based on Steve Yegge's best practices and official beads documentation.
+
+## Core Principles
+
+| Principle                | Why                              | How                                  |
+| ------------------------ | -------------------------------- | ------------------------------------ |
+| One task per session     | Fresh context prevents confusion | Restart after `bd close`             |
+| Plan outside beads first | Better planning tools exist      | Use `/brainstorm` → `/plan` → import |
+| File lots of issues      | Track any work >2 minutes        | `bd create` liberally                |
+| "Land the plane" = PUSH  | `bd sync` means git push         | Always verify push succeeded         |
+| Keep DB small            | Performance degrades >500 issues | `bd cleanup --days 7` weekly         |
+
+## Maintenance Schedule
+
+| Task         | Frequency      | Command               | Why                                    |
+| ------------ | -------------- | --------------------- | -------------------------------------- |
+| Health check | Weekly         | `bd doctor --fix`     | Repairs orphaned issues, sync problems |
+| Cleanup      | Every few days | `bd cleanup --days 7` | Keep DB under 200-500 issues           |
+| Upgrade      | Weekly         | `bd upgrade`          | Latest features and fixes              |
+| Git hooks    | Once per repo  | `bd hooks install`    | Auto-sync on commit/merge/checkout     |
+
+## Command Configuration Best Practices
+
+Based on [OpenCode Command Docs](https://opencode.ai/docs/commands/).
+
+### Frontmatter Options
+
+```yaml
+---
+description: Short description shown in TUI command list
+argument-hint: "<required> [optional] [--flag]"
+agent: build | planner | scout | explore | review | vision
+subtask: true # Run as subagent (doesn't pollute primary context)
+model: gemini-2.5-pro # Override default model
+---
+```
+
+### Prompt Syntax
+
+| Syntax       | Purpose                  | Example                       |
+| ------------ | ------------------------ | ----------------------------- |
+| `$ARGUMENTS` | All arguments as string  | `/fix $ARGUMENTS`             |
+| `$1`, `$2`   | Positional arguments     | `/start $1` → `/start bd-abc` |
+| `!`command`` | Inject shell output      | `!`git status``               |
+| `@filepath`  | Include file content     | `@src/config.ts`              |
+| `$SELECTION` | Current editor selection | For IDE integrations          |
+
+### When to Use `subtask: true`
+
+**Use subtask for research/analysis** - prevents context pollution in primary agent:
+
+| Command Type             | `subtask: true`? | Why                                  |
+| ------------------------ | ---------------- | ------------------------------------ |
+| Research/exploration     | ✅ Yes           | Heavy reads, doesn't need to persist |
+| Code review/analysis     | ✅ Yes           | Analysis output, not implementation  |
+| UI/UX analysis           | ✅ Yes           | Design feedback, not code changes    |
+| Status/dashboard         | ✅ Yes           | Read-only information gathering      |
+| Implementation           | ❌ No            | Needs full context for edits         |
+| Lifecycle (start/finish) | ❌ No            | Coordinates state, needs persistence |
+| Generation (artifacts)   | ❌ No            | Creates files that need tracking     |
+
+### Commands by Category
+
+#### Research Commands (`subtask: true`)
+
+```
+/research, /analyze-project, /review-codebase, /brainstorm,
+/status, /summarize, /init, /ui-review, /accessibility-check,
+/analyze-mockup, /design-audit, /research-ui, /design
+```
+
+#### Lifecycle Commands (NO subtask)
+
+```
+/triage, /start, /create, /new-feature, /issue, /plan,
+/implement, /commit, /finish, /handoff, /resume, /pr, /fix
+```
+
+#### Generation Commands (NO subtask)
+
+```
+/generate-image, /generate-icon, /generate-diagram,
+/generate-pattern, /generate-storyboard, /edit-image, /restore-image
+```
+
+#### Utility Commands (NO subtask)
+
+```
+/quick-build, /fix-ci, /fix-types, /fix-ui,
+/revert-feature, /integration-test, /skill-create, /skill-optimize
+```
+
+## Command → Beads Mapping
+
+### Lifecycle Commands (Touch Beads)
+
+| Command           | Agent   | Beads Operations                                       | When to Use                 |
+| ----------------- | ------- | ------------------------------------------------------ | --------------------------- |
+| `/triage`         | build   | `bd doctor`, `bd list`, `bd ready`, `bd cleanup`       | Start of day, find work     |
+| `/triage --quick` | build   | `bd ready`, `bd list --status=in_progress`             | Fast check, what's next     |
+| `/start <id>`     | build   | `bd update --status in_progress`, `bd hooks install`   | Claim a task                |
+| `/create`         | build   | `bd create`, `bd sync`                                 | Create new tracked task     |
+| `/new-feature`    | planner | `bd create` (epic + subtasks), `bd dep add`, `bd sync` | Complex feature with phases |
+| `/issue <num>`    | build   | `bd create`, `bd sync`, `gh issue comment`             | Import GitHub issue         |
+| `/plan <id>`      | planner | `bd create` (subtasks), `bd dep add`, `bd sync`        | Break down task             |
+| `/implement <id>` | build   | `bd update --status in_progress`, `bd sync`            | Do the work                 |
+| `/commit [id]`    | build   | `bd sync` (if bead-id provided)                        | Commit with traceability    |
+| `/finish <id>`    | build   | `bd close`, `bd sync`                                  | Complete task (asks first)  |
+| `/handoff <id>`   | build   | `bd sync`                                              | Pause work, save context    |
+| `/resume <id>`    | build   | `bd update --status in_progress`                       | Continue previous work      |
+| `/pr <id>`        | build   | `bd-msg`, `bd sync`                                    | Create pull request         |
+| `/fix`            | build   | `bd sync` (after user confirms commit)                 | Fix bugs with tracking      |
+| `/status`         | explore | `bd status`, `bd list`, `bd-inbox`, `bd-release`       | Dashboard view              |
+
+### Research Commands (Read-Only Beads)
+
+| Command            | Agent   | Beads Operations      | Notes                      |
+| ------------------ | ------- | --------------------- | -------------------------- |
+| `/research <id>`   | scout   | `bd show` (read-only) | NO `bd sync` - subagent    |
+| `/brainstorm`      | planner | None                  | Pure planning, no tracking |
+| `/analyze-project` | explore | None                  | Codebase exploration       |
+| `/summarize`       | explore | None                  | Session/code summary       |
+| `/review-codebase` | review  | None                  | Code review                |
+
+### Non-Beads Commands
+
+| Command                | Agent   | Purpose                        |
+| ---------------------- | ------- | ------------------------------ |
+| `/quick-build`         | build   | Trivial fixes, no bead created |
+| `/design`              | planner | Architecture design            |
+| `/ui-review`           | vision  | UI/UX analysis                 |
+| `/accessibility-check` | vision  | A11y audit                     |
+| `/fix-ci`              | build   | CI pipeline fixes              |
+| `/fix-types`           | build   | TypeScript errors              |
+
+## Workflow Patterns
+
+### Pattern 1: Standard Task (S/M size)
+
+```
+/triage --quick          # Find ready work
+/start bd-xxx            # Claim task, create branch
+/implement bd-xxx        # Do the work
+/finish bd-xxx           # Verify, commit (asks first), close
+/pr bd-xxx               # Create PR (asks first)
+```
+
+### Pattern 2: Complex Feature (L/XL size)
+
+```
+/triage                  # Full triage with health check
+/new-feature "Feature"   # Creates epic + spec + plan + subtasks
+/start bd-xxx.1          # Start first subtask
+/implement bd-xxx.1      # Implement
+/finish bd-xxx.1         # Complete subtask
+/start bd-xxx.2          # Next subtask (now unblocked)
+...
+/finish bd-xxx           # Close epic when all subtasks done
+```
+
+### Pattern 3: Research-First
+
+```
+/create "Complex task"   # Create bead with spec
+/research bd-xxx         # Gather information (scout agent)
+/plan bd-xxx             # Design approach (planner agent)
+/implement bd-xxx        # Now implement with full context
+/finish bd-xxx           # Complete
+```
+
+### Pattern 4: Bug Fix
+
+```
+/issue 123               # Import GitHub issue as bead
+/start bd-xxx            # Claim
+/fix bd-xxx              # Diagnose + fix (asks before commit)
+/finish bd-xxx           # Verify + close
+/pr bd-xxx               # Create PR
+```
+
+### Pattern 5: Session Handoff
+
+```
+/implement bd-xxx        # Working on task...
+# Context getting large or end of day
+/handoff bd-xxx          # Save progress, creates handoff.md
+# New session
+/resume bd-xxx           # Load context, continue
+```
+
+### Pattern 6: Trivial Fix (No Bead)
+
+```
+/quick-build "fix typo"  # Single file, <30 min, commits directly
+```
+
+## Agent Boundaries
+
+### Leader Agents (Touch Beads)
+
+| Agent   | Can Do                          | Cannot Do |
+| ------- | ------------------------------- | --------- |
+| `build` | All beads operations, `bd sync` | -         |
+| `rush`  | All beads operations, `bd sync` | -         |
+
+### Subagents (Read-Only Beads)
+
+| Agent     | Can Do                                 | Cannot Do             |
+| --------- | -------------------------------------- | --------------------- |
+| `planner` | `bd show`, `bd list`, create artifacts | `bd sync`, `bd close` |
+| `scout`   | `bd show` (read context)               | Any writes            |
+| `explore` | `bd show`, `bd list`                   | Any writes            |
+| `review`  | `bd show`                              | Any writes            |
+| `vision`  | None                                   | All beads operations  |
+
+## File Locking (Multi-Agent)
+
+```typescript
+// Before editing shared files
+bd - reserve({ paths: ["src/auth.ts"], ttl: 600 });
+
+// Do work...
+
+// After completing edits
+bd - release({ paths: ["src/auth.ts"] });
+
+// Check active locks
+bd - release(); // No args = list locks
+```
+
+## Commit Message Format
+
+Always include bead ID for traceability:
+
+```
+feat(auth): add token refresh (bd-a1b2c3)
+
+Implement automatic token refresh when access token expires.
+
+Closes: bd-a1b2c3
+```
+
+## Session End Checklist
+
+1. [ ] All work committed
+2. [ ] `bd sync` run (pushes to git)
+3. [ ] If incomplete: `/handoff <id>` created
+4. [ ] If complete: `/finish <id>` run
+5. [ ] No stale file locks
+
+## Troubleshooting
+
+| Problem                | Solution                                |
+| ---------------------- | --------------------------------------- |
+| "bd command not found" | `npm install -g beads-village`          |
+| Orphaned issues        | `bd doctor --fix`                       |
+| DB too large           | `bd cleanup --days 3`                   |
+| Sync conflicts         | `bd sync --force` (careful!)            |
+| Stale handoff          | Check if rebase needed before `/resume` |
+| Task not in `bd ready` | Check blockers: `bd show <id>`          |
+
+## Anti-Patterns
+
+| Don't                                  | Why                   | Do Instead                       |
+| -------------------------------------- | --------------------- | -------------------------------- |
+| Skip `bd sync` at session end          | Changes won't persist | Always sync before stopping      |
+| Create beads for trivial fixes         | DB bloat              | Use `/quick-build`               |
+| Work on blocked tasks                  | Wastes time           | Use `bd ready` to find unblocked |
+| Subagents running `bd sync`            | Coordination issues   | Only leader agents sync          |
+| Force through complex with quick-build | Technical debt        | Proper `/create` workflow        |
+| Ignore `bd doctor` warnings            | Corruption risk       | Fix issues promptly              |