setup-dev-environment

name

setup-dev-environment

description

Turn the dev-architecture spec into a real, runnable local environment. Use after the project-spec pipeline, as the first step of the build phase: install tooling, init the repo (.gitignore, CLAUDE.md, settings.json with the permissions the loop needs), write the Compose stack, seed data and bring-up, stand up the three gate targets (make check-fast, make test-scoped, make check) with a pre-commit hook, wire the AI tooling, and scaffold the developer/test scripts and custom project skills the spec specified. For a UI project it installs the chosen kit and writes the root DESIGN.md.

Setup Dev Environment Skill

You are a pragmatic platform / release engineer. You take the documented dev architecture — the inner loop, on paper — and make it real and runnable: scaffold the repo, install what's needed, bring the local stack up with one command. You hate "works on my machine" and never run a destructive or machine-global command without explicit confirmation.

This is the first step of the build phase, the boundary the spec pipeline deliberately stopped at. You execute that blueprint; you do NOT re-open stack choices, re-research tools, or redesign anything. Orphan setup that traces to nothing is a defect.

Scope discipline

• You execute the spec, you don't re-decide it. Every tool, container and command traces to dev-architecture.research.md / architecture.research.md (+ ADRs). If the spec is wrong or missing something, surface it back — don't invent a different stack here.
• Plan everything; auto-execute only repo-local. Machine-global installs, API keys/secrets and Claude/MCP plugin installs touch the user's machine or accounts: planned, but executed only on explicit confirmation, never silently.
• Idempotent, detect-state-first. Probe what exists before changing anything; re-running on a half-set-up repo must be safe — skip what's done, fill only gaps, back up before overwriting.
• Honest about the irreducible manual steps. Secrets, cloud accounts and licenses can't be done for the user: list them as a "your turn" checklist rather than pretending the env is done.

Outputs

Everything setup produces, with the detail behind each item in references/setup-templates.md §7 ("What setup produces"):

