maestro-flow 0.3.30 → 0.3.32

package/.claude/agents/cli-explore-agent.md

@@ -54,7 +54,7 @@ Phase 4: Output Generation
    - Read schema file and memorize requirements BEFORE any analysis begins
 
 3. **Project Context Loading** (from spec system):
-   - Load exploration specs: `maestro spec load --category exploration`
+   - Load exploration specs: `maestro spec load --category arch`
    - Extract: tech_stack, architecture, key_components, overview
    - If no specs returned, proceed with fresh analysis
 

package/.claude/agents/workflow-verifier.md

@@ -47,7 +47,7 @@ You perform goal-backward verification of completed work using a three-layer che
 - `.task/TASK-{NNN}.json` files with `convergence.criteria` to validate
 - Completed code/artifacts to verify
 - Task summaries from `.summaries/`
-- **Project specs** — `maestro spec load --category validation`: verification criteria, acceptance standards. Must verify code complies with loaded constraints.
+- **Project specs** — `maestro spec load --category quality`: verification criteria, acceptance standards. Must verify code complies with loaded constraints.
 
 ## Output
 `verification.json`:

package/.claude/commands/maestro-ralph-execute.md

@@ -1,6 +1,6 @@
 ---
 name: maestro-ralph-execute
-description: Single-step executor — find next pending command in ralph session, execute by type (decision/skill/cli), hand off to next iteration
+description: Single-step executor — find next pending step in session, execute by type (decision/skill/cli), hand off to next iteration
 argument-hint: "[-y] [session-id]"
 allowed-tools:
   - Read
@@ -12,34 +12,42 @@ allowed-tools:
   - Skill
 ---
 <purpose>
-Single-step executor for ralph command chains. Each invocation:
-1. Finds the next pending command in the ralph session JSON
+Unified single-step executor for both maestro and ralph sessions.
+All sessions stored at `.workflow/.maestro/*/status.json` with unified JSON schema.
+
+Each invocation:
+1. Finds the next pending step in the session
 2. Executes it based on node type (decision → ralph, skill → Skill(), cli → delegate)
 3. Updates status.json
 4. Hands off to next iteration via self-invocation or ralph callback
 
+Two session sources:
+- **source: "maestro"** — Static chain, no decision nodes. Steps are `type: "skill"|"cli"` only.
+- **source: "ralph"** — Adaptive chain with decision nodes. Steps include `type: "decision"`.
+
 Three node types drive different execution + handoff patterns:
-- **decision**: `Skill("maestro-ralph")` — ralph re-evaluates state, may expand chain
+- **decision**: `Skill("maestro-ralph")` — ralph re-evaluates state, may expand chain (ralph-only)
 - **skill**: `Skill({ skill, args })` — synchronous in-session → `Skill("maestro-ralph-execute")`
 - **cli**: `maestro delegate` background → STOP → callback → `Skill("maestro-ralph-execute")`
 
-Mutual invocation with `/maestro-ralph` forms a persistent self-perpetuating work loop.
+Mutual invocation with `/maestro-ralph` forms a persistent self-perpetuating work loop (ralph sessions).
+For maestro sessions, execution is purely sequential with no decision callbacks.
 </purpose>
 
 <context>
-$ARGUMENTS — optional `-y` flag + optional session ID. If session ID omitted, finds latest running ralph session.
+$ARGUMENTS — optional `-y` flag + optional session ID. If session ID omitted, finds latest running session.
 
 **Flag parsing:**
 ```
 Parse $ARGUMENTS:
   Contains "-y" or "--yes" → auto = true, remove flag from remaining args
-  Remaining → session_id (if matches ralph-* pattern)
+  Remaining → session_id (if matches maestro-* or ralph-* pattern)
 ```
 
 **Session discovery:**
-Scan `.workflow/.ralph/ralph-*/status.json` for `status == "running"`, sorted by `created_at` descending.
+Scan `.workflow/.maestro/*/status.json` for `status == "running"`, sorted by `updated_at` or dir mtime descending.
 If remaining args match a session ID pattern, use that specific session.
