maestro-flow 0.5.1 → 0.5.3

package/.codex/skills/maestro-learn/SKILL.md

@@ -1,80 +1,80 @@
----
-name: maestro-learn
-description: Route learning intent to learn-* commands
-argument-hint: "\"intent text\" [-y] [--dry-run] [--chain <name>]"
-allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
----
-
-<purpose>
-Route learning requests to the optimal learn command or multi-step chain.
-Executes commands sequentially with session tracking.
-
-```
-Intent → Route to Chain → Execute Steps → Session Summary
-```
-</purpose>
-
-<context>
-$ARGUMENTS — learning intent text, or flags.
-
-**Flags:**
-- `-y, --yes` — Auto mode: skip confirmation
-- `--dry-run` — Show planned chain without executing
-- `--chain <name>` — Force specific chain
-
-**Chains:**
-| Chain | Steps | Use when |
-|-------|-------|----------|
-| `follow` | learn-follow | Read/understand code or docs |
-| `investigate` | learn-investigate | Answer "how/why" questions |
-| `decompose` | learn-decompose | Catalog patterns in a module |
-| `second-opinion` | learn-second-opinion | Get review/challenge on code |
-| `retro` | learn-retro --lens all | Full retrospective |
-| `deep-understand` | follow → decompose → second-opinion | Thorough module analysis |
-| `pattern-catalog` | decompose --save-spec --save-wiki → second-opinion --mode review | Full pattern extraction + review |
-
-**Session state:** `.workflow/knowhow/.maestro-learn/{session_id}/status.json`
-</context>
-
-<execution>
-
-### Step 1: Parse & Route
-
-**Intent routing:**
-| Keywords | Route |
-|----------|-------|
-| File path (contains `/` or `\`) | `follow` |
-| read, follow, walk through, understand | `follow` |
-| why, how, what if, investigate | `investigate` |
-| pattern, decompose, catalog | `decompose` |
-| opinion, review, challenge, consult | `second-opinion` |
-| retro, git, commit, decision | `retro` |
-| thorough, deep | `deep-understand` |
-
-No match → present menu via AskUserQuestion. Max 1 clarification.
-
-### Step 2: Resolve Target & Build Args
-Map chain to skill invocations. Extract target and flags from arguments.
-
-### Step 3: Confirm & Execute
-- `--dry-run`: display chain and exit
-- Not `-y`: show plan, ask confirmation
-- Execute each step sequentially. On failure: retry/skip/abort
-- Write session `status.json`, display summary
-</execution>
-
-<error_codes>
-| Code | Severity | Condition | Recovery |
-|------|----------|-----------|----------|
-| E001 | error | No intent provided | Provide learning goal or use --chain |
-| E002 | error | Cannot determine intent | Rephrase or use --chain |
-| E005 | error | Invalid --chain name | Show valid chains |
-| W001 | warning | Intent ambiguous | Present options |
-</error_codes>
-
-<success_criteria>
-- [ ] Intent routed to correct chain
-- [ ] Session directory created with status.json
-- [ ] All chain steps executed
-- [ ] Session summary displayed with next-step routing
-</success_criteria>
+---
+name: maestro-learn
+description: Route learning intent to learn-* commands
+argument-hint: "\"intent text\" [-y] [--dry-run] [--chain <name>]"
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, request_user_input
+---
+
+<purpose>
+Route learning requests to the optimal learn command or multi-step chain.
+Executes commands sequentially with session tracking.
+
+```
+Intent → Route to Chain → Execute Steps → Session Summary
+```
+</purpose>
+
+<context>
+$ARGUMENTS — learning intent text, or flags.
+
+**Flags:**
+- `-y, --yes` — Auto mode: skip confirmation
+- `--dry-run` — Show planned chain without executing
+- `--chain <name>` — Force specific chain
+
+**Chains:**
+| Chain | Steps | Use when |
+|-------|-------|----------|
+| `follow` | learn-follow | Read/understand code or docs |
+| `investigate` | learn-investigate | Answer "how/why" questions |
+| `decompose` | learn-decompose | Catalog patterns in a module |
+| `second-opinion` | learn-second-opinion | Get review/challenge on code |
+| `retro` | learn-retro --lens all | Full retrospective |
+| `deep-understand` | follow → decompose → second-opinion | Thorough module analysis |
+| `pattern-catalog` | decompose --save-spec --save-wiki → second-opinion --mode review | Full pattern extraction + review |
+
+**Session state:** `.workflow/knowhow/.maestro-learn/{session_id}/status.json`
+</context>
+
+<execution>
+
+### Step 1: Parse & Route
+
+**Intent routing:**
+| Keywords | Route |
+|----------|-------|
+| File path (contains `/` or `\`) | `follow` |
+| read, follow, walk through, understand | `follow` |
+| why, how, what if, investigate | `investigate` |
+| pattern, decompose, catalog | `decompose` |
+| opinion, review, challenge, consult | `second-opinion` |
+| retro, git, commit, decision | `retro` |
+| thorough, deep | `deep-understand` |
+
+No match → present menu via request_user_input. Max 1 clarification.
+
+### Step 2: Resolve Target & Build Args
+Map chain to skill invocations. Extract target and flags from arguments.
+
+### Step 3: Confirm & Execute
+- `--dry-run`: display chain and exit
+- Not `-y`: show plan, ask confirmation
+- Execute each step sequentially. On failure: retry/skip/abort
+- Write session `status.json`, display summary
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | No intent provided | Provide learning goal or use --chain |
+| E002 | error | Cannot determine intent | Rephrase or use --chain |
+| E005 | error | Invalid --chain name | Show valid chains |
+| W001 | warning | Intent ambiguous | Present options |
+</error_codes>
+
+<success_criteria>
+- [ ] Intent routed to correct chain
+- [ ] Session directory created with status.json
+- [ ] All chain steps executed
+- [ ] Session summary displayed with next-step routing
+</success_criteria>

package/.codex/skills/maestro-merge/SKILL.md

@@ -1,76 +1,76 @@
----
-name: maestro-merge
-description: Merge milestone worktree branch back to main
-argument-hint: "-m <milestone-number> [--force] [--dry-run] [--no-cleanup] [--continue]"
-allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
----
-
-<purpose>
-Merge a completed milestone worktree branch back into main, sync scratch artifacts,
-and reconcile artifact registry. Two-phase approach: git merge first (source code),
-artifact sync second (only after git succeeds). Prevents partial state corruption
-when merge conflicts occur.
-</purpose>
-
-<required_reading>
-@~/.maestro/workflows/merge.md
-</required_reading>
-
-<context>
-$ARGUMENTS — milestone number and optional flags.
-
-**Flags:**
-- `-m <N>` or bare `<N>`: Milestone number
-- `--force`: Merge even if milestone has incomplete artifacts
-- `--dry-run`: Show what would be merged
-- `--no-cleanup`: Keep worktree and branch after merge
-- `--continue`: Resume merge paused due to git conflict
-
-**Merge sequence:**
-1. Registry health check → 2. Milestone artifact completeness validation →
-3. Pre-merge rebase → 4. Git merge (source) → 5. Scratch artifact sync →
-6. Artifact registry reconciliation → 7. Cleanup
-
-**Phase 2 detail:**
-- Copy worktree `scratch/*` to main `.workflow/scratch/`
-- Merge `state.json.artifacts[]` entries (worktree wins for same id)
-- Remove milestone `"forked"` flag in main state.json
-</context>
-
-<execution>
-Follow '~/.maestro/workflows/merge.md' completely.
-
-**Knowledge inquiry on completion:**
-After successful merge, ask user once: "Record milestone learnings?" If yes, persist via `maestro spec add learning "<title>" "<insight>" --keywords <kw1>,<kw2> --description "<summary>"`.
-
-**Next steps:**
-- View dashboard → `$manage-status`
-- Audit milestone → `$maestro-milestone-audit`
-</execution>
-
-<invariants>
-**Phase order enforcement** — git merge MUST complete before artifact sync. Do NOT sync artifacts until git merge succeeds — prevents partial state corruption.
-</invariants>
-
-<error_codes>
-| Code | Severity | Condition | Recovery |
-|------|----------|-----------|----------|
-| E001 | error | Running inside a worktree | Run from main worktree |
-| E002 | error | No worktree registry found | Nothing to merge |
-| E003 | error | --continue but no merge state | Start fresh merge |
-| E004 | error | No milestone number | Provide `-m <N>` |
-| W001 | warning | Stale registry entries | Auto-cleaned |
-| W002 | warning | Incomplete artifacts without --force | Confirm or use --force |
-| W003 | warning | Conflict pulling main into worktree | Resolve first |
-</error_codes>
-
-<success_criteria>
-- [ ] Registry health check passed
-- [ ] Pre-merge rebase successful
-- [ ] Git merge completed (or conflicts resolved via --continue)
-- [ ] Scratch artifacts synced to main `.workflow/scratch/`
-- [ ] `state.json.artifacts[]` reconciled (worktree entries merged)
-- [ ] Milestone `"forked"` flag removed
-- [ ] Worktree removed and branch deleted (unless --no-cleanup)
-- [ ] Registry updated
-</success_criteria>
+---
+name: maestro-merge
+description: Merge milestone worktree branch back to main
+argument-hint: "-m <milestone-number> [--force] [--dry-run] [--no-cleanup] [--continue]"
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, request_user_input
+---
+
+<purpose>
+Merge a completed milestone worktree branch back into main, sync scratch artifacts,
+and reconcile artifact registry. Two-phase approach: git merge first (source code),
+artifact sync second (only after git succeeds). Prevents partial state corruption
+when merge conflicts occur.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/merge.md
+</required_reading>
+
+<context>
+$ARGUMENTS — milestone number and optional flags.
+
+**Flags:**
+- `-m <N>` or bare `<N>`: Milestone number
+- `--force`: Merge even if milestone has incomplete artifacts
+- `--dry-run`: Show what would be merged
+- `--no-cleanup`: Keep worktree and branch after merge
+- `--continue`: Resume merge paused due to git conflict
+
+**Merge sequence:**
+1. Registry health check → 2. Milestone artifact completeness validation →
+3. Pre-merge rebase → 4. Git merge (source) → 5. Scratch artifact sync →
+6. Artifact registry reconciliation → 7. Cleanup
+
+**Phase 2 detail:**
+- Copy worktree `scratch/*` to main `.workflow/scratch/`
+- Merge `state.json.artifacts[]` entries (worktree wins for same id)
+- Remove milestone `"forked"` flag in main state.json
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/merge.md' completely.
+
+**Knowledge inquiry on completion:**
+After successful merge, ask user once: "Record milestone learnings?" If yes, persist via `maestro spec add learning "<title>" "<insight>" --keywords <kw1>,<kw2> --description "<summary>"`.
+
+**Next steps:**
+- View dashboard → `$manage-status`
+- Audit milestone → `$maestro-milestone-audit`
+</execution>
+
+<invariants>
+**Phase order enforcement** — git merge MUST complete before artifact sync. Do NOT sync artifacts until git merge succeeds — prevents partial state corruption.
+</invariants>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | Running inside a worktree | Run from main worktree |
+| E002 | error | No worktree registry found | Nothing to merge |
+| E003 | error | --continue but no merge state | Start fresh merge |
+| E004 | error | No milestone number | Provide `-m <N>` |
+| W001 | warning | Stale registry entries | Auto-cleaned |
+| W002 | warning | Incomplete artifacts without --force | Confirm or use --force |
+| W003 | warning | Conflict pulling main into worktree | Resolve first |
+</error_codes>
+
+<success_criteria>
+- [ ] Registry health check passed
+- [ ] Pre-merge rebase successful
+- [ ] Git merge completed (or conflicts resolved via --continue)
+- [ ] Scratch artifacts synced to main `.workflow/scratch/`
+- [ ] `state.json.artifacts[]` reconciled (worktree entries merged)
+- [ ] Milestone `"forked"` flag removed
+- [ ] Worktree removed and branch deleted (unless --no-cleanup)
+- [ ] Registry updated
+</success_criteria>

package/.codex/skills/maestro-milestone-release/SKILL.md

@@ -1,74 +1,74 @@
----
-name: maestro-milestone-release
-description: Bump version, generate changelog, tag milestone
-argument-hint: "[<version>] [--bump patch|minor|major] [--dry-run] [--no-tag] [--no-push]"
-allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
----
-
-<purpose>
-Package a completed milestone into a releasable version. Bumps project version in manifest,
-generates CHANGELOG.md entry from phase/milestone summaries and git log, creates annotated
-git tag, optionally pushes to remote. Runs after `/maestro-milestone-complete`.
-</purpose>
-
-<required_reading>
-@~/.maestro/workflows/milestone-release.md
-</required_reading>
-
-<context>
-$ARGUMENTS — optional explicit version and flags.
-
-**Flags:**
-- `<version>` — Explicit version (e.g. `1.2.0`). If omitted, derived from `--bump`.
-- `--bump patch|minor|major` — Semver bump (default: `minor`)
-- `--dry-run` — Compute version + changelog without writing
-- `--no-tag` — Skip git tag creation
-- `--no-push` — Skip `git push --follow-tags`
-
-**Preconditions:**
-- Current milestone completed (audit PASS + milestone-complete run)
-- Working tree clean (no uncommitted changes) unless `--dry-run`
-</context>
-
-<execution>
-Follow '~/.maestro/workflows/milestone-release.md' completely.
-
-**Flow:** Validate preconditions → Resolve version → Collect changes → Generate CHANGELOG →
-Bump manifest → Commit → Tag → Push
-
-**Report:**
-```
-=== RELEASE COMPLETE ===
-Version:   v{previous} → v{new}
-Milestone: {name}
-Tag:       v{new} {pushed|local-only}
-Changelog: {N} entries
-```
-</execution>
-
-<invariants>
-**Prerequisite enforcement** — milestone MUST be completed (audit PASS + milestone-complete run). Working tree MUST be clean. Artifact verification: CHANGELOG.md entry, version manifest update, release commit, git tag (unless --no-tag) all MUST exist before reporting completion.
-</invariants>
-
-<error_codes>
-| Code | Severity | Condition | Recovery |
-|------|----------|-----------|----------|
-| E001 | error | Milestone not completed | Run `$maestro-milestone-complete` first |
-| E002 | error | Audit verdict not PASS | Re-run `$maestro-milestone-audit` |
-| E003 | error | Working tree not clean | Commit or stash changes |
-| E004 | error | Version manifest not found | Add manifest or pass explicit version |
-| E005 | error | Version not greater than current | Choose higher version |
-| W001 | warning | No changes since last tag | Confirm release is desired |
-| W002 | warning | Remote push failed | Retry `git push --follow-tags` |
-</error_codes>
-
-<success_criteria>
-- [ ] Preconditions validated
-- [ ] Target version computed and greater than previous
-- [ ] Version manifest(s) updated
-- [ ] CHANGELOG.md entry with milestone summary + grouped changes
-- [ ] Release commit created
-- [ ] Annotated git tag created (unless --no-tag)
-- [ ] Pushed to remote (unless --no-push)
-- [ ] state.json updated with last_release_version
-</success_criteria>
+---
+name: maestro-milestone-release
+description: Bump version, generate changelog, tag milestone
+argument-hint: "[<version>] [--bump patch|minor|major] [--dry-run] [--no-tag] [--no-push]"
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, request_user_input
+---
+
+<purpose>
+Package a completed milestone into a releasable version. Bumps project version in manifest,
+generates CHANGELOG.md entry from phase/milestone summaries and git log, creates annotated
+git tag, optionally pushes to remote. Runs after `$maestro-milestone-complete`.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/milestone-release.md
+</required_reading>
+
+<context>
+$ARGUMENTS — optional explicit version and flags.
+
+**Flags:**
+- `<version>` — Explicit version (e.g. `1.2.0`). If omitted, derived from `--bump`.
+- `--bump patch|minor|major` — Semver bump (default: `minor`)
+- `--dry-run` — Compute version + changelog without writing
+- `--no-tag` — Skip git tag creation
+- `--no-push` — Skip `git push --follow-tags`
+
+**Preconditions:**
+- Current milestone completed (audit PASS + milestone-complete run)
+- Working tree clean (no uncommitted changes) unless `--dry-run`
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/milestone-release.md' completely.
+
+**Flow:** Validate preconditions → Resolve version → Collect changes → Generate CHANGELOG →
+Bump manifest → Commit → Tag → Push
+
+**Report:**
+```
+=== RELEASE COMPLETE ===
+Version:   v{previous} → v{new}
+Milestone: {name}
+Tag:       v{new} {pushed|local-only}
+Changelog: {N} entries
+```
+</execution>
+
+<invariants>
+**Prerequisite enforcement** — milestone MUST be completed (audit PASS + milestone-complete run). Working tree MUST be clean. Artifact verification: CHANGELOG.md entry, version manifest update, release commit, git tag (unless --no-tag) all MUST exist before reporting completion.
+</invariants>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | Milestone not completed | Run `$maestro-milestone-complete` first |
+| E002 | error | Audit verdict not PASS | Re-run `$maestro-milestone-audit` |
+| E003 | error | Working tree not clean | Commit or stash changes |
+| E004 | error | Version manifest not found | Add manifest or pass explicit version |
+| E005 | error | Version not greater than current | Choose higher version |
+| W001 | warning | No changes since last tag | Confirm release is desired |
+| W002 | warning | Remote push failed | Retry `git push --follow-tags` |
+</error_codes>
+
+<success_criteria>
+- [ ] Preconditions validated
+- [ ] Target version computed and greater than previous
+- [ ] Version manifest(s) updated
+- [ ] CHANGELOG.md entry with milestone summary + grouped changes
+- [ ] Release commit created
+- [ ] Annotated git tag created (unless --no-tag)
+- [ ] Pushed to remote (unless --no-push)
+- [ ] state.json updated with last_release_version
+</success_criteria>

package/.codex/skills/maestro-next/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: maestro-next
-description: Single-command recommendation — pick the best next skill from the pool and execute it in-context
+description: "Single-command recommendation — pick the best next skill from the pool and execute it in-context"
 argument-hint: "\"<intent>\" [-y] [--dry-run] [--top N] [--list]"
 allowed-tools: Read, Bash, Glob, Grep, request_user_input
 ---

package/.codex/skills/maestro-player/SKILL.md

@@ -2,7 +2,7 @@
 name: maestro-player
 description: Play workflow templates with checkpoint resume
 argument-hint: "<template-slug|path> [--context key=value...] [-c [session-id]] [--list] [--dry-run]"
-allowed-tools: spawn_agents_on_csv, Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
+allowed-tools: spawn_agents_on_csv, Read, Write, Edit, Bash, Glob, Grep, request_user_input
 ---
 
 <purpose>
@@ -123,7 +123,7 @@ S_COMPLETE:
 
 1. Resolve template: absolute/relative/slug → index.json lookup
 2. Parse --context key=value, validate template JSON
-3. Collect missing required vars via AskUserQuestion
+3. Collect missing required vars via request_user_input
 4. Bind {variable} placeholders (leave {N-xxx.field}/{prev_*} for runtime)
 
 ### A_INIT_SESSION
@@ -135,7 +135,7 @@ S_COMPLETE:
 
 ### A_EXECUTE_WAVE
 
-1. **Checkpoint**: handle inline — save snapshot, update context.last_checkpoint, mark completed. If auto_continue==false: AskUserQuestion (Continue/Pause/Abort).
+1. **Checkpoint**: handle inline — save snapshot, update context.last_checkpoint, mark completed. If auto_continue==false: request_user_input (Continue/Pause/Abort).
 
 2. **Skill nodes**: resolve runtime references → write wave-{N}.csv (only rows with status == "pending") → spawn:
 ```