pi-maestro-flow 0.2.0

package/skills/maestro-composer/SKILL.md

@@ -0,0 +1,192 @@
+---
+name: maestro-composer
+description: "Compose reusable workflow templates from natural language Arguments: <workflow-description> [--resume] [--edit <template-path>]"
+allowed-tools: Read Write Edit Bash Glob Grep Agent AskUserQuestion Skill
+---
+
+<purpose>
+Interactive workflow template composer: natural language to DAG template.
+Three modes: new design (default), resume (`--resume`), edit (`--edit <path>`).
+</purpose>
+
+<deferred_reading>
+- [node-catalog](~/.maestro/templates/workflows/specs/node-catalog.md) — read at Phase 2 (Resolve)
+- [template-schema](~/.maestro/templates/workflows/specs/template-schema.md) — read at Phase 5 (Persist)
+</deferred_reading>
+
+<context>
+$ARGUMENTS — natural language description, or flags.
+
+**Flags**: `--resume` (resume in-progress design), `--edit <path>` (edit existing template)
+
+**Constants**:
+- Template dir: `~/.maestro/templates/workflows/`
+- Template index: `~/.maestro/templates/workflows/index.json`
+- Design drafts: `.workflow/templates/design-drafts/`
+- Template ID: `wft-<slug>-<YYYYMMDD>`, Node ID: `N-<seq>`, Checkpoint: `CP-<seq>`
+- Max nodes: 20
+
+### Pre-load specs
+1. **Architecture specs**: Run `maestro load --type spec --category arch` to load architecture constraints. Use as context for node resolution — ensures workflow design respects documented patterns.
+2. **Coding specs**: Run `maestro load --type spec --category coding` to load coding conventions. Informs executor argument defaults and context injection.
+3. Optional — proceed without if unavailable.
+
+**Output boundary**: ALL file writes MUST target `~/.maestro/templates/workflows/` (template JSON + index.json) and `.workflow/templates/design-drafts/` (intermediate drafts) only. NEVER modify source code or `.claude/commands/` files.
+</context>
+
+<invariants>
+1. **Max 20 nodes** — workflow templates MUST NOT exceed 20 nodes; larger workflows MUST be split into sub-workflows
+2. **Acyclic DAG** — generated template MUST be a directed acyclic graph; cycles MUST be detected and rejected before persistence
+3. **No orphan nodes** — every node MUST be reachable from at least one edge; unreachable nodes MUST be flagged
+4. **Confirmation before write** — template JSON MUST be shown to user via AskUserQuestion before writing to `~/.maestro/templates/workflows/`; cancellation saves draft only
+5. **Draft preservation** — abandoning at any confirmation gate MUST save current progress to design-drafts directory; NEVER discard user's partial work
+6. **Deferred reading only** — node-catalog and template-schema MUST be read at their designated phases (P2, P5), NEVER loaded eagerly at startup
+</invariants>
+
+<state_machine>
+
+<states>
+S_ROUTE        — 入口路由（new/resume/edit）               PERSIST: —
+S_PARSE        — 语义意图提取                               PERSIST: intent.json
+S_CONFIRM_1    — 确认解析结果                               PERSIST: —
+S_RESOLVE      — 映射步骤到 executor 节点                   PERSIST: nodes.json
+S_CONFIRM_2    — 确认节点映射                               PERSIST: —
+S_ENRICH       — 注入 checkpoint + 构建 DAG                 PERSIST: dag.json
+S_CONFIRM_3    — 可视化 pipeline + 用户审批                  PERSIST: —
+S_PERSIST      — 组装 JSON + 保存模板                       PERSIST: template file + index
+</states>
+
+<transitions>
+
+S_ROUTE:
+  → S_PARSE       WHEN: no flags (new design)
+  → S_RESOLVE     WHEN: --resume                           DO: load draft, skip to last incomplete phase
+  → S_CONFIRM_3   WHEN: --edit <path>                      DO: load template, show pipeline, ask edits
+
+S_PARSE:
+  → S_CONFIRM_1   DO: A_PARSE_INTENT
+
+S_CONFIRM_1:
+  → S_RESOLVE     WHEN: user confirms "Looks good"
+  → S_PARSE       WHEN: user selects "Edit steps" or "Add step"
+  → END           WHEN: user cancels                       DO: save draft
+
+S_RESOLVE:
+  → S_CONFIRM_2   DO: A_RESOLVE_NODES (read deferred: node-catalog)
+
+S_CONFIRM_2:
+  → S_ENRICH      WHEN: user confirms "Continue"
+  → S_RESOLVE     WHEN: user changes executor or node type
+  → S_PARSE       WHEN: user selects "Back to intent"
+  → END           WHEN: user cancels                       DO: save draft
+
+S_ENRICH:
+  → S_CONFIRM_3   DO: A_BUILD_DAG
+
+S_CONFIRM_3:
+  → S_PERSIST     WHEN: user confirms "Confirm & Save"
+  → S_CONFIRM_3   WHEN: user edits/adds/removes node       DO: apply change, re-render
+  → S_ENRICH      WHEN: user selects "Re-run checkpoints"
+  → END           WHEN: user cancels                       DO: save draft
+
+S_PERSIST:
+  → END           DO: A_SAVE_TEMPLATE (read deferred: template-schema)
+
+</transitions>
+
+<actions>
+
+### A_PARSE_INTENT
+
+1. Parse description (if empty: AskUserQuestion for workflow description)
+2. Extract candidate nodes via semantic signals:
+
+| Signal | Type hint |
+|--------|-----------|
+| "analyze", "review", "explore" | analysis (cli) |
+| "plan", "design", "spec" | planning (skill) |
+| "implement", "build", "code", "fix" | execution (skill) |
+| "test", "validate", "verify" | testing (skill) |
+| "then", "next", "after" | sequential edge |
+| "parallel", "simultaneously" | parallel edge |
+
+3. Extract variables (inputs that vary per run)
+4. Classify: task type + complexity (simple 1-3 / medium 4-7 / complex 8+)
+5. Write `intent.json` to design drafts dir
+6. Display: parsed steps, variables, task type, complexity
+
+### A_RESOLVE_NODES
+
+Read deferred `node-catalog.md` (fallback to built-in mapping):
+
+| Type hint | Default executor |
+|-----------|-----------------|
+| planning | `maestro-plan` |
+| execution | `maestro-execute` |
+| testing | `quality-test` |
+| review | `quality-review` |
+| brainstorm | `maestro-brainstorm` |
+| analysis | `maestro delegate --to <tool> --mode analysis` |
+| verify | `maestro-execute` |
+| refactor | `quality-refactor` |
+| debug | `quality-debug` |
+
+Build `args_template` with variable placeholders. Context injection: planning-after-analysis → `--context {prev_output_path}`, execution-after-planning → `--resume-session {prev_session_id}`.
+Write `nodes.json`. Display resolved node list.
+
+### A_BUILD_DAG
+
+1. Build sequential edges (fan-out/fan-in for parallel groups)
+2. Auto-inject checkpoints:
+
+| Rule | Condition |
+|------|-----------|
+| Artifact boundary | Source outputs plan/spec/analysis/review |
+| Execution gate | Target contains `execute` |
+| Long-running | Target is maestro-plan, maestro-blueprint |
+| Post-testing | Source contains `test` or `auto-test` |
+| User-defined | type_hint == checkpoint |
+
+3. Finalize context_schema from {variable} references
+4. Validate: no cycles, no orphans, all reachable
+5. Write `dag.json`
+6. Display ASCII pipeline visualization
+
+### A_SAVE_TEMPLATE
+
+Read deferred `template-schema.md` (fallback to built-in structure).
+Assemble template JSON: template_id, name, nodes, edges, checkpoints, context_schema, execution_mode.
+**Confirmation gate**: AskUserQuestion showing template summary (ID, node count, variables) before writing.
+- User confirms → write to `~/.maestro/templates/workflows/<slug>.json` and update index.json.
+- User cancels → save draft, do not write template or index.
+Display: path, ID, node count, variables, execute/edit commands. Clean up draft dir.
+
+</actions>
+
+</state_machine>
+
+<error_codes>
+| Code | Condition | Recovery |
+|------|-----------|----------|
+| E002 | 0 steps extracted | Ask user to rephrase with action verbs |
+| E003 | Node count > 20 | Suggest splitting into sub-workflows |
+| E005 | DAG cycle detected | Show cycle, ask user to resolve |
+| E006 | Edit template not found (--edit) | Show available templates |
+| W001 | Ambiguous step→executor mapping | Show candidates, let user choose |
+</error_codes>
+
+<success_criteria>
+- [ ] Each phase has interactive confirmation gate
+- [ ] Template JSON written with nodes, edges, checkpoints, context_schema
+- [ ] Index updated; deferred specs loaded only when phase needs them
+</success_criteria>
+
+<completion>
+### Next-step routing
+
+| Condition | Suggestion |
+|-----------|-----------|
+| Template saved | `/maestro-player <template-id>` |
+| Template needs edits | `maestro composer --edit <template-path>` |
+| Design abandoned mid-flow | `maestro composer --resume` to continue from last draft |
+</completion>

