setup-engineer
/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.
- Author
- niekcandaele ↗
- Repository
- claude-helpers ↗
- Licence
- MIT
- Last repository change
- 27.10.2026
Assessment and security
- Files in this package
- 9
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
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.
Triggers from the description
Original author 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.
How it works
- What "golden state" means
- The reconciler loop
- Two behavioral laws you must install
- Reference map
SKILL.md preview
--- 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. disable-model-invocation: true allowed-tools: - Read - Write - Edit - Bash - Grep - Glob - AskUserQuestion - Task metadata: group: design --- # /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 |
Files in this package (9)
- SKILL.md 10 KB
- references/cli-and-just.md 5 KB
- references/dependencies.md 7 KB
- references/engineer-skill.md 6 KB
- references/env-and-ports.md 5 KB
- references/golden-state.md 6 KB
- references/report-format.md 1 KB
- references/tracker.md 5 KB
- templates/justfile 3 KB
Versions
The database has no other skills named setup-engineer.
Database snapshot: 13.11.2026 · package version d80ecfb4efc5 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 90setting-up-just
Set up a repo-local just task runner with a root Justfile, optional .just/ helper scripts, and curated help, build, fmt, lint, test, and ci recipes. Use when a repo needs just, a Justfile, .just helpers, or when the user mentions task automation, "just build", "just lint", "just… - 100just
Reference for `just`, the command runner. Use when working in a project with a `justfile` or when the user mentions `just` or `justfile`. - 100cli-just
Use for just/justfile task automation: create justfiles, write recipes, configure settings, add modules/attributes, or set up command-runner workflows. - 95justfile-style
Style guidelines for justfile recipes, extracted scripts and configuration, documentation, and dependencies. Use when writing or editing justfiles. - 100justfile-author
Use this skill when authoring or refactoring a justfile (and matching Makefile wrapper) for one of Nick's projects. Triggers when the user asks to "create a justfile", "add a justfile to this project", "set up just for…", "wire up tmux services", "scaffold the task runner", or… - 100configure-justfile
Check and configure Justfiles with standard recipes. Use when setting up a Justfile, auditing for missing recipes, or migrating from Makefile to Justfile.