Agent Skills: Harness Setup

Harness Setup

The boot stage of the harness. Every other skill's script reads boundary.config.json and assumes it is correct; a wrong config fails silently (shelf_index returns empty, the shelf-check ungrounds, duplication returns). This skill is "parse, don't validate" applied to the config itself: establish a proven config once, so every downstream stage can trust it.

It configures all skills, so it sits above the federation as its installer. Run it before the first feature goes through feature-workflow.

The .harness/ mirror layout (namespaced — required)

When a repo's verify checks reference harness scripts, they are mirrored into a local .harness/ so the project is self-contained. Mirror per skill, never flat: .harness/<skill-name>/<script>.py. This is mandatory because more than one skill ships a scripts/store.py (library-knowledge, specialist-knowledge, mental-models all have their own storage port), and a flat .harness/ would let one skill's store.py clobber another's — silently breaking the other skill's tools. Config and verify commands reference the namespaced path (.harness/library-knowledge/lib_lookup.py, etc.). One obvious home per skill's scripts; no same-named module can collide.

The setup workflow

1. Detect (a PREDICTION, never an assumption)

Run python scripts/config_init.py --repo <path> --skills-root <where skills are installed>. It identifies the substrate from an unambiguous marker file (go.mod → Go, Cargo.toml → Rust, pyproject.toml → Python, package.json → Node/TS, …), then proposes that substrate's conventional layer directories, verify commands, and exclude globs. It writes a draft boundary.config.json with a _substrate field and a confidence report.

The discipline that matters here: detection is a prediction shaped by the tool's defaults, not a fact about the repo. The boundary model (trust, effect, consistency, containment) is universal, but conventions are not, and the failure to avoid is assuming one ecosystem's layout is the universe — guessing TypeScript on a Go repo and writing a confident config for a project that does not exist. So the tool does two honest things: it reports a confidence, and when it cannot recognize the substrate it refuses to default — it writes an explicit UNKNOWN skeleton with FILL markers rather than a disguised guess. If you see SUBSTRATE UNKNOWN or a low confidence, treat the whole draft as a hypothesis to falsify (this is the inquiry faculty: predict the layout, then make the cheapest observation — what marker files and directories actually exist? — that would prove the prediction wrong, before ratifying).

2. Propose & confirm (judgment — the important step)

The draft's layer→directory mapping encodes the repo's architecture, which a detector can only predict. Read the confidence report's REVIEW items and the draft, and reason over the actual repo: does each layer glob point at the directories that really hold that layer (atomic tokens/value-objects, primitives, seams/ports, patterns, pipelines, scaffolds)? Where the repo's conventions differ from the probes, fix the globs. Confirm the mapping with the human — they own the architecture; setup ratifies it, it does not invent it.

Use the substrate model in the feature-workflow skill (references/shelf.md) as the definition of each layer while mapping.

3. Validate (mechanical — the gate)

Run python scripts/config_check.py --repo <path>. This is the doctor: it proves the config resolves against the real repo — every layer glob matches real paths, feature_roots exist, verify commands are well-formed, and any script path referenced in a check actually exists. It fails closed: ERRORs (placeholder paths, missing scripts, invalid globs) must be fixed; WARNs (an empty layer) are reviewed. Do not consider setup done until the doctor exits 0.

4. Record

The validated boundary.config.json lives at the repo root. Then write the repo's agent charter: python scripts/agents_init.py --repo <path> generates AGENTS.md (the loop, the shelf-check rungs, the layer map, the verify gate — all from boundary.config.json, so it describes THIS repo) and links CLAUDE.md to it, so Claude Code and AGENTS.md-convention tools read one source of truth. The harness-owned content sits in a managed block that re-runs regenerate; the "Repo conventions & learnings" section below it is never touched — it is the durable home for the outer-loop ratchet's output.

Optionally wire the gates as hooks for L3 enforcement (the maturity ladder applied to the workflow): config_check and feature-workflow's plan_check as pre-commit, verify as pre-push. Re-run the doctor (step 3) periodically, or in CI, to catch config drift as the repo's structure evolves — stale config is the same dialect-drift failure the workflow warns about, one level up.

When to engage

• Installing the skills in a new repo → run this first.
• A harness script returns empty/wrong results → re-run the doctor; the config has likely drifted from the repo.
• Repo restructured (layers moved/added) → re-detect and re-validate.

Files

• scripts/config_init.py — detect stack + layout, scaffold a draft config, report confidence. (Scaffolds, like plan_new.)
• scripts/config_check.py — the doctor: validate the config resolves against the repo. Fails closed, gate-able. (Validates, like plan_check.) Exit 0 = pass.
• scripts/agents_init.py — write AGENTS.md from the config and link CLAUDE.md to it (the RECORD step's charter). Idempotent; preserves edits outside the managed block.

What this configures

One boundary.config.json at the repo root, read by: layers → feature-workflow/shelf_index.py · feature_roots → feature-workflow/promote.py · verify → feature-workflow/verify.py · include_ext/exclude_globs → boundary-discipline/scan.py and shelf_index.py.