maestro-flow 0.3.8 → 0.3.9

package/.claude/commands/manage-codebase-refresh.md

@@ -53,5 +53,5 @@ Follow '~/.maestro/workflows/codebase-refresh.md' completely.
 - [ ] Only affected docs refreshed (selective mapper re-run)
 - [ ] doc-index.json timestamps updated per affected entry
 - [ ] state.json updated with codebase_last_refreshed timestamp
-- [ ] Next step routing: Skill({ skill: "manage-status" }) or Skill({ skill: "spec-load" }) to use updated docs
+- [ ] Next step routing: `/manage-status` or `/spec-load` to use updated docs
 </success_criteria>

package/.claude/commands/manage-harvest.md

@@ -89,16 +89,16 @@ Follow '~/.maestro/workflows/harvest.md' Stages 1–8 in order. Key invariants:
 
 **Next-step routing on completion:**
 - Review wiki entries → `maestro wiki list --type note`
-- Connect wiki graph → `Skill({ skill: "wiki-connect", args: "--fix" })`
-- Triage issues → `Skill({ skill: "manage-issue", args: "list --source harvest" })`
-- View specs → `Skill({ skill: "spec-load", args: "--category general" })`
-- Full retrospective → `Skill({ skill: "quality-retrospective" })`
+- Connect wiki graph → `/wiki-connect --fix`
+- Triage issues → `/manage-issue list --source harvest`
+- View specs → `/spec-load --category general`
+- Full retrospective → `/quality-retrospective`
 </execution>
 
 <error_codes>
 | Code | Severity | Condition | Recovery |
 |------|----------|-----------|----------|
-| E001 | error | `.workflow/` not initialized | Run `Skill({ skill: "maestro-init" })` first |
+| E001 | error | `.workflow/` not initialized | Run `/maestro-init` first |
 | E002 | error | Invalid `--to` target (must be: wiki, spec, issue, auto) | Display valid options |
 | E003 | error | Invalid `--source` type | Display valid source types from registry |
 | E004 | error | Session ID not found in any source path | Show available sessions with `--source all` |

package/.claude/commands/manage-issue-discover.md

@@ -73,5 +73,5 @@ Follow '~/.maestro/workflows/issue-discover.md' completely.
 - [ ] Findings deduplicated before issue creation
 - [ ] Issues appended to issues.jsonl with correct schema
 - [ ] Discovery session fully traceable via session directory
-- [ ] Next step routing: Skill({ skill: "manage-issue-analyze", args: "<ISS-ID>" }) for root cause analysis, or Skill({ skill: "manage-issue", args: "list" }) to review all issues
+- [ ] Next step routing: `/manage-issue-analyze <ISS-ID>` for root cause analysis, or `/manage-issue list` to review all issues
 </success_criteria>

package/.claude/commands/manage-issue-execute.md

@@ -48,9 +48,9 @@ $ARGUMENTS -- ISS-ID (required) + optional flags.
 Follow '~/.maestro/workflows/issue-execute.md' completely.
 
 **Next-step routing on completion:**
-- Execution succeeded → Skill({ skill: "manage-issue", args: "close <ISS-ID> --resolution fixed" })
-- Execution failed → Skill({ skill: "quality-debug", args: "<failure description>" }) then retry
-- Want verification → Skill({ skill: "maestro-verify", args: "{phase}" })
+- Execution succeeded → `/manage-issue close <ISS-ID> --resolution fixed`
+- Execution failed → `/quality-debug <failure description>` then retry
+- Want verification → `/maestro-verify {phase}`
 </execution>
 
 <error_codes>
@@ -67,7 +67,7 @@ Follow '~/.maestro/workflows/issue-execute.md' completely.
 - [ ] Solution executed (or dry-run displayed)
 - [ ] Issue status updated in issues.jsonl (in_progress -> resolved or open on failure)
 - [ ] Result summary displayed with next-step routing:
-  - Execution succeeded → Skill({ skill: "manage-issue", args: "close <ISS-ID> --resolution fixed" })
-  - Execution failed → Skill({ skill: "quality-debug", args: "<failure description>" }) then retry
-  - Want verification → Skill({ skill: "maestro-verify", args: "{phase}" })
+  - Execution succeeded → `/manage-issue close <ISS-ID> --resolution fixed`
+  - Execution failed → `/quality-debug <failure description>` then retry
+  - Want verification → `/maestro-verify {phase}`
 </success_criteria>

package/.claude/commands/manage-issue.md

@@ -48,9 +48,9 @@ Parse subcommand from first token of $ARGUMENTS.
 Follow '~/.maestro/workflows/issue.md' completely.
 
 **Next-step routing on completion:**
