Setup

Interactive setup for metaswarm. Detects your stack, asks targeted questions, writes project-local files, and creates platform-appropriate instruction files and command shims. Replaces both npx metaswarm init and the old /metaswarm-setup command.

After Phase 2 (user questions), determine the correct coverage command from the detection results, then run this Bash command:

PLUGIN_ROOT="${PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-${extensionPath:-}}}"
if [ -z "$PLUGIN_ROOT" ]; then
  setup_script="$(find "${CODEX_HOME:-$HOME/.codex}/plugins/cache" -path '*/metaswarm/*/lib/setup-mandatory-files.sh' -print -quit 2>/dev/null)"
  if [ -n "$setup_script" ]; then
    PLUGIN_ROOT="$(cd "$(dirname "$setup_script")/.." && pwd)"
  fi
fi
if [ -z "$PLUGIN_ROOT" ] && [ -f "$(pwd)/lib/setup-mandatory-files.sh" ]; then
  PLUGIN_ROOT="$(pwd)"
fi
bash "${PLUGIN_ROOT}/lib/setup-mandatory-files.sh" "$(pwd)" <threshold> "<coverage-command>" --platform <platform>

Where:

• <threshold> is the user's chosen percentage (e.g., 100)
• <coverage-command> is the enforcement command for their test runner:
  • pytest → "pytest --cov --cov-fail-under=<threshold>"
  • vitest/pnpm → "pnpm vitest run --coverage"
  • jest/npm → "npx jest --coverage"
  • go → "go test -coverprofile=coverage.out ./..."
  • cargo → "cargo tarpaulin --fail-under <threshold>"
• <platform> is codex, claude, gemini, or all. Prefer:
  • codex when running in Codex (PLUGIN_ROOT or CODEX_HOME is present, or the user invoked $setup)
  • claude when running in Claude Code (CLAUDE_PLUGIN_ROOT is present, or the setup skill was invoked there)
  • gemini when running in Gemini (extensionPath is present, or the setup skill was invoked there)
  • all only when the user explicitly asks to configure every supported CLI

The script handles:

1. Instruction file — AGENTS.md for Codex, CLAUDE.md for Claude, GEMINI.md for Gemini; appends metaswarm section (or writes new), skips if already present
2. .coverage-thresholds.json — writes at project root with correct thresholds and command
3. Claude command shims — for Claude/all only, writes .claude/commands/start-task.md, prime.md, review-design.md, self-reflect.md, pr-shepherd.md, brainstorm.md

The script outputs JSON with what was created/skipped/errored. Check that "status": "ok".

If the script is not available or fails, fall back to writing these files manually with the Write tool. Do NOT skip them. </CRITICAL-REQUIREMENTS>

Pre-Flight

Existing Profile Check

Use Glob to check if .metaswarm/project-profile.json exists.

• If it exists: Read it, present the current configuration summary, and ask the user via AskUserQuestion: "You already have a metaswarm project profile. Re-run setup (overwrites choices) or skip?" Options: "Re-run setup" / "Skip". If the user skips, stop with: "Setup skipped. Existing configuration unchanged."
• If it does not exist: Continue to Project Detection.

Phase 1: Project Detection

Scan the project directory silently using Glob and Read. Do NOT ask the user for any of this information. Detect everything, then present results.

1.1 Language

Check for marker files at the project root:

If tsconfig.json exists alongside package.json, the language is "TypeScript".

If multiple languages are detected, note all of them but use the primary one (most infrastructure) for command generation.

If no language detected: Use AskUserQuestion to ask the user what language/stack they are using before proceeding.

1.2 Framework

Node.js/TypeScript — Read package.json and check dependencies + devDependencies:

Python — Check pyproject.toml or requirements.txt for: fastapi, django, flask.

Go — Read go.mod for: github.com/gin-gonic/gin (Gin), github.com/labstack/echo (Echo), github.com/gofiber/fiber (Fiber).

If no framework detected, set to null.

1.3 Package Manager (Node.js only)

Default to npm if no lock file found. For non-Node.js, set to null.

