maestro-flow 0.4.12 → 0.4.14

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

@@ -53,7 +53,7 @@ Follow '~/.maestro/workflows/knowhow.md' Part A (KnowHow Management) completely.
 <error_codes>
 | Code | Severity | Description | Stage |
 |------|----------|-------------|-------|
-| E001 | error | No memory stores found — run `/manage-knowhow-capture` or create MEMORY.md | resolve_paths |
+| E001 | error | No memory stores found — for workflow store run `/manage-knowhow-capture`; for system store create `~/.claude/projects/{project}/memory/MEMORY.md` manually | resolve_paths |
 | E002 | error | Entry ID or filename not found | execute_view, execute_delete |
 | E003 | error | Prune requires at least one filter (--tag, --type, --before, --after) | execute_prune |
 | E004 | error | Cannot delete MEMORY.md — use `edit` subcommand instead | execute_delete |

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

@@ -30,7 +30,7 @@ Arguments: $ARGUMENTS
 - `"<insight text>"` (or any non-keyword text) → insight capture mode
 - `tip <text>` → tip capture mode (quick contextual note, auto-tagged `tip`)
 - `list` → list recent entries (default 20)
-- `search <query>` → `maestro spec load --category learning` or text search across `specs/learnings.md`
+- `search <query>` → `maestro spec load --category learning` or text search across `.workflow/specs/learnings.md`
 - `show <INS-id>` → full detail with phase context
 - empty → AskUserQuestion to prompt for text
 
@@ -47,19 +47,19 @@ Follow `~/.maestro/workflows/learn.md` Stages 1–5 in order.
 | E001 | error | `.workflow/` not initialized — run `/maestro-init` first | parse_input |
 | E002 | error | Unknown `--category` value (allowed: pattern, antipattern, decision, tool, gotcha, technique, tip) | parse_input |
 | E003 | error | `show` mode requires an INS-id argument | show |
-| E004 | error | Insight id not found in `specs/learnings.md` | show |
+| E004 | error | Insight id not found in `.workflow/specs/learnings.md` | show |
 | W001 | warning | Auto-phase detection found a current_phase but no matching artifact in registry; phase set to null | capture |
 </error_codes>
 
 <success_criteria>
 - [ ] Mode correctly routed (capture / list / search / show)
-- [ ] Capture: `<spec-entry>` block appended to `specs/learnings.md` with all required fields
+- [ ] Capture: `<spec-entry>` block appended to `.workflow/specs/learnings.md` with all required fields
 - [ ] Capture: phase auto-link resolves correctly via artifact registry when `state.json` has `current_phase`
 - [ ] Capture: category inference produces a sensible default when `--category` absent
 - [ ] List: filters apply, output sorted newest-first, default limit 20
 - [ ] Search: results ranked by title (3) > tags (2) > summary (1) match
 - [ ] Show: full insight displayed with phase context and routed-artifact link if any
-- [ ] No file modifications outside `.workflow/knowhow/`
+- [ ] No file modifications outside `.workflow/specs/learnings.md` and `.workflow/knowhow/`
 - [ ] Confirmation banner displayed with INS-id and next-step hints
 - [ ] Next step: `/manage-learn list` to browse, or `/manage-learn search <query>` to find related insights
 </success_criteria>

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

@@ -40,13 +40,13 @@ Phase or task: $ARGUMENTS (required — phase number)
 
 **Intelligent routing** (auto-detected from project state):
 
-| Priority | Condition | Route | Equivalent to |
-|----------|-----------|-------|---------------|
+| Priority | Condition | Route | Reference skill |
+|----------|-----------|-------|-----------------|
 | 1 | Active session exists (state.json status=running) | Resume | — |
 | 2 | --re-run flag + previous failures | Re-run | — |
-| 3 | Spec package exists (REQ-*.md) | spec | quality-business-test |
-| 4 | Nyquist gaps exist (verification.json) | gap | quality-test-gen |
-| 5 | Default | code | quality-integration-test |
+| 3 | Spec package exists (REQ-*.md) | spec | quality-business-test (separate skill) |
+| 4 | Nyquist gaps exist (verification.json) | gap | quality-test-gen (separate skill) |
+| 5 | Default | code | quality-integration-test (separate skill) |
 
 Flags, artifact context resolution, and output formats defined in workflow auto-test.md.
 

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

@@ -46,7 +46,7 @@ After successful refactoring, ask user once: "Record refactoring pattern as codi
 
 **Next-step routing on completion:**
 - All tests pass → `/quality-sync` (update codebase docs)
