maestro-flow-one 0.2.25 → 0.2.27

package/maestro-flow/commands/lifecycle/init.md

@@ -13,28 +13,56 @@ allowed-tools:
 ---
 <purpose>
 Initialize a new project through auto state detection and unified flow. Invoked when starting a fresh project or onboarding an existing codebase into workflow management. Produces the `.workflow/` directory structure with project.md, state.json, config.json, and specs. Does NOT create roadmap — use maestro-roadmap (light mode, default) or maestro-roadmap --mode full (spec package) as the next step.
+
+Pipeline position: entry point (no upstream). Downstream: `maestro-roadmap` or `maestro-brainstorm`.
 </purpose>
 
 <required_reading>
 @~/.maestro/workflows/init.md
-@~/.maestro/templates/project.md
-@~/.maestro/templates/state.json
-@~/.maestro/templates/config.json
 </required_reading>
 
+<deferred_reading>
+- [project.md](~/.maestro/templates/project.md) — read when generating project description
+- [state.json](~/.maestro/templates/state.json) — read when creating initial state
+- [config.json](~/.maestro/templates/config.json) — read when creating workflow configuration
+</deferred_reading>
+
 <context>
+$ARGUMENTS — none for interactive mode, or `-y` with `@file` reference for auto mode.
+
 **Flags:**
-- `-y` -- Automatic mode. After config questions, runs research without further interaction. Expects idea document via @ reference.
-- `--from <source>` -- Load upstream context package (brainstorm:ID, @file, or path). Consumes context-package.json to pre-fill project vision, goals, constraints, and terminology. Skips interactive questioning. Alias: `--from-brainstorm`
+
+| Flag | Effect | Default |
+|------|--------|---------|
+| `-y` / `--yes` | Automatic mode. After config questions, runs research without further interaction. Expects idea document via @ reference. | `false` |
+| `--from <source>` | Load upstream context package (brainstorm:ID, @file, or path). Consumes context-package.json to pre-fill project vision, goals, constraints, and terminology. Skips interactive questioning. Alias: `--from-brainstorm` | — |
 
 **Load project state if exists:**
 Check for `.workflow/state.json` -- loads context if project already initialized.
 </context>
 
+<interview_protocol>
+Follows @~/.maestro/workflows/interview-mechanics.md standard.
+
+**Interaction mode**: convergent menu-driven
+**Decision tree** (strict order): project type (greenfield / existing codebase onboarding) → tech stack detection and confirmation → directory structure preferences → initial configuration (specs categories, wiki bootstrap)
+**Scope guard**: only init decisions; do not prejudge roadmap structure or plan scope
+**Writeback target**: project.md (project description) + config.json (settings) + state.json (initial state)
+**Additional skip conditions**: --from source (upstream context pre-fills decisions)
+**Exit condition**: all configuration questions settled → proceed to workflow execution
+</interview_protocol>
+
 <execution>
+### Pre-flight
+
+1. Check if `.workflow/` already exists — if so, load state and warn (E002 for greenfield conflicts)
+2. Validate `--from` source is accessible if provided
+
 Follow '~/.maestro/workflows/init.md' completely.
+</execution>
 
-**Report format on completion:**
+<completion>
+### Standalone report
 
 ```
 === WORKFLOW INITIALIZED ===
@@ -46,17 +74,31 @@ Created:
   .workflow/state.json
   .workflow/config.json
   .workflow/specs/
+```
 
-Next steps (choose one path to create roadmap):
-  /maestro-roadmap <requirement>                               -- Direct interactive roadmap (light, default)
-  /maestro-roadmap --mode full <idea>                          -- Full spec package + roadmap (heavy)
+### Ralph-invoked completion
 
