maestro-flow 0.3.7 → 0.3.9

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

@@ -22,7 +22,7 @@ Post-execution multi-perspective retrospective (复盘) for completed phases. Co
 
 <deferred_reading>
 - @~/.maestro/workflows/issue.md (issues.jsonl schema for auto-creation)
-- @~/.maestro/workflows/memory.md (Part B for note routing via manage-memory-capture)
+- @~/.maestro/workflows/learn.md (tip routing via manage-learn tip)
 - @~/.maestro/workflows/verify.md (verification.json schema for quality lens parsing)
 - @~/.maestro/workflows/review.md (review.json schema for quality lens parsing)
 </deferred_reading>
@@ -47,7 +47,7 @@ Arguments: $ARGUMENTS
 - `.workflow/phases/{NN}-{slug}/retrospective.json` — structured record
 - `.workflow/specs/SPEC-retro-*.md` — spec stubs (one per spec-routed insight)
 - `.workflow/issues/issues.jsonl` — appended issue rows (`source: "retrospective"`)
-- `.workflow/memory/TIP-*.md` — memory tips (via `manage-memory-capture` skill)
+- `.workflow/learning/lessons.jsonl` — tips routed via `manage-learn tip` (formerly manage-memory-capture)
 - `.workflow/learning/lessons.jsonl` — append-only insight log
 - `.workflow/learning/learning-index.json` — searchable index
 
@@ -64,7 +64,7 @@ Follow `~/.maestro/workflows/retrospective.md` Stages 1–8 in order. Key invari
 1. **Read-only until Stage 6** — Stages 1–5 must not write anything except the in-memory retrospective record.
 2. **Parallel lens dispatch** — Stage 4 spawns one Agent per active lens in a single message (multiple Agent tool calls). All agents use `subagent_type: "general-purpose"` and `run_in_background: false`.
 3. **Match canonical issues schema** — Stage 6 issue routing must produce rows that pass `jq` parsing and match the schema in `workflows/issue.md` Step 4 exactly (status `"open"`, full `issue_history` entry, all required fields).
-4. **Reuse `manage-memory-capture` for note routing** — do not duplicate the memory pipeline; invoke via `Skill()`.
+4. **Reuse `manage-learn tip` for note routing** — do not duplicate the learning pipeline; invoke via `Skill({ skill: "manage-learn", args: "tip ..." })`.
 5. **Backward-compat with phase-transition** — append a one-line summary per insight to `.workflow/specs/learnings.md` if and only if that file already exists. Never create it.
 6. **Stable insight IDs** — `INS-{8 hex}` from `hash(phase_num + lens + title)` so re-runs do not duplicate.
 7. **Archive before overwrite** — if existing `retrospective.{md,json}` are being replaced, move them to `{phase_dir}/.history/` with a timestamp suffix first.
@@ -73,14 +73,14 @@ 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 |
 | E005 | error | Phase argument out of range / phase directory not found | scan_unreviewed |
 | W001 | warning | One or more lens agents failed — proceeding with partial coverage | multi_lens_analysis |
 | W002 | warning | Existing retrospective.json found and not `--all` — prompted user to overwrite | scan_unreviewed |
-| W003 | warning | `manage-memory-capture` did not return parseable TIP id; fell back to direct write | route_outputs |
+| W003 | warning | `manage-learn tip` did not return parseable INS id; fell back to direct write | route_outputs |
 | W004 | warning | `--compare` target phase has no retrospective.json; delta omitted | load_artifacts |
 </error_codes>
 
@@ -94,10 +94,10 @@ Follow `~/.maestro/workflows/retrospective.md` Stages 1–8 in order. Key invari
 - [ ] If routing enabled (default): every recommendation either created an artifact or was explicitly skipped by user
 - [ ] Spec stubs (if any) written to `.workflow/specs/SPEC-retro-*.md` with proper frontmatter
 - [ ] Issue rows (if any) match canonical issues.jsonl schema (status "open", full issue_history, all required fields)