-- Test failures after refactor → `/quality-debug {scope}`
+- Test failures after refactor → `/quality-debug "test failures after refactor in {scope}"`
 - No test suite available → `/quality-auto-test {phase}`
 </execution>
 

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

@@ -13,7 +13,7 @@ allowed-tools:
   - AskUserQuestion
 ---
 <purpose>
-Post-execution multi-perspective retrospective (复盘) for completed phases. Consumes existing execution artifacts (verification.json, review.json, issues.jsonl, plan.json, .summaries/, uat.md, state.json) and runs four parallel lenses — technical, process, quality, decision — to distill reusable insights. Routes each insight into the appropriate store: spec stub for reusable patterns, memory tip for process notes, issue for recurring gaps. Auto-scans for unreviewed completed phases and reports the backlog. Every insight is also persisted to `.workflow/knowhow/specs/learnings.md` as `<spec-entry>` blocks for cross-phase queryability.
+Post-execution multi-perspective retrospective (复盘) for completed phases. Consumes existing execution artifacts (verification.json, review.json, issues.jsonl, plan.json, .summaries/, uat.md, state.json) and runs four parallel lenses — technical, process, quality, decision — to distill reusable insights. Routes each insight into the appropriate store: spec stub for reusable patterns, memory tip for process notes, issue for recurring gaps. Auto-scans for unreviewed completed phases and reports the backlog. Every insight is also persisted to `.workflow/specs/learnings.md` as `<spec-entry>` blocks for cross-phase queryability.
 </purpose>
 
 <required_reading>
@@ -70,7 +70,7 @@ Follow `~/.maestro/workflows/retrospective.md` Stages 1–8 in order. Key invari
 - [ ] Spec entries (if any) appended as `<spec-entry>` to matching `.workflow/specs/{category-file}.md`
 - [ ] Issue rows (if any) match canonical issues.jsonl schema (status "open", full issue_history, all required fields)
 - [ ] Note tips (if any) created via `Skill({ skill: "manage-learn", args: "tip ..." })`
-- [ ] `specs/learnings.md` appended with one `<spec-entry>` per insight regardless of routing target
+- [ ] `.workflow/specs/learnings.md` appended with one `<spec-entry>` per insight regardless of routing target
 - [ ] No existing phase artifacts modified (verification.json, review.json, plan.json untouched)
 - [ ] Confirmation banner displays routing counts and next-step suggestions
 - [ ] Next step: `/manage-status` to review state, or `/manage-issue list --source retrospective` to triage created issues, or `/manage-learn list` to browse the knowhow library

package/.claude/commands/security-audit.md

@@ -16,6 +16,10 @@ Systematic security audit covering OWASP Top 10, dependency supply chain, secret
 CI/CD pipeline review, and optional STRIDE threat modeling. Three tiers control depth vs speed.
 </purpose>
 
+<required_reading>
+@~/.maestro/workflows/review.md
+</required_reading>
+
 <context>
 $ARGUMENTS — Parse tier and scope:
 - Tier: `quick` (default) | `standard` | `deep`
@@ -143,6 +147,26 @@ CONCERNS: {count} critical findings require immediate action
 NEXT: /quality-review
 --- END STATUS ---
 ```
+
+**Register artifact on completion** (so retrospective/harvest can trace this audit):
+```
+Append to state.json.artifacts[]:
+{
+  id: nextArtifactId(artifacts, "review"),  // RVW-NNN (security-audit reuses review type)
+  type: "review",
+  subtype: "security-audit",
+  milestone: current_milestone || null,
+  phase: target_phase || null,
+  scope: target_phase ? "phase" : "standalone",
+  path: "scratch/{YYYYMMDD}-security-audit-{tier}-{slug}",
+  status: critical_count == 0 ? "completed" : "completed_with_concerns",
+  tier: tier,                              // quick|standard|deep
+  harvested: false,
+  created_at: start_time,
+  completed_at: now()
+}
+```
+Write findings report to the same `path` (severity matrix, file:line refs, remediation).
 </execution>
 
 <success_criteria>

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

@@ -1,7 +1,7 @@
 ---
 name: spec-remove
 description: Remove spec entry by ID
-argument-hint: "<entry-id>"
+argument-hint: "<entry-id> [--cascade]"
 allowed-tools:
   - Read
   - Write
@@ -26,6 +26,9 @@ $ARGUMENTS -- expects `<entry-id>` (e.g., `spec-learnings-003`, `spec-coding-con
 **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.