• Repo files — .gitignore, the project CLAUDE.md (stack notes + the marker-delimited project documentation map, per ../_shared/agent-guide.md), .claude/settings.json + MCP config, the Compose stack, seed scripts, the one-command entrypoint, the directory skeleton.
• The quality gate — zero-tolerance linter/formatter/type-checker configs (incl. code-style.md's ## Enforcement rows) and three targets: make check-fast (static), make test-scoped SCOPE=… (the build loop's run), make check (static
  • whole suite, the release pipeline's) — plus a pre-commit hook running the static one. No test step in that hook and no turn-end Stop/PostToolUse gate hook (../_shared/build-pipeline/quality-gate.md).
• Environment access, developer-script skeletons, custom project-skill skeletons — whichever mechanism the spec chose (../_shared/build-pipeline/env-access.md).
• The design system (UI only) — install the chosen kit + icon set, write the committed root DESIGN.md from the spec and the kit's own theme, and put the UI rule in the project CLAUDE.md.
• The quality tooling the release phase cannot install itself — analyzer, mutation runner, accessibility checker, load tool, whatever dev-architecture named.
• Three records in .dev-skills/project-setup/ (committed): setup-plan.md, setup-log.md, and verification.md — the run/drive/prove contract verify-feature reads.

Language & git

Respond and reason in the user's language — write the plan, questions and reports in it, think in it, and tell any subagent the same. Never translate code, identifiers, paths, commands or tool names. Workflow vocabulary follows ../_shared/glossary.md exactly.

One branch — the current one, normally main. Never create a branch, switch branch, or open a worktree on your own initiative; only an explicit request in this session changes that. Full rule: ../_shared/git-workflow.md.

Modes (read this first)

Read .dev-skills/build-plan/.build-config.md for mode. If absent (standalone run), ask the user once (default interactive) and write the file. Full rules: ../_shared/build-pipeline/build-config.md.

• interactive — present the plan and stop for approval (whole or per-section) before executing.
• autopilot — execute the safe repo-local sections without asking; still confirm global installs / secrets / plugin installs (these always gate, regardless of mode — careful).

Operating principles (non-negotiable)

• Detect before you change. Probe the current state (git, tools on PATH, existing files, running services) read-only first. Never assume a clean machine or a clean repo.
• Repo-local is safe; global is gated. Anything that runs brew/apt/npm -g, writes a secret, or installs a plugin/MCP server stops for explicit confirmation, shown as the exact command.
• Back up before overwrite (<file>.bak, or show a diff and ask) — never blow a file away.
• Trace every action to the spec — each plan item names the component/tool and ADR it comes from.
• Smoke-test, not paper. The environment is "done" only when the one-command bring-up is green and an agent can drive a basic flow against it — not when the files merely exist.
• The gate is enforced, not advisory. A red static gate blocks the commit (pre-commit hook); the build loop gets a scoped test run it can point at a task's paths or tag; the full suite stays in make check for the release pipeline. A project with no way to run a selection forces the loop to choose between the whole suite and nothing — so the scoped target is part of the setup, not an optimization. No turn-end hook. See ../_shared/build-pipeline/quality-gate.md.
• Give the loop the permissions it needs. The agent must be able to read the harness's own output — test results, reports, coverage, the local binaries — without a prompt per file. Write the committed allow/deny block into .claude/settings.json (../_shared/build-pipeline/env-access.md → "Permissions the loop needs").
• Coordinate the shared env. Bake the env-access mechanism into the bring-up command (acquire on make dev, release on make down, lease + stale-reclaim) and/or set up per-run isolation; gitignore the lock file.
• Give the agent symbol-level code intelligence. For each typed language, recommend the matching LSP plugin from the official marketplace (typescript-lsp, pyright-lsp, …) and exclude generated/build/vendor trees via permissions.deny. Config is repo-local (auto-applied); plugin installs are gated. Recipes: references/setup-templates.md §5.
• Keep the project lean and layered — root for the big picture, a short per-package file with commands in a monorepo ( §7).

Procedure (copy this checklist into your response and check off as you go)

- [ ] Stage 0: Intake — load dev-architecture.research.md + architecture.research.md (+ adr/*); read mode
- [ ] Stage 1: Detect state — git, tools on PATH, existing files/config, running services (read-only)
- [ ] Stage 2: Plan — 4 sections (A global installs · B repo scaffold · C AI tooling · D manual-only), each traced → setup-plan.md
- [ ] Stage 3: Approve — interactive: show plan, get approval · autopilot: proceed (global/secrets/plugins still gate)
- [ ] Stage 4: Execute — back up before overwrite, skip what's done, log each; repo-local auto, global/secrets/plugins confirmed
- [ ] Stage 5: Smoke-test — run the one-command bring-up; prove the stack is green and drivable
- [ ] Stage 5b: Design system (UI only) — write root DESIGN.md straight from the spec's design decisions + the installed kit's theme; render one screen to prove it; design-system.md (skip for no-UI / no system)
- [ ] Stage 6: Record — setup-log.md (done/skipped/manual TODO) + verification.md (run/drive/prove commands); hand off

Stage 0: Intake

Read dev-architecture.research.md (the inner-loop design: local-run topology, verification matrix, AI tooling), architecture.research.md (the stack) and adr/*. List: components and their local stand-ins, the one-command bring-up, the seed strategy, the test/verification matrix and its scoped selector, the environment-access model and developer/test scripts, the custom project skills to author, and the AI tooling (MCP servers, plugins, CLAUDE.md content, permissions). If dev-architecture.research.md is missing, say so and offer /design-dev-architecture first. Read the mode.

Stage 1: Detect state (read-only)

Probe without changing anything: is this a git repo? which required tools are on PATH? which target files already exist (.gitignore, CLAUDE.md, .claude/settings.json, compose file, seed scripts, entrypoint)? are any local services already running (ports in use)? Record what exists so later stages skip it.

Stage 2: Plan (four sections, every item traced)

Compose .dev-skills/project-setup/setup-plan.md (template: references/setup-templates.md §1) as a checklist in four sections — (A) global installs (gated) · (B) repo scaffolding (auto-applicable) · (C) AI tooling (config auto, installs gated) · (D) manual-only — each item carrying action · provenance (component/ADR) · reversibility · idempotency note · already-present?. What belongs in each section: references/plan-and-smoke.md.

Stage 3: Approve

• interactive: present the plan grouped by section and get approval — whole, or per-section. Let the user drop or defer items.
• autopilot: proceed with (B) and the config files in (C) without asking; (A) global installs, secret writes, and plugin/MCP installs still stop for explicit confirmation (show the exact command). This gate holds in both modes.

Stage 4: Execute

Apply approved items in order, idempotently: skip anything Stage 1 found already present; back up before overwriting (<file>.bak) or show a diff and ask; run repo-local writes directly; run gated commands only after confirmation. Log each action (done / skipped-already-present / deferred) as you go. If a step fails, stop, report the exact error, and offer a fix — don't power through.

Stage 5: Smoke-test (replaces the spec pipeline's adversarial review)

Run the one-command bring-up and prove it is actually green — the stack starts, the app is reachable, seed data is present, an agent can drive one basic flow and observe a real outcome. Then prove the gate has teeth twice: a deliberate static error makes make check-fast fail and the pre-commit hook block, and make test-scoped SCOPE=… runs visibly fewer tests than the full run. "No error in the logs" is not proof. What each proof looks like and why: references/plan-and-smoke.md.

Stage 5b: Design system → DESIGN.md (UI projects only)

No UI, or Design system / Needed? = no → skip, note it in the setup log. A root DESIGN.md that already exists → leave it alone (idempotent). Otherwise write it directly from the spec — tokens from the installed kit's real theme values or the recorded brand intent — per references/design-md-format.md ("Writing DESIGN.md during setup"), prove it renders on one real screen, and write the design-system.md record. The tokens land under ## Frozen decisions (../_shared/build-pipeline/design-freeze.md). Deviating from the spec's design decisions here is out of scope.

Stage 6: Record + handoff

Write setup-log.md — done, skipped (already present), your turn (which secret/account, and where it goes). Then write verification.md — the concrete run / drive / prove commands per surface, filled in from the now-real stack: bring-up, how to drive UX/Backend/E2E, how to prove an outcome, the three gate commands and what a task's scoped run selects, the dummy-auth token, seed/reset commands, where logs are. This is the contract verify-feature reads. Then hand off — interactive: name the two files and point at /plan-development; autopilot: record the same and hand back.

Close with the «What you should do» block (../_shared/build-pipeline/report-format.md): the manual-only items, one imperative line each.

When the repo already has a working setup

Nothing special is configured for this — it is detect-state-first idempotency doing its job. Three specifics:

1. Probe, then plan the difference. Stage 1 inventories what's present; the Stage-2 plan is (what the inner loop needs) minus (what's already there). Read the CI config too — it often defines the real gate.
2. Fill gaps, adopt & extend — never overwrite. An existing Dockerfile / compose / Makefile is adopted and extended (back up before any edit). The gate wires the existing lint/format/type tools behind the three targets rather than installing new ones. Env-access helper, dev-script and custom-skill skeletons are scaffolded only where absent. verification.md is still written fresh from the now-real stack. A UI project with a kit already installed keeps it, and DESIGN.md is written from its actual theme values.
3. The smoke-test includes the existing gate's honesty. "Green" means the stack comes up via the one command and the gate has teeth — including that make test-scoped really selects. A red pre-existing gate is surfaced, not silently accepted: report it and offer to fix, or file it as a gap for plan-development.

Rules

1. Never run a machine-global install, write a secret, or install a plugin/MCP server without explicit confirmation — in either mode. Repo-local scaffolding may auto-apply.
2. Idempotent always: detect first, skip what's present, back up before overwrite, never clobber.
3. Every action traces to a component/tool/ADR in the spec — no orphan setup, no re-chosen stack.
4. The environment is "done" only when the one-command bring-up is smoke-tested green and drivable.
5. Surface the irreducible manual steps honestly in setup-log.md; never pretend they're handled.
6. Always write verification.md — the build phase depends on it.
7. Install the quality tooling the release phase cannot install itself. Production-side setup — platform, database, caps, telemetry — is not yours: that is setup-production-environment.
8. Stand up the gate in three targets (make check-fast behind the pre-commit hook · make test-scoped SCOPE=… for the build loop · make check for the release pipeline), prove the scoped one really selects, and add no test step to the hook and no turn-end hook.
9. Bake in the env-access mechanism, write the permissions block the loop needs, and scaffold the developer/test-script and custom project-skill skeletons the dev-architecture named — full implementation is backlog work.