maestro-flow-one 0.2.24 → 0.2.25

package/maestro-flow/agents/workflow-collab-planner.md

@@ -42,9 +42,10 @@ You are a collaborative planner that works within a pre-allocated task ID range.
   "type": "feature",
   "priority": "medium",
   "effort": "medium",
-  "action": "Implement",
+  "action": "<concrete action with exact values: function signatures, config keys, import paths>",
   "scope": "<module path>",
   "focus_paths": [],
+  "read_first": ["src/module/existing.ts", "src/types/shared.ts"],
   "depends_on": [],
   "parallel_group": null,
   "convergence": {
@@ -116,6 +117,8 @@ You are a collaborative planner that works within a pre-allocated task ID range.
 - Task files must use `convergence.criteria` (array of testable strings), not `done_when`
 - files must use `[{path, action, target, change}]` format, not `["path"]`
 - Each task must have convergence.criteria with min 2 testable conditions
+- Each task must have `read_first[]` — files the executor MUST read before implementation
+- `action` must contain concrete values (function signatures, config keys, import paths), not just a verb
 - Task definitions follow the same schema as workflow-planner output
 - If you discover scope that belongs to another planner's range, note it in plan-note.md
 - Do not modify other planners' task files

package/maestro-flow/agents/workflow-plan-checker.md

@@ -30,7 +30,9 @@ You validate the quality of execution plans before they proceed to implementatio
    - Each criterion must reference a concrete artifact, output, or behavior
    - Criteria should be sufficient to prove the task is complete
 7. **Check files array** -- Verify each task's `files[]` array is consistent with its description
-8. **Report** -- Write check report with issues or approval
+8. **Check read_first** -- Verify each task has `read_first[]` containing: the file being modified + source-of-truth files. Missing or empty `read_first` is a critical issue.
+9. **Check action concreteness** -- Verify each task's `action` contains concrete values (function signatures, config keys, import paths), not vague verbs like "Implement" or references like "align X with Y"
+10. **Report** -- Write check report with issues or approval
 
 ### Revision Loop (max 3 rounds)
 - If issues found: write report with specific issues and suggested fixes
@@ -72,6 +74,14 @@ Check report written to the output location above:
 ## Files Array Consistency
 - TASK-006: description mentions "update config" but files[] does not include any config file
 
+## Read First Completeness
+- TASK-001 read_first: Missing — must include src/auth.ts (file being modified) + src/types/auth.ts (type definitions)
+- TASK-003 read_first: Has target file but missing source-of-truth reference
+
+## Action Concreteness
+- TASK-002 action: Too vague ("Implement auth") — should include: "Add verifyToken(token: string): Promise<AuthPayload> to src/auth.ts, import from jsonwebtoken"
+- TASK-005 action: Contains "align with existing pattern" — must specify the exact target state
+
 ## Summary
 <Overall assessment>
 ```

package/maestro-flow/agents/workflow-planner.md

@@ -92,9 +92,10 @@ When invoked with `quick` flag:
   "type": "feature",
   "priority": "medium",
   "effort": "medium",
-  "action": "Implement",
+  "action": "<concrete action with exact values: function signatures, config keys, import paths>",
   "scope": "<module path>",
   "focus_paths": ["src/tools/"],
+  "read_first": ["src/tools/existing-tool.ts", "src/types/tool.ts"],
   "depends_on": [],
   "parallel_group": null,
   "convergence": {
@@ -164,6 +165,8 @@ These rules prevent over-splitting that wastes tokens on unnecessary agent spawn
 - Each task must be substantial (15-60 min of work); group related changes, avoid file-per-task
 - Each task must have convergence.criteria (min 2 testable conditions)
 - convergence.criteria must be specific and testable (not "works correctly")
+- Each task must have `read_first[]` — files the executor MUST read before implementation (the file being modified + source-of-truth files)
+- `action` must contain concrete values (function signatures, config keys, import paths), not just a verb like "Implement"
 - files must use array format `[{path, action, target, change}]`
 - Wave ordering must respect dependencies (no task before its dependency)
 - Task descriptions must be clear enough for the executor to implement without ambiguity

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

@@ -48,7 +48,7 @@ $ARGUMENTS -- phase number for micro mode, topic text for macro/adhoc mode, no a
 - `-y` / `--yes`: Auto mode — skip interactive scoping, use recommended defaults, auto-deepen
 - `-c` / `--continue`: Resume from existing session (auto-detect session folder + discussion.md)
 - `-q` / `--quick`: Quick mode — skip exploration + scoring, go straight to decision extraction (context.md only)
-- `--from <source>`: Load upstream context package (brainstorm:ID, blueprint:BLP-xxx, @file, or path)
+- `--from <source>`: Load upstream context package (grill:ID, brainstorm:ID, blueprint:BLP-xxx, @file, or path)
 - `--gaps [ISS-ID]`: Issue root cause analysis mode. If ISS-ID provided, analyze single issue. If omitted, analyze all open/registered issues from issues.jsonl.
 
 Scope routing, output directory format, artifact registration schema, and output artifact listing are defined in workflow analyze.md (Scope Routing and Output Structure sections).

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

@@ -68,7 +68,7 @@ Interview the user relentlessly until shared understanding is reached. Active on
 - Branch jumps allowed: the user may switch freely between mode / role / upstream / sub-pipeline branches; sequence is not enforced, but every decision point must end with a definite answer.
 - Scope guard: only ask about decisions owned by `brainstorm`. Do not pre-resolve roadmap/plan choices.
 
-Decision points: mode (auto / single-role / review-only) / role selection and `--count` / `--from` upstream source / whether to enable design-research and the DESIGN.md sub-pipeline.
+Decision points: mode (auto / single-role / review-only) / role selection and `--count` / `--from` upstream source (grill:ID, blueprint:ID, @file, path) / whether to enable design-research and the DESIGN.md sub-pipeline.
 
 Exit: on consensus or explicit user signal to proceed, finalize session metadata. The §11 table (already populated incrementally) uses this schema:
 `| # | Decision | Choice | Source (user / code / default) |`
@@ -84,6 +84,7 @@ Auto mode:
 - Project initialized, need formal spec package → Skill({ skill: "maestro-blueprint", args: "--from brainstorm:{artifact_id}" })
 - Project initialized, quick roadmap → Skill({ skill: "maestro-roadmap", args: "--from brainstorm:{artifact_id}" })
 - Need deeper analysis first → Skill({ skill: "maestro-analyze", args: "{topic} --from brainstorm:{artifact_id}" })
+- Need stress-testing first → Skill({ skill: "maestro-grill", args: "{topic}" })
 - `html-prototypes/` produced with 2+ files and user wants to browse → load `~/.maestro/workflows/brainstorm-visualize.md` and launch visualizer server (optional, user-triggered)
 - DESIGN.md established during Step 3.5 → suggest: "Run `/maestro-impeccable build <feature-description>` to build with the established design system"
 

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

@@ -0,0 +1,531 @@
+---
+name: maestro-companion
+description: Knowledge companion — load context, record companion doc, capture insights, route to skills
+argument-hint: "[before|note|after|route] [--task <description>] [--type <task_type>] [--category <cat>]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Skill
+  - AskUserQuestion
+---
+
+<purpose>
+Task companion command — pairs with any task to provide knowledge context loading,
+structured companion document recording, insight capture, and skill routing.
+
+Does not create sessions or modify workflow state. Pure side-car utility.
+
+Four modes:
+- **before** — Pre-task: load spec + knowhow index + codebase index, create companion doc
+- **note** — Mid-task: append a structured entry to the active companion doc
+- **after** — Post-task: review companion doc, promote entries to spec/knowhow, suggest next steps
+- **route** — Routing: recommend next skill/command based on intent
+
+No arguments → auto-detect: uncommitted changes → `after`, else → `before`.
+</purpose>
+
+<context>
+$ARGUMENTS — mode + optional flags.
+
+**Mode detection priority:**
+1. Explicit `before` / `note` / `after` / `route`
+2. Intent text that is not a mode keyword → `route`
+3. No arguments → auto-detect (`git status` has changes → `after`, else → `before`)
+
+**Flags:**
+- `--task <description>` — Current task description (for targeted knowledge loading and doc title)
+- `--type <task_type>` — Task type for field template selection (see task types below)
+- `--category <cat>` — Spec category filter: coding / arch / test / review / debug / learning / ui
+
+**Task types** (determines which recording sections are active):
+
+| Type | Description | Key sections |
+|------|-------------|--------------|
+| `implement` | Feature development, code writing | working_files, dependencies, decisions, tests_affected |
+| `debug` | Bug investigation, root cause analysis | symptoms, hypotheses, evidence, root_cause, fix_applied |
+| `analyze` | Code/architecture/performance analysis | scope, findings, risks, recommendations |
+| `design` | Architecture/UI/API design | constraints, alternatives, trade_offs, chosen_approach |
+| `plan` | Task decomposition, roadmap planning | goals, breakdown, estimates, dependencies |
+| `review` | Code review, PR review | files_reviewed, findings, severity_counts, verdict |
+| `test` | Test writing, UAT, coverage expansion | coverage_before, coverage_after, gaps, test_files |
+| `refactor` | Code restructuring, tech debt | affected_modules, before_after, breaking_changes |
+| `learn` | Codebase exploration, knowledge building | questions, answers, mental_model, references |
+| `general` | Default / unclassified | (all universal sections) |
+
+Auto-detection: if `--type` not provided, infer from `--task` description keywords.
+
+**Companion document:**
+- Path: `.workflow/.scratchpad/companion-{YYYYMMDD-HHmmss}.md`
+- Active doc tracking: `.workflow/.scratchpad/.companion-active` (stores path of current companion doc)
+- Format: YAML frontmatter (rich metadata) + typed sections + timestamped entries
+</context>
+
+<state_machine>
+
+<states>
+S_PARSE    — Parse arguments, detect mode, resolve task type
+S_BEFORE   — Load knowledge context, create companion doc with typed template
+S_NOTE     — Append structured entry to active companion doc
+S_AFTER    — Review companion doc, populate outcome, promote entries, suggest next steps
+S_ROUTE    — Skill routing via maestro-next
+</states>
+
+<transitions>
+
+S_PARSE:
+  → S_BEFORE   WHEN: mode == "before" OR (no args AND no uncommitted changes)
+  → S_NOTE     WHEN: mode == "note"
+  → S_AFTER    WHEN: mode == "after" OR (no args AND has uncommitted changes)
+  → S_ROUTE    WHEN: mode == "route" OR intent text present
+
+</transitions>
+
+</state_machine>
+
+<execution>
+
+## S_BEFORE — Knowledge Loading + Companion Doc Creation
+
+Execute in order, skip unavailable steps:
+
+### 1. Load specs
+
+```bash
+# With --category: load by category
+maestro spec load --category <cat>
+
+# With --task: load by keyword extracted from task description
+maestro spec load --keyword <extracted_keyword>
+
+# No flags: load coding (most universal)
+maestro spec load --category coding
+```
+
+Display loaded rules summary (entry count + key rule names).
+
+### 2. Browse knowhow index
+
+```bash
+# List recent knowhow entries
+maestro knowhow list --store workflow
+
+# With --task: search relevant entries
+maestro knowhow search "<task_keyword>"
+```
+
+Display available knowhow entries (ID + title). Hint: `maestro wiki load <id>` for details.
+
+### 3. Check codebase index
+
+```bash
+ls .workflow/codebase/doc-index.json
+```
+
+- Exists → display "Codebase docs ready, last updated: {timestamp}"
+- Missing → suggest `/manage-codebase-rebuild`
+- Stale (>7 days) → suggest `/manage-codebase-refresh`
+
+### 4. Create companion document
+
+Create `.workflow/.scratchpad/` if needed. Resolve task type from `--type` flag or infer from `--task` keywords.
+
+Write companion doc with the full field template:
+
+```markdown
+---
+# === Identity ===
+task: "{task_description or 'Untitled task'}"
+task_type: "{resolved type: implement|debug|analyze|design|plan|review|test|refactor|learn|general}"
+created: "{ISO timestamp}"
+status: active
+
+# === Context Loaded ===
+specs_loaded: "{category or 'coding'}"
+specs_count: {N}
+knowhow_searched: "{keyword or 'none'}"
+knowhow_available: {M}
+codebase_index: "{ready|missing|stale}"
+branch: "{current git branch}"
+phase: "{current phase from state.json or 'none'}"
+milestone: "{current milestone from state.json or 'none'}"
+
+# === Scope ===
+working_files: []
+dependencies: []
+related_artifacts: []
+
+# === Outcome (populated by after mode) ===
+outcome: ""
+files_changed: []
+promoted_specs: 0
+promoted_knowhow: 0
+follow_up: []
+completed: ""
+---
+
+# Companion Doc — {task_description}
+
+> `/maestro-companion note "<content>"` — add entries
+> `/maestro-companion after` — review, promote, close
+
+## Context
+
+{Type-specific context section — see templates below}
+
+## Entries
+
+## Summary
+```
+
+**Type-specific context templates** (written into `## Context`):
+
+**implement:**
+```markdown
+### Working Files
+| File | Role | Status |
+|------|------|--------|
+
+### Dependencies
+- (modules, APIs, or services this task depends on)
+
+### Decisions
+| # | Decision | Rationale | Alternatives Considered |
+|---|----------|-----------|------------------------|
+
+### Tests Affected
+- (test files that need creation or update)
+```
+
+**debug:**
+```markdown
+### Symptoms
+- (observable behavior vs expected behavior)
+
+### Hypotheses
+| # | Hypothesis | Status | Evidence |
+|---|-----------|--------|----------|
+
+### Evidence Trail
+| Time | Source | Type | Finding |
+|------|--------|------|---------|
+
+### Root Cause
+- (populated when identified)
+
+### Fix Applied
+- (description of fix, files changed)
+```
+
+**analyze:**
+```markdown
+### Scope
+- (what is being analyzed and boundaries)
+
+### Findings
+| # | Finding | Severity | Location |
+|---|---------|----------|----------|
+
+### Risks
+- (identified risks or concerns)
+
+### Recommendations
+- (actionable recommendations)
+```
+
+**design:**
+```markdown
+### Constraints
+- (hard limits, requirements, compatibility needs)
+
+### Alternatives
+| # | Approach | Pros | Cons |
+|---|----------|------|------|
+
+### Trade-offs
+- (key trade-off decisions and rationale)
+
+### Chosen Approach
+- (selected design with justification)
+```
+
+**plan:**
+```markdown
+### Goals
+- (what success looks like)
+
+### Breakdown
+| # | Task | Estimate | Depends On | Status |
+|---|------|----------|------------|--------|
+
+### Dependencies
+- (external dependencies, blockers, prerequisites)
+```
+
+**review:**
+```markdown
+### Files Reviewed
+| File | Lines | Findings |
+|------|-------|----------|
+
+### Findings
+| # | Severity | Category | File:Line | Description |
+|---|----------|----------|-----------|-------------|
+
+### Verdict
+- (pass / pass-with-concerns / fail)
+```
+
+**test:**
+```markdown
+### Coverage
+- Before: {%}
+- After: {%}
+- Target: {%}
+
+### Test Files
+| File | Type | Tests Added | Status |
+|------|------|------------|--------|
+
+### Gaps
+- (uncovered paths or scenarios)
+```
+
+**refactor:**
+```markdown
+### Affected Modules
+- (modules being restructured)
+
+### Before / After
+| Aspect | Before | After |
+|--------|--------|-------|
+
+### Breaking Changes
+- (API or behavior changes that affect consumers)
+```
+
+**learn:**
+```markdown
+### Questions
+| # | Question | Answered | Source |
+|---|----------|----------|--------|
+
+### Mental Model
+- (evolving understanding of how it works)
+
+### References
+- (files, docs, wiki entries consulted)
+```
+
+**general:**
+```markdown
+### Notes
+- (general working notes)
+```
+
+Write the companion doc path to `.workflow/.scratchpad/.companion-active`.
+
+### 5. Output summary card
+
+```
+Knowledge context loaded
+  Spec:     {N} rules ({category})
+  Knowhow:  {M} entries available
+  Codebase: {status}
+  Doc:      {companion_doc_path} [{task_type}]
+
+Mid-task commands:
+  /maestro-companion note "finding or decision"
+  /maestro-companion note --file src/auth.ts "changed token validation"
+  /spec-load --keyword <keyword>
+  maestro wiki search "<query>"
+```
+
+---
+
+## S_NOTE — Append Structured Entry to Companion Doc
+
+### 1. Locate active companion doc
+
+Read `.workflow/.scratchpad/.companion-active` to get the doc path.
+If missing or file not found → create a new companion doc (same as S_BEFORE step 4, minimal — no spec/knowhow loading).
+
+### 2. Parse entry content and flags
+
+Parse $ARGUMENTS after `note` keyword:
+- `--file <path>` — associate entry with a specific file (appended to frontmatter `working_files`)
+- `--severity <level>` — for findings: critical / high / medium / low
+- Remaining text = entry content
+
+### 3. Classify entry type
+
+Auto-classify from content signals:
+
+| Content signal | Type tag |
+|---------------|----------|
+| "decided/decision/chose/picked/went with" | `decision` |
+| "pattern/convention/rule/always/never/must" | `spec-candidate` |
+| "pitfall/gotcha/careful/warning/trap/beware" | `pitfall` |
+| "learned/realized/discovered/understood/turns out" | `insight` |
+| "hypothesis/suspect/might be/could be" | `hypothesis` |
+| "found bug/root cause/because of/caused by" | `evidence` |
+| "risk/concern/worry/might break" | `risk` |
+| "todo/need to/should also/follow up/remaining" | `todo` |
+| "question/why does/how does/unclear" | `question` |
+| "blocked/stuck/can't/impossible" | `blocker` |
+| Default | `note` |
+
+### 4. Append entry
+
+Append to the companion doc under `## Entries`:
+
+```markdown
+### [{type}] {HH:mm} — {first line of content}
+
+{full content}
+
+{if --file: **File:** `{path}`}
+{if --severity: **Severity:** {level}}
+```
+
+### 5. Update frontmatter fields
+
+- If `--file` provided and not already in `working_files` → append to `working_files`
+- If type is `decision` → also append row to `### Decisions` table (if implement/design type doc)
+- If type is `hypothesis` → also append row to `### Hypotheses` table (if debug type doc)
+- If type is `evidence` → also append row to `### Evidence Trail` table (if debug type doc)
+- If type is `risk` → also append to `### Risks` list (if analyze/design type doc)
+- If type is `question` → also append row to `### Questions` table (if learn type doc)
+
+### 6. Confirm
+
+```
+[{type}] entry added to companion doc
+  /maestro-companion note "..."  — add more
+  /maestro-companion after       — review & promote
+```
+
+---
+
+## S_AFTER — Review Companion Doc + Populate Outcome + Promote Entries + Route
+
+### 1. Load companion doc
+
+Read `.workflow/.scratchpad/.companion-active` → read the companion doc.
+If no active doc or doc is empty → skip to step 4 (accumulation reminder).
+
+### 2. Populate outcome fields
+
+Collect task outcome data:
+
+```bash
+# Detect files changed since companion doc creation
+git diff --name-only --since="{companion_created_timestamp}"
+```
+
+Update frontmatter:
+- `files_changed` — from git diff
+- `completed` — current ISO timestamp
+- `status` — `completed`
+
+Display entry summary:
+```
+Companion doc review — {task_type}
+  Entries:    {total} ({by type breakdown})
+  Files:      {files_changed count} changed
+  Duration:   {elapsed since created}
+
+Promotable entries:
+  {list of decision/spec-candidate/pitfall/insight entries}
+```
+
+### 3. Promote entries
+
+If promotable entries exist, AskUserQuestion:
+
+- Option 1: "Promote to spec" — short coding/arch/test constraint
+- Option 2: "Promote to knowhow" — detailed recipe/template/decision/tip
+- Option 3: "Promote both" — spec index entry + knowhow document
+- Option 4: "Skip — nothing to promote"
+
+**Routing by selection:**
+
+| Selection | Action |
+|-----------|--------|
+| Spec | `Skill("spec-add", args)` — guide user through category + content |
+| Knowhow | `Skill("manage-knowhow-capture", args)` — guide through type + content |
+| Both | `Skill("spec-add")` first, then `Skill("manage-knowhow-capture")` |
+| Skip | Proceed to step 4 |
+
+Update frontmatter: `promoted_specs`, `promoted_knowhow` counts.
+
+Extract any `todo` entries → write to `follow_up` in frontmatter.
+
+Clear `.workflow/.scratchpad/.companion-active`.
+
+### 4. Output accumulation reminder + routing
+
+```
+Knowledge accumulation reminders:
+  Reusable pattern found?        /spec-add <category> "title" "content"
+  Solved a complex problem?      /manage-knowhow-capture recipe "description"
+  Made an architecture decision? /manage-knowhow-capture decision "description"
+  Discovered a useful trick?     /manage-knowhow-capture tip "content"
+
+Next steps:
+  /maestro-next          — recommend next command
+  /maestro "<intent>"    — route intent to full workflow
+  /manage-status         — view project dashboard
+```
+
+---
+
+## S_ROUTE — Skill Routing
+
+### 1. Parse intent
+
+Extract intent text from $ARGUMENTS after removing the `route` keyword.
+
+### 2. Delegate to maestro-next
+
+```
+Skill("maestro-next", "<intent_text>")
+```
+
+Reuses maestro-next routing table and scoring logic to recommend the best single command.
+
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| W001 | warning | `.workflow/specs/` not initialized | Suggest `/spec-setup` |
+| W002 | warning | `.workflow/knowhow/` is empty | Normal, skip knowhow index |
+| W003 | warning | `.workflow/codebase/` does not exist | Suggest `/manage-codebase-rebuild` |
+| W004 | warning | No active companion doc found (note/after mode) | Create new doc or skip |
+</error_codes>
+
+<success_criteria>
+- [ ] Mode correctly detected (before/note/after/route)
+- [ ] Task type resolved from --type flag or inferred from --task keywords
+- [ ] before: spec + knowhow + codebase indexes loaded or hints given
+- [ ] before: companion doc created with full YAML frontmatter (identity + context + scope + outcome placeholders)
+- [ ] before: type-specific context template written (matching task_type)
+- [ ] before: active doc path written to `.companion-active`
+- [ ] before: summary card output with mid-task command hints
+- [ ] note: active companion doc located and entry appended with type tag
+- [ ] note: entry type auto-classified from content signals (11 type tags)
+- [ ] note: --file flag updates working_files in frontmatter
+- [ ] note: typed entries cross-posted to matching context tables (decisions→Decisions, hypothesis→Hypotheses, etc.)
+- [ ] after: companion doc entries reviewed and promotable items identified
+- [ ] after: outcome fields populated (files_changed, completed, status)
+- [ ] after: AskUserQuestion routes to spec-add or manage-knowhow-capture
+- [ ] after: todo entries extracted to follow_up field
+- [ ] after: companion doc marked completed, active pointer cleared
+- [ ] after: accumulation reminder + next-step routing displayed
+- [ ] route: intent correctly forwarded to maestro-next
+- [ ] No session created, no state.json modified
+</success_criteria>

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

@@ -0,0 +1,114 @@
+---
+name: maestro-grill
+description: Use when stress-testing a plan, idea, or requirement against codebase reality before brainstorming
+argument-hint: "<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 a plan, idea, or requirement against codebase reality. Walks every branch of the decision tree one question at a time — challenging vague terminology against existing code, probing edge cases with concrete scenarios, and verifying assumptions with code evidence. Produces a verified context package (grill-report.md + terminology.md + context-package.json) for downstream brainstorm/analyze/roadmap consumption.
+
+Positioned BEFORE brainstorm in the pipeline: grill stress-tests and sharpens; brainstorm generates and elaborates.
+</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:**
+- `-y` / `--yes`: Auto mode — CLI exploration replaces human answers
+- `-c` / `--continue`: Resume from last grill session
+- `--session ID`: Resume specific session
+- `--depth shallow|standard|deep`: Branch count 3/5/8 (default: 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`
+
+### Role Knowledge
+`maestro wiki search "{topic keywords}"` → load relevant entries before grilling.
+`maestro spec load --category arch` → load architecture constraints.
+</context>
+
+<interview_protocol>
+Grill the user relentlessly until every branch of the decision tree is walked. This is NOT a menu-driven interview — it is adversarial Socratic questioning. Active only in interactive mode; skip when `-y/--yes` or `-c/--continue`.
+
+Core protocol:
+- **One question per turn**. Each question probes ONE specific aspect. Never ask compound questions.
+- **Code-grounded**: Before asking, search the codebase for evidence. Use findings to sharpen the question or challenge the user's answer. Never ask what code can verify — search first, then confront.
+- **Escalating depth**: Start with scope boundaries, progress to data model, edge cases, failure modes. Each branch goes basic → specific → adversarial.
+- **Immediate writeback**: After each answered question, immediately append the Q&A + decision to `grill-report.md`. Do NOT batch — partial progress must be on disk before the next question.
+- **Challenge contradictions**: If an answer conflicts with code evidence or a prior answer, immediately surface the contradiction and demand resolution.
+- **Terminology enforcement**: When the user uses a term that conflicts with codebase naming, challenge it immediately. Propose the code-consistent alternative. Update `terminology.md` as terms crystallize.
+
+Question framing rules:
+- Reference specific code findings: "The codebase uses `{symbol}` at `{file:line}` — your proposal calls it `{term}`. Which wins?"
+- Use concrete scenarios: "What happens when a user does {action} while {condition} is true?"
+- Probe boundaries: "You said {X} is in scope — does that include {edge_case}, or is that separate?"
+- Challenge scale: "This touches `{table}` — at 10x current data volume, which query breaks first?"
+
+Branch walking order: Scope & Boundaries → Data Model & State → Edge Cases & Failure Modes → Integration & Dependencies → Scale & Performance → Security & Access Control → Observability & Operations → Migration & Rollback. Number of branches determined by `--depth`.
+
+Exit: When all depth-selected branches are fully walked (every question answered or explicitly deferred), finalize the report and generate context-package.json.
+</interview_protocol>
+
+<execution>
+Follow '~/.maestro/workflows/grill.md' completely.
+
+**Next-step routing on completion:**
+
+Standard routing:
+- 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}" })
+
+Resume routing:
+- More branches to walk → Skill({ skill: "maestro-grill", args: "{topic} -c" })
+</execution>
+
+<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
+</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>

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

@@ -73,6 +73,10 @@ If exit code is 1, present warnings and ask whether to proceed.
 
 Follow '~/.maestro/workflows/plan.md' completely.
 
+### P3 Agent Constraint (MANDATORY)
+
+Main flow **MUST** spawn a planner agent (Agent tool) for P3 planning — inline planning by main flow is FORBIDDEN. The agent produces both `plan.json` and `.task/TASK-*.json` files. Main flow only passes context and validates output.
+
 ### Codebase Docs Loading (P1 addition)
 
 During P1 Context Collection, after loading context files, load codebase documentation if available:

package/maestro-flow/commands/lifecycle/swarm-workflow.md

@@ -0,0 +1,256 @@
+---
+name: maestro-swarm-workflow
+description: Parallel workflow accelerator — route intent to fixed Workflow scripts for multi-agent concurrent execution
+argument-hint: "<intent> [--script <name>] [--dims <d1,d2>] [--roles <r1,r2>] [--count N] [--tier quick|standard] [--resume <runId>]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Workflow
+  - AskUserQuestion
+---
+<purpose>
+Parallel accelerator layer for maestro commands. Routes user intent to pre-built Workflow scripts
+that leverage `parallel()` / `pipeline()` for multi-agent concurrent execution.
+
+Complements maestro-ralph (sequential decision chain) — ralph manages state + decisions,
+swarm-workflow provides parallel compute bursts within individual steps.
+
+Scripts: `~/.maestro/workflows/swarm/wf-*.js`
+
+| Script | Accelerates | Pattern |
+|--------|-------------|---------|
+| `wf-analyze` | maestro-analyze | cli-explore-agent → 6-dimension parallel scoring → synthesis |
+| `wf-brainstorm` | maestro-brainstorm | multi-role parallel analysis → cross-role-reviewer → guidance |
+| `wf-review` | quality-review | 6-dimension workflow-reviewer → adversarial verify → report |
+| `wf-verify` | maestro-verify | 3-layer workflow-verifier + convergence + antipattern → aggregate |
+| `wf-grill` | maestro-grill | cli-explore-agent → parallel branch stress-testing → contradiction synthesis |
+| `wf-plan` | maestro-plan | parallel context exploration → workflow-planner → plan-checker |
+| `wf-execute` | maestro-execute | wave-based parallel workflow-executor (worktree isolation) |
+| `wf-milestone-audit` | maestro-milestone-audit | parallel coverage + execution + integration-checker |
+
+Integration modes:
+- **Standalone**: `/maestro-swarm-workflow "analyze auth module"` — direct invocation
+- **Ralph step**: ralph chain 中某个 step 可指定 `swarm-workflow` 作为加速执行器
+- **Chained**: 输出 JSON 可被下游命令通过 `--from` 消费
+</purpose>
+
+<context>
+$ARGUMENTS — intent text with optional flags.
+
+**Parse:**
+```
+--script <name>  → 强制指定脚本（wf-analyze, wf-brainstorm, wf-review, wf-verify）
+--dims <d1,d2>   → 限定分析维度（analyze: architecture,complexity,patterns,risk,testability,performance）
+--roles <r1,r2>  → 限定角色（brainstorm: system-architect,product-manager,test-strategist,ux-expert,security-analyst,data-architect）
+--count N        → 角色数量（brainstorm 默认 3）
+--tier <level>   → review 层级（quick=2 维度, standard=4 维度）
+--resume <runId> → 从之前的 workflow 运行恢复（增量重跑）
+Remaining        → intent
+```
+
+**Script inventory** (`~/.maestro/workflows/swarm/`):
+
+| Script | args 接口 |
+|--------|-----------|
+| `wf-analyze` | `{ target, scope, context, phase?, dimensions? }` |
+| `wf-brainstorm` | `{ topic, context, count?, roles? }` |
+| `wf-review` | `{ target, scope, specs?, tier?, dimensions? }` |
+| `wf-verify` | `{ goals, plan_dir?, scope?, task_files?, must_haves?, skip_antipattern? }` |
+| `wf-grill` | `{ topic, context?, depth?: "shallow"\|"standard"\|"deep" }` |
+| `wf-plan` | `{ context_dir?, from?, phase?, scope?, specs?, gaps?, quick? }` |
+| `wf-execute` | `{ plan_dir, specs?, codebase_context?, wiki_context?, auto_commit? }` |
+| `wf-milestone-audit` | `{ milestone?, is_adhoc? }` |
+</context>
+
+<state_machine>
+
+<states>
+S_PARSE        — 解析参数和意图                    PERSIST: —
+S_ROUTE        — 路由到目标脚本                    PERSIST: —
+S_CONTEXT      — 组装 context payload             PERSIST: —
+S_DISPATCH     — 调用 Workflow 工具                PERSIST: —
+S_INGEST       — 处理返回结果                      PERSIST: —
+S_FALLBACK     — 无法路由                         PERSIST: —
+</states>
+
+<transitions>
+
+S_PARSE:
+  → S_ROUTE     WHEN: intent parsed                DO: A_PARSE_ARGS
+  → S_FALLBACK  WHEN: no intent
+
+S_ROUTE:
+  → S_CONTEXT   WHEN: script resolved              DO: A_ROUTE_SCRIPT
+  → S_FALLBACK  WHEN: ambiguous intent              DO: AskUserQuestion
+
+S_CONTEXT:
+  → S_DISPATCH  DO: A_ASSEMBLE_CONTEXT
+
+S_DISPATCH:
+  → S_INGEST    WHEN: workflow completed            DO: A_DISPATCH_WORKFLOW
+  → S_FALLBACK  WHEN: workflow failed
+
+S_INGEST:
+  → END         DO: A_INGEST_RESULTS
+
+S_FALLBACK:
+  → S_PARSE     WHEN: user provides input
+  → END         WHEN: user cancels
+
+</transitions>
+
+<actions>
+
+### A_PARSE_ARGS
+
+1. 提取 flags（--script, --dims, --roles, --count, --tier, --resume）
+2. 剩余文本作为 intent
+3. 若有 --resume，记录 resumeRunId
+
+### A_ROUTE_SCRIPT
+
+Intent-to-script routing（按关键词匹配，--script 优先级最高）：
+
+| Keywords | Script |
+|----------|--------|
+| 分析 / analyze / 探索 / explore / 架构 / architecture / 复杂度 / 风险 | `wf-analyze` |
+| 头脑风暴 / brainstorm / 方案 / 设计 / 评估 / evaluate / 多角度 | `wf-brainstorm` |
+| 审查 / review / 代码审查 / code review / 质量 / quality | `wf-review` |
+| 验证 / verify / 检查 / check / 反模式 / antipattern | `wf-verify` |
+| 拷问 / grill / 压力测试 / stress-test / 挑战 / challenge | `wf-grill` |
+| 规划 / plan / 任务分解 / decompose / 分波 / wave | `wf-plan` |
+| 执行 / execute / 实现 / implement / 开发 / develop | `wf-execute` |
+| 里程碑审计 / milestone-audit / 集成检查 / integration | `wf-milestone-audit` |
+
+多命中 → AskUserQuestion 让用户选择。
+
+### A_ASSEMBLE_CONTEXT
+
+根据目标脚本组装 args payload：
+
+**wf-analyze:**
+1. Read `.workflow/state.json` 获取当前 phase/milestone 信息
+2. `target` = intent 中的目标描述
+3. `scope` = 从 intent 推断文件范围，或读 roadmap 获取 phase scope
+4. `context` = 拼接相关上下文（上游 artifact 摘要、specs）
+5. `dimensions` = --dims 解析结果（可选）
+
+**wf-brainstorm:**
+1. `topic` = intent 文本
+2. `context` = 读取相关代码文件摘要 + 已有 specs
+3. `count` = --count 或默认 3
+4. `roles` = --roles 解析结果（可选）
+
+**wf-review:**
+1. `target` = 读 git diff 描述变更范围
+2. `scope` = 变更文件列表
+3. `tier` = --tier 或 "standard"
+4. `dimensions` = --dims 解析结果（可选）
+
+**wf-verify:**
+1. `goals` = 读最近的 plan artifact 提取目标列表
+2. `plan_dir` = 定位最近的 plan scratch 目录
+3. `scope` = plan 涉及的文件范围
+4. `skip_tests` / `skip_antipattern` = 从 flags 提取
+
+### A_DISPATCH_WORKFLOW
+
+1. 确定 scriptPath = `~/.maestro/workflows/swarm/{script}.js`（展开为绝对路径）
+2. 构建 Workflow 调用：
+   ```
+   Workflow({
+     scriptPath: absoluteScriptPath,
+     args: assembledArgs,
+     resumeFromRunId: resumeRunId  // 若有
+   })
+   ```
+3. 等待 Workflow 返回结果
+4. 记录 runId 用于潜在的后续 resume
+
+### A_INGEST_RESULTS
+
+Workflow 返回 JSON 后：
+
+1. **摘要输出**：按脚本类型格式化关键指标
+   - analyze: overall_score, scope_verdict, go_no_go, critical findings count
+   - brainstorm: role count, conflict/synergy count, top guidance items
+   - review: verdict (APPROVE/REQUEST_CHANGES/BLOCK), confirmed vs false-positive count
+   - verify: overall_passed, confidence, gap count, antipattern blocker count
+
+2. **Artifact 写入**（可选）：
+   - 若当前在 ralph session 中（检测 `.workflow/.maestro/ralph-*/status.json` 状态为 running）：
+     将结果写入对应 step 的 scratch 目录，格式兼容命令产出
+   - 否则写入 `.workflow/scratch/{YYYYMMDD}-swarm-{script}-{slug}/results.json`
+
+3. **Ralph 兼容产出**：
+   - analyze → `analysis.md` + `context.md`（decisions）+ `conclusions.json`
+   - brainstorm → `guidance-specification.md`
+   - review → `review.json`
+   - verify → `verification.json`
+
+4. **RunId 提示**：显示 `Resume: /maestro-swarm-workflow --resume {runId}` 用于增量重跑
+
+</actions>
+
+</state_machine>
+
+<invariants>
+1. **只做并行加速，不做状态决策** — 不修改 ralph status.json，不推进 step
+2. **args 预编译** — 所有 FS 读取在 A_ASSEMBLE_CONTEXT 完成，脚本内 agent 通过工具自行读取补充
+3. **产出格式兼容** — 写入的 artifact 格式必须与对应命令（analyze/brainstorm/review/verify）的产出一致
+4. **resume 透传** — resumeFromRunId 直接透传给 Workflow 工具，利用内置缓存机制
+5. **脚本只读** — 路由命令不修改 `~/.maestro/workflows/swarm/wf-*.js` 脚本文件
+6. **结果必须展示** — Workflow 返回后必须向用户展示格式化摘要，不得静默完成
+</invariants>
+
+<appendix>
+
+### 与 Ralph 集成
+
+Ralph 可以在 A_BUILD_STEPS 中将某些 step 的执行方式标记为 `swarm-workflow`：
+
+```json
+{
+  "index": 2,
+  "skill": "maestro-swarm-workflow",
+  "args": "--script wf-analyze {phase}",
+  "stage": "analyze",
+  "command_scope": "project",
+  "command_path": "<resolved by maestro ralph skills>"
+}
+```
+
+ralph-execute 正常通过 `maestro ralph next` 加载并执行，swarm-workflow 内部再调 Workflow 工具。
+
+### 输出示例
+
+```
+┌─ wf-analyze ──────────────────────────────────────┐
+│  Explore  [████████████████████] 6/6 dimensions    │
+│  Synthesize  [████████████████] done               │
+├────────────────────────────────────────────────────┤
+│  Score: 7.2/10  Scope: medium  Verdict: go         │
+│  Findings: 23 total (2 critical, 5 high)           │
+│  Cross-cutting: 3 themes                           │
+│  Decisions: 4 locked, 2 free, 1 deferred           │
+├────────────────────────────────────────────────────┤
+│  Output: .workflow/scratch/20260530-swarm-analyze/  │
+│  Resume: /maestro-swarm-workflow --resume wf_abc123 │
+└────────────────────────────────────────────────────┘
+```
+
+### Error Codes
+
+| Code | Description | Recovery |
+|------|-------------|----------|
+| E001 | No intent and no --script | Prompt for intent |
+| E002 | Ambiguous routing | AskUserQuestion |
+| E003 | Script file not found | Check .claude/workflows/ |
+| E004 | Workflow execution failed | Show error, suggest --resume |
+| E005 | Result ingestion failed | Write raw JSON to scratch |
+
+</appendix>

package/maestro-flow/commands/manage/codebase-rebuild.md

@@ -35,7 +35,7 @@ $ARGUMENTS -- optional flags.
 | Agent | Focus | Output file |
 |-------|-------|-------------|
 | Mapper 1 | **Tech stack** -- languages, frameworks, dependencies, build system | `tech-stack.md` |
-| Mapper 2 | **Architecture** -- layers, module boundaries, data flow, entry points | `architecture.md` |
+| Mapper 2 | **Architecture** -- produced by KG pipeline Step 14 (UA architecture-analyzer delegate); layers, module boundaries, data flow, entry points | `architecture.md` |
 | Mapper 3 | **Features** -- capabilities, API surface, user-facing functionality | `features.md` |
 | Mapper 4 | **Cross-cutting concerns** -- error handling, logging, auth, config, testing | `concerns.md` |
 
@@ -43,6 +43,9 @@ $ARGUMENTS -- optional flags.
 - `.workflow/` -- must be initialized (project.md, state.json exist)
 - `.workflow/codebase/` -- target directory (will be cleared and rebuilt)
 - `.workflow/codebase/doc-index.json` -- generated documentation index
+- `.workflow/codebase/knowledge-graph.json` -- Knowledge Graph with nodes, edges, layers, and tour (generated by KG pipeline Steps 10–17 if UA vendor is installed)
+
+**UA vendor requirement:** The KG pipeline (Steps 10–17) requires the UA vendor at `~/.maestro/vendor/ua/understand-anything-plugin/`. If not installed, these steps are skipped automatically. Run `scripts/ua-vendor-setup.sh` to install.
 </context>
 
 <execution>
@@ -53,6 +56,9 @@ Follow '~/.maestro/workflows/codebase-rebuild.md' completely.
 **Next-step routing on completion:**
 - View updated project state → `/manage-status`
 - Incremental updates later → `/manage-codebase-refresh`
+- Verify KG stats → `maestro kg stats`
+- Verify wiki integration → `maestro wiki list --keyword kg`
+- Future change impact → `maestro kg diff-wiki`
 </execution>
 
 <error_codes>
@@ -61,6 +67,8 @@ Follow '~/.maestro/workflows/codebase-rebuild.md' completely.
 | E001 | error | .workflow/ not initialized | Run maestro-init first to create .workflow/ |
 | W001 | warning | A mapper agent failed (partial results) | Retry failed mapper or accept partial results |
 | W002 | warning | `.workflow/codebase/` already exists -- user prompted for rebuild/skip | check_existing |
+| W003 | warning | KG validation failed (graph written with valid=false) | Review .kg-tmp/ artifacts, re-run KG pipeline |
+| W004 | warning | Wiki index rebuild failed after KG generation | Non-fatal, retries on next wiki access |
 </error_codes>
 
 <success_criteria>
@@ -71,5 +79,9 @@ Follow '~/.maestro/workflows/codebase-rebuild.md' completely.
 - [ ] All documentation files regenerated
 - [ ] state.json updated with rebuild timestamp
 - [ ] project.md Tech Stack section updated if changes detected
+- [ ] KG pipeline executed (if UA vendor installed)
+- [ ] knowledge-graph.json generated in .workflow/codebase/ (if UA vendor installed)
+- [ ] KG nodes indexed as virtual wiki entries (automatic via WikiIndexer on next wiki access)
 - [ ] Next step routing: `/manage-status` or `/manage-codebase-refresh` for incremental updates later
+- [ ] KG impact check available: `maestro kg diff-wiki` for future change impact analysis
 </success_criteria>

package/maestro-flow/commands/manage/codebase-refresh.md

@@ -32,6 +32,7 @@ $ARGUMENTS -- optional flags.
 - `.workflow/` -- must be initialized
 - `.workflow/codebase/` -- must contain existing docs (from prior rebuild)
 - `.workflow/codebase/doc-index.json` -- documentation index with timestamps
+- `.workflow/codebase/knowledge-graph.json` -- Knowledge Graph (optional, for KG impact analysis)
 - `.workflow/state.json` -- contains `codebase_last_rebuilt` timestamp
 </context>
 
@@ -50,6 +51,8 @@ Follow '~/.maestro/workflows/codebase-refresh.md' completely.
 <success_criteria>
 - [ ] Changed files detected via git diff since last refresh
 - [ ] Affected documentation entries identified from doc-index.json
+- [ ] KG impact analysis run (if knowledge-graph.json exists): `maestro kg diff-wiki --json`
+- [ ] Affected wiki entries flagged with warnings (if any)
 - [ ] Only affected docs refreshed (selective mapper re-run)
 - [ ] doc-index.json timestamps updated per affected entry
 - [ ] state.json updated with codebase_last_refreshed timestamp

package/maestro-flow/commands/spec/setup.md

@@ -11,8 +11,9 @@ allowed-tools:
 ---
 <purpose>
 Initialize the project-level specs directory by scanning the codebase for conventions, patterns, and tech stack.
-Core files (coding, arch, knowhow) are always created. Optional files (quality, debug, test, review) are created only when relevant signals are detected.
-All output lands in `.workflow/specs/`.
+Core files (coding, arch, learnings) are always created. Optional spec files (quality, test, ui) are created only when relevant signals are detected.
+Additionally, generates recipe-type knowhow docs in `.workflow/knowhow/` for detected operational workflows (test / debug / build / dev / lint) — capturing "how to do X in this project" so future agents can find them via `maestro wiki search`.
+Spec output lands in `.workflow/specs/`; recipe output lands in `.workflow/knowhow/`.
 </purpose>
 
 <required_reading>
@@ -37,12 +38,15 @@ Follow '~/.maestro/workflows/specs-setup.md' completely.
 | E001 | fatal | `.workflow/` directory not initialized -- run `/maestro-init` first | parse_input |
 | E002 | fatal | No source files found in project -- nothing to scan | scan_codebase |
 | W001 | warning | Convention detection uncertain for one or more categories -- marked `[UNCERTAIN]` | generate_specs |
+| W002 | warning | Workflow recipe signals detected but commands ambiguous -- recipe skipped | generate_recipes |
+| W003 | warning | Existing recipe slug found -- new content written as `.proposed.md` for manual diff | generate_recipes |
 </error_codes>
 
 <success_criteria>
 - [ ] `.workflow/specs/` directory created
-- [ ] Core files always created: `coding-conventions.md`, `architecture-constraints.md`, `knowhow.md`
-- [ ] Optional files created when detected: `quality-rules.md` (linter/CI), `test-conventions.md` (test framework), `debug-notes.md` (on demand), `review-standards.md` (on demand)
-- [ ] Report displayed with summary and next steps
+- [ ] Core spec files always created: `coding-conventions.md`, `architecture-constraints.md`, `learnings.md`
+- [ ] Optional spec files created when detected: `quality-rules.md` (linter/CI), `test-conventions.md` (test framework), `ui-conventions.md` (frontend framework). `debug-notes.md` / `review-standards.md` deferred (on demand via `/spec-add`).
+- [ ] Workflow recipe knowhow created in `.workflow/knowhow/` for each detected operational workflow (test / debug / build / dev / lint). Each recipe matches the `recipe` schema in `~/.maestro/workflows/knowhow.md` Part B and contains at least one runnable command.
+- [ ] Report displayed grouped by destination (specs / recipes / skipped / deferred), with `.proposed.md` files surfaced when an existing recipe slug was preserved.
 </success_criteria>
 </output>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "maestro-flow-one",
-  "version": "0.2.24",
+  "version": "0.2.25",
   "description": "All Maestro workflow commands as a single Claude Code skill — intent routing, decision gates, minimal closed-loop chains",
   "bin": {
     "maestro-flow": "bin/maestro-flow.js"