Golden path: a harness template repo (Phase 8)

The final phase of the Harness Engineering series: package everything built across phases 0–5.5 into a forkable template repo. The harness stops being an artisanal per-project build and becomes a golden path. What goes in the template with project-specific cleanup (AGENTS.md / CLAUDE.md with stubs, the ExecPlan template, an ADR _template, environment.md with an EMPTY tool-selection table, deterministic-check configs as TODO templates, GC jobs as tool-agnostic contracts, only the universal .claude/skills/), the migration capsule (the portable mechanism + a curated _core vs project-bound noise), HOW_TO_FORK.md with a 2–3 day estimate, and the "living fork" horizon — a shared harness-kit. Stack- and infra-agnostic, with a copyable fork skeleton.

AdvancedAI DevOps20 mintemplate repo, git, AGENTS.md, ADR, CI

Why a template: capture-once, reuse-everywhere

In every prior phase you assembled the harness for one specific repository: the audit, AGENTS.md, ExecPlan, barriers, GC, the lessons-ledger. So far it's an artisanal build: each new project starts from scratch, and someone re-remembers that AGENTS.md exists, that an ADR has a template, that barriers hang on pre-commit and CI. Phase 8 solves exactly this — capture-once, reuse-everywhere. The harness stops being a one-project artifact and becomes a golden path: the default route a new project takes without reinventing the structure. The goal is measurable, and you should phrase it that way: 'time from a new project's start to the first PR an agent makes by the harness rules'. Without a template that's weeks; with a proven template it trends toward < 1 day on a simple stack and 2–3 days on a non-trivial one. That's the phase's DoD in one line: the template repo exists, is forkable, and deploys on a new project independent of its stack and infrastructure. A key mindset shift: you're packaging not 'a finished harness' but the skeleton plus the mechanism for growing it. A harness is never finished — it accrues. The template gives a new project the right shape from day one, not its final content.

🟥 Artisanal per-project build

Every project starts from scratch
People re-remember AGENTS.md even exists
Start-to-first-agent-PR — weeks

🟩 Golden path (template)

Fork the skeleton — the structure is already there
Capture-once: the growth mechanism is built in
Start-to-first-agent-PR → < 1 day / 2–3 days

The phase metric is not 'how many files the template has' but 'time to the first agent PR by the rules'. If a fork doesn't cut that time, the template is bloated: configs baked for someone else's stack only get in the way, because the new project still starts by cleaning them out.

What goes in the template (with stubs and TODOs, no baked choices)

