maestro-flow 0.3.11 → 0.3.13

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

@@ -36,23 +36,56 @@ Phase or task: $ARGUMENTS (optional)
 - `--smoke` -- Run cold-start smoke tests before UAT (basic sanity: app starts, routes respond, no crash)
 - `--auto-fix` -- After diagnosis, auto-trigger gap-fix loop instead of asking user
 
-Context files resolved from target directory:
-- verification.json (must_haves, gaps from maestro-verify)
-- validation.json (coverage, requirement mapping)
-- review.json (findings from quality-review, if exists)
-- index.json (success_criteria, execution results)
-- plan.json (task overview)
-- .summaries/TASK-*.md (execution summaries)
-- uat.md (existing session, if resuming)
+**All context via state.json.artifacts[]:**
+
+```
+related = artifacts.filter(a =>
+  a.phase === target_phase && a.milestone === current_milestone
+).sort_by(completed_at asc)
+```
+
+Each artifact's type determines its outputs at `.workflow/{a.path}/`:
+- **execute** → .summaries/, .task/, verification.json, plan.json (test target source)
+- **verify** → verification.json (must_haves, gaps)
+- **review** → review.json (findings become additional test scenarios)
+- **debug** → understanding.md (confirmed root causes become regression tests)
+- **test** → uat.md (existing session, resumable)
+
+Extract conclusions from related artifacts that may affect this test session — review findings generate additional scenarios, debug root causes generate regression tests.
+
+**Output**: `TEST_DIR = .workflow/scratch/{YYYYMMDD}-test-P{N}-{slug}/` (P{N} = phase number, enables directory-level identification as state.json fallback)
 </context>
 
 <execution>
 Follow '~/.maestro/workflows/test.md' completely.
 
-**Review findings integration (when review.json exists):**
-- Extract critical/high findings from review.json.findings_by_dimension as additional test scenarios
-- These review-derived scenarios are prioritized and marked `source: "review_finding"`
-- When review.json verdict is "BLOCK" and review-finding tests fail, auto-enter gap-fix loop without user confirmation (Step 12 auto-fix condition)
+**Output writes to TEST_DIR** (`scratch/{YYYYMMDD}-test-P{N}-{slug}/`):
+- uat.md, test-plan.json, .tests/test-results.json, .tests/coverage-report.json
+
+**Review findings integration** (from related review artifacts):
+- Extract critical/high findings as additional test scenarios, marked `source: "review_finding"`
+- When review verdict is "BLOCK" and review-finding tests fail, auto-enter gap-fix loop
+
+**Debug root cause integration** (from related debug artifacts):
+- Generate regression test scenarios from confirmed root causes, marked `source: "debug_root_cause"`
+
+**Register artifact on completion:**
+```
+Append to state.json.artifacts[]:
+{
+  id: nextArtifactId(artifacts, "test"),  // TST-001
+  type: "test",
+  milestone: current_milestone,
+  phase: target_phase,
+  scope: "phase",
+  path: "scratch/{YYYYMMDD}-test-P{N}-{slug}",
+  status: issues == 0 ? "completed" : "failed",
+  depends_on: exec_art.id,
+  harvested: false,
+  created_at: start_time,
+  completed_at: now()
+}
+```
 
 **Next-step routing on completion:**
 - All tests pass → `/maestro-phase-transition {phase}`

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