-Also read `session.auto` from status.json — if `true`, treat as `-y` even if flag not passed（ralph 已写入）。
+Also read `session.auto_mode` from status.json — if `true`, treat as `-y` even if flag not passed.
 </context>
 
 <execution>
@@ -47,27 +55,27 @@ Also read `session.auto` from status.json — if `true`, treat as `-y` even if f
 ## Step 1: Locate Session
 
 ```
-If $ARGUMENTS matches ralph-* pattern:
-  session_path = .workflow/.ralph/{$ARGUMENTS}/status.json
+If $ARGUMENTS matches maestro-* or ralph-* pattern:
+  session_path = .workflow/.maestro/{$ARGUMENTS}/status.json
 Else:
-  Scan .workflow/.ralph/ralph-*/status.json
+  Scan .workflow/.maestro/*/status.json
   Filter: status == "running"
-  Sort: created_at DESC
+  Sort: mtime DESC (or updated_at DESC)
   Take first
 
 If no session found:
-  Output: "无运行中的 ralph 会话。使用 /maestro-ralph 创建新会话。"
+  Output: "无运行中的会话。使用 /maestro 或 /maestro-ralph 创建新会话。"
   End.
 ```
 
-Read status.json → extract: `id`, `steps[]`, `current_step`, `status`, `phase`.
+Read status.json → extract: `session_id`, `source`, `steps[]`, `current_step`, `status`, `phase`, `auto_mode`.
 
-## Step 2: Find Next Pending Command
+## Step 2: Find Next Pending Step
 
 ```
 next = steps.find(step => step.status == "pending")
 
-If no pending command:
+If no pending step:
   → Step 5 (Complete)
 ```
 
@@ -79,21 +87,27 @@ Before execution, enrich `next.args` with context from session and prior outputs
 1. `status.json.intent` — user's original input text
 2. `status.json.phase` — current phase number
 3. `status.json.milestone` — current milestone name
-4. `.workflow/state.json.artifacts[]` — latest artifacts for path resolution
-5. Previous completed command outputs — scratch dirs, session IDs
+4. `status.json.context` — nested context object (plan_dir, analysis_dir, scratch_dir, etc.)
+5. `.workflow/state.json.artifacts[]` — latest artifacts for path resolution
+6. Previous completed step outputs — scratch dirs, session IDs
 
 **Placeholder substitution in args:**
 ```
-{phase}       → status.phase
-{milestone}   → status.milestone
-{intent}      → status.intent
-{scratch_dir} → latest artifact path for current phase from state.json
+{phase}        → status.phase
+{milestone}    → status.milestone
+{intent}       → status.intent
+{description}  → status.intent (alias)
+{scratch_dir}  → status.context.scratch_dir or latest artifact path
+{plan_dir}     → status.context.plan_dir
+{analysis_dir} → status.context.analysis_dir
+{issue_id}     → status.context.issue_id
+{milestone_num}→ status.context.milestone_num
 ```
 
-**Per-command enrichment** (when args is empty or only has phase number):
+**Per-skill enrichment** (when args is empty or only has phase number):
 
-| Command | Required context | Source |
-|---------|-----------------|--------|
+| Skill | Required context | Source |
+|-------|-----------------|--------|
 | maestro-brainstorm | topic description | `status.intent` — pass as `"{intent}"` |
 | maestro-roadmap | description + context | `status.intent` — pass as `"{intent}"` |
 | maestro-analyze | phase or topic | `{phase}` or `"{intent}"` if no phase |
@@ -122,7 +136,7 @@ Write status.json
 ```
 next.status = "running"
 next.started_at = new Date().toISOString()
-status.current = next.index
+status.current_step = next.index
 status.updated_at = new Date().toISOString()
 
 Write status.json
@@ -133,19 +147,20 @@ Display step banner:
 ------------------------------------------------------------
   [{next.index}/{steps.length - 1}] {next.skill} [{next.type}]
 ------------------------------------------------------------
+  Session: {session_id} [{source}]
   Args: {next.args}
   {next.type == "decision" ? "Retry: " + JSON.parse(next.args).retry_count + "/" + JSON.parse(next.args).max_retries : ""}
 ```
 
