/plumb-line-bootstrap

name: plumb-line-bootstrap
description: Use when setting up a project with the plumb-line discipline — interviews the builder to find their source-truth layer and layering, generates a domain-neutral ruleset, and installs parameterized enforcement (boundary check, test gate, pre-commit gate, branch guard) for the project's language. Ships no default layers and invents no answers.

Bootstrap a project with plumb-line

Part of the five-skill flow: find your fit with `plumb-line-adopt`, learn the discipline with `plumb-line-method`, set the project up here, review changes with `plumb-line-audit`, and apply findings with `plumb-line-remediate`.

REQUIRED READING FIRST: `reference/portable-principles.md` and `adapters/adapter-contract.md` (plugin root). If either file cannot be read, stop immediately and report which file is missing. Do not proceed from memory.

Two entries: full bootstrap vs. declaration-only (mid-audit)

This skill has two entry modes. **Full bootstrap** — the builder asked for setup — runs every step below. **Declaration-only** — `plumb-line-audit` invoked this skill because the project declares no architecture and the audit needs that context before proceeding — runs a deliberately two-minute detour:

• Ask ONLY interview questions 1–3 (layers + direction; source-truth layer;

composition root). The audit needs the declaration, not the ceremony.

• Write the ruleset from those answers (Step 3), marking every section the

interview did not reach as `planned` — an un-asked question must not read as an answered one.

• Skip Step 4, Step 4b, and Step 6's audit offer entirely: no enforcement

install, no primitive offer, nothing added to the project beyond the ruleset file. Those belong to a full bootstrap run — name it as the follow-up in the report's TODOs.

• Emit the Step 5 report header with one extra line — `entry: declaration-only`

— then return the baton: the calling audit resumes with the freshly declared architecture (do not start a second audit).

The honesty constraint applies in both modes: if the builder cannot name a source-truth layer, stop and say so — in declaration-only mode that answer goes back to the audit, which then proceeds calibrated with the gap on record.

Step 1 — Detect language, pick the adapter

• Look for `package.json` -> JS adapter (`adapters/js`).
• Look for `pyproject.toml` / `setup.py` / `requirements.txt` -> Python adapter (`adapters/python`).
• If both or neither, ASK the builder which to use. Never guess silently.

Step 2 — Interview (one question at a time)

Ask the find-your-version prompts from the principles, in this order (ask one, wait for the answer, then proceed). Do NOT supply defaults; these answers are the builder's, not yours:

1. Layers, top to bottom, and the one-way direction. 2. The source-truth layer, and what must never leak into it. 3. The one allowed exception (composition root), if any. 4. What flows downstream (gets provenance + confidence). 5. Where non-real (mock/fallback/cached) data is used. 6. Which constants encode judgment calls (priors to lift to config). 7. Public output shapes that need a versioned contract. 8. For each key output, the inputs needed to reproduce it. 9. Which derived outputs to freeze as a golden baseline. 10. The phrasing for a valid null result in this domain. 11. On branches that are not protected, should the pre-commit gate run the tests (`"run"`: a failure is reported, not blocked) or skip them (`"skip"`)? A protected branch always runs them and blocks on failure. Recommend `"run"` when the project has no CI, since nothing else would run them before review. Write the answer into `branch-guard.json` as `testsOnOtherBranches` (Step 4).

HONESTY CONSTRAINT: if the builder cannot name a source-truth layer, stop and say so — that absence is the finding. Do not fabricate one.

Step 3 — Generate the ruleset

Fill `reference/ruleset-template.md` placeholders with the answers; write it to the target repo as `AGENTS.md` (or append if one exists — never overwrite silently).

Step 4 — Install enforcement (from the chosen adapter)

• Copy the boundary config template, replacing layer placeholders with the

builder's layers/direction. (JS: eslint zones; Python: import-linter layers.)

• Copy the guard hook scripts into the target repo's `.claude/guards/` (or

hooks dir): the branch guard, its commit-hook wrapper (`branch-guard-commit.mjs` / `branch_guard_commit.py`, which imports the guard) and the pre-commit gate (which imports the wrapper), all three in the same directory.

• Wire git's pre-commit hook to run the wrapper, then the pre-commit gate with

a test command (see *Hook I/O contract* below). Advise a fast one for the gate, such as the unit tests, and leave the full suite to CI: the gate runs it on every commit to a protected branch, and on every commit with `testsOnOtherBranches` `"run"`. Keep in that fast subset the audits-clean test and the provenance lint that ride the command (Step 4b items 4–5, Step 4c), or the gate stops running them.

• Tell the builder exactly what was written and how to enable the hooks, and

what the gate does not guard: a commit allowed on another branch, unchecked or red, can still reach a protected branch by a local fast-forward or a clean merge, which runs no pre-commit hook. CI and branch protection guard that route.

• **Verify, don't assume.** After installing, plant a deliberate upward import

and confirm the boundary check errors; on the protected branch, run a code path through the branch guard's installed wiring (the hook command itself, so the branch it sees is the one the wiring supplies) and confirm it blocks, then a docs-allowlisted path the same way and confirm it passes. Feed both as the host sends them (for Claude Code, a PreToolUse payload with an absolute `tool_input.file_path`), or the docs check cannot catch a path the wiring failed to make repo-relati