+
+**Flags:**
+- `--cascade` — When the target spec is a ref-type entry (created via `spec-add --ref` and linked to a knowhow document), also delete the referenced knowhow file. Without this flag, ref-type removal leaves an orphan knowhow file.
 </context>
 
 <execution>
@@ -47,5 +50,6 @@ Follow '~/.maestro/workflows/specs-remove.md' completely.
 - [ ] 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
+- [ ] If `--cascade` and entry has a `ref` attribute: referenced knowhow file deleted, orphan avoided
+- [ ] Confirmation displayed with removed entry details (and cascaded knowhow path if applicable)
 </success_criteria>

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

@@ -8,7 +8,7 @@ allowed-tools: spawn_agents_on_csv, Read, Write, Edit, Bash, Glob, Grep, AskUser
 <purpose>
 Systematic pattern extraction from code via CSV wave pipeline. 4 parallel dimension agents
 scan a module, then a cross-reference agent deduplicates against existing patterns and
-produces a catalog. Discovered patterns persist to `specs/learnings.md` and optionally to
+produces a catalog. Discovered patterns persist to `.workflow/specs/learnings.md` and optionally to
 specs (via `spec-add`) and wiki.
 
 ```
@@ -50,7 +50,7 @@ $ARGUMENTS — target path/module and optional flags.
 Parse flags from `$ARGUMENTS`: `-y`/`--yes`, `--patterns <list>`, `--save-spec`, `--save-wiki`, `--continue`, `-c N`.
 Extract remaining text as target path/module.
 
-Resolve target to file list. Load coding specs: `maestro spec load --category coding` for documented patterns and conventions. Load existing patterns from `coding-conventions.md` + `specs/learnings.md` for dedup set. Browse wiki: `maestro wiki list --category coding`, load relevant entries.
+Resolve target to file list. Load coding specs: `maestro spec load --category coding` for documented patterns and conventions. Load existing patterns from `coding-conventions.md` + `.workflow/specs/learnings.md` for dedup set. Browse wiki: `maestro wiki list --category coding`, load relevant entries.
 
 ### Phase 2: Wave 1 — Parallel Dimension Scans
 
@@ -88,7 +88,7 @@ Single agent receives all wave 1 findings via `prev_context`. Tasks:
 ### Phase 4: Persist
 
 1. Write `KNW-decompose-{slug}-{date}.md` with full catalog
-2. Append each **new** pattern to `specs/learnings.md` (source: "decompose", category: "pattern")
+2. Append each **new** pattern to `.workflow/specs/learnings.md` (source: "decompose", category: "pattern")
 3. If `--save-spec`: invoke `spec-add` per new pattern
 4. If `--save-wiki`: create wiki note per dimension group
 </execution>
@@ -108,6 +108,6 @@ Single agent receives all wave 1 findings via `prev_context`. Tasks:
 - [ ] Each finding has: name, dimension, confidence, anchors, description
 - [ ] Cross-reference performed (documented / known / new)
 - [ ] Pattern catalog written to `KNW-decompose-{slug}-{date}.md`
-- [ ] New patterns appended to `specs/learnings.md` with stable INS-ids
+- [ ] New patterns appended to `.workflow/specs/learnings.md` with stable INS-ids
 - [ ] If --save-spec / --save-wiki: entries created
 </success_criteria>

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

@@ -8,7 +8,7 @@ allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
 <purpose>
 Guided reading experience for code files, wiki entries, or topics. Walks through content
 section by section using 4 forcing questions to extract patterns, identify assumptions,
-and build a structured understanding map. Insights persist to `specs/learnings.md`.
+and build a structured understanding map. Insights persist to `.workflow/specs/learnings.md`.
 
 Unlike `learn-decompose` which is parallel pattern extraction, this is sequential
 deep reading that builds understanding incrementally.
@@ -57,7 +57,7 @@ Cross-reference against `coding-conventions.md`: documented vs undocumented patt
 
 ### Stage 5: Persist
 1. Write `KNW-follow-{slug}-{date}.md` with understanding map
-2. Append new patterns to `specs/learnings.md` (source: "follow", stable INS-ids)
+2. Append new patterns to `.workflow/specs/learnings.md` (source: "follow", stable INS-ids)
 3. If `--save-wiki`: create wiki note entry
 
 **Next steps:** `/learn-decompose <path>`, `/spec-add coding ...`, `/learn-second-opinion <file>`
@@ -79,5 +79,5 @@ Cross-reference against `coding-conventions.md`: documented vs undocumented patt
 - [ ] Patterns extracted with file:line anchors
 - [ ] Understanding map produced with concepts, patterns, assumptions, questions
 - [ ] `KNW-follow-{slug}-{date}.md` written
-- [ ] `specs/learnings.md` appended with stable INS-ids
+- [ ] `.workflow/specs/learnings.md` appended with stable INS-ids
 </success_criteria>

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

@@ -29,7 +29,7 @@ $ARGUMENTS — question text and optional flags.
 ### Stage 1: Frame the Question
 - Parse question, generate slug, create investigation directory
 - Load debug specs: `maestro spec load --category debug` for known issues and patterns
-- Search prior knowledge: `maestro wiki list --category debug`, wiki search, grep specs/learnings.md
+- Search prior knowledge: `maestro wiki list --category debug`, wiki search, grep .workflow/specs/learnings.md
 - Write initial `understanding.md`
 
 ### Stage 2: Evidence Collection
@@ -55,7 +55,7 @@ If all hypotheses fail: broaden scope, search wiki with alt keywords, or mark IN
 
 ### Stage 5: Synthesize + Persist
 1. Write `report.md` with answer, evidence trail, hypothesis results
-2. Append to `specs/learnings.md`:
+2. Append to `.workflow/specs/learnings.md`:
    - Confirmed → category: "technique" / "pattern"
    - Disproved → category: "gotcha"
 3. Display summary with next-step routing
@@ -79,6 +79,6 @@ If all hypotheses fail: broaden scope, search wiki with alt keywords, or mark IN
 - [ ] At least 1 hypothesis formed and tested
 - [ ] understanding.md tracks evolving understanding
 - [ ] report.md written with answer and evidence trail
-- [ ] Findings appended to specs/learnings.md with stable INS-ids
+- [ ] Findings appended to .workflow/specs/learnings.md with stable INS-ids
 - [ ] 3-strike escalation triggered if all hypotheses fail
 </success_criteria>

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

@@ -41,7 +41,7 @@ $ARGUMENTS — lens selection and scope flags.
 **Trend comparison** if prior `retro-*.json` exists.
 
 ### Phase 3: Decision Lens (skip if --lens git)
-**3a: Collect decisions** from wiki, specs, git log, phase context, specs/learnings.md.
+**3a: Collect decisions** from wiki, specs, git log, phase context, .workflow/specs/learnings.md.
 **3b: Build decision registry** per decision (id, title, source, rationale, alternatives, evidence).
 
 **3c: Multi-perspective evaluation** via spawn_agents_on_csv (3 parallel agents):
@@ -58,7 +58,7 @@ $ARGUMENTS — lens selection and scope flags.
 Write `KNW-retro-{date}.md` + `KNW-retro-{date}.json` with metrics, sessions, hotspots, decision health, combined insights, recommended actions.
 
 ### Phase 5: Persist
-Append insights to `specs/learnings.md` (source: "retro-git" or "retro-decision"). Display summary.
+Append insights to `.workflow/specs/learnings.md` (source: "retro-git" or "retro-decision"). Display summary.
 
 **Next steps:** `/learn-follow <path>`, `/quality-auto-test <area>`, `/learn-investigate <question>`
 </execution>
@@ -79,5 +79,5 @@ Append insights to `specs/learnings.md` (source: "retro-git" or "retro-decision"
 - [ ] Git lens: metrics computed, sessions detected, hotspots identified
 - [ ] Decision lens: decisions collected, 3 agents spawned in parallel, lifecycle classified
 - [ ] Unified report written to KNW-retro-{date}.md + KNW-retro-{date}.json
-- [ ] specs/learnings.md appended with insights (stable INS-ids)
+- [ ] .workflow/specs/learnings.md appended with insights (stable INS-ids)
 </success_criteria>

package/.codex/skills/learn-second-opinion/SKILL.md

@@ -11,7 +11,7 @@ Structured second-opinion for code, decisions, or plans. Three modes:
 - **challenge**: single adversarial agent via spawn_agents_on_csv (1 worker)
 - **consult**: interactive Q&A (no CSV wave — direct orchestration)
 
-Findings persist to `specs/learnings.md`. Decoupled from phase lifecycle.
+Findings persist to `.workflow/specs/learnings.md`. Decoupled from phase lifecycle.
 </purpose>
 
 <context>
@@ -62,7 +62,7 @@ Interactive loop via AskUserQuestion. Agent studies target, answers questions wi
 
 ### Phase 3: Persist
 1. Write `KNW-opinion-{slug}-{date}.md` with per-persona findings + synthesis
-2. Append non-trivial findings to `specs/learnings.md` (source: "second-opinion")
+2. Append non-trivial findings to `.workflow/specs/learnings.md` (source: "second-opinion")
 3. Display summary with verdict and next steps
 
 **Next steps:** `/manage-issue create`, `/learn-decompose <path>`, `/learn-follow <path>`
@@ -82,5 +82,5 @@ Interactive loop via AskUserQuestion. Agent studies target, answers questions wi
 - [ ] Mode executed: review (3 parallel agents), challenge (adversarial), or consult (interactive)
 - [ ] Synthesis produced with agreements, disagreements, verdict
 - [ ] Report written to `KNW-opinion-{slug}-{date}.md`
-- [ ] Non-trivial findings appended to `specs/learnings.md`
+- [ ] Non-trivial findings appended to `.workflow/specs/learnings.md`
 </success_criteria>

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

@@ -36,14 +36,15 @@ $ARGUMENTS -- phase number, topic text, and optional flags.
 <interview_protocol>
 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 AskUserQuestion with 2–4 options + a (Recommended) default; every question must include a `Proceed now` option so the user can end the interview at any time.
-- Never ask what code can verify — resolve via `state.json`, `roadmap.md`, `issues.jsonl`, `maestro spec load`, `maestro wiki search`, Grep, or Read.
+- One decision per turn via AskUserQuestion 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 wiki 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.
 
 Decision points: scope (phase / topic / milestone-wide / adhoc / --gaps) → depth (quick / standard / deep) → dimensions (which of the 6 to keep) → Go/No-Go threshold.
 
-Exit: on `Proceed now` or when all decision points are settled, write the table below into `context.md` under an `Interview Decisions` section (and mirror into `analysis.md` in full mode):
+Exit: when all decision points are settled (or user explicitly signals to proceed), finalize session metadata. The decision table (populated incrementally during interview) uses this schema:
 `| # | Decision | Choice | Source (user / code / default) |`
 </interview_protocol>
 

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