@@ -0,0 +1,51 @@
+---
+name: spec-remove
+description: Remove a spec entry from a specs file by entry ID
+argument-hint: "<entry-id>"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - AskUserQuestion
+---
+<purpose>
+Remove a `<spec-entry>` from a specs file. Symmetric with `/spec-add`.
+Uses `maestro wiki remove-entry` for atomic removal with index auto-update.
+</purpose>
+
+<required_reading>
+@~/.maestro/workflows/specs-remove.md
+</required_reading>
+
+<context>
+$ARGUMENTS -- expects `<entry-id>` (e.g., `spec-learnings-003`, `spec-coding-conventions-001`)
+
+**Entry ID format**: `spec-{file-stem}-{NNN}` — the sub-node ID assigned by WikiIndexer when indexing `<spec-entry>` blocks.
+
+**Discovery**: Use `maestro wiki list --type spec --json` or `/spec-load --keyword <term>` to find entry IDs.
+</context>
+
+<execution>
+Follow '~/.maestro/workflows/specs-remove.md' completely.
+</execution>
+
+<error_codes>
+| Code | Severity | Description | Stage |
+|------|----------|-------------|-------|
+| E001 | fatal | Entry ID is required -- usage: `/spec-remove <entry-id>` | parse_input |
+| E002 | fatal | `.workflow/specs/` not initialized -- run `/spec-setup` first | validate |
+| E003 | fatal | Entry ID not found in wiki index | lookup |
+| E004 | fatal | Entry is not a spec sub-node (wrong type) | validate |
+</error_codes>
+
+<success_criteria>
+- [ ] Entry ID parsed and validated
+- [ ] Entry found in wiki index (type=spec, is sub-node)
+- [ ] User confirmed removal (unless -y flag)
+- [ ] Entry removed from container file via `maestro wiki remove-entry`
+- [ ] Wiki index auto-updated
+- [ ] Confirmation displayed with removed entry details
+</success_criteria>

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

@@ -12,7 +12,7 @@ allowed-tools:
 <purpose>
 Initialize the project-level specs directory by scanning the codebase for conventions, patterns, and tech stack.
 Core files (coding, arch, learning) are always created. Optional files (quality, debug, test, review) are created only when relevant signals are detected.
-All output lands in `.workflow/specs/` and `.workflow/project-tech.json`.
+All output lands in `.workflow/specs/`.
 </purpose>
 
 <required_reading>
@@ -20,7 +20,6 @@ All output lands in `.workflow/specs/` and `.workflow/project-tech.json`.
 </required_reading>
 
 <deferred_reading>
-- [project-tech.json](~/.maestro/templates/project-tech.json) — read when generating project-tech configuration
 </deferred_reading>
 
 <context>
@@ -47,7 +46,6 @@ Follow '~/.maestro/workflows/specs-setup.md' completely.
 - [ ] `.workflow/specs/` directory created
 - [ ] Core files always created: `coding-conventions.md`, `architecture-constraints.md`, `learnings.md`
 - [ ] Optional files created when detected: `quality-rules.md` (linter/CI), `test-conventions.md` (test framework), `debug-notes.md` (on demand), `review-standards.md` (on demand)
-- [ ] `project-tech.json` written with detected tech stack
 - [ ] Report displayed with summary and next steps
 </success_criteria>
 </output>

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

@@ -11,6 +11,10 @@ allowed-tools:
   - Agent
   - AskUserQuestion
 ---
+<required_reading>
+@~/.maestro/workflows/wiki-connect.md
+</required_reading>
+
 <purpose>
 Knowledge graph link discovery and health improvement. Analyzes the wiki index to find orphaned entries, missing connections, and transitive link gaps, then suggests or auto-applies new `related` links to improve graph connectivity.
 
@@ -21,7 +25,7 @@ Leverages maestro's unique wiki graph infrastructure (BM25 search, backlinks, he
 Arguments: $ARGUMENTS
 
 **Flags:**
-- `--scope <type>` — Limit analysis to a wiki type (spec, phase, memory, note, lesson, issue). Default: all types.
+- `--scope <type>` — Limit analysis to a wiki type (spec, memory, note, lesson, issue). Default: all types.
 - `--min-similarity N` — Minimum similarity score threshold 0.0-1.0 (default: 0.3)
 - `--fix` — Auto-apply the top suggestions by updating wiki entries with new `related` links
 - `--max N` — Maximum number of suggestions to generate (default: 20)
@@ -66,13 +70,13 @@ For each entry, compute potential connections:
 For each orphan entry, search for related entries using:
 - `maestro wiki search "<orphan title>"` — BM25 match by title
 - Tag overlap: entries sharing 2+ tags with the orphan
