maestro-flow 0.1.4 → 0.2.0

package/.claude/commands/maestro-brainstorm.md

@@ -1,90 +1,90 @@
----
-name: maestro-brainstorm
-description: Unified brainstorming with dual-mode operation - auto pipeline and single role analysis
-argument-hint: "[topic|role-name] [--yes] [--count N] [--session ID] [--update] [--skip-questions] [--include-questions] [--style-skill PKG]"
-allowed-tools:
-  - Read
-  - Write
-  - Bash
-  - Glob
-  - Grep
-  - Agent
-  - AskUserQuestion
----
-<purpose>
-Unified brainstorming combining interactive framework generation, multi-role parallel analysis, and cross-role synthesis. Two modes: Auto (full pipeline with guidance-specification → parallel role analysis → synthesis) and Single Role (individual role analysis for an existing session). Outputs structured artifacts in .brainstorming/ directory ready for downstream planning.
-</purpose>
-
-<required_reading>
-@~/.maestro/workflows/brainstorm.md
-</required_reading>
-
-<deferred_reading>
-- [scratch-index.json](~/.maestro/templates/scratch-index.json) — read when operating in scratch mode
-- [index.json](~/.maestro/templates/index.json) — read when operating in phase mode
-</deferred_reading>
-
-<context>
-$ARGUMENTS -- topic text for auto mode, or role name for single role mode.
-
-**Auto mode**: topic text (e.g., "Build real-time collaboration platform") triggers full pipeline.
-**Single role mode**: valid role name (e.g., "system-architect") runs one role analysis.
-**Phase mode** (number): resolves phase directory, creates .brainstorming/ inside it.
-**Scratch mode** (text): creates `.workflow/scratch/brainstorm-{slug}-{date}/`.
-
-**Valid roles**: data-architect, product-manager, product-owner, scrum-master, subject-matter-expert, system-architect, test-strategist, ui-designer, ux-expert
-
-**Flags**:
-- `--yes` / `-y`: Auto mode, skip interactive questions, use defaults
-- `--count N`: Number of roles to select (default 3, max 9)
-- `--session ID`: Use existing session
-- `--update`: Update existing analysis (single role)
-- `--skip-questions`: Skip context gathering questions
-- `--include-questions`: Force context gathering even if analysis exists
-- `--style-skill PKG`: Style package for ui-designer role
-</context>
-
-<execution>
-Follow '~/.maestro/workflows/brainstorm.md' completely.
-
-**Next-step routing on completion:**
-
-Auto mode:
-- Project not initialized → Skill({ skill: "maestro-init" })
-- Project initialized, need spec package → Skill({ skill: "maestro-spec-generate", args: "--from-brainstorm {session_id}" })
-- Project initialized, quick roadmap → Skill({ skill: "maestro-roadmap", args: "--from-brainstorm {session_id}" })
-- Need deeper analysis first → Skill({ skill: "maestro-analyze", args: "{topic}" })
-
-Single role mode:
-- More roles needed → Skill({ skill: "maestro-brainstorm", args: "{next_role} --session {session_id}" })
-- All roles done, run synthesis → Skill({ skill: "maestro-brainstorm", args: "{topic} --session {session_id}" })
-</execution>
-
-<error_codes>
-| Code | Severity | Condition | Recovery |
-|------|----------|-----------|----------|
-| E001 | error | Topic or role argument required | Prompt user for topic text or role name |
-| E002 | error | No active session for single role mode | Guide user to run auto mode first |
-| E003 | error | Invalid role name | Show valid roles list |
-| W001 | warning | Fewer than 10 ideas in divergent phase | Proceed with available ideas |
-| W002 | warning | Project context (.workflow/) not found | Continue without project context |
-| W003 | warning | Role template not found | Use generic analysis structure |
-| W004 | warning | Validation score < 60 | Log warning, suggest manual review |
-| W005 | warning | External research agent failed | Continue without designResearchContext |
-</error_codes>
-
-<success_criteria>
-**Auto mode**:
-- [ ] guidance-specification.md with RFC 2119 keywords, terminology, non-goals, feature decomposition
-- [ ] Role analysis files for each selected role in `.brainstorming/{role}/`
-- [ ] Feature specs in `.brainstorming/feature-specs/` (or synthesis-specification.md)
-- [ ] feature-index.json and synthesis-changelog.md
-- [ ] All user decisions captured with Decision Recording Protocol
-- [ ] Session metadata updated with completion status
-
-**Single role mode**:
-- [ ] analysis.md written to `{output_dir}/{role}/`
-- [ ] Feature-point organization used when feature list available
-- [ ] Framework reference included when guidance-specification.md exists
-- [ ] Session metadata updated
-</success_criteria>
+---
+name: maestro-brainstorm
+description: Unified brainstorming with dual-mode operation - auto pipeline and single role analysis
+argument-hint: "[topic|role-name] [--yes] [--count N] [--session ID] [--update] [--skip-questions] [--include-questions] [--style-skill PKG]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+<purpose>
+Unified brainstorming combining interactive framework generation, multi-role parallel analysis, and cross-role synthesis. Two modes: Auto (full pipeline with guidance-specification → parallel role analysis → synthesis) and Single Role (individual role analysis for an existing session). Outputs structured artifacts in .brainstorming/ directory ready for downstream planning.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/brainstorm.md
+</required_reading>
+
+<deferred_reading>
+- [scratch-index.json](~/.maestro/templates/scratch-index.json) — read when operating in scratch mode
+- [index.json](~/.maestro/templates/index.json) — read when operating in phase mode
+</deferred_reading>
+
+<context>
+$ARGUMENTS -- topic text for auto mode, or role name for single role mode.
+
+**Auto mode**: topic text (e.g., "Build real-time collaboration platform") triggers full pipeline.
+**Single role mode**: valid role name (e.g., "system-architect") runs one role analysis.
+**Phase mode** (number): resolves phase directory, creates .brainstorming/ inside it.
+**Scratch mode** (text): creates `.workflow/scratch/brainstorm-{slug}-{date}/`.
+
+**Valid roles**: data-architect, product-manager, product-owner, scrum-master, subject-matter-expert, system-architect, test-strategist, ui-designer, ux-expert
+
+**Flags**:
+- `--yes` / `-y`: Auto mode, skip interactive questions, use defaults
+- `--count N`: Number of roles to select (default 3, max 9)
+- `--session ID`: Use existing session
+- `--update`: Update existing analysis (single role)
+- `--skip-questions`: Skip context gathering questions
+- `--include-questions`: Force context gathering even if analysis exists
+- `--style-skill PKG`: Style package for ui-designer role
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/brainstorm.md' completely.
+
+**Next-step routing on completion:**
+
+Auto mode:
+- Project not initialized → Skill({ skill: "maestro-init" })
+- Project initialized, need spec package → Skill({ skill: "maestro-spec-generate", args: "--from-brainstorm {session_id}" })
+- Project initialized, quick roadmap → Skill({ skill: "maestro-roadmap", args: "--from-brainstorm {session_id}" })
+- Need deeper analysis first → Skill({ skill: "maestro-analyze", args: "{topic}" })
+
+Single role mode:
+- More roles needed → Skill({ skill: "maestro-brainstorm", args: "{next_role} --session {session_id}" })
+- All roles done, run synthesis → Skill({ skill: "maestro-brainstorm", args: "{topic} --session {session_id}" })
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | Topic or role argument required | Prompt user for topic text or role name |
+| E002 | error | No active session for single role mode | Guide user to run auto mode first |
+| E003 | error | Invalid role name | Show valid roles list |
+| W001 | warning | Fewer than 10 ideas in divergent phase | Proceed with available ideas |
+| W002 | warning | Project context (.workflow/) not found | Continue without project context |
+| W003 | warning | Role template not found | Use generic analysis structure |
+| W004 | warning | Validation score < 60 | Log warning, suggest manual review |
+| W005 | warning | External research agent failed | Continue without designResearchContext |
+</error_codes>
+
+<success_criteria>
+**Auto mode**:
+- [ ] guidance-specification.md with RFC 2119 keywords, terminology, non-goals, feature decomposition
+- [ ] Role analysis files for each selected role in `.brainstorming/{role}/`
+- [ ] Feature specs in `.brainstorming/feature-specs/` (or synthesis-specification.md)
+- [ ] feature-index.json and synthesis-changelog.md
+- [ ] All user decisions captured with Decision Recording Protocol
+- [ ] Session metadata updated with completion status
+
+**Single role mode**:
+- [ ] analysis.md written to `{output_dir}/{role}/`
+- [ ] Feature-point organization used when feature list available
+- [ ] Framework reference included when guidance-specification.md exists
+- [ ] Session metadata updated
+</success_criteria>