-**Context weight hint** (after 4+ completed steps):
+**Context weight hint** (after 4+ completed steps, skip if auto):
 ```
-If completed_count >= 4:
+If completed_count >= 4 && !auto:
   Display: ⚡ 已执行 {completed_count} 步，上下文较重。可 /maestro-ralph continue 在新上下文恢复。
 ```
 
 ## Step 4: Execute by Type
 
-### 4a. decision node
+### 4a. decision node (ralph-only)
 
 Decision nodes hand control back to ralph for re-evaluation.
 
@@ -173,10 +188,12 @@ auto_flag_map = {
   "maestro-analyze": "-y",
   "maestro-brainstorm": "-y",
   "maestro-roadmap": "-y",
+  "maestro-ui-design": "-y",
   "maestro-plan": "-y",
   "maestro-execute": "-y",
   "quality-business-test": "-y",
   "quality-test": "-y --auto-fix",
+  "quality-retrospective": "-y",
   "maestro-milestone-complete": "-y"
 }
 flag = auto_flag_map[next.skill] || ""
@@ -191,6 +208,12 @@ On success:
 ```
 next.status = "completed"
 next.completed_at = new Date().toISOString()
+
+Scan output for context propagation signals:
+  PHASE: N         → status.phase
+  scratch_dir: path → context.scratch_dir
+  SPEC-xxx         → context.spec_session_id
+
 Write status.json
 
 Display: [N/total] ✓ {next.skill} completed
@@ -229,7 +252,7 @@ Background delegate execution with stop-and-wait pattern.
 
 Resolve CLI tool from session or default config:
 ```
-cli_tool = session.cli_tool || "gemini"   // from ralph status.json or fallback
+cli_tool = session.cli_tool || "gemini"
 ```
 
 ```
@@ -254,6 +277,9 @@ Retrieve output: maestro delegate output <exec_id>
 
 next.status = "completed"
 next.completed_at = new Date().toISOString()
+
+Scan output for context propagation (same as 4b).
+
 Write status.json
 
 Display: [N/total] ✓ {next.skill} completed [cli]
@@ -286,19 +312,20 @@ Write status.json
 Display completion report:
 ```
 ============================================================
-  RALPH COMPLETE
+  SESSION COMPLETE
 ============================================================
-  Session:  {id}
+  Session:  {session_id} [{source}]
+  Chain:    {chain_name}
   Phase:    {phase}
   Steps:    {completed}/{total}
 
-  {steps.map(cmd => {
-    icon = cmd.status == "completed" ? "✓" :
-           cmd.status == "skipped"   ? "—" :
-           cmd.status == "failed"    ? "✗" : " "
-    type_badge = cmd.type == "decision" ? "◆" :
-                 cmd.type == "cli"      ? "⚡" : " "
-    return `  [${icon}] ${cmd.index}. ${type_badge} ${cmd.skill} ${cmd.args} [${cmd.type}]`
+  {steps.map(step => {
+    icon = step.status == "completed" ? "✓" :
+           step.status == "skipped"   ? "—" :
+           step.status == "failed"    ? "✗" : " "
+    type_badge = step.type == "decision" ? "◆" :
+                 step.type == "cli"      ? "⚡" : " "
+    return `  [${icon}] ${step.index}. ${type_badge} ${step.skill} ${step.args} [${step.type}]`
   })}
 ============================================================
 ```
@@ -310,23 +337,25 @@ Display completion report:
 <error_codes>
 | Code | Severity | Description | Recovery |
 |------|----------|-------------|----------|
-| E001 | error | No running ralph session found | Suggest /maestro-ralph to create |
+| E001 | error | No running session found | Suggest /maestro or /maestro-ralph to create |
 | E002 | error | Session status.json corrupt or unreadable | Show path, suggest manual check |
-| E003 | error | CLI delegate failed + user chose abort | Mark paused, suggest /maestro-ralph continue |
+| E003 | error | CLI delegate failed + user chose abort | Mark paused, suggest resume |
 | W001 | warning | Step completed with warnings | Log and continue |
-| W002 | warning | Context getting heavy (step >= 4) | Hint: /maestro-ralph continue for fresh context |
+| W002 | warning | Context getting heavy (step >= 4) | Hint: fresh context resume |
 </error_codes>
 
 <success_criteria>
