What the harness installs

The 60-second version

Two ideas explain the design

1. The rules live in the repo, not on anyone's machine. Clone it and you have everything — the same guardrails, AI crew, and checks as every teammate.
2. Enforcement happens twice. The .claude/ files stop the AI on the developer's machine, early and cheaply. The pull-request checks stop everyone at the server. The AI can't skip the first; nobody can skip the second.

How the install is assembled

The installer builds each repo's copy in layers. Every layer may add to or replace what came before, so the most specific layer wins:

1. core             the neutral standard — identical everywhere
2. stack pack       how we build in this technology        (from the profile's language)
3. CI/CD pack       which platform runs the checks         (from the profile's platform)
4. frontend packs   for repos with screens: a generic UX layer, then the framework's (react, angular)
5. tools packs      optional tools the team opted into     (from the profile's tools list)
6. customer profile one company's standards (coverage bar, compliance)
7. repo adaptation  the repo's own edits during setup — owned by the repo from then on

If a layer doesn't exist yet for a given choice — say, a language with no pack built — setup installs the neutral core for that piece and says so. It never fails for lack of a pack.

CLAUDE.md — the working agreement

Every AI session in the repo starts by reading this file: how the team works, the coding standards for the stack, what the project's words mean. That's why the AI behaves the same for every developer — everyone's sessions start from the same page.

It's assembled at setup from the standard's base, the stack's coding standards, and the customer profile. The repo owns it from then on.

settings.json — the three buckets

Everything the AI could do falls into one of three buckets:

• Do freely — building, testing, reading history. Safe, reversible, no nagging.
• Ask first — pushing code; touching login/security code, database migrations, infrastructure, or the checks themselves. A human clicks yes in the moment.
• Never — force-pushing, wiping work, piping downloads into a shell, reading secrets files. Refused outright.

Two details worth knowing: a developer's personal settings can loosen "do freely" for themselves, but can never cancel a team "never" — hard limits are team property. And the AI changing its own guardrails is itself an ask-first action.

hooks/ — the barriers

A written rule like "always review before pushing" is exactly the kind of thing that gets forgotten under pressure. So these rules aren't written — they're machinery:

• The done-gate. The AI cannot end its work turn while the build is broken — the turn is refused and the errors are handed back. Documentation-only turns skip the build.
• The ship-gate. The AI cannot push code until the required reviews provably ran against the exact version being pushed. Change the code afterward and the evidence no longer matches — the gate demands a fresh review. No "I reviewed it earlier, trust me."

If the environment is broken (a tool missing), the hooks warn and step aside rather than trapping the session. If the code is provably broken, they block.

agents/ — the AI crew

Six specialists the AI can hand work to. Each starts with fresh eyes — it sees the code and the requirements, not the reasoning that produced the code. That's what makes its review honest.

Only the two automatic ones arrive uninvited — they cover the two situations where forgetting to ask is the real risk.

skills/ — the runbooks

Standard procedures the AI follows when the situation matches. The rules they lock in:

• No spec, no build — a feature starts as a written spec with checkable acceptance criteria.
• A bug fix starts with a failing test — reproduce first, fix second, prove third.
• Tests explain why — every test maps back to a requirement.
• New code follows the house pattern — find how this codebase already does it and copy that.
• PRs tell the reviewer what to check — the change mapped to requirements, with a test plan.
• AI-powered features get a fixed test suite before they're built.

Each runbook can only use the tools its job needs — the spec writer, for example, can't run commands at all.

.mcp.json — the shared plug-ins

Plug-ins give the AI extra abilities. This file is the team's shared set: open the repo once, approve the list once, and they're simply there — the same for every developer.

Personal plug-ins stay in your own machine's config — this file is only for what the whole team should share. Tools that install themselves (like GitNexus) come with printed instructions instead.

The pull-request checks — workflows/

These run at the server and apply to every change, no matter who or what wrote it. The principle: work can be proposed by anyone; only a gate lets it through.

On top sits branch protection: the blocking checks are mandatory, and a person who didn't write the change must approve it. In one sentence: machines verify the facts; a human makes the call.

Where the pieces come from

delivery-standard/kit      the source of truth (this repo)
        │  sync_kit.py
claude-code-sdlc/harness   the plugin's bundled copy — generated, never hand-edited
        │  install_harness.py --profile
product repo               composed core + packs, then adapted during setup

After install there is no live link back — nothing upstream can change a client repo behind its back. Updating is deliberate: update the plugin, run /sdlc-upgrade. The install receipt (.claude/harness-manifest.json, written at install with a fingerprint of every file as installed) keeps it safe: untouched files come forward, adapted files are left alone, and files changed on both sides are reported for a deliberate merge. Nothing is silently overwritten.