package/.claude/commands/maestro-coordinate.md

@@ -1,65 +1,65 @@
----
-name: maestro-coordinate
-description: CLI-based coordinator - analyze intent → select command chain → execute sequentially via maestro cli with auto-confirm
-argument-hint: "\"intent text\" [-y] [-c] [--dry-run] [--chain <name>] [--tool <tool>]"
-allowed-tools:
-  - Read
-  - Write
-  - Edit
-  - Bash
-  - Glob
-  - Grep
-  - Agent
-  - AskUserQuestion
----
-<purpose>
-Orchestrate maestro commands via external CLI (`maestro cli`) with async state machine.
-Classifies intent, reads project state, selects command chain, then executes each step
-through `maestro cli --tool <tool> --mode write` with a universal prompt template.
-Auto-confirm injection ensures non-blocking background execution. Structured return
-format enables context propagation between steps.
-</purpose>
-
-<required_reading>
-@~/.maestro/workflows/maestro-coordinate.md
-</required_reading>
-
-<deferred_reading>
-- [coordinate template](~/.maestro/templates/cli/prompts/coordinate-step.txt) — read when filling step prompts
-</deferred_reading>
-
-<context>
-$ARGUMENTS — user intent text, or special keywords (`continue`/`next`/`status`).
-
-**Flags:**
-- `-y` / `--yes` — Auto mode: skip clarification and confirmation
-- `-c` / `--continue` — Resume previous session
-- `--dry-run` — Show planned chain without executing
-- `--chain <name>` — Force a specific chain
-- `--tool <tool>` — CLI tool override (default: claude)
-</context>
-
-<execution>
-Follow '~/.maestro/workflows/maestro-coordinate.md' completely.
-</execution>
-
-<error_codes>
-| Code | Severity | Description | Recovery |
-|------|----------|-------------|----------|
-| E001 | error | No intent and project not initialized | Suggest maestro-init |
-| E002 | error | Clarity too low after 2 rounds | Ask to rephrase |
-| E003 | error | Step failed + abort | Suggest resume with -c |
-| E004 | error | Resume session not found | Show available sessions |
-| E005 | error | CLI tool unavailable | Try fallback tool |
-</error_codes>
-
-<success_criteria>
-- [ ] Intent classified and chain selected via detectTaskType + chainMap
-- [ ] Each step executed via `maestro cli` with coordinate-step template
-- [ ] Auto-confirm injected, structured return parsed
-- [ ] Each completed step analyzed via `maestro cli --tool gemini --mode analysis`
-- [ ] Analysis hints injected into next step prompt via `{{ANALYSIS_HINTS}}`
-- [ ] Gemini sessions chained via `--resume` for accumulated context
-- [ ] Session state at .workflow/.maestro-coordinate/{session_id}/
-- [ ] Completion report with per-step status and quality scores
-</success_criteria>
+---
+name: maestro-coordinate
+description: CLI-based coordinator - analyze intent → select command chain → execute sequentially via maestro cli with auto-confirm
+argument-hint: "\"intent text\" [-y] [-c] [--dry-run] [--chain <name>] [--tool <tool>]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+<purpose>
+Orchestrate maestro commands via external CLI (`maestro cli`) with async state machine.
+Classifies intent, reads project state, selects command chain, then executes each step
+through `maestro cli --tool <tool> --mode write` with a universal prompt template.
+Auto-confirm injection ensures non-blocking background execution. Structured return
+format enables context propagation between steps.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/maestro-coordinate.md
+</required_reading>
+
+<deferred_reading>
+- [coordinate template](~/.maestro/templates/cli/prompts/coordinate-step.txt) — read when filling step prompts
+</deferred_reading>
+
+<context>
+$ARGUMENTS — user intent text, or special keywords (`continue`/`next`/`status`).
+
+**Flags:**
+- `-y` / `--yes` — Auto mode: skip clarification and confirmation
+- `-c` / `--continue` — Resume previous session
+- `--dry-run` — Show planned chain without executing
+- `--chain <name>` — Force a specific chain
+- `--tool <tool>` — CLI tool override (default: claude)
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/maestro-coordinate.md' completely.
+</execution>
+
+<error_codes>
+| Code | Severity | Description | Recovery |
+|------|----------|-------------|----------|
+| E001 | error | No intent and project not initialized | Suggest maestro-init |
+| E002 | error | Clarity too low after 2 rounds | Ask to rephrase |
+| E003 | error | Step failed + abort | Suggest resume with -c |
+| E004 | error | Resume session not found | Show available sessions |
+| E005 | error | CLI tool unavailable | Try fallback tool |
+</error_codes>
+
+<success_criteria>
+- [ ] Intent classified and chain selected via detectTaskType + chainMap
+- [ ] Each step executed via `maestro cli` with coordinate-step template
+- [ ] Auto-confirm injected, structured return parsed
+- [ ] Each completed step analyzed via `maestro cli --tool gemini --mode analysis`
+- [ ] Analysis hints injected into next step prompt via `{{ANALYSIS_HINTS}}`
+- [ ] Gemini sessions chained via `--resume` for accumulated context
+- [ ] Session state at .workflow/.maestro-coordinate/{session_id}/
+- [ ] Completion report with per-step status and quality scores
+</success_criteria>