-Other commands:
-  /manage-status                                               -- View project dashboard
-  /maestro-brainstorm <topic>                                  -- Explore ideas first
-  /maestro-quick <task>                                        -- Quick ad-hoc task
+End the step by calling the CLI (no text block output):
 ```
-</execution>
+maestro ralph complete <idx> --status {STATUS} [--evidence {path}]
+```
+
+Status verdicts:
+- **DONE** — Normal completion
+- **DONE_WITH_CONCERNS** — Completed with caveats; pass `--concerns`
+- **NEEDS_RETRY** — Tooling error / transient issue; ralph will retry
+- **BLOCKED** — External hard blocker; pass `--reason`
+
+### Next-step routing
+
+| Condition | Suggestion |
+|-----------|-----------|
+| Roadmap needed (default light) | `/maestro-roadmap <requirement>` |
+| Full spec package + roadmap | `/maestro-roadmap --mode full <idea>` |
+| Explore ideas first | `/maestro-brainstorm <topic>` |
+| View project dashboard | `/manage-status` |
+| Quick ad-hoc task | `/maestro-quick <task>` |
+</completion>
 
 <error_codes>
 | Code | Severity | Condition | Recovery |
@@ -68,11 +110,11 @@ Other commands:
 </error_codes>
 
 <success_criteria>
-- [ ] Deep questioning completed (threads followed, not rushed) — or extracted from document/brainstorm
 - [ ] `.workflow/project.md` created with Core Value, Requirements (Validated/Active/Out of Scope), Key Decisions
 - [ ] `.workflow/state.json` created with artifacts[] array, initialized to idle state
 - [ ] `.workflow/config.json` created with workflow / execution / git / gates / codebase / guard / collab / specInjection / dashboard segments
 - [ ] `.workflow/specs/` initialized with convention files
-- [ ] Research completed (if enabled) — 4 parallel agents spawned
-- [ ] User knows next step is `/maestro-roadmap` (light) or `/maestro-roadmap --mode full` (spec package)
+- [ ] All interview decisions written to project.md / config.json before proceeding
+- [ ] Research completed (if enabled) — parallel agents spawned with results merged
+- [ ] Next-step routing displayed in completion report
 </success_criteria>

package/maestro-flow/commands/lifecycle/plan.md

@@ -120,7 +120,13 @@ For each created TASK-{NNN}.json that has issue_id:
 
 This ensures issue → TASK traceability. The `task_refs[]` and `task_plan_dir` fields on the issue allow the dashboard to resolve and display associated TASK details.
 
-**Report format on completion:**
+### Mode: Revise / Check
+
+Follow workflow plan.md § "Revise Mode" and § "Check Mode" respectively. These modes bypass the standard P1-P5 create pipeline.
+</execution>
+
+<completion>
+### Standalone report
 
 ```
 === PLAN READY ===
@@ -131,20 +137,16 @@ Collision: {collision_status}
 
 Plan: scratch/{YYYYMMDD}-plan-P{N}-{slug}/plan.json
 Tasks: scratch/{YYYYMMDD}-plan-P{N}-{slug}/.task/TASK-*.json
-
-Next steps:
-  /maestro-execute              -- Execute the plan
-  /maestro-execute --dir {dir}  -- Execute specific plan
-  /maestro-plan {phase}         -- Re-plan with modifications
 ```
 
-**Completion (when invoked from ralph):**
-End the step by calling the CLI (no `--- COMPLETION STATUS ---` text block):
+### Ralph-invoked completion
+
+End the step by calling the CLI (no text block output):
 ```
-maestro ralph complete <idx> --status DONE [--evidence scratch/{YYYYMMDD}-plan-P{N}-{slug}/plan.json]
+maestro ralph complete <idx> --status {STATUS} [--evidence scratch/{YYYYMMDD}-plan-P{N}-{slug}/plan.json]
 ```
 
-STATUS verdicts (CLI-enforced enum):
+Status verdicts:
 - **DONE** — Plan created/revised and confirmed → next step picks up automatically
 - **DONE_WITH_CONCERNS** — Plan produced but with explicit caveats; pass `--concerns "..."`
 - **NEEDS_RETRY** — Plan failed (tooling error, transient issue); ralph will retry
@@ -152,10 +154,14 @@ STATUS verdicts (CLI-enforced enum):
 
 > Ambiguous requirements are NOT a completion status — resolve them in-place via `AskUserQuestion` during planning (≤3 rounds), then proceed to DONE. `NEEDS_CONTEXT` has been removed; context shortage is handled by the harness's automatic compaction.
 
-### Mode: Revise / Check
+### Next-step routing
 
