Setup

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.

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)"  "" --platform 

Where:

• ` is the user's chosen percentage (e.g., 100`)
• `` is the enforcement command for their test runner:
• pytest → "pytest --cov --cov-fail-under="
• vitest/pnpm → "pnpm vitest run --coverage"
• jest/npm → "npx jest --coverage"
• go → "go test -coverprofile=coverage.out ./..."
• cargo → "cargo tarpaulin --fail-under "
• ` 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.

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 | | .golangci.yml OR .golangci.yaml | golangci-lint | | .clippy.toml or clippy in Cargo.toml | clippy |

1.6 Formatter

| Marker | Formatter | |---|---| | .prettierrc* OR prettier in devDependencies | prettier | | biome.json (also formats) | biome | | black in Python deps | black | | [tool.ruff.format] in pyproject.toml | ruff format | | rustfmt.toml OR .rustfmt.toml | rustfmt |

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

1.7 Type Checker

| Marker | Type Checker | |---|---| | tsconfig.json | tsc | | mypy in Python deps OR [tool.mypy] in pyproject.toml | mypy | | pyright in Python deps OR pyrightconfig.json | pyright |

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

1.8 CI Detection

| Marker | CI System | |---|---| | .github/workflows/*.yml | GitHub Actions | | .gitlab-ci.yml | GitLab CI | | Jenkinsfile | Jenkins | | .circleci/config.yml | CircleCI |

1.9 Git Hooks Detection

| Marker | Hook System | |---|---| | .husky/ | Husky | | .pre-commit-config.yaml | pre-commit | | .lefthook.yml | Lefthook |

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:

1. External AI tools — Ask only for non-trivial projects: "Set up external AI tools (Codex/Gemini) for cost savings on implementation?" Options: "Yes" / "No"

1. 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"

1. CI pipeline — Ask only if NO CI detected: "Create a GitHub Actions CI pipeline?" Options: "Yes (Recommended)" / "No"

1. 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)"  "" --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 `` 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.

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 — the standalone beads plugin (v0.63.3+) provides bd compact for semantic summarization natively.

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

| Condition | Source | Destination | |---|---|---| | User chose YES for CI | ./templates/ci.yml | .github/workflows/ci.yml | | User chose YES for git hooks AND Husky detected or Node.js project | ./templates/pre-push | .husky/pre-push (chmod +x) | | User chose YES for external tools | ./templates/external-tools.yaml | .metaswarm/external-tools.yaml | | Always | ./templates/.env.example | .env.example | | Always | ./templates/SERVICE-INVENTORY.md | SERVICE-INVENTORY.md | | Always | ./templates/gitignore | Merge into existing .gitignore (append missing entries, never duplicate) |

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:

| Test Runner | Pkg Mgr | Test Command | Coverage Command | |---|---|---|---| | vitest | pnpm | pnpm vitest run | pnpm vitest run --coverage | | vitest | npm | npx vitest run | npx vitest run --coverage | | vitest | yarn | yarn vitest run | yarn vitest run --coverage | | jest | pnpm | pnpm jest | pnpm jest --coverage | | jest | npm | npx jest | npx jest --coverage | | jest | yarn | yarn jest | yarn jest --coverage | | mocha | any | npx mocha | npx nyc mocha | | pytest | -- | pytest | pytest --cov --cov-fail-under={threshold} | | go test | -- | go test ./... | go test -coverprofile=coverage.out ./... | | cargo test | -- | cargo test | cargo tarpaulin --fail-under {threshold} | | mvn test | -- | mvn test | mvn test jacoco:report | | gradle test | -- | gradle test | gradle test jacocoTestReport |

---

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.

Command naming: When recommending me

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: dsifry
• Source: dsifry/metaswarm
• License: MIT

Install and usage instructions live in the source repository linked above.