-- create → Skill({ skill: "manage-issue-analyze", args: "<ISS-ID>" }) or Skill({ skill: "manage-issue-plan", args: "<ISS-ID>" })
-- list → Skill({ skill: "manage-issue-analyze", args: "<ISS-ID>" }) for any open issue
-- close → Skill({ skill: "manage-status" })
+- create → `/manage-issue-analyze <ISS-ID>` or `/manage-issue-plan <ISS-ID>`
+- list → `/manage-issue-analyze <ISS-ID>` for any open issue
+- close → `/manage-status`
 </execution>
 
 <error_codes>
@@ -67,7 +67,7 @@ Follow '~/.maestro/workflows/issue.md' completely.
 - [ ] Output displayed in appropriate format (table for list, detail for status)
 - [ ] Cross-references maintained (link creates bidirectional references)
 - [ ] Next step routing by subcommand:
-  - create → Skill({ skill: "manage-issue-analyze", args: "<ISS-ID>" }) or Skill({ skill: "manage-issue-plan", args: "<ISS-ID>" })
-  - list → Skill({ skill: "manage-issue-analyze", args: "<ISS-ID>" }) for any open issue
-  - close → Skill({ skill: "manage-status" })
+  - create → `/manage-issue-analyze <ISS-ID>` or `/manage-issue-plan <ISS-ID>`
+  - list → `/manage-issue-analyze <ISS-ID>` for any open issue
+  - close → `/manage-status`
 </success_criteria>

package/.claude/commands/manage-learn.md

@@ -69,7 +69,7 @@ Follow `~/.maestro/workflows/learn.md` Stages 1–5 in order. Key invariants:
 <error_codes>
 | Code | Severity | Description | Stage |
 |------|----------|-------------|-------|
-| E001 | error | `.workflow/` not initialized — run `Skill({ skill: "maestro-init" })` first | parse_input |
+| E001 | error | `.workflow/` not initialized — run `/maestro-init` first | parse_input |
 | E002 | error | Unknown `--category` value (allowed: pattern, antipattern, decision, tool, gotcha, technique, tip) | parse_input |
 | E003 | error | `show` mode requires an INS-id argument | show |
 | E004 | error | Insight id not found in lessons.jsonl | show |
@@ -88,5 +88,5 @@ Follow `~/.maestro/workflows/learn.md` Stages 1–5 in order. Key invariants:
 - [ ] Show: full insight displayed with phase context and routed-artifact link if any
 - [ ] No file modifications outside `.workflow/learning/`
 - [ ] Confirmation banner displayed with INS-id and next-step hints
-- [ ] Next step: `Skill({ skill: "manage-learn", args: "list" })` to browse, or `Skill({ skill: "manage-learn", args: "search <query>" })` to find related insights
+- [ ] Next step: `/manage-learn list` to browse, or `/manage-learn search <query>` to find related insights
 </success_criteria>

package/.claude/commands/manage-memory-capture.md

@@ -40,8 +40,8 @@ Follow '~/.maestro/workflows/memory.md' Part B (Memory Capture) completely.
 <error_codes>
 | Code | Severity | Description | Stage |
 |------|----------|-------------|-------|
-| E001 | error | `.workflow/` not initialized — run Skill({ skill: "maestro-init" }) first | parse_input |
-| E002 | error | Tip mode removed — use `Skill({ skill: "manage-learn", args: "tip <text>" })` instead | parse_input |
+| E001 | error | `.workflow/` not initialized — run `/maestro-init` first | parse_input |
+| E002 | error | Tip mode removed — use `/manage-learn tip <text>` instead | parse_input |
 | W001 | warning | No active workflow session found — compact will capture conversation only | analyze_session |
 | W002 | warning | Plan detection found no explicit plan — using inferred plan | analyze_session |
 </error_codes>
@@ -54,6 +54,6 @@ Follow '~/.maestro/workflows/memory.md' Part B (Memory Capture) completely.
 - [ ] Execution plan preserved VERBATIM (not summarized)
 - [ ] All file paths are ABSOLUTE
 - [ ] Confirmation banner displayed with entry ID
-- [ ] Next step: Skill({ skill: "manage-status" }) to resume workflow, or Skill({ skill: "manage-memory", args: "view <entry_id>" }) to verify captured memory
-- [ ] For tips: redirect user to `Skill({ skill: "manage-learn", args: "tip <text>" })`
+- [ ] Next step: `/manage-status` to resume workflow, or `/manage-memory view <entry_id>` to verify captured memory
+- [ ] For tips: redirect user to `/manage-learn tip <text>`
 </success_criteria>

package/.claude/commands/manage-memory.md

@@ -64,7 +64,7 @@ Follow '~/.maestro/workflows/memory.md' Part A (Memory Management) completely.
 <error_codes>
 | Code | Severity | Description | Stage |
 |------|----------|-------------|-------|