-Follow workflow plan.md § "Revise Mode" and § "Check Mode" respectively. These modes bypass the standard P1-P5 create pipeline.
-</execution>
+| Condition | Suggestion |
+|-----------|-----------|
+| Plan confirmed for execution | `/maestro-execute` |
+| Plan confirmed, specific directory | `/maestro-execute --dir {dir}` |
+| Re-plan with modifications | `/maestro-plan {phase}` |
+</completion>
 
 <error_codes>
 | Code | Severity | Condition | Recovery |

package/maestro-flow/commands/lifecycle/roadmap.md

@@ -36,13 +36,16 @@ For formal specification documents (Product Brief, PRD, Architecture, Epics), us
 $ARGUMENTS -- requirement text, @file reference, or upstream context source.
 
 **Flags:**
-- `-y` / `--yes`: Auto mode — skip interactive questions, use recommended defaults
-- `-c` / `--continue`: Resume from last checkpoint
-- `-m progressive|direct|auto`: Decomposition strategy (default: auto)
-- `--from <source>`: Load upstream context package (brainstorm:ID, blueprint:BLP-xxx, analyze:ANL-xxx, @file, or path). Consumes context-package.json
-- `--from-brainstorm SESSION-ID`: (backward compat alias for `--from brainstorm:ID`)
-- `--revise [instructions]`: Revise existing roadmap. If instructions provided, apply directly. If omitted, ask user. Preserves completed phase progress.
-- `--review`: Roadmap health assessment (read-only)
+
+| Flag | Effect | Default |
+|------|--------|---------|
+| `-y` / `--yes` | Auto mode — skip interactive questions, use recommended defaults | false |
+| `-c` / `--continue` | Resume from last checkpoint | false |
+| `-m progressive\|direct\|auto` | Decomposition strategy | auto |
+| `--from <source>` | Load upstream context package (brainstorm:ID, blueprint:BLP-xxx, analyze:ANL-xxx, @file, or path). Consumes context-package.json | — |
+| `--from-brainstorm SESSION-ID` | Backward compat alias for `--from brainstorm:ID` | — |
+| `--revise [instructions]` | Revise existing roadmap. If instructions provided, apply directly. If omitted, ask user. Preserves completed phase progress. | — |
+| `--review` | Roadmap health assessment (read-only) | — |
 
 **Input types:**
 - Direct text: `"Implement user authentication system with OAuth and 2FA"`
@@ -61,24 +64,22 @@ maestro-roadmap → .workflow/roadmap.md (Milestone > Phase hierarchy)
 maestro-analyze {phase} → maestro-plan → maestro-execute → maestro-verify
 ```
 
-### Pre-load specs
-1. **Architecture specs**: Run `maestro spec load --category arch` to load architecture constraints. Use as context for phase decomposition — ensures roadmap respects documented decisions and boundaries.
-2. Optional — proceed without if unavailable.
+### Pre-load
+
+1. **Specs**: `maestro spec load --category arch` — load architecture constraints for phase decomposition
+2. **Wiki search**: `maestro wiki search "{requirement keywords}" --json` → prior knowledge
+3. All optional — proceed without if unavailable
 </context>
 
 <interview_protocol>
-Interview the user relentlessly until shared understanding is reached. Active only in interactive mode; skip when `-y/--yes`, `--revise`, `--review`, `-c/--continue`, or input is already specific (clear requirement + mode).
-
-- 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 or via `Other` at any time.
-- Search-first when uncertain: before asking, resolve via `state.json`, existing `roadmap.md`, `project.md`, `maestro spec load`, `maestro wiki search`, Glob/Grep/Read, or — for open-ended multi-file scans — spawn `Agent(subagent_type: Explore)` / `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 the `Roadmap Decisions` section at the top of `.workflow/roadmap.md` (create the section if absent). Do NOT batch writeback to the end — partial decisions must already be on disk before the next question.
-- Walk the decision dependency tree strictly: mode → requirement scope → decomposition strategy → phase dependencies/order. Do not open the next branch until the current one is settled.
-- Scope guard: only decide the shape of the roadmap. Do not pre-resolve intra-phase task breakdown — that belongs to `plan`.
-
-Decision points: scope (MVP / complete / phased) → strategy (progressive / direct / auto) → milestone boundaries → phase dependencies and order.
-
-Exit: on consensus or explicit user signal to proceed, finalize the `Roadmap Decisions` section (rows already populated incrementally). Schema:
-`| # | Decision | Choice | Source (user / code / default) |`
+Follows @~/.maestro/workflows/interview-mechanics.md standard.
+
+**Interaction mode**: convergent menu-driven
+**Decision tree** (strict order): mode (create / revise / review) → requirement scope (MVP / complete / phased) → decomposition strategy (progressive / direct / auto) → milestone boundaries → phase dependencies and order
+**Scope guard**: only roadmap shape; do not pre-resolve intra-phase task breakdown (belongs to plan)
+**Writeback target**: .workflow/roadmap.md "Roadmap Decisions" section (create if absent)
+**Additional skip conditions**: --revise, --review (skip to respective mode)
+**Exit condition**: on consensus or explicit user signal → finalize Roadmap Decisions section
 </interview_protocol>
 
 <execution>
