opencodekit 0.9.1 → 0.10.0

package/README.md

@@ -251,10 +251,10 @@ You've successfully set up OpenCodeKit when:
 
 ---
 
-**OpenCodeKit v0.9.1**  
+**OpenCodeKit v0.9.2**  
 **Architecture**: Two-layer (Memory + Beads + Git)  
 **Package**: `npx opencodekit` to scaffold new projects  
-**New in v0.9.1**: Memory & Compaction plugin merge, session.start auto-load hook  
+**New in v0.9.2**: 6 new LSP tools, `ock init --beads` flag, improved tool guidance  
 **Ready for**: Daily production use
 
 Enjoy your streamlined agent system with clean phase transitions!

package/dist/index.js

@@ -750,7 +750,7 @@ var cac = (name = "") => new CAC(name);
 // package.json
 var package_default = {
   name: "opencodekit",
-  version: "0.9.1",
+  version: "0.10.0",
   description: "CLI tool for bootstrapping and managing OpenCodeKit projects",
   type: "module",
   repository: {
@@ -764,10 +764,7 @@ var package_default = {
   bin: {
     ock: "dist/index.js"
   },
-  files: [
-    "dist",
-    "README.md"
-  ],
+  files: ["dist", "README.md"],
   scripts: {
     dev: "bun run src/index.ts",
     build: "bun build src/index.ts --outdir dist --target node && mkdir -p dist/template && rsync -av --exclude=node_modules --exclude=dist --exclude=.git --exclude=coverage --exclude=.next --exclude=.turbo --exclude=logs --exclude=package-lock.json .opencode/ dist/template/.opencode/",
@@ -779,14 +776,7 @@ var package_default = {
     lint: "biome check .",
     "lint:fix": "biome check --fix ."
   },
-  keywords: [
-    "cli",
-    "opencodekit",
-    "template",
-    "agents",
-    "mcp",
-    "opencode"
-  ],
+  keywords: ["cli", "opencodekit", "template", "agents", "mcp", "opencode"],
   author: "OpenCodeKit",
   license: "MIT",
   engines: {
@@ -809,9 +799,7 @@ var package_default = {
     "@types/node": "^22.10.1",
     typescript: "^5.7.2"
   },
-  trustedDependencies: [
-    "@beads/bd"
-  ]
+  trustedDependencies: ["@beads/bd"]
 };
 
 // src/commands/agent.ts
@@ -3062,14 +3050,15 @@ async function editAutoupdate(configPath) {
 }
 
 // src/commands/init.ts
+import { execSync } from "node:child_process";
 import {
   existsSync as existsSync3,
   mkdirSync as mkdirSync2,
   readFileSync as readFileSync3,
-  writeFileSync as writeFileSync3,
-  readdirSync as readdirSync2
+  readdirSync as readdirSync2,
+  writeFileSync as writeFileSync3
 } from "node:fs";
-import { join as join3, dirname, basename } from "node:path";
+import { basename, dirname, join as join3 } from "node:path";
 import { fileURLToPath } from "node:url";
 var import_picocolors7 = __toESM(require_picocolors(), 1);
 var EXCLUDED_DIRS = [
@@ -3126,9 +3115,7 @@ async function copyDir(src, dest) {
       continue;
     const srcPath = join3(src, entry.name);
     const destPath = join3(dest, entry.name);
-    if (entry.isSymbolicLink()) {
-      continue;
-    } else if (entry.isDirectory()) {
+    if (entry.isSymbolicLink()) {} else if (entry.isDirectory()) {
       await copyDir(srcPath, destPath);
     } else {
       const content = readFileSync3(srcPath, "utf-8");
@@ -3190,7 +3177,28 @@ async function initCommand(options = {}) {
     process.exit(1);
   }
   s.stop("Done");
-  le(`cd .opencode && bun install`, "Next steps");
+  if (options.beads) {
+    const beadsDir = join3(targetDir, ".beads");
+    if (!existsSync3(beadsDir)) {
+      const bs = de();
+      bs.start("Initializing .beads/");
+      try {
+        execSync("bd init", { cwd: targetDir, stdio: "ignore" });
+        bs.stop("Beads initialized");
+      } catch {
+        mkdirSync2(beadsDir, { recursive: true });
+        writeFileSync3(join3(beadsDir, "config.yaml"), `# Beads configuration
+version: 1
+`);
+        writeFileSync3(join3(beadsDir, "issues.jsonl"), "");
+        writeFileSync3(join3(beadsDir, "metadata.json"), JSON.stringify({ created: new Date().toISOString() }, null, 2));
+        bs.stop("Beads initialized (manual)");
+      }
+    } else {
+      f2.info(".beads/ already exists");
+    }
+  }
+  le("cd .opencode && bun install", "Next steps");
   $e(import_picocolors7.default.green("Ready to code!"));
 }
 
@@ -3736,7 +3744,7 @@ var cli = cac("ock");
 cli.option("--verbose", "Enable verbose logging");
 cli.option("--quiet", "Suppress all output");
 cli.version(`${packageVersion}`);
-cli.command("init", "Initialize OpenCodeKit in current directory").option("--force", "Reinitialize even if already exists").action(initCommand);
+cli.command("init", "Initialize OpenCodeKit in current directory").option("--force", "Reinitialize even if already exists").option("--beads", "Also initialize .beads/ for multi-agent coordination").action(initCommand);
 cli.command("agent [action]", "Manage agents (list, add, view)").action(async (action) => {
   if (!action) {
     console.log(`

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

@@ -1,5 +1,64 @@
 # OpenCode Global Rules
 
+## Constraint Awareness
+
+OpenCode operates at **Stage 5-6** of AI adoption:
+
+- **Stage 5** (Agentic Verification): Agents run tests and iterate autonomously
+- **Stage 6** (Multi-Agent Orchestration): Parallel workstreams with coordination
+
+**Current constraint**: Planning and specification quality. Implementation capacity is not the bottleneck—how well you specify requirements is.
+
+### Autonomous Duration
+
+The key metric: **How long can an agent work before losing the plot?**
+
+Extend autonomous duration by:
+
+- Binding tighter to intent (clear specs, constraints, invariants)
+- Providing systematic context (AGENTS.md hierarchy, memory files)
+- Verification loops (test → iterate → verify)
+
+### Greenfield vs Legacy
+
+- **Greenfield**: Simple context, fast prototypes, agents work well immediately
+- **Legacy**: Complex context, hidden invariants, "that one place you must not touch"
+
+Codebase complexity is a primary difficulty knob. Context is how you pay it down.
+
+### Context Engineering Principles
+
+**Three constraints on context:**
+
+1. **Blind spots cause hallucinations** - If agent doesn't see specific context, it fills gaps with generic training priors. You only get the behavior you load.
+2. **Everything influences everything** - Noise-to-signal ratio matters. Irrelevant files degrade ALL output quality.
+3. **Window is finite** - Performance degrades BEFORE hitting hard token limits. Curate the smallest, highest-signal slice.
+
+**Practical implications:**
+
+- Prefer `lsp_document_symbols` over reading entire files
+- Read specific line ranges, not whole documents
+- Navigate AGENTS.md hierarchy: root → subsystem → details (progressive disclosure)
+- Prune context aggressively; completed work doesn't need to stay loaded
+
+### Intent Layer Principles
+
+**What belongs in each AGENTS.md (Intent Node):**
+
+- **Purpose & Scope** - What this area does. What it explicitly DOESN'T do.
+- **Entry Points & Contracts** - Main APIs, invariants, "all X goes through Y"
+- **Usage Patterns** - Canonical examples: "To add a rule, follow this pattern..."
+- **Anti-patterns** - Negative examples: "Never call X directly; go through Y"
+- **Dependencies & Downlinks** - What it connects to, pointers to child AGENTS.md
+- **Pitfalls** - Things that repeatedly confused agents/humans
+
+**Key mechanics:**
+
+- **Hierarchical loading** - When a node loads, all ancestors load too (T-shaped view)
+- **Compression, not bloat** - Good nodes compress code; if node is 10k tokens for 20k code, you're adding weight
+- **Least Common Ancestor (LCA)** - Place shared knowledge at shallowest node covering all relevant paths
+- **Downlinks for discovery** - Point to related context without loading everything upfront
+
 ## Priority Hierarchy
 
 1. Security constraints (always first)
@@ -48,6 +107,56 @@ Specify depth when delegating to control tool call budget:
 - **Find work**: Use `bd ready` for unblocked tasks
 - **URLs**: Never generate or guess URLs. Only use URLs from user input, tool results, or verified documentation.
 
+## Interaction Modes
+
+### Sounding Board Mode
+
+Recognize when user wants discussion, not action. Trigger phrases:
+
+- "Let's chat for a second..."
+- "Help me think through this..."
+- "Before we write any code..."
+- "What are the tradeoffs of..."
+- "I'm torn between X and Y..."
+- "Play devil's advocate..."
+
+**Response**: Ask clarifying questions, surface tradeoffs, explore alternatives. Don't jump to implementation.
+
+### Execution Mode (Default)
+
+Take action. Produce output. Iterate based on feedback.
+
+**Key insight**: First output is ~70-80% right. Refinement is expected, not failure.
+
+### Generic + Specific Pattern
+
+For batch operations, combine generic goal with concrete example:
+
+```
+"Refactor all database queries to use parameterized statements.
+
+For example, this: db.execute(f"SELECT * FROM users WHERE id = {user_id}")
+Becomes: db.execute("SELECT * FROM users WHERE id = ?", [user_id])
+
+Find and fix all similar patterns."
+```
+
+The generic sets intent; the example sets format. Agent generalizes from example.
+
+### Inject Uncertainty
+
+When facing design decisions, don't just accept user framing as gospel. Question assumptions:
+
+- If user says "use SQLite for cache" → Ask about tradeoffs vs alternatives
+- If user provides a list → Ask if categories make sense, what's missing
+- If plan seems too simple → Surface edge cases they might not have considered
+
+Trigger uncertainty mode with phrases like:
+
+- "I think this should be... but I'm not sure that's right"
+- "My plan is X, but I'm second-guessing whether..."
+- "What am I missing here?"
+
 ## Universal Standards
 
 ### Communication
@@ -79,35 +188,80 @@ Specify depth when delegating to control tool call budget:
 
 ## Tool Priority
 
-**LSP tools → AST tools → Built-in tools**
+**LSP tools → AST-grep → Built-in tools**
+
+1. **LSP tools** - Semantic code intelligence (10 tools)
+2. `ast-grep` - **Code search/replace** (functions, patterns, imports, hooks)
+3. `grep` - **Text search** (logs, config, non-code files, simple strings)
+4. `glob` - File discovery by name pattern
+5. `read`, `edit`, `write` - File operations
 
-1. `lsp_rename`, `lsp_code_actions`, `lsp_organize_imports` - Semantic refactoring (LSP-based)
-2. `ast-grep` - Semantic code search/replace (AST-based)
-3. `grep`, `glob` - Pattern matching, file discovery
-4. `read`, `edit`, `write` - File operations
+### Choosing the Right Search Tool
+
+Ask yourself: **"Am I looking for code structure or just text?"**
+
+**Use `ast-grep` when you need to find:**
+
+- How a function is called → `pattern="fetchUser($$$)"`
+- Where a hook is used → `pattern="useState($$$)"`
+- Import statements → `pattern="import { $$ } from '$MOD'"`
+- Class definitions → `pattern="class $NAME { $$$ }"`
+- Try-catch blocks → `pattern="try { $$$ } catch ($E) { $$$ }"`
+
+**Use `grep` when you need to find:**
+
+- Error messages in logs → `pattern="FATAL|ERROR"`
+- Config values → `pattern="API_KEY"`
+- TODO comments → `pattern="TODO|FIXME"`
+- Text in markdown/docs → `pattern="deprecated"`
+
+**Use LSP tools when you need to:**
+
+- Understand what a symbol is → `lsp_hover`
+- Jump to where something is defined → `lsp_goto_definition`
+- Find all usages before refactoring → `lsp_find_references`
+- Rename across the entire codebase → `lsp_rename`
 
 **Rule**: Always `read` before `edit` to verify content.
 
-### LSP Tools Usage
+### LSP Tools (10 tools)
 
-Semantic refactoring via Language Server Protocol - smarter than text replacement:
+Semantic code intelligence via Language Server Protocol:
 
-```
-# Rename symbol across entire codebase
-lsp_rename(filePath, line, character, newName)
+**Navigation & Understanding:**
 
-# Get available refactorings at location
-lsp_code_actions(filePath, startLine, startCharacter, endLine, endCharacter)
+- `lsp_hover(filePath, line, character)` - Get type info and docs at cursor
+- `lsp_goto_definition(filePath, line, character)` - Jump to where symbol is defined
+- `lsp_find_references(filePath, line, character)` - Find all usages of a symbol
+- `lsp_document_symbols(filePath)` - Get file outline (classes, functions, etc.)
+- `lsp_workspace_symbols(query, filePath)` - Fuzzy search symbols across workspace
 
-# Clean up imports
-lsp_organize_imports(filePath)
-```
+**Diagnostics:**
+
+- `lsp_diagnostics(filePath, severity?)` - Get errors/warnings from language server
+
+**Refactoring:**
 
-**When to use LSP over manual edit:**
+- `lsp_rename(filePath, line, character, newName)` - Rename symbol across codebase
+- `lsp_code_actions(filePath, startLine, startChar, endLine, endChar)` - Get available refactorings
+- `lsp_code_action_apply(...)` - Apply a specific code action
+- `lsp_organize_imports(filePath)` - Clean up and sort imports
 
-- Renaming functions, variables, classes → `lsp_rename` (updates all references)
-- Cleaning imports after refactoring → `lsp_organize_imports`
-- Exploring refactoring options → `lsp_code_actions`
+**When to use each tool:**
+
+**"What type is this variable?"** → Use `lsp_hover` to see type signature without reading the entire definition file.
+
+**"Where is this function defined?"** → Use `lsp_goto_definition` to jump directly to source instead of grepping.
+
+**"What uses this function?"** → Use `lsp_find_references` before changing anything to see all call sites.
+
+**"What's in this file?"** → Use `lsp_document_symbols` for a quick outline without reading the entire file.
+
+**"Where is UserService defined?"** → Use `lsp_workspace_symbols` to fuzzy search across all files.
+
+**"Are there type errors?"** → Use `lsp_diagnostics` to check before running tests.
+
+**"Rename this function safely"** → Use `lsp_rename` to update all references automatically.
 
 **Caveat**: LSP tools modify files directly. Re-read files before further edits.
 
@@ -216,23 +370,17 @@ memory-search(query: "session", type: "handoffs")
 
 - Task tracking uses Beads (`bd` CLI)
 
-## Active Plugins
-
-Plugins run automatically in the background:
-
-- **enforcer** - OS notification when session idles with incomplete TODOs
-- **compactor** - Warns at 70%, 85%, 95% context usage - prevents rushed work
-- **truncator** - Dynamic output truncation based on context remaining
+## Session Management
 
-**Compactor thresholds**:
+**Philosophy**: Short sessions (<150k tokens) beat long bloated ones. Agents get worse with too much context. Cost is exponential.
 
-- 70% - Gentle reminder, still plenty of room
-- 85% - Consider pruning or summarizing
-- 95% - Critical: prune immediately or start new session
+### Context Thresholds
 
-## Session Management
+The environment monitors context usage and warns at these thresholds:
 
-**Philosophy**: Short sessions (<150k tokens) beat long bloated ones. Agents get worse with too much context. Cost is exponential.
+- **70%** - Consolidate work; consider pruning irrelevant tool outputs
+- **85%** - Summarize findings and consider starting a new session
+- **95%** - Critical: prune context immediately or restart session
 
 ### Session Tools
 
@@ -355,25 +503,6 @@ Call `bd_insights` for graph analysis showing bottlenecks and high-priority keys
 
 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
@@ -381,40 +510,6 @@ bd_done({ id: task.id, msg: "Implemented auth" });
 - **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
-
-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`
-- Implementing feature → `test-driven-development`
-- Before commit/done → `verification-before-completion`
-- Complex multi-step work → `writing-plans` → `executing-plans`
-- Finished implementation → `requesting-code-review`
-- Building UI → `frontend-aesthetics`
-- UI/UX with images → `ui-ux-research` or `visual-analysis`
-- Accessibility audit → `accessibility-audit`
-- Design system audit → `design-system-audit`
-- Mockups to code → `mockup-to-code`
-- Large codebase research → `gemini-large-context`
-
-Skip for simple questions, quick edits, or conversations.
-
-### How It Works
-
-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
 
 - No sudo

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

@@ -329,8 +329,8 @@ fi
 
 ---
 
-**OpenCodeKit v0.9.1**  
+**OpenCodeKit v0.9.2**  
 **Architecture:** Two-Layer (Memory + Beads + Git)  
-**New in v0.9.1:** Memory & Compaction plugin merge, session.start auto-load hook  
+**New in v0.9.2:** 6 new LSP tools, `ock init --beads` flag, improved tool guidance  
 **Package:** `npx opencodekit` to scaffold new projects  
 **Last Updated:** January 2, 2026

package/dist/template/.opencode/agent/build.md

@@ -43,35 +43,14 @@ Primary orchestrator. Execute-first. Autonomous task completion until resolved.
 - Use `file:line_number` format for code references
 - No emojis unless explicitly requested
 - Keep responses concise
+- First output is ~70-80% right; refinement is expected, not failure
 
-## Tool Priority
+## Interaction Awareness
 
-1. **LSP tools** for semantic refactoring (rename, code actions, organize imports)
-2. **AST-Grep** for semantic code search/replace
-3. **Built-in tools** for pattern matching (grep, glob, read)
-4. **Bash** for running tests, builds, commands
+**Sounding Board triggers**: "Let's chat", "Help me think through", "Before we code", "What are the tradeoffs"
+→ Ask clarifying questions, explore alternatives. Don't jump to implementation.
 
-### LSP Tools
-
-Use LSP tools for safe, semantic refactoring. Use `lsp_rename` to rename functions, variables, or classes across the entire codebase - it updates all references automatically. Use `lsp_organize_imports` after making changes to clean up unused imports and sort the remaining ones. Use `lsp_code_actions` to explore available refactoring options at a specific location.
-
-**Caveat**: LSP tools modify files directly. Re-read before further edits.
-
-### AST-Grep
-
-Semantic code search/replace - smarter than regex:
-
-```
-# Search patterns
-ast-grep pattern="console.log($$$)"                    # Find all console.log
-ast-grep pattern="async function $NAME($$$) { $$$ }"   # Find async functions
-ast-grep pattern="const [$S, $SET] = useState($$$)"    # Find React hooks
-
-# Replace (dry run first)
-ast-grep pattern="oldFunc($$$)" rewrite="newFunc($$$)" dryRun=true
-```
-
-**Pattern syntax**: `$NAME` = single node, `$$$` = zero or more nodes
+**Execution mode** (default): Take action, produce output, iterate on feedback.
 
 ## Anti-Hallucination
 
@@ -79,6 +58,17 @@ ast-grep pattern="oldFunc($$$)" rewrite="newFunc($$$)" dryRun=true
 **During work:** Verify against spec constraints; stop if violation detected
 **After work:** Update review.md; close bead with reason
 
+## Verification Loop
+
+You are the implementation half of an implementation+verification pair. After making changes:
+
+1. Run tests, check for regressions
+2. If tests fail, iterate: analyze → fix → retest
+3. Continue loop until tests pass (up to 30-60 min autonomous cycles)
+4. Only then mark task complete
+
+**Goal**: Return tested, working code—not just code that looks right.
+
 ## Task Management
 
 - Use TodoWrite to track subtasks; update every 10-15 minutes

package/dist/template/.opencode/agent/explore.md

@@ -14,18 +14,33 @@ tools:
   todoread: false
   todowrite: false
   ast-grep*: true
+  lsp*: true
 ---
 
 # Explore Agent
 
 File search specialist. Navigate and explore codebases efficiently.
 
+**Context is your constraint.** Your job is to find the smallest, highest-signal slice of code that answers the question. Avoid loading noise; every irrelevant file degrades the caller's output quality.
+
 ## Strengths
 
 - Finding files using glob patterns
 - Searching code with regex patterns
 - Reading and analyzing file contents
 - Semantic code search with AST-Grep
+- Understanding symbol types and definitions with LSP
+
+## Navigation Strategy
+
+**Progressive disclosure**: Start broad, narrow based on findings.
+
+1. Use `lsp_workspace_symbols` or `lsp_document_symbols` to understand structure without reading whole files
+2. Use `lsp_goto_definition` to jump directly to source instead of grepping
+3. Use `lsp_find_references` to map usage before returning
+4. Only `read` the specific lines that matter
+
+**Avoid blind exploration**: Don't grep for generic terms. Use semantic tools first.
 
 ## Guidelines
 
@@ -35,32 +50,10 @@ File search specialist. Navigate and explore codebases efficiently.
 - No emojis in responses
 - **DO NOT** create files or modify system state
 
-## Tool Priority
-
-**Use AST-Grep for semantic search, then fall back to built-in tools.**
-
-### AST-Grep (Semantic Search)
-
-`ast-grep` finds functions, classes, and patterns semantically.
-
-**Pattern syntax:** `$NAME` = single node, `$$$` = zero or more nodes
-
-**Examples:**
-
-- `ast-grep pattern="function $NAME($$$) { $$$ }"` - Find all functions
-- `ast-grep pattern="console.log($$$)"` - Find all console.log calls
-- `ast-grep pattern="const [$S, $SET] = useState($$$)"` - Find React hooks
-
-### Built-in Tools (Pattern Matching)
-
-- `glob` - Find files by pattern (`**/*.ts`)
-- `grep` - Search file contents with regex
-- `read` - Read specific file contents
-
 ## Thoroughness Levels
 
-**Quick**: Single ast-grep or glob. Read 1-3 files. Return immediately.
+**Quick**: Single ast-grep, lsp_workspace_symbols, or glob. Read 1-3 files. Return immediately.
 
-**Medium**: AST-grep + grep verification. Check 2-3 naming conventions. Read 3-5 files.
+**Medium**: AST-grep + LSP verification. Check 2-3 naming conventions. Read 3-5 files. Use `lsp_find_references` to trace usage.
 
-**Very Thorough**: Comprehensive search across multiple terms and locations. Build dependency map. Report with file:line references.
+**Very Thorough**: Comprehensive search across multiple terms and locations. Use `lsp_find_references` to build dependency map. Report with file:line references.

package/dist/template/.opencode/agent/planner.md

@@ -27,6 +27,8 @@ tools:
 
 Break complex tasks into phases, assign agents, coordinate execution.
 
+**At Stage 6, specification quality is THE constraint.** Implementation capacity is not the bottleneck—how well you define requirements, edge cases, and acceptance criteria determines success.
+
 ## Strengths
 
 - Decomposing complex tasks into phases
@@ -41,6 +43,18 @@ Break complex tasks into phases, assign agents, coordinate execution.
 - Use `task` tool to delegate execution
 - No emojis in responses
 - Keep coordinating until all phases complete
+- Question user assumptions; surface tradeoffs before committing to approach
+
+## Inject Uncertainty
+
+Don't accept user framing as gospel. Actively question:
+
+- If user says "use X for Y" → Ask about tradeoffs vs alternatives
+- If user provides a list → Ask if categories make sense, what's missing
+- If plan seems too simple → Surface edge cases they might not have considered
+
+Trigger phrases to recognize: "I think... but not sure", "My plan is X, but I'm second-guessing", "What am I missing here?"
+→ Engage in exploration before committing to plan.
 
 ## Planning Pattern
 
@@ -57,15 +71,6 @@ Use **Facts/Guesses/Plans** in bead notes:
 - **Guesses**: Unverified. Include validation strategy and risk.
 - **Plans**: Concrete actions with dependencies.
 
-## Agent Assignments
-
-- Codebase search → @explore
-- Library docs, patterns → @scout
-- Code review, debugging → @review
-- Implementation → @build
-
-**Typical chain**: research → plan → build → review
-
 ## Re-planning Triggers
 
 When blocked 3+ attempts or >24h stall:
@@ -78,3 +83,27 @@ When blocked 3+ attempts or >24h stall:
 ## Output Format
 
 Provide: Phase breakdown, deliverables per phase, validation gates, agent assignments.
+
+## Specification Quality Checklist
+
+Before delegating to @build:
+
+- [ ] Edge cases identified and documented
+- [ ] Acceptance criteria are testable
+- [ ] Constraints and invariants explicit
+- [ ] Dependencies mapped
+- [ ] "Never do X" rules surfaced
+
+Poorly defined specs waste agent cycles. Your planning quality is the ceiling.
+
+## Intent Layer Planning
+
+When planning new subsystems or major refactors, include AGENTS.md creation:
+
+1. **Define scope boundaries** - What this area owns, what it explicitly doesn't
+2. **Document contracts** - Entry points, invariants, "all X goes through Y"
+3. **Capture anti-patterns early** - "Never do X" rules before they become bugs
+4. **Plan downlinks** - How this connects to existing AGENTS.md hierarchy
+5. **Place at LCA** - Shared knowledge goes at shallowest node covering all paths
+
+A good Intent Node compresses understanding; if you need 10k tokens to describe 10k tokens of code, you're adding weight, not value.