setup

# 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
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:
1. **CLAUDE.md** — appends metaswarm section (or writes new), skips if already present
2. **`.coverage-thresholds.json`** — writes at project root with correct thresholds and command
3. **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) |

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

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:

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

Example for Python with pytest at 100%:
```bash
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 `<!-- TODO: ... -->` 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:

```json
{
  "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:
  ✔ 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

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

```bash
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`).