package/.claude/commands/maestro-execute.md

@@ -1,86 +1,96 @@
----
-name: maestro-execute
-description: Execute phase plan with wave-based parallel execution and atomic commits
-argument-hint: "<phase> [--auto-commit] [--method agent|cli] [--dir <path>]"
-allowed-tools:
-  - Read
-  - Write
-  - Edit
-  - Bash
-  - Glob
-  - Grep
-  - Agent
-  - AskUserQuestion
----
-<purpose>
-Execute all tasks in a phase plan using wave-based parallel execution with dependency-aware ordering. Invoked after Skill({ skill: "maestro-plan" }) produces a confirmed plan.json. Produces task summaries, updated task statuses, commits, and execution progress in index.json.
-</purpose>
-
-<required_reading>
-@~/.maestro/workflows/execute.md
-</required_reading>
-
-<deferred_reading>
-- [task.json](~/.maestro/templates/task.json) — read when reading task definitions
-- [index.json](~/.maestro/templates/index.json) — read when updating phase index
-</deferred_reading>
-
-<context>
-Phase: $ARGUMENTS (required -- phase number or slug)
-
-**Flags:**
-- `--auto-commit` -- Automatically commit after each task completion
-- `--method agent|cli` -- Override execution method (default: from config.json or index.json)
-- `--dir <path>` -- Use arbitrary directory instead of phase resolution (scratch mode, skip roadmap validation)
-
-Context files resolved from `.workflow/phases/{NN}-{slug}/` (or `--dir` path):
-- index.json (phase metadata + plan.waves + execution progress)
-- plan.json (plan overview)
-- .task/TASK-{NNN}.json (individual task definitions, lazy-loaded per wave)
-
-**executionContext handoff:** If received from Skill({ skill: "maestro-plan" }) confirmation, skip disk reload and use in-memory plan + explorations + clarifications.
-</context>
-
-<execution>
-Follow '~/.maestro/workflows/execute.md' completely.
-
-**Report format on completion:**
-
-```
-=== EXECUTION COMPLETE ===
-Phase:     {phase_name}
-Completed: {completed_count}/{total_count} tasks
-Failed:    {failed_count} tasks
-Waves:     {waves_executed}/{total_waves}
-
-Summaries: {phase_dir}/.summaries/
-Tasks:     {phase_dir}/.task/
-
-Next steps:
-  Skill({ skill: "maestro-verify", args: "{phase}" })  -- Verify execution results
-  Skill({ skill: "manage-status" })          -- View project dashboard
-```
-
-If this was a gap-fix execution (plan originated from `--gaps`), emphasize re-verification:
-  "Gap-fix execution complete. Run Skill({ skill: "maestro-verify", args: "{phase}" }) to confirm gaps are resolved."
-
-If failed tasks exist, suggest Skill({ skill: "quality-debug" }) for investigation.
-</execution>
-
-<error_codes>
-| Code | Severity | Condition | Recovery |
-|------|----------|-----------|----------|
-| E001 | error | Phase argument required | Check arguments format, re-run with correct input |
-| E002 | error | Phase directory not found | Check arguments format, re-run with correct input |
-| E003 | error | plan.json not found in phase directory | Verify plan.json exists, run maestro-plan first |
-| E004 | error | No pending tasks, all tasks already completed | Check task statuses, reset if needed |
-| W001 | warning | Executor completed with partial failures | Check task dependencies, retry failed wave |
-</error_codes>
-
-<success_criteria>
-- [ ] All pending tasks executed (completed or explicitly failed)
-- [ ] `.summaries/TASK-{NNN}-summary.md` written for each completed task
-- [ ] `.task/TASK-{NNN}.json` statuses updated
-- [ ] index.json execution progress updated
-- [ ] state.json project progress updated
-</success_criteria>
+---
+name: maestro-execute
+description: Execute phase plan with wave-based parallel execution and atomic commits
+argument-hint: "<phase> [--auto-commit] [--method agent|cli] [--dir <path>]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+<purpose>
+Execute all tasks in a phase plan using wave-based parallel execution with dependency-aware ordering. Invoked after Skill({ skill: "maestro-plan" }) produces a confirmed plan.json. Produces task summaries, updated task statuses, commits, and execution progress in index.json.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/execute.md
+</required_reading>
+
+<deferred_reading>
+- [task.json](~/.maestro/templates/task.json) — read when reading task definitions
+- [index.json](~/.maestro/templates/index.json) — read when updating phase index
+</deferred_reading>
+
+<context>
+Phase: $ARGUMENTS (required -- phase number or slug)
+
+**Flags:**
+- `--auto-commit` -- Automatically commit after each task completion
+- `--method agent|cli` -- Override execution method (default: from config.json or index.json)
+- `--dir <path>` -- Use arbitrary directory instead of phase resolution (scratch mode, skip roadmap validation)
+
+Context files resolved from `.workflow/phases/{NN}-{slug}/` (or `--dir` path):
+- index.json (phase metadata + plan.waves + execution progress)
+- plan.json (plan overview)
+- .task/TASK-{NNN}.json (individual task definitions, lazy-loaded per wave)
+
+**executionContext handoff:** If received from Skill({ skill: "maestro-plan" }) confirmation, skip disk reload and use in-memory plan + explorations + clarifications.
+</context>
+
+<execution>
+### Pre-flight: team conflict check
+
+Before any task execution, run:
+```
+Bash("maestro team preflight --phase <phase-number>")
+```
+If exit code is 1, the command prints warnings about teammates active on the same phase. Present the warnings to the user and ask whether to proceed. If the user confirms or says "force", continue. If they decline, abort with a clear message.
+
+If exit code is 0, or `maestro team preflight` is unavailable (e.g., team mode not enabled), continue normally.
+
+Follow '~/.maestro/workflows/execute.md' completely.
+
+**Report format on completion:**
+
+```
+=== EXECUTION COMPLETE ===
+Phase:     {phase_name}
+Completed: {completed_count}/{total_count} tasks
+Failed:    {failed_count} tasks
+Waves:     {waves_executed}/{total_waves}
+
+Summaries: {phase_dir}/.summaries/
+Tasks:     {phase_dir}/.task/
+
+Next steps:
+  Skill({ skill: "maestro-verify", args: "{phase}" })  -- Verify execution results
+  Skill({ skill: "manage-status" })          -- View project dashboard
+```
+
+If this was a gap-fix execution (plan originated from `--gaps`), emphasize re-verification:
+  "Gap-fix execution complete. Run Skill({ skill: "maestro-verify", args: "{phase}" }) to confirm gaps are resolved."
+
+If failed tasks exist, suggest Skill({ skill: "quality-debug" }) for investigation.
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | Phase argument required | Check arguments format, re-run with correct input |
+| E002 | error | Phase directory not found | Check arguments format, re-run with correct input |
+| E003 | error | plan.json not found in phase directory | Verify plan.json exists, run maestro-plan first |
+| E004 | error | No pending tasks, all tasks already completed | Check task statuses, reset if needed |
+| W001 | warning | Executor completed with partial failures | Check task dependencies, retry failed wave |
+</error_codes>
+
+<success_criteria>
+- [ ] All pending tasks executed (completed or explicitly failed)
+- [ ] `.summaries/TASK-{NNN}-summary.md` written for each completed task
+- [ ] `.task/TASK-{NNN}.json` statuses updated
+- [ ] index.json execution progress updated
+- [ ] state.json project progress updated
+</success_criteria>