-| E001 | error | No memory stores found — run Skill({ skill: "manage-memory-capture" }) or create MEMORY.md | resolve_paths |
+| E001 | error | No memory stores found — run `/manage-memory-capture` or create MEMORY.md | resolve_paths |
 | E002 | error | Entry ID or filename not found | execute_view, execute_delete |
 | E003 | error | Prune requires at least one filter (--tag, --type, --before, --after) | execute_prune |
 | E004 | error | Cannot delete MEMORY.md — use `edit` subcommand instead | execute_delete |
@@ -84,5 +84,5 @@ Follow '~/.maestro/workflows/memory.md' Part A (Memory Management) completely.
 - [ ] Delete: MEMORY.md protected, confirmation required, references checked
 - [ ] Prune: workflow-only, filters validated, index updated
 - [ ] Integrity check catches orphans and broken links
-- [ ] Next step: Skill({ skill: "manage-memory-capture", args: "compact" }) to save new memory, or Skill({ skill: "manage-status" }) to continue workflow
+- [ ] Next step: `/manage-memory-capture compact` to save new memory, or `/manage-status` to continue workflow
 </success_criteria>

package/.claude/commands/manage-status.md

@@ -8,9 +8,9 @@ allowed-tools:
   - Grep
 ---
 <purpose>
-Display a unified project dashboard showing phase progress, task counts, active work, and intelligent next-step suggestions.
-Reads all state files from `.workflow/` and renders a formatted overview with progress bars and status tables.
-Provides situational awareness before continuing work.
+Display a unified project dashboard showing artifact progress, task counts, active work, and intelligent next-step suggestions.
+Reads state.json artifact registry and roadmap to render a formatted overview with progress and status tables.
+Provides situational awareness before continuing work. Uses virtual phase view derived from artifact registry.
 </purpose>
 
 <required_reading>
@@ -21,10 +21,10 @@ Provides situational awareness before continuing work.
 $ARGUMENTS (no arguments required)
 
 **State files read:**
-- `.workflow/state.json` -- project-level state machine
+- `.workflow/state.json` -- project-level state machine + artifact registry
 - `.workflow/roadmap.md` -- milestone and phase structure
-- `.workflow/phases/*/index.json` -- per-phase metadata and progress
-- `.workflow/phases/*/.task/TASK-*.json` -- individual task statuses
+- `.workflow/scratch/*/plan.json` -- plan metadata (via artifact registry paths)
+- `.workflow/scratch/*/.task/TASK-*.json` -- individual task statuses
 </context>
 
 <execution>
@@ -33,29 +33,29 @@ Follow '~/.maestro/workflows/status.md' completely.
 **Next-step decision table:**
 | Current state | Suggested command | Reason |
 |---------------|-------------------|--------|
