npm - opencodekit - Versions diffs - 0.16.6 → 0.16.7 - Mend

opencodekit 0.16.6 → 0.16.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (10) hide show

package/dist/index.js +1 -1
package/dist/template/.opencode/command/design.md +1 -1
package/dist/template/.opencode/command/review-codebase.md +2 -2
package/dist/template/.opencode/command/ui-review.md +1 -1
package/dist/template/.opencode/dcp.jsonc +2 -0
package/dist/template/.opencode/memory/project/tech-stack.md +1 -1
package/dist/template/.opencode/opencode.json +9 -13
package/dist/template/.opencode/package.json +1 -1
package/package.json +1 -1
package/dist/template/.opencode/memory/beads-workflow.md +0 -564

package/dist/index.js CHANGED Viewed

@@ -759,7 +759,7 @@ var cac = (name = "") => new CAC(name);
 // package.json
 var package_default = {
   name: "opencodekit",
-  version: "0.16.6",
+  version: "0.16.7",
   description: "CLI tool for bootstrapping and managing OpenCodeKit projects",
   keywords: ["agents", "cli", "mcp", "opencode", "opencodekit", "template"],
   license: "MIT",

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

@@ -609,7 +609,7 @@ observation({
 For component/page designs:
 ```bash
-br create "Implement [component/page] design" -t task -p 2
+br create "Implement [component/page] design" --type task --priority 2
 ```
 ### Bead Integration

package/dist/template/.opencode/command/review-codebase.md CHANGED Viewed

@@ -35,7 +35,7 @@ Parse `$ARGUMENTS` to determine what to review:
 | Input                    | Scope                  | How to Get Code                             |
 | ------------------------ | ---------------------- | ------------------------------------------- |
 | File/directory path      | That path only         | `read` or `glob` + `read`                   |
-| Bead ID (e.g., `br-123`) | Implementation vs spec | `br show` then `git diff` from spec         |
+| Bead ID (e.g., `bd-123`) | Implementation vs spec | `br show` then `git diff` from spec         |
 | PR number (e.g., `#45`)  | PR changes             | `gh pr diff 45`                             |
 | `all` or empty           | Recent changes         | `git diff main...HEAD` or `git diff HEAD~5` |
@@ -123,7 +123,7 @@ Review each category with specific focus:
 For each Critical or Important finding:
 ```bash
-br create "[Review] <brief issue description>" -t bug -p 1
+br create "[Review] <brief issue description>" --type bug --priority 1
 ```
 Skip creating beads for Minor issues (just report them).

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

@@ -284,7 +284,7 @@ If `--bead=<id>` provided:
 ```bash
 # Create issues for critical findings
-br create "[UI] Fix invisible focus states" -t bug -p 1
+br create "[UI] Fix invisible focus states" --type bug --priority 1
 # Then link to parent bead
 br dep add <task-id> <bead-id>

package/dist/template/.opencode/dcp.jsonc CHANGED Viewed

@@ -30,6 +30,8 @@
 		"settings": {
 			"nudgeEnabled": true,
 			"nudgeFrequency": 10,
+			// Trigger compression at ~94% of Copilot's 128k context limit
+			"contextLimit": 120000,
 			// Protect state-modifying and critical workflow tools
 			// LSP excluded: ephemeral exploration, prune after understanding
 			"protectedTools": [

package/dist/template/.opencode/memory/project/tech-stack.md CHANGED Viewed

@@ -45,7 +45,7 @@ This file is automatically injected into ALL AI prompts via `opencode.json` inst
 ## Active Integrations
 - **OpenCode AI:** @opencode-ai/plugin (^1.1.12) - OpenCode integration
-- **Beads CLI:** @beads/bd (^0.29.0) - Task tracking CLI
+- **Beads CLI:** beads_rust (br) - Task tracking CLI
 ---

package/dist/template/.opencode/opencode.json CHANGED Viewed

@@ -165,18 +165,12 @@
 					"reasoning": true,
 					"tool_call": true,
 					"options": {
-						"reasoningEffort": "medium"
-					},
-					"variants": {
-						"high": {
-							"options": {
-								"reasoningEffort": "high"
-							}
+						"thinking": {
+							"type": "enabled",
+							"budgetTokens": 31999
 						},
-						"max": {
-							"options": {
-								"reasoningEffort": "max"
-							}
+						"interleaved": {
+							"field": "reasoning_content"
 						}
 					}
 				}
@@ -257,7 +251,8 @@
 					"tool_call": true,
 					"options": {
 						"reasoningEffort": "medium",
-						"reasoningSummary": "auto"
+						"reasoningSummary": "auto",
+						"textVerbosity": "medium"
 					},
 					"variants": {
 						"high": {
@@ -282,7 +277,8 @@
 					"tool_call": true,
 					"options": {
 						"reasoningEffort": "medium",
-						"reasoningSummary": "auto"
+						"reasoningSummary": "auto",
+						"textVerbosity": "medium"
 					},
 					"variants": {
 						"fast": {

package/dist/template/.opencode/package.json CHANGED Viewed

@@ -11,7 +11,7 @@
     "type-check": "tsc --noEmit"
   },
   "dependencies": {
-    "@opencode-ai/plugin": "1.1.50"
+    "@opencode-ai/plugin": "1.1.51"
   },
   "devDependencies": {
     "@types/node": "^25.1.0",

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
 	"name": "opencodekit",
-	"version": "0.16.6",
+	"version": "0.16.7",
 	"description": "CLI tool for bootstrapping and managing OpenCodeKit projects",
 	"keywords": ["agents", "cli", "mcp", "opencode", "opencodekit", "template"],
 	"license": "MIT",

package/dist/template/.opencode/memory/beads-workflow.md DELETED Viewed

@@ -1,564 +0,0 @@
----
-purpose: Complete beads workflow mapping for OpenCodeKit commands
-updated: 2025-01-08
----
-# 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 `br close`             |
-| Plan outside beads first | Better planning tools exist      | Use `/brainstorm` → `/plan` → import |
-| File lots of issues      | Track any work >2 minutes        | `br create` liberally                |
-| "Land the plane" = PUSH  | `br sync --flush-only` means git push         | Always verify push succeeded         |
-| Keep DB small            | Performance degrades >500 issues | `br cleanup --days 7` weekly         |
-## Hierarchy Model: Epic → Task → Subtask
-### Hierarchy Levels
-```
-Epic (feature-level)
-├── Task 1 (domain or phase)
-│   ├── Subtask 1.1 (atomic work unit)
-│   └── Subtask 1.2
-├── Task 2 (blocked by Task 1)
-│   └── Subtask 2.1
-└── Task 3 (blocked by Task 2)
-```
-| Level   | Scope        | Duration   | Agent Work                            |
-| ------- | ------------ | ---------- | ------------------------------------- |
-| Epic    | Full feature | Days-weeks | Coordinate, delegate, not implement   |
-| Task    | Domain/phase | Hours-day  | May implement or delegate to subtasks |
-| Subtask | Atomic unit  | 30min-2hrs | Implement directly                    |
-### Size Estimation
-| Size | Tool Calls | Hierarchy Level    | Session Scope     |
-| ---- | ---------- | ------------------ | ----------------- |
-| S    | ~10        | Subtask            | Quick fix         |
-| M    | ~30        | Task               | Single session    |
-| L    | ~100       | Task with subtasks | Single session    |
-| XL   | 100+       | Epic required      | Multiple sessions |
-### Creating Hierarchy
-```bash
-# Create epic
-br create "User Authentication" -t epic -p 2
-# Returns: bd-epic
-# Create tasks with dependencies
-br create "Setup database schema" -t task -p 2
-br dep add bd-xxx1 bd-epic
-br create "Implement API endpoints" -t task -p 2
-br dep add bd-xxx2 bd-epic
-br dep add bd-xxx2 bd-xxx1 --type blocks  # Sequential
-# Create subtasks for complex tasks
-br create "POST /api/users endpoint" -t subtask -p 2
-br dep add bd-xxx2.1 bd-xxx2
-br create "GET /api/users/:id endpoint" -t subtask -p 2
-br dep add bd-xxx2.2 bd-xxx2
-br dep add bd-xxx2.2 bd-xxx2.1 --type blocks  # Sequential subtasks
-# Verify hierarchy
-br dep tree bd-epic
-```
-## Git Worktree Integration
-### When to Use Worktrees
-| Scenario                     | Use Worktree | Why                        |
-| ---------------------------- | ------------ | -------------------------- |
-| Epic-level work              | ✅ Yes       | Multi-session isolation    |
-| Parallel feature development | ✅ Yes       | No context switching       |
-| Long-running experiments     | ✅ Yes       | Keep main workspace clean  |
-| Single task (S/M)            | ❌ No        | Branch is sufficient       |
-| Hotfix/quick-build           | ❌ No        | Overkill for small changes |
-### Worktree Setup
-```bash
-# Verify .gitignore
-grep -q "^\.worktrees/$" .gitignore || echo ".worktrees/" >> .gitignore
-# Create worktree for feature
-git worktree add .worktrees/bd-xxx -b feature/auth
-# Navigate and setup
-cd .worktrees/bd-xxx
-npm install  # or project-specific setup
-# Verify clean baseline
-npm test
-```
-### Beads + Worktree Architecture
-```
-main-repo/
-├── .beads/              ← Shared database (all worktrees use this)
-├── .worktrees/
-│   ├── feature-a/       ← Worktree 1
-│   │   └── (working copy)
-│   └── feature-b/       ← Worktree 2
-│       └── (working copy)
-└── src/                 ← Main working copy
-```
-**Key insight:** `.beads/` is shared. All worktrees access the same database.
-### Worktree Daemon Behavior
-| Mode        | Configuration                          | Use When                 |
-| ----------- | -------------------------------------- | ------------------------ |
-| Default     | Daemon auto-disabled in worktrees      | Most cases               |
-| Sync branch | `br config set sync-branch beads-sync` | Full daemon in worktrees |
-| External DB | `export BEADS_DIR=~/project/.beads`    | Complete separation      |
-| Sandbox     | `br --sandbox` or `BEADS_NO_DAEMON=1`  | Claude Code, containers  |
-### Worktree Cleanup
-```bash
-# When feature complete
-cd /main-repo
-git worktree remove .worktrees/feature-a
-# Or force if dirty
-git worktree remove --force .worktrees/feature-a
-# Clean orphaned worktrees
-git worktree prune
-```
-## Subagent Delegation Patterns
-### Agent Hierarchy
-```
-Leader Agents (touch beads, sync, coordinate)
-├── build   - Primary implementation agent
-└── plan    - Architecture and planning agent
-Subagents (read-only, stateless workers)
-├── general - Fast, well-defined tasks
-├── explore - Codebase search, patterns
-├── scout   - External docs, best practices
-├── review  - Code review, debugging
-└── vision  - UI/UX, visual analysis
-```
-### Delegation Rules
-| Agent     | Can Do                   | Cannot Do              |
-| --------- | ------------------------ | ---------------------- |
-| `build`   | All beads ops, `br sync --flush-only` | -                      |
-| `plan`    | All beads ops, `br sync --flush-only` | -                      |
-| `general` | Read, small edits        | `br sync --flush-only`, beads write |
-| `explore` | Read, grep, glob         | Edit, write, `br sync --flush-only` |
-| `scout`   | Fetch, search, Context7  | Edit, write, `br sync --flush-only` |
-| `plan`    | Read, create artifacts   | Edit files, `br sync --flush-only`  |
-| `review`  | Read, analyze, suggest   | Edit files, `br sync --flush-only`  |
-| `vision`  | Analyze images, mockups  | All beads operations   |
-### Parallel Research Pattern
-Fire subagents in parallel, continue working immediately:
-```typescript
-// Launch both - don't wait
-Task({
-  subagent_type: "explore",
-  prompt: `Find codebase patterns for [task]:
-    - Similar implementations
-    - Test patterns
-    - Affected files
-    Return: File paths, patterns, test approach`,
-  description: "Explore codebase",
-});
-Task({
-  subagent_type: "scout",
-  prompt: `Research best practices for [task]:
-    - Official documentation
-    - Common patterns
-    - Pitfalls to avoid
-    Return: Examples, warnings, recommendations`,
-  description: "Scout external docs",
-});
-// Continue working immediately
-// Collect results when needed
-```
-### When to Delegate
-| Situation                | Delegate To | Why                        |
-| ------------------------ | ----------- | -------------------------- |
-| Need codebase patterns   | `@explore`  | Fast grep/glob             |
-| Need library docs        | `@scout`    | Context7, GitHub patterns  |
-| Complex planning         | `@plan`     | Structured decomposition   |
-| Code review before merge | `@review`   | Fresh eyes, evidence-based |
-| UI/mockup analysis       | `@vision`   | Visual expertise           |
-| Stuck on implementation  | `@explore`  | Fresh search perspective   |
-## Maintenance Schedule
-| Task         | Frequency      | Command               | Why                                    |
-| ------------ | -------------- | --------------------- | -------------------------------------- |
-| Health check | Weekly         | `br doctor --fix`     | Repairs orphaned issues, sync problems |
-| Cleanup      | Every few days | `br cleanup --days 7` | Keep DB under 200-500 issues           |
-| Upgrade      | Weekly         | `br upgrade`          | Latest features and fixes              |
-| Git hooks    | Once per repo  | `br 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 | plan | 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   | `br doctor`, `br list`, `br ready`, `br cleanup`       | Start of day, find work     |
-| `/triage --quick`            | build   | `br ready`, `br list --status=in_progress`             | Fast check, what's next     |
-| `/start <id>`                | build   | `br update --status in_progress`, `br hooks install`   | Claim a task                |
-| `/start <id> --worktree`     | build   | + Create git worktree                                  | Isolated feature work       |
-| `/start <id> --research`     | build   | + Parallel subagent research                           | Complex task preparation    |
-| `/create`                    | build   | `br create`, `br sync --flush-only`                                 | Create new tracked task     |
-| `/new-feature`               | plan    | `br create` (epic + subtasks), `br dep add`, `br sync --flush-only` | Complex feature with phases |
-| `/new-feature --worktree`    | plan    | + Create git worktree for epic                         | Isolated feature branch     |
-| `/issue <num>`               | build   | `br create`, `br sync --flush-only`, `gh issue comment`             | Import GitHub issue         |
-| `/plan <id>`                 | plan    | `br create` (subtasks), `br dep add`, `br sync --flush-only`        | Break down task             |
-| `/plan <id> --create-beads`  | plan    | Create child beads after planning                      | Auto-hierarchy creation     |
-| `/implement <id>`            | build   | `br update --status in_progress`, `br sync --flush-only`            | Do the work                 |
-| `/implement <id> --parallel` | build   | + Aggressive subagent research                         | Complex implementation      |
-| `/commit [id]`               | build   | `br sync --flush-only` (if bead-id provided)                        | Commit with traceability    |
-| `/finish <id>`               | build   | `br close`, `br sync --flush-only`                                  | Complete task (asks first)  |
-| `/handoff <id>`              | build   | `br sync --flush-only`                                              | Pause work, save context    |
-| `/resume <id>`               | build   | `br update --status in_progress`                       | Continue previous work      |
-| `/pr <id>`                   | build   | `br-msg`, `br sync --flush-only`                                    | Create pull request         |
-| `/fix`                       | build   | `br sync --flush-only` (after user confirms commit)                 | Fix bugs with tracking      |
-| `/status`                    | explore | `br status`, `br list`, `br-inbox`, `br-release`       | Dashboard view              |
-### Research Commands (Read-Only Beads)
-| Command            | Agent   | Beads Operations      | Notes                      |
-| ------------------ | ------- | --------------------- | -------------------------- |
-| `/research <id>`   | scout   | `br show` (read-only) | NO `br sync --flush-only` - subagent    |
-| `/brainstorm`      | plan    | 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`              | plan   | 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 with Worktree (L/XL size)
-```
-/triage                        # Full triage with health check
-/new-feature "Feature" --worktree  # Creates epic + subtasks + worktree
-cd .worktrees/bd-epic          # Enter worktree
-/start bd-xxx.1                # Start first task
-/implement bd-xxx.1            # Implement
-/finish bd-xxx.1               # Complete task
-/start bd-xxx.2                # Next task (now unblocked)
-/implement bd-xxx.2            # Continue...
-/finish bd-xxx.2               # Complete
-...
-/finish bd-epic                # Close epic when all tasks done
-git worktree remove .worktrees/bd-epic  # Cleanup worktree
-```
-### Pattern 3: Research-First with Subagent Delegation
-```
-/create "Complex task"         # Create bead with spec
-/start bd-xxx --research       # Claim + parallel subagent research
-/plan bd-xxx --create-beads    # Design with auto-hierarchy
-/implement bd-xxx.1            # Implement first subtask
-/finish bd-xxx.1               # Complete subtask
-/implement bd-xxx.2 --parallel # Next subtask with research
-/finish bd-xxx.2               # Complete subtask
-/finish bd-xxx                 # Close parent task
-```
-### 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
-```
-### Pattern 7: Epic with Parallel Workstreams
-```
-/new-feature "Big Feature" --worktree
-# Creates: bd-epic with bd-xxx1, bd-xxx2, bd-xxx3
-# Agent 1 (main worktree)
-/start bd-xxx1 --worktree
-/implement bd-xxx1
-/finish bd-xxx1
-# Agent 2 (separate worktree - if independent)
-/start bd-xxx2 --worktree
-/implement bd-xxx2
-/finish bd-xxx2
-# Merge when all complete
-/finish bd-epic
-```
-### Pattern 8: Ralph Wiggum Autonomous Loop
-For tasks that can run autonomously until completion. The agent loops until it outputs `<promise>COMPLETE</promise>` or hits max iterations.
-```
-/ralph-loop "Migrate all Jest tests to Vitest"
-# Or with PRD file:
-/ralph-loop "Complete PRD tasks" --prd PRD.md --max 50
-# Agent automatically:
-# 1. Picks highest-priority incomplete task
-# 2. Implements ONE feature
-# 3. Runs feedback loops (typecheck, test, lint)
-# 4. Commits if all pass
-# 5. Updates progress.txt
-# 6. Loops until <promise>COMPLETE</promise> or max iterations
-```
-**When to use Ralph:**
-| Scenario                  | Use Ralph? | Why                                  |
-| ------------------------- | ---------- | ------------------------------------ |
-| Test coverage improvement | ✅ Yes     | Clear success criteria, safe to loop |
-| Linting fixes             | ✅ Yes     | Deterministic, feedback-driven       |
-| Migration (Jest→Vitest)   | ✅ Yes     | Repetitive, well-defined end state   |
-| Feature implementation    | ⚠️ HITL    | Need oversight for design decisions  |
-| Architectural changes     | ❌ No      | Too risky for autonomous work        |
-| Vague "improve X" tasks   | ❌ No      | No clear completion criteria         |
-**Ralph + Beads Integration:**
-```bash
-# Create PRD from beads
-br list --status=open --json > PRD.json
-# Start Ralph loop
-/ralph-loop "Complete all open tasks" --prd PRD.json
-# Ralph will work through tasks, you can:
-ralph-status   # Check progress
-ralph-stop     # Stop gracefully
-# After completion, sync beads
-br sync --flush-only
-```
-**Key constraints:**
-- ONE feature per iteration (prevents context rot)
-- MUST pass all feedback loops before commit
-- Small steps > large changes
-- Always cap iterations (never infinite loops)
-## Agent Boundaries
-### Leader Agents (Touch Beads)
-| Agent   | Can Do                          | Cannot Do |
-| ------- | ------------------------------- | --------- |
-| `build` | All beads operations, `br sync --flush-only` | -         |
-| `plan`  | All beads operations, `br sync --flush-only` | -         |
-### Subagents (Read-Only Beads)
-| Agent     | Can Do                                 | Cannot Do             |
-| --------- | -------------------------------------- | --------------------- |
-| `plan`    | `br show`, `br list`, create artifacts | `br sync --flush-only`, `br close` |
-| `scout`   | `br show` (read context)               | Any writes            |
-| `explore` | `br show`, `br list`                   | Any writes            |
-| `review`  | `br 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({ _: true }); // No paths = 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. [ ] `br sync --flush-only` run (pushes to git)
-3. [ ] If incomplete: `/handoff <id>` created
-4. [ ] If complete: `/finish <id>` run
-5. [ ] No stale file locks (`br-release({ _: true })`)
-6. [ ] Worktrees cleaned up (if used)
-## Troubleshooting
-| Problem                      | Solution                                            |
-| ---------------------------- | --------------------------------------------------- |
-| "bd command not found"       | `npm install -g beads-village`                      |
-| Orphaned issues              | `br doctor --fix`                                   |
-| DB too large                 | `br cleanup --days 3`                               |
-| Sync conflicts               | `br sync --force` (careful!)                        |
-| Stale handoff                | Check if rebase needed before `/resume`             |
-| Task not in `br ready`       | Check blockers: `br show <id>`                      |
-| "Branch already checked out" | `rm -rf .git/beads-worktrees && git worktree prune` |
-| Daemon issues in worktree    | `br config set sync-branch beads-sync`              |
-| Sandbox environment          | `br --sandbox` or `BEADS_NO_DAEMON=1`               |
-## Anti-Patterns
-| Don't                                  | Why                   | Do Instead                       |
-| -------------------------------------- | --------------------- | -------------------------------- |
-| Skip `br sync --flush-only` 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 `br ready` to find unblocked |
-| Subagents running `br sync --flush-only`            | Coordination issues   | Only leader agents sync          |
-| Force through complex with quick-build | Technical debt        | Proper `/create` workflow        |
-| Ignore `br doctor` warnings            | Corruption risk       | Fix issues promptly              |
-| Skip worktree for XL features          | Merge conflicts       | Use `--worktree` flag            |
-| Implement epic directly                | Too large             | Work on subtasks instead         |
-| Wait for subagent results              | Blocks progress       | Fire parallel, continue working  |