opencodekit 0.16.6 → 0.16.8

package/dist/index.js

@@ -759,7 +759,7 @@ var cac = (name = "") => new CAC(name);
 // package.json
 var package_default = {
   name: "opencodekit",
-  version: "0.16.6",
+  version: "0.16.8",
   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

@@ -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

@@ -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

@@ -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

@@ -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

@@ -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

@@ -165,17 +165,34 @@
 					"reasoning": true,
 					"tool_call": true,
 					"options": {
-						"reasoningEffort": "medium"
+						"thinking": {
+							"type": "enabled",
+							"budgetTokens": 8192,
+							"reasoning_effort": "high"
+						},
+						"interleaved": {
+							"field": "reasoning_content"
+						}
 					},
 					"variants": {
 						"high": {
 							"options": {
-								"reasoningEffort": "high"
+								"thinkingBudget": 16384,
+								"type": "enabled",
+								"reasoning_effort": "high"
+							},
+							"interleaved": {
+								"field": "reasoning_content"
 							}
 						},
 						"max": {
 							"options": {
-								"reasoningEffort": "max"
+								"thinkingBudget": 32768,
+								"type": "enabled",
+								"reasoning_effort": "high"
+							},
+							"interleaved": {
+								"field": "reasoning_content"
 							}
 						}
 					}
@@ -257,7 +274,8 @@
 					"tool_call": true,
 					"options": {
 						"reasoningEffort": "medium",
-						"reasoningSummary": "auto"
+						"reasoningSummary": "auto",
+						"textVerbosity": "medium"
 					},
 					"variants": {
 						"high": {
@@ -282,7 +300,8 @@
 					"tool_call": true,
 					"options": {
 						"reasoningEffort": "medium",
-						"reasoningSummary": "auto"
+						"reasoningSummary": "auto",
+						"textVerbosity": "medium"
 					},
 					"variants": {
 						"fast": {
@@ -359,6 +378,47 @@
 						"top_p": 0.95
 					},
 					"reasoning": true
+				},
+				"kimi-k2.5-free": {
+					"limit": {
+						"context": 262144,
+						"output": 32768
+					},
+					"temperature": true,
+					"reasoning": true,
+					"tool_call": true,
+					"options": {
+						"thinking": {
+							"type": "enabled",
+							"budgetTokens": 8192,
+							"reasoning_effort": "high"
+						},
+						"interleaved": {
+							"field": "reasoning_content"
+						}
+					},
+					"variants": {
+						"high": {
+							"options": {
+								"thinkingBudget": 16384,
+								"type": "enabled",
+								"reasoning_effort": "high"
+							},
+							"interleaved": {
+								"field": "reasoning_content"
+							}
+						},
+						"max": {
+							"options": {
+								"thinkingBudget": 32768,
+								"type": "enabled",
+								"reasoning_effort": "high"
+							},
+							"interleaved": {
+								"field": "reasoning_content"
+							}
+						}
+					}
 				}
 			}
 		},

package/dist/template/.opencode/package.json

@@ -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

@@ -1,6 +1,6 @@
 {
 	"name": "opencodekit",
-	"version": "0.16.6",
+	"version": "0.16.8",
 	"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

@@ -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  |