# Setup Engineer

> Reconcile this repository toward the opinionated "golden state" for agentic local development — a per-repo dev CLI, a thin justfile surface, a generated port-offset env contract, a four-file engineer skill, thin CI, and a doctor invariant-enforcer. Run /setup-engineer whenever you want to set up, audit, or repair a repo's local-dev tooling: a fresh repo with nothing, a half-built repo with organic scripts that needs consolidating, or a finished repo you just want to verify still conforms.

- Skill: `niekcandaele/setup-engineer` (Agent Skill, multi-file: 9 files)
- Install (CLI): `npx skillmds@latest add niekcandaele/setup-engineer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/niekcandaele/setup-engineer/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: niekcandaele (https://skillmd.com/u/niekcandaele)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/niekcandaele/setup-engineer

---


# /setup-engineer — Golden-State Reconciler

This command does not "generate documentation." It **reconciles a repository toward a fixed,
opinionated golden state** for agentic local development, then hands ongoing enforcement to a
`doctor` command that lives in the repo. Think of it as `terraform apply` for a repo's dev
tooling: it reads the current world, diffs against the desired world, and closes the gap in
verified phases.

You are the **guardian** of this golden state. Every time it runs, the repo should end up the
same shape — predictable, parallel-instance-safe, self-healing.

## What "golden state" means

A repo is golden when all eight of these are true. The full invariant checklist (the thing
`doctor` enforces) lives in [references/golden-state.md](references/golden-state.md) — read it
before you diff anything.

1. **A per-repo dev CLI** — a *deep module* in the repo's native language (JS repo → JS,
   Python repo → Python). Simple verb surface, all the messy orchestration hidden inside. It
   owns the entire local-dev lifecycle. Spec: [references/cli-and-just.md](references/cli-and-just.md).
2. **A thin `just` surface** — identical verbs across every repo and language, zero logic, each
   line shells into the CLI. This is what makes your muscle memory and the engineer skill
   portable. Template: [templates/justfile](templates/justfile).
3. **A generated env / port contract** — one `ENV_INDEX`, one `DEV_HOST`, a slot table as the
   single source of truth, `BASE + INDEX*100 + slot`, and the in-docker-DNS-vs-host-offset
   boundary law. Spec: [references/env-and-ports.md](references/env-and-ports.md).
4. **A four-file engineer skill** — `SKILL.md` / `ARCHITECTURE.md` / `TESTING.md` /
   `GOTCHAS.md`. Commands-out, why-in. Spec: [references/engineer-skill.md](references/engineer-skill.md).
5. **Thin CI** — workflows call the same `just`/CLI surface and hold ~zero logic. This is both
   reuse and resistance to CI-vendor lock-in.
6. **`doctor` is wired and green** — the in-repo invariant enforcer (a CLI verb) passes, and CI
   runs it.
7. **A tracker binding** — a `TRACKER.md` beside the engineer skill naming this repo's issue
   tracker, its commands, and what its labels mean, so every skill that writes to the tracker
   agrees. Optional: a repo with no tracker worth binding stays golden without it. Spec:
   [references/tracker.md](references/tracker.md).
8. **A dependency binding** — a `DEPENDENCIES.md` beside the engineer skill naming which
   packages this repo treats as riskier than their bump size suggests, which verb proves
   which kind of dependency, and how far an unattended sweep may go. Optional, like the
   tracker: a repo with no dependency bot stays golden without it. Spec:
   [references/dependencies.md](references/dependencies.md).

`setup-engineer` reconciles the **existence and shape** of 1–8. `doctor` enforces the
**invariants** at runtime once the shape exists. Keep that split clear: setup-engineer is the
meta-reconciler that *creates and migrates*; doctor is the in-repo guard that *catches drift*.
setup-engineer runs `doctor` as its final gate.

## The reconciler loop

Run these steps in order. Do not skip the diff and do not big-bang an existing repo.

### 1. Detect

Inventory what exists. Don't assume — look.

```bash
# Identity
basename "$(git rev-parse --show-toplevel 2>/dev/null || pwd)"

