maestro-flow 0.5.35 → 0.5.37

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

@@ -6,8 +6,6 @@ allowed-tools: Read, Write, Bash, Glob, Grep, request_user_input
 ---
 <purpose>
 Signal-driven overlay generator — collect workflow deficiency signals from multiple sources, diagnose which commands need amendment, batch-generate targeted overlays. All amendments use overlay system (`~/.maestro/overlays/*.json`) — non-invasive, idempotent, survives reinstall.
-
-Differs from `$maestro-overlay` (single explicit intent). This command **discovers** what needs amending by analyzing workflow artifacts.
 </purpose>
 
 <required_reading>

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

@@ -14,8 +14,6 @@ Wave 1 (CLI exploration, parallel) -> Wave 2 (6-dimension scoring, parallel) ->
 **Dual-layer scope (D-003)**:
 - **Macro layer** (text argument, e.g. `analyze "auth refactor"`): broad impact exploration. Produces `scope_verdict ∈ {small, medium, large}` to drive downstream routing (roadmap vs plan).
 - **Phase layer** (numeric argument, e.g. `analyze 1`): phase-scoped deep analysis under `current_milestone`. Milestone resolved via D-007 `phase_slugs` reverse lookup, NEVER direct `current_milestone` read.
-
-Produces context-package.json (standardized cross-command context contract) in all modes.
 </purpose>
 
 <context>
@@ -35,9 +33,9 @@ $ARGUMENTS -- phase number, topic text, and optional flags.
 
 ### Pre-load (runs unconditionally, including -y auto mode)
 1. **Codebase docs**: IF `.workflow/codebase/doc-index.json` exists → Read ARCHITECTURE.md for module boundaries
-2. **Specs**: `maestro spec load --category arch` — load architecture constraints
+2. **Specs**: `maestro load --type spec --category arch` — load architecture constraints
 3. **Wiki search**: `maestro search "{topic keywords}" --json` → top 5-10 entries as prior knowledge
-4. **Role Knowledge**: `maestro search --category debug` → select relevant → `maestro wiki load`
+4. **Role Knowledge**: `maestro search --category debug` → select relevant → `maestro load --type knowhow --id`
 5. All optional — proceed without if unavailable (log warning)
 </context>
 
@@ -45,7 +43,7 @@ $ARGUMENTS -- phase number, topic text, and optional flags.
 Interview the user relentlessly until shared understanding is reached. Active only in interactive mode; skip when `-y/--yes`, `--continue`, or input is already specific (explicit phase number or unambiguous topic).
 
 - One decision per turn via request_user_input with 2–4 options + a (Recommended) default. The user controls termination — keep interviewing until convergence; they can interrupt naturally at any time.
-- Search-first when uncertain: before asking, resolve via `state.json`, `roadmap.md`, `issues.jsonl`, `maestro spec load`, `maestro search`, Grep, Read, or — for open-ended multi-file scans — `maestro delegate ... --role explore`. Never ask what code or memory can verify; never bounce your own ambiguity back to the user — search first, then ask only what truly needs human judgment.
+- Search-first when uncertain: before asking, resolve via `state.json`, `roadmap.md`, `issues.jsonl`, `maestro load --type spec`, `maestro search`, Grep, Read, or — for open-ended multi-file scans — `maestro delegate ... --role explore`. Never ask what code or memory can verify; never bounce your own ambiguity back to the user — search first, then ask only what truly needs human judgment.
 - Writeback cadence: each settled decision is immediately appended/updated in `context.md` "Interview Decisions" (and mirrored into `analysis.md` in full mode). Do NOT batch writeback to the end — partial decisions must already be on disk before the next question.
 - Walk the decision dependency tree strictly: scope → depth → dimensions → Go/No-Go threshold. Do not open the next branch until the current one is settled.
 - Scope guard: only ask about decisions owned by `analyze`. Do not prejudge plan/execute concerns.
@@ -151,7 +149,12 @@ S_WAVE_1:
   -> ERROR        WHEN: all failed
 
 S_WAVE_2:
