/massgen

name: massgen
description: "Invoke MassGen's multi-agent system. Use when the user wants multiple AI agents on a task: writing, code, review, planning, specs, research, design, or any task where parallel iteration beats working alone."

MassGen Skill

Delegate tasks to your MassGen team.

Before You Launch

Check that a config exists:

ls .massgen/config.yaml 2>/dev/null || ls ~/.config/massgen/config.yaml 2>/dev/null

If **no config exists**, set one up:

• **Default (browser)**: run `uv run massgen --web-quickstart` — user picks

models and keys in the browser

• **Headless**: read `references/config_setup.md` — you discover available

backends via `--list-backends`, check the user's API keys, discuss preferences, and generate config with `--quickstart --headless`

If config exists — launch immediately. No need to ask questions first.

Important: Only Add What's Asked

Do NOT add extra flags unless the user explicitly requests them:

• No `--personas` unless the user asks for diverse approaches
• No `--plan-depth deep` unless the user wants detailed decomposition
• No `--quick` unless the user wants speed over quality

The defaults are good. Let MassGen handle the rest.

Quick Dispatch

1. Detect Mode

| User Intent | CLI Flags | |-------------|-----------| | General task (write, build, research, design) | *(default)* | | Review/critique existing work | `--checklist-criteria-preset evaluation` | | Plan a feature or project | `--plan` | | Plan and auto-execute | `--plan-and-execute` | | Write requirements/spec | `--spec` | | Execute an existing plan | `--execute-plan <path_or_latest>` | | Execute against an existing spec | `--execute-spec <path_or_latest>` |

2. Write Criteria

**Always write opinionated evaluation criteria** tailored to the task. Criteria shape what agents produce, not just how they're scored. Save to a temp file and pass via `--eval-criteria`. Aim for 4-7 criteria.

**Required JSON format** — each criterion needs `text`, `category`, and `anti_patterns`:

{
  "aspiration": "A site a designer would screenshot for their portfolio",
  "criteria": [
    {
      "text": "Design coherence: Does it feel authored or assembled? ...",
      "category": "primary",
      "anti_patterns": ["unmodified library defaults", "AI-generic aesthetics"]
    },
    {
      "text": "Content depth: Every section teaches something specific ...",
      "category": "standard",
      "anti_patterns": ["Wikipedia-summary prose", "filler sections"]
    }
  ]
}

Categories: `primary` (ONE — where the model needs most push), `standard` (must-pass), `stretch` (nice-to-have). See `references/criteria_guide.md` for full guidance on writing effective opinionated criteria.

For evaluate/plan/spec modes, you can use `--checklist-criteria-preset` instead of writing custom criteria (presets: `evaluation`, `planning`, `spec`, `persona`, `decomposition`, `prompt`, `analysis`).

3. Build Prompt

**General**: User's task with relevant context.

**Evaluate**: What to evaluate. Auto-gather git diff, changed files, test output. Keep it factual — what was built, not your quality opinion. Let agents discover issues independently.

**Plan**: Goal + constraints.

**Spec**: Problem statement + user needs + constraints.

4. Choose CWD Context

**Default to `rw` when the task produces files.** If the deliverable is a file (code, docs, config, README, website, etc.), agents need write access. Use `ro` only when agents need to *read* the codebase for context but their output is pure text (an answer, review, or analysis) — not files.

| Scenario | Flag | |----------|------| | Task produces/modifies files in the project (code, docs, configs, etc.) | `--cwd-context rw` | | Task needs codebase context but output is text only (review, analysis, Q&A) | `--cwd-context ro` | | Isolated task, no codebase needed (default) | *(omit flag)* |

**Rule of thumb**: if the user says "write", "create", "build", "rewrite", "update", or "edit" something in the project → `rw`.

5. Run

Always use the wrapper script:

# Isolated task (default, no cwd-context needed)
bash "$SKILL_DIR/scripts/massgen_run.sh" \
  --mode general \
  --criteria /tmp/massgen_criteria.json \
  "Create an SVG of a butterfly mixed with a panda"

# Task that writes to the project → rw
bash "$SKILL_DIR/scripts/massgen_run.sh" \
  --mode general --cwd-context rw \
  --criteria /tmp/massgen_criteria.json \
  "Rewrite the README with better examples and structure"

The wrapper includes `--web --no-browser` by default. The run starts immediately — the user can open http://localhost:8000/ anytime to monitor progress. **Tell the user about this URL.**

Run in the background. MassGen prints these for tracking:

• `LOG_DIR: <path>` — full run data
• `STATUS: <path>/status.json` — live status
• `ANSWER: <path>` — winning agent's answer.txt

Expect 15-45 minutes for multi-round runs.

5b. Review Notification (when `--cwd-context rw`)

When agents have write access (`--cwd-context rw`), automatically add `--web-review` so the user can review git diffs before changes are applied. Review requires `--web` (the wrapper's default).

**Headless (`--no-web`)**: If the user explicitly requests headless mode with `--cwd-context rw`, skip `--web-review` — changes are applied directly without a review gate. Warn the user that there will be no diff review.

After launching the MassGen run, **also launch the review watcher** in the background. Parse `LOG_DIR` from the MassGen output first:

# Launch the watcher (reads LOG_DIR from the MassGen run output)
bash "$SKILL_DIR/scripts/review_watcher.sh" "$LOG_DIR"

The watcher polls `status.json` and prints structured markers when review is ready:

__REVIEW_PENDING__
REVIEW_URL: http://localhost:8000/?v=2
REVIEW_API: http://localhost:8000/api/sessions/{id}/review-response
FILES_CHANGED: src/foo.py (M), src/bar.py (A)
__END_REVIEW_INFO__

When you see `__RE