octomux 1.0.25 → 1.0.28

package/README.md

@@ -4,172 +4,183 @@
 
 # octomux
 
-**Your local command center for autonomous Claude Code agents.**
+> **Coding got faster. Managing agents didn't.**
 
-Pull tasks from Jira, GitHub, or any source your agent can read. Agents work in isolated worktrees. Get notified when they need you. PRs auto-link and tasks auto-close on merge. Review diffs with built-in lazygit. Survives restarts.
+A local web app to **dispatch, watch, and review** parallel **Claude Code** and **Cursor** agents from one place. Kanban for fleet status. One inbox for every "allow this tool?" prompt. In-app diff review with **Ship**. No cloud. MIT.
 
-![octomux dashboard](assets/screenshots/dashboard-hero.png)
-
-## The Loop
-
-```
-1. INTAKE      Pull Jira tickets or GitHub issues — auto-creates tasks with prompts
-2. EXECUTE     Each task gets its own worktree, branch, and Claude Code agents
-3. SUPERVISE   Live terminals + notifications when agents finish or need attention
-4. REVIEW      Built-in lazygit & lazyvim — check diffs without leaving octomux
-5. MERGE       PRs auto-detected and linked — tasks auto-close when PRs merge
-6. RESUME      Close your laptop. Reboot. Everything picks back up automatically.
+```bash
+npm install -g octomux && octomux init && cd your-repo && octomux start
 ```
 
-> The orchestrator agent can drive this entire loop autonomously — or you can control each step from the CLI and dashboard.
-
-## Features
+Open [http://localhost:7777](http://localhost:7777) — describe a task in the composer, pick **Claude Code** or **Cursor**, and watch agents work in place.
 
-### Orchestrator: agents managing agents
+## From prompt to merged PR
 
-A dedicated Claude Code instance that orchestrates your entire workflow. Create tasks, monitor status, add agents, create PRs — all via slash commands (`/create-task`, `/list-tasks`, `/status`, `/create-pr`).
+Three phases, one window:
 
-Wire it to Jira MCP, GitHub CLI, or any source — the orchestrator pulls context and creates properly named tasks with initial prompts. Ships with Claude Code skills (`create-task`, `create-pr`, `create-commit`) that any agent can use directly.
+- **01 — Dispatch.** Type a task. Pick Claude Code or Cursor. Hit go. The composer takes plain English, Jira links, or GitHub issue URLs. Drop a second agent on the same branch with one click.
+- **02 — Watch.** See every agent work, live. Each task streams its own view — files the agent is editing, the diff as it grows, terminal output as it runs. When an agent needs permission, the prompt lands in your inbox so you don't have to babysit every pane.
+- **03 — Review & Ship.** Diff review in the same window. File tree, per-file reviewed state, inline comments. Hit **Ship** and the PR auto-links to the task — closes itself when the PR merges.
 
-![orchestrator](assets/screenshots/orchestrator.png)
+Code never leaves your laptop. No telemetry, no cloud sync. Crash, reboot, close the lid — `octomux start` restores every task, branch, and session.
 
-### Intake from anywhere
+## Screenshots
 
-- Any Claude Code agent can create tasks via `octomux create-task`
-- Works with Jira MCP, GitHub CLI, or anything your agent can read
-- Auto-generates task names and initial prompts from ticket context
-- Draft tasks: create in draft mode, edit title/prompt/branch before starting
+|                                                                               |                                                          |
+| ----------------------------------------------------------------------------- | -------------------------------------------------------- |
+| **Home inbox + composer** — permission prompts, recent activity, dispatch bar | ![Home](assets/screenshots/dashboard-hero.png)           |
+| **Command center** — kanban from backlog → done                               | ![Command center](assets/screenshots/command-center.png) |
+| **Settings** — default harness, Cursor model & `--force`                      | ![Settings](assets/screenshots/settings-harnesses.png)   |
+| **Task cockpit** — agent tabs, live Claude session, Ship, Done                | ![Task detail](assets/screenshots/task-detail.png)       |
+| **Diff review** — file tree, reviewed state, inline comments                  | ![Diff](assets/screenshots/diff-review.png)              |
 
-### Isolated execution
+## Features
 
-- Each task gets its own git worktree, branch, and tmux session
-- Multiple agents per task, working in parallel
-- Custom base branches supported (work from `develop`, not just `main`)
-- Your main working tree stays untouched
+- **Sessions inbox** — every permission prompt and question lands in one place; reply once, agents keep going. Tab title shows `(N) octomux` when something needs you.
+- **Command center** — kanban for backlog → done; drag status, archive, workflow from draft → ship.
+- **In-app diff review** — compare to `main`, mark files reviewed, queue inline comments, open lazygit in-editor.
+- **Dual harnesses** — run **Claude Code** (`claude`) or **Cursor** (`cursor-agent`) per task; mix agents on one task via **Add agent**.
+- **Worktrees keep agents off each other** — each task gets its own git worktree and `agents/<task-id>` branch; five agents can edit `auth.ts` at the same time without conflicts on your main tree.
+- **Live task view** — see every agent work in real time: files edited, diff growing, terminal output streaming via xterm.js. Attach the same session from the CLI if you prefer.
+- **Agents that dispatch agents** — `/create-task`, `/list-tasks`, `/send-agent-message` skills work inside any Claude Code window; recursive dispatch from inside an agent.
+- **Integrations** — Jira wiring plus orchestrator skills for GitHub / auto-review intake.
+- **CLI ↔ dashboard parity** — `octomux create-task`, `send-message`, `resume-task` — same tasks the UI shows.
+- **Reboot-proof** — WAL SQLite + preserved worktrees across restarts.
+- **Local-only** — no telemetry, no cloud sync, no analytics. Your `.env` stays on the host.
 
-### Smart supervision
+## Patterns
 
-- Live terminals in the dashboard via xterm.js
-- Color-coded agent activity: green (active), gray (idle), amber (waiting for input)
-- Notifications when agents finish, stop unexpectedly, or hit permission prompts
-- Browser tab shows `(N) octomux` + red favicon dot when tasks need attention
-- Toast notifications with "View" button — one click to the relevant agent
-- Send messages to running agents via `octomux send-message`
-- Smart status: tasks needing attention surface before idle tasks
+Three workflows octomux makes one-click:
 
-![task detail](assets/screenshots/task-detail.png)
+### Verifier — two agents, two opinions
 
-### Built-in review
+Claude wrote it. Drop Cursor on the same branch for a second pass. Same-model self-review is just self-confirmation — a different model reads the diff without inheriting the first agent's assumptions. Catches missing nonce checks, off-by-one TTLs, and the kind of mistakes that pass type-checking but break in prod.
 
-- Lazygit and lazyvim integrated — review diffs inside octomux
-- Open ad-hoc shell terminals in any task's worktree from the dashboard
-- No context switching to a separate terminal or IDE
-- Clean branches ready to push and PR when you're satisfied
+> Finish a task with Claude → hit **Add agent** → pick Cursor → reviews land as inline comments → you arbitrate, Ship.
 
-![lazygit review](assets/screenshots/lazygit-review.png)
+### Sweep — five PRs by lunch
 
-### Auto PR detection + merge
+Paste a Jira filter or GitHub issue list into the composer. Each ticket gets its own worktree, branch, and agent. Mix Claude and Cursor across the batch so the model best at each kind of task ends up on it. Come back from standup to a kanban of ready-to-review PRs.
 
-- Background poller detects PRs on task branches via `gh pr list`
-- PR URLs auto-linked in task cards — visible from the dashboard
-- Tasks auto-close when their PRs are merged
-- Zero manual status updates from task creation to merged code
+### Operator — one prompt becomes an epic
 
-### Survives restarts
+Give an agent the orchestrator skills. It plans the work, breaks down the spec, and dispatches subtasks — each one gets its own worktree, mergeable independently. Inside a Claude Code window, the agent itself becomes the user of octomux. You supervise from the dashboard.
 
-- Full state persistence in SQLite across reboots
-- On next `octomux start`, running tasks are recovered and agent sessions resume
-- Close your laptop, come back tomorrow, run `octomux start`, keep going
+> `/create-task`, `/list-tasks`, `/send-agent-message` skills inside any Claude Code window. Recursive dispatch.
 
-### Safety: graduated trust
+## Quick start
 
-Each task worktree gets a permission config (`.claude/settings.local.json`) with three tiers:
+```bash
+brew install tmux git
+npm install -g @anthropic-ai/claude-code    # and/or Cursor CLI
+npm install -g octomux
+octomux init
+cd your-project
+octomux start
+```
 
-- **Denied**: `git push --force`, `rm -rf`, `git reset --hard` — always blocked
-- **Allowed**: read-only ops, safe writes, non-force `git push` — auto-approved
-- **Prompted**: everything else requires explicit user permission
+```bash
+octomux create-task -t "Add OAuth login" -r .
+octomux create-task -t "Spike with Cursor" -r . --harness cursor
+```
 
-Permission prompts surface in the dashboard with tool name and input details. Agents can't destroy things without asking first.
+Step-by-step setup, Jira, and orchestrator skills: [ONBOARDING.md](./ONBOARDING.md)
 
-## Quick Start
+## How it works
 
-```bash
-npm install -g octomux
-cd your-project
-octomux start                                    # opens dashboard at localhost:7777
-octomux create-task -t "Add auth flow" -r .      # create a task from the CLI
+```
+DISPATCH → BRANCH → CODE → INBOX → REVIEW → MERGE
 ```
 
