maestro-flow 0.5.34 → 0.5.36

package/workflows/impeccable/codex.md

@@ -1,9 +1,5 @@
 # Codex: Visual Direction & Asset Production
 
-This file is loaded by `/maestro-impeccable craft` when the harness has native image generation (currently Codex via `image_gen`). Other harnesses skip it. It covers the two craft steps that depend on real image generation: landing the visual direction, and producing the raster assets the implementation will compose.
-
-Read this *before* generating any images. The order matters, and the per-step user pauses are what keep generated imagery from drifting away from the brief.
-
 ### Four stop points before code
 
 Steps A through D each end with the user. Do not advance past any of them on your own read of the situation.

package/workflows/init.md

@@ -113,6 +113,14 @@ If `.workflow/specs/` does not exist:
    - Skip spec-setup (nothing to scan)
    - Note: Specs will be progressively populated as pipeline stages produce knowledge
 
+## Step 2.5: Domain Init (first-run only)
+
+If `.workflow/domain/` does not exist:
+
+1. Run `Bash("maestro domain init")` — creates `.workflow/domain/glossary.yaml` with empty terms array
+2. If brownfield project (has source files): run `maestro domain discover --auto` to scan codebase for initial term candidates, present top 5 for confirmation
+3. If greenfield project: skip discovery (no codebase to scan); domain terms will be populated by grill/brainstorm sessions via finish-work extraction
+
 
 ---
 
@@ -126,6 +134,7 @@ Verify all required directories and files exist:
   state.json         ✓
   config.json        ✓
   specs/             ✓
+  domain/            ✓ (glossary.yaml)
   research/          ✓ (if research enabled)
   scratch/           ✓ (create empty)
   milestones/        ✓ (create empty)

package/workflows/interview-mechanics.md

@@ -3,5 +3,6 @@
 - **One decision per turn** via AskUserQuestion, 2-4 options, first marked `(Recommended)`. User can redirect via `Other`.
 - **Search-first**: resolve via state.json → session artifacts → `maestro spec/wiki` → Glob/Grep/Read → Agent(Explore) / delegate. Never ask what code can answer.
 - **Writeback**: each decision **immediately written to disk** before the next question. No batching.
-- **Skip**: auto mode (`-y`), resume (`-c`), or unambiguous input → skip entire interview.
-- **Decision table**: `| # | Decision | Choice | Source (user / code / default) |`
+- **Skip**: auto mode (`-y`) → 逐问题 Search-first 代答（不跳过整段 interview）；仅当代码给出高置信答案时跳过该问题。**例外**：broad intent 的边界澄清永不跳过（即使 `-y`）；phase 歧义永不跳过。resume (`-c`) → 跳过已答问题。unambiguous 单一答案输入 → 仅跳过该问题。
+- **Decision table**: `| # | Decision | Choice | Source (user / code / default) | Confidence (high / medium / LOW) |`
+  - `code` source：Search-first 派生（state.json / spec / Glob / Grep）。`code` + 非 broad → 可自动定；`code` + broad → 标 `LOW CONFIDENCE` 需用户确认；`default` source → 一律标 `LOW CONFIDENCE`。

package/workflows/issue-analyze.md

@@ -3,8 +3,6 @@
 > **DEPRECATED**: Superseded by `issue-gaps-analyze.md` which adds batch support and context.md output.
 > Use `maestro-analyze --gaps [ISS-ID]` instead.
 
-This workflow's executable steps have been removed to prevent divergent implementations.
-
 ## Migration
 
 | Old usage | New usage |
@@ -20,6 +18,3 @@ This workflow's executable steps have been removed to prevent divergent implemen
 - `issue-execute.md` — downstream execution after planning
 
 ## Notes
-
-- Issue records analyzed by the new pipeline still write to `.workflow/issues/issues.jsonl` with `analysis` field (root_cause, impact, related_files, confidence, suggested_approach, analyzed_at, analyzed_by).
-- Status is unchanged by analysis (non-destructive enrichment).

package/workflows/issue-gaps-analyze.codex.md

@@ -1,11 +1,5 @@
 # Workflow: Issue Gaps Analysis (Codex — CSV Wave)
 