-- [ ] Session discovery finds latest running ralph session
-- [ ] `-y` flag parsed from args OR inherited from session.auto
+- [ ] Session discovery scans .workflow/.maestro/ (covers both maestro-* and ralph-* sessions)
+- [ ] Reads unified JSON: steps[], current_step, session_id, auto_mode, source
+- [ ] `-y` flag parsed from args OR inherited from session.auto_mode
 - [ ] Pending step correctly identified from steps[]
-- [ ] decision nodes hand off to maestro-ralph via Skill()
+- [ ] decision nodes hand off to maestro-ralph via Skill() (ralph sessions only)
 - [ ] skill nodes execute synchronously via Skill() and self-invoke next
-- [ ] `-y` auto flag 按传播表附加到目标 skill args
 - [ ] cli nodes use maestro delegate with run_in_background + stop pattern
+- [ ] `-y` auto flag 按传播表附加到目标 skill args
+- [ ] Context propagation: output signals update status.json.context
 - [ ] status.json updated after every status change (resume-safe)
 - [ ] auto 模式：失败重试一次后 auto-skip；非 auto：AskUserQuestion retry/skip/abort
-- [ ] Completion report shows all steps with status icons
+- [ ] Completion report shows all steps with status icons and type badges
 - [ ] Self-invocation chain continues until all steps complete
 </success_criteria>

package/.claude/commands/maestro-ralph.md

@@ -26,7 +26,7 @@ Key difference from maestro coordinator:
 - maestro: static chainMap → one-time selection → chain-execute runs all steps
 - ralph: living chain → decision nodes re-evaluate after each critical step → chain grows/shrinks dynamically
 
-Produces session at `.workflow/.ralph/ralph-{YYYYMMDD-HHmmss}/status.json`.
+Produces session at `.workflow/.maestro/ralph-{YYYYMMDD-HHmmss}/status.json` using unified JSON schema (source: "ralph").
 Mutual invocation with `/maestro-ralph-execute` forms a persistent self-perpetuating work loop.
 </purpose>
 
@@ -38,13 +38,13 @@ $ARGUMENTS — user intent text, or keywords.
 - `continue` — Find latest running session → `Skill({ skill: "maestro-ralph-execute" })`. **End.**
 
 **Decision-node trigger detection:**
-If a running ralph session exists AND `commands[current].type == "decision"` AND `commands[current].status == "running"`:
+If a running ralph session exists AND `steps[current_step].type == "decision"` AND `steps[current_step].status == "running"`:
 → Enter **Decision Evaluation Mode** (Step 2b) instead of New Session Mode.
 
 **State files read:**
 - `.workflow/state.json` — artifact registry, milestone, phase status
 - `.workflow/roadmap.md` — milestone/phase structure
-- `.workflow/.ralph/ralph-*/status.json` — ralph session state
+- `.workflow/.maestro/ralph-*/status.json` — ralph session state
 </context>
 
 <execution>
@@ -57,8 +57,8 @@ Parse $ARGUMENTS:
   "continue" → handleContinue(). End.
   
 Check running ralph session:
-  Scan .workflow/.ralph/ralph-*/status.json for status == "running"
-  If found AND commands[current].type == "decision" AND commands[current].status == "running":
+  Scan .workflow/.maestro/ralph-*/status.json for status == "running"
+  If found AND steps[current_step].type == "decision" AND steps[current_step].status == "running":
     → Step 2b (Decision Evaluation Mode)
   Else if $ARGUMENTS is non-empty:
     → Step 2a (New Session Mode)
@@ -68,13 +68,13 @@ Check running ralph session:
 
 ### handleStatus()
 ```
-Scan .workflow/.ralph/ralph-*/status.json (latest by created_at)
+Scan .workflow/.maestro/ralph-*/status.json (latest by created_at)
 Display:
   Session:  {id}
   Status:   {status}
   Position: {lifecycle_position}
   Progress: {completed}/{total} commands
-  Current:  [{current}] {commands[current].skill} [{commands[current].type}]
+  Current:  [{current}] {steps[current_step].skill} [{steps[current_step].type}]
   
   Commands:
     [✓] 0. maestro-analyze 1         [skill]
@@ -264,21 +264,38 @@ milestone-complete maestro-milestone-complete    skill   decision:post-milestone
 
 ```
 session_id = "ralph-{YYYYMMDD-HHmmss}"