-Open [http://localhost:7777](http://localhost:7777) to watch agents work, or keep using the CLI.
-
-## CLI Commands
-
-| Command                                           | Description                                     |
-| ------------------------------------------------- | ----------------------------------------------- |
-| `octomux start`                                   | Launch the local web dashboard                  |
-| `octomux create-task`                             | Create a new task                               |
-| `octomux list-tasks`                              | List all tasks                                  |
-| `octomux get-task <id>`                           | Get task details                                |
-| `octomux close-task <id>`                         | Stop agents and preserve the worktree           |
-| `octomux delete-task <id>`                        | Fully clean up task state, branch, and worktree |
-| `octomux resume-task <id>`                        | Resume a previously closed task                 |
-| `octomux add-agent <task-id>`                     | Add an agent to an existing task                |
-| `octomux send-message <task-id> <agent-id> "msg"` | Send a message to an agent                      |
-
-## Why octomux?
-
-|                      | Without octomux          | With octomux                             |
-| -------------------- | ------------------------ | ---------------------------------------- |
-| Git isolation        | Manual worktrees         | Automatic per task                       |
-| Agent visibility     | Tab-switching            | Single dashboard with activity dots      |
-| Backlog intake       | Copy-paste prompts       | Agent-driven from Jira/GH                |
-| PR tracking          | Manual                   | Auto-detected and linked                 |
-| Task completion      | Manual status updates    | Auto-closes on PR merge                  |
-| After a reboot       | Start over               | Auto-resumes                             |
-| Reviewing changes    | Switch to terminal + git | Built-in lazygit                         |
-| Agent safety         | Hope for the best        | Graduated trust: denied/allowed/prompted |
-| Lifecycle management | None                     | draft → running → closed                 |
-
-## How It Works
+| Phase        | What happens                                                                |
+| ------------ | --------------------------------------------------------------------------- |
+| **Dispatch** | Composer, CLI, orchestrator skills, or Jira/GitHub drafts                   |
+| **Branch**   | Automatic git worktree + `agents/<task-id>` branch                          |
+| **Code**     | tmux session per task; harness launches `claude` or `cursor-agent`          |
+| **Inbox**    | Every permission prompt or question collects in one place                   |
+| **Review**   | Diff tab, lazygit terminal, mark files reviewed, **Ship** / **Done**        |
+| **Merge**    | PR poller links branches; tasks close when their PRs merge                  |
+| _Recovery_   | DB + worktrees survive reboot — `octomux start` picks up where you left off |
+
+## CLI
+
+| Command                              | Description                                              |
+| ------------------------------------ | -------------------------------------------------------- |
+| `octomux start`                      | Dashboard at `:7777`                                     |
+| `octomux init`                       | Defaults wizard (Jira, base branch, harness prefs)       |
+| `octomux create-task`                | New task (`--harness cursor` optional)                   |
+| `octomux list-tasks` / `get-task`    | Inspect tasks                                            |
+| `octomux close-task` / `delete-task` | Stop or fully remove                                     |
+| `octomux resume-task`                | Resume a closed task                                     |
+| `octomux add-agent`                  | Another agent window                                     |
+| `octomux send-message`               | Message a running agent — course-correct without restart |
+
+## Architecture
 
 ```mermaid
-graph LR
-    O[Orchestrator Agent] -->|octomux create-task| B[Dashboard / API]
-    A[Any Claude Code Agent] -->|octomux create-task| B
-    B --> C[Git Worktree]
-    B --> D[tmux Session]
-    B --> H[(SQLite DB)]
-    D --> E[Claude Code Agent]
-    E -->|done / permission| F[Notifications]
-    C --> G[lazygit Review]
-    H -->|recovery on restart| D
-    E -->|git push| P[GitHub PR]
-    P -->|poller detects merge| B
+flowchart LR
+  subgraph intake [Intake]
+    C[Composer]
+    CLI[CLI / skills]
+  end
+  subgraph core [octomux]
+    API[API + SQLite]
+    IN[Inbox]
+    BC[Command center]
+  end
+  subgraph run [Per task]
+    WT[Worktree]
+    TM[tmux]
+    H[Claude or Cursor]
+  end
+  C --> API
+  CLI --> API
+  API --> WT
+  API --> TM
+  TM --> H
+  H -->|hooks| API
+  API --> IN
+  API --> BC
+  WT --> DIFF[Diff review]
+  H --> GH[GitHub PR]
+  GH -->|poller| API
 ```
 
 ## Requirements
 
-- **macOS** (ARM64 or x64)
-- **Node.js 20+**
-- **tmux**: `brew install tmux`
-- **git**: `brew install git`
-- **Claude Code CLI**: `npm install -g @anthropic-ai/claude-code`
-
-> Xcode Command Line Tools (`xcode-select --install`) may be needed if native dependencies (`better-sqlite3`, `node-pty`) require local compilation.
+- macOS (ARM64 or x64), Node.js 20+
+- `tmux`, `git`
+- At least one harness: **Claude Code** (`claude`) and/or **Cursor CLI** (`cursor-agent`)
+- Recommended: `lazygit`, `neovim`
 
 ## Configuration
 
-| Option          | Description                     | Default                 |
-| --------------- | ------------------------------- | ----------------------- |
-| `--port <port>` | Port for the dashboard          | `7777`                  |
-| `--no-open`     | Do not auto-open the browser    | —                       |
-| `PORT`          | Alternative to `--port`         | `7777`                  |
-| `OCTOMUX_URL`   | Server URL used by CLI commands | `http://localhost:7777` |
+| Variable / flag           | Purpose                          |
+| ------------------------- | -------------------------------- |
+| `OCTOMUX_PORT` / `--port` | Dashboard port (default `7777`)  |
+| `OCTOMUX_URL`             | CLI → API base URL               |
+| `OCTOMUX_DB_PATH`         | Override task DB path            |
+| `OCTOMUX_GITHUB_LOGIN`    | Reviewer-request polling account |
+
+## FAQ
+
+**What's the difference between octomux and just running tmux + Claude Code?**
+octomux adds the kanban, the inbox, and diff review on top. tmux is just plumbing underneath.
+
+**Does it work with Cursor?**
+Yes. Pick Claude Code or Cursor per task. Mix them on the same task with **Add agent**.
+
+**What happens if two agents touch the same file?**
+They can't — each task runs in its own git worktree on its own branch. Five agents can edit `auth.ts` at the same time without conflicts on your main tree.
+
+**What if my laptop reboots or crashes?**
+Run `octomux start`. Tasks, branches, terminals, and review state all come back.
+
+**How do I track what each agent is costing me?**
+Each agent's tmux session has its own session log; Claude Code and Cursor both emit token usage there. A first-class cost view in the dashboard is on the roadmap.
 
 ## Links
 
-- GitHub: [github.com/ShreyPaharia/octomux](https://github.com/ShreyPaharia/octomux)
-- npm: [npmjs.com/package/octomux](https://www.npmjs.com/package/octomux)
-- Landing page: [octomux.com](https://octomux.com)
+- [GitHub](https://github.com/ShreyPaharia/octomux) · [npm](https://www.npmjs.com/package/octomux) · [octomux.dev](https://octomux.dev)
 
-Contributions welcome — [open an issue](https://github.com/ShreyPaharia/octomux/issues) or submit a PR.
+Issues and PRs welcome.

package/agents/orchestrator.md

@@ -0,0 +1,216 @@
+---
+name: orchestrator
+description: Coordinates autonomous Claude Code agents via the octomux CLI. Creates tasks, monitors progress, manages agent lifecycles.
+model: opus
+---
+
+# Octomux Orchestrator
+
+You coordinate autonomous Claude Code agents through the octomux CLI. You create tasks, monitor progress, and manage agent lifecycles — you never interact with agent terminals directly.
+
+## Environment
+
+The octomux CLI is at `node cli/dist/index.js`. All commands support `--json` for machine-readable output. The octomux server runs at localhost:7777.
+
+## Greeting
+
+On the first message of a conversation, greet the user briefly:
+
+---
+
+**Octomux Orchestrator** — ready to coordinate your agents.
+
+I can help you:
+
+- **Create tasks** — dispatch Claude Code agents to isolated worktrees
+- **Monitor progress** — check status, agents, and errors
+- **Manage lifecycle** — close, resume, delete tasks; add or stop agents
+
+Try something like:
+
+- "Create a task to fix the login bug in the auth service"
+- "Show me all running tasks"
+- "What's the status of task abc123?"
+
+---
+
+Then handle whatever the user asked.
+
+## Commands
+
+### Task Operations
+
+```bash
+# Create and start a task
+node cli/dist/index.js create-task \
+  --title "Fix status badge colors" \
+  --description "Status badges are all gray, should be color-coded" \
+  --repo-path "/path/to/repo" \
+  --initial-prompt "In src/components/TaskCard.tsx, change the status badge..." \
+  --base-branch main
+
+# Create as draft (does not start agents)
+node cli/dist/index.js create-task \
+  --title "..." --description "..." --repo-path "..." --draft
+
+# List all tasks
+node cli/dist/index.js list-tasks
+
+# Filter by status
+node cli/dist/index.js list-tasks --status running
+
+# Get task details (includes agents, status, errors)
+node cli/dist/index.js get-task <id>
+
+# Close a task (preserves worktree + branch for later resume)
+node cli/dist/index.js close-task <id>
+
+# Resume a closed or errored task
+node cli/dist/index.js resume-task <id>
+
+# Delete a task (irreversible — removes worktree, branch, tmux session)
+node cli/dist/index.js delete-task <id>
+```
+
+### Agent Operations
+
+```bash
+# Add another agent to a running task
+node cli/dist/index.js add-agent <task-id> --prompt "Focus on writing tests for..."
+
+# Stop a specific agent
+node cli/dist/index.js stop-agent <agent-id> --task <task-id>
+
+# Send a message to a running agent
+node cli/dist/index.js send-message "Your message here" --task <task-id> --agent <agent-id>
+```
+
+### Utility Commands
+
+```bash
+# List recently used repositories
+node cli/dist/index.js recent-repos
+
+# Get default branch for a repo
+node cli/dist/index.js default-branch --repo-path /path/to/repo
+```
+
+## Decision Logic
+
+When the user gives you work, follow this sequence:
+
+1. **Understand the request.** Break it into discrete, parallelizable tasks. Each task should have one clear objective.
+2. **Check existing tasks.** Run `list-tasks` to avoid duplicating work already in progress.
+3. **Create tasks.** Use `create-task` with a clear title, description, and initial prompt.
+4. **Monitor progress.** Run `get-task <id>` to check status and watch for errors.
+5. **Handle failures.** If a task errors, check the error field. Use `resume-task` if the issue is transient.
+6. **Scale up.** If a running task needs parallel work, use `add-agent` with a focused prompt.
+7. **Close completed tasks.** When agents finish, run `close-task <id>`.
+
+### When to use each command
+
+| Situation                          | Command                                       |
+| ---------------------------------- | --------------------------------------------- |
+| User wants work done               | `create-task`                                 |
+| User asks about progress           | `get-task <id>` or `list-tasks`               |
+| Task finished successfully         | `close-task <id>`                             |
+| Task errored, issue is transient   | `resume-task <id>`                            |
+| Task is done permanently           | `delete-task <id>` after confirming with user |
+| Task needs more parallel workers   | `add-agent <task-id> --prompt "..."`          |
+| Agent is stuck or no longer needed | `stop-agent <agent-id> --task <task-id>`      |
+| Need to nudge an agent             | `send-message "..." --task <id> --agent <id>` |
+
+### Before creating a task
+
+- **Base branch is required.** If the user has not specified a base branch, ask: "What base branch should this task branch off from?" before proceeding. Never silently assume `main`.
+
+### What requires user confirmation
+
+- **Deleting tasks** — irreversible, removes worktree and branch
+- **Stopping agents** — kills a running Claude instance
+- **Resuming errored tasks** — user should understand what went wrong first
+
+### What you do autonomously
+
+- Creating tasks from user requests
+- Checking task status
+- Listing tasks
+- Adding agents to running tasks when the user asks for parallel work
+
+## Planning
+
+For non-trivial tasks, spawn a planner subagent before creating the task. The planner
+reads the codebase and produces a structured implementation plan that becomes the
+agent's initial prompt.
+
+### When to plan first
+
+- Jira tickets with multiple acceptance criteria
+- Changes likely spanning 3+ files
+- Unfamiliar repos or areas of the codebase
+- Any request where you'd need to explore the code to write a good prompt
+
+### When to skip planning
+
+- Single-file fixes with clear instructions from the user
+- PR reviews (the reviewer agent handles its own scoping)
+- Tasks where the user already provided a detailed initial prompt
+
+### How to plan
+
+1. Spawn a planner subagent:
+   ```
+   Agent(subagent_type="planner", prompt="Plan implementation for: <description>.
+   Target repo: <repo_path>. Read CLAUDE.md and explore the codebase.")
+   ```
+2. The planner returns a structured plan with files, steps, and test strategy.
+3. Use the plan output as the `--initial-prompt` for `create-task`.
+
+The planner's output is designed to be used directly as an initial prompt —
+don't rewrite it, just pass it through.
+
+## Writing Effective Prompts
+
+The `--initial-prompt` is sent to the first Claude agent after it starts. Good prompts are:
+
+- **Specific** — reference exact files, functions, or behaviors
+- **Self-contained** — include all context the agent needs; don't assume it knows the task title
+- **Action-oriented** — tell the agent what to do, not just what's wrong
+- **Scoped** — one clear objective per task; split large work into multiple tasks
+
+For complex tasks, use the planner subagent instead of writing prompts manually.
+The planner explores the codebase and produces prompts that reference specific
+files, functions, and line ranges — more precise than manual prompt writing.
+
+## Task Lifecycle
+
+```
+draft → setting_up → running → closed → (resume) → running
+                                error → (resume) → running
+```
+
+| Status       | Meaning                                                              |
+| ------------ | -------------------------------------------------------------------- |
+| `draft`      | Created but not started. No worktree or agents yet.                  |
+| `setting_up` | Worktree being created, tmux session initializing, Claude launching. |
+| `running`    | Agent(s) actively working.                                           |
+| `closed`     | Stopped gracefully. Worktree and branch preserved — can be resumed.  |
+| `error`      | Something went wrong. Check `error` field. Can be resumed.           |
+
+**Close vs Delete:** Close preserves work (worktree, branch) so the task can resume later. Delete is irreversible — removes the worktree, branch, and tmux session entirely.
+
+## How Tasks Work
+
+Each task gets:
+
+1. A git worktree at `<repo>/.worktrees/<slug>` — an isolated copy of the repo
+2. A git branch `agents/<slug>` (or a custom branch name)
+3. A tmux session `octomux-agent-<id>` with one window per agent
+4. Each agent window runs `claude --session-id <uuid>` for session tracking
+
+## Constraints
+
+- Tasks are isolated in git worktrees — agents won't interfere with each other or the main repo.
+- Each agent is a full Claude Code instance with terminal access, file editing, and tool use.
+- Coordinate at the task level. Do not interact with agent tmux sessions directly.
+- The dashboard at localhost:7777 shows live terminal output for all agents.

package/agents/planner.md

@@ -0,0 +1,99 @@
+---
+name: planner
+description: Reads a codebase and produces a concrete implementation plan from a feature request, bug report, or Jira ticket.
+tools: Read, Grep, Glob, Bash, WebFetch
+model: opus
+---
+
+# Planner Agent
+
+You are a senior software architect. Given a feature request, bug report,
+or Jira ticket, produce a concrete implementation plan for a coding agent.
+
+## Process
+
+1. **Understand the request.** Read the full description carefully.
+2. **Read CLAUDE.md** at the repo root for conventions, architecture, and gotchas.
+3. **Explore the codebase.** Use Grep/Glob to find the files, functions, types, and
+   tests involved. Be specific — name files and line ranges.
+4. **Ask all clarifying questions at once.** Before planning, gather everything you
+   need. Present your questions in a single batch — do not ask one at a time.
+   For each question, suggest what you think the answer should be based on your
+   codebase exploration, and offer 2-3 concrete options where applicable.
+5. **Wait for answers.** Do not proceed to planning until all questions are answered.
+6. **Produce a plan** based on the answers, in the format below.
+
+## When to Ask Questions
+
+Always ask when:
+
+- The request is ambiguous or could be interpreted multiple ways
+- There are multiple valid implementation approaches (present options with trade-offs)
+- You're unsure about scope (what's in vs out)
+- The request conflicts with existing patterns in the codebase
+- You need to know about external constraints (deadlines, dependencies, rollout strategy)
+
+Skip questions when:
+
+- The request is completely unambiguous
+- There's only one reasonable implementation approach
+- CLAUDE.md already answers your concerns
+
+## Question Format
+
+Present all questions together like this:
+
+```
+Before I plan this, a few questions:
+
+1. **Scope:** The ticket mentions X and Y. Should the agent handle both,
+   or just X? I'd suggest just X for now because [reason].
+
+2. **Approach:** I see two ways to implement this:
+   - **Option A:** [description] — simpler, but [tradeoff]
+   - **Option B:** [description] — more flexible, but [tradeoff]
+   I'd recommend Option A because [reason].
+
+3. **Testing:** The existing tests in `file.test.ts` use [pattern].
+   Should the agent follow that, or is there a preferred approach?
+```
+
+## Output Format
+
+Your output is a structured plan that will be used directly as a coding agent's
+initial prompt. Write it as instructions, not as a document to be read.
+
+### Structure
+
+```
+## Summary
+One paragraph: what this change does and why.
+
+## Files to Modify
+- `path/to/file.ts` — what to change and why (reference specific functions/types)
+
+## Files to Create (if any)
+- `path/to/new-file.ts` — purpose
+
+## Implementation Steps
+1. First, do X in `file.ts:functionName` because...
+2. Then modify Y in `other.ts` to...
+3. Add tests in `file.test.ts` covering...
+
+## Test Strategy
+- What to test and which test files to modify/create
+- Edge cases to cover
+
+## Risks
+- Anything that could go wrong or needs careful handling
+```
+
+## Constraints
+
+- **Do not write code.** Plan only.
+- Be specific: name files, functions, types, and line ranges.
+- The plan must be self-contained — a coding agent should execute it
+  with no other context besides the repo itself.
+- Ask all questions upfront in one batch, not one at a time.
+- For each question, suggest your recommended answer and explain why.
+- Keep the plan to ~40 lines. Longer plans get ignored.