package/skills/maestro-execute/SKILL.md

@@ -0,0 +1,193 @@
+---
+name: maestro-execute
+description: "Use when a confirmed plan is ready for implementation Arguments: [milestone] [--auto-commit] [--method agent|cli|auto] [--executor <tool>] [--dir <path>] [-y]"
+allowed-tools: Read Write Edit Bash Glob Grep Agent AskUserQuestion
+---
+
+<purpose>
+Execute confirmed plan tasks via wave-based parallel dispatch.
+Consumes plan from maestro-plan; registers EXC artifact in state.json.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/execute.md
+</required_reading>
+
+<deferred_reading>
+- [task.json](~/.maestro/templates/task.json) — read when reading task definitions
+- [state.json](~/.maestro/templates/state.json) — read when registering artifact
+</deferred_reading>
+
+<context>
+$ARGUMENTS — milestone number, or no args for current milestone, with optional flags.
+
+### Flags
+
+| Flag | Effect | Default |
+|------|--------|---------|
+| `--auto-commit` | Auto-commit after each completed task | false |
+| `--method agent\|cli\|auto` | Execution method: Agent tool, CLI delegate, or auto-select | `auto` |
+| `--executor <tool>` | Explicit executor tool for CLI delegate mode | First enabled in config |
+| `--dir <path>` | Execute a specific plan directory instead of auto-discovery | — |
+| `-y` / `--yes` | Auto mode — skip ALL interactive questions (executor selection, wave progression, blocked prompts) | false |
+
+### Scope routing
+
+| Input | Scope | Resolution |
+|-------|-------|------------|
+| numeric arg | milestone | Resolve plans for the given milestone |
+| `--dir <path>` | explicit | Use specified plan directory |
+| no args + milestone | milestone | Find all pending plans, execute sequentially |
+| no args + no milestone | error E001 | No plan found |
+
+Full resolution logic, output directory format, artifact registration schema, and incremental knowhow extraction are defined in workflow `execute.md`.
+
+### Pre-load context (before task execution)
+
+1. **Codebase docs**: If `.workflow/codebase/doc-index.json` exists, read `ARCHITECTURE.md` for module boundaries. Pass as shared context to executor agents.
+2. **Wiki knowledge**: Run `maestro search "<phase keywords>" --json 2>/dev/null`. If results found, extract top 5 entries as prior knowledge context for agents.
+3. **Coding specs + tools**: Run `maestro load --type spec --category coding` to load coding conventions AND discoverable knowhow tools (tool: true entries). Pass as specs context to all executor agents.
+4. **UI specs (conditional)**: If any task involves frontend/UI work (task scope/description contains keywords like component, page, style, layout, CSS, HTML, frontend; or focus_paths in `src/components/`, `src/pages/`, `src/styles/`, `src/ui/`), also run `maestro load --type spec --category ui` and include in agent context.
+5. All are optional — proceed without if unavailable (log warning).
+
+### Role Knowledge
+`maestro search --category coding` → select relevant → `maestro load --type knowhow --id`
+</context>
+
+<execution>
+### Pre-flight: team conflict check
+
+Before any task execution, run:
+```
+Bash("maestro collab preflight --phase <phase-number>")
+```
+If exit code is 1, present warnings and ask whether to proceed.
+
+Follow '~/.maestro/workflows/execute.md' completely.
+
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Plan Load → Task Execution**
+- REQUIRED: plan.json found and parsed with valid task definitions.
+- REQUIRED: `.task/TASK-*.json` files exist for all tasks in plan.
+- BLOCKED if no pending tasks: error E004.
+
+**GATE 2: Per-Task Execution → Summary**
+- REQUIRED: Each completed task has `.summaries/TASK-{NNN}-summary.md` written with concrete evidence (files changed, tests run, verification results).
+- REQUIRED: `.task/TASK-{NNN}.json` status updated to completed|blocked.
+- BLOCKED if missing: summary file absent or task status not updated — halt wave progression until evidence is recorded.
+- Do NOT silently skip failed tasks — mark as blocked with reason.
+
+**GATE 2.5: Wave Failure Handling**
+- IF all tasks in a wave failed: halt wave progression, report E005 with per-task failure reasons. Do NOT proceed to next wave — downstream waves depend on current wave outputs.
+- IF cascading failure (wave N fails → wave N+1 has unmet dependencies): mark all dependent tasks in subsequent waves as `blocked` with reason `"upstream_wave_failed"`. Skip blocked waves and proceed to completion with partial results.
+- `-y` mode: auto-skip blocked waves without prompting, log warning W002.
+- Non `-y` mode: `AskUserQuestion` with options [retry wave / skip and continue / abort execution].
+
+**GATE 3: All Tasks → Completion**
+- REQUIRED: All waves executed in dependency order (or explicitly skipped via Gate 2.5).
+- REQUIRED: EXC artifact registered in state.json.
+- BLOCKED if missing: waves incomplete or EXC artifact not registered — do not report execution complete.
+
+### Evidence Requirement
+
+Task summaries MUST include:
+- Files actually modified (not just planned targets)
+- Convergence criteria verification results (pass/fail with evidence)
+- Any deviations from the plan with rationale
+
+### Post-task Knowledge Inquiry
+
+After each task completion, extract structured fields from the task summary, then check triggers:
+
+**Structured extraction** (from `.summaries/TASK-{NNN}-summary.md`):
+- `deviations[]` — explicit plan deviations (look for "deviated", "changed approach", "instead of", "unlike plan")
+- `design_rationale[]` — explicit design decisions (look for "chose X because", "decided to", "trade-off")
+- `retry_count` — from `.task/TASK-{NNN}.json` status history
+
+| Condition | Ask | Route |
+|-----------|-----|-------|
+| `deviations[]` is non-empty | "Record as arch constraint?" | spec-add arch |
+| `retry_count >= 2` | "Document fix pattern?" | spec-add debug |
+| `design_rationale[]` is non-empty | "Record as knowhow?" | spec-add learning |
+
+On confirm → `Skill("spec-add", "<category> <content> --description \"<summary>\"")`.
+Include `--description` with a one-line summary for search result display.
+
+### Issue Status Sync
+
+On each task completion, if `task.issue_id` exists, sync status back to the issue in `.workflow/issues/issues.jsonl`.
+
+**Confirmation gate**: Before writing to issues.jsonl, show the proposed status change and ask for confirmation — unless `-y` is active, in which case auto-approve.
+
+```
+For each completed/failed TASK with issue_id:
+  Read issue from issues.jsonl by issue_id
+  Collect all task_refs[] statuses for that issue:
+    all task_refs completed → proposed issue.status = "resolved"
+    any task_ref failed    → proposed issue.status = "in_progress"
+  IF NOT auto_mode (-y):
+    AskUserQuestion: "Update issue {issue_id} status to {proposed_status}?" [Yes / Skip]
+    IF Skip → continue to next task without writing
+  Append history entry: { action: "executed", at: <ISO>, by: "maestro-execute", summary: "TASK-{NNN} {status}" }
+  Write updated issue back to issues.jsonl
+```
+
+</execution>
+
+<completion>
+### Standalone report
+
+```
+=== EXECUTION COMPLETE ===
+Plans executed: {plans_count}
+Completed: {completed_count}/{total_count} tasks
+Failed:    {failed_count} tasks
+
+Summaries: {plan_dir}/.summaries/
+Tasks:     {plan_dir}/.task/
+```
+
+### Ralph-invoked completion
+
+End the step by calling the CLI (no text block output):
+```
+maestro ralph complete <idx> --status {STATUS} [--evidence {path}]
+```
+
+Status verdicts:
+- **DONE** — Normal completion
+- **DONE_WITH_CONCERNS** — Completed with caveats; pass `--concerns`
+- **NEEDS_RETRY** — Tooling error / transient issue; ralph will retry
+- **BLOCKED** — External hard blocker; pass `--reason`
+
+### Next-step routing
+
+| Condition | Suggestion |
+|-----------|-----------|
+| All tasks completed successfully | `/quality-review` |
+| Failed tasks exist | `/quality-debug` |
+| View project dashboard | `/manage-status` |
+</completion>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | No pending plans found | Verify plans exist, run maestro-plan first |
+| E002 | error | Plan directory not found | Check --dir path |
+| E003 | error | plan.json not found in directory | Verify plan.json exists, run maestro-plan first |
+| E004 | error | No pending tasks, all tasks already completed | Check task statuses, reset if needed |
+| E005 | error | All tasks in wave failed — wave progression halted | Review per-task failure reasons; retry wave or abort |
+| W001 | warning | Executor completed with partial failures | Check task dependencies, retry failed wave |
+| W002 | warning | Cascading wave failure — downstream waves auto-blocked | Review blocked tasks; re-run after fixing upstream failures |
+</error_codes>
+
+<success_criteria>
+- [ ] All pending plans identified and executed sequentially
+- [ ] Within each plan: waves executed in parallel, waves串行
+- [ ] `.summaries/TASK-{NNN}-summary.md` written for each completed task
+- [ ] `.task/TASK-{NNN}.json` statuses updated (completed|blocked)
+- [ ] EXC artifact registered in state.json for each plan executed
+- [ ] Incremental knowhow extracted to specs/learnings.md
+- [ ] state.json updated with execution progress
+</success_criteria>