-Root cause analysis for issues via `spawn_agents_on_csv` wave execution.
-Supports single issue (ISS-ID) or batch with classification and parallel analysis.
-Produces analysis records in issues.jsonl and context.md for downstream `plan --gaps`.
-
-**Invoked by**: `maestro-analyze --gaps [ISS-ID]` (codex SKILL.md)
-
 ## Pipeline
 
 ```

package/workflows/knowledge-audit.md

@@ -1,9 +1,5 @@
 # Knowledge Audit Workflow
 
-审查 spec / knowhow / artifact 三大知识存储，识别矛盾、失效、老化、孤儿，通过 keep/deprecate/delete 三态决策淘汰。
-
-与 `harvest.md` 对称：harvest 写入知识 → knowledge-audit 清理知识。与 `harvest --prune`（Stage 9）的区别：prune 做物理 GC（孤儿指针、格式损坏），audit 做语义审查（逻辑矛盾、生命周期决策）。
-
 ---
 
 ## Prerequisites

package/workflows/learn.md

@@ -1,15 +1,9 @@
 # Learn Workflow
 
-Atomic insight capture, search, and retrieval. Lightweight gstack-style "eureka moment" log that complements the retrospective workflow: where retrospective extracts insights from completed phases in bulk, `manage-learn` captures one insight at a time during active work.
-
 Storage:
 - `.workflow/specs/learnings.md` — append-only container of `<spec-entry>` sub-entries (shared with retrospective output)
 - Auto-indexed by WikiIndexer (no manual index required)
 
-**Shared store rationale:** Manual captures (`source: "manual"`), tips (`source: "tip"`), retrospective-distilled insights (`source: "retrospective"`, `lens: <name>` from `quality-retrospective`), and learn-retro insights (`source: "retro-git"` or `source: "retro-decision"` from `learn-retro`) all live in the same store so search and list see the entire knowledge corpus. The `source` field disambiguates origin.
-
-This workflow does NOT spawn sub-agents; it may invoke maestro CLI utilities (e.g. `maestro wiki search`, `maestro wiki list`) for list/search subcommands. The core capture flow is a thin file operation: parse → infer → append → confirm.
-
 ---
 
 ## Prerequisites

package/workflows/maestro.codex.md

@@ -1,9 +1,5 @@
 # Workflow: Maestro (Codex Edition)
 
-CSV wave coordinator version of the intelligent coordinator. Replaces `spawn_agent / wait / close_agent` loop with `spawn_agents_on_csv` (max_workers=1) for sequential pipeline execution. Each chain step is a CSV row with `skill_call` column; agents read prior results from session directory for context propagation.
-
-> Referenced by: `~/.codex/skills/maestro/SKILL.md`
-
 ---
 
 ## Step 1: Parse Arguments

package/workflows/maestro.md

@@ -1,8 +1,7 @@
 # Workflow: maestro
 
 Intelligent coordinator that routes user intent to optimal command chain based on project state.
-Two step types: **Skill** (in-process, synchronous) and **CLI** (via `maestro delegate`, async with role-based tool selection).
-Default `auto` mode selects type based on step complexity. All execution dispatched to unified executor (`maestro-ralph-execute`).
+Builds a `ralph_protocol_version: "1"` session: every executable step carries `skill,args,stage,scope,command_scope,command_path`; every cross-step gate is a `step.decision` node. All execution dispatched to unified executor (`maestro-ralph-execute`); the command body (`.claude/commands/maestro.md`) owns session build + dispatch. `--exec` is legacy input only — recorded to `legacy_options.exec_mode`, never changes execution. This brain is consumed for **classification only** (intent → task_type → chain); it does NOT prescribe execution semantics.
 
 **Prerequisites:**
 - None for initial invocation (can bootstrap)
@@ -110,6 +109,9 @@ Directly match user intent to the best `task_type` (maps to chain in chainMap).
 | `overlay` | Create/edit command overlays |
 | `update` | Update maestro itself |
 | `harvest` | Extract knowledge from artifacts |
+| `domain_add` | Register a domain term into glossary |
+| `domain_list` | List registered domain terms |
+| `domain_discover` | Discover domain term candidates from codebase |
 | `wiki` | Manage wiki graph |
 | `knowhow` | Manage knowhow entries |
 | `impeccable_chain` | UI design — explore, general |
@@ -127,6 +129,9 @@ Directly match user intent to the best `task_type` (maps to chain in chainMap).
 | `team_tech_debt` | Team tech debt remediation |
 | `team_lifecycle` | Team full lifecycle (plan+dev+test+review) |
 | `full-lifecycle` | Complete phase: plan→execute→review→test→audit |
+| `grill` | Stress-test a plan/idea against codebase reality (Socratic; `-y` → Auto mode code-answers, stage NOT skipped) |
+| `blueprint` | Formal spec package — 7-phase spec-generate |
+| `analyze-macro` | Broad/medium intent, no numeric phase — produces scope_verdict for ralph `post-analyze-scope` |
 | `brainstorm-driven` | Start from exploration/brainstorm |
 | `spec-driven` | From spec/requirements (heavy, with init) |
 | `roadmap-driven` | From requirements (light, with init) |
@@ -170,7 +175,7 @@ Display intent analysis: action, object, scope, issue_id, phase_ref, task_type,
 
 **Resolution order:**
 1. `state_continue` → `detectNextAction(projectState)` → `{ chain, argsOverride? }`. Apply argsOverride before template substitution.
-2. Task-type aliases → named chain: `spec_generate`→`spec-driven`, `brainstorm`→`brainstorm-driven`, `issue_execute`→`issue-full`
+2. Task-type aliases → named chain: `spec_generate`→`spec-driven`, `brainstorm`→`brainstorm-driven`, `grill`→`grill-driven`, `blueprint`→`blueprint-driven`, `analyze_macro`→`analyze-plan-execute`, `issue_execute`→`issue-full`
 3. `chainMap[taskType]` → direct lookup
 
 Full `chainMap` and `detectNextAction` are in the [Reference Data](#reference-data) section.
@@ -210,9 +215,9 @@ When executing issue chains, replace `{issue_id}` in step args with resolved ID.
 **If not `autoYes`:** Confirm with user — show numbered steps, offer: Execute / Execute from step N / Cancel.
 If user chooses "Execute from step N": set `$START_STEP = N` (used in 3f to set `current_step`).
 
-### 3e: Step-level type selection
+### 3e: Step-level command resolution (v1)
 
-Step type is selected **per step**, not per chain. Pre-compute and write to each step's `type` field in status.json (executor reads this, does not re-compute).
+> **Superseded by `ralph_protocol_version: "1"`.** The command body resolves `command_scope`/`command_path` per execution step via `maestro ralph skills --platform claude --json --quiet`; cross-step gates carry `step.decision`. Do NOT write a per-step `type` field (legacy skill/cli). `--exec` is recorded to `legacy_options.exec_mode` only — it never changes execution. FSM owns step ordering + decision evaluation (control-plane precedence, see command-body invariant 15).
 
 ```
 If execMode is 'cli' or 'internal' → force that type for all steps ("cli" or "skill").