@@ -56,14 +56,15 @@ maestro-analyze → maestro-roadmap → maestro-plan
 <interview_protocol>
 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, and a `Proceed now` option.
-- Never ask what code can verify — resolve via `state.json`, existing artifacts, `maestro spec load`, or direct codebase exploration (Glob/Grep/Read) instead of prompting.
+- 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.
+- 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.
 
 Decision points: scope (full product / feature set / single feature) → spec type (service / api / library / platform) → focus areas → whether to run codebase exploration.
 
-Exit: on consensus or `Proceed now`, persist decisions in blueprint-config.json and proceed to Phase 1.
+Exit: on consensus or explicit user signal to proceed, finalize blueprint-config.json (decisions already written incrementally) and proceed to Phase 1.
 </interview_protocol>
 
 <execution>

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

@@ -39,28 +39,169 @@ $ARGUMENTS — topic text and optional flags.
 <interview_protocol>
 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; every question must include a `Proceed now` option.
-- Never ask what code can verify — resolve via `state.json`, the session directory, `maestro spec load`, or `maestro wiki search`.
+- 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 wiki 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.
+- 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.
 
 Decision points: mode (auto / single-role / review-only) / role selection and `--count` / `--from` upstream source / whether to enable design-research and the DESIGN.md sub-pipeline.
 
