Metaswarm setup

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

install

source · Clone the upstream repo

git clone https://github.com/dsifry/metaswarm

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/dsifry/metaswarm "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/setup" ~/.claude/skills/dsifry-metaswarm-setup && rm -rf "$T"

manifest: skills/setup/SKILL.md

source content

Setup

Interactive, Claude-guided setup for metaswarm. Detects your stack, asks targeted questions, writes project-local files, and creates command shims. Replaces both

npx metaswarm init

and the old

/metaswarm-setup

command.

<CRITICAL-REQUIREMENTS> Setup MUST produce these 3 mandatory outputs. 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:

bash "${CLAUDE_PLUGIN_ROOT}/lib/setup-mandatory-files.sh" "$(pwd)" <threshold> "<coverage-command>"

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

The script handles:

CLAUDE.md — appends metaswarm section (or writes new), skips if already present
.coverage-thresholds.json
— writes at project root with correct thresholds and command

6 shims in
.claude/commands/
— writes

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)

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

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

Glob for
```
vitest.config.*
```
or
```
vitest
```
in devDependencies ->
```
vitest
```
Glob for
```
jest.config.*
```
or
```
jest
```
in devDependencies ->
```
jest
```
```
mocha
```
in devDependencies ->
```
mocha
```

Python: Check for

[tool.pytest]

pyproject.toml

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]

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:

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

Ask only if relevant:

External AI tools — Ask only for non-trivial projects: "Set up external AI tools (Codex/Gemini) for cost savings on implementation?" Options: "Yes" / "No"
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"
CI pipeline — Ask only if NO CI detected: "Create a GitHub Actions CI pipeline?" Options: "Yes (Recommended)" / "No"
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:

bash "${CLAUDE_PLUGIN_ROOT}/lib/setup-mandatory-files.sh" "$(pwd)" <threshold> "<coverage-command>"

Example for Python with pytest at 100%:

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

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 CLAUDE.md TODO sections

If CLAUDE.md 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 CLAUDE.md 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)

Check if Codex and Gemini CLIs are installed via Bash (
```
command -v codex
```
,
```
command -v gemini
```
)
For tools not installed, tell the user how to install them
For installed tools, verify with
```
--version
```

Update

.metaswarm/external-tools.yaml

— set

enabled: true

for installed tools,

enabled: false

for missing ones

5.2 Visual Review (if enabled)

Run
```
npx playwright install chromium
```
via Bash
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:
  ✔ CLAUDE.md          — {written new / appended metaswarm section / already had it}
  ✔ .coverage-thresholds.json — {threshold}% coverage, enforcement: `{command}`
  ✔ .claude/commands/   — 6 shims: 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 /start-task to begin working.

Command naming: When recommending commands to the user, always use the short shim names (

/start-task

/prime

/brainstorm

, etc.), NOT the namespaced plugin names (

/metaswarm:start-task

). The shims you just created in

.claude/commands/

make the short names work. The short names are easier to type and remember.

Offer 1-2 relevant tips based on configuration:

If external tools enabled: "Use
```
/external-tools-health
```
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

/start-task

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-task

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:

echo "CLAUDE.md:"; grep -c "metaswarm" CLAUDE.md 2>/dev/null || echo "MISSING"; echo "coverage:"; ls .coverage-thresholds.json 2>/dev/null || echo "MISSING"; echo "shims:"; ls .claude/commands/start-task.md .claude/commands/prime.md .claude/commands/brainstorm.md 2>/dev/null || echo "MISSING"

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 the short names (

/start-task

/prime

/brainstorm

, etc.) — NOT the namespaced names (

/metaswarm:start-task

). The command shims make the short names work. Do NOT recommend commands that don't exist (e.g.,

/metaswarm:start

/metaswarm:status

/metaswarm:architect-agent