@@ -287,7 +292,7 @@ status.json already created in Step 3g, TodoWrite initialized in Step 3h.
 Skill({ skill: "maestro-ralph-execute" })
 ```
 
-The unified executor discovers the latest running session from `.workflow/.maestro/*/status.json` and executes steps sequentially. For maestro sessions (source: "maestro"), there are no decision nodes — execution is purely sequential.
+The unified executor discovers the latest running session from `.workflow/.maestro/*/status.json` and executes steps in order. maestro sessions (source: "maestro") are `ralph_protocol_version: "1"`: execution steps load via `maestro ralph next`; any `step.decision` node hands off to `Skill("maestro-ralph")` for evaluation (same mechanism as ralph sessions). Decision nodes ARE supported in maestro sessions.
 
 ---
 
@@ -300,6 +305,9 @@ const chainMap = {
   // ── Single-step ──
   'status':             [{ cmd: 'manage-status' }],
   'init':               [{ cmd: 'maestro-init' }],
+  'grill':              [{ cmd: 'maestro-grill', args: '"{description}"' }],
+  'blueprint':          [{ cmd: 'maestro-blueprint', args: '"{description}"' }],
+  'analyze-macro':      [{ cmd: 'maestro-analyze', args: '"{description}"' }],
   'analyze':            [{ cmd: 'maestro-analyze', args: '{phase}' }],
   'analyze-quick':      [{ cmd: 'maestro-analyze', args: '{phase} -q' }],
   'ui_design':          [{ cmd: 'maestro-impeccable', args: '"{description}" --chain build' }],
@@ -327,6 +335,9 @@ const chainMap = {
   'spec_add':           [{ cmd: 'spec-add', args: '"{description}"' }],
   'spec_load':          [{ cmd: 'spec-load' }],
   'spec_map':           [{ cmd: 'manage-codebase-rebuild' }],
+  'domain_add':         [{ cmd: 'domain-add', args: '"{description}"' }],
+  'domain_list':        [{ cmd: 'domain-list' }],
+  'domain_discover':    [{ cmd: 'domain-discover' }],
   'knowhow_capture':     [{ cmd: 'manage-knowhow-capture', args: '"{description}"' }],
   'issue':              [{ cmd: 'manage-issue', args: '"{description}"' }],
   'issue_discover':     [{ cmd: 'manage-issue-discover', args: '"{description}"' }],
@@ -349,20 +360,22 @@ const chainMap = {
   'team_tech_debt':     [{ cmd: 'team-tech-debt', args: '"{description}"' }],
 
   // ── Multi-step chains ──
-  'full-lifecycle':       [{ cmd: 'maestro-plan', args: '{phase}' }, { cmd: 'maestro-execute', args: '{phase}' }, { cmd: 'quality-review', args: '{phase}' }, { cmd: 'quality-test', args: '{phase}' }, { cmd: 'maestro-milestone-audit' }],
-  'spec-driven':          [{ cmd: 'maestro-init' }, { cmd: 'maestro-roadmap', args: '--mode full "{description}"' }, { cmd: 'maestro-plan', args: '{phase}' }, { cmd: 'maestro-execute', args: '{phase}' }],
-  'roadmap-driven':       [{ cmd: 'maestro-init' }, { cmd: 'maestro-roadmap', args: '"{description}"' }, { cmd: 'maestro-plan', args: '{phase}' }, { cmd: 'maestro-execute', args: '{phase}' }],
-  'brainstorm-driven':    [{ cmd: 'maestro-brainstorm', args: '"{description}"' }, { cmd: 'maestro-plan', args: '{phase}' }, { cmd: 'maestro-execute', args: '{phase}' }],
+  'full-lifecycle':       [{ cmd: 'maestro-plan', args: '{phase}' }, { cmd: 'maestro-execute', args: '{phase}' }, { cmd: 'quality-review', args: '{phase}' }, { cmd: 'quality-test', args: '{phase}' }, { cmd: 'maestro-milestone-audit' }, { cmd: 'manage-harvest', args: '--auto' }],
+  'spec-driven':          [{ cmd: 'maestro-init' }, { cmd: 'maestro-roadmap', args: '--mode full "{description}"' }, { cmd: 'maestro-plan', args: '{phase}' }, { cmd: 'maestro-execute', args: '{phase}' }, { cmd: 'manage-harvest', args: '--auto' }],
+  'roadmap-driven':       [{ cmd: 'maestro-init' }, { cmd: 'maestro-roadmap', args: '"{description}"' }, { cmd: 'maestro-plan', args: '{phase}' }, { cmd: 'maestro-execute', args: '{phase}' }, { cmd: 'manage-harvest', args: '--auto' }],
+  'grill-driven':         [{ cmd: 'maestro-grill', args: '"{description}"' }, { cmd: 'maestro-brainstorm', args: '"{description}" --from grill:{grill_id}' }, { cmd: 'maestro-plan', args: '{phase}' }, { cmd: 'maestro-execute', args: '{phase}' }, { cmd: 'manage-harvest', args: '--auto' }],
+  'blueprint-driven':     [{ cmd: 'maestro-init' }, { cmd: 'maestro-blueprint', args: '"{description}"' }, { cmd: 'maestro-plan', args: '{phase}' }, { cmd: 'maestro-execute', args: '{phase}' }, { cmd: 'manage-harvest', args: '--auto' }],
+  'brainstorm-driven':    [{ cmd: 'maestro-brainstorm', args: '"{description}"' }, { cmd: 'maestro-plan', args: '{phase}' }, { cmd: 'maestro-execute', args: '{phase}' }, { cmd: 'manage-harvest', args: '--auto' }],
   'brainstorm_visualize': [{ cmd: 'brainstorm-visualize', args: '"{description}"' }],
   'impeccable-build':       [{ cmd: 'maestro-impeccable', args: '"{description}" --chain build' }, { cmd: 'maestro-plan', args: '{phase}' }, { cmd: 'maestro-execute', args: '{phase}' }],
   'impeccable-driven':      [{ cmd: 'maestro-impeccable', args: '"{description}" --chain build' }, { cmd: 'maestro-execute', args: '{phase}' }],
-  'analyze-plan-execute': [{ cmd: 'maestro-analyze', args: '"{description}" -q' }, { cmd: 'maestro-plan', args: '--dir {scratch_dir}' }, { cmd: 'maestro-execute', args: '--dir {scratch_dir}' }],
+  'analyze-plan-execute': [{ cmd: 'maestro-analyze', args: '"{description}" -q' }, { cmd: 'maestro-plan', args: '--dir {scratch_dir}' }, { cmd: 'maestro-execute', args: '--dir {scratch_dir}' }, { cmd: 'manage-harvest', args: '--auto' }],
   'quality-loop':         [{ cmd: 'quality-review', args: '{phase}' }, { cmd: 'quality-auto-test', args: '{phase}' }, { cmd: 'quality-test', args: '{phase}' }, { cmd: 'quality-debug', args: '--from-uat {phase}' }, { cmd: 'maestro-plan', args: '{phase} --gaps' }, { cmd: 'maestro-execute', args: '{phase}' }],
   'milestone-close':      [{ cmd: 'maestro-milestone-audit' }, { cmd: 'maestro-milestone-complete' }],
   'next-milestone':       [{ cmd: 'maestro-roadmap', args: '"{description}"' }, { cmd: 'maestro-plan', args: '{phase}' }, { cmd: 'maestro-execute', args: '{phase}' }],
   'review-fix':           [{ cmd: 'maestro-plan', args: '{phase} --gaps' }, { cmd: 'maestro-execute', args: '{phase}' }, { cmd: 'quality-review', args: '{phase}' }],
   'quality-loop-partial': [{ cmd: 'maestro-plan', args: '{phase} --gaps' }, { cmd: 'maestro-execute', args: '{phase}' }],
-  'issue-full':           [{ cmd: 'maestro-analyze', args: '--gaps {issue_id}' }, { cmd: 'maestro-plan', args: '--gaps' }, { cmd: 'maestro-execute', args: '' }, { cmd: 'quality-review', args: '{phase}' }, { cmd: 'manage-issue', args: 'close {issue_id} --resolution fixed' }],
+  'issue-full':           [{ cmd: 'maestro-analyze', args: '--gaps {issue_id}' }, { cmd: 'maestro-plan', args: '--gaps' }, { cmd: 'maestro-execute', args: '' }, { cmd: 'quality-review', args: '{phase}' }, { cmd: 'manage-issue', args: 'close {issue_id} --resolution fixed' }, { cmd: 'manage-harvest', args: '--auto' }],
   'issue-quick':          [{ cmd: 'maestro-plan', args: '--gaps' }, { cmd: 'maestro-execute', args: '' }, { cmd: 'manage-issue', args: 'close {issue_id} --resolution fixed' }],
   'milestone-release':    [{ cmd: 'maestro-milestone-audit' }, { cmd: 'maestro-milestone-release' }],
 
@@ -417,19 +430,19 @@ detectNextAction(state):
 
 | Chain | Steps | Use Case |
 |-------|-------|----------|
-| `full-lifecycle` | plan → execute → review → test → audit | Full milestone completion |
-| `blueprint-driven` | init → blueprint → plan → execute | From idea/requirements (heavy) |
-| `roadmap-driven` | init → roadmap → plan → execute | From requirements (light) |
-| `brainstorm-driven` | brainstorm → plan → execute | From exploration |
+| `full-lifecycle` | plan → execute → review → test → audit → harvest | Full milestone completion |
+| `blueprint-driven` | init → blueprint → plan → execute → harvest | From idea/requirements (heavy) |
+| `roadmap-driven` | init → roadmap → plan → execute → harvest | From requirements (light) |
+| `brainstorm-driven` | brainstorm → plan → execute → harvest | From exploration |
 | `impeccable-build` | impeccable --chain build → plan → execute | From design system generation |
-| `analyze-plan-execute` | analyze -q → plan --dir → execute --dir | Fast track (scratch mode) |
+| `analyze-plan-execute` | analyze -q → plan --dir → execute --dir → harvest | Fast track (scratch mode) |
 | `review-fix` | plan --gaps → execute → review | Fix review-blocked issues |
 | `quality-loop` | review → test-gen → test → debug → plan --gaps → execute | Fix quality issues |
 | `quality-loop-partial` | plan --gaps → execute | Partial quality fix cycle |
 | `milestone-close` | audit → complete | Close a milestone |
 | `milestone-release` | audit → release | Release with version tag |
 | `next-milestone` | roadmap → plan → execute | Next milestone (auto-loads deferred) |
-| `issue-full` | analyze → plan → execute → review → close | Issue with quality gate |
+| `issue-full` | analyze → plan → execute → review → close → harvest | Issue with quality gate |
 | `issue-quick` | plan → execute → close | Issue fast path |
 
 ### Pipeline Examples

package/workflows/merge.md

@@ -1,9 +1,5 @@
 # Workflow: merge
 
-Two-phase merge of a completed milestone worktree branch back into main. Phase 1: git merge (source code). Phase 2: artifact sync (workflow state). Artifact sync only proceeds after successful git merge.
-
-Merges operate at the **milestone level** — one worktree per milestone, all phases merged together.
-
 ---
 
 ## Step 1: Parse Arguments and Flags

package/workflows/milestone-complete.md

@@ -1,7 +1,5 @@
 # Workflow: milestone-complete
 
-Archive completed milestone, move artifacts to history, and prepare for next.
-
 ---
 
 ## Step 1: Validation
@@ -167,5 +165,3 @@ Next steps:
   /maestro-analyze              -- Start next milestone (standard only)
   /manage-status                -- View project state
 ```