-Exit: on consensus or `Proceed now`, write the table below into `guidance-specification.md` §11 and session metadata:
+Exit: on consensus or explicit user signal to proceed, finalize session metadata. The §11 table (already populated incrementally) uses this schema:
 `| # | Decision | Choice | Source (user / code / default) |`
 </interview_protocol>
 
 <csv_schema>
 ```csv
 id,title,description,role,topic,guidance_spec,deps,context_from,wave,status,findings,output_file,error
-"1","Guidance Spec","...","guidance-generator","<topic>","","","","1","","","",""
-"2","System Architect","...","system-architect","<topic>","","1","1","2","","","system-architect/analysis.md",""
-"3","UI Designer","...","ui-designer","<topic>","","1","1","2","","","ui-designer/analysis.md",""
-"4","Cross-Role Review","...","cross-role-reviewer","<topic>","","2;3","2;3","3","","","",""
+"1","Guidance Spec","<W1 prompt — see <agent_prompt_template>>","guidance-generator","<topic>","","","","1","","","",""
+"2","System Architect","<W2 prompt — see <agent_prompt_template>>","system-architect","<topic>","","1","1","2","","","<ABS_SESSION>/system-architect/analysis.md",""
+"3","UI Designer","<W2 prompt — see <agent_prompt_template>>","ui-designer","<topic>","","1","1","2","","","<ABS_SESSION>/ui-designer/analysis.md",""
+"4","Cross-Role Review","<W3 prompt — see <agent_prompt_template>>","cross-role-reviewer","<topic>","","2;3","2;3","3","","","",""
 ```