package/skills/maestro-fork/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: maestro-fork
+description: "Create or sync milestone worktree for parallel dev Arguments: -m <milestone-number> [--base <branch>] [--sync]"
+allowed-tools: Read Write Edit Bash Glob Grep Agent AskUserQuestion
+---
+
+<purpose>
+Create or sync a milestone-level git worktree for parallel development.
+Supports `--sync` mode to pull latest main changes into an active worktree.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/fork.md
+</required_reading>
+
+<deferred_reading>
+- [worktrees.json](~/.maestro/templates/worktrees.json) — read when updating registry
+- [worktree-scope.json](~/.maestro/templates/worktree-scope.json) — read when writing scope marker
+</deferred_reading>
+
+<context>
+$ARGUMENTS -- milestone number and optional flags.
+
+Modes (`Fork` / `Sync`), flags (`-m`, `--base`, `--sync`), milestone resolution, worktree layout, and artifact scoping are defined in workflow `fork.md`.
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/fork.md' completely.
+
+Fork and sync algorithm steps are defined in workflow `fork.md`.
+
+### Phase Gates (MANDATORY, BLOCKING)
+
+**Fork mode:**
+
+**GATE 1: Validation → Worktree Creation**
+- REQUIRED: Milestone resolved from state.json.milestones[].
+- REQUIRED: No existing active worktree for this milestone (E008).
+- REQUIRED: Not running inside a worktree (E003).
+- BLOCKED if: milestone not found (E006), already forked (E008), or running inside worktree (E003).
+
+**GATE 2: Worktree Creation → Artifact Copy**
+- REQUIRED: Git worktree created with branch (`milestone/{slug}`).
+- REQUIRED: Shared `.workflow/` files copied (project.md, roadmap.md, config.json, specs/).
+- BLOCKED if missing: worktree creation failed or shared files not copied — do not proceed to artifact scoping.
+
+**GATE 3: Artifact Copy → Completion**
+- REQUIRED: AskUserQuestion confirmation before registry writes — show milestone scope, worktree path, and state entries to be written. User must confirm or abort.
+- REQUIRED: `worktree-scope.json` written with milestone scope (after confirmation).
+- REQUIRED: Scoped `state.json` written (only this milestone's artifacts) (after confirmation).
+- REQUIRED: `worktrees.json` registry updated in main worktree (after confirmation).
+- BLOCKED if missing: scope marker, scoped state, or registry update absent — worktree is unusable without these.
+
+**Sync mode:**
+
+**GATE: Sync → Completion**
+- REQUIRED: Git merge main into worktree branch completed.
+- REQUIRED: Shared artifacts re-copied.
+- BLOCKED if: merge has unresolved conflicts or shared artifacts failed to copy.
+
+</execution>
+
+<completion>
+### Next-step routing
+
+| Condition | Suggestion |
+|-----------|-----------|
+| Fork complete | `cd {wt.path} && /maestro-analyze` |
+| Fork + automated | `maestro delegate "run full lifecycle for milestone" --cd {wt.path} --mode write` |
+| Fork + status check | Skill({ skill: "manage-status" }) |
+| Sync complete | Resume work in worktree |
+| Sync conflicts found | Resolve manually, then retry |
+</completion>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | Project not initialized | Run maestro-init first |
+| E002 | error | No roadmap found | Run maestro-roadmap first |
+| E003 | error | Running inside a worktree | Run from main worktree |
+| E004 | error | No milestone number provided | Provide `-m <N>` |
+| E005 | error | No milestones defined in state.json | Run maestro-roadmap first |
+| E006 | error | Milestone number out of range | Check available milestones |
+| E007 | error | No active worktree for milestone (--sync) | Check worktrees.json |
+| E008 | error | Milestone already has active worktree | Merge or cleanup first |
+</error_codes>
+
+<success_criteria>
+Fork mode:
+- [ ] Milestone resolved from state.json.milestones[]
+- [ ] Git worktree created with branch (`milestone/{slug}`)
+- [ ] Shared `.workflow/` files copied (project.md, roadmap.md, config.json, specs/)
+- [ ] Milestone scratch artifacts copied (filtered from artifact registry)
+- [ ] `worktree-scope.json` written with milestone scope
+- [ ] Scoped `state.json` written (only this milestone's artifacts)
+- [ ] `worktrees.json` registry updated in main worktree
+- [ ] Milestone marked as `"forked"` in main `state.json.milestones[]`
+- [ ] Summary displayed with next-step commands
+
+Sync mode:
+- [ ] Git merge main into worktree branch
+- [ ] Shared artifacts re-copied (project.md, roadmap.md, config.json, specs/)
+- [ ] Conflicts reported if any
+</success_criteria>

package/skills/maestro-grill/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: maestro-grill
+description: "Use when stress-testing a plan, idea, or requirement against codebase reality before brainstorming Arguments: <topic|plan> [-y] [-c] [--from <source>] [--depth shallow|standard|deep]"
+allowed-tools: Read Write Edit Bash Glob Grep Agent AskUserQuestion
+---
+
+<purpose>
+Socratic stress-testing of plans/ideas against codebase reality. Produces grill-report.md + terminology.md + context-package.json for downstream brainstorm/analyze/roadmap.
+
+Pipeline position: BEFORE brainstorm (stress-test → then elaborate).
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/grill.md
+</required_reading>
+
+<deferred_reading>
+- [state.json](~/.maestro/templates/state.json) — read when registering artifact
+</deferred_reading>
+
+<context>
+$ARGUMENTS -- topic/plan text for interactive mode, or --from source for upstream input.
+
+**Mode selection:**
+- **Interactive mode** (default): Topic text triggers full Socratic grilling with user Q&A
+- **Auto mode** (`-y`): Code exploration answers questions instead of the user
+- **Resume mode** (`-c` or `--session ID`): Continue from a previous grill session
+
+**Flags:**
+
+| Flag | Effect | Default |
+|------|--------|---------|
+| `-y` / `--yes` | Auto mode — CLI exploration replaces human answers | `false` |
+| `-c` / `--continue` | Resume from last grill session | — |
+| `--session ID` | Resume specific session | — |
+| `--depth shallow\|standard\|deep` | Branch count 3/5/8 | `standard` |
+| `--from <source>` | Load upstream material (`blueprint:ID`, `@file`, or path) | — |
+
+**Output directory**: `.workflow/scratch/{YYYYMMDD}-grill-{slug}/`
+**Produced files**: `grill-report.md`, `terminology.md`, `context-package.json`
+
+### Pre-load
+
+1. **Specs**: `maestro load --type spec --category arch` — load architecture constraints
+2. **Wiki search**: `maestro search "{topic keywords}"` → load relevant entries before grilling
+3. All optional — proceed without if unavailable
+</context>
+
+<interview_protocol>
+Follows @~/.maestro/workflows/interview-mechanics.md standard.
+
+**Interaction mode override**: adversarial Socratic — NOT menu-driven
+**Question style**:
+  - Reference specific code: "The codebase uses `{symbol}` at `{file:line}` — your proposal calls it `{term}`. Which wins?"
+  - Concrete scenarios: "What happens when {action} while {condition}?"
+  - Challenge contradictions: immediately surface conflicts with code evidence or prior answers
+  - Escalating depth: per branch basic → specific → adversarial
+**Branch traversal** (depth-gated, --depth controls count): Scope & Boundaries → Data Model & State → Edge Cases & Failure Modes → Integration & Dependencies → Scale & Performance → Security & Access Control → Observability & Operations → Migration & Rollback
+**Writeback target**: grill-report.md (Q&A append per question) + terminology.md (term crystallization)
+**Additional skip conditions**: none beyond standard (-y, -c)
+**Exit condition**: all depth-selected branches fully walked → finalize report + context-package.json
+</interview_protocol>
+
+<execution>
+Follow '~/.maestro/workflows/grill.md' completely.
+
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Setup → Branch Walking** (Step 1 → Step 2)
+- REQUIRED: Topic parsed and output directory created.
+- REQUIRED: Initial codebase scan completed — at least one code reference identified for grounding.
+- BLOCKED if missing: cannot grill without code reality baseline.
+
+**GATE 2: Branch Walking → Synthesis** (Step 2 → Step 3)
+- REQUIRED: All depth-selected branches walked (shallow=3, standard=5, deep=8).
+- REQUIRED: Each branch has ≥2 Q&A pairs with evidence (code reference or explicit user input).
+- REQUIRED: Every locked decision has evidence — NOT just orchestrator inference.
+- BLOCKED if branches incomplete: continue walking before synthesizing.
+
+**GATE 3: Synthesis → Completion** (Step 3 → Report)
+- REQUIRED: `grill-report.md` written with Branch Log table + all Q&A entries + synthesis section.
+- REQUIRED: `terminology.md` written with ≥5 terms.
+- REQUIRED: `context-package.json` generated.
+- BLOCKED if any artifact missing: produce it before reporting completion.
+
+</execution>
+
+<completion>
+### Standalone report
+
+```
+=== GRILL READY ===
+Topic: {topic}
+Branches walked: {count}/{depth_target}
+Decisions locked: {locked_count}
+Open risks: {risk_count}
+Output: {output_dir}
+Artifact: GRL-{id}
+=== END GRILL ===
+```
+
+### Ralph-invoked completion
+
+End the step by calling the CLI (no text block output):
+```
+maestro ralph complete <idx> --status {STATUS} [--evidence {path}]
+```
+
+Status verdicts:
+- **DONE** — Normal completion
+- **DONE_WITH_CONCERNS** — Completed with caveats; pass `--concerns`
+- **NEEDS_RETRY** — Tooling error / transient issue; ralph will retry
+- **BLOCKED** — External hard blocker; pass `--reason`
+
+### Next-step routing
+
+| Condition | Suggestion |
+|-----------|-----------|
+| Need multi-role elaboration | `Skill({ skill: "maestro-brainstorm", args: "{topic} --from grill:{artifact_id}" })` |
+| Need deep technical analysis | `Skill({ skill: "maestro-analyze", args: "{topic} --from grill:{artifact_id}" })` |
+| Scope is clear, ready for roadmap | `Skill({ skill: "maestro-roadmap", args: "--from grill:{artifact_id}" })` |
+| Need formal spec package | `Skill({ skill: "maestro-blueprint", args: "--from grill:{artifact_id}" })` |
+| More branches to walk | `Skill({ skill: "maestro-grill", args: "{topic} -c" })` |
+</completion>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | No topic/plan and no --from/--continue flag | Prompt user for topic text |
+| E002 | error | --session ID not found | Show available sessions |
+| W001 | warning | Codebase scan failed or returned empty | Continue without code grounding, note limitation |
+| W002 | warning | CLI exploration timeout in auto mode | Skip question, mark as open |
+| W003 | warning | Max branch depth reached without resolution | Force synthesis, offer continuation |
+</error_codes>
+
+<success_criteria>
+- [ ] Interactive mode: all depth-selected branches walked (shallow=3, standard=5, deep=8)
+- [ ] Each branch has >= 2 question-answer pairs with evidence or explicit user input
+- [ ] `grill-report.md` written with Branch Log table, all Q&A entries, synthesis section
+- [ ] `terminology.md` written with >= 5 terms, code references where applicable
+- [ ] Every locked decision has evidence (code reference or explicit user confirmation)
+- [ ] Contradictions between answers and code surfaced and resolved (or logged as risks)
+- [ ] Risk register captures all unresolved tensions
+- [ ] `context-package.json` generated with schema "context-package/1.0"
+- [ ] Artifact registered in state.json (type=grill, id=GRL-xxx)
+- [ ] Session sealed via finish-work (finish-work.md includes AskUserQuestion confirmation before state.json artifact registration and optional spec/knowhow extraction)
+</success_criteria>
+
+<on_complete>
+@~/.maestro/workflows/finish-work.md — SESSION_DIR={output_dir}, SESSION_TYPE=grill, SESSION_ID={artifact_id}, LINKED_MILESTONE=null
+</on_complete>