-session_dir = ".workflow/.ralph/{session_id}/"
+session_dir = ".workflow/.maestro/{session_id}/"
 
 Write status.json:
 {
-  "id": "{session_id}",
+  "session_id": "{session_id}",
+  "source": "ralph",
   "created_at": "{ISO}",
+  "updated_at": "{ISO}",
   "intent": "{user_intent}",
   "status": "running",
+  "chain_name": "ralph-lifecycle",
+  "task_type": "lifecycle",
   "lifecycle_position": "{position}",
   "target": "milestone-complete",
   "phase": {N},
   "milestone": "{M}",
-  "commands": [...],
-  "current": 0,
-  "updated_at": "{ISO}"
+  "auto_mode": false,
+  "cli_tool": "gemini",
+  "quality_mode": "standard",
+  "passed_gates": [],
+  "context": {
+    "issue_id": null,
+    "milestone_num": null,
+    "spec_session_id": null,
+    "scratch_dir": null,
+    "plan_dir": null,
+    "analysis_dir": null,
+    "brainstorm_dir": null
+  },
+  "steps": [...],
+  "waves": [],
+  "current_step": 0
 }
 ```
 
@@ -324,7 +341,7 @@ Triggered when ralph-execute encounters a decision node and hands back to ralph.
 
 ### 2b.1: Load session + locate results
 
-Read ralph session status.json. Identify the decision node at `commands[current]`.
+Read ralph session status.json. Identify the decision node at `steps[current_step]`.
 
 **Locate result files** — find the artifact dir for current phase:
 ```
@@ -478,7 +495,7 @@ When inserting new commands after current position:
 
 ```
 new_commands = buildInsertionCommands(...)  // each with appropriate type/skill/args
-splice commands[] at position (current + 1), insert new_commands
+splice steps[] at position (current_step + 1), insert new_commands
 Reindex: commands.forEach((cmd, i) => cmd.index = i)
 ```
 