-| No phases planned | Skill({ skill: "maestro-brainstorm", args: "1" }) or Skill({ skill: "maestro-plan", args: "1" }) | Explore ideas or start planning first phase |
-| Phase pending, needs analysis | Skill({ skill: "maestro-analyze", args: "<N>" }) | Evaluate feasibility before planning |
-| Phase pending, needs decisions | Skill({ skill: "maestro-analyze", args: "<N> -q" }) | Quick decision extraction |
-| Phase planned, not executed | Skill({ skill: "maestro-execute", args: "<N>" }) | Execute the planned phase |
-| Phase executing, tasks blocked | Skill({ skill: "quality-debug", args: "<N>" }) | Unblock stuck tasks |
-| Phase executed, not verified | Skill({ skill: "maestro-verify", args: "<N>" }) | Verify execution results |
-| Phase verified with gaps | Skill({ skill: "maestro-plan", args: "<N> --gaps" }) | Plan gap fixes |
-| Phase verified, not reviewed | Skill({ skill: "quality-review", args: "<N>" }) | Code quality review before UAT |
-| Phase reviewed, verdict BLOCK | Skill({ skill: "maestro-plan", args: "<N> --gaps" }) | Fix critical review findings first |
-| Phase reviewed, verdict PASS/WARN | Skill({ skill: "quality-test", args: "<N>" }) | Proceed to UAT testing |
-| Phase verified, low test coverage | Skill({ skill: "quality-test-gen", args: "<N>" }) | Generate missing automated tests |
-| UAT passed | Skill({ skill: "maestro-phase-transition" }) | Move to next phase |
-| UAT has failures | Skill({ skill: "quality-debug", args: "--from-uat <N>" }) | Debug UAT gaps with parallel agents |
-| Need integration test cycle | Skill({ skill: "quality-integration-test", args: "<N>" }) | Self-iterating integration tests |
-| All phases in milestone complete | Skill({ skill: "maestro-milestone-audit" }) | Cross-phase integration check |
-| Milestone audit passed | Skill({ skill: "maestro-milestone-complete" }) | Archive milestone, advance |
-| Ad-hoc small task | Skill({ skill: "maestro-quick", args: "<task>" }) | Quick execute without full pipeline |
+| No phases planned | `/maestro-brainstorm 1` or `/maestro-plan 1` | Explore ideas or start planning first phase |
+| Phase pending, needs analysis | `/maestro-analyze <N>` | Evaluate feasibility before planning |
+| Phase pending, needs decisions | `/maestro-analyze <N> -q` | Quick decision extraction |
+| Phase planned, not executed | `/maestro-execute <N>` | Execute the planned phase |
+| Phase executing, tasks blocked | `/quality-debug <N>` | Unblock stuck tasks |
+| Phase executed, not verified | `/maestro-verify <N>` | Verify execution results |
+| Phase verified with gaps | `/maestro-plan <N> --gaps` | Plan gap fixes |
+| Phase verified, not reviewed | `/quality-review <N>` | Code quality review before UAT |
+| Phase reviewed, verdict BLOCK | `/maestro-plan <N> --gaps` | Fix critical review findings first |
+| Phase reviewed, verdict PASS/WARN | `/quality-test <N>` | Proceed to UAT testing |
+| Phase verified, low test coverage | `/quality-test-gen <N>` | Generate missing automated tests |
+| UAT passed, all phases done | `/maestro-milestone-audit` | Cross-phase integration check |
+| UAT has failures | `/quality-debug --from-uat <N>` | Debug UAT gaps with parallel agents |
+| Need integration test cycle | `/quality-integration-test <N>` | Self-iterating integration tests |
+| All phases in milestone complete | `/maestro-milestone-audit` | Cross-phase integration check |
+| Milestone audit passed | `/maestro-milestone-complete` | Archive milestone, advance |
+| Ad-hoc small task | `/maestro-quick <task>` | Quick execute without full pipeline |
 </execution>
 
 <error_codes>
 | Code | Severity | Description | Stage |
 |------|----------|-------------|-------|
-| E001 | fatal | `.workflow/` not initialized -- run Skill({ skill: "maestro-init" }) first | parse_input |
+| E001 | fatal | `.workflow/` not initialized -- run `/maestro-init` first | parse_input |
 | E002 | fatal | `state.json` missing or corrupt -- project state unrecoverable | parse_input |
 </error_codes>
 

package/.claude/commands/quality-business-test.md

@@ -70,11 +70,11 @@ Context files:
 Follow '~/.maestro/workflows/business-test.md' completely.
 
 **Next-step routing on completion:**
-- All requirements verified → Skill({ skill: "maestro-phase-transition", args: "{phase}" })
-- Failures found → Skill({ skill: "quality-debug", args: "--from-business-test {phase}" })
-- Re-run all pass → Skill({ skill: "maestro-verify", args: "{phase}" })
-- Low coverage → Skill({ skill: "quality-test-gen", args: "{phase}" })
-- Need integration tests → Skill({ skill: "quality-integration-test", args: "{phase}" })
+- All requirements verified → `/maestro-phase-transition {phase}`
+- Failures found → `/quality-debug --from-business-test {phase}`
+- Re-run all pass → `/maestro-verify {phase}`
+- Low coverage → `/quality-test-gen {phase}`
+- Need integration tests → `/quality-integration-test {phase}`
 </execution>
 
 <error_codes>

package/.claude/commands/quality-debug.md

@@ -49,10 +49,10 @@ User's issue: $ARGUMENTS
 Follow '~/.maestro/workflows/debug.md' completely.
 
 **Next-step routing on completion:**
-- Root cause found, fix needed → Skill({ skill: "maestro-plan", args: "{phase} --gaps" })
-- Root cause found (from UAT), auto-fix → Skill({ skill: "quality-test", args: "{phase} --auto-fix" })
-- Inconclusive, need more info → Skill({ skill: "quality-debug", args: "{issue} -c" }) (resume session)
-- Standalone fix already applied → Skill({ skill: "maestro-verify", args: "{phase}" })
+- Root cause found, fix needed → `/maestro-plan {phase} --gaps`
+- Root cause found (from UAT), auto-fix → `/quality-test {phase} --auto-fix`
+- Inconclusive, need more info → `/quality-debug {issue} -c` (resume session)
+- Standalone fix already applied → `/maestro-verify {phase}`
 
 Note: Debug output (.debug/) is auto-loaded by maestro-plan --gaps.
 </execution>

package/.claude/commands/quality-integration-test.md

@@ -54,10 +54,10 @@ Phase: $ARGUMENTS (required -- phase number)
 Follow '~/.maestro/workflows/integration-test.md' completely.
 
 **Next-step routing on completion:**