+
+**Column semantics (orchestrator MUST honor when generating tasks.csv)**:
+- `description`: full agent prompt — orchestrator MUST inflate `<W1/W2/W3 prompt>` placeholders using the templates in `<agent_prompt_template>` below. Never leave it as `"..."` — the spawned agent reads ONLY this field as its task brief.
+- `output_file`: **index file only** (single primary deliverable used by Wave 3 reviewer to locate the role). Wave 2 role agents write multiple files (`analysis.md` + per-feature + findings) under the same `{role}/` directory; the CSV only tracks the index path for dependency wiring.
+- **All paths in CSV (`output_file`, any path referenced in `description`) MUST be absolute.** Orchestrator MUST resolve `<ABS_SESSION>` to the absolute session dir (e.g. `D:/proj/.workflow/.csv-wave/20260521-brainstorm-foo/`) before writing tasks.csv. Relative paths break agent Write calls.
+
 Wave 1: 1 guidance row. Wave 2: N role rows (parallel) — each writes `{role}/analysis.md` + `{role}/analysis-F-*.md` + `{role}/findings-*.md`. Wave 3: 1 reviewer row (reads analysis.md §2 Decision Digests; emits structured findings consumed by orchestrator).
 </csv_schema>
 
+<agent_prompt_template>
+The orchestrator MUST inflate the CSV `description` field per row using these templates before invoking `spawn_agents_on_csv`. Without inflation, spawned agents have no contract and will not write files.
+
+### W1 prompt (role: guidance-generator)
+
+```
+You are the guidance generator for a brainstorm session on: <topic>.
+
+OUTPUT: Write `<ABS_SESSION>/guidance-specification.md` using the Write tool. MUST be on disk; do NOT return as chat text.
+
+CONTRACT — guidance-specification.md sections:
+  §1 Project Positioning & Goals
+  §2 Concepts & Terminology (5–10 core terms table)
+  §3 Non-Goals (Out of Scope) with rationale
+  §4–N Role Decisions with RFC 2119 keywords (MUST / SHOULD / MAY / MUST NOT / SHOULD NOT)
+  Cross-Role Integration
+  Risks & Constraints
+  §10 Feature Decomposition (max 8 features, F-{3-digit} id + slug, independently implementable)
+  §11 Decision Tracking appendix (incrementally populated during interview)
+  §12 Cross-Role Resolutions (initially empty — populated by Wave 3)
+
+CONSTRAINTS:
+- All behavioural statements MUST use RFC 2119 keywords.
+- No interrogative sentences in the deliverable (all declarative).
+- After write, verify with Glob; emit `TASK COMPLETE` only after file exists on disk.
+```
+
+### W2 prompt (role: one of the 9 valid roles)
+
+```
+You are the <role> for a brainstorm session on: <topic>.
+
+INPUTS:
+- Read guidance-specification.md at: <ABS_SESSION>/guidance-specification.md
+- Extract decisions belonging to your role (by ID prefix) and the §10 feature list.
+- If <ABS_SESSION>/design-research.md exists, integrate it as evidence (cite by project name + section).
+
+OUTPUT: Write multiple files under `<ABS_SESSION>/<role>/` using the Write tool. Files on disk are the ONLY valid deliverable — do NOT return analysis as chat text.
+
+FILE LAYOUT (all under <ABS_SESSION>/<role>/):
+  analysis.md                          — INDEX (see structure below)
+  analysis-F-{id}-{slug}.md            — one per feature in guidance §10 (< 2000 words each)
+  findings-{slug}.md                   — additional discoveries (0 or more, < 1000 words each)
+
+analysis.md structure (MUST contain):
+  §1 Role Mandate (≤ 200 words: what you decide, what you defer, why you are here)
+  §2 Decision Digest — four tables:
+       Decisions      | ID | Feature | Stance | Constraints (RFC 2119) |
+       Interfaces     | Name | Contract | Consumers |
+       Cross-Cutting Positions | Topic | Stance |
+       Findings Summary | Slug | Title | Impact |
+     MUST have ≥ 1 Decisions row per feature in §10.
+  §3 Cross-Cutting Foundations — role-specific subsections (see role-specific addendum below).
+  §4 File Index — list every written file with its top-level headings.
+  §5 Outstanding TODOs
+
+REFERENCE, DON'T DUPLICATE:
+- Reference guidance decisions by ID (e.g., SA-03) — do NOT copy decision text.
+- Cross-link sub-files with relative links: `see [F-002](analysis-F-002-skill-engine.md)`.
+
+CONSTRAINTS:
+- Aim for ≥ 5 RFC 2119 keyword occurrences across analysis.md.
+- No interrogative sentences.
+- After all writes, verify with Glob that analysis.md and every analysis-F-*.md exist. Only then emit `TASK COMPLETE`.
+
+ROLE-SPECIFIC §3 ADDENDUM (use these as §3 subsection headings):
+- system-architect:       Data Model · State Machine · Error Handling · Observability · Configuration · Boundary Scenarios
+- data-architect:         Filesystem Layout · YAML Schemas · Indexer Algorithm · Ref Bridge · Lifecycle · Migration
+- ux-expert:              Information Architecture · Sigil/Input · Visual Choreography · Streaming · Confirmation · Interrupt · Accessibility
+- subject-matter-expert:  Pitfall Taxonomy · Pattern Fingerprints · Domain-Silence Decisions · Differentiation Thesis · Crosswalk
+- test-strategist:        Test Layers · Coverage Targets · Risk-Based Prioritization · Tooling
+- product-manager:        Personas · Success Metrics · Roadmap Shape · Prioritization Rationale
+- product-owner:          Backlog Decomposition · Acceptance Criteria · Done Definition
+- scrum-master:           Cadence · Ceremonies · Impediments · Flow Metrics
+- ui-designer:            Design Tokens · Component States · Visual Language · Animation
+
+(Orchestrator inflates only the addendum line matching the current row's role.)
+```
+
+### W3 prompt (role: cross-role-reviewer)
+
+```
+You are the cross-role reviewer for a brainstorm session on: <topic>.
+
+INPUTS — read these files (do NOT modify):
+- <ABS_SESSION>/guidance-specification.md
+- <ABS_SESSION>/<role_1>/analysis.md
+- <ABS_SESSION>/<role_2>/analysis.md
+- ... (one per role from Wave 2)
+
+(Orchestrator MUST inject the actual absolute paths for all completed Wave 2 rows.)
+
+TASK: Compare §2 Decision Digests across role analysis.md index files. Identify:
+- Conflicts: contradictory stances between roles on the same feature/topic
+- Gaps: §2 Interfaces consumers referencing definitions that no role owns
+- Synergies: §2 Findings Summary items that align across roles and should cross-reference
+
+OUTPUT — return this structured markdown report as your final message (do NOT write files; the orchestrator parses your output and applies patches):
+
+  ## Conflicts (need user decision)
+  ### C-001: <one-line summary>
+    patch_targets:
+      - target_file: <ABS_SESSION>/<role-A>/analysis-F-{id}-{slug}.md  (or <role-A>/analysis.md for cross-cutting)
+        target_heading: ## <exact heading text from §4 File Index>
+        edit_type: annotate_and_strikeout
+        edit_content: > **Cross-Role Resolution (C-001)**: <1-line resolution>
+      - target_file: <ABS_SESSION>/<role-B>/analysis-F-{id}-{slug}.md
+        target_heading: ## <exact heading text>
+        edit_type: annotate_and_strikeout
+
+  ## Gaps
+  ### G-001: ...
+    patch_targets:
+      - target_file: <ABS_SESSION>/<ref-role>/analysis.md   edit_type: annotate_after_heading
+        target_heading: ### Interfaces
+      - target_file: <ABS_SESSION>/<owner-role>/analysis.md edit_type: append_to_section
+        target_heading: ### Decisions
+
+  ## Synergy Opportunities
+  ### S-001: ...
+    patch_targets:
+      - target_file: <ABS_SESSION>/<role-A>/analysis-F-{id}-{slug}.md edit_type: annotate_after_heading
+      - target_file: <ABS_SESSION>/<role-B>/analysis-F-{id}-{slug}.md edit_type: annotate_after_heading
+
+  ## Summary
+  conflicts_count / gaps_count / synergies_count / review_confidence (0–1)
+
+CONSTRAINTS:
+- `edit_type` is a CLOSED vocabulary: only `annotate_after_heading` / `annotate_and_strikeout` / `append_to_section`.
+- `target_heading` MUST match the heading text verbatim as it appears in the target file's §4 File Index (case + punctuation). Never invent.
+- If zero conflicts/gaps/synergies detected, return a `## Summary` block with all counts = 0 and a one-line explanation. Do not fabricate findings.
+```
+</agent_prompt_template>
+
 <invariants>
 1. **Wave order sacred**: Guidance (W1) MUST complete before role design (W2); review (W3) MUST run only after all W2 rows complete.
 2. **CSV source of truth**: Master tasks.csv holds all state.

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

@@ -12,6 +12,8 @@ the worktree. Since `.workflow/` is gitignored, this command explicitly copies p
 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>

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

@@ -73,10 +73,11 @@ Read `.workflow/config.json`. If file missing, initialize with empty guard secti
 - Write config
 
 **`deny <path>`:**
-- Normalize path to forward slashes
+- Normalize path to forward slashes, ensure trailing slash for directories
+- If `guard.mode` is `allow`, switch to `deny` and clear paths with warning
 - Set `guard.mode = "deny"`
 - Add path to `guard.paths` (deduplicate)
-- Set `guard.enabled = true` if not already
+- Set `guard.enabled = true` if not already (symmetric with `allow`: adding a deny path auto-enables the guard)
 - Write config
 
 **Step 4: Confirm**

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

@@ -68,6 +68,8 @@ responsive-design.md, spatial-design.md, typography.md, ux-writing.md
 
 ## Chains
 
+Chain step names below reuse Command Routing names but resolve through the chain runner. To avoid ambiguity with Direct command invocation, internal display, todo items, and session status records always tag chain steps with the `impeccable:` prefix (e.g. `impeccable:craft`, `impeccable:critique`). The bare names in this table refer to the workflow file at `~/.maestro/workflows/impeccable/{name}.md` that the chain step reads.
+
 | Chain | Steps | Scenario |
 |-------|-------|----------|
 | build | teach? → explore? → shape → craft → critique → [refine] → audit → polish | New from scratch |
@@ -180,17 +182,17 @@ Before reading any command workflow:
 ## Chain Execution
 
 1. Prerequisites ✓
-2. **Display chain preview**: parse chain definition, output full step preview:
+2. **Display chain preview**: parse chain definition, output full step preview (chain steps prefixed `impeccable:` to disambiguate from Direct commands):
    ```
    ── Chain: build ──────────────────────────