The template's contents are a slice of every phase, cleaned of project specifics. Context engineering: AGENTS.md and CLAUDE.md where the name, domain and layers are replaced with <PROJECT_NAME> stubs; the rollout doc HARNESS_ROLLOUT.md WITHOUT a filled Progress (the new project keeps its own); the ExecPlan template for long tasks; an ADR _template plus a README in docs/decisions/ explaining how to open ADRs. The phase's core principle is being stack- and infra-agnostic. So environment.md ships as a TEMPLATE: that same role→tool tool-selection table, but with EMPTY rows. The new project picks tools on ITS OWN Phase 0 — here we don't re-teach how to do that and don't bake in someone else's choice (for how, see the project-audit recipe, which owns the role→tool table). Likewise the deterministic-check configs (boundary linter, type-check, dead-code) ship as TODO templates, not ready configs for one stack: 'here's the role and the shape, your Phase 0/3 fills in the tool'. The GC jobs ship as tool-agnostic contracts: one 'what we do' (a check PRODUCES an artifact — a PR/issue/updated MD) plus a couple of implementation examples for popular schedulers. Into .claude/skills/ go ONLY the universal skills (opening an ADR, the ledger's normalize/maintain) — project-specific SKILL.md files stay behind. And CONTRIBUTING.md with an agent section: how the agent works in this repo.

Template contents (stubs / TODOs / universal only)

AGENTS.md + CLAUDE.md with <PROJECT_NAME>, domain and layer stubs

HARNESS_ROLLOUT.md WITHOUT a filled Progress + the ExecPlan template

ADR _template + a docs/decisions/ README

environment.md as a TEMPLATE: tool-selection table with EMPTY rows

Barrier configs — as TODO templates, not ready for one stack

GC jobs — a tool-agnostic contract + a couple of scheduler examples

.claude/skills/ — ONLY universal skills + CONTRIBUTING.md (agent section)

Baking a ready eslint/mypy config and a filled table for one stack

A per-file cleanup rule: 'is this about the mechanism or about this project?'. Name, domain, layers, chosen tools, a filled Progress — strip to a stub/TODO. The document's shape, its sections, a check's contract — keep. A baked foreign choice is worse than an empty row: it gets silently inherited as fact.

The migration capsule: the portable mechanism vs project-bound context

The subtlest part of the phase is what exactly to carry into a new project. There are two classes of content, and they must not be mixed. Portable is the MECHANISM common to any repo: the prompts (the ledger's normalize / maintain), the /wrong command, the retrieve rule, the Definition of Done, the ADR template — and a curated set of portable lessons in _core/. Project-bound is everything tied to THIS repo's modules and contracts: lessons like 'in our persistence layer we load it this way', specific boundaries, service names. In a new project such lessons are pure noise: they describe code that isn't there, and the agent will 'apply' rules for things that don't exist. Hence the definition of migration: fork the SKELETON (the mechanism) plus the curated _core, NOT the whole ledger. _core is a capsule of portable lessons that hold on any project of this class; the portable/project-bound split and _core itself are introduced by the lessons-ledger recipe — here we don't re-explain the ledger's mechanics, we use its distinction. The _core curator picks literally a handful of lessons: 'a small core that's true everywhere' beats 'we moved the whole notebook and buried the new project in foreign context'.

🟩 Portable (the mechanism)

normalize / maintain prompts, the /wrong command
the retrieve rule, the DoD, the ADR template
curated _core: lessons true on any such project
Travels into the fork — this is the golden path

🟥 Project-bound (the context)

Lessons about THIS repo's modules and contracts
Specific boundaries, service names, the domain
Describes code the new project doesn't have
Stays behind — in a new project it is noise

A one-line _core test: 'is this lesson true on ANY project of this class, or only on this one?'. Any → _core. Only this → leave it in the source repo. When in doubt — do NOT carry it: a stray project-bound lesson in the fork costs more than a missing portable one, which you can always add later by hand.

HOW_TO_FORK.md: fork, upstream, what to customize on day 1

A template is useless without a fork guide — otherwise everyone deploys it their own way and the golden path diverges. HOW_TO_FORK.md answers four questions. First: how to fork the skeleton into the new project's repo (and take the curated _core, not the whole ledger). Second: how to pull upstream when the template itself updates — rebase/merge the mechanism changes (prompts, the ADR template, _core) without clobbering the project's local layer. Third: what to customize on day 1 versus later. Day 1 is unlocking the agent: fill the <PROJECT_NAME> stubs in AGENTS.md, run Phase 0 (baseline.md + environment.md with REAL tools for the stack), turn on the 1–2 cheapest barriers. Later: the rest of the barriers, the GC schedule, populating the ledger. Fourth: the honest 2–3 day estimate to the state where the agent makes its first PR by the rules. Below is a copyable HOW_TO_FORK.md skeleton, generalized and stack-agnostic: drop in your Phase 0 tools. It's not 'all the setup at once' but the minimal path to agent-ready, plus an explicit list of what's deferred.

Fork the skeleton + curated _core

Day 1: <PROJECT_NAME> stubs, Phase 0

Turn on 1–2 cheap barriers

2–3 days

First agent PR by the rules

accrues

Later: GC, the rest of the barriers, the ledger

# HOW_TO_FORK.md  (generalized, stack-agnostic — fill in YOUR Phase 0 tools)

## 0. Fork
- Fork/clone this harness template into the new project's repo.
- Take the SKELETON + curated lessons/_core/ ONLY. Do NOT copy a source
  project's full ledger or its project-bound lessons.

## 1. Day 1 — unlock the agent (target: first agent PR in 2–3 days)
- [ ] Replace every <PROJECT_NAME> / <DOMAIN> / <LAYER> stub in AGENTS.md + CLAUDE.md.
- [ ] Run Phase 0 (see the project-audit recipe): write baseline.md and fill
      environment.md — the role->tool table with REAL tools for THIS stack.
- [ ] Turn on the 1-2 cheapest barriers (formatter + one boundary/type check)
      on pre-commit + CI. One real barrier beats a perfect plan.
- [ ] Open ADR 0001-tool-selection from the _template (records the choices above).

## 2. Later — let the harness accrue (do NOT do all of this on day 1)
- [ ] Remaining barriers from the role table (Phase 3).
- [ ] GC schedule: wire the tool-agnostic job contracts to your scheduler (Phase 5).
- [ ] Start the ledger: enable /wrong; lessons accrue from real corrections.

## 3. Upstream updates (the template is a living dependency)
- The template ships MECHANISM (prompts, ADR _template, _core, DoD).
- To update: rebase/merge upstream into your fork; resolve so the MECHANISM
  advances and your LOCAL project layer (filled AGENTS.md, your ADRs, your
  lessons) is preserved. Never let an upstream pull overwrite local context.

# Honest estimate: simple stack -> ~1 day; non-trivial -> 2-3 days to agent-ready.
# This is a STARTING POINT, not a finished harness. The rest accrues over time.

Don't configure everything on day 1. The fork's goal is to unlock the agent (a filled AGENTS.md + 1–2 barriers + Phase 0), not to run every phase at once. A full rollout is the very scope creep the series guards against: one real barrier today beats a perfect week-long plan.

The horizon: the "living fork" and a shared harness-kit

The template has a fundamental flaw: a fork is a point-in-time snapshot. Improve the normalize prompt or add a lesson to _core on project A — projects B and C never learn of it until someone manually pulls upstream. The phase's horizon is to remove this: extract _core and the prompts (the mechanism) into a shared package/repo — call it a harness-kit — that projects DEPEND on, layering local lessons and ADRs on top. Then a core improvement in one place is picked up by all projects via a dependency bump, not a manual merge into every fork. This is the horizon AFTER the template is proven on one project, not the first step. First confirm the fork really cuts the start to 2–3 days; extracting a shared package before that is premature abstraction: you'd freeze a not-yet-settled mechanism shape into a dependency and break every project on each change to it. And honesty about the template itself — a constant note of this series: a template and a harness-kit give a new project the right SHAPE, not finished content. The layer model, ADRs, stack-specific barriers and the ledger's content still accrue on each project over time. A template cuts 'time to agent-ready', it doesn't abolish the work.

Project-local layer (accrues)

Filled AGENTS.md, own ADRs, project-bound lessons, stack-specific barriers

Shared harness-kit (a dependency, updated in one place)

normalize/maintain prompts, _core, the ADR template, the DoD — the mechanism

The project's stack and infra

Any language, any CI, any scheduler — the kit is agnostic to them

Don't extract a harness-kit until the template is proven on at least one or two projects. Premature abstraction is especially costly here: a dependency couples every project to the mechanism's shape, and until that's settled, every core edit is a breaking change for all of them at once.

The series finale: what the template does NOT do, and the map

This is the last phase — the Harness Engineering series is assembled. You went from auditing a brownfield project (Phase 0) through context engineering, ExecPlan, architectural barriers, garbage collection and the lessons-ledger (Phase 5.5) to packaging all of it into a forkable golden path. The final phase's DoD is met when the template repo exists, is forkable, and deploys on a new project independent of stack and infrastructure. And finally — the harness's honest boundaries, the same note sounded all series. The harness ensures architectural integrity and maintainability — but NOT functional correctness: whether the code does what the user needs is still checked by a human and product tests. It does NOT replace human review. And it degrades without discipline: barriers rust, docs drift, the ledger turns into a write-only graveyard if unattended (which is exactly what GC and maintain are for). A template replicates the mechanism, it doesn't remove the duty to maintain it. With that, the series is complete. Head back to the hub — it maps all phases and how they connect.

Honest boundaries — what the harness does NOT do

Ensures architectural integrity and maintainability

The template forks and deploys independent of stack and infra (DoD)

Does NOT validate functional correctness — that is humans and product tests

Does NOT replace human review

Degrades without discipline: barriers rust, the ledger becomes a graveyard

The most common scaling failure is confusing 'we forked the template' with 'the harness is done'. The template gives the shape in 2–3 days; integrity holds only through maintenance discipline (GC, maintain, review). A snapshot without living upkeep goes stale like any other document.

Result

The final phase is assembled: the harness stopped being an artisanal per-project build and became a golden path — a forkable template repo. You know what goes into the template with project-specific cleanup (<PROJECT_NAME> stubs, environment.md with an empty tool-selection table, barrier configs and GC jobs as TODOs/contracts, only the universal .claude/skills/), how the migration capsule works (the portable mechanism + a curated _core vs project-bound noise), what HOW_TO_FORK.md answers (fork, upstream, day 1 vs later, the 2–3 day estimate), and where the 'living fork' horizon leads — a shared harness-kit as a dependency. And above all — honesty: a template gives the shape, not a finished harness; integrity holds through discipline, the harness doesn't validate functional correctness and doesn't replace review. The Harness Engineering series is complete — the map of all phases is in the hub.

Next Steps

Series hub: Harness Engineering