maestro-flow 0.5.3 → 0.5.31

package/.agy/skills/maestro-execute/SKILL.md

@@ -14,173 +14,172 @@ allowed-tools:
   - view_file
   - write_to_file
 ---
-<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.
-
-Pipeline position: upstream from maestro-plan (consumes confirmed plan). Verification is built-in (E2.7).
-</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
-
-| Flag | Effect | Default |
-|------|--------|---------|
-| `--auto-commit` | Auto-commit after each completed task | false |
-| `--method agent\|cli\|auto` | Execution method: Agent tool, CLI delegate, or auto-select | `auto` |
-| `--executor <tool>` | Explicit executor tool for CLI delegate mode | First enabled in config |
-| `--dir <path>` | Execute a specific plan directory instead of auto-discovery | — |
-| `-y` / `--yes` | Auto mode — skip interactive questions | false |
-
-### Scope routing
-
-| Input | Scope | Resolution |
-|-------|-------|------------|
-| numeric arg | phase | Resolve plan from roadmap phase |
-| `--dir <path>` | explicit | Use specified plan directory |
-| no args + milestone | milestone | Find all pending plans, execute sequentially |
-| no args + no milestone | error E001 | No plan found |
-
-Full resolution logic, output directory format, artifact registration schema, and incremental knowhow extraction are defined in workflow `execute.md`.
-
-### Pre-load context (before task execution)
-
-1. **Codebase docs**: If `.workflow/codebase/doc-index.json` exists, read `ARCHITECTURE.md` for module boundaries. Pass as shared context to executor agents.
-2. **Wiki knowledge**: Run `maestro search "<phase keywords>" --json 2>/dev/null`. If results found, extract top 5 entries as prior knowledge context for agents.
-3. **Coding specs + tools**: Run `maestro spec load --category coding` to load coding conventions AND discoverable knowhow tools (tool: true entries). Pass as specs context to all executor agents.
-4. **UI specs (conditional)**: If any task involves frontend/UI work (task scope/description contains keywords like component, page, style, layout, CSS, HTML, frontend; or focus_paths in `src/components/`, `src/pages/`, `src/styles/`, `src/ui/`), also run `maestro spec load --category ui` and include in agent context.
-5. All are optional — proceed without if unavailable (log warning).
-
-### Role Knowledge
-`maestro search --category coding` → select relevant → `maestro wiki load`
-</context>
-
-<execution>
-### Pre-flight: team conflict check
-
-Before any task execution, run:
-```
-run_command("maestro collab preflight --phase <phase-number>")
-```
-If exit code is 1, present warnings and ask whether to proceed.
-
-Follow '~/.maestro/workflows/execute.md' completely.
-
-### Phase Gates (MANDATORY, BLOCKING)
-
-**GATE 1: Plan Load → Task Execution**
-- REQUIRED: plan.json found and parsed with valid task definitions.
-- REQUIRED: `.task/TASK-*.json` files exist for all tasks in plan.
-- BLOCKED if no pending tasks: error E004.
-
-**GATE 2: Per-Task Execution → Summary**
-- REQUIRED: Each completed task has `.summaries/TASK-{NNN}-summary.md` written with concrete evidence (files changed, tests run, verification results).
-- REQUIRED: `.task/TASK-{NNN}.json` status updated to completed|blocked.
-- Do NOT silently skip failed tasks — mark as blocked with reason.
-
-**GATE 3: All Tasks → Completion**
-- REQUIRED: All waves executed in dependency order.
-- REQUIRED: EXC artifact registered in state.json.
-
-### Evidence Requirement
-
-Task summaries MUST include:
-- Files actually modified (not just planned targets)
-- Convergence criteria verification results (pass/fail with evidence)
-- Any deviations from the plan with rationale
-
-### Post-task Knowledge Inquiry
-
-After each task completion, check triggers:
-
-| Condition | Ask | Route |
-|-----------|-----|-------|
-| Summary mentions approach change / plan deviation | "Record as arch constraint?" | spec-add arch |
-| retry_count >= 2 | "Document fix pattern?" | spec-add debug |
-| Summary contains design rationale ("chose X because") | "Record as knowhow?" | spec-add learning |
-
-On confirm → `Skill("spec-add", "<category> <content> --description \"<summary>\"")`.
-Include `--description` with a one-line summary for search result display.
-
-### Issue Status Sync
-
-On each task completion, if `task.issue_id` exists, sync status back to the issue in `.workflow/issues/issues.jsonl`:
-
-```
-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
-```
-
-</execution>
-
-<completion>
-### Standalone report
-
-```
-=== EXECUTION COMPLETE ===
-Plans executed: {plans_count}
-Completed: {completed_count}/{total_count} tasks
-Failed:    {failed_count} tasks
-
-Summaries: {plan_dir}/.summaries/
-Tasks:     {plan_dir}/.task/
-```
-
-### Ralph-invoked completion
-
-End the step by calling the CLI (no text block output):
-```
-maestro ralph complete <idx> --status {STATUS} [--evidence {path}]
-```
-
-Status verdicts:
-- **DONE** — Normal completion
-- **DONE_WITH_CONCERNS** — Completed with caveats; pass `--concerns`
-- **NEEDS_RETRY** — Tooling error / transient issue; ralph will retry
-- **BLOCKED** — External hard blocker; pass `--reason`
-
-### Next-step routing
-
-| Condition | Suggestion |
-|-----------|-----------|
-| All tasks completed successfully | `/quality-review` |
-| Failed tasks exist | `/quality-debug` |
-| View project dashboard | `/manage-status` |
-</completion>
-
-<error_codes>
-| Code | Severity | Condition | Recovery |
-|------|----------|-----------|----------|
-| E001 | error | No pending plans found | Verify plans exist, run maestro-plan first |
-| E002 | error | Plan directory not found | Check --dir path |
-| E003 | error | plan.json not found in directory | Verify plan.json exists, run maestro-plan first |
-| E004 | error | No pending tasks, all tasks already completed | Check task statuses, reset if needed |
-| 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 knowhow extracted to specs/learnings.md
-- [ ] state.json updated with execution progress
-</success_criteria>
+<purpose>
+Execute confirmed plan tasks via wave-based parallel dispatch.
+Consumes plan from maestro-plan; registers EXC artifact in state.json.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/execute.md
+</required_reading>
+
+<deferred_reading>
+- [task.json](~/.maestro/templates/task.json) — read when reading task definitions
+- [state.json](~/.maestro/templates/state.json) — read when registering artifact
+</deferred_reading>
+
+<context>
+$ARGUMENTS — phase number, or no args for milestone-wide execution, with optional flags.
+
+### Flags
+
+| Flag | Effect | Default |
+|------|--------|---------|
+| `--auto-commit` | Auto-commit after each completed task | false |
+| `--method agent\|cli\|auto` | Execution method: Agent tool, CLI delegate, or auto-select | `auto` |
+| `--executor <tool>` | Explicit executor tool for CLI delegate mode | First enabled in config |
+| `--dir <path>` | Execute a specific plan directory instead of auto-discovery | — |
+| `-y` / `--yes` | Auto mode — skip interactive questions | false |
+
+### Scope routing
+
+| Input | Scope | Resolution |
+|-------|-------|------------|
+| numeric arg | phase | Resolve plan from roadmap phase |
+| `--dir <path>` | explicit | Use specified plan directory |
+| no args + milestone | milestone | Find all pending plans, execute sequentially |
+| no args + no milestone | error E001 | No plan found |
+
+Full resolution logic, output directory format, artifact registration schema, and incremental knowhow extraction are defined in workflow `execute.md`.
+
+### Pre-load context (before task execution)
+
+1. **Codebase docs**: If `.workflow/codebase/doc-index.json` exists, read `ARCHITECTURE.md` for module boundaries. Pass as shared context to executor agents.
+2. **Wiki knowledge**: Run `maestro search "<phase keywords>" --json 2>/dev/null`. If results found, extract top 5 entries as prior knowledge context for agents.
+3. **Coding specs + tools**: Run `maestro spec load --category coding` to load coding conventions AND discoverable knowhow tools (tool: true entries). Pass as specs context to all executor agents.
+4. **UI specs (conditional)**: If any task involves frontend/UI work (task scope/description contains keywords like component, page, style, layout, CSS, HTML, frontend; or focus_paths in `src/components/`, `src/pages/`, `src/styles/`, `src/ui/`), also run `maestro spec load --category ui` and include in agent context.
+5. All are optional — proceed without if unavailable (log warning).
+
+### Role Knowledge
+`maestro search --category coding` → select relevant → `maestro wiki load`
+</context>
+
+<execution>
+### Pre-flight: team conflict check
+
+Before any task execution, run:
+```
+run_command("maestro collab preflight --phase <phase-number>")
+```
+If exit code is 1, present warnings and ask whether to proceed.
+
+Follow '~/.maestro/workflows/execute.md' completely.
+
+### Phase Gates (MANDATORY, BLOCKING)
+
+**GATE 1: Plan Load → Task Execution**
+- REQUIRED: plan.json found and parsed with valid task definitions.
+- REQUIRED: `.task/TASK-*.json` files exist for all tasks in plan.
+- BLOCKED if no pending tasks: error E004.
+
+**GATE 2: Per-Task Execution → Summary**
+- REQUIRED: Each completed task has `.summaries/TASK-{NNN}-summary.md` written with concrete evidence (files changed, tests run, verification results).
+- REQUIRED: `.task/TASK-{NNN}.json` status updated to completed|blocked.
+- BLOCKED if missing: summary file absent or task status not updated — halt wave progression until evidence is recorded.
+- Do NOT silently skip failed tasks — mark as blocked with reason.
+
+**GATE 3: All Tasks → Completion**
+- REQUIRED: All waves executed in dependency order.
+- REQUIRED: EXC artifact registered in state.json.
+- BLOCKED if missing: waves incomplete or EXC artifact not registered — do not report execution complete.
+
+### Evidence Requirement
+
+Task summaries MUST include:
+- Files actually modified (not just planned targets)
+- Convergence criteria verification results (pass/fail with evidence)
+- Any deviations from the plan with rationale
+
+### Post-task Knowledge Inquiry
+
+After each task completion, check triggers:
+
+| Condition | Ask | Route |
+|-----------|-----|-------|
+| Summary mentions approach change / plan deviation | "Record as arch constraint?" | spec-add arch |
+| retry_count >= 2 | "Document fix pattern?" | spec-add debug |
+| Summary contains design rationale ("chose X because") | "Record as knowhow?" | spec-add learning |
+
+On confirm → `Skill("spec-add", "<category> <content> --description \"<summary>\"")`.
+Include `--description` with a one-line summary for search result display.
+
+### Issue Status Sync
+
+On each task completion, if `task.issue_id` exists, sync status back to the issue in `.workflow/issues/issues.jsonl`:
+
+```
+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
+```
+
+</execution>
+
+<completion>
+### Standalone report
+
+```
+=== EXECUTION COMPLETE ===
+Plans executed: {plans_count}
+Completed: {completed_count}/{total_count} tasks
+Failed:    {failed_count} tasks
+
+Summaries: {plan_dir}/.summaries/
+Tasks:     {plan_dir}/.task/
+```
+
+### Ralph-invoked completion
+
+End the step by calling the CLI (no text block output):
+```
+maestro ralph complete <idx> --status {STATUS} [--evidence {path}]
+```
+
+Status verdicts:
+- **DONE** — Normal completion
+- **DONE_WITH_CONCERNS** — Completed with caveats; pass `--concerns`
+- **NEEDS_RETRY** — Tooling error / transient issue; ralph will retry
+- **BLOCKED** — External hard blocker; pass `--reason`
+
+### Next-step routing
+
+| Condition | Suggestion |
+|-----------|-----------|
+| All tasks completed successfully | `/quality-review` |
+| Failed tasks exist | `/quality-debug` |
+| View project dashboard | `/manage-status` |
+</completion>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | No pending plans found | Verify plans exist, run maestro-plan first |
+| E002 | error | Plan directory not found | Check --dir path |
+| E003 | error | plan.json not found in directory | Verify plan.json exists, run maestro-plan first |
+| E004 | error | No pending tasks, all tasks already completed | Check task statuses, reset if needed |
+| 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 knowhow extracted to specs/learnings.md
+- [ ] state.json updated with execution progress
+</success_criteria>

package/.agy/skills/maestro-fork/SKILL.md

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