# Stack / package manager
ls package.json pyproject.toml go.mod Cargo.toml 2>/dev/null
# Compose + existing env tooling
ls docker-compose*.yml compose*.yml .env .env.example 2>/dev/null
ls scripts/ 2>/dev/null
# Existing command surface
ls justfile Justfile Makefile 2>/dev/null
# Existing engineer skill — check wherever this repo keeps skills
ls -d */skills/*-engineer/ .*/skills/*-engineer/ 2>/dev/null | grep -v '^\.\./'
# Tracker — a binding beside the engineer skill, and evidence of what to bind to
ls */skills/*-engineer/TRACKER.md .*/skills/*-engineer/TRACKER.md 2>/dev/null
git remote -v; command -v gh glab jira 2>/dev/null
# Dependency binding — the same, plus evidence of a bot to bind to
ls */skills/*-engineer/DEPENDENCIES.md .*/skills/*-engineer/DEPENDENCIES.md 2>/dev/null
ls renovate.json renovate.json5 .renovaterc* .github/renovate.json* \
   .github/dependabot.yml 2>/dev/null
# CI
ls .github/workflows/ .gitlab-ci.yml 2>/dev/null
```

Read whatever you find. Existing organic scripts (a `setup-env.mjs`, a `dev-data.mjs`, a
`reset-data.sh`) are not junk to delete — they are the **logic you will migrate into the CLI**.
Read them to learn the repo's real lifecycle before you propose anything.

### 2. Classify

Put the repo in exactly one bucket. This decides how aggressive you are.

- **Greenfield** — no CLI, no `just`, no env tooling, no engineer skill. → Scaffold the whole
  golden state from the per-language template. Low risk; little to break.
- **Partial** — has organic scripts and/or a monolith engineer skill (the most common
  starting point). → **Migrate**, phase by phase, verifying after each. Highest risk; never big-bang.
- **Golden** — already conforms. → Run `just doctor`, report green, stop. Don't churn a repo
  that's already correct.

### 3. Diff

Produce a concrete drift report against the golden-state checklist. For each of the eight
elements, state: present / partial / missing, and the specific gap. Example:

```
CLI            partial   logic lives in 4 loose scripts/*.mjs, no single entrypoint, no `doctor`
just           missing   no justfile
env contract   partial   setup-env.mjs exists but 2 services hardcode host ports in compose
engineer skill partial   1 monolith SKILL.md (33KB) + 3 helper scripts inside the skill dir
CI             partial   workflow reimplements test orchestration inline instead of calling CLI
doctor         missing
tracker        missing   github remote + authenticated gh, but no TRACKER.md
dependencies   missing   renovate.json present, no DEPENDENCIES.md
```

### 4. Plan

Turn the diff into an **ordered, phased** remediation plan. For a Partial repo the order that
keeps the repo working at every step is:

1. **Scaffold the CLI skeleton** (verb surface + `doctor`, delegating to existing scripts at
   first) and the thin justfile over it.
2. **Migrate organic logic into the CLI** one concern at a time (env → lifecycle → data →
   tests), deleting each loose script only once its verb works.
3. **Bring the env/port contract to spec** (slot table as truth, kill hardcoded ports, derive
   boundary URLs) until `doctor` passes.
4. **Restructure the engineer skill** to the four-file floor; move commands out, move scripts
   into the CLI, keep only why/architecture/gotchas.
5. **Thin the CI** to call `just`/CLI.
6. **Bind the tracker** — late, because it touches nothing the earlier phases depend on, and
   because resolving it may need a question the user can answer while the rest is landing.
7. **Draft `DEPENDENCIES.md`** — with the tracker, and after the `just` verbs it points at
   exist, because every command in it has to resolve to a real verb.

Present the plan and get sign-off before applying. This matches the repo owner's standing rule:
multi-phase plans verify at the end of each phase.

### 5. Apply — phase-gated, never big-bang

After **each** phase:

```bash
just doctor      # invariants hold
just test        # nothing broke   (use the repo's real test verb if `just` isn't wired yet)
```

If a phase breaks something, stop and fix it before the next phase. Spawn verification
subagents with the Task tool for the heavier checks (run the full suite, exercise the app) so a
phase isn't declared done on a hunch. Do not delete an organic script until its replacement
verb is green.

### 6. Verify and report

End on a green `doctor` plus the report in [references/report-format.md](references/report-format.md):
what changed, what each phase verified, and any drift left for a follow-up.

## Two behavioral laws you must install

These go into the engineer skill's `SKILL.md` so **every** agent that later works in the repo
follows them ambiently — they are the heart of "guardian / continuous improvement." Full text
and rationale in [references/engineer-skill.md](references/engineer-skill.md).

- **Lifecycle hygiene** — *you brought the environment up, you tear it down when finished.*
  `just down` is the cheap reflex (keeps data, frees RAM so more instances run in parallel).
  This matters most when several agent instances run at once; stale environments eating
  RAM is the failure mode.
- **Self-improvement (executable-encoding-first)** — when an agent fights through friction, the
  fix is routed to the most permanent layer that can hold it: a new `just`/CLI verb > a new
  `doctor` check > a `GOTCHAS.md` note. Prose is the fallback, not the default. This includes
  the **infra-change law**: adding or changing a service (datastore, queue, cache, IdP) means,
  in the same change, adding its port slot + healthcheck + `nuke` volume-coverage + regenerated
  `.env` — and `doctor` fails until all four are true.

## Reference map

| Read this | When |
|---|---|
| [references/golden-state.md](references/golden-state.md) | Before diffing — the full invariant checklist |
| [references/cli-and-just.md](references/cli-and-just.md) | Scaffolding/migrating the CLI + justfile + doctor |
| [references/env-and-ports.md](references/env-and-ports.md) | Working the env/port contract, devbox, HTTPS |
| [references/engineer-skill.md](references/engineer-skill.md) | Restructuring the engineer skill + the two laws |
| [references/tracker.md](references/tracker.md) | Binding the repo's issue tracker into `TRACKER.md` |
| [references/dependencies.md](references/dependencies.md) | Binding the repo's dependency policy into `DEPENDENCIES.md` |
| [templates/justfile](templates/justfile) | The canonical thin verb surface to drop in |
| [references/report-format.md](references/report-format.md) | The final golden-state report |