maestro-flow 0.3.38 → 0.3.39

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

@@ -1,114 +1,120 @@
----
-name: maestro-execute
-description: Execute plan with wave-based parallel execution and atomic commits
-argument-hint: "[phase] [--auto-commit] [--method agent|cli|auto] [--executor <tool>] [--dir <path>] [-y]"
-allowed-tools:
-  - Read
-  - Write
-  - Edit
-  - Bash
-  - Glob
-  - Grep
-  - Agent
-  - AskUserQuestion
----
-<purpose>
-Execute all tasks in a plan using wave-based parallel execution with dependency-aware ordering. Each plan is executed independently (plans串行, plan内wave并行). Task summaries are written to the plan's scratch directory under `.summaries/`. Registers EXC artifact in state.json.
-
-Invoked after /maestro-plan produces a confirmed plan. When called without args on a milestone, finds all pending plans and executes them sequentially.
-</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 — phase number, or no args for milestone-wide execution, with optional flags.
-
-Scope routing, flags, resolution logic, output directory format, artifact registration schema, and incremental learning extraction are defined in workflow `execute.md`.
-</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.
-
-### Post-task Knowledge Inquiry
-
-After each task completes, evaluate inquiry triggers:
-
-1. **Execution deviation**: If task summary mentions approach change, dependency swap, or plan deviation:
-   → Ask: "TASK-{NNN} deviated from the plan. Should this decision be recorded as an architecture constraint? (`/spec-add arch`)"
-
-2. **Retry success**: If task required ≥2 retries before completion:
-   → Ask: "TASK-{NNN} succeeded after {N} retries. Should this fix pattern be documented? (`/spec-add debug`)"
-
-3. **Implicit knowledge**: If task summary contains design rationale ("chose X because", "rejected Y due to"):
-   → Ask: "Design decision detected. Should it be recorded as a learning? (`/spec-add learning`)"
-
-If user confirms, invoke `Skill({ skill: "spec-add", args: "<category> <content>" })` with extracted content.
-
-### Issue Status Sync
-
-On each task completion, if `task.issue_id` exists, sync status back to the issue in `.workflow/issues/issues.jsonl`:
-
-```
-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 → issue.status = "resolved"
-    any task_ref failed    → issue.status = "in_progress"
-  Append history entry: { action: "executed", at: <ISO>, by: "maestro-execute", summary: "TASK-{NNN} {status}" }
-  Write updated issue back to issues.jsonl
-```
-
-**Report format on completion:**
-
-```
-=== EXECUTION COMPLETE ===
-Plans executed: {plans_count}
-Completed: {completed_count}/{total_count} tasks
-Failed:    {failed_count} tasks
-
-Summaries: {plan_dir}/.summaries/
-Tasks:     {plan_dir}/.task/
-
-Next steps:
-  /maestro-verify              -- Verify execution results
-  /maestro-verify --dir {dir}  -- Verify specific plan
-  /manage-status               -- View project dashboard
-```
-
-If failed tasks exist, suggest /quality-debug for investigation.
-</execution>
-
-<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 |
-| W001 | warning | Executor completed with partial failures | Check task dependencies, retry failed wave |
-</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 learnings extracted to specs/learnings.md
-- [ ] state.json updated with execution progress
-</success_criteria>
+---
+name: maestro-execute
+description: Execute plan with parallel waves and atomic commits
+argument-hint: "[phase] [--auto-commit] [--method agent|cli|auto] [--executor <tool>] [--dir <path>] [-y]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+<purpose>
+Execute all tasks in a plan using wave-based parallel execution with dependency-aware ordering. Each plan is executed independently (plans串行, plan内wave并行). Task summaries are written to the plan's scratch directory under `.summaries/`. Registers EXC artifact in state.json.
+
+Invoked after /maestro-plan produces a confirmed plan. When called without args on a milestone, finds all pending plans and executes them sequentially.
+</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 — phase number, or no args for milestone-wide execution, with optional flags.
+
+Scope routing, flags, resolution logic, output directory format, artifact registration schema, and incremental learning 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 wiki search "<phase keywords>" --json 2>/dev/null`. If results found, extract top 5 entries as prior knowledge context for agents.
+3. Both are optional — proceed without if unavailable (log warning).
+</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.
+
+### Post-task Knowledge Inquiry
+
+After each task completes, evaluate inquiry triggers:
+
+1. **Execution deviation**: If task summary mentions approach change, dependency swap, or plan deviation:
+   → Ask: "TASK-{NNN} deviated from the plan. Should this decision be recorded as an architecture constraint? (`/spec-add arch`)"
+
+2. **Retry success**: If task required ≥2 retries before completion:
+   → Ask: "TASK-{NNN} succeeded after {N} retries. Should this fix pattern be documented? (`/spec-add debug`)"
+
+3. **Implicit knowledge**: If task summary contains design rationale ("chose X because", "rejected Y due to"):
+   → Ask: "Design decision detected. Should it be recorded as a learning? (`/spec-add learning`)"
+
+If user confirms, invoke `Skill({ skill: "spec-add", args: "<category> <content>" })` with extracted content.
+
+### Issue Status Sync
+
+On each task completion, if `task.issue_id` exists, sync status back to the issue in `.workflow/issues/issues.jsonl`:
+
+```
+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 → issue.status = "resolved"
+    any task_ref failed    → issue.status = "in_progress"
+  Append history entry: { action: "executed", at: <ISO>, by: "maestro-execute", summary: "TASK-{NNN} {status}" }
+  Write updated issue back to issues.jsonl
+```
+
+**Report format on completion:**
+
+```
+=== EXECUTION COMPLETE ===
+Plans executed: {plans_count}
+Completed: {completed_count}/{total_count} tasks
+Failed:    {failed_count} tasks
+
+Summaries: {plan_dir}/.summaries/
+Tasks:     {plan_dir}/.task/
+
+Next steps:
+  /maestro-verify              -- Verify execution results
+  /maestro-verify --dir {dir}  -- Verify specific plan
+  /manage-status               -- View project dashboard
+```
+
+If failed tasks exist, suggest /quality-debug for investigation.
+</execution>
+
+<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 |
+| W001 | warning | Executor completed with partial failures | Check task dependencies, retry failed wave |
+</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 learnings extracted to specs/learnings.md
+- [ ] state.json updated with execution progress
+</success_criteria>

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

@@ -1,86 +1,86 @@
----
-name: maestro-fork
-description: Create a worktree for milestone-level parallel development, or sync existing worktree with main
-argument-hint: "-m <milestone-number> [--base <branch>] [--sync]"
-allowed-tools:
-  - Read
-  - Write
-  - Edit
-  - Bash
-  - Glob
-  - Grep
-  - Agent
-  - AskUserQuestion
----
-<purpose>
-Create a git worktree for an entire milestone, enabling inter-milestone parallel development. The worktree scope is milestone-level — all scratch artifacts for that milestone are owned by the worktree.
-
-Since `.workflow/` is gitignored, this command explicitly copies project context and existing milestone scratch artifacts into the worktree. Per-phase parallelism within a milestone is NOT supported.
-
-Also supports `--sync` mode to pull latest main branch changes and shared artifacts into an active worktree (prevents source and artifact drift for long-lived worktrees).
-
-Produces `.workflow/worktrees.json` registry in the main worktree and `.workflow/worktree-scope.json` marker in the 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`.
-
-**Next-step routing on completion:**
-
-Fork mode:
-- Enter worktree → `cd {wt.path} && /maestro-analyze`
-- Automated → `maestro delegate "run full lifecycle for milestone" --cd {wt.path} --mode write`
-- Status → Skill({ skill: "manage-status" })
-
-Sync mode:
-- Sync complete → resume work in worktree
-- Conflicts found → resolve manually, then retry
-</execution>
-
-<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>
+---
+name: maestro-fork
+description: Create or sync milestone worktree for parallel dev
+argument-hint: "-m <milestone-number> [--base <branch>] [--sync]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+<purpose>
+Create a git worktree for an entire milestone, enabling inter-milestone parallel development. The worktree scope is milestone-level — all scratch artifacts for that milestone are owned by the worktree.
+
+Since `.workflow/` is gitignored, this command explicitly copies project context and existing milestone scratch artifacts into the worktree. Per-phase parallelism within a milestone is NOT supported.
+
+Also supports `--sync` mode to pull latest main branch changes and shared artifacts into an active worktree (prevents source and artifact drift for long-lived worktrees).
+
+Produces `.workflow/worktrees.json` registry in the main worktree and `.workflow/worktree-scope.json` marker in the 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`.
+
+**Next-step routing on completion:**
+
+Fork mode:
+- Enter worktree → `cd {wt.path} && /maestro-analyze`
+- Automated → `maestro delegate "run full lifecycle for milestone" --cd {wt.path} --mode write`
+- Status → Skill({ skill: "manage-status" })
+
+Sync mode:
+- Sync complete → resume work in worktree
+- Conflicts found → resolve manually, then retry
+</execution>
+
+<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/.claude/commands/maestro-init.md

@@ -1,78 +1,78 @@
----
-name: maestro-init
-description: Initialize project with auto state detection (empty/code/existing)
-argument-hint: "[-y] [--from-brainstorm SESSION-ID]"
-allowed-tools:
-  - Read
-  - Write
-  - Bash
-  - Glob
-  - Grep
-  - Agent
-  - AskUserQuestion
----
-<purpose>
-Initialize a new project through auto state detection and unified flow. Invoked when starting a fresh project or onboarding an existing codebase into workflow management. Produces the `.workflow/` directory structure with project.md, state.json, config.json, and specs. Does NOT create roadmap — use maestro-roadmap (light mode, default) or maestro-roadmap --mode full (spec package) as the next step.
-</purpose>
-
-<required_reading>
-@~/.maestro/workflows/init.md
-@~/.maestro/templates/project.md
-@~/.maestro/templates/state.json
-@~/.maestro/templates/config.json
-</required_reading>
-
-<context>
-**Flags:**
-- `-y` -- Automatic mode. After config questions, runs research without further interaction. Expects idea document via @ reference.
-- `--from-brainstorm SESSION-ID` -- Import from a brainstorm session. Reads guidance-specification.md to pre-fill project vision, goals, constraints, and terminology. Skips interactive questioning.
-
-**Load project state if exists:**
-Check for `.workflow/state.json` -- loads context if project already initialized.
-</context>
-
-<execution>
-Follow '~/.maestro/workflows/init.md' completely.
-
-**Report format on completion:**
-
-```
-=== WORKFLOW INITIALIZED ===
-Project: {project_name}
-State:   .workflow/state.json (active)
-
-Created:
-  .workflow/project.md
-  .workflow/state.json
-  .workflow/config.json
-  .workflow/specs/
-
-Next steps (choose one path to create roadmap):
-  /maestro-roadmap <requirement>                               -- Direct interactive roadmap (light, default)
-  /maestro-roadmap --mode full <idea>                          -- Full spec package + roadmap (heavy)
-
-Other commands:
-  /manage-status                                               -- View project dashboard
-  /maestro-brainstorm <topic>                                  -- Explore ideas first
-  /maestro-quick <task>                                        -- Quick ad-hoc task
-```
-</execution>
-
-<error_codes>
-| Code | Severity | Condition | Recovery |
-|------|----------|-----------|----------|
-| E001 | error | No arguments provided when -y requires @ reference | Check arguments format, re-run with correct input |
-| E002 | error | .workflow/ already exists for greenfield init | Check .workflow/ directory state, resolve conflicts |
-| E003 | error | Brainstorm session not found (--from-brainstorm) | Check arguments format, re-run with correct input |
-| W001 | warning | Research agent failed, continuing with partial results | Retry research or proceed with partial results |
-</error_codes>
-
-<success_criteria>
-- [ ] Deep questioning completed (threads followed, not rushed) — or extracted from document/brainstorm
-- [ ] `.workflow/project.md` created with Core Value, Requirements (Validated/Active/Out of Scope), Key Decisions
-- [ ] `.workflow/state.json` created with artifacts[] array, initialized to idle state
-- [ ] `.workflow/config.json` created with user-selected granularity, workflow agents, gate preferences
-- [ ] `.workflow/specs/` initialized with convention files
-- [ ] Research completed (if enabled) — 4 parallel agents spawned
-- [ ] User knows next step is `/maestro-roadmap` (light) or `/maestro-roadmap --mode full` (spec package)
-</success_criteria>
+---
+name: maestro-init
+description: Initialize project with auto state detection
+argument-hint: "[-y] [--from-brainstorm SESSION-ID]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+  - AskUserQuestion
+---
+<purpose>
+Initialize a new project through auto state detection and unified flow. Invoked when starting a fresh project or onboarding an existing codebase into workflow management. Produces the `.workflow/` directory structure with project.md, state.json, config.json, and specs. Does NOT create roadmap — use maestro-roadmap (light mode, default) or maestro-roadmap --mode full (spec package) as the next step.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/init.md
+@~/.maestro/templates/project.md
+@~/.maestro/templates/state.json
+@~/.maestro/templates/config.json
+</required_reading>
+
+<context>
+**Flags:**
+- `-y` -- Automatic mode. After config questions, runs research without further interaction. Expects idea document via @ reference.
+- `--from-brainstorm SESSION-ID` -- Import from a brainstorm session. Reads guidance-specification.md to pre-fill project vision, goals, constraints, and terminology. Skips interactive questioning.
+
+**Load project state if exists:**
+Check for `.workflow/state.json` -- loads context if project already initialized.
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/init.md' completely.
+
+**Report format on completion:**
+
+```
+=== WORKFLOW INITIALIZED ===
+Project: {project_name}
+State:   .workflow/state.json (active)
+
+Created:
+  .workflow/project.md
+  .workflow/state.json
+  .workflow/config.json
+  .workflow/specs/
+
+Next steps (choose one path to create roadmap):
+  /maestro-roadmap <requirement>                               -- Direct interactive roadmap (light, default)
+  /maestro-roadmap --mode full <idea>                          -- Full spec package + roadmap (heavy)
+
+Other commands:
+  /manage-status                                               -- View project dashboard
+  /maestro-brainstorm <topic>                                  -- Explore ideas first
+  /maestro-quick <task>                                        -- Quick ad-hoc task
+```
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | No arguments provided when -y requires @ reference | Check arguments format, re-run with correct input |
+| E002 | error | .workflow/ already exists for greenfield init | Check .workflow/ directory state, resolve conflicts |
+| E003 | error | Brainstorm session not found (--from-brainstorm) | Check arguments format, re-run with correct input |
+| W001 | warning | Research agent failed, continuing with partial results | Retry research or proceed with partial results |
+</error_codes>
+
+<success_criteria>
+- [ ] Deep questioning completed (threads followed, not rushed) — or extracted from document/brainstorm
+- [ ] `.workflow/project.md` created with Core Value, Requirements (Validated/Active/Out of Scope), Key Decisions
+- [ ] `.workflow/state.json` created with artifacts[] array, initialized to idle state
+- [ ] `.workflow/config.json` created with user-selected granularity, workflow agents, gate preferences
+- [ ] `.workflow/specs/` initialized with convention files
+- [ ] Research completed (if enabled) — 4 parallel agents spawned
+- [ ] User knows next step is `/maestro-roadmap` (light) or `/maestro-roadmap --mode full` (spec package)
+</success_criteria>