1.4 Test Runner

Node.js/TypeScript (first match wins):

1. Glob for vitest.config.* or vitest in devDependencies -> vitest
2. Glob for jest.config.* or jest in devDependencies -> jest
3. mocha in devDependencies -> mocha

Python: Check for [tool.pytest] in pyproject.toml or pytest in dependencies -> pytest (default for Python).

Go: go test (built-in). Rust: cargo test (built-in). Java/Maven: mvn test. Java/Gradle: gradle test.

1.5 Linter

1.6 Formatter

If biome detected as both linter and formatter, report once as "Biome (lint + format)".

1.7 Type Checker

Go (go vet) and Rust (cargo check) have built-in type checking — note but do not list separately.

1.8 CI Detection

1.9 Git Hooks Detection

1.10 Present Results

After all detection, present findings:

I detected the following about your project:

  Language:        {language}
  Framework:       {framework or "None detected"}
  Package manager: {package_manager or "N/A"}
  Test runner:     {test_runner or "None detected"}
  Linter:          {linter or "None detected"}
  Formatter:       {formatter or "None detected"}
  Type checker:    {type_checker or "None detected"}
  CI:              {ci or "None detected"}
  Git hooks:       {git_hooks or "None detected"}

Phase 2: Interactive Questions

Use AskUserQuestion to ask ONLY questions relevant based on detection. 3-5 questions maximum.

Always ask:

1. Coverage threshold — "What test coverage threshold do you want to enforce?" Options: "100% (Recommended)" / "80%" / "60%" / "Custom"

Ask only if relevant:

2. External AI tools — Ask only for non-trivial projects: "Set up external AI tools (Codex/Gemini) for cost savings on implementation?" Options: "Yes" / "No"
3. Visual review — Ask only if a web framework was detected (Next.js, Nuxt, React, Vue, Angular, SvelteKit, Django, Flask): "Enable visual screenshot review for UI changes?" Options: "Yes" / "No"
4. CI pipeline — Ask only if NO CI detected: "Create a GitHub Actions CI pipeline?" Options: "Yes (Recommended)" / "No"
5. Git hooks — Ask only if NO hooks detected: "Set up git hooks for pre-push quality checks?" Options: "Yes (Recommended)" / "No"

Phase 3: Write Required Files

Step 1: Run the mandatory files script

This is the FIRST thing to do after Phase 2. Determine the coverage command, then run:

PLUGIN_ROOT="${PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-${extensionPath:-}}}"
if [ -z "$PLUGIN_ROOT" ]; then
  setup_script="$(find "${CODEX_HOME:-$HOME/.codex}/plugins/cache" -path '*/metaswarm/*/lib/setup-mandatory-files.sh' -print -quit 2>/dev/null)"
  if [ -n "$setup_script" ]; then
    PLUGIN_ROOT="$(cd "$(dirname "$setup_script")/.." && pwd)"
  fi
fi
if [ -z "$PLUGIN_ROOT" ] && [ -f "$(pwd)/lib/setup-mandatory-files.sh" ]; then
  PLUGIN_ROOT="$(pwd)"
fi
bash "${PLUGIN_ROOT}/lib/setup-mandatory-files.sh" "$(pwd)" <threshold> "<coverage-command>" --platform <platform>

Example for Codex with Python/pytest at 100%:

bash "${PLUGIN_ROOT}/lib/setup-mandatory-files.sh" "$(pwd)" 100 "pytest --cov --cov-fail-under=100" --platform codex

Check the JSON output. If "status": "ok", the 3 mandatory files are done. Report to the user what was created.

If the script fails or is not found, write the files manually (see CRITICAL-REQUIREMENTS above for what they are).

Step 2: Customize instruction-file TODO sections

If the instruction file was newly written (not appended), use Edit to replace the TODO placeholders:

• Replace npm test / npm run test:coverage with the detected test/coverage commands
• Replace TypeScript strict mode / ESLint + Prettier with the detected language tools
• Remove the <!-- TODO: ... --> comment lines

If the instruction file was appended to (existing file), this step is not needed.