-- Converged (pass rate met) → Skill({ skill: "maestro-phase-transition", args: "{phase}" })
-- Max iterations, pass rate close → Skill({ skill: "quality-debug", args: "{phase}" }) (investigate remaining failures)
-- Regressions detected → Skill({ skill: "quality-debug", args: "{phase}" })
-- Stuck 3+ iterations → Skill({ skill: "maestro-analyze", args: "{phase} -q" }) (reassess approach)
+- Converged (pass rate met) → `/maestro-phase-transition {phase}`
+- Max iterations, pass rate close → `/quality-debug {phase}` (investigate remaining failures)
+- Regressions detected → `/quality-debug {phase}`
+- Stuck 3+ iterations → `/maestro-analyze {phase} -q` (reassess approach)
 </execution>
 
 <error_codes>

package/.claude/commands/quality-refactor.md

@@ -33,9 +33,9 @@ If not provided, prompt user for scope.
 Follow '~/.maestro/workflows/refactor.md' completely.
 
 **Next-step routing on completion:**
-- All tests pass → Skill({ skill: "quality-sync" }) (update codebase docs)
-- Test failures after refactor → Skill({ skill: "quality-debug", args: "{scope}" })
-- No test suite available → Skill({ skill: "quality-test-gen", args: "{phase}" })
+- All tests pass → `/quality-sync` (update codebase docs)
+- Test failures after refactor → `/quality-debug {scope}`
+- No test suite available → `/quality-test-gen {phase}`
 </execution>
 
 <error_codes>

package/.claude/commands/quality-retrospective.md

@@ -73,7 +73,7 @@ Follow `~/.maestro/workflows/retrospective.md` Stages 1–8 in order. Key invari
 <error_codes>
 | Code | Severity | Description | Stage |
 |------|----------|-------------|-------|
-| E001 | error | `.workflow/` not initialized — run `Skill({ skill: "maestro-init" })` first | parse_input |
+| E001 | error | `.workflow/` not initialized — run `/maestro-init` first | parse_input |
 | E002 | error | Unknown `--lens` name (allowed: technical, process, quality, decision) | parse_input |
 | E003 | error | `--compare` requires a single phase argument | parse_input |
 | E004 | error | Phase has not executed yet — no `.task/` or `.summaries/` artifacts | load_artifacts |
@@ -99,5 +99,5 @@ Follow `~/.maestro/workflows/retrospective.md` Stages 1–8 in order. Key invari
 - [ ] `learning-index.json` updated and parseable
 - [ ] No existing phase artifacts modified (verification.json, review.json, plan.json untouched)
 - [ ] Confirmation banner displays routing counts and next-step suggestions
-- [ ] Next step: `Skill({ skill: "manage-status" })` to review state, or `Skill({ skill: "manage-issue", args: "list --source retrospective" })` to triage created issues, or `Skill({ skill: "manage-learn", args: "list" })` to browse the lessons library
+- [ ] Next step: `/manage-status` to review state, or `/manage-issue list --source retrospective` to triage created issues, or `/manage-learn list` to browse the lessons library
 </success_criteria>

package/.claude/commands/quality-review.md