-  -> S_WAVE_3     DO: A_SPAWN_WAVE_2
+  -> S_BOUNDARY_GRILL   DO: A_SPAWN_WAVE_2
+
+S_BOUNDARY_GRILL:
+  -> S_WAVE_3     WHEN: no boundary conflicts detected     DO: —
+  -> S_WAVE_3     WHEN: conflicts detected + resolved      DO: A_BOUNDARY_GRILL
+  GUARD: max 3 conflicts × 3 questions; non-blocking (see boundary-grill.md)
 
 S_WAVE_3:
   -> S_AGGREGATE  DO: A_SPAWN_WAVE_3
@@ -237,6 +240,14 @@ Write to `conclusions.json.scope_verdict` (all modes that produce conclusions);
 
 Gray area detection: domain-aware (things users SEE/CALL/RUN/READ), phase-specific (skip prior decided areas).
 
+### A_BOUNDARY_GRILL
+
+Run boundary grill per `~/.maestro/workflows/boundary-grill.md` after Wave 2 scoring, before Wave 3 synthesis.
+Input: Wave 1 exploration findings + Wave 2 dimension scores. Scope guard: "only analyze decisions; do not prejudge plan/execute concerns".
+Detect RSC (scope violations), MOD (module boundary crossings), DEC (upstream locked vs code reality).
+IF conflicts → results to `analysis.md` § Boundary Grill Results + update `context.md` Locked/Free/Deferred.
+Non-blocking: conflicts produce warnings, pipeline continues.
+
 ### A_AGGREGATE_RESULTS
 
 1. Export results.csv
@@ -310,6 +321,8 @@ Protocol: read before analysis, append-only, dedup by type+key.
 - [ ] Decision Recording Protocol applied to all decisions
 - [ ] Confidence scored per dimension with factor-based model (full mode)
 - [ ] Readiness gate checked before synthesis (wave 3)
+- [ ] Boundary grill executed between Wave 2 and Wave 3 (skip if no conflicts detected)
+- [ ] Boundary grill results written to analysis.md § Boundary Grill Results (if conflicts found)
 - [ ] Pressure pass completed ≥ 1 time on highest-risk dimension before synthesis
 - [ ] Deferred items auto-created as issues
 - [ ] Scope creep redirected to Deferred section

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

@@ -7,10 +7,6 @@ allowed-tools: Read, Write, Edit, Bash, Glob, Grep, spawn_agents_on_csv, request
 <purpose>
 Formal specification document chain producing a complete specification package through 7 sequential phases (P0–P6, plus P1.5 requirement expansion) with multi-CLI analysis and interactive refinement. Pure documentation — no code generation, no roadmap generation.
 
-Parallel to `brainstorm` as an upstream origin command:
-- **brainstorm** = divergent exploration (lightweight, multi-role creative)
-- **blueprint** = convergent documentation (heavyweight, 7-phase formal spec chain)
-
 Output: `.workflow/blueprint/BLP-{slug}-{date}/` containing Product Brief, PRD, Architecture, and Epics.
 </purpose>
 
@@ -49,7 +45,7 @@ maestro-analyze → maestro-roadmap → maestro-plan
 **Output boundary**: ALL file writes MUST target `.workflow/blueprint/BLP-{slug}-{date}/` or `.workflow/state.json` only. NEVER modify source code or files outside these paths.
 
 ### Pre-load specs
-1. **Architecture specs**: Run `maestro spec load --category arch` to load architecture constraints. Use as context for architecture decisions (Phase 4).
+1. **Architecture specs**: Run `maestro load --type spec --category arch` to load architecture constraints. Use as context for architecture decisions (Phase 4).
 2. Optional — proceed without if unavailable.
 </context>
 
@@ -57,7 +53,7 @@ maestro-analyze → maestro-roadmap → maestro-plan
 Interview the user relentlessly about every aspect of the spec until shared understanding is reached. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one; if a question can be answered by exploring the codebase, explore the codebase instead. Active only in interactive mode; skip when `-y/--yes`, `-c/--continue`, or input is already specific (clear idea + scope).
 
 - Ask one question per turn via request_user_input and wait for the user's feedback before continuing; every question must carry a recommended answer marked `(Recommended)`, 2–4 options total. The user controls termination — keep interviewing until convergence; they can interrupt naturally at any time.
