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 __REVIEW_PENDING__ , tell the user: "MassGen has changes ready for review. You can open the WebUI to review diffs visually, or tell me which files to approve/reject." Two resolution paths: Browser : User opens the REVIEW_URL and approves/rejects in the UI. Agent (text-based) : Fetch diffs via GET /api/sessions/{id}/review , show the user a summary, then submit their decision: # Approve all curl -X POST " $REVIEW_API " -H "Content-Type: application/json" \ -d '{"approved": true, "action": "approve"}' # Approve specific files curl -X POST " $REVIEW_API " -H "Content-Type: application/json" \ -d '{"approved": true, "approved_files": ["src/foo.py"]}' # Reject all curl -X POST " $REVIEW_API " -H "Content-Type: application/json" \ -d '{"approved": false, "action": "reject"}' Either path resolves the review — the other side auto-closes. After resolution, __REVIEW_COMPLETE__ APPROVED=true|false is printed. 6. Read Results Read the ANSWER: path from the output. The winning agent's workspace is always in the workspace/ directory next to answer.txt . Workspace paths in answer.txt are best-effort normalized to reference the adjacent workspace/ directory. However, always navigate to the workspace/ next to answer.txt as the ground truth — not paths mentioned in the text. For plan mode, project_plan.json is in the workspace. For spec mode, project_spec.json is in the workspace. Optional Flags (only when requested) Flag Purpose --quick One-shot, no voting/refinement --plan-depth <level> Decomposition depth: dynamic (default), shallow , medium , deep --plan-thoroughness thorough Deeper strategic reasoning (default: standard ) --personas <style> Agent diversity: perspective , implementation , methodology , or off --cwd-context ro Give agents read access to codebase --cwd-context rw Give agents write access to codebase --web --no-browser Enable WebUI for watching progress (on by default in wrapper) Config MassGen auto-discovers config from .massgen/config.yaml or ~/.config/massgen/config.yaml . See setup instructions above. References Only consult when the quick dispatch isn't enough: File When references/criteria_guide.md Criteria format, tiers, examples references/config_setup.md Headless config creation references/advanced_workflows.md Checkpoint loops, living documents, structured eval, plan-evaluate integration