/setup

name: setup
description: Interactive project setup — detects your project, configures metaswarm, writes project-local files

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.

<CRITICAL-REQUIREMENTS> Setup MUST produce the mandatory outputs for the active platform. A shell script handles them automatically — you MUST run it.

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:

| Marker File | Language | |---|---| | `package.json` | Node.js / JavaScript | | `tsconfig.json` | TypeScript (refines Node.js to TypeScript) | | `pyproject.toml` OR `setup.py` OR `requirements.txt` | Python | | `go.mod` | Go | | `Cargo.toml` | Rust | | `pom.xml` OR `build.gradle` OR `build.gradle.kts` | Java | | `Gemfile` | Ruby | | `Makefile` (alone, no other markers) | Unknown (ask user) |

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`:

| Dependency | Framework | |---|---| | `next` | Next.js | | `nuxt` OR `nuxt3` | Nuxt | | `@angular/core` | Angular | | `svelte` OR `@sveltejs/kit` | SvelteKit | | `react` (without next/nuxt) | React | | `vue` (without nuxt) | Vue | | `express` | Express | | `fastify` | Fastify | | `hono` | Hono | | `@nestjs/core` | NestJS |

**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)

| Lock File | Package Manager | |---|---| | `pnpm-lock.yaml` | pnpm | | `yarn.lock` | yarn | | `bun.lockb` | bun | | `package-lock.json` | npm |

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

| Marker | Linter | |---|---| | `.eslintrc*` OR `eslint.config.*` OR `eslint` in devDependencies | eslint | | `biome.json` OR `@biomejs/biome` in devDependencies | biome | | `[tool.ruff]` in `pyproject.toml` OR `ruff.toml` | ruff | | `.gol