@@ -486,7 +503,7 @@ Reindex: commands.forEach((cmd, i) => cmd.index = i)
 
 ```
 Mark current decision node status = "completed", completed_at = now
-Update status.json: commands[], current, updated_at
+Update status.json: steps[], current_step, updated_at
 
 If commands were inserted:
   Display: ◆ Decision: {type} → {outcome}, +{N} commands inserted

package/.claude/commands/maestro.md

@@ -1,6 +1,6 @@
 ---
 name: maestro
-description: Intelligent coordinator - analyze intent + read project state → select optimal command chain → execute via internal or CLI delegate
+description: Intelligent coordinator - analyze intent + read project state → select optimal command chain → dispatch to unified executor
 argument-hint: "\"intent text\" [-y] [-c] [--dry-run] [--exec auto|cli|internal] [--tool <name>] [--super]"
 allowed-tools:
   - Read
@@ -19,17 +19,16 @@ Two routing modes:
 1. **Intent-based**: User describes a goal → classify task type → select/compose command chain → confirm → execute
 2. **State-based**: Read .workflow/state.json → determine next logical step → suggest/execute (triggered by `continue`/`next`)
 
-Per-step execution engine (default: auto):
-- **internal**: Execute via Skill() in current session — output visible in conversation, synchronous, user can intervene
-- **CLI delegate**: Heavy execution steps — context isolation, template-driven prompts, gemini quality analysis
+Per-step type selection (default: auto):
+- **skill**: Execute via Skill() in current session — output visible in conversation, synchronous, user can intervene
+- **cli**: Heavy execution steps via CLI delegate — context isolation, template-driven prompts
 
 Produces session directory at `.workflow/.maestro/{session_id}/` with status.json tracking chain progress.
-Executes commands sequentially with artifact propagation between steps.
+Dispatches to unified executor (`maestro-ralph-execute`) for sequential step execution with artifact propagation.
 </purpose>
 
 <deferred_reading>
-- [maestro.md](~/.maestro/workflows/maestro.md) — read at execution start (Steps 1-3: intent analysis, chain selection, session setup)
-- [maestro-chain-execute.md](~/.maestro/workflows/maestro-chain-execute.md) — read when dispatching chain execution (Step 4) or resume mode
+- [maestro.md](~/.maestro/workflows/maestro.md) — read at execution start (Steps 1-3: intent analysis, chain selection, session setup; Step 4 dispatches to unified executor)
 - [maestro-super.md](~/.maestro/workflows/maestro-super.md) — read when `--super` flag is active
 </deferred_reading>
 
@@ -55,7 +54,7 @@ $ARGUMENTS — user intent text, or special keywords.
 </context>
 
 <execution>
-**Resume mode (`-c`):** Skip selection workflow entirely — scan `.workflow/.maestro/` for latest session, then read `~/.maestro/workflows/maestro-chain-execute.md` and follow it with `$SESSION_PATH` = discovered session path. **End.**
+**Resume mode (`-c`):** Skip selection workflow entirely — scan `.workflow/.maestro/` for latest session, then `Skill({ skill: "maestro-ralph-execute" })`. The unified executor discovers the running session and resumes from the next pending step. **End.**
 
 **Normal mode:** Read `~/.maestro/workflows/maestro.md` from deferred_reading, then follow it completely.
 
@@ -109,12 +108,12 @@ In auto mode, maestro also:
 - [ ] Intent classified with task_type, complexity, clarity_score
 - [ ] Project state read and incorporated into routing
 - [ ] Command chain selected and confirmed (or auto-confirmed with -y)
-- [ ] Per-step engine selected (auto routes heavy steps to CLI, observable steps to internal)
+- [ ] Per-step type selected (auto routes heavy steps to "cli", observable steps to "skill")
 - [ ] Auto flags correctly propagated to supporting commands only
 - [ ] Session directory created at .workflow/.maestro/{session_id}/
-- [ ] status.json created with steps[], context, and tracking fields
+- [ ] status.json created with unified schema (source: "maestro", steps[] with type field)
 - [ ] Low-complexity intents routed to maestro-quick
-- [ ] All chains dispatched via execution workflow (maestro-chain-execute.md) with status.json tracking
+- [ ] All chains dispatched via unified executor (maestro-ralph-execute) with status.json tracking
 - [ ] Phase numbers auto-detected and passed to downstream commands
 - [ ] (super mode) Requirements expanded and validated via Gemini before roadmap creation
 - [ ] (super mode) Each milestone scored ≥ 80% before advancing

package/.claude/skills/team-quality-assurance/roles/executor/role.md

@@ -26,7 +26,7 @@ Run test suites, collect coverage data, and perform automatic fix cycles when te
 | Target layer | task description `layer: L1/L2/L3` | Yes |
 
 1. Extract session path and target layer from task description
-2. Load validation specs: Run `ccw spec load --category validation` for verification rules and acceptance criteria
+2. Load validation specs: Run `ccw spec load --category quality` for verification rules and acceptance criteria
 3. Read .msg/meta.json for strategy and generated test file list
 3. Detect test command by framework:
 

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

@@ -110,20 +110,30 @@ After each barrier skill completes, read its artifacts and update `state.context
 ```json
 {
   "session_id": "maestro-{YYYYMMDD-HHMMSS}",
+  "source": "maestro",
   "created_at": "ISO",
+  "updated_at": "ISO",
   "intent": "...",
   "task_type": "...",
   "chain_name": "...",
   "phase": null,
+  "milestone": null,
   "auto_mode": false,
   "exec_mode": "auto",
   "cli_tool": "codex",
-  "gemini_session_id": null,
-  "step_analyses": [],
-  "context": { "plan_dir": null, "analysis_dir": null,
-               "brainstorm_dir": null, "spec_session_id": null, "gaps": null },
+  "lifecycle_position": null,
+  "target": null,
+  "context": {
+    "issue_id": null,
+    "milestone_num": null,
+    "spec_session_id": null,
+    "scratch_dir": null,
+    "plan_dir": null,
+    "analysis_dir": null,
+    "brainstorm_dir": null
+  },
   "waves": [],
-  "steps": [{ "index": 0, "skill": "...", "args": "", "engine": null, "status": "pending", "started_at": null, "completed_at": null, "wave_n": null }],
+  "steps": [{ "index": 0, "skill": "...", "args": "", "type": "skill", "status": "pending", "started_at": null, "completed_at": null, "error": null, "wave_n": null }],
   "current_step": 0,
   "status": "running"
 }

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

@@ -409,6 +409,10 @@ Write wave CSV with `prev_context`, execute `spawn_agents_on_csv` for synthesis
 
 6. **Auto-create issues from Deferred items**: Filter decisions with `classification == "Deferred"`, append each as issue to `.workflow/issues/issues.jsonl`.
 
+7b. **Spec Enrichment**: For each Locked decision in context.md, persist via CLI:
+   - `maestro spec add arch "<decision.title>" "<decision.rationale>" --keywords ... --source analyze:{sessionId}`
+   - For non-trivial code patterns discovered during exploration → `maestro spec add coding ...`
+
 7. **Register artifact in state.json**: Append `{ id: "ANL-{next_id}", type: "analyze", milestone, phase, scope, path: scratchDir, status: "completed", depends_on: null, harvested: false, created_at, completed_at }`.
 8. Copy final outputs (context.md, analysis.md, conclusions.json) from CSV session folder to `scratchDir`
 9. Display summary

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

@@ -249,7 +249,11 @@ Blocked/failed tasks cascade: mark all downstream dependents as `skipped` with e
 
 4. **Register EXC artifact in state.json**: Find matching plan artifact, create `{ id: "EXC-{next_id}", type: "execute", milestone, phase, scope, path, status: "completed", depends_on: plan_artifact.id, harvested: false, created_at, completed_at }`
 
-5. **Extract incremental learnings**: Read `.summaries/`, dedup against existing specs, append to `.workflow/specs/learnings.md` as `<spec-entry>` (category=learning), mark artifact `harvested: true`
+5. **Extract incremental specs**: Read `.summaries/`, use `maestro spec add` CLI:
+   - Learnings/pitfalls → `maestro spec add learning "<title>" "<content>" --keywords ... --source execute:{PLAN_DIR}`
+   - Design rationale → `maestro spec add coding "<title>" "<content>" --keywords ...`
+   - Root cause/workaround → `maestro spec add debug "<title>" "<content>" --keywords ...`
+   Mark artifact `harvested: true`
 
 6. **Post-task Knowledge Inquiry**: Prompt user to capture knowledge when:
    - Execution deviation detected (plan change) -> `/spec-add arch`

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

@@ -98,7 +98,13 @@ Configuration questions (or defaults for -y): granularity (fine/medium/coarse),
 
 ### Step 9: Initialize specs/
 
-Create in `.workflow/specs/`: `conventions.md` (detected coding conventions), `learnings.md` (empty placeholder).
+Run `Bash("maestro spec init")` to create empty seed files in `.workflow/specs/`.
+
+If project state is **code** (existing source files detected):
+- Auto-trigger `Skill({ skill: "spec-setup" })` to scan codebase and populate specs with detected conventions.
+
+If project state is **empty** (greenfield):
+- Skip spec-setup. Specs are populated progressively by analyze, plan, and execute stages via `maestro spec add`.
 
 ### Step 10: Completion Report
 

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

@@ -312,6 +312,11 @@ spawn_agents_on_csv({
 
 2. **Revision loop** (max 3 rounds): If critical issues found, regenerate affected tasks.
 
+2b. **Spec Enrichment**: Persist cross-task reusable design decisions:
+   - `maestro spec add coding|arch "<decision.title>" "<rationale>" --keywords ... --source plan:{sessionId}`
+   - Test strategy decisions → `maestro spec add test ...`
+   - Typical: 0-3 entries per plan session
+
 3. **Export results**:
    - Export `results.csv` from master `tasks.csv`
    - Generate `context.md`: summary (phase, task count, wave count, complexity, exploration count), exploration findings per angle, plan overview (approach, task IDs, waves), next steps