Step 3: Additional files

Knowledge Base

Read each file from ./knowledge/:

• patterns.jsonl, gotchas.jsonl, decisions.jsonl, api-behaviors.jsonl, codebase-facts.jsonl, anti-patterns.jsonl, facts.jsonl

Write them to .beads/knowledge/ in the project. Skip any that already exist.

Shell Utilities

Read each file from ./bin/:

• estimate-cost.sh, external-tools-verify.sh, pr-comments-check.sh, pr-comments-filter.sh

Write them to bin/ in the project. Make executable with chmod +x. Skip any that already exist.

Do NOT copy metaswarm-agents.sh or metaswarm-usage into the project. Skills always run them from the plugin: the plugin bin/ is on PATH in Claude Code, so resolve with command -v metaswarm-agents.sh, falling back to ${CLAUDE_PLUGIN_ROOT:-$PLUGIN_ROOT}/bin/metaswarm-agents.sh.

Models Config and Phase Agents

1. Note whether .claude/agents/ already exists (it matters for Phase 6).
2. If .metaswarm/models.yaml is absent, copy ./templates/models.yaml to .metaswarm/models.yaml (create .metaswarm/ if needed).
3. Generate the project-scoped phase agents from it:

MA="$(command -v metaswarm-agents.sh || echo "${CLAUDE_PLUGIN_ROOT:-$PLUGIN_ROOT}/bin/metaswarm-agents.sh")" # command -v metaswarm-agents.sh
"$MA" generate

This writes .claude/agents/metaswarm-<role>.md. Exit 1 means a file was hand-edited or is user-authored; report it to the user and do not pass --force unless they ask. Exit 2 means models.yaml has a syntax error (models.yaml:<line>: <reason>); show it and ask the user to fix it.

TypeScript Scripts

Read each file from ./scripts/:

• beads-fetch-pr-comments.ts, beads-fetch-conversation-history.ts

Write them to scripts/ in the project. Skip any that already exist.

Note: The former beads-self-reflect.ts script is no longer bundled. /self-reflect captures session learnings on its own and needs no extra script.

Node.js dependency warning: If Node.js was NOT detected as the project language, print:

"Note: scripts/*.ts require Node.js (npx tsx) to run. Some advanced features (PR comment fetching, conversation history) will work once Node.js is available. Core metaswarm functionality does not require Node.js."

Conditional Files

For .gitignore, read the existing file (if any), then append language-specific entries that are not already present. Always ensure .env, .DS_Store, and *.log are included.

Phase 4: Profile Creation

Write .metaswarm/project-profile.json with all detection results and user choices:

{
  "metaswarm_version": "1.0.0",
  "distribution": "plugin",
  "installed_at": "{current ISO 8601 timestamp}",
  "updated_at": "{current ISO 8601 timestamp}",
  "detection": {
    "language": "{detected language}",
    "framework": "{detected framework or null}",
    "test_runner": "{detected test runner}",
    "linter": "{detected linter or null}",
    "formatter": "{detected formatter or null}",
    "package_manager": "{detected package manager or null}",
    "type_checker": "{detected type checker or null}",
    "ci": "{detected CI system or null}",
    "git_hooks": "{detected hook system or null}"
  },
  "choices": {
    "coverage_threshold": 100,
    "external_tools": false,
    "visual_review": false,
    "ci_pipeline": false,
    "git_hooks": false
  },
  "commands": {
    "test": "{resolved test command}",
    "coverage": "{resolved coverage command}",
    "lint": "{resolved lint command or null}",
    "typecheck": "{resolved typecheck command or null}",
    "format_check": "{resolved format check command or null}"
  }
}

Fill all values from detection and user answers. Use null for anything not detected.

Command resolution reference:

Phase 5: Post-Setup Actions

5.1 External Tools (if enabled)

1. Check if Codex and Gemini CLIs are installed via Bash (command -v codex, command -v gemini)
2. For tools not installed, tell the user how to install them
3. For installed tools, verify with --version
4. Update .metaswarm/external-tools.yaml — set enabled: true for installed tools, enabled: false for missing ones