@@ -94,10 +94,10 @@ Next steps:
 ```
 
 **Next-step routing by verdict:**
-- PASS → Skill({ skill: "quality-test", args: "{phase}" })
-- PASS + low test coverage → Skill({ skill: "quality-test-gen", args: "{phase}" })
-- WARN → Skill({ skill: "quality-test", args: "{phase}" }) (proceed with caveats)
-- BLOCK → Skill({ skill: "maestro-plan", args: "{phase} --gaps" }) (fix critical findings first)
+- PASS → `/quality-test {phase}`
+- PASS + low test coverage → `/quality-test-gen {phase}`
+- WARN → `/quality-test {phase}` (proceed with caveats)
+- BLOCK → `/maestro-plan {phase} --gaps` (fix critical findings first)
 </execution>
 
 <error_codes>

package/.claude/commands/quality-sync.md

@@ -31,14 +31,14 @@ $ARGUMENTS -- optional flags:
 Follow '~/.maestro/workflows/sync.md' completely.
 
 **Next-step routing on completion:**
-- Docs refreshed → Skill({ skill: "manage-status" })
-- Major structural changes detected → Skill({ skill: "manage-codebase-rebuild" }) (full rebuild recommended)
+- Docs refreshed → `/manage-status`
+- Major structural changes detected → `/manage-codebase-rebuild` (full rebuild recommended)
 </execution>
 
 <error_codes>
 | Code | Severity | Condition | Recovery |
 |------|----------|-----------|----------|
-| E001 | error | .workflow/ not initialized | Suggest running Skill({ skill: "maestro-init" }) first|
+| E001 | error | .workflow/ not initialized | Suggest running `/maestro-init` first|
 | W001 | warning | No changes detected since last sync | Report clean state, skip updates |
 </error_codes>
 

package/.claude/commands/quality-test-gen.md

@@ -46,10 +46,10 @@ Context files:
 Follow '~/.maestro/workflows/test-gen.md' completely.
 
 **Next-step routing on completion:**
-- All tests pass → Skill({ skill: "quality-test", args: "{phase}" })
-- Bugs discovered (failing tests) → Skill({ skill: "quality-debug", args: "{phase}" })
-- Regressions in existing tests → Skill({ skill: "quality-debug", args: "{phase}" })
-- Coverage still low → Skill({ skill: "quality-test-gen", args: "{phase} --layer {missing_layer}" })
+- All tests pass → `/quality-test {phase}`
+- Bugs discovered (failing tests) → `/quality-debug {phase}`
+- Regressions in existing tests → `/quality-debug {phase}`
+- Coverage still low → `/quality-test-gen {phase} --layer {missing_layer}`
 </execution>
 
 <error_codes>

package/.claude/commands/quality-test.md

@@ -55,22 +55,22 @@ Follow '~/.maestro/workflows/test.md' completely.
 - When review.json verdict is "BLOCK" and review-finding tests fail, auto-enter gap-fix loop without user confirmation (Step 12 auto-fix condition)
 
 **Next-step routing on completion:**
-- All tests pass → Skill({ skill: "maestro-phase-transition", args: "{phase}" })
-- Issues found, --auto-fix ran and succeeded → Skill({ skill: "maestro-verify", args: "{phase}" })
-- Issues found, --auto-fix ran but gaps remain → Skill({ skill: "quality-debug", args: "--from-uat {phase}" })
-- Issues found, manual fix needed → Skill({ skill: "quality-debug", args: "--from-uat {phase}" })
-- Coverage below threshold → Skill({ skill: "quality-test-gen", args: "{phase}" })
-- Need integration tests → Skill({ skill: "quality-integration-test", args: "{phase}" })
+- All tests pass → `/maestro-phase-transition {phase}`
+- Issues found, --auto-fix ran and succeeded → `/maestro-verify {phase}`
+- Issues found, --auto-fix ran but gaps remain → `/quality-debug --from-uat {phase}`
+- Issues found, manual fix needed → `/quality-debug --from-uat {phase}`
+- Coverage below threshold → `/quality-test-gen {phase}`
+- Need integration tests → `/quality-integration-test {phase}`
 </execution>
 
 <error_codes>
 | Code | Severity | Condition | Recovery |
 |------|----------|-----------|----------|
 | E001 | error | Phase or task target required (no active sessions) | Prompt user for phase number |
-| E002 | error | Phase not verified yet (no verification.json) | Suggest Skill({ skill: "maestro-verify" }) first |
-| E003 | error | Smoke test failed (app won't start) | Suggest Skill({ skill: "quality-debug" }) |
+| E002 | error | Phase not verified yet (no verification.json) | Suggest `/maestro-verify` first |
+| E003 | error | Smoke test failed (app won't start) | Suggest `/quality-debug` |
 | W001 | warning | One or more test scenarios failed | Auto-diagnose, suggest fix options |
-| W002 | warning | Coverage below threshold | Suggest Skill({ skill: "quality-test-gen" }) |
+| W002 | warning | Coverage below threshold | Suggest `/quality-test-gen` |
 </error_codes>
 
 <success_criteria>

package/.claude/commands/spec-add.md

@@ -43,7 +43,7 @@ Follow '~/.maestro/workflows/specs-add.md' completely.
 | Code | Severity | Description | Stage |
 |------|----------|-------------|-------|
 | E001 | fatal | Category and content are both required -- usage: `<type> <content>` | parse_input |
-| E002 | fatal | `.workflow/specs/` not initialized -- run Skill({ skill: "spec-setup" }) first | validate_entry |
+| E002 | fatal | `.workflow/specs/` not initialized -- run `/spec-setup` first | validate_entry |
 | E003 | fatal | Invalid category -- must be one of: bug, pattern, decision, rule, debug, test, review, validation | parse_input |
 </error_codes>
 
@@ -52,5 +52,5 @@ Follow '~/.maestro/workflows/specs-add.md' completely.
 - [ ] Entry appended to `.workflow/specs/learnings.md` with timestamp
 - [ ] Relevant spec file updated (if type is pattern/decision/rule)
 - [ ] Confirmation report displayed
-- [ ] Next step: Skill({ skill: "spec-load", args: "--category {type}" }) to verify, or continue current task
+- [ ] Next step: `/spec-load --category {type}` to verify, or continue current task
 </success_criteria>

package/.claude/commands/spec-load.md

@@ -48,7 +48,7 @@ Follow '~/.maestro/workflows/specs-load.md' completely.
 <error_codes>
 | Code | Severity | Description | Stage |
 |------|----------|-------------|-------|
-| E001 | fatal | `.workflow/specs/` not initialized -- run Skill({ skill: "spec-setup" }) first | detect_context |
+| E001 | fatal | `.workflow/specs/` not initialized -- run `/spec-setup` first | detect_context |
 | W001 | warning | No matching specs found for keyword -- showing all specs in category instead | load_specs |
 </error_codes>
 

package/.claude/commands/spec-setup.md

@@ -27,7 +27,7 @@ All output lands in `.workflow/specs/` and `.workflow/project-tech.json`.
 $ARGUMENTS (no arguments expected)
 
 **Preconditions:**
-- `.workflow/` directory must exist (created by Skill({ skill: "maestro-init" }))  # (see code: E001)
+- `.workflow/` directory must exist (created by `/maestro-init`)  # (see code: E001)
 - Project must contain source files to scan  # (see code: E002)
 </context>
 
@@ -38,7 +38,7 @@ Follow '~/.maestro/workflows/specs-setup.md' completely.
 <error_codes>
 | Code | Severity | Description | Stage |
 |------|----------|-------------|-------|
-| E001 | fatal | `.workflow/` directory not initialized -- run Skill({ skill: "maestro-init" }) first | parse_input |
+| E001 | fatal | `.workflow/` directory not initialized -- run `/maestro-init` first | parse_input |
 | E002 | fatal | No source files found in project -- nothing to scan | scan_codebase |
 | W001 | warning | Convention detection uncertain for one or more categories -- marked `[UNCERTAIN]` | generate_specs |
 </error_codes>
@@ -51,7 +51,7 @@ Follow '~/.maestro/workflows/specs-setup.md' completely.
 - [ ] `learnings.md` initialized with format instructions
 - [ ] `project-tech.json` written with detected tech stack
 - [ ] Report displayed with summary and next steps:
-  - Build codebase docs → Skill({ skill: "manage-codebase-rebuild" })
-  - Load specs for task → Skill({ skill: "spec-load" })
-  - Add new knowledge → Skill({ skill: "spec-add", args: "<type> <content>" })
+  - Build codebase docs → `/manage-codebase-rebuild`
+  - Load specs for task → `/spec-load`
+  - Add new knowledge → `/spec-add <type> <content>`
 </success_criteria>

package/.claude/commands/wiki-connect.md

@@ -137,15 +137,15 @@ After all updates:
 3. Display summary
 
 **Next-step routing:**
-- Generate knowledge digest → `Skill({ skill: "wiki-digest", args: "<topic>" })`
-- Follow-along on orphan → `Skill({ skill: "learn-follow", args: "<wiki-id>" })`
+- Generate knowledge digest → `/wiki-digest <topic>`
+- Follow-along on orphan → `/learn-follow <wiki-id>`
 - View full graph → `maestro wiki graph`
 </execution>
 
 <error_codes>
 | Code | Severity | Condition | Recovery |
 |------|----------|-----------|----------|
-| E001 | error | No wiki entries found (empty index) | Initialize wiki content first, or run `Skill({ skill: "maestro-init" })` |
+| E001 | error | No wiki entries found (empty index) | Initialize wiki content first, or run `/maestro-init` |
 | E002 | error | `maestro wiki` CLI not available | Check maestro installation |
 | W001 | warning | No connection candidates found above threshold | Lower --min-similarity or check if graph is already well-connected |
 | W002 | warning | Some wiki update calls failed during --fix | Partial application; retry failed entries manually |

package/.claude/commands/wiki-digest.md

@@ -171,11 +171,11 @@ For each knowledge gap identified in Stage 5:
 4. Display summary with key findings
 
 **Next-step routing:**
-- Deep dive on a theme → `Skill({ skill: "learn-follow", args: "<wiki-id>" })`
-- Fix graph gaps → `Skill({ skill: "wiki-connect", args: "--fix" })`
-- Decompose code for missing patterns → `Skill({ skill: "learn-decompose", args: "<path>" })`
+- Deep dive on a theme → `/learn-follow <wiki-id>`
+- Fix graph gaps → `/wiki-connect --fix`
+- Decompose code for missing patterns → `/learn-decompose <path>`
 - Create missing entries → `maestro wiki create --type <type> --slug <slug>`
-- Triage gap issues → `Skill({ skill: "manage-issue", args: "list --source wiki-digest" })`
+- Triage gap issues → `/manage-issue list --source wiki-digest`
 </execution>
 
 <error_codes>

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

@@ -176,17 +176,46 @@ const subjectArg = $ARGUMENTS
   .replace(/--yes|-y|--continue|--concurrency\s+\d+|-c\s+\d+|-q|--quick/g, '')
   .trim()
 
-// Detect phase mode vs scratch mode
-const isPhaseMode = /^\d+$/.test(subjectArg)
-const slug = isPhaseMode
-  ? `phase${subjectArg}`
-  : subjectArg.toLowerCase().replace(/[^a-z0-9]+/g, '-').substring(0, 40)
+// Auto-bootstrap state.json if missing
+if (!fileExists('.workflow/state.json')) {
+  Bash('mkdir -p .workflow/scratch/')
+  writeMinimalStateJson()  // { project: null, status: "active", current_milestone: null, artifacts: [] }
+}
 
-const dateStr = getUtc8ISOString().substring(0, 10).replace(/-/g, '')
+// Scope determination (per scratch-milestone-architecture)
+const state = JSON.parse(Read('.workflow/state.json'))
+let scope, slug, phaseNum = null
+
+if (subjectArg === '') {
+  // No args → milestone-wide
+  if (state.current_milestone && fileExists('.workflow/roadmap.md')) {
+    scope = 'milestone'
+    slug = slugify(state.milestones.find(m => m.id === state.current_milestone)?.name || state.current_milestone)
+  } else {
+    ERROR('E001: No args and no roadmap — provide topic text or create roadmap first')
+  }
+} else if (/^\d+$/.test(subjectArg)) {
+  // Phase number
+  if (state.current_milestone && fileExists('.workflow/roadmap.md')) {
+    scope = 'phase'
+    phaseNum = parseInt(subjectArg)
+    slug = resolvePhaseSlugFromRoadmap(phaseNum)  // parse roadmap.md for phase N slug
+  } else {
+    ERROR('Phase number requires init + roadmap')
+  }
+} else {
+  // Text → adhoc or standalone
+  slug = subjectArg.toLowerCase().replace(/[^a-z0-9]+/g, '-').substring(0, 40)
+  scope = state.current_milestone ? 'adhoc' : 'standalone'
+}
+
+const dateStr = getUtc8ISOString().substring(0, 10)
 const sessionId = `analyze-${slug}-${dateStr}`
 const sessionFolder = `.workflow/.csv-wave/${sessionId}`
+const scratchDir = `.workflow/scratch/analyze-${slug}-${dateStr}`
 
 Bash(`mkdir -p ${sessionFolder}`)
+Bash(`mkdir -p ${scratchDir}`)
 ```
 
 ---