@@ -91,16 +92,45 @@ Sub-modes:
 - **Revise** (`--revise`): Follow workflow roadmap.md "Mode: Revise" section
 - **Review** (`--review`): Follow workflow roadmap.md "Mode: Review" section
 
-### Next-step routing on completion
+</execution>
+
+<completion>
+### Standalone report
+
+```
+=== ROADMAP READY ===
+Milestones: {count}
+Phases: {total_phases}
+Strategy: {progressive|direct|auto}
+Output: .workflow/roadmap.md
+--- COMPLETION STATUS ---
+Status: {DONE|DONE_WITH_CONCERNS}
+Concerns: {if any}
+```
+
+### Ralph-invoked completion
+
+End the step by calling the CLI (no text block output):
+```
+maestro ralph complete <idx> --status {STATUS} [--evidence {path}]
+```
+
+Status verdicts:
+- **DONE** — Normal completion
+- **DONE_WITH_CONCERNS** — Completed with caveats; pass `--concerns`
+- **NEEDS_RETRY** — Tooling error / transient issue; ralph will retry
+- **BLOCKED** — External hard blocker; pass `--reason`
+
+### Next-step routing
 
 | Condition | Suggestion |
 |-----------|-----------|
-| Roadmap approved, need analysis | /maestro-analyze 1 |
-| Simple project, ready to plan | /maestro-plan 1 |
-| Need UI design first | /maestro-impeccable build |
-| View project dashboard | /manage-status |
-| Need formal spec documents | /maestro-blueprint |
-</execution>
+| Roadmap approved, need analysis | `/maestro-analyze 1` |
+| Simple project, ready to plan | `/maestro-plan 1` |
+| Need UI design first | `/maestro-impeccable build` |
+| View project dashboard | `/manage-status` |
+| Need formal spec documents | `/maestro-blueprint` |
+</completion>
 
 <error_codes>
 | Code | Severity | Condition | Recovery |

package/maestro-flow/commands/lifecycle/swarm-workflow.md

@@ -21,16 +21,16 @@ swarm-workflow provides parallel compute bursts within individual steps.
 
 Scripts: `~/.maestro/workflows/swarm/wf-*.js`
 
