maestro-flow 0.3.11 → 0.3.12

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

@@ -1,68 +1,98 @@
----
-name: maestro-fork
-description: Create git worktree for milestone-level parallel development, or sync existing worktree with main. Copies .workflow/ context into worktree since it is gitignored.
-argument-hint: "-m <milestone-number> [--base <branch>] [--sync]"
-allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
----
-
-<purpose>
-Create a git worktree for an entire milestone, enabling inter-milestone parallel development.
-All phases within the milestone are owned by the worktree. Since `.workflow/` is gitignored,
-this command explicitly copies project context and milestone phase directories into the worktree.
-
-Also supports `--sync` mode to pull latest main into an active worktree.
-</purpose>
-
-<required_reading>
-@~/.maestro/workflows/fork.md
-</required_reading>
-
-<context>
-$ARGUMENTS — milestone number and optional flags.
-
-**Modes:**
-| Mode | Trigger | Behavior |
-|------|---------|----------|
-| Fork | `-m 2` or `2` | Create worktree for milestone 2 |
-| Sync | `-m 2 --sync` | Sync existing worktree with main |
-
-**Flags:**
-- `-m <N>` or bare `<N>`: Milestone number
-- `--base <branch>`: Override base branch (default: HEAD)
-- `--sync`: Pull main into existing worktree, re-copy shared artifacts
-
-**Worktree layout:** `.worktrees/m{N}-{slug}/` with scoped `.workflow/`
-</context>
-
-<execution>
-Follow '~/.maestro/workflows/fork.md' completely.
-
-**Next steps:**
-- Fork → `cd {wt.path} && $maestro-analyze {first_phase}`
-- Sync → resume work in worktree
-</execution>
-
-<error_codes>
-| Code | Severity | Condition | Recovery |
-|------|----------|-----------|----------|
-| E001 | error | Project not initialized | Run maestro-init |
-| E002 | error | No roadmap found | Run maestro-roadmap |
-| E003 | error | Running inside a worktree | Run from main worktree |
-| E004 | error | No milestone number | Provide `-m <N>` |
-| E006 | error | Milestone out of range | Check available milestones |
-| E008 | error | Milestone already has active worktree | Merge or cleanup first |
-</error_codes>
-
-<success_criteria>
-Fork mode:
-- [ ] Milestone phases identified from roadmap
-- [ ] Git worktree created with branch `milestone/{slug}`
-- [ ] `.workflow/` context copied (all milestone + dependency phases)
-- [ ] `worktree-scope.json` written with owned phase numbers
-- [ ] `worktrees.json` registry updated in main worktree
-
-Sync mode:
-- [ ] Git merge main into worktree branch
-- [ ] Shared artifacts re-copied
-- [ ] Conflicts reported if any
-</success_criteria>
+---
+name: maestro-fork
+description: Create git worktree for milestone-level parallel development, or sync existing worktree with main. Copies .workflow/ context and scratch artifacts into worktree since .workflow/ is gitignored.
+argument-hint: "-m <milestone-number> [--base <branch>] [--sync]"
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
+---
+
+<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 milestone scratch artifacts into the worktree.
+
+Also supports `--sync` mode to pull latest main into an active worktree.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/fork.md
+</required_reading>
+
+<context>
+$ARGUMENTS — milestone number and optional flags.
+
+**Modes:**
+| Mode | Trigger | Behavior |
+|------|---------|----------|
+| Fork | `-m 2` or `2` | Create worktree for milestone 2 |
+| Sync | `-m 2 --sync` | Sync existing worktree with main |
+
+**Flags:**
+- `-m <N>` or bare `<N>`: Milestone number
+- `--base <branch>`: Override base branch (default: HEAD)
+- `--sync`: Pull main into existing worktree, re-copy shared artifacts
+
+**Worktree layout:**
+```
+.worktrees/m{N}-{slug}/
+├── .workflow/
+│   ├── worktree-scope.json     (milestone scope marker)
+│   ├── state.json              (scoped — this milestone's artifacts only)
+│   ├── project.md, roadmap.md, config.json, specs/  (read-only copies)
+│   └── scratch/                (milestone's existing + new artifacts)
+└── <source code>
+```
+
+**Artifact scoping:**
+Fork copies scratch artifacts belonging to the target milestone (filtered from `state.json.artifacts[]` where `milestone == target`). New work creates scratch artifacts normally, registered in the worktree's local `state.json`.
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/fork.md' completely.
+
+**Fork flow:**
+1. Validate: initialized, roadmap exists, not inside worktree, milestone not forked
+2. Resolve milestone: `state.json.milestones[N-1]`
+3. Create worktree: `git worktree add -b milestone/{slug} .worktrees/m{N}-{slug} HEAD`
+4. Copy `.workflow/`: shared files + milestone scratch artifacts
+5. Write `worktree-scope.json` with milestone scope
+6. Write scoped `state.json` (this milestone's artifacts only)
+7. Update main: `worktrees.json` registry, mark milestone `"forked"`
+
+**Sync flow:**
+1. Find worktree from `worktrees.json`
+2. `cd worktree && git merge main`
+3. Re-copy shared files (project.md, roadmap.md, config.json, specs/)
+
+**Next steps:**
+- Fork → `cd {wt.path} && $maestro-analyze`
+- Sync → resume work in worktree
+</execution>
+
+<error_codes>
+| Code | Severity | Condition | Recovery |
+|------|----------|-----------|----------|
+| E001 | error | Project not initialized | Run maestro-init |
+| E002 | error | No roadmap found | Run maestro-roadmap |
+| E003 | error | Running inside a worktree | Run from main worktree |
+| E004 | error | No milestone number | Provide `-m <N>` |
+| E006 | error | Milestone out of range | Check available milestones |
+| 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 (this milestone's artifacts only)
+- [ ] `worktrees.json` registry updated in main worktree
+- [ ] Milestone marked `"forked"` in main state.json
+
+Sync mode:
+- [ ] Git merge main into worktree branch
+- [ ] Shared artifacts re-copied
+- [ ] Conflicts reported if any
+</success_criteria>

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

@@ -87,7 +87,7 @@ Read the following templates:
 ### Step 5: Create .workflow/ Structure
 
 ```bash
-mkdir -p .workflow/specs .workflow/phases .workflow/scratch .workflow/codebase
+mkdir -p .workflow/specs .workflow/scratch .workflow/codebase
 ```
 
 ### Step 6: Write project.md
@@ -103,9 +103,10 @@ Write to `.workflow/project.md`.
 ### Step 7: Write state.json
 
 Initialize state from template:
-- `current_phase`: null
 - `current_milestone`: null
+- `current_task_id`: null
 - `status`: "initialized"
+- `artifacts`: []
 
 Write to `.workflow/state.json`.
 
@@ -122,7 +123,7 @@ Write to `.workflow/config.json`.
 
 Create convention files in `.workflow/specs/`:
 - `conventions.md` — detected or specified coding conventions
-- `learnings.md` — empty, populated during phase transitions
+- `learnings.md` — empty, populated during execute summaries extraction
 
 ### Step 10: Completion Report
 

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

@@ -1,62 +1,69 @@
----
-name: maestro-merge
-description: Two-phase merge of milestone worktree branch back — git merge first, artifact sync only on success. Registry health check, pre-merge rebase, atomic state reconciliation.
-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 workflow artifacts,
-and reconcile project state. 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 not all phases completed
-- `--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. Phase readiness validation → 3. Pre-merge rebase →
-4. Git merge (source) → 5. Artifact sync (.workflow/) → 6. State reconciliation → 7. Cleanup
-</context>
-
-<execution>
-Follow '~/.maestro/workflows/merge.md' completely.
-
-**Next steps:**
-- View dashboard → `$manage-status`
-- Audit milestone → `$maestro-milestone-audit`
-</execution>
-
-<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 phases 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)
-- [ ] Phase artifacts synced to main `.workflow/`
-- [ ] `state.json` reconciled
-- [ ] Worktree removed and branch deleted (unless --no-cleanup)
-- [ ] Registry updated
-</success_criteria>
+---
+name: maestro-merge
+description: Two-phase merge of milestone worktree branch back — git merge first, scratch artifact sync and registry reconciliation only on success.
+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.
+
+**Next steps:**
+- View dashboard → `$manage-status`
+- Audit milestone → `$maestro-milestone-audit`
+</execution>
+
+<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-ui-design/SKILL.md

@@ -54,7 +54,7 @@ When `--yes` or `-y`: Skip interactive selection, auto-pick top-scored variant,
 ### Step 1: Parse Input and Resolve Target
 
 1. Parse flags from `$ARGUMENTS`: `--styles N`, `--stack`, `--targets`, `--persist`, `--full`, `-y`
-2. **Phase mode** (number): resolve `.workflow/phases/{NN}-*/` directory
+2. **Phase mode** (number): resolve via state.json artifact registry to `.workflow/scratch/{type}-{slug}-{date}/`; legacy fallback to `.workflow/phases/{NN}-*/`
 3. **Scratch mode** (text): create `.workflow/scratch/ui-design-{slug}-{date}/` with minimal index.json
 4. Create output directories:
    ```bash

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

@@ -83,15 +83,15 @@ When `--yes` or `-y`: Auto-confirm check decomposition, skip interactive validat
 
 ```csv
 id,title,description,layer,phase_dir,check_type,deps,context_from,wave,status,findings,gaps_found,fix_plan,error
-"1","Truth: User can see existing messages","Verify observable behavior: user can see existing messages by checking supporting artifacts, API calls, and render logic.","truth",".workflow/phases/03-chat/","observable_behavior","","","1","","","","",""
-"2","Truth: User can send new messages","Verify observable behavior: user can send new messages by checking form submission, API POST, and state update.","truth",".workflow/phases/03-chat/","observable_behavior","","","1","","","","",""
-"3","Artifact Exists: src/components/Chat.tsx","Check L1 existence: verify file src/components/Chat.tsx exists on disk.","artifact",".workflow/phases/03-chat/","exists","","","1","","","","",""
-"4","Artifact Exists: src/api/chat.ts","Check L1 existence: verify file src/api/chat.ts exists on disk.","artifact",".workflow/phases/03-chat/","exists","","","1","","","","",""
-"5","Artifact Substance: src/components/Chat.tsx","Check L2 substance: verify src/components/Chat.tsx has real implementation (not stub/placeholder). Minimum logic threshold, no placeholder markers.","artifact",".workflow/phases/03-chat/","substance","3","3","2","","","","",""
-"6","Artifact Substance: src/api/chat.ts","Check L2 substance: verify src/api/chat.ts has real implementation (not stub/placeholder).","artifact",".workflow/phases/03-chat/","substance","4","4","2","","","","",""
-"7","Wiring: Chat.tsx -> /api/chat","Check L3 wiring: verify Chat.tsx imports and calls /api/chat endpoints. Check import statements and actual usage beyond imports.","wiring",".workflow/phases/03-chat/","import_usage","3;4","3;4","2","","","","",""
-"8","Anti-Pattern Scan","Scan all modified files for TODO/FIXME/XXX/HACK, placeholder content, empty returns, log-only functions, hardcoded test data, disabled tests. Categorize as Blocker/Warning/Info.","antipattern",".workflow/phases/03-chat/","pattern_scan","1;2;5;6;7","1;2;5;6;7","3","","","","",""
-"9","Nyquist Test Coverage Audit","Map requirements to test files. Classify each as COVERED/PARTIAL/MISSING. Detect test framework, run coverage if available.","nyquist",".workflow/phases/03-chat/","test_coverage","1;2;5;6;7","1;2;5;6;7","3","","","","",""
+"1","Truth: User can see existing messages","Verify observable behavior: user can see existing messages by checking supporting artifacts, API calls, and render logic.","truth",".workflow/scratch/plan-chat-2026/","observable_behavior","","","1","","","","",""
+"2","Truth: User can send new messages","Verify observable behavior: user can send new messages by checking form submission, API POST, and state update.","truth",".workflow/scratch/plan-chat-2026/","observable_behavior","","","1","","","","",""
+"3","Artifact Exists: src/components/Chat.tsx","Check L1 existence: verify file src/components/Chat.tsx exists on disk.","artifact",".workflow/scratch/plan-chat-2026/","exists","","","1","","","","",""
+"4","Artifact Exists: src/api/chat.ts","Check L1 existence: verify file src/api/chat.ts exists on disk.","artifact",".workflow/scratch/plan-chat-2026/","exists","","","1","","","","",""
+"5","Artifact Substance: src/components/Chat.tsx","Check L2 substance: verify src/components/Chat.tsx has real implementation (not stub/placeholder). Minimum logic threshold, no placeholder markers.","artifact",".workflow/scratch/plan-chat-2026/","substance","3","3","2","","","","",""
+"6","Artifact Substance: src/api/chat.ts","Check L2 substance: verify src/api/chat.ts has real implementation (not stub/placeholder).","artifact",".workflow/scratch/plan-chat-2026/","substance","4","4","2","","","","",""
+"7","Wiring: Chat.tsx -> /api/chat","Check L3 wiring: verify Chat.tsx imports and calls /api/chat endpoints. Check import statements and actual usage beyond imports.","wiring",".workflow/scratch/plan-chat-2026/","import_usage","3;4","3;4","2","","","","",""
+"8","Anti-Pattern Scan","Scan all modified files for TODO/FIXME/XXX/HACK, placeholder content, empty returns, log-only functions, hardcoded test data, disabled tests. Categorize as Blocker/Warning/Info.","antipattern",".workflow/scratch/plan-chat-2026/","pattern_scan","1;2;5;6;7","1;2;5;6;7","3","","","","",""
+"9","Nyquist Test Coverage Audit","Map requirements to test files. Classify each as COVERED/PARTIAL/MISSING. Detect test framework, run coverage if available.","nyquist",".workflow/scratch/plan-chat-2026/","test_coverage","1;2;5;6;7","1;2;5;6;7","3","","","","",""
 ```
 
 **Columns**:
@@ -102,7 +102,7 @@ id,title,description,layer,phase_dir,check_type,deps,context_from,wave,status,fi
 | `title` | Input | Short check title |
 | `description` | Input | Detailed verification instructions for this check |
 | `layer` | Input | Verification layer: truth/artifact/wiring/antipattern/nyquist |
-| `phase_dir` | Input | Phase directory path (e.g., `.workflow/phases/03-chat/`) |
+| `phase_dir` | Input | Target directory path (e.g., `.workflow/scratch/plan-chat-2026/`; legacy: `.workflow/phases/03-chat/`) |
 | `check_type` | Input | Specific check type: observable_behavior/exists/substance/import_usage/pattern_scan/test_coverage |
 | `deps` | Input | Semicolon-separated dependency task IDs |
 | `context_from` | Input | Semicolon-separated task IDs whose findings this task needs |
@@ -191,7 +191,7 @@ Bash(`mkdir -p ${sessionFolder}`)
 
 **Decomposition Rules**:
 
-1. **Phase resolution**: Resolve `{phaseArg}` to `.workflow/phases/{NN}-{slug}/`
+1. **Phase resolution**: Resolve `{phaseArg}` via artifact registry in `state.json` to `.workflow/scratch/{type}-{slug}-{date}/`; legacy fallback to `.workflow/phases/{NN}-{slug}/`
 2. **Artifact loading**: Read from phase directory:
    - `index.json` -- success_criteria (ground truth for verification)
    - `plan.json` -- original plan with task_ids
@@ -528,7 +528,7 @@ echo '{"ts":"<ISO>","worker":"{id}","type":"verification_gap","data":{"gap_id":"
 
 | Error | Resolution |
 |-------|------------|
-| Phase directory not found | Abort with error: "Phase {N} not found" |
+| Phase directory not found | Resolve via state.json artifact registry; legacy fallback to `.workflow/phases/`; abort if neither found |
 | No execution results found | Abort with error: "No completed tasks found -- run execute first" |
 | No summaries found | Warn, proceed with task file analysis only |
 | No success_criteria in index.json | Derive must-haves from phase goal (fallback) |

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

@@ -98,7 +98,7 @@ Verify `.workflow/` exists (E001 if not).
 | gotcha, surprising, unexpected, watch out | gotcha |
 | technique, approach, method, pattern for | technique |
 
-2. **Auto-link phase**: Read `.workflow/state.json` for `current_phase`. Resolve matching directory slug from `.workflow/phases/`. `--phase 0` forces null.
+2. **Auto-link phase**: Read `.workflow/state.json` for `current_phase`. Resolve matching directory slug via artifact registry in `state.json` to `.workflow/scratch/{type}-{slug}-{date}/`; legacy fallback to `.workflow/phases/`. `--phase 0` forces null.
 
 3. **Generate stable INS-id**: `INS-{8 lowercase hex}` from `hash(insightText + timestamp)`.
 

package/.codex/skills/manage-status/SKILL.md

@@ -19,8 +19,8 @@ $manage-status
 Reads from:
 - `.workflow/state.json` — project-level state machine
 - `.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/*/index.json` — per-phase metadata and progress (resolved via state.json artifact registry; legacy fallback: `.workflow/phases/*/index.json`)
+- `.workflow/scratch/*/.task/TASK-*.json` — individual task statuses (legacy fallback: `.workflow/phases/*/.task/TASK-*.json`)
 </context>
 
 <execution>
@@ -38,8 +38,8 @@ test -f .workflow/state.json || exit 1  # E002: state missing
 Read all state sources:
 - `.workflow/state.json` -- project-level state machine
 - `.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/*/index.json` -- per-phase metadata and progress (resolved via state.json artifact registry; legacy fallback: `.workflow/phases/*/index.json`)
+- `.workflow/scratch/*/.task/TASK-*.json` -- individual task statuses (legacy fallback: `.workflow/phases/*/.task/TASK-*.json`)
 
 ### Step 3: Calculate Progress
 

package/.codex/skills/quality-business-test/SKILL.md

@@ -71,7 +71,7 @@ $quality-business-test "3 --auto"                   # skip plan confirmation
 ### Step 1: Resolve Target & Load Spec Package
 
 1. Parse `$ARGUMENTS` for phase number and flags
-2. Set `PHASE_DIR = .workflow/phases/{NN}-{slug}/`
+2. Resolve `PHASE_DIR` via artifact registry in `state.json` to `.workflow/scratch/{type}-{slug}-{date}/`; legacy fallback to `.workflow/phases/{NN}-{slug}/`
 3. Load `index.json` -> find `spec_ref` -> locate `.workflow/.spec/SPEC-xxx/`
 4. **Full mode**: Read `requirements/_index.md` + all `REQ-*.md` + `NFR-*.md` + `architecture/_index.md` + `epics/EPIC-*.md`
 5. **Degraded mode** (no spec package): Read `index.json.success_criteria` + `plan.json` convergence criteria + `.summaries/TASK-*.md`
@@ -206,7 +206,7 @@ FOR each REQ:
 | Code | Severity | Condition | Recovery |
 |------|----------|-----------|----------|
 | E001 | error | Phase number required | Prompt user for phase number |
-| E002 | error | Phase directory not found | Verify phase exists in .workflow/phases/ |
+| E002 | error | Phase directory not found | Resolve via state.json artifact registry; legacy fallback to `.workflow/phases/` |
 | E003 | error | No spec package AND no success_criteria | Run maestro-spec-generate or maestro-plan first |
 | E004 | error | L1 critical failures block L2/L3 | Fix blockers via quality-debug |
 | W001 | warning | Degraded mode (no spec package) | Consider running maestro-spec-generate |

package/.codex/skills/quality-integration-test/SKILL.md

@@ -213,7 +213,7 @@ Write(`${sessionFolder}/reflection-log.md`,
 
 **Decomposition Rules**:
 
-1. **Phase resolution**: Resolve `{phaseArg}` to `.workflow/phases/{NN}-{slug}/`
+1. **Phase resolution**: Resolve `{phaseArg}` via artifact registry in `state.json` to `.workflow/scratch/{type}-{slug}-{date}/`; legacy fallback to `.workflow/phases/{NN}-{slug}/`
 
 2. **Codebase exploration**:
    - Cross-module imports and dependencies

package/.codex/skills/quality-retrospective/SKILL.md

@@ -66,8 +66,8 @@ $quality-retrospective "3 --compare 2 --auto-yes"
 When `--auto-yes`: Accept all routing recommendations without prompting. Route all insights automatically.
 
 **Storage written**:
-- `.workflow/phases/{NN}-{slug}/retrospective.md` -- human-readable record
-- `.workflow/phases/{NN}-{slug}/retrospective.json` -- structured record
+- `{target_dir}/retrospective.md` -- human-readable record (target_dir resolved via state.json artifact registry to `.workflow/scratch/{type}-{slug}-{date}/`; legacy fallback to `.workflow/phases/{NN}-{slug}/`)
+- `{target_dir}/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)
@@ -75,8 +75,8 @@ When `--auto-yes`: Accept all routing recommendations without prompting. Route a
 - `.workflow/learning/learning-index.json` -- updated searchable index
 
 **Storage read (never modified)**:
-- `.workflow/phases/{NN}-{slug}/index.json`, `plan.json`, `verification.json`, `review.json`, `uat.md`
-- `.workflow/phases/{NN}-{slug}/.task/TASK-*.json`, `.summaries/TASK-*-summary.md`
+- `{target_dir}/index.json`, `plan.json`, `verification.json`, `review.json`, `uat.md`
+- `{target_dir}/.task/TASK-*.json`, `.summaries/TASK-*-summary.md`
 - `.workflow/issues/issues.jsonl`, `.workflow/state.json`
 
 ### Agent Registry
@@ -151,7 +151,7 @@ functions.update_plan({
 Validate `--lens` values. If `--compare <M>` present, require single mode.
 
 **Stage 2: Validate phase artifacts**. For each target phase:
-- Phase directory `.workflow/phases/{NN}-{slug}/` must exist
+- Phase directory must exist (resolved via state.json artifact registry to `.workflow/scratch/{type}-{slug}-{date}/`; legacy fallback to `.workflow/phases/{NN}-{slug}/`)
 - `index.json` must show `status: "completed"`
 - `.task/` directory must exist with at least one `TASK-*.json`
 - If existing `retrospective.json` found and not `--all`: emit W002, prompt overwrite
@@ -404,7 +404,7 @@ If `!AUTO_YES`: present routing table and ask confirmation before routing each g
 ```javascript
 functions.apply_patch:
 *** Begin Patch
-*** Add File: .workflow/phases/<NN>-<slug>/retrospective.json
+*** Add File: <target_dir>/retrospective.json
 +{
 +  "phase": <N>,
 +  "phase_slug": "<slug>",
@@ -415,7 +415,7 @@ functions.apply_patch:
 +  "distilled_insights": <insights_array>,
 +  "routing_summary": <routing_summary>
 +}
-*** Add File: .workflow/phases/<NN>-<slug>/retrospective.md
+*** Add File: <target_dir>/retrospective.md
 +# Retrospective: Phase <N> -- <slug>
 +
 +> Generated: <ISO> | Lenses: technical, process, quality, decision

package/.codex/skills/quality-review/SKILL.md

@@ -175,7 +175,7 @@ Bash(`mkdir -p ${sessionFolder}`)
 
 **Decomposition Rules**:
 
-1. **Phase resolution**: Resolve `{phaseArg}` to `.workflow/phases/{NN}-{slug}/`
+1. **Phase resolution**: Resolve `{phaseArg}` via artifact registry in `state.json` to `.workflow/scratch/{type}-{slug}-{date}/`; legacy fallback to `.workflow/phases/{NN}-{slug}/`
 2. **File collection**: Read `.task/TASK-*.json` -> collect all `files[].path` where action != "read"
 3. **Level detection**:
 
@@ -332,7 +332,7 @@ spawn_agents_on_csv({
 | standard | critical + high |
 | deep | critical + high + medium |
 
-7. **Phase index update**: Update `.workflow/phases/{phase}/index.json` with review status.
+7. **Phase index update**: Update `{phase_dir}/index.json` with review status.
 
 8. Display summary.
 

package/.codex/skills/quality-test/SKILL.md

@@ -49,15 +49,15 @@ No auto mode -- UAT is inherently interactive. `--auto-fix` only automates gap c
 ### Step 1: Resolve Target
 
 1. Parse `$ARGUMENTS` for phase number, scratch task ID, or flags
-2. **Phase mode**: set `PHASE_DIR = .workflow/phases/{NN}-{slug}/`
+2. **Phase mode**: resolve `PHASE_DIR` via artifact registry in `state.json` to `.workflow/scratch/{type}-{slug}-{date}/`; legacy fallback to `.workflow/phases/{NN}-{slug}/`
 3. **Scratch mode**: set `SCRATCH_DIR = .workflow/scratch/{id}/`
 4. Validate target exists and has `verification.json` -- if missing: **E002**
 
 ### Step 2: Check Active Sessions
 
 ```bash
-find .workflow/phases -name "uat.md" -type f 2>/dev/null | head -5
 find .workflow/scratch -name "uat.md" -type f 2>/dev/null | head -5
+find .workflow/phases -name "uat.md" -type f 2>/dev/null | head -5
 ```
 
 - If active sessions exist and no target specified: display session table, ask user to resume or start new

package/.codex/skills/quality-test-gen/SKILL.md

@@ -170,7 +170,7 @@ Bash(`mkdir -p ${sessionFolder}`)
 
 **Decomposition Rules**:
 
-1. **Phase resolution**: Resolve `{phaseArg}` to `.workflow/phases/{NN}-{slug}/`
+1. **Phase resolution**: Resolve `{phaseArg}` via artifact registry in `state.json` to `.workflow/scratch/{type}-{slug}-{date}/`; legacy fallback to `.workflow/phases/{NN}-{slug}/`
 
 2. **Test infrastructure discovery**:
    - Find config files: `jest.config.*`, `vitest.config.*`, `pytest.ini`, `.mocharc.*`

package/README.md

@@ -323,6 +323,8 @@ maestro/
 - **[Worktree Parallel Dev Guide](guide/worktree-guide.md)** — Milestone-level worktree parallelism: fork, sync, merge, scope enforcement, dashboard integration
 - **[Collab — User Guide](guide/team-lite-guide.md)** — Multi-person collaboration for 2-8 person teams: join, sync, activity awareness, conflict preflight, task management, namespace isolation
 - **[Collab — Design](guide/team-lite-design.md)** — Architecture, data model, namespace boundary between human-collab (`.workflow/collab/`) and agent-pipeline (`.workflow/.team/`) domains
+- **[MCP Tools Reference](guide/mcp-tools-guide.en.md)** — All 9 MCP endpoint tools: file ops (edit/write/read), team collaboration (msg/mailbox/task/agent), and persistent memory
+- **[CLI Commands Reference](guide/cli-commands-guide.en.md)** — All 21 terminal commands — install, delegate, coordinate, wiki, hooks, overlay, collab, and more
 
 ---
 

package/README.zh-CN.md

@@ -322,6 +322,8 @@ maestro/
 - **[Worktree 并行开发指南](guide/worktree-guide.md)** -- 里程碑级 worktree 并行: fork、sync、merge、scope 保护、Dashboard 集成
 - **[Collab 协作 -- 使用指南](guide/team-lite-guide.md)** -- 2-8 人小团队协作: 加入、同步、活动感知、冲突预检、任务管理、命名空间隔离
 - **[Collab 协作 -- 设计文档](guide/team-lite-design.md)** -- 架构、数据模型、人类协作域 (`.workflow/collab/`) 与智能体管线 (`.workflow/.team/`) 的命名空间边界
+- **[MCP 工具参考](guide/mcp-tools-guide.md)** -- 全部 9 个 MCP 端点工具：文件操作 (edit/write/read)、团队协作 (msg/mailbox/task/agent)、持久记忆
+- **[CLI 命令参考](guide/cli-commands-guide.md)** -- 全部 21 个终端命令 — 安装、委派、协调、Wiki、Hook、Overlay、协作等
 
 ---
 

package/dashboard/dist/assets/{ArtifactsPage-DZNCi6tn.js → ArtifactsPage-CUrrDGgN.js}

@@ -1,4 +1,4 @@
-import{d as W,r as d,A as J,j as e,F as C,o as xe,W as j,p as pe,V as ue,X as fe,n as Z,B as he}from"./index-DWG-WrzT.js";import{C as me}from"./code-CFN2uX9V.js";import{S as X}from"./search-SieXnOgr.js";import{u as Q}from"./shallow-Bme1JY57.js";import{F as M,T as ge}from"./TreeBrowser-Q12qobZs.js";import{M as ve}from"./MarkdownRenderer-X4af_WNb.js";import{C as ee}from"./chevron-right-Csu22t58.js";import{D as te}from"./folder-CWq_lAnf.js";import{C as re}from"./circle-CMrkbRNg.js";import{C as $}from"./circle-check-gYxxSYuH.js";import{A as be}from"./index-Do71weNR.js";import{m as N}from"./proxy-BKxDAKTj.js";/**
+import{d as W,r as d,A as J,j as e,F as C,o as xe,W as j,p as pe,V as ue,X as fe,n as Z,B as he}from"./index-C2Mcb4TJ.js";import{C as me}from"./code-Ble63Idz.js";import{S as X}from"./search-BS6fI6Bg.js";import{u as Q}from"./shallow-BXasQBvr.js";import{F as M,T as ge}from"./TreeBrowser-B9DHdULE.js";import{M as ve}from"./MarkdownRenderer-D7AehrnR.js";import{C as ee}from"./chevron-right-C7bVDreZ.js";import{D as te}from"./folder-B9ewx9LL.js";import{C as re}from"./circle-Qfgy4LB_.js";import{C as $}from"./circle-check-CEGgy3NV.js";import{A as be}from"./index-JTmGteaT.js";import{m as N}from"./proxy-D72Y8a4Y.js";/**
  * @license lucide-react v0.577.0 - ISC
  *
  * This source code is licensed under the ISC license.