5.2 Visual Review (if enabled)

1. Run npx playwright install chromium via Bash
2. Report success or failure

5.3 Git Hooks (if enabled)

Node.js/TypeScript: Install Husky if not present, run npx husky init, write pre-push hook. Python: Suggest pip install pre-commit and offer to create .pre-commit-config.yaml. Other: Suggest appropriate hook tools for the ecosystem.

Phase 6: Summary

Present a final summary:

Setup complete! Here's what was configured:

  Project:         {name}
  Language:        {language}
  Framework:       {framework or "None"}
  Test runner:     {test_runner} -> `{test command}`
  Coverage:        {threshold}% -> `{coverage command}`
  Linter:          {linter or "None"}
  Formatter:       {formatter or "None"}
  CI:              {ci or "None"}
  Git hooks:       {hooks or "None"}
  External tools:  {Enabled/Disabled}
  Visual review:   {Enabled/Disabled}

Mandatory files:
  ✔ {instruction file} — {written new / appended metaswarm section / already had it}
  ✔ .coverage-thresholds.json — {threshold}% coverage, enforcement: `{command}`
  ✔ .claude/commands/   — Claude only: shims for start-task, prime, review-design, self-reflect, pr-shepherd, brainstorm

Other files written:
  {list every other file written or modified with its path}

You're all set! Run the platform's start command to begin working.

Restart note: if .claude/agents/ did not exist before Phase 3 and generate created it, tell the user to restart the session (Claude Code only watches agent directories that existed at session start). Until then the plugin's default phase models apply.

Command naming: When recommending metaswarm skills to the user, use $name forms ($start, $setup, $status, $pr-shepherd) unless the active platform has already created and selected its own command shims.

Offer 1-2 relevant tips based on configuration:

• If external tools enabled: "Use $external-tools to check tool status."
• If no CI set up: "Consider adding CI later -- metaswarm includes a template at ./templates/ci.yml."
• If visual review enabled: "The visual review skill will screenshot your app during development."

Missing Setup Auto-Detection

If $start is invoked and .metaswarm/project-profile.json does not exist, the start skill should auto-route here. This skill will run the full setup flow, then hand back to $start to continue with the user's original request.

Error Handling

• If any Bash command fails, report the error and offer to skip that step or retry.
• If a file cannot be read, note it and continue with other detection.
• If AskUserQuestion is dismissed, use defaults: 100% coverage, no external tools, no visual review.
• Never leave the project half-configured. The pre-flight check allows re-running setup to completion.
• All template paths are hardcoded in this skill. Never construct file paths from user-provided input.

Final Verification (run this before declaring setup complete)

Before saying "setup complete", run this Bash command to verify the 3 mandatory files:

platform="${METASWARM_PLATFORM:-${CLAUDE_PLUGIN_ROOT:+claude}}"
platform="${platform:-${extensionPath:+gemini}}"
platform="${platform:-${CODEX_HOME:+codex}}"
platform="${platform:-${PLUGIN_ROOT:+codex}}"
platform="${platform:-claude}"
case "$platform" in
  claude) instruction_file="CLAUDE.md" ;;
  gemini) instruction_file="GEMINI.md" ;;
  codex) instruction_file="AGENTS.md" ;;
  *) echo "UNKNOWN PLATFORM: $platform"; exit 1 ;;
esac
echo "$instruction_file:"; grep -c "metaswarm" "$instruction_file" 2>/dev/null || echo "MISSING"
echo "coverage:"; ls .coverage-thresholds.json 2>/dev/null || echo "MISSING"
if [ "$platform" = "claude" ]; then
  echo "shims:"; ls .claude/commands/start-task.md .claude/commands/prime.md .claude/commands/brainstorm.md 2>/dev/null || echo "MISSING"
fi

If any output says "MISSING", go back and run the setup-mandatory-files.sh script or create the files manually. Do NOT declare success with missing files.

When reporting available commands to the user, use $name skill invocation unless the active platform has its own confirmed command shims. Do NOT recommend commands that do not exist on that platform.