maestro-flow-one 0.2.0 → 0.2.1

package/maestro-flow/commands/lifecycle/learn.md

@@ -0,0 +1,140 @@
+---
+name: maestro-learn
+description: Route learning intent to learn-* commands
+argument-hint: "\"intent text\" [-y] [--dry-run] [--chain <name>]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+<purpose>
+Route learning requests to the optimal learn command or multi-step chain. Supports direct chain selection via `--chain` or intent-based routing via keyword matching.
+
+Executes commands sequentially via Skill() with session tracking.
+</purpose>
+
+<context>
+$ARGUMENTS — user learning intent text, or flags.
+
+**Flags:**
+- `-y` / `--yes` — Auto mode: skip confirmation
+- `--dry-run` — Show planned chain without executing
+- `--chain <name>` — Force a specific chain (bypass intent detection)
+
+**Available learn commands:**
+| Command | Purpose |
+|---------|---------|
+| `learn-follow` | Guided reading with forcing questions, pattern extraction |
+| `learn-investigate` | Hypothesis-driven question investigation |
+| `learn-decompose` | 4-dimension parallel pattern extraction |
+| `learn-second-opinion` | Multi-perspective review/challenge/consult |
+| `learn-retro` | Unified retrospective (git metrics + decision evaluation) |
+
+**Available chains:**
+| Chain | Steps | Use when |
+|-------|-------|----------|
+| `follow` | learn-follow | Read/understand code or docs |
+| `investigate` | learn-investigate | Answer a "how/why" question |
+| `decompose` | learn-decompose | Catalog patterns in a module |
+| `second-opinion` | learn-second-opinion | Get review/challenge on code |
+| `retro` | learn-retro --lens all | Full retrospective (git + decisions) |
+| `deep-understand` | follow → decompose → second-opinion | Thorough module analysis |
+| `pattern-catalog` | decompose --save-spec --save-wiki → second-opinion --mode review | Full pattern extraction + review |
+
+**Storage:**
+- `.workflow/learning/.maestro-learn/{session_id}/status.json` — Session tracking
+- All learn command outputs go to `.workflow/learning/`
+</context>
+
+<execution>
+
+### Step 1: Parse & Route
+
+Parse flags (`-y`, `--dry-run`, `--chain`). Extract intent text.
+
+**If `--chain` specified:** validate against known chains, jump to Step 2.
+
+**Intent routing table** (match first token or keywords):
+
+| Keywords | Route |
+|----------|-------|
+| File path (contains `/` or `\`) | `follow` |
+| Wiki ID (`type-slug` pattern) | `follow` |
+| read, follow, walk through, understand, 阅读, 跟读 | `follow` |
+| why, how, what if, investigate, 为什么, 怎么 | `investigate` |
+| pattern, decompose, catalog, 分解, 模式 | `decompose` |
+| opinion, review, challenge, consult, 评审, 挑战 | `second-opinion` |
+| retro, git, commit, decision, 回顾 | `retro` |
+| thorough, deep, 全面, 深入 | `deep-understand` |
+
+**If no match:** present menu via AskUserQuestion:
+```
+What would you like to do?
+1. Read through code/docs → follow
+2. Investigate a question → investigate
+3. Find patterns in code → decompose
+4. Get a second opinion → second-opinion
+5. Retrospective → retro
+```
+
+Max 1 clarification round. If still unclear: error.
+
+### Step 2: Resolve Target & Build Args
+
+- File path → pass directly
+- Wiki ID → pass directly
+- Topic string → pass as quoted argument
+- Extract any flags (--depth, --days, --lens, --mode, --scope, etc.)
+
+**Chain → command mapping:**
+```
+follow          → Skill("learn-follow", "{target} {flags}")
+investigate     → Skill("learn-investigate", "\"{target}\" {flags}")
+decompose       → Skill("learn-decompose", "{target} {flags}")
+second-opinion  → Skill("learn-second-opinion", "{target} {flags}")
+retro           → Skill("learn-retro", "{flags}")
+deep-understand → [learn-follow --depth deep, learn-decompose --save-spec, learn-second-opinion --mode challenge]
+pattern-catalog → [learn-decompose --save-spec --save-wiki, learn-second-opinion --mode review]
+```
+
+### Step 3: Confirm & Execute
+
+**If `--dry-run`:** display chain plan and exit.
+
+**If not `-y`:** show plan, ask for confirmation.
+
+**Execute:**
+1. Create session dir: `.workflow/learning/.maestro-learn/learn-{timestamp}/`
+2. Write `status.json` with chain steps
+3. Execute each step via `Skill()`:
+   - On success: mark completed, continue
+   - On failure (interactive): ask retry/skip/abort
+   - On failure (auto): skip and continue
+4. Display session summary with artifact list and next-step suggestion
+
+</execution>
+
+<error_codes>
+| Code | Severity | Description | Recovery |
+|------|----------|-------------|----------|
+| E001 | error | No intent provided | Provide a learning goal or use --chain |
+| E002 | error | Cannot determine intent after clarification | Rephrase or use --chain directly |
+| E003 | error | Chain step failed + user chose abort | Partial progress saved in status.json |
+| E005 | error | Invalid --chain name | Show valid chains |
+| W001 | warning | Intent ambiguous between commands | Present options |
+| W002 | warning | Chain step completed with warnings | Log and continue |
+</error_codes>
+
+<success_criteria>
+- [ ] Intent routed to correct chain (or --chain validated)
+- [ ] Target resolved and arguments assembled
+- [ ] Session directory created with status.json
+- [ ] All chain steps executed via Skill()
+- [ ] Error handling: retry/skip/abort per step
+- [ ] Session summary displayed with next-step routing
+- [ ] No files modified outside `.workflow/learning/`
+</success_criteria>

package/maestro-flow/commands/lifecycle/link-coordinate.md

@@ -0,0 +1,71 @@
+---
+name: maestro-link-coordinate
+description: Execute command chain nodes step by step
+argument-hint: "\"intent text\" [--list] [-c [sessionId]] [--chain <name>] [--tool <tool>] [-y]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+---
+<purpose>
+Step-mode workflow coordinator using `maestro coordinate` CLI subcommands (start/next/status).
+Walks chain graphs node by node — each command node executed via `maestro delegate` internally.
+Decision/gate/eval nodes auto-resolve between steps. Session persisted for resume.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/maestro-link-coordinate.md
+</required_reading>
+
+<context>
+$ARGUMENTS — user intent text, or flags.
+
+**Flags:**
+- `--list` — List all available chain graphs
+- `-c` / `--continue [sessionId]` — Resume step_paused session via `coordinate next`
+- `--chain <name>` — Force a specific chain graph
+- `--tool <tool>` — CLI tool override (default: claude)
+- `-y` / `--yes` — Auto mode
+
+**CLI endpoints used:**
+- `maestro coordinate list` — enumerate chains
+- `maestro coordinate start "intent" --chain X` — begin step-mode session
+- `maestro coordinate next [sessionId]` — advance one step
+- `maestro coordinate status [sessionId]` — query state
+- `maestro coordinate run "intent"` — autonomous full run
+- `maestro coordinate watch <sessionId> [--follow]` — read-only event tail (separate from driver loop)
+- `maestro coordinate report` — agent-invoked command-node result writer (authoritative result channel)
+
+**Internal walker capabilities (invisible to driver loop):**
+- Prompt assembly owned by the walker (main flow) for both command and decision nodes
+- Decision nodes auto-resolve via `strategy: 'expr'` (fast path) with LLM decider fallback when expr has no match and no default edge, or explicit `strategy: 'llm'`
+- Walker events published to a file/SQLite broker for `watch` observers
+- LLM decision in step mode is synchronous — avoid tight per-step deadlines
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/maestro-link-coordinate.md' completely.
+</execution>
+
+<error_codes>
+| Code | Severity | Description | Recovery |
+|------|----------|-------------|----------|
+| E001 | error | No intent and no --list/--chain | Suggest --list |
+| E002 | error | Chain graph not found | Show list output |
+| E003 | error | Step execution failed | Check status, retry next |
+| E004 | error | Resume session not found | List sessions |
+| E005 | error | CLI endpoint unavailable | Check maestro installation |
+</error_codes>
+
+<success_criteria>
+- [ ] Chain graph loaded via `maestro coordinate start`
+- [ ] Each step executed via `maestro coordinate next` loop
+- [ ] JSON output parsed for session tracking
+- [ ] Decision nodes auto-resolved between steps
+- [ ] Session persisted and resumable via `-c`
+- [ ] Completion summary displayed
+</success_criteria>

package/maestro-flow/commands/lifecycle/merge.md

@@ -0,0 +1,61 @@
+---
+name: maestro-merge
+description: Merge milestone worktree branch back to main
+argument-hint: "-m <milestone-number> [--force] [--dry-run] [--no-cleanup] [--continue]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+<purpose>
+Merge a completed milestone worktree branch back into the main branch, sync scratch artifacts, and reconcile the artifact registry. Uses a two-phase approach: git merge first (source code), artifact sync second (only after git succeeds). This prevents partial state corruption when merge conflicts occur.
+
+Includes registry health check, pre-merge rebase (pull main into worktree to minimize conflicts), and atomic state reconciliation (merge artifact entries, don't overwrite).
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/merge.md
+</required_reading>
+
+<context>
+$ARGUMENTS -- milestone number and optional flags.
+
+Flags (`-m`, `--force`, `--dry-run`, `--no-cleanup`, `--continue`), merge sequence, artifact sync detail, and conflict handling are defined in workflow `merge.md`.
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/merge.md' completely.
+
+**Next-step routing on completion:**
+- View dashboard → Skill({ skill: "manage-status" })
+- Audit milestone → Skill({ skill: "maestro-milestone-audit" })
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | Running inside a worktree | Run from main worktree |
+| E002 | error | No worktree registry found | Nothing to merge |
+| E003 | error | --continue but no merge state | Start fresh merge |
+| E004 | error | No milestone number provided | Provide `-m <N>` |
+| W001 | warning | Stale registry entries found | Auto-cleaned |
+| W002 | warning | Incomplete artifacts (without --force) | Confirm or use --force |
+| W003 | warning | Conflict pulling main into worktree | Resolve in worktree first |
+</error_codes>
+
+<success_criteria>
+- [ ] Registry health check passed (stale entries cleaned)
+- [ ] Pre-merge rebase successful (worktree has latest main)
+- [ ] Git merge completed without conflicts (or conflicts resolved via --continue)
+- [ ] All scratch artifacts synced to main `.workflow/scratch/`
+- [ ] `state.json.artifacts[]` reconciled (worktree entries merged into main)
+- [ ] Milestone `"forked"` flag removed in `state.json.milestones[]`
+- [ ] `roadmap.md` completed phases marked
+- [ ] Worktree removed and branch deleted (unless --no-cleanup)
+- [ ] `worktrees.json` registry updated (entry removed)
+</success_criteria>

package/maestro-flow/commands/lifecycle/overlay.md

@@ -0,0 +1,178 @@
+---
+name: maestro-overlay
+description: Create or edit command overlays from natural language
+argument-hint: "<intent>"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+  - AskUserQuestion
+---
+<purpose>
+Turn a user's natural-language instruction into a command overlay — a JSON patch file that augments one or more `.claude/commands/*.md` files non-invasively. Overlays live at `~/.maestro/overlays/` and are auto-applied by every `maestro install` run, so injected steps survive reinstalls. Use this skill when the user says things like "always run CLI verification after `/maestro-execute`", "require reading doc X before `/maestro-plan`", or "add a `ccw cli` quality check at the end of every quality-review".
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/overlays.md
+@~/.maestro/cli-tools.json
+</required_reading>
+
+<context>
+**Overlay model** — an overlay is a JSON file with a `name`, one or more `targets` (command names without `.md`), and a list of `patches`. Each patch targets an XML section (`execution`, `required_reading`, `context`, `success_criteria`, etc.), a mode (`append`, `prepend`, `replace`, `new-section`), and `content`. On apply, the patcher wraps the content in hashed HTML-comment markers so re-apply is idempotent and removal is surgical.
+
+**Where overlays live**
+- User overlays: `~/.maestro/overlays/*.json` — created by this skill
+- Shared docs: `~/.maestro/overlays/docs/*.md` — referenced via `@~/.maestro/overlays/docs/*.md` inside patch content
+- Shipped examples: `~/.maestro/overlays/_shipped/` — read-only, do not edit
+
+**Management** — listing and removing overlays is handled by `maestro overlay list` (ink TUI with interactive delete). This skill focuses solely on creation.
+
+**Available sections** (for `section:` in patches): `purpose`, `required_reading`, `deferred_reading`, `context`, `execution`, `error_codes`, `success_criteria`.
+</context>
+
+<execution>
+### 1. Parse user intent
+
+Treat the argument as natural-language intent. If unclear, ask up to 2 questions with AskUserQuestion: (a) which command(s) to target, (b) where in the command flow the injection should happen.
+
+### 2. Identify targets, injection points, and visualize
+
+For each likely target command, read the pristine source from `$PKG_ROOT/.claude/commands/<name>.md` (preferred — untouched by overlays) or fall back to `~/.claude/commands/<name>.md`. Inspect the XML sections and pick the right one:
+
+- **New step after execution** → `section: execution`, `mode: append`
+- **Required reading** → `section: required_reading`, `mode: append`
+- **Preconditions / gating** → `section: context`, `mode: append`
+- **Output quality gate** → `section: success_criteria`, `mode: append`
+
+If the user wants a whole new section, use `mode: new-section` with `afterSection: execution` (or whichever anchor makes sense).
+
+**Injection point preview** — after selecting section + mode, render the target command's section map showing existing overlays and the new injection point:
+
+```
+=== maestro-execute.md (1 overlay exists) ===
+
+  <purpose>
+  <required_reading>
+  <context>
+  <execution>
+     ├─ [existing] cli-verify #1  "CLI Verification step"
+     >>> NEW: append here (your overlay)
+  <success_criteria>
+```
+
+Use AskUserQuestion to confirm:
+- **"Confirm"** — proceed with this injection point
+- **"Pick different section"** — re-select section/mode
+- **"Cancel"** — abort
+
+### 2.5. Skill chain configuration
+
+After confirming the injection point, ask whether this overlay should chain to another skill upon completion. This enables the overlay's injected content to hand off to a skill via AskUserQuestion at runtime — similar to how `/maestro` chains commands via `Skill({ skill: "...", args: "..." })`.
+
+Use AskUserQuestion:
+- **"No chain"** — standard overlay, no skill handoff
+- **"Chain to skill"** → ask for the target skill name (e.g., `quality-review`, `maestro-verify`, `quality-test`)
+- **"Chain with alternatives"** → ask for primary skill + 1-2 alternative skills
+
+If chain is selected, record the skill name(s) for use in Step 3.
+
+### 3. Draft the overlay JSON
+
+Build a slug from the user's intent (kebab-case, lowercase). Write to `~/.maestro/overlays/<slug>.json`:
+
+```json
+{
+  "name": "<slug>",
+  "description": "<short summary of what and why>",
+  "targets": ["maestro-execute"],
+  "priority": 50,
+  "enabled": true,
+  "patches": [
+    {
+      "section": "execution",
+      "mode": "append",
+      "content": "## CLI Verification (overlay)\n\nAfter execution, run:\n```\nccw cli -p \"PURPOSE: ...\" --mode analysis --rule analysis-review-code-quality\n```"
+    }
+  ]
+}
+```
+
+**Content guidelines**
+- Lead the injected block with a heading that includes `(overlay)` so readers see it's machine-injected
+- Keep content concise — overlays should add a step, not rewrite the command
+- `@~/.maestro/...` references are encouraged for pointing at docs
+- Escape `\n` in JSON strings; use a HEREDOC via Bash if content is long
+
+**Skill chain content** — if a chain was configured in Step 2.5, append a Skill Handoff block at the end of the patch `content`. The handoff uses AskUserQuestion so the user controls whether to proceed:
+
+```markdown
+---
+
+**Skill Handoff** (overlay)
+
+After the above step completes, use AskUserQuestion:
+- "Proceed to /quality-review" — Hand off to quality review
+- "Skip" — Continue with current command flow
+- "Alternative: /maestro-verify" — Run verification instead
+
+On user selection:
+- Proceed → Skill({ skill: "quality-review", args: "{phase}" })
+- Alternative → Skill({ skill: "maestro-verify", args: "{phase}" })
+- Skip → continue normally
+```
+
+Handoff rules:
+- Always include a **"Skip"** option — the user can always decline the chain
+- Use `Skill({ skill: "<name>", args: "..." })` syntax consistent with maestro.md chainMap
+- Mark handoff heading with `(overlay)` tag
+- Support runtime variable placeholders: `{phase}`, `{description}`, `{session_id}`
+- Keep handoff block under 10 lines of markdown
+
+### 4. Install via `maestro overlay add`
+
+Run:
+
+```bash
+maestro overlay add ~/.maestro/overlays/<slug>.json
+```
+
+This validates the overlay, copies it into place (idempotent), and applies it across all known install scopes. On validation failure, fix the JSON and re-run.
+
+### 5. Report
+
+Show the user:
+- Path of the saved overlay JSON
+- Which targets were patched and which were skipped (missing/disabled)
+- Skill chain info (if configured)
+- A reminder that `maestro install` will auto-reapply on every run
+- How to remove: `maestro overlay remove <slug>`
+
+**Report format**
+
+```
+=== OVERLAY INSTALLED ===
+Name:    <slug>
+Path:    ~/.maestro/overlays/<slug>.json
+Targets: maestro-execute (applied), maestro-plan (skipped: missing)
+Chain:   quality-review (via AskUserQuestion) | none
+Scopes:  [global]
+
+Re-apply: maestro overlay apply
+Remove:   maestro overlay remove <slug>
+Inspect:  maestro overlay list
+```
+
+After the report, remind the user they can run `maestro overlay list` for the interactive TUI showing section maps and overlay management.
+</execution>
+
+<success_criteria>
+- [ ] Overlay JSON written to `~/.maestro/overlays/<slug>.json` and validates
+- [ ] `maestro overlay add` exited successfully and applied to at least one scope
+- [ ] Target command file(s) contain `<!-- maestro-overlay:<slug>#N hash=... -->` markers
+- [ ] Re-running `maestro overlay apply` produces no file changes (idempotent)
+- [ ] User shown the report with target list and removal instructions
+- [ ] Injection point preview shown (with existing overlays + `>>>` marker) and confirmed before drafting
+- [ ] If chain configured, `content` includes Skill Handoff block with AskUserQuestion + Skip option + `Skill()` calls
+</success_criteria>

package/maestro-flow/commands/lifecycle/plan.md

@@ -0,0 +1,154 @@
+---
+name: maestro-plan
+description: Plan phase execution with exploration and verification
+argument-hint: "[phase] [--collab] [--spec SPEC-xxx] [-y] [--gaps] [--dir <path>] [--revise [instructions]] [--check <plan-dir>]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+<purpose>
+Create, revise, or verify an execution plan through a 5-stage pipeline: Exploration, Clarification, Planning, Plan Checking, and Confirmation. Produces plan.json with waves, task definitions, and user-confirmed execution strategy.
+
+Supports three modes:
+- **Create** (default): Build plan from analysis context or phase requirements
+- **Revise** (`--revise`): Incrementally modify existing plan — edit tasks, adjust waves, add/remove tasks
+- **Check** (`--check`): Standalone plan verification — run plan-checker against existing plan
+
+All plan output goes to `.workflow/scratch/{YYYYMMDD}-plan-[P{N}-|M{N}-]{slug}/`. Date-first ordering enables chronological sorting. Scope prefix in directory name (`P{N}` for phase, `M{N}` for milestone, omit for adhoc/standalone) enables fallback identification. Registers PLN artifact in state.json. Performs collision detection against other plans in same milestone.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/plan.md
+</required_reading>
+
+<deferred_reading>
+- [plan.json](~/.maestro/templates/plan.json) — read when generating plan output
+- [task.json](~/.maestro/templates/task.json) — read when generating task files
+- [state.json](~/.maestro/templates/state.json) — read when registering artifact
+</deferred_reading>
+
+<context>
+$ARGUMENTS — phase number, or no args for milestone-wide planning, with optional flags.
+
+Scope routing, base flags (`--collab`, `--spec`, `-y`, `--gaps`, `--dir`), output directory format, and artifact registration are defined in workflow plan.md.
+
+**Command-level flags** (extensions beyond workflow base):
+- `--revise [instructions]` -- See workflow plan.md § Revise Mode
+- `--check <plan-dir>` -- See workflow plan.md § Check Mode
+
+**Upstream context:**
+- Reads `context.md` from prior analyze artifact (auto-discovered from state.json or via --dir)
+- Reads `conclusions.json` if available (implementation_scope seeds task generation)
+</context>
+
+<execution>
+### Pre-flight: team conflict check
+
+Before starting the plan pipeline, run:
+```
+Bash("maestro collab preflight --phase <phase-number>")
+```
+If exit code is 1, present warnings and ask whether to proceed.
+
+Follow '~/.maestro/workflows/plan.md' completely.
+
+### Codebase Docs Loading (P1 addition)
+
+During P1 Context Collection, after loading context files, load codebase documentation if available:
+
+```
+IF exists(.workflow/codebase/doc-index.json):
+  codebase_ctx = Read(.workflow/codebase/ARCHITECTURE.md) + Read(.workflow/codebase/FEATURES.md)
+  Pass codebase_ctx to planner agent as structural context
+ELSE:
+  display "W004: Codebase docs unavailable, continuing with code exploration only"
+```
+
+### Wiki Knowledge Search (P1 addition)
+
+During P1 Context Collection, after loading context files and before parallel exploration (step 5), search the wiki for prior knowledge related to the phase:
+
+```
+phase_keywords = extract key terms from goal/title (2-5 terms)
+wiki_result = Bash("maestro wiki search ${phase_keywords} --json 2>/dev/null")
+
+IF wiki_result exit code != 0 OR empty:
+  display "W003: Wiki search unavailable, continuing without prior knowledge"
+ELSE:
+  entries = JSON.parse(wiki_result).entries (limit to first 10)
+  wiki_context = structured block for downstream stages
+```
+
+### Issue Linkback (--gaps mode)
+
+After plan generation and checking, if `--gaps` mode was used, link TASK files back to issues bidirectionally:
+
+```
+For each created TASK-{NNN}.json that has issue_id:
+  Update corresponding issue in .workflow/issues/issues.jsonl:
+    task_refs: append TASK-{NNN} to array
+    task_plan_dir: relative path to .task/ directory
+    status: "planned"
+    updated_at: now()
+  Append history entry: { action: "planned", at: <ISO>, by: "maestro-plan", summary: "Linked to TASK-{NNN}" }
+```
+
+This ensures issue → TASK traceability. The `task_refs[]` and `task_plan_dir` fields on the issue allow the dashboard to resolve and display associated TASK details.
+
+**Report format on completion:**
+
+```
+=== PLAN READY ===
+Phase: {phase_name}
+Tasks: {task_count} tasks in {wave_count} waves
+Check: {checker_status} (iteration {check_count}/{max_checks})
+Collision: {collision_status}
+
+Plan: scratch/{YYYYMMDD}-plan-P{N}-{slug}/plan.json
+Tasks: scratch/{YYYYMMDD}-plan-P{N}-{slug}/.task/TASK-*.json
+
+Next steps:
+  /maestro-execute              -- Execute the plan
+  /maestro-execute --dir {dir}  -- Execute specific plan
+  /maestro-plan {phase}         -- Re-plan with modifications
+```
+
+### Mode: Revise / Check
+
+Follow workflow plan.md § "Revise Mode" and § "Check Mode" respectively. These modes bypass the standard P1-P5 create pipeline.
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | No args and no roadmap (cannot determine scope) | Provide phase number or topic, or create roadmap |
+| E003 | error | --gaps requires prior verification/issues to exist | Run maestro-verify first |
+| E004 | error | No plan found to revise (--revise without target) | Use --dir to specify plan, or create plan first |
+| E005 | error | Plan directory not found (--check) | Check path, use --dir |
+| W001 | warning | Exploration agent returned incomplete results | Retry exploration or proceed with available context |
+| W002 | warning | Plan-checker found minor issues, continuing | Review plan-checker feedback, adjust plan if needed |
+| W003 | warning | Wiki search unavailable or returned no results | Continue without prior knowledge context |
+| W004 | warning | Collision detected with existing plan | Review colliding files, confirm or adjust scope |
+</error_codes>
+
+<success_criteria>
+- [ ] plan.json written to scratch directory with summary, approach, task_ids, waves (with phase labels)
+- [ ] .task/TASK-*.json files created for each task
+- [ ] Every task has `read_first[]` with at least the file being modified + source of truth files
+- [ ] Every task has `convergence.criteria[]` with grep-verifiable conditions (no subjective language)
+- [ ] Every task `action` and `implementation` contain concrete values (no "align X with Y")
+- [ ] Plan confidence scored in P4 with 5-dimension factor model
+- [ ] Plan readiness gate checked before P4.5 collision detection
+- [ ] Pressure pass completed on highest-complexity task
+- [ ] plan.json includes confidence section (overall, dimensions, pressure_pass)
+- [ ] Collision detection executed against same-milestone plans (non-blocking)
+- [ ] Plan-checker passed (or minor issues acknowledged)
+- [ ] User confirmation captured (execute/modify/cancel) with confidence displayed
+- [ ] Artifact registered in state.json with correct scope/milestone/phase/depends_on
+</success_criteria>