maestro-flow 0.3.7 → 0.3.9

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

@@ -1,96 +1,137 @@
----
-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>
+---
+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>]"
+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.
+
+**Flags:**
+- `--auto-commit` -- Automatically commit after each task completion
+- `--method agent|cli|auto` -- Override execution method (default: from config.json)
+- `--executor <tool>` -- Default CLI tool: gemini|codex|qwen|opencode|claude
+- `--dir <path>` -- Execute specific plan directory (e.g., `scratch/plan-auth-2026-04-20`)
+
+**Scope routing:**
+
+| Invocation | Behavior |
+|-----------|----------|
+| `execute` (no args) | Find all pending plans for current milestone, execute sequentially |
+| `execute 1` | Find pending plans for phase 1, execute sequentially |
+| `execute --dir scratch/plan-xxx` | Execute the specific plan |
+
+**Resolution logic (no-args / phase):**
+```
+1. Read state.json.artifacts
+2. Filter: milestone=target, type=plan, status=completed, AND no corresponding EXC artifact
+3. If phase specified: further filter by phase=target
+4. Sort by phase dependency order (roadmap phase order), adhoc last
+5. Execute each plan sequentially
+```
+
+**Output**: Task summaries written to plan's scratch dir:
+```
+scratch/plan-{slug}-{date}/
+├── plan.json
+├── .task/
+│   ├── TASK-001.json    # status updated to completed|blocked
+│   └── TASK-002.json
+└── .summaries/          ← execute writes here
+    ├── TASK-001-summary.md
+    └── TASK-002-summary.md
+```
+
+**Incremental learning extraction**: After each plan completes, extract strategy adjustments / patterns / pitfalls from `.summaries/` and append to `specs/learnings.md`. Mark artifact `harvested: true`.
+
+**Artifact registration**: For each plan executed, register in `state.json.artifacts[]`:
+```jsonc
+{
+  "id": "EXC-{NNN}",
+  "type": "execute",
+  "milestone": "{current_milestone or null}",
+  "phase": "{phase or null}",
+  "scope": "{inherited from plan}",
+  "path": "{same as plan path}",
+  "status": "completed",
+  "depends_on": "PLN-{NNN}",
+  "harvested": false,
+  "created_at": "...",
+  "completed_at": "..."
+}
+```
+</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.
+
+**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

@@ -0,0 +1,111 @@
+---
+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. All phases within the milestone are owned by the worktree and executed sequentially inside it.
+
+Since `.workflow/` is gitignored, this command explicitly copies project context and all milestone phase directories 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 name and optional flags.
+
+**Modes:**
+
+| Mode | Trigger | Behavior |
+|------|---------|----------|
+| Fork | `-m 2` or `2` | Create worktree for all phases in milestone 2 |
+| Sync | `-m 2 --sync` | Sync existing milestone 2 worktree with main branch |
+
+**Flags:**
+- `-m <N>` or bare `<N>`: Milestone number (1-based, maps to `state.json.milestones[]`)
+- `--base <branch>`: Override base branch for worktree creation (default: HEAD)
+- `--sync`: Sync mode — pull main into existing worktree, re-copy shared artifacts
+
+**Milestone resolution:** `state.json.milestones[N-1]` → `{name, title, phases: [...]}`
+
+**Worktree layout:**
+```
+.worktrees/m{N}-{slug}/
+├── .workflow/
+│   ├── worktree-scope.json     (scope marker — lists all owned phases)
+│   ├── state.json              (scoped to this milestone)
+│   ├── project.md              (read-only copy)
+│   ├── roadmap.md              (read-only copy)
+│   ├── config.json             (read-only copy)
+│   ├── specs/                  (read-only copy)
+│   └── phases/
+│       ├── {NN}-{slug}/        (owned — all phases in milestone)
+│       └── {dep}-{dep-slug}/   (read-only dependency reference from prior milestones)
+└── <source code>               (git worktree checkout)
+```
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/fork.md' completely.
+
+**Next-step routing on completion:**
+
+Fork mode:
+- Enter worktree → `cd {wt.path} && /maestro-analyze {first_phase}`
+- 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 phases identified from roadmap
+- [ ] Git worktree created with branch (`milestone/{slug}`)
+- [ ] `.workflow/` context copied into worktree (all milestone phases + dependency phases)
+- [ ] `worktree-scope.json` written with all owned phase numbers
+- [ ] Scoped `state.json` written (current_phase = first pending phase)
+- [ ] `worktrees.json` registry updated in main worktree
+- [ ] Milestone phase indexes marked as "forked" in main worktree
+- [ ] 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

@@ -48,13 +48,13 @@ Created:
   .workflow/specs/
 
 Next steps (choose one path to create roadmap):
-  Skill({ skill: "maestro-spec-generate", args: "<idea>" })   -- Full spec package + roadmap (heavy)
-  Skill({ skill: "maestro-roadmap", args: "<requirement>" })   -- Direct interactive roadmap (light)
+  /maestro-spec-generate <idea>                                -- Full spec package + roadmap (heavy)
+  /maestro-roadmap <requirement>                               -- Direct interactive roadmap (light)
 
 Other commands:
-  Skill({ skill: "manage-status" })                            -- View project dashboard
-  Skill({ skill: "maestro-brainstorm", args: "<topic>" })     -- Explore ideas first
-  Skill({ skill: "maestro-quick", args: "<task>" })           -- Quick ad-hoc task
+  /manage-status                                               -- View project dashboard
+  /maestro-brainstorm <topic>                                  -- Explore ideas first
+  /maestro-quick <task>                                        -- Quick ad-hoc task
 ```
 </execution>
 
@@ -70,7 +70,7 @@ Other commands:
 <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 and initialized to idle state
+- [ ] `.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