-
-**Adhoc milestone note:** When completing an adhoc milestone, the "Next steps" section omits "Start next milestone" since adhoc milestones have no successor in a roadmap chain.

package/workflows/overlays.md

@@ -1,7 +1,5 @@
 # Command Overlays — Format & Contract
 
-Overlays are non-invasive patches for `.claude/commands/*.md` files. They let users and operators inject additional steps, reading requirements, or gating rules into any slash command without editing the pristine source files shipped by the `maestro` package. Every `maestro install` run reapplies them automatically.
-
 ## File format
 
 Each overlay is a JSON file at `~/.maestro/overlays/<name>.json`:
@@ -83,10 +81,6 @@ On apply, each patch's `content` is wrapped in hashed markers:
 2. Restore `.md.disabled` state from the prior install
 3. **Apply overlays** — reads `~/.maestro/overlays/*.json`, applies each enabled one to the just-installed commands, writes `~/.maestro/manifests/overlays-<scope>.json`
 
-Because step 1 always overwrites commands with pristine content, the apply in step 3 is always clean — no drift, no stacking across reinstalls.
-
-Users can also run `maestro overlay apply` standalone between installs — it's idempotent and safe to call any number of times.
-
 ## CLI reference
 
 ```bash
@@ -96,10 +90,6 @@ maestro overlay add <file.json>             # validate, install, apply
 maestro overlay remove <name>               # strip markers, delete overlay file
 ```
 