-- Search-first when uncertain: before asking, resolve via `state.json`, existing artifacts, `maestro spec load`, direct codebase exploration (Glob/Grep/Read), or — for open-ended multi-file scans — `maestro delegate ... --role explore`. Never ask what code or memory can verify; never bounce your own ambiguity back to the user — search first, then ask only what truly needs human judgment.
+- Search-first when uncertain: before asking, resolve via `state.json`, existing artifacts, `maestro load --type spec`, codebase exploration (`maestro explore` preferred, fallback Glob/Grep/Read). Never ask what code or memory can verify; never bounce your own ambiguity back to the user — search first, then ask only what truly needs human judgment.
 - Writeback cadence: each settled decision is immediately persisted into `blueprint-config.json` before the next question. Do NOT batch writeback to the end — partial decisions must already be on disk.
 - Walk the decision dependency tree depth-first: scope → spec type → focus areas → requirement priorities. Do not open the next branch until the current one is settled.
 - Scope guard: only decide the shape of the specification. Do not pre-resolve roadmap phases or plan tasks — those belong to downstream commands.

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

@@ -36,8 +36,8 @@ When `--from` is absent, auto-discover from state.json: latest `type=grill` arti
 **9 valid roles**: data-architect, product-manager, product-owner, scrum-master, subject-matter-expert, system-architect, test-strategist, ui-designer, ux-expert
 
 ### Pre-load
-1. **Architecture specs**: `maestro spec load --category arch` — load architecture constraints as context for multi-role design (roles respect documented decisions).
-2. **Role Knowledge**: `maestro search --category arch` → identify relevant entries → `maestro wiki load <id1> [id2...]`
+1. **Architecture specs**: `maestro load --type spec --category arch` — load architecture constraints as context for multi-role design (roles respect documented decisions).
+2. **Role Knowledge**: `maestro search --category arch` → identify relevant entries → `maestro load --type knowhow --id <id1> [id2...]`
 3. **Project context**: Read `.workflow/project.md` (if exists) → Validated requirements (already shipped) as constraints, Active requirements as current scope. Read `state.json.accumulated_context` → deferred items as brainstorming seeds, key_decisions as locked constraints.
 4. All optional — proceed without if unavailable.
 
@@ -57,7 +57,7 @@ When `--from` is absent, auto-discover from state.json: latest `type=grill` arti
 Interview the user relentlessly until shared understanding is reached. Active only in interactive mode; skip when `-y/--yes`, `--skip-questions`, `--continue` (existing session), or input is already specific.
 
 - One decision per turn via request_user_input with 2–4 options + a (Recommended) default. The user controls termination — keep interviewing until convergence; they can interrupt naturally at any time.
-- Search-first when uncertain: before asking, resolve via `state.json`, the session directory, `maestro spec load`, `maestro search`, Glob/Grep/Read, or — for open-ended multi-file scans — `maestro delegate ... --role explore`. Never ask what code or memory can verify; never bounce your own ambiguity back to the user — search first, then ask only what truly needs human judgment.
+- Search-first when uncertain: before asking, resolve via `state.json`, the session directory, `maestro load --type spec`, `maestro search`, `maestro explore` (preferred, fallback Glob/Grep/Read). Never ask what code or memory can verify; never bounce your own ambiguity back to the user — search first, then ask only what truly needs human judgment.
 - Writeback cadence: each time a decision settles, immediately append/update its row in `guidance-specification.md` §11 (create the section if absent). Do NOT batch writeback to the end — partial decisions must already be on disk before the next question.
 - Branch jumps allowed: the user may switch freely between mode / role / upstream / sub-pipeline branches; sequence is not enforced, but every decision point must end with a definite answer.
 - Scope guard: only ask about decisions owned by `brainstorm`. Do not pre-resolve roadmap/plan choices.
@@ -316,8 +316,13 @@ S_WAVE_2 → S_AGGREGATE WHEN: all failed       DO: skip review
 S_CHECK_2 → S_WAVE_3   WHEN: -y OR user "Proceed"
 S_CHECK_2 → S_WAVE_2   WHEN: user "Add Roles"  DO: add new role rows, spawn only new
 
