# Team Massgen Run

> Launch parallel MassGen step mode processes — the lead manages all background tasks directly, tracks answers/votes, detects consensus, and synthesizes the result.

- Skill: `massgen/team-massgen-run` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add massgen/team-massgen-run`
- Raw SKILL.md: https://api.skillmd.com/api/skills/massgen/team-massgen-run/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: massgen (https://skillmd.com/u/massgen)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/massgen/team-massgen-run

---


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
   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`:
   ```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
   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:
   ```json
   {"text": "<description>", "category": "must"}
   ```
   Write the converted array to `.massgen-quality/sessions/<team_id>/session/eval_criteria.json`.

   **Massgen `--eval-criteria` format** (required fields):
   ```json
   [
     {"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
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
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)