-## Authoring via the `/maestro-overlay` skill
-
-Users rarely write overlay JSON by hand. The `/maestro-overlay` skill takes natural-language intent, reads the pristine target command to find the right section, drafts the overlay JSON, and runs `maestro overlay add` for you. See `.claude/commands/maestro-overlay.md`.
-
 ## Edge cases
 
 - **Disabled targets** (`.md.disabled`) are skipped silently.

package/workflows/plan.md

@@ -76,8 +76,6 @@ When plan resolves to `scope == "standalone"` AND `state.json.current_milestone
 5. Use this milestone ID for artifact registration (P5 Step 4)
 ```
 
-This ensures downstream commands (verify, milestone-audit, milestone-complete) have a valid milestone context without requiring roadmap.
-
 **Backward compatibility:** If `state.json.milestones[]` already has entries with `current_milestone != null`, skip creation (existing milestone takes precedence). Missing `type` field on legacy milestones defaults to `"standard"`.
 
 ---
@@ -261,6 +259,7 @@ Output: `plan.json` (summary, approach, task_ids[], task_count, complexity, wave
 - Group simple unrelated changes into a batch task to minimize agent spawns
 - depends_on only for genuine output dependencies; most tasks should be parallel
 - Each task must be substantial (15-60 min); sub-5-min changes must be merged
+- **Vertical slice for UI**: a user-facing feature is ONE end-to-end task/wave (backend endpoint + frontend wiring + integration); never split into backend-only/frontend-only. Each UI delivery wave needs ≥1 task carrying a `[UI-observable]` convergence criterion (verifiable user flow; runtime-checked by ralph frontend-verify gate)
 
 ### Deep Work Rules (MANDATORY for all modes)
 
@@ -322,7 +321,7 @@ Bidirectional linking (main flow, post-planner): update matching issues in `.wor
 
 1. **Spawn workflow-plan-checker agent**
    - Input: plan.json + all .task/TASK-*.json + index.json (success_criteria)
-   - Check dimensions: requirements coverage, feasibility, dependency correctness (no circular deps), convergence criteria quality (grep-verifiable, no subjective language), read_first completeness, action concreteness (no vague references), wave structure (no conflicting files), completeness (no orphan tasks)
+   - Check dimensions: requirements coverage, feasibility, dependency correctness (no circular deps), convergence criteria quality (grep-verifiable, no subjective language), read_first completeness, action concreteness (no vague references), wave structure (no conflicting files), completeness (no orphan tasks), UI-observable coverage (when plan touches UI: each delivery wave has ≥1 `[UI-observable]` criterion)
 
 2. **Revision loop** (max 3 rounds)
    - Critical issues → re-spawn planner with issues, revise, re-check

package/workflows/roadmap-common.md

@@ -1,7 +1,5 @@
 # Workflow: Roadmap Common
 
-Shared logic for roadmap generation — used by roadmap.md.
-
 ---
 
 ## Worktree Guard
@@ -18,8 +16,6 @@ Block if `.workflow/worktree-scope.json` exists — must run from main worktree.
 specs_content = maestro spec load --category arch
 ```
 
-Ensure phases respect architectural constraints.
-
 ### Load Project History (if `.workflow/` exists)
 
 Read project artifacts to understand what has already been built:

package/workflows/tdd.md

@@ -1,7 +1,5 @@
 # TDD Workflow
 
-Test-Driven Development discipline for plan generation and execution. Invoked when `maestro-plan --tdd` is used. Transforms feature requirements into RED-GREEN-REFACTOR task chains that `maestro-execute` can consume.
-
 ---
 
 ## Iron Law

package/workflows/tools-spec.md

@@ -1,14 +1,8 @@
 # Tool Spec Reference
 
-<reference>
-Tool specs are a **subtype of knowhow** (`tool: true` frontmatter on knowhow documents). For the full knowhow data model, lifecycle, and management commands, see `knowhow.md`. This file documents only the tool-specific subset.
-</reference>
-
-Shared reference for tool spec registration and execution commands.
-
 ## Storage
 
-Tool specs are stored as knowhow documents in `.workflow/knowhow/` with `tool: true` in YAML frontmatter. Tool registration creates new knowhow files or promotes existing ones (via frontmatter update). The `category` field determines which `spec load --category` queries match this tool.
+Path: `.workflow/knowhow/` with `tool: true` in YAML frontmatter.
 
 ## Entry Format
 

package/workflows/ui-codify-extract.md

@@ -1,7 +1,5 @@
 # UI Codify: Phase 2 — Parallel Agent Extraction
 
-从源代码文件中提取设计系统 token，通过 3 个并行 Agent 分析。
-
 ## Overview
 
 - 3 个 Agent 并行运行：Style、Animation、Layout

package/workflows/ui-codify-package.md

@@ -1,7 +1,5 @@
 # UI Codify: Phase 3 — Reference Package Generation
 
-将提取结果转换为可分享的参考包，包含交互式预览页面。
-
 ## Prerequisites
 
 来自前序 Phase 的变量：