-S_WAVE_3 → S_RESOLVE   DO: spawn wave-3, capture review_findings (conflicts/gaps/synergies with patch_targets)
-S_WAVE_3 → S_AGGREGATE WHEN: zero findings    DO: log "No cross-role issues detected", skip resolve
+S_WAVE_3 → S_BOUNDARY_GRILL  DO: spawn wave-3, capture review_findings (conflicts/gaps/synergies with patch_targets)
+S_WAVE_3 → S_AGGREGATE      WHEN: zero findings    DO: log "No cross-role issues detected", skip resolve
+
+S_BOUNDARY_GRILL:
+  → S_RESOLVE     WHEN: no boundary conflicts detected     DO: —
+  → S_RESOLVE     WHEN: conflicts detected + resolved      DO: A_BOUNDARY_GRILL
+  GUARD: max 3 conflicts × 3 questions; non-blocking (see boundary-grill.md)
 
 S_RESOLVE → S_AGGREGATE  DO: A_APPLY_RESOLUTIONS (orchestrator iterates patch_targets and applies Edits)
 
@@ -382,6 +387,13 @@ When ui-designer is among selected roles, establish visual direction before Wave
 explore generates multi-style HTML prototypes, visual comparison, user selection/mix, and produces DESIGN.md.
 ui-designer agents in Wave 2 then focus on UX/visual design referencing DESIGN.md.
 
+### A_BOUNDARY_GRILL
+
+Run boundary grill per `~/.maestro/workflows/boundary-grill.md` after cross-role review, before resolution application.
+Input: reviewer findings + role Decision Digests. Scope guard: "only brainstorm decisions; do not pre-resolve roadmap/plan choices".
+IF conflicts → results to `guidance-specification.md` §12.5 Boundary Grill Results + feed into S_RESOLVE.
+Non-blocking: conflicts produce warnings, pipeline continues.
+
 ### A_APPLY_RESOLUTIONS
 
 For each finding in `review_findings`:
@@ -442,6 +454,8 @@ Protocol: read before analysis, append-only, dedup by type+key.
 - [ ] system-architect/analysis.md §3 includes Data Model + State Machine when system-architect selected
 - [ ] Each {role}/analysis.md §2 Decisions table has ≥ 1 row per feature
 - [ ] Cross-role review (W3) executed; reviewer output includes `patch_targets[]` for every finding
+- [ ] Boundary grill executed after cross-role review (skip if no conflicts detected)
+- [ ] Boundary grill results written to guidance-specification.md §12.5 (if conflicts found)
 - [ ] If findings: resolutions applied via Edit AND logged in guidance §12 "Cross-Role Resolutions"
 - [ ] If zero findings: final report explicitly notes "No cross-role issues detected"; guidance §12 unchanged
 - [ ] Heading-drift patch failures surfaced (not silently dropped)

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

@@ -1,7 +1,7 @@
 ---
 name: maestro-collab
 description: Use when a question needs cross-verification from multiple CLI tools or diverse analytical perspectives
-argument-hint: "\"<requirement>\" [--tools gemini,qwen,claude] [--mode analysis|write] [--rule <template>] [-y]"
+argument-hint: "\"<requirement>\" [--tools agy,qwen,claude] [--mode analysis|write] [--rule <template>] [-y]"
 allowed-tools: Read, Write, Edit, Glob, Grep, request_user_input
 ---
 
@@ -100,7 +100,12 @@ S_FAN_OUT:
   → ERROR(E004)     WHEN: all failed OR fewer than 2 completed
 
 S_CROSS_VERIFY:
-  → S_SYNTHESIZE    DO: A_CROSS_VERIFY
+  → S_BOUNDARY_GRILL  DO: A_CROSS_VERIFY
+
+S_BOUNDARY_GRILL:
+  → S_SYNTHESIZE    WHEN: no boundary conflicts detected     DO: —
+  → S_SYNTHESIZE    WHEN: conflicts detected + resolved      DO: A_BOUNDARY_GRILL
+  GUARD: max 3 conflicts × 3 questions; non-blocking (see boundary-grill.md)
 
 S_SYNTHESIZE:
   → S_AGGREGATE     DO: A_SYNTHESIZE