-- [ ] Note tips (if any) created via `Skill({ skill: "manage-memory-capture", args: "tip ..." })`
+- [ ] Note tips (if any) created via `Skill({ skill: "manage-learn", args: "tip ..." })`
 - [ ] `lessons.jsonl` appended with one row per insight regardless of routing target
 - [ ] `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

@@ -1,7 +1,7 @@
 ---
 name: spec-load
-description: Load relevant specs for current context (used by agents before execution)
-argument-hint: "[--category <type>] [keyword]"
+description: Load relevant specs and lessons for current context (used by agents before execution)
+argument-hint: "[--category <type>] [--with-lessons] [keyword]"
 allowed-tools:
   - Read
   - Bash
@@ -36,6 +36,9 @@ $ARGUMENTS -- optional `--category <type>` flag and/or keyword to filter specs
 
 **Keyword:** If provided, search within loaded files for matching sections.
 If no arguments, loads all specs for the active phase/task context.
+
+**Flags:**
+- `--with-lessons` — Also search `.workflow/learning/lessons.jsonl` for entries with `category: "gotcha"`, `"antipattern"`, or `"pattern"` relevant to the keyword or current context. Appends matched lessons after spec output. This bridges the gap between specs (prescriptive rules) and lessons (discovered knowledge).
 </context>
 
 <execution>
@@ -45,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>
 
@@ -53,6 +56,8 @@ Follow '~/.maestro/workflows/specs-load.md' completely.
 - [ ] Category filter parsed correctly (or defaults to all)
 - [ ] Spec files resolved and read
 - [ ] Keyword filtering applied if provided
+- [ ] If `--with-lessons`: lessons.jsonl searched for gotcha/antipattern/pattern entries matching context
+- [ ] If `--with-lessons`: matched lessons displayed after specs (max 10, newest first)
 - [ ] Results displayed with file:line references
 - [ ] Relevant specs loaded into agent context
 - [ ] Next step: proceed with current task using loaded specs as context

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

@@ -17,6 +17,10 @@ Knowledge synthesis command that generates actionable digests from the wiki know
 Unlike `maestro wiki list` which shows raw entries, this command synthesizes and interprets the knowledge base, producing a curated summary with gap analysis and recommended next actions.
 </purpose>
 
+<deferred_reading>
+- @~/.maestro/workflows/issue.md (issues.jsonl canonical schema for `--create-issues` routing)
+</deferred_reading>
+
 <context>
 Arguments: $ARGUMENTS
 
@@ -29,10 +33,12 @@ Arguments: $ARGUMENTS
 **Flags:**
 - `--format brief` — Compact summary, one paragraph per theme (default)
 - `--format full` — Detailed digest with per-entry summaries and full gap analysis
+- `--create-issues` — Auto-create `type: "knowledge-gap"` entries in `.workflow/issues/issues.jsonl` for each identified gap (closes the discovery→action loop)
 
 **Storage written:**
 - `.workflow/learning/digest-{slug}-{YYYY-MM-DD}.md` — Digest document
 - `.workflow/learning/lessons.jsonl` — Meta-insights about knowledge structure (source: "wiki-digest")
+- `.workflow/issues/issues.jsonl` — Knowledge-gap issues (only when `--create-issues`)
 
 **Storage read (via maestro wiki CLI, offline mode):**
 - `maestro wiki list --json` — All entries (or filtered)
@@ -139,7 +145,24 @@ Produce `.workflow/learning/digest-{slug}-{date}.md`:
 2. ...
 ```
 
-### Stage 7: Persist
+### Stage 7: Gap → Issue Routing (if --create-issues)
+For each knowledge gap identified in Stage 5:
+1. Check `.workflow/issues/issues.jsonl` for existing gap with same theme + type
+2. If not duplicate, append to `issues.jsonl` using the canonical schema from `~/.maestro/workflows/issue.md` Step 4:
+   - `id`: `ISS-XXXXXXXX-NNN` format (8 hex hash + sequence)
+   - `title`: "Knowledge gap: {gap description}"
+   - `type`: "knowledge-gap"
+   - `status`: "open"
+   - `severity`: "low"
+   - `priority`: "low"
+   - `source`: "wiki-digest"
+   - `description`: "Theme: {theme}, Missing type: {type}. Suggested action: {action}"
+   - `tags`: ["knowledge-gap", "{theme-slug}"]
+   - `created`: ISO date
+   - `issue_history`: initial entry with `action: "created"`, `by: "wiki-digest"`, `timestamp`
+3. Report created issue count
+
+### Stage 8: Persist
 1. Write digest file
 2. Append meta-insights to `lessons.jsonl`:
    - `source: "wiki-digest"`, `category: "technique"`
@@ -148,10 +171,11 @@ Produce `.workflow/learning/digest-{slug}-{date}.md`:
 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 → `/manage-issue list --source wiki-digest`
 </execution>
 
 <error_codes>
@@ -172,9 +196,10 @@ Produce `.workflow/learning/digest-{slug}-{date}.md`:
 - [ ] Cross-reference with lessons.jsonl completed
 - [ ] Coverage heatmap generated (type × theme matrix)
 - [ ] Knowledge gaps identified with suggested actions
+- [ ] If `--create-issues`: gap issues created in `issues.jsonl` (deduped)
 - [ ] Digest written to `digest-{slug}-{date}.md`
 - [ ] Meta-insights appended to `lessons.jsonl`
 - [ ] `learning-index.json` updated
-- [ ] No files modified outside `.workflow/learning/`
+- [ ] No files modified outside `.workflow/learning/` and `.workflow/issues/` (issues only when `--create-issues`)
 - [ ] Summary displayed with key findings and next-step routing
 </success_criteria>

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
 
 ---