-| Script | Accelerates | Pattern |
-|--------|-------------|---------|
-| `wf-analyze` | maestro-analyze | cli-explore-agent → 6-dimension parallel scoring → synthesis |
-| `wf-brainstorm` | maestro-brainstorm | multi-role parallel analysis → cross-role-reviewer → guidance |
-| `wf-review` | quality-review | 6-dimension workflow-reviewer → adversarial verify → report |
-| `wf-verify` | maestro-verify | 3-layer workflow-verifier + convergence + antipattern → aggregate |
-| `wf-grill` | maestro-grill | cli-explore-agent → parallel branch stress-testing → contradiction synthesis |
-| `wf-plan` | maestro-plan | parallel context exploration → workflow-planner → plan-checker |
-| `wf-execute` | maestro-execute | wave-based parallel workflow-executor (worktree isolation) |
-| `wf-milestone-audit` | maestro-milestone-audit | parallel coverage + execution + integration-checker |
+| Script | Accelerates | Adversarial Pattern |
+|--------|-------------|---------------------|
+| `wf-analyze` | maestro-analyze | explore → 6-dim scoring → **skeptic cross-verify** → **3-way advocacy (go/no-go/conditional) + referee** |
+| `wf-brainstorm` | maestro-brainstorm | multi-role analysis → **3-specialist cross-review** → **3-proposal competition** → **arbitrator** |
+| `wf-review` | quality-review | 6-dim scan → **3-vote adversarial verify (prosecutor/defense/judge)** → **3-perspective report + arbitrated verdict** |
+| `wf-verify` | maestro-verify | 3-layer + antipattern + convergence → **prosecutor vs defender debate** → **judge verdict** |
+| `wf-grill` | maestro-grill | explore → parallel branch stress → **meta-skeptic challenge** → **3-vote verdict (optimist/pessimist/realist)** |
+| `wf-plan` | maestro-plan | parallel context → **3-strategy competing proposals** → **judge panel scoring** → **3-critic adversarial check** |
+| `wf-execute` | maestro-execute | wave-based parallel execution → **adversarial convergence spot-check** → **3-vote status determination** |
+| `wf-milestone-audit` | maestro-milestone-audit | parallel 3-dim audit → **adversarial dimension challenge** → **3-vote verdict (strict/lenient/objective)** |
 
 Integration modes:
 - **Standalone**: `/maestro-swarm-workflow "analyze auth module"` — direct invocation
@@ -175,11 +175,15 @@ Intent-to-script routing（按关键词匹配，--script 优先级最高）：
 
 Workflow 返回 JSON 后：
 
-1. **摘要输出**：按脚本类型格式化关键指标
-   - analyze: overall_score, scope_verdict, go_no_go, critical findings count
-   - brainstorm: role count, conflict/synergy count, top guidance items
-   - review: verdict (APPROVE/REQUEST_CHANGES/BLOCK), confirmed vs false-positive count
-   - verify: overall_passed, confidence, gap count, antipattern blocker count
+1. **摘要输出**：按脚本类型格式化关键指标（含对抗决策结果）
+   - analyze: overall_score, scope_verdict, adversarial_outcome (go/no-go/conditional advocacy + referee), scores_challenged count
+   - brainstorm: role count, conflict/synergy count, 3-proposal competition result, arbitration notes
+   - review: verdict (APPROVE/REQUEST_CHANGES/BLOCK), 3-vote tally, confirmed vs false-positive count, adversarial_verdict
+   - verify: overall_status, prosecutor vs defender confidence, adversarial_outcome, gap count
+   - grill: overall_verdict, meta-skeptic quality rating, 3-vote verdict tally, overblown findings count
+   - plan: selected_strategy (breadth/depth/risk), judge panel scores, 3-critic adversarial check verdict
+   - execute: 3-vote status (DONE/DONE_WITH_CONCERNS/NEEDS_RETRY), convergence trust %, discrepancy count
+   - milestone-audit: 3-vote verdict, dimensions_overturned count, next_step
 
 2. **Artifact 写入**（可选）：
    - 若当前在 ralph session 中（检测 `.workflow/.maestro/ralph-*/status.json` 状态为 running）：
@@ -187,10 +191,14 @@ Workflow 返回 JSON 后：
    - 否则写入 `.workflow/scratch/{YYYYMMDD}-swarm-{script}-{slug}/results.json`
 
 3. **Ralph 兼容产出**：
-   - analyze → `analysis.md` + `context.md`（decisions）+ `conclusions.json`
-   - brainstorm → `guidance-specification.md`
-   - review → `review.json`
-   - verify → `verification.json`
+   - analyze → `analysis.md` + `context.md`（decisions）+ `conclusions.json` + `adversarial-debate.json`
+   - brainstorm → `guidance-specification.md` + `proposals-competition.json`
+   - review → `review.json`（含 adversarial_verdict + 3-vote tally）
+   - verify → `verification.json`（含 adversarial_outcome: prosecutor/defender debate）
+   - grill → `grill-results.json`（含 meta-challenge + 3-vote verdict）
+   - plan → `plan.json`（含 competition scores + critic feedback）
+   - execute → `execution-report.json`（含 convergence_checks + 3-vote status）
+   - milestone-audit → `audit-report.json`（含 dimension challenges + 3-vote verdict）
 
 4. **RunId 提示**：显示 `Resume: /maestro-swarm-workflow --resume {runId}` 用于增量重跑