-    1. teach        (conditional: PRODUCT.md missing)
-    2. explore      (conditional: DESIGN.md missing)
-    3. shape
-    4. craft
-    5. critique     ◆ quality gate (threshold: 26/40)
-    6. [refine]     ↺ auto-fix loop (max: 3)
-    7. audit        ◆ quality gate (threshold: 14/20)
-    8. polish
+    1. impeccable:teach        (conditional: PRODUCT.md missing)
+    2. impeccable:explore      (conditional: DESIGN.md missing)
+    3. impeccable:shape
+    4. impeccable:craft
+    5. impeccable:critique     ◆ quality gate (threshold: 26/40)
+    6. impeccable:[refine]     ↺ auto-fix loop (max: 3)
+    7. impeccable:audit        ◆ quality gate (threshold: 14/20)
+    8. impeccable:polish
    ─────────────────────────────────────────
    Target: {target}
    ```
@@ -204,9 +206,9 @@ Before reading any command workflow:
      "gate_history": [], "loop_count": 0, "status": "running" }
    ```
 4. **Init tracking**: create todo items for all chain steps
-   - One item per step, format: `[chain] step N: {command} — {description}`
+   - One item per step, format: `[chain] step N: impeccable:{command} — {description}` (use `impeccable:` prefix to disambiguate from Direct command items)
    - If conditional step is skipped, immediately mark completed
-   - Quality gate steps include threshold: `[chain] step 5: critique ◆ gate ≥26/40`
+   - Quality gate steps include threshold: `[chain] step 5: impeccable:critique ◆ gate ≥26/40`
 5. For each step:
    - Read `~/.maestro/workflows/impeccable/{command}.md` → execute
    - **Step start**: mark current step in_progress

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

@@ -2,7 +2,7 @@
 name: maestro-ralph
 description: Use when the optimal command sequence is unclear and needs automated state-based determination
 argument-hint: "<intent> [-y] | status | continue"
-allowed-tools: Read, Write, Edit, Bash, Glob, Grep, request_user_input
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, Skill, request_user_input
 ---
 <purpose>
 Closed-loop decision engine for the maestro workflow lifecycle.