env-init

# env-init Stand up a project as a harness **environment**. You are an autonomous installer: you write the artifacts end-to-end, explain the *significance* of each as you go, and gather everything onto a `feature/env-init` PR the human reviews and merges. You are the second half of a two-command setup, and the split is the point — it is harness engineering in miniature: - **`context-specs add <path>` already ran** (deterministic CLI, tier 1): it registered this environment with the harness repo, symlinked the canonical skills/agents into `.claude/` (gitignored), and wrote the managed `.gitignore` block. Everything a script can do without reading the project, a script did. - **You do what needs judgment** (Software 3.0, tier 2): every artifact below requires *reading this project* — its manifests, README, CI, conventions. Scan, generate, cite the evidence. **Never invent a command you didn't see evidence for** — ask instead. The tier test, if you're ever unsure what belongs to you: *could this be written without reading the project's code?* Yes → it's the CLI's/harness repo's, leave it alone. No → it's yours to generate here. ## Operating mode Run the steps end-to-end without stopping for per-step approval — **the user reviews everything in the `feature/env-init` PR.** Your job while installing is to explain *significance*: for each artifact, one or two sentences on what it is, why it exists, and what would break without it. Lead with the why, then write the file. Read first: `references/mental-model.md` (so you can explain what the harness *is*) and `references/invariants-to-preserve.md` (the rules nothing you generate may break). Load other references as each step needs them. **Stop-and-confirm points — the only interruptions:** 1. **Secret-copying** (bootstrap step) — before writing any `cp` line that touches a `.env` or credentials file: name the exact files, confirm copy direction (source → worktree, never reverse, never delete), get explicit consent. 2. **Reviewer choice** — wires CI and billing; the user's call. 3. **The PR merge** — after the PR opens, stop and wait for the human. ## Preconditions - Run in the **developer's checkout** of the environment, on `main`, clean tree, `origin` remote. - `context-specs add` has run: `.claude/skills/` contains symlinks into the harness repo (you are reading this SKILL.md through one). If it hasn't, stop and have the user run it first; `context-specs doctor` diagnoses. --- ## The install chain ### Step 1 — Config (`.harness/env`) Read `references/config-options.md`. Write `.harness/env` from `assets/harness-env.template` with the defaults (`MAX_WORKTREES=1`, per-dev `WATCH_PATTERN` derived from `git config user.email`) unless the user has a concrete reason otherwise. This file is **committed** — it is the environment's project-owned dial on the tier-1 dispatcher. Runtime counters live in the harness repo's `state/<env>/`, so there is nothing to gitignore here. ### Step 2 — Install `/intent` (project-owned, one of the two levers) `/intent` is deliberately **not** symlinked like the other skills — it is a committed, project-owned artifact, because *how well this project expresses intent is one of the biggest levers it has*. Frame it exactly that way to the user: **/intent and the Expert are the two developer-owned levers** — /intent shapes what goes *into* every feature (the PRD + runnable definition of done), the Expert shapes what every feature *knows*. Developers should expect to tune both over time. Copy the canonical template from the harness repo: `$CONTEXT_SPECS_HOME/skills/human-loop/intent/` → `.claude/skills/intent/` (SKILL.md + references/). (`CONTEXT_SPECS_HOME` = the symlinks' target root: `readlink .claude/skills/spec-planning` and strip `/skills/...`.) Then offer the choice: - **Generic (fine to start):** install verbatim; customize later by editing — it's the project's file either way. - **Customized now:** scan the repo and tailor the marked hackable seams — `references/prd-template.md` (project DoD conventions: what can `run-prd-test.sh` actually exercise here — e2e harness? LLM-judge hybrid?), `references/elicitation.md` (domain vocabulary, the questions this project's features always end up needing), `references/runner-recipes.md` (this project's test idioms). Cite the scan evidence for every tailored line. ### Step 3 — Seed the Expert (long-term memory) skeleton Copy `assets/expert-skeleton/` → `.claude/skills/expert/`. Structure only — empty routing table, no invented content: shards are added by `/learn` (post- merge), by the implementer's Reflect step (post-slice), **and by the developer directly**. Narrate the ownership model loudly; it is the heart of the system: the Expert is the project's long-term memory, and **the developer owns it**. The loops are continuous helpers that file things into it; editing it directly is expected, not exceptional. Long-term memory informs short-term memory — every `/spec-planning` run reads this to plan the next feature — so improving a shard improves every future feature. The skeleton's conventions (one topic per shard, prefix names, `USE WHEN:` openers, routing table inline in SKILL.md) exist so a weak plan can be traced back to the specific shard that should have taught it. ### Step 4 — `AGENTS.md` (Software 3.0) Read `references/agents-md-guidance.md` and `references/project-discovery.md`. Scan the repo, fill `assets/AGENTS.md.template`'s bracketed parts (project name, the verification-layer tooling), keep the rest verbatim. AGENTS.md is the neutral, eagerly-loaded contract — a map that points into the Expert, not an encyclopedia; keep it tight (~150 lines). Cite the scan finding behind each filled-in line. The Expert section is intentional even while the Expert is a skeleton. ### Step 5 — `scripts/local-checks.sh` (optional, Software 3.0) The deterministic gate the dispatcher runs before opening a PR (two-strike: `local-checks.sh fix` → `/fix-local-checks` → STUCK). Cheapest place to catch correctness issues — left of the reviewer and CI. **Read `references/local-checks-design.md` first** and narrate the *why*; the user owns and tunes this script. Two responsibilities: - **Wire the project's deterministic checks** — lint/format (with a `fix` subcommand), typecheck, the **fast** unit suite (slow/integration → CI), a **skip-detection** check, and everything in `scripts/lints/`. Prefer commands the project already defines. - **Propose custom correctness lints** from the codebase as-is (snapshot discovery), behind the five guards in the reference. The gate proves **correctness, not coverage** — block only what the project **decided** (correctness, plus structure the user opts into), warn on undecided taste. The **skip rule** is load-bearing: an agent may never add a test-skip marker; a legitimate skip is the human's call at STUCK. If the project has no deterministic checks, skip this step — the dispatcher treats the script as absent and works fine. ### Step 6 — `scripts/bootstrap-worktree.sh` (Software 3.0 below the line) Read `references/worktree-bootstrap.md`. Generate from `assets/bootstrap-worktree.template.sh`, whose **deterministic header is verbatim and untouchable**: it calls `context-specs link` so every fresh worktree gets the tier-1 skill symlinks (gitignored symlinks never materialize in new worktrees — without this line, every headless step would run skill-less). The dispatcher exports `CONTEXT_SPECS_HOME` when it calls this script, so nothing machine-specific is committed. You generate only the section **below the marker**: copy gitignored runtime files, install dependencies, run codegen — discovered from README/CI/manifests (`references/project-discovery.md`); if discovery is thin, ask the user how they set the project up on a fresh machine. Idempotent, non-interactive, well-commented. **The secret-copy lines are stop-and-confirm point 1** — see Operating mode. If the project has no gitignored secrets, skip that part and say so. ### Step 7 — Reviewer (stop-and-confirm point 2) Read `references/reviewer-options.md`. Three paths (self-hosted via `claude-code-action` = recommended default; managed Code Review; none); switching later is cheap. **Present the paths, recommend self-hosted, and confirm — including auth — before configuring anything.** - **Self-hosted:** copy `assets/REVIEW.md` → repo root and `assets/workflows/claude-review.yml` → `.github/workflows/`, then: 1. **Pick auth with the user:** subscription (`CLAUDE_CODE_OAUTH_TOKEN` from `claude setup-token`) vs metered API (`ANTHROPIC_API_KEY`). Uncomment the chosen line, have them add the matching repo secret. 2. **Pin the action** to the current release tag (`gh release view --repo anthropics/claude-code-action`). 3. **Tell them the v1 same-content rule:** the workflow only takes effect once merged to `main`; it can't be tested from a feature branch. - **Managed:** copy `REVIEW.md`; give the GitHub App install instructions. - **None:** create nothing; set `REVIEW_CLEAN_MARKER=` (empty) in `.harness/env` so the dispatcher converges at PR-open. **Convergence marker (both reviewer paths):** `REVIEW.md` instructs the reviewer to post a PR comment containing `HARNESS_REVIEW_CLEAN` once no Important findings remain; the dispatcher sees it and hands the PR to the human for `/evaluate-pr`. Configurable via `REVIEW_CLEAN_MARKER` (must match REVIEW.md). If the reviewer never posts it, the feedback loop STUCKs at `FEEDBACK_CAP` instead — a clean PR the human merges. ### Step 8 — Commit on `feature/env-init`, push, open PR, wait for merge **Hard rule: never commit setup artifacts directly to `main`.** Everything from Steps 1–7 — plus the `.gitignore` block `context-specs add` wrote — lands on `feature/env-init` and reaches `main` only via a merged PR: the whole install in one reviewable diff. ``` git checkout -b feature/env-init git add .harness/env .gitignore scripts/ AGENTS.md REVIEW.md .github/ \ .claude/skills/intent .claude/skills/expert git commit -m "harness: environment setup via env-init" git push -u origin feature/env-init gh pr create --base main --head feature/env-init \ --title "harness: environment setup" --fill ``` (The symlinked skills are gitignored and stay out of the diff — that's the tier split showing up in git: canonical stays in the harness repo, project-owned gets committed here.) Walk the user through the PR, then **stop and ask them to merge before continuing (stop-and-confirm point 3).** Why merge first: the dispatcher works entirely through `origin` — it claims PRDs from origin refs and creates worktrees from `origin/feature/*` branches that fork off `main`. Until this merge lands, those branches would contain none of these artifacts (no `.harness/env`, no bootstrap, no Expert), so the first feature would run against an unconfigured project. ### Step 9 — Prove the wiring, then hand off to the CLI Once merged (`git fetch && git pull`), have the user run, from the harness repo: ``` context-specs doctor # every check green for this environment context-specs run <env> # one foreground tick: fetch, find nothing, exit idle ``` A clean no-op `run` proves the whole chain — registry, dispatcher, config, worktree base — without doing any work. **Then offer to seed long-term memory (recommended).** The Expert installed in Step 3 is an empty skeleton, and an empty Expert means every spec plan starts from zero — it's the biggest lever on plan quality. Ask the user (AskUserQuestion): *"Seed the initial long-term memory now? (recommended)"* with options **Seed now (recommended)** / **Later**. - **Seed now** → invoke `/improve-context` in this session with this steering: *"The user just initialized this environment and the Expert is empty. Explore the codebase, then interactively help them write the initial long-term memory — architecture concepts, key how-tos, hard invariants, and any direction the team already knows."* - **Later** → include in the handoff below, plainly: run `/improve-context` soon — an empty Expert means every plan starts from zero. Then the daily flow: ``` context-specs start <env> # background supervisor: build loop + memory loop ``` 1. **`/intent`** in this checkout → confirm a PRD → walk away. The harness picks it up (a tick that advances work re-fires immediately — real work drains at machine speed; idle ticks nap the interval). 2. Either: the reviewer converges → the harness posts **"Ready for your review"** with the build-session trail → run **`/evaluate-pr <feature>`**, understand it, merge. Or: a step hits its cap → **STUCK** post on the PR. Run **`/improve-context <feature>`** — it walks you through the diagnosis-first flow (context defect before code fix) so you don't have to hold the machinery in your head. 3. After each merge, the memory loop raises a `learn/<sha>` PR — the project updating its own long-term memory. Review it with the same care as code: it decides what every future feature knows. `context-specs status` shows every environment's features and phases; `context-specs logs <env> -f` follows the loop. --- ## Inner skill dependency The dispatcher invokes `/spec-planning`, `/spec-validate`, `/implement-mainspec`, `/fix-local-checks`, and `/address-feedback`; the memory loop invokes `/learn`. All arrive as symlinks from the harness repo via `context-specs add` — verify they resolve (`context-specs doctor`). Three are **human-invoked**: `/intent` (installed by Step 2 as project-owned), `/evaluate-pr`, and `/improve-context`. env-init generates the project-specific artifacts; it does not author skills. ## Re-running Safe to re-run. For canonical files (REVIEW.md, workflow, the bootstrap header), diff and offer to update. For generated files (`AGENTS.md`, `local-checks.sh`, the bootstrap body, /intent customizations), re-scan and show a diff rather than overwriting blind. Never overwrite the Expert's references/ — that is live memory now, not yours. If `feature/env-init` already exists from a prior run, update that branch rather than creating a fresh one. ## Hard rules (from invariants-to-preserve.md) - Never generate an LLM call into the dispatcher's decision path (Invariant 5). - Never replace the atomic-rename claim with a marker/lock file (Invariant 2/7). - Never generate a "go backward" / sentinel-deleting step (Invariant 9). - `bootstrap-worktree.sh` copies secrets source→worktree only, never deletes, never the reverse (Invariant 6) — and its `context-specs link` header stays. - Never commit setup artifacts directly to `main` — everything rides the `feature/env-init` PR (Step 8).