@@ -141,7 +146,7 @@ multi_tool_use.parallel({
     {
       recipient_name: "functions.exec_command",
       parameters: {
-        cmd: "maestro delegate \"<shared_prompt>\" --to gemini --mode <mode> [--rule <rule>]",
+        cmd: "maestro delegate \"<shared_prompt>\" --to agy --mode <mode> [--rule <rule>]",
         yield_time_ms: 30000,
         max_output_tokens: 6000
       }
@@ -229,6 +234,12 @@ Compute: `consensus_level = consensus_count / total_findings * 100`
 
 Write results to `{scratchDir}/cross-verify.md`.
 
+### A_BOUNDARY_GRILL
+
+Run boundary grill per `~/.maestro/workflows/boundary-grill.md` after cross-verification.
+Input: classified CONFLICT findings + per-tool outputs. Check upstream scope if `--from` used.
+IF conflicts → tag with resolution, feed into A_SYNTHESIZE. No conflicts → pass through.
+
 ### A_SYNTHESIZE
 
 Generate 3 output files from cross-verify results:
@@ -313,6 +324,8 @@ Generate 3 output files from cross-verify results:
 - [ ] Blocking poll loop ran until pending_sessions empty — no early exit
 - [ ] Per-tool raw outputs saved to {scratchDir}/per-tool/
 - [ ] Cross-verify: CONSENSUS/CONFLICT/UNIQUE classified, consensus_level computed
+- [ ] Boundary grill executed on CONFLICT items (skip if no boundary conflicts detected)
+- [ ] Boundary grill results written to collab-report.md § Boundary Grill Results (if conflicts found)
 - [ ] collab-report.md + context.md + conclusions.json produced
 - [ ] CLB artifact registered in state.json
 - [ ] Partial degradation: continued if 2+ tools succeeded

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

@@ -9,8 +9,6 @@ allowed-tools: Read, Write, Edit, Bash, Glob, Grep, request_user_input
 Task companion command — pairs with any task to provide knowledge context loading,
 structured companion document recording, insight capture, and skill routing.
 
-Does not create sessions or modify workflow state. Pure side-car utility.
-
 Four modes:
 - **before** — Pre-task: load spec + knowhow index + codebase index, create companion doc
 - **note** — Mid-task: append a structured entry to the active companion doc
@@ -72,16 +70,16 @@ Auto-detection: if `--type` not provided, infer from `--task` description keywor
 
 ### Step 1: Load Specs
 
-Run `maestro spec load` with appropriate flags:
-- With `--category`: `maestro spec load --category <cat>`
-- With `--task`: `maestro spec load --keyword <extracted_keyword>`
-- No flags: `maestro spec load --category coding`
+Run `maestro load --type spec` with appropriate flags:
+- With `--category`: `maestro load --type spec --category <cat>`
+- With `--task`: `maestro load --type spec --keyword <extracted_keyword>`
+- No flags: `maestro load --type spec --category coding`
 
 Display loaded rules summary (entry count + key rule names).
 
 ### Step 2: Browse Knowhow Index
 
-Run `maestro knowhow list --store workflow`. With `--task`, also run `maestro search "<task_keyword>" --type knowhow`. Display available entries (ID + title). Hint: `maestro wiki load <id>` for details.
+Run `maestro knowhow list --store workflow`. With `--task`, also run `maestro search "<task_keyword>" --type knowhow`. Display available entries (ID + title). Hint: `maestro load --type knowhow --id <id>` for details.
 
 ### Step 3: Check Codebase Index
 

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

@@ -52,8 +52,8 @@ $ARGUMENTS — natural language workflow description, or flags.
 **Template schema**: Read `~/.maestro/templates/workflows/specs/template-schema.md` at Phase 5 (deferred).
 
 ### Pre-load specs
-1. **Architecture specs**: Run `maestro spec load --category arch` to load architecture constraints. Use as context for node resolution — ensures workflow design respects documented patterns.
-2. **Coding specs**: Run `maestro spec load --category coding` to load coding conventions. Informs executor argument defaults and context injection.
+1. **Architecture specs**: Run `maestro load --type spec --category arch` to load architecture constraints. Use as context for node resolution — ensures workflow design respects documented patterns.
+2. **Coding specs**: Run `maestro load --type spec --category coding` to load coding conventions. Informs executor argument defaults and context injection.
 3. Optional — proceed without if unavailable.
 </context>
 

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

@@ -230,9 +230,9 @@ If exit code is 1, present warnings and ask whether to proceed.
 
 4. **Build tasks.csv**: For each pending task per wave, read `.task/TASK-{NNN}.json` and extract: title, description, scope (from files), convergence.criteria, hints, execution_directives. Set `deps` from task dependency, `context_from` = deps, `wave` from plan.json.
 
-5. **Load project specs + tools**: Run `maestro spec load --category coding` to load coding conventions, architecture constraints, AND discoverable knowhow tools (passed to all agents)
+5. **Load project specs + tools**: Run `maestro load --type spec --category coding` to load coding conventions, architecture constraints, AND discoverable knowhow tools (passed to all agents)
 
-6. **Load UI specs (conditional)**: If any task involves frontend/UI work (task scope/description contains component, page, style, layout, CSS, HTML, frontend; or focus_paths in `src/components/`, `src/pages/`, `src/styles/`, `src/ui/`), also run `maestro spec load --category ui` and include in agent context.
+6. **Load UI specs (conditional)**: If any task involves frontend/UI work (task scope/description contains component, page, style, layout, CSS, HTML, frontend; or focus_paths in `src/components/`, `src/pages/`, `src/styles/`, `src/ui/`), also run `maestro load --type spec --category ui` and include in agent context.
 
 7. **Load codebase + wiki context** (optional, passed to all agents):
    - If `.workflow/codebase/ARCHITECTURE.md` exists: read and include as `codebase_context` in agent instructions

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

@@ -1,158 +1,156 @@
----
-name: maestro-fork
-description: Create or sync milestone worktree for parallel dev
-argument-hint: "-m <milestone-number> [--base <branch>] [--sync]"
-allowed-tools: Read, Write, Edit, Bash, Glob, Grep, request_user_input
----
-
-<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.
-
-Produces `.workflow/worktrees.json` registry in the main worktree and `.workflow/worktree-scope.json` marker in the worktree, and writes a scoped `state.json` inside the worktree containing only the forked milestone's artifacts.
-</purpose>
-
-<required_reading>
-@~/.maestro/workflows/fork.md
-</required_reading>
-
-<deferred_reading>
-- [worktrees.json](~/.maestro/templates/worktrees.json) — read when initializing or updating worktree registry
-- [worktree-scope.json](~/.maestro/templates/worktree-scope.json) — read when creating worktree scope marker
-</deferred_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/)
-
-**Registry: `worktrees.json`** (`.workflow/worktrees.json` in main worktree):
-
-Initialize if not exists: `{ "version": "1.0", "worktrees": [], "fork_sessions": [] }`
-
-On fork, append to `worktrees[]`:
-```json
-{
-  "milestone_num": "{milestoneNum}",
-  "milestone": "{milestoneName}",
-  "slug": "{milestoneSlug}",
-  "branch": "milestone/{milestoneSlug}",
-  "path": "{worktreeRoot}/m{milestoneNum}-{milestoneSlug}",
-  "base_commit": "{baseCommit}",
-  "status": "active",
-  "created_at": "{UTC8_ISO}",
-  "owned_phases": ["{ownedPhaseNumbers}"],
-  "fork_session": "{forkSessionId}"
-}
-```
-
-Append to `fork_sessions[]`:
-```json
-{
-  "session_id": "fork-{UTC8_compact_timestamp}",
-  "created_at": "{UTC8_ISO}",
-  "milestone_num": "{milestoneNum}",
-  "milestone": "{milestoneName}",
-  "base_branch": "{baseBranch}",
-  "base_commit": "{baseCommit}"
-}
-```
-
-**Scope marker: `worktree-scope.json`** (`{wtPath}/.workflow/worktree-scope.json`):
-```json
-{
-  "worktree": true,
-  "milestone_num": "{milestoneNum}",
-  "milestone": "{milestoneName}",
-  "owned_phases": ["{ownedPhaseNumbers}"],
-  "phase_dependencies": "{phaseDeps}",
-  "main_worktree": "{resolve(cwd)}",
-  "branch": "milestone/{milestoneSlug}",
-  "base_commit": "{baseCommit}",
-  "created_at": "{UTC8_ISO}"
-}
-```
-
-Presence of `worktree-scope.json` signals "inside a worktree" — used by E003 validation to prevent nested forks.
-
-**Next steps:**
-- Fork → `cd {wt.path} && $maestro-analyze`
-- Sync → resume work in worktree
-</execution>
-
-<invariants>
-**Artifact verification** — worktree-scope.json, scoped state.json, and worktrees.json registry update MUST all complete. If any missing: DO NOT report completion.
-</invariants>
-
-<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>
+---
+name: maestro-fork
+description: Create or sync milestone worktree for parallel dev
+argument-hint: "-m <milestone-number> [--base <branch>] [--sync]"
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, request_user_input
+---
+
+<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>
+
+<deferred_reading>
+- [worktrees.json](~/.maestro/templates/worktrees.json) — read when initializing or updating worktree registry
+- [worktree-scope.json](~/.maestro/templates/worktree-scope.json) — read when creating worktree scope marker
+</deferred_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/)
+
+**Registry: `worktrees.json`** (`.workflow/worktrees.json` in main worktree):
+
+Initialize if not exists: `{ "version": "1.0", "worktrees": [], "fork_sessions": [] }`
+
+On fork, append to `worktrees[]`:
+```json
+{
+  "milestone_num": "{milestoneNum}",
+  "milestone": "{milestoneName}",
+  "slug": "{milestoneSlug}",
+  "branch": "milestone/{milestoneSlug}",
+  "path": "{worktreeRoot}/m{milestoneNum}-{milestoneSlug}",
+  "base_commit": "{baseCommit}",
+  "status": "active",
+  "created_at": "{UTC8_ISO}",
+  "owned_phases": ["{ownedPhaseNumbers}"],
+  "fork_session": "{forkSessionId}"
+}
+```
+
+Append to `fork_sessions[]`:
+```json
+{
+  "session_id": "fork-{UTC8_compact_timestamp}",
+  "created_at": "{UTC8_ISO}",
+  "milestone_num": "{milestoneNum}",
+  "milestone": "{milestoneName}",
+  "base_branch": "{baseBranch}",
+  "base_commit": "{baseCommit}"
+}
+```
+
+**Scope marker: `worktree-scope.json`** (`{wtPath}/.workflow/worktree-scope.json`):
+```json
+{
+  "worktree": true,
+  "milestone_num": "{milestoneNum}",
+  "milestone": "{milestoneName}",
+  "owned_phases": ["{ownedPhaseNumbers}"],
+  "phase_dependencies": "{phaseDeps}",
+  "main_worktree": "{resolve(cwd)}",
+  "branch": "milestone/{milestoneSlug}",
+  "base_commit": "{baseCommit}",
+  "created_at": "{UTC8_ISO}"
+}
+```
+
+Presence of `worktree-scope.json` signals "inside a worktree" — used by E003 validation to prevent nested forks.
+
+**Next steps:**
+- Fork → `cd {wt.path} && $maestro-analyze`
+- Sync → resume work in worktree
+</execution>
+
+<invariants>
+**Artifact verification** — worktree-scope.json, scoped state.json, and worktrees.json registry update MUST all complete. If any missing: DO NOT report completion.
+</invariants>
+
+<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-grill/SKILL.md

@@ -7,10 +7,9 @@ allowed-tools: Read, Write, Edit, Bash, Glob, Grep, request_user_input
 <purpose>
 Socratic stress-testing of a plan, idea, or requirement against codebase reality. Walks every branch of the decision tree one question at a time — challenging vague terminology against existing code, probing edge cases with concrete scenarios, and verifying assumptions with code evidence. Produces a verified context package (grill-report.md + terminology.md + context-package.json) for downstream brainstorm/analyze/roadmap consumption.
 
-Positioned BEFORE brainstorm in the pipeline: grill stress-tests and sharpens; brainstorm generates and elaborates.
 
 Codex specifics:
-- **No agent spawning** — codebase exploration runs directly via Glob/Grep/Read in coordinator context.
+- **No agent spawning** — codebase exploration via `maestro explore` (preferred, fallback Glob/Grep/Read).
 - **request_user_input** replaces request_user_input for Socratic Q&A.
 - **CLI delegation** for auto mode: `exec_command("maestro delegate ... --role analyze --mode analysis")`.
 </purpose>
@@ -43,7 +42,7 @@ $ARGUMENTS -- topic/plan text for interactive mode, or --from source for upstrea
 
 ### Role Knowledge
 `maestro search "{topic keywords}"` → load relevant entries before grilling.
-`maestro spec load --category arch` → load architecture constraints.
+`maestro load --type spec --category arch` → load architecture constraints.
 </context>
 
 <interview_protocol>