@@ -197,14 +226,13 @@ Bash(`mkdir -p ${sessionFolder}`)
 
 **Decomposition Rules**:
 
-1. **Mode detection**: Number = phase mode (resolve `.workflow/phases/{NN}-{slug}/`), text = scratch mode
-2. **Context loading** (phase mode):
+1. **Scope detection**: Already determined in Session Initialization (milestone/phase/adhoc/standalone)
+2. **Context loading** (milestone/phase scope):
    - Read `.workflow/project.md` -- project vision and constraints
    - Read `.workflow/roadmap.md` -- phase structure and dependencies
-   - Read phase `index.json` -- goal, success_criteria
-   - Read `.brainstorming/guidance-specification.md` (if exists) -- detailed requirements from brainstorm
-   - Read `.brainstorming/feature-index.json` (if exists) -- feature decomposition
-   - Read prior phases' `context.md` files -- skip already-decided areas
+   - Read `.workflow/state.json` → `current_milestone`, `artifacts[]`, `accumulated_context`
+   - Find prior analyze artifacts from `state.json.artifacts[]` (type=analyze, same milestone) → load their `context.md`
+   - Find brainstorm artifacts from `state.json.artifacts[]` (type=brainstorm, same milestone) → load `guidance-specification.md`
    - Load project specs: `maestro spec load --category planning`
 
 3. **Quick mode routing**: If QUICK_MODE, generate only wave 3 (synthesis/decide) task in CSV. Skip exploration and scoring.
@@ -457,8 +485,18 @@ IF deferred_items.length > 0:
   Print: "Created {N} deferred issues for tracking"
 ```
 
-7. Update phase `index.json` with analysis status (if phase mode)
-8. Display summary
+7. **Register artifact in state.json**:
+   ```
+   Read .workflow/state.json
+   next_id = max ANL-NNN + 1 (or 1 if none)
+   Push artifact: { id: "ANL-{next_id}", type: "analyze", milestone: current_milestone,
+     phase: phaseNum, scope: scope, path: scratchDir (relative to .workflow/),
+     status: "completed", depends_on: null, harvested: false,
+     created_at: session_start, completed_at: now() }
+   Write state.json (atomic)
+   ```
+8. Copy final outputs (context.md, analysis.md, conclusions.json) from CSV session folder to `scratchDir`
+9. Display summary
 
 ---