maestro-collab

Each CLI tool independently analyzes the requirement via maestro delegate shell call. Coordinator waits for ALL CLI results to completion via shell-exec-protocol.md, then cross-verifies for consensus/conflicts and synthesizes into unified report.

NO spawn_agents_on_csv. NO spawn_agent. ALL CLI calls directly by coordinator via shell_exec.

Flags:

--tools <list>: Comma-separated CLI tools (default: first 3 enabled)
--mode analysis|write: Delegate mode (default: analysis)
--rule <template>: Shared rule template for all delegates (see Rule Reference below)
-y: Skip confirmations

Rule Reference — common --rule values for collab scenarios:

Scenario	Rule	Description
Code quality review	`analysis-review-code-quality`	Multi-dimensional Code Quality Review
Architecture review	`analysis-review-architecture`	Architecture Design Review
Bug root cause	`analysis-diagnose-bug-root-cause`	Bug Root Cause Diagnosis
Security assessment	`analysis-assess-security-risks`	Security Risk Assessment
Performance analysis	`analysis-analyze-performance`	Performance Bottleneck Analysis
Code pattern analysis	`analysis-analyze-code-patterns`	Code Pattern/Anti-pattern Identification
Architecture design	`planning-plan-architecture-design`	Architecture Solution Design
Task breakdown	`planning-breakdown-task-steps`	Task Breakdown Planning
Migration strategy	`planning-plan-migration-strategy`	Migration Strategy Formulation
Rigorous style	`universal-universal-rigorous-style`	Rigorous Style (General)

Auto-select (no --tools): read ~/.maestro/cli-tools.json → filter enabled + eligible → first 3. Exclude api-endpoint when --mode write. Minimum 2 required.

Session: .workflow/.maestro/{YYYYMMDD}-collab-{slug}/ Scratch: .workflow/scratch/{YYYYMMDD}-collab-{slug}/

Output files:

collab-report.md — merged findings (Consensus/Conflicts/Unique/Recommendations)
context.md — Locked/Free/Deferred decisions (plan compatible)
conclusions.json — session_id, tools[], consensus_level, recommendation, confidence, dimensions[], decisions[]
per-tool/{tool}-output.md — raw CLI outputs

Downstream compatibility:

Consumer	Artifact
maestro-plan	context.md + conclusions.json (via --dir)
maestro-analyze	context.md as prior context (via state.json)
maestro-ralph	artifact chain lookup (type=collab)

<state_machine>

S_PARSE: → S_CONFIRM WHEN: eligible tools >= 2 DO: A_PARSE_AND_DISCOVER → ERROR(E002) WHEN: eligible tools < 2

S_CONFIRM: → S_FAN_OUT WHEN: -y OR user confirms → S_PARSE WHEN: user modifies tools → END WHEN: user cancels

S_FAN_OUT: → S_CROSS_VERIFY WHEN: 2+ delegates completed DO: A_FAN_OUT_DELEGATES → ERROR(E004) WHEN: all failed OR fewer than 2 completed

S_CROSS_VERIFY: → S_BOUNDARY_GRILL DO: A_CROSS_VERIFY

S_BOUNDARY_GRILL: → S_SYNTHESIZE WHEN: no boundary conflicts detected DO: — → S_SYNTHESIZE WHEN: conflicts detected + resolved DO: A_BOUNDARY_GRILL GUARD: max 3 conflicts × 3 questions; non-blocking (see boundary-grill.md)

S_SYNTHESIZE: → S_AGGREGATE DO: A_SYNTHESIZE

S_AGGREGATE: → END DO: A_AGGREGATE_RESULTS

A_PARSE_AND_DISCOVER

Parse flags: requirement, tools, mode, rule, autoYes
Read ~/.maestro/cli-tools.json → build eligible tool list
Auto-select if no --tools: first 3 eligible in config order

Build shared delegate prompt (6-field format):

PURPOSE: {requirement} + cross-verification analysis
TASK: {specific analysis tasks from requirement}
MODE: {mode}
CONTEXT: @**/* | {project context if available}
EXPECTED: Structured findings with evidence, confidence per dimension
CONSTRAINTS: {scope limits}

Create session + scratch dirs
update_plan with all phases pending

A_FAN_OUT_DELEGATES

Phase 1: Parallel Launch

Launch ALL delegate commands simultaneously in parallel:

// Parallel fan-out — one shell_exec per selected tool:
Bash(`maestro delegate "<shared_prompt>" --to agy --mode <mode> [--rule <rule>]`, { run_in_background: true })
Bash(`maestro delegate "<shared_prompt>" --to claude --mode <mode> [--rule <rule>]`, { run_in_background: true })
// ... one call per selected tool
// Execution mapping: @~/.maestro/workflows/shell-exec-protocol.md

Phase 2: Block Until ALL Complete

Each shell_exec call blocks until its delegate completes. Save each result:

Completed → save output to {scratchDir}/per-tool/{tool}-output.md
Failed → log error for that tool

Blocking guarantees (per shell-exec-protocol.md):

Each shell_exec waits until CLI returns — no short-circuit
NO max timeout — delegate can run as long as needed
NO early exit — all tools must complete before proceeding

Phase 3: Validate

Count completed tools
completed < 2 → ERROR(E004)
1 tool failed but 2+ succeeded → W001, log failure, continue

Iron rules:

NEVER skip waiting — every shell_exec MUST complete before proceeding
NEVER proceed to S_CROSS_VERIFY while any delegate is still running
NEVER set a max timeout on shell_exec calls
NEVER generate analysis internally as substitute for CLI output
NEVER summarize or paraphrase — save raw CLI output verbatim

A_CROSS_VERIFY

Coordinator reads ALL per-tool outputs from {scratchDir}/per-tool/ and classifies each finding:

Condition	Tag
2+ tools agree on same finding	CONSENSUS
Tools have contradictory findings	CONFLICT
Only 1 tool identified	UNIQUE

For each CONFLICT: note which tools disagree, their evidence, and confidence levels.

Compute: consensus_level = consensus_count / total_findings * 100

Write results to {scratchDir}/cross-verify.md.

A_BOUNDARY_GRILL

Run boundary grill per ~/.maestro/workflows/boundary-grill.md after cross-verification. Input: classified CONFLICT findings + per-tool outputs. Check upstream scope if --from used. IF conflicts → tag with resolution, feed into A_SYNTHESIZE. No conflicts → pass through.

A_SYNTHESIZE

Generate 3 output files from cross-verify results:

collab-report.md:

# Collaborative Analysis: {requirement}

## Summary
Tools: {tool list} | Consensus: {consensus_level}%

## Consensus Findings
{findings agreed by 2+ tools, with evidence}

## Conflicts
{contradictory findings with per-tool positions and evidence}

## Unique Insights
{single-tool findings worth noting}

## Recommendations
{actionable recommendations, prioritized}

## Per-Tool Confidence
| Tool | Confidence | Key Contribution |
|------|-----------|-----------------|

context.md: Locked (CONSENSUS) / Free (UNIQUE w/ strong evidence) / Deferred (CONFLICT unresolved)

conclusions.json:

{
  "session_id": "", "subject": "", "mode": "",
  "tools": [], "consensus_level": 0,
  "recommendation": "Go|No-Go|Conditional",
  "confidence": 0,
  "dimensions": [{ "name": "", "consensus": "", "details": "" }],
  "decisions": [{ "area": "", "status": "locked|free|deferred", "rationale": "" }]
}

A_AGGREGATE_RESULTS

Copy outputs to scratchDir
Register CLB artifact in state.json (type: collab, scope: adhoc)
Spec enrichment (gated): for each Locked decision, display the proposed spec entry. Unless -y/--yes, request_user_input to confirm before writing. Only confirmed entries execute maestro spec add arch "<title>" "<content>" --keywords <kw> --description "<summary>". Under -y, auto-write all Locked decisions.
update_plan all steps completed

Display summary:

== Collab Analysis Complete ==
Requirement: {requirement}
Tools: {tool list with status}
Consensus Level: {consensus_level}%

Key Findings:
  CONSENSUS: {count}
  CONFLICT:  {count}
  UNIQUE:    {count}

Reports: {scratchDir}/collab-report.md
Next: $maestro-plan --dir {scratchDir}

</state_machine>

<error_codes>

Code	Condition	Recovery
E002	Fewer than 2 eligible tools	Check cli-tools.json, specify --tools
E004	All delegates failed or < 2 completed	Show per-tool errors, abort
W001	One tool failed	Continue with remaining
W004	consensus_level < 40%	Flag in summary as low-confidence
</error_codes>

<success_criteria>

ALL analysis performed via shell_exec → maestro delegate — zero internal analysis
Parallel shell_exec calls used for fan-out launch
Every shell_exec waited to completion — no timeout cap, no early exit
All shell_exec calls waited to completion — no early exit
Per-tool raw outputs saved to {scratchDir}/per-tool/
Cross-verify: CONSENSUS/CONFLICT/UNIQUE classified, consensus_level computed
Boundary grill executed on CONFLICT items (skip if no boundary conflicts detected)
Boundary grill results written to collab-report.md § Boundary Grill Results (if conflicts found)
collab-report.md + context.md + conclusions.json produced
CLB artifact registered in state.json
Partial degradation: continued if 2+ tools succeeded </success_criteria>

<next_step_routing>

Deep feasibility analysis → $maestro-analyze "{topic}"
Plan from conclusions → $maestro-plan --dir {scratchDir}
Expand exploration → $maestro-brainstorm "{topic}" </next_step_routing>