# Setup Dev Environment

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

- Skill: `a-v-ershov/setup-dev-environment` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add a-v-ershov/setup-dev-environment`
- Raw SKILL.md: https://api.skillmd.com/api/skills/a-v-ershov/setup-dev-environment/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: a-v-ershov (https://skillmd.com/u/a-v-ershov)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/a-v-ershov/setup-dev-environment

---


# 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 `CLAUDE.md` lean and layered** — root for the big picture, a short per-package
  file with *scoped* commands in a monorepo (`references/setup-templates.md` §7).
- **Minimal, proven infra.** Bring up exactly what the spec says; never reproduce production scale/HA
  locally or add tooling the spec didn't choose.

## 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.