-- Same phase: entries with matching `phaseRef`
+- Same category: entries with matching `category`
 
 **2b. Missing Bidirectional Links:**
 For entries that have forward links but no corresponding backlink (A links to B, but B doesn't link to A), suggest adding the reverse link.
 
 **2c. Transitive Closure:**
-If A → B and B → C, but A has no link to C, and A and C share tags or are in the same phase, suggest A → C.
+If A → B and B → C, but A has no link to C, and A and C share tags or category, suggest A → C.
 
 **2d. Type Bridge:**
 Entries of different types that reference the same concept (e.g., a `spec-auth` and a `lesson-auth-gotcha`) but aren't linked.
@@ -83,13 +87,13 @@ For each candidate connection (source → target), compute similarity:
 ```
 score = 0.4 × tag_overlap_ratio
       + 0.3 × title_bm25_similarity
-      + 0.2 × same_phase_bonus
+      + 0.2 × same_category_bonus
       + 0.1 × type_bridge_bonus
 ```
 
 - `tag_overlap_ratio`: shared_tags / max(source_tags, target_tags)
 - `title_bm25_similarity`: normalized BM25 score from wiki search
-- `same_phase_bonus`: 1.0 if same phaseRef, else 0.0
+- `same_category_bonus`: 1.0 if same category, else 0.0
 - `type_bridge_bonus`: 1.0 if different types, else 0.0
 
 Filter by `--min-similarity`, rank descending, limit to `--max`.

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>
 
+<required_reading>
+@~/.maestro/workflows/wiki-digest.md
+</required_reading>
+
 <deferred_reading>
 - @~/.maestro/workflows/issue.md (issues.jsonl canonical schema for `--create-issues` routing)
 </deferred_reading>
@@ -27,7 +31,7 @@ Arguments: $ARGUMENTS
 **Scope resolution (auto-detected):**
 - `<topic>` — Search wiki for entries matching the topic via `maestro wiki search`
 - `--recent N` — Entries updated in the last N days
-- `--type <type>` — Filter by wiki type (spec, phase, memory, note, lesson, issue)
+- `--type <type>` — Filter by wiki type (spec, memory, note, lesson, issue)
 - No arguments — digest of the entire wiki
 
 **Flags:**
@@ -101,7 +105,6 @@ Build a matrix showing knowledge density by type × theme:
 ```
               Theme 1    Theme 2    Theme 3    Theme 4    Theme 5
 spec          ███░░      ░░░░░      █████      ██░░░      ░░░░░
-phase         ████░      ███░░      ░░░░░      █████      ██░░░
 memory        ░░░░░      ████░      ██░░░      ░░░░░      ███░░
 lesson        █░░░░      ██░░░      ████░      █░░░░      ░░░░░
 issue         ██░░░      ░░░░░      █░░░░      ███░░      ░░░░░
@@ -166,7 +169,7 @@ For each knowledge gap identified in Stage 5:
 1. Write digest file
 2. Append meta-insights to `lessons.jsonl`:
    - `source: "wiki-digest"`, `category: "technique"`
-   - e.g., "Auth knowledge is concentrated in specs but lacks lessons", "Phase 2 has no decision entries"
+   - e.g., "Auth knowledge is concentrated in specs but lacks lessons", "Security category has no decision entries"
 3. Update `learning-index.json`
 4. Display summary with key findings
 

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

@@ -63,7 +63,7 @@ After a barrier skill completes **in its spawned sub-agent**, coordinator reads
 | Skill | Artifacts to Read | Context Updates |
 |-------|------------------|-----------------|
 | `maestro-analyze` | `.workflow/.csv-wave/*/context.md`, `state.json` | `gaps`, `phase`, `analysis_dir` |
-| `maestro-plan` | `{phase_dir}/plan.json`, `{phase_dir}/.task/TASK-*.json` | `plan_dir`, `task_count`, `wave_count` |
+| `maestro-plan` | `{artifact_dir}/plan.json`, `{artifact_dir}/.task/TASK-*.json` | `plan_dir`, `task_count`, `wave_count` |
 | `maestro-brainstorm` | `.workflow/.csv-wave/*/.brainstorming/` | `brainstorm_dir`, `features` |
 | `maestro-spec-generate` | `.workflow/.csv-wave/*/specs/` | `spec_session_id` |
 | `maestro-execute` | `.workflow/.csv-wave/*/results.csv` | `exec_status`, `completed_tasks`, `failed_tasks` |
@@ -111,7 +111,7 @@ function analyzeBarrierArtifacts(step, result, ctx) {
 **`--continue`**: Glob `.workflow/.maestro-coordinate/MCC-*/state.json` sorted desc; load most recent; resume from first pending wave.
 
 **Fresh mode**:
-1. Read `.workflow/state.json` for project context (`current_phase`, `workflow_name`)
+1. Read `.workflow/state.json` for project context (derive current phase from artifact registry, `workflow_name`)
 2. If `--chain` given, use directly
 3. Otherwise classify intent via keyword heuristics (see chain_map)
 4. No match + not AUTO_YES → one clarifying question via `AskUserQuestion`

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

@@ -61,7 +61,7 @@ Wave-based multi-dimensional analysis using `spawn_agents_on_csv`. Diamond topol
 $maestro-analyze "3"
 $maestro-analyze -y "microservices vs monolith"
 $maestro-analyze -c 6 "3 -q"
-$maestro-analyze --continue "analyze-microservices-20260318"
+$maestro-analyze --continue "20260318-analyze-microservices"
 ```
 
 **Flags**:
@@ -132,7 +132,7 @@ Each wave generates `wave-{N}.csv` with extra `prev_context` column.
 ### Session Structure
 
 ```
-.workflow/.csv-wave/analyze-{slug}-{date}/
+.workflow/.csv-wave/{YYYYMMDD}-analyze-{slug}/
 +-- tasks.csv
 +-- results.csv
 +-- discoveries.ndjson
@@ -219,9 +219,9 @@ if (GAPS_MODE) {
 }
 
 const dateStr = getUtc8ISOString().substring(0, 10)
-const sessionId = `analyze-${slug}-${dateStr}`
+const sessionId = `${dateStr}-analyze-${slug}`
 const sessionFolder = `.workflow/.csv-wave/${sessionId}`
-const scratchDir = `.workflow/scratch/analyze-${slug}-${dateStr}`
+const scratchDir = `.workflow/scratch/${dateStr}-analyze-${slug}`
 
 Bash(`mkdir -p ${sessionFolder}`)
 Bash(`mkdir -p ${scratchDir}`)

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

@@ -60,7 +60,7 @@ Wave-based multi-role brainstorming using `spawn_agents_on_csv`. Diamond topolog
 $maestro-brainstorm "Build real-time collaboration platform"
 $maestro-brainstorm -y "Build real-time collaboration platform"
 $maestro-brainstorm -c 6 "Build real-time collaboration platform --count 5"
-$maestro-brainstorm --continue "brainstorm-collab-20260318"
+$maestro-brainstorm --continue "20260318-brainstorm-collab"
 ```
 
 **Flags**:
@@ -125,7 +125,7 @@ Each wave generates `wave-{N}.csv` with extra `prev_context` column.
 ### Session Structure
 
 ```
-.workflow/.csv-wave/brainstorm-{slug}-{date}/
+.workflow/.csv-wave/{YYYYMMDD}-brainstorm-{slug}/
 +-- tasks.csv
 +-- results.csv
 +-- discoveries.ndjson
@@ -184,7 +184,7 @@ const topicArg = $ARGUMENTS
 
 const slug = topicArg.toLowerCase().replace(/[^a-z0-9]+/g, '-').substring(0, 40)
 const dateStr = getUtc8ISOString().substring(0, 10).replace(/-/g, '')
-const sessionId = `brainstorm-${slug}-${dateStr}`
+const sessionId = `${dateStr}-brainstorm-${slug}`
 const sessionFolder = `.workflow/.csv-wave/${sessionId}`
 
 Bash(`mkdir -p ${sessionFolder}/.brainstorming`)
@@ -196,7 +196,7 @@ Bash(`mkdir -p ${sessionFolder}/.brainstorming`)
 
 **Decomposition Rules**:
 
-1. **Mode detection**: Number = phase mode (resolve `.workflow/phases/{NN}-{slug}/`), text = scratch mode
+1. **Mode detection**: Number = phase mode (resolve via state.json artifact registry to `.workflow/scratch/{YYYYMMDD}-{type}-{slug}/`), text = scratch mode
 2. **Project specs loading**: Read `.workflow/specs/` for architecture-aware analysis context
 3. **Role selection**:
 

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

@@ -106,7 +106,7 @@ const AUTO_FLAG_MAP = {
 
 function assembleArgs(step) {
   let a = (step.args || '')
-    .replace(/\{phase\}/g, context.current_phase || '')
+    .replace(/\{phase\}/g, context.phase || '')
     .replace(/\{description\}/g, context.user_intent || '')
     .replace(/\{issue_id\}/g, context.issue_id || '')
     .replace(/\{spec_session_id\}/g, context.spec_session_id || '')
@@ -145,7 +145,7 @@ Bash({
 ```javascript
 // Context propagation from output
 const phaseMatch = output.match(/PHASE:\s*(\d+)/m);
-if (phaseMatch) context.current_phase = phaseMatch[1];
+if (phaseMatch) context.phase = phaseMatch[1];  // derived from output, not stored in state
 const specMatch = output.match(/SPEC-[\w-]+/);
 if (specMatch) context.spec_session_id = specMatch[0];
 const scratchMatch = output.match(/scratch_dir:\s*(.+)/m);

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

@@ -60,7 +60,7 @@ $maestro-execute "3"
 $maestro-execute -c 4 "3 --auto-commit"
 $maestro-execute -y "3 --method cli"
 $maestro-execute "3 --dir .workflow/scratch/quick-fix"
-$maestro-execute --continue "execute-phase3-20260318"
+$maestro-execute --continue "20260318-execute-P3-phase3"
 ```
 
 **Flags**:
@@ -130,7 +130,7 @@ Each wave generates `wave-{N}.csv` with extra `prev_context` column populated fr
 ### Session Structure
 
 ```
-.workflow/.csv-wave/execute-{phase}-{date}/
+.workflow/.csv-wave/{YYYYMMDD}-execute-P{N}-{slug}/
 +-- tasks.csv
 +-- results.csv
 +-- discoveries.ndjson
@@ -181,8 +181,8 @@ const phaseArg = $ARGUMENTS
 
 const dateStr = getUtc8ISOString().substring(0, 10).replace(/-/g, '')
 const sessionId = scratchDir
-  ? `execute-scratch-${dateStr}`
-  : `execute-phase${phaseArg}-${dateStr}`
+  ? `${dateStr}-execute-scratch`
+  : `${dateStr}-execute-P${phaseArg}-${phaseSlug}`
 const sessionFolder = `.workflow/.csv-wave/${sessionId}`
 
 Bash(`mkdir -p ${sessionFolder}`)
@@ -325,9 +325,19 @@ If a task is blocked/failed and other tasks in later waves depend on it:
 5. **Extract incremental learnings**:
    - Read all `.summaries/` from PLAN_DIR
    - Extract strategy adjustments, patterns, pitfalls
-   - Append to `.workflow/specs/learnings.md`
+   - Check existing entries via `maestro spec load --category learning` (dedup)
+   - Append to `.workflow/specs/learnings.md` using `<spec-entry>` closed-tag format (category=`learning`, auto-extract keywords, date=today, source=`execute`)
    - Mark artifact `harvested: true` in state.json
 
+5b. **Post-task Knowledge Inquiry** (after each task completes):
+   - **Execution deviation**: If task summary mentions approach change, dependency swap, or plan deviation:
+     → Ask: "TASK-{NNN} deviated from the plan. Should this decision be recorded as an architecture constraint? (`/spec-add arch`)"
+   - **Retry success**: If task required ≥2 retries before completion:
+     → Ask: "TASK-{NNN} succeeded after {N} retries. Should this fix pattern be documented? (`/spec-add debug`)"
+   - **Implicit knowledge**: If task summary contains design rationale ("chose X because", "rejected Y due to"):
+     → Ask: "Design decision detected. Should it be recorded as a learning? (`/spec-add learning`)"
+   - If user confirms, append `<spec-entry>` to matching category file via `spec-add` mechanism
+
 6. **Generate context.md**:
 
 ```markdown

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

@@ -16,7 +16,7 @@ When `--auto`: After config questions, run research without further interaction.
 ```bash
 $maestro-init ""
 $maestro-init "--auto"
-$maestro-init "--from-brainstorm brainstorm-auth-20260318"
+$maestro-init "--from-brainstorm 20260318-brainstorm-auth"
 ```
 
 **Flags**:
@@ -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