| name | setup-engineer |
| description | 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. |
/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 six of these are true. The full invariant checklist (the thing
doctor enforces) lives in references/golden-state.md — read it
before you diff anything.
- 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.
- 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.
- 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.
- A four-file engineer skill —
SKILL.md / ARCHITECTURE.md / TESTING.md /
GOTCHAS.md. Commands-out, why-in. Spec: references/engineer-skill.md.
- Thin CI — workflows call the same
just/CLI surface and hold ~zero logic. This is both
reuse and resistance to CI-vendor lock-in.
doctor is wired and green — the in-repo invariant enforcer (a CLI verb) passes, and CI
runs it.
setup-engineer reconciles the existence and shape of 1–6. 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.
basename "$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
ls package.json pyproject.toml go.mod Cargo.toml 2>/dev/null
ls docker-compose*.yml compose*.yml .env .env.example 2>/dev/null
ls scripts/ 2>/dev/null
ls justfile Justfile Makefile 2>/dev/null
ls .claude/skills/*-engineer/ 2>/dev/null
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 (this is the akari/takaro
case). → 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 six
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
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:
- Scaffold the CLI skeleton (verb surface +
doctor, delegating to existing scripts at
first) and the thin justfile over it.
- Migrate organic logic into the CLI one concern at a time (env → lifecycle → data →
tests), deleting each loose script only once its verb works.
- Bring the env/port contract to spec (slot table as truth, kill hardcoded ports, derive
boundary URLs) until
doctor passes.
- Restructure the engineer skill to the four-file floor; move commands out, move scripts
into the CLI, keep only why/architecture/gotchas.
- Thin the CI to call
just/CLI.
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:
just doctor
just test
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:
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.
- 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 because the repo owner runs many headless instances 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
