team-massgen-run

name	team-massgen-run
description	Launch parallel MassGen step mode processes — the lead manages all background tasks directly, tracks answers/votes, detects consensus, and synthesizes the result.
user-invocable	true
argument-hint	<query> [with codex, gemini, grok, claude] [--no-docker] [--max-rounds N] [--timeout N] [--cost-budget N]
allowed-tools	["Read","Write","Edit","Bash","Glob","Grep","Agent"]

You are orchestrating a multi-model run. You are the lead and sole orchestrator. You launch all MassGen step mode processes as background tasks, track their results, detect consensus, and synthesize the final answer. No Agent Teams, no teammates — you manage everything directly.

Pre-Flight Checks

1. Read .massgen-quality/environment.json — verify massgen.available
2. Check api_keys in environment.json — verify which providers have auth
3. Map requested backends to API keys:
   • openai/* or codex/* → OPENAI_API_KEY
   • gemini/* → GOOGLE_API_KEY or GEMINI_API_KEY
   • claude/* or claude_code/* → ANTHROPIC_API_KEY
   • grok/* → XAI_API_KEY
4. Warn if a backend lacks its key; abort if ALL missing
5. Verify massgen --step is supported (read plugin_dir from environment.json):

   bash "<plugin_dir>/scripts/run-massgen.sh" --help 2>&1 | grep -q "\-\-step"
   

Parse Arguments

• query: The task (required)
• models: Which backends to use. Can be specified naturally — no flags needed.
• --no-docker: Use local execution (default: Docker if available)
• --max-rounds: Max rounds per agent (default: 5)
• --timeout: Total timeout in seconds (default: 1800)
• --cost-budget: Maximum total cost in dollars across all agents (no default — unlimited if unset)

Specifying models

Models can be mentioned anywhere in the prompt naturally. All of these work:

/team-massgen-run "Build a landing page"
/team-massgen-run "Build a landing page" with codex, gemini, and grok
/team-massgen-run "Build a landing page" using codex and claude
/team-massgen-run "Build a landing page" --models codex gemini

Short names expand to default models:

Short name	Expands to
codex	codex/gpt-5.4
gemini	gemini/gemini-3.1-pro-preview
claude	claude/claude-opus-4-6
grok	grok/grok-4.20-0309-reasoning

Full specs like codex/gpt-5.4 are also accepted for specific model versions.

Default selection (no models mentioned)

Read api_keys from .massgen-quality/environment.json and pick up to 3 available backends:

• OPENAI_API_KEY → codex/gpt-5.4
• GOOGLE_API_KEY or GEMINI_API_KEY → gemini/gemini-3.1-pro-preview
• ANTHROPIC_API_KEY → claude/claude-opus-4-6
• XAI_API_KEY → grok/grok-4.20-0309-reasoning

Pick the first 3 that have keys. If fewer than 2 have keys, abort.

Initialize Session

1. Create team session directory (ID format: team_<YYYYMMDD_HHMMSS>):

   .massgen-quality/sessions/<team_id>/
     config.json
     session/agents/    (empty)
     configs/           (generated per-step configs)
     synthesis/         (final answer)
   

2. Write config.json:

   {
     "session_id": "team_<timestamp>",
     "query": "<query>",
     "models": ["codex/gpt-5.4", "gemini/gemini-3.1-pro-preview"],
     "agent_mapping": {
       "agent_a": "codex/gpt-5.4",
       "agent_b": "gemini/gemini-3.1-pro-preview"
     },
     "max_rounds": 5,
     "timeout_seconds": 1800
   }
   

3. Read plugin_dir from .massgen-quality/environment.json.

4. For each backend, generate a config using the massgen wrapper:

   bash "<plugin_dir>/scripts/run-massgen.sh" \
     --quickstart --headless \
     --config .massgen-quality/sessions/<team_id>/configs/<agent_id>_step.yaml \
     --config-backend <type> \
     --config-model <model> \
     --config-agent-id <agent_id>
   

   Add --config-docker if Docker is available. Split the backend spec on / (e.g., codex/gpt-5.4 → --config-backend codex --config-model gpt-5.4). Use absolute paths for --config.

5. Generate evaluation criteria (via generate_eval_criteria MCP tool) and convert to massgen's --eval-criteria format. The MCP tool outputs {id, name, description, weight} but massgen expects {text, category}.

   Convert each criterion:

   {"text": "<description>", "category": "must"}
   

   Write the converted array to .massgen-quality/sessions/<team_id>/session/eval_criteria.json.

   Massgen --eval-criteria format (required fields):

   [
     {"text": "criterion description", "category": "must"},
     {"text": "another criterion", "category": "should", "verify_by": "how to check"}
   ]
   

   • text: description of the criterion (required)
   • category: "must" | "should" | "could" (required)
   • verify_by: how to verify (optional)

Launch All Agents in Parallel

For each agent, launch massgen --step as a background task. All paths must be absolute. Step mode runs take 5-30 minutes, so you MUST use run_in_background: true on the Bash tool.

Launch all N processes simultaneously in a single message with multiple Bash tool calls:

bash "<plugin_dir>/scripts/run-massgen.sh" \
  --step \
  --session-dir "<session_dir>" \
  --config "<config_path>" \
  --eval-criteria "<criteria_path>" \
  --automation \
  "<query>"

The wrapper handles API key sourcing and massgen resolution automatically. Record the background task ID for each agent. You will be automatically notified when each completes — no polling needed.

Collect Results

As each background task completes (you receive auto-notification):

1. Read the task output for stderr lines:

   SESSION_DIR: /path/to/session
   ACTION: new_answer|vote
   STATUS: /path/to/session/agents/<agent_id>/last_action.json
   

2. Read the per-agent action file for full details: <session_dir>/agents/<agent_id>/last_action.json
3. Update your internal state tracking:

   agent_a: { status: "answered", latest_answer_step: 1 }
   agent_b: { status: "voted", latest_answer_step: null, voted_for: "agent_a", seen_steps: {...} }
   

Wait until ALL agents have completed their step before checking consensus.

Status display

At any point, run the team status script for a formatted overview:

bash scripts/team-status.sh <session_dir> --config <config.json>

This shows: agent table, answer previews, vote graph, consensus status, and a timeline swimlane of all rounds.

Check Consensus

CRITICAL: Only check consensus when ALL agents have completed their step.

1. If any agent submitted a new_answer this round:

   • All existing votes are potentially stale
   • For each vote: read vote.json → check seen_steps against current answer steps
   • If vote's seen_steps[X] < current answer step for agent X → vote is stale

2. Only when ALL agents have voted with non-stale votes:

   • Count votes → if majority vote for same target → CONSENSUS

3. If no consensus or stale votes exist:

   • Re-launch every agent that does not have a valid (non-stale) vote for a current answer
   • Go back to "Launch All Agents in Parallel" for that subset

4. If max_rounds, timeout_seconds, or --cost-budget reached:

   • Force consensus using the answer with the most votes
   • If no votes exist: use the first answer submitted

Answer-Driven Restart

When an agent submits a new_answer:

• Any agent that previously voted is now stale
• Re-launch stale voters in the next round
• Agents that submitted new_answer this round wait
• Agents that haven't acted yet continue normally

This mirrors MassGen's production restart_pending logic.

Final Synthesis

After consensus:

1. Read agents/<winner>/last_action.json → note workspace_path
2. Access deliverable files from session_dir/agents/<winner>/<step>/workspace/ (workspace paths in answer text point to this location — auto-replaced on save)
3. Read all other agents' latest answers for context
4. Clean up the deliverable:
   • Verify correctness (no errors, broken code, missing pieces)
   • Test/validate code if applicable
   • Remove debug output, placeholders, inconsistencies
   • Ensure production-ready quality
5. Merge unique strengths from other agents that the winner missed
6. Write final synthesis to .massgen-quality/sessions/<team_id>/synthesis/final_answer.md
7. Present the result to the user

Timeout and Budget Handling

• Track elapsed time from start
• After each round, sum cost from each agent's last_action.json to get cumulative spend
• If timeout_seconds reached: force consensus using the answer with the most votes; if no votes, use the first answer submitted
• If max_rounds reached: same forced consensus logic
• If --cost-budget exceeded: same forced consensus logic — report the total spend to the user

Reference Documentation

Read these for protocol details:

• skills/team-massgen-run/references/step-mode.md — MassGen step mode interface
• skills/team-massgen-run/references/team-protocol.md — Lead-managed orchestration protocol

Rules

• NEVER modify files in session_dir/agents/ directly — only massgen writes there
• NEVER influence agent behavior — agents decide whether to answer or vote based on session state. Claude is a mechanical orchestrator, not a participant.
• NEVER make quality judgments about agent answers when resolving consensus or forced consensus. Use vote counts only.
• ALWAYS wait for ALL agents to complete before checking consensus
• Track and report total cost across all step mode invocations
• If an agent errors out, continue with remaining agents
• Minimum 2 agents required — if only 1 remains, use their answer directly
• Launch background tasks in parallel (multiple Bash calls in one message)