harness-docs

name

harness-docs

description

This skill should be used when the user asks to "scaffold agent docs", "write AGENTS.md", "write ARCHITECTURE.md", "set up docs folder", "make this repo agent-ready", "add per-directory AGENTS.md", "organize docs", or when the user references the OpenAI harness engineering pattern or matklad's ARCHITECTURE.md convention. Always creates AGENTS.md (map, not manual, ≤~100 lines, markdown) and ARCHITECTURE.html (codemap); then adds only the docs/ files the repo actually warrants — SECURITY, RELIABILITY, DESIGN, PLANS, product-specs, etc. are created when there is real content for them, not by default — plus a root index.html when there are multiple HTML docs to tie together. Human-facing docs are standalone single-file HTML in a warm aesthetic, composed from the relevant gallery examples in references/examples/ — a single doc (especially ARCHITECTURE.html) usually draws on several. Works for both new (green-field) and existing (audit + migrate) projects.

Harness Docs

Build agent-friendly documentation using the OpenAI harness engineering playbook plus matklad's ARCHITECTURE.md principles.

What gets created (decide — don't dump the whole tree)

The skill decides which docs a repo needs. It does not scaffold the full docs/ tree by default. There are two tiers:

Core — always create (every repo gets these):

• AGENTS.md (markdown) — the agent-read map.
• ARCHITECTURE.html — the codemap.

Earned — create one only when you have real, repo-specific content to put in it right now. A doc earns its place when the repo (or the user) hands you at least one concrete section to write. If the only thing you could put in the file is the "why this doc exists" lede and <<PLACEHOLDER>>s, do not create the file. An empty or stub doc is noise: it crowds the index, dilutes signal, implies a maturity the repo doesn't have, and agents skip it anyway. The tree grows later, when content appears (see Review Cadence) — not up front.

Decision signals for each earned doc:

Doc / dir	Create it when…	Skip it when…
index.html	there are ≥2 human-facing HTML docs to tie together	only ARCHITECTURE.html exists — link it from AGENTS.md
docs/README.html	docs/ ends up holding ≥1 other file	docs/ is empty
docs/DESIGN.html, docs/design-docs/	there's real rationale / ADRs / "why it's built this way" beyond the codemap	the codemap already says all there is
docs/SECURITY.html	the repo has a security surface: auth, secrets, PII, payments, untrusted input, a threat model	a pure library/CLI with no security surface
docs/RELIABILITY.html	it's a deployed service with SLOs, runbooks, on-call, error budgets	a library, static site, or one-off tool
docs/PRODUCT_SENSE.html, docs/product-specs/	it's a user-facing product with stated principles / specs	infra, libraries, internal tooling
docs/QUALITY_SCORE.html	the team defines quality explicitly (rubric, scorecard, DoD beyond CI)	quality just means "tests pass"
docs/PLANS.html, docs/exec-plans/	there's a roadmap or in-flight execution plans	no planned work to record
docs/exec-plans/tech-debt-tracker.html	tracked tech debt exists	none tracked
docs/references/	third-party docs are worth vendoring for model consumption	nothing external to vendor
docs/generated/	something auto-produces docs (schemas, API specs)	nothing is generated
docs/FRONTEND.html	the repo is a frontend project (frontend dep in package.json, top-level index.html, or angular.json)	no frontend
<subsystem>/AGENTS.md	a subsystem has its own toolchain (distinct language, separate manifest, distinct deploy)	one stack across the repo

When you skip a doc, also skip its row in AGENTS.md's "Where Things Live" table and its link in index.html / docs/README.html. Don't list what doesn't exist ("Name, don't link"; don't invent structure), and don't leave a "TODO: write SECURITY.html" stub — a doc's absence is the correct state until there's content for it. The realistic minimal output for a small or green-field repo is just AGENTS.md + ARCHITECTURE.html.

Output Format

• AGENTS.md (and nested AGENTS.md) stay markdown. They are the agent-read source of truth — plain, greppable text that agents and harnesses load directly. Never convert them to HTML. Author them by adapting the filled-in AGENTS.md / nested AGENTS.md shapes in references/examples.md — copy the shape, not the content.
• Everything human-facing is standalone HTML. ARCHITECTURE.html, plus whichever index.html / docs/** files you decide to create (see "What gets created"), are authored as beautiful, single-file .html documents (inline CSS, no network, opens by double-click) in the warm "Anthropic" aesthetic. They follow modern web best practices: semantic landmarks, color-scheme: light dark with a warm dark palette that respects the reader's system theme, ink-friendly print styles, responsive layout, and keyboard focus styles. When you author or edit these, start by copying the asset assets/template.html verbatim — literally cp assets/template.html <target> — then fill the <!-- … --> slots and compose the <main> content from the gallery. assets/template.html is the canonical shell (warm tokens, base CSS, sticky TOC + scroll-spy, ::selection, the a.card anti-fill guard). Never hand-write or re-derive the CSS from memory — that is the main way these docs go wrong (dropped TOC, missing ::selection, card links that fill clay on hover). After authoring, run bash scripts/check-doc.sh <file>; it fails if the shell was dropped. The asset is self-contained, so this skill never depends on any other skill. The split is deliberate: machines read the map (markdown); people read the reference material (HTML).
• A root index.html ties the HTML docs together — when there are several. Create it once the repo has ≥2 human-facing HTML docs; it's the landing page that links to AGENTS.md (the machine-read map), ARCHITECTURE.html, and whatever docs/ files exist. If ARCHITECTURE.html is the only HTML doc, skip index.html and link ARCHITECTURE.html straight from AGENTS.md. When created, it carries a harness-docs:doc-index marker comment so it is never mistaken for an application entry point when you check whether the repo is a frontend project.
• Compose the content from the gallery — never author HTML from scratch. With the shell already copied from assets/template.html, fill <main> from references/examples/ — 20 reference artifacts (plus their own index.html gallery) in this exact aesthetic. Before writing, survey the gallery and draw on every example whose structure or visuals fit — a single doc usually combines several. Lift their structure, components, and especially their visuals — diagrams, flowcharts, SVG illustrations, charts, panels, tables. A doc that is a wall of prose with no visual means you skipped this step. references/html-style.md explains the palette and rules (the why); assets/template.html is the what to copy.
• Open each HTML doc with a one-line "why this doc exists" lede, and leave <<PLACEHOLDER>> markers (wrapped in <span class="ph">) for anything you can't fill yet — a later linter can catch the unfilled stubs.

Authoring the HTML (compose from the gallery)

Two ingredients per doc — shell and content — kept strictly separate:

1. Shell = assets/template.html, copied verbatim. Run cp assets/template.html <target>. The shell is <head>, the whole <style>, the .layout/TOC, and the scroll-spy <script>. Never reproduce it from memory or hand-edit the CSS — copying the file is what guarantees every doc gets the TOC, ::selection, and the a.card anti-fill guard.
2. Content = composed from the gallery in references/examples/ (below): fill the <!-- … --> slots inside <main>.

After authoring, run bash scripts/check-doc.sh <target>. It strips whitespace and checks the shell's sentinels; a non-zero exit means the shell was dropped or hand-rewritten — re-copy assets/template.html and re-fill rather than patching.

Survey the gallery first, then compose — don't grab one "closest" file. Before writing a doc, skim the gallery and open at least three or four examples, then pull each part from wherever it's done best. Most docs combine several examples: one for the overall structure, others for individual diagrams, panels, tables, or interactive bits. Which examples you use depends on the project and what the doc must show — the tables below are starting points, not a 1:1 mapping and not a limit. ARCHITECTURE.html in particular usually draws on the most.

Starting points by doc kind (non-exhaustive — combine freely)

Doc	Open these first, then add whatever else the project needs
ARCHITECTURE.html	04-code-understanding + 13-flowchart-diagram, then mix in 10-svg-illustrations (lifecycle / data-flow figures), 11-status-report (key-stat panels), 16-implementation-plan (sequencing), and tables for invariants / boundaries
index.html, docs/README.html, **/index.html	index.html (masthead + linked catalogue); borrow card grids from any example
docs/DESIGN.html, docs/design-docs/*	15-research-concept-explainer, 14-research-feature-explainer; add 13 / 10 to diagram a decision
docs/PRODUCT_SENSE.html, docs/product-specs/*	14-research-feature-explainer, 02-exploration-visual-designs, 06-component-variants
docs/SECURITY.html	14-research-feature-explainer + 13-flowchart-diagram (trust boundaries) + 18-editor-triage-board (risk table)
docs/RELIABILITY.html	11-status-report, 12-incident-report; add 16-implementation-plan for runbook sequences
docs/QUALITY_SCORE.html	11-status-report (scorecards) + 18-editor-triage-board
docs/PLANS.html, docs/exec-plans/*	16-implementation-plan + 18-editor-triage-board
docs/FRONTEND.html	05-design-system + 06-component-variants + 07-prototype-animation / 08-prototype-interaction (live demos)

Visual building blocks (use as many as the doc needs)

The gallery is visual by design — that is the whole reason to compose from it, and the fix for plain, text-only output. Every doc earns at least one visual, and most earn several. The richer the architecture, the more blocks ARCHITECTURE.html should combine:

Want…	Borrow from
Module / data-flow / boundary flowchart	13-flowchart-diagram
Conceptual SVG figures / illustrations	10-svg-illustrations
Code structure / annotated tree	04-code-understanding
Metric cards, status panels, scorecards	11-status-report
Post-mortem / incident write-up	12-incident-report
Timeline / sequenced plan	16-implementation-plan
Triage board / status table	18-editor-triage-board
Toggle / config / flag rows	19-editor-feature-flags
Side-by-side options / variants	01-exploration-code-approaches, 06-component-variants, 02-exploration-visual-designs
Component / token system	05-design-system
Animated or interactive demo	07-prototype-animation, 08-prototype-interaction, 20-editor-prompt-tuner
Slides / step-through	09-slide-deck
PR / change write-up	03-code-review-pr, 17-pr-writeup

Lift the SVG/markup wholesale from each example, then replace its labels and data — don't hand-roll a plainer version. Combining two or three blocks in one doc is normal and encouraged.

No example fits a particular section? Still copy the shell verbatim from references/html-style.md, then build that section from the nearest building block above. Always open with a "why this doc exists" lede and leave <span class="ph"> placeholders for anything you can't fill yet.

Core Principles

• AGENTS.md is a map, not a manual. Target ≤ ~100 lines. Point to docs/*. Resist growing it. A giant instruction file crowds out task, code, and relevant docs in the model's context.
• ARCHITECTURE.md is a codemap. Answer "where is the thing that does X?" and "what does this thing do?" for new contributors. Include only things that don't change often.
• Hierarchy. Root AGENTS.md plus sub-directory AGENTS.md overrides. Codex walks from repo root to cwd, closer files winning; apply the same convention for Claude.
• Progressive disclosure. Start agents with a small, stable entry point; teach them where to look next.
• Name, don't link. Name files / modules / types — agents can grep. Links rot.
• Invariants as absences. "X never calls Y" is more useful than "X calls Y".
• Reflect, don't sync. Revisit these files 1–2× a year, not continuously.
• AGENTS.md is the portable source of truth. If the repo already has CLAUDE.md, .cursorrules, .github/copilot-instructions.md, GEMINI.md, .windsurfrules, or .aider.conf.yml, propose migrating portable content (schema, conventions, invariants) into AGENTS.md / docs/, leaving only tool-specific content (slash commands, hooks, IDE flags) in those files. After migration, the recommended CLAUDE.md shape is a one-line @AGENTS.md import (real import — Claude Code expands the file into context) followed by any Claude Code–specific additions below. The skill proposes this shape to the user during migration; it is not a scaffolded artifact. See references/claude-md-best-practices.md for the full rubric and the per-tool pointer patterns. Never migrate without user approval; if declined, fall back to cross-linking without moving content.

Target Folder Layout (the maximal tree — create only what's earned)

This is the full menu, not a checklist. Always create the two Core files; create everything below them only when the "What gets created" signals are met. Most repos use a fraction of this.

repo/
├── AGENTS.md                 # CORE — markdown, ~100 lines, map + pointers
├── ARCHITECTURE.html         # CORE — codemap (HTML)
│
│   #  ↓↓ EARNED — create only when there's real content (see "What gets created") ↓↓
├── index.html                # only if ≥2 HTML docs exist to tie together
├── docs/
│   ├── README.html           # only once docs/ holds ≥1 other file
│   ├── DESIGN.html           # only if real design rationale exists
│   ├── FRONTEND.html         # only if a frontend project
│   ├── SECURITY.html         # only if there's a security surface
│   ├── RELIABILITY.html      # only if a deployed service w/ SLOs
│   ├── PRODUCT_SENSE.html    # only if a user-facing product w/ principles
│   ├── QUALITY_SCORE.html    # only if quality is explicitly defined
│   ├── PLANS.html            # only if there's a roadmap
│   ├── design-docs/          # only if there are catalogued ADRs
│   │   ├── index.html
│   │   └── core-beliefs.html
│   ├── exec-plans/           # only if there are execution plans / tracked debt
│   │   ├── active/
│   │   ├── completed/
│   │   └── tech-debt-tracker.html
│   ├── product-specs/        # only if there are feature & UX specs
│   │   └── index.html
│   ├── references/           # only if third-party docs are worth vendoring
│   └── generated/            # only if something auto-produces docs (schemas etc.)
└── <subsystem>/
    └── AGENTS.md             # only for a subsystem with its own toolchain

The minimal real-world output is just AGENTS.md + ARCHITECTURE.html. Note the split: AGENTS.md files are markdown (agent-read source of truth); ARCHITECTURE.html and all of docs/** are standalone single-file HTML (see Output Format above).

Two Workflows

A. New Project

1. Confirm target. Ask for the repo root path. Never author into $PWD blindly.
2. Author the two Core files (never overwrite — check first):
   • AGENTS.md (markdown) by adapting the filled-in shape in references/examples.md: project one-liner, install/build/test/lint commands, primary subsystems, 1–3 hard "never do" rules. Leave <<PLACEHOLDER>> markers for anything unknown — don't invent. Keep ≤ ~100 lines.
   • ARCHITECTURE.html: cp assets/template.html <repo>/ARCHITECTURE.html, then compose the codemap from several gallery examples as the architecture needs — e.g. 04-code-understanding (code layout) + 13-flowchart-diagram (module/boundary diagram), plus 10-svg-illustrations, 11-status-report panels, 16-implementation-plan sequencing, and tables for invariants/boundaries (see "Authoring the HTML"). Fill the <!-- … --> slots and leave <span class="ph"> placeholders for unknowns. See references/workflow-new-project.md for content.
3. Decide the earned docs. Walk the "What gets created" table against what you actually know about this repo (and ask the user what they have: security surface? deployed service? roadmap? product principles?). Create a doc only if you can fill it with ≥1 real, repo-specific section right now. Green-field repos usually have little of this — it's normal for the output to be just the two Core files plus maybe one or two others. Don't pre-create stubs.
4. Author each earned doc you decided on: cp assets/template.html <target>, open with a "WHY this doc exists" lede, and write at least one real section, composing from the gallery per "Authoring the HTML" (draw on several examples where it helps). (For a frontend project, that includes docs/FRONTEND.html; markers: a frontend dep in package.json, a top-level index.html, or angular.json.) Run bash scripts/check-doc.sh <file> on each HTML doc before moving on.
5. Author index.html only if you created ≥2 HTML docs. Set the project name; link only the docs that exist. (If ARCHITECTURE.html is the lone HTML doc, skip index.html and point at it from AGENTS.md instead.) Make sure AGENTS.md's "Where Things Live" table lists only docs that exist.
6. Commit. The structure that exists signals real, filled content to future agents — and grows as content appears.

B. Existing Project

1. Audit. List top-level dirs, existing docs, build/test/lint commands, known constraints. Check for tool-specific agent docs (CLAUDE.md, .cursorrules, .github/copilot-instructions.md, GEMINI.md, .windsurfrules, .aider.conf.yml) and classify each section as portable (schema, conventions, never-do rules → candidates for migration) or tool-specific (slash commands, hooks, IDE flags → stay in place). Do not invent structure — describe what exists. Detail in references/workflow-existing-project.md.
2. Propose migration and get approval. If portable content was found in step 1, present a short plan: what moves (section → destination), what stays, and what the tool-specific file will look like after. For CLAUDE.md the recommended post-migration shape is an @AGENTS.md import followed by any Claude Code–specific additions (see references/claude-md-best-practices.md); for other tools, a prose pointer to AGENTS.md plus tool-specific content below. This skill never writes these stubs — the agent edits the files directly after the user approves. Wait for explicit approval before editing any files. If the user declines, fall back to cross-linking only.
3. Write ARCHITECTURE.html first — one author, one sitting. cp assets/template.html ARCHITECTURE.html. Start from the directory tree; describe what each top-level module does in one paragraph. Compose its visuals from several gallery examples as the architecture needs — 04-code-understanding, 13-flowchart-diagram, 10-svg-illustrations, 11-status-report, and tables (see "Authoring the HTML").
4. Write AGENTS.md (markdown). If migration was approved, this is the new source of truth; otherwise it's a thin map that cross-links to the tool-specific file via the "Tool-Specific Agent Docs" section. Also point at any pre-existing README.md, CONTRIBUTING.md, docs/*.
5. Add nested AGENTS.md in every top-level subsystem with its own stack (distinct language, separate package.json / pyproject.toml, distinct deploy target). Adapt the nested AGENTS.md shape in references/examples.md.
6. Create earned docs only where the audit found content. Map what step 1 surfaced onto the "What gets created" table — existing security notes → docs/SECURITY.html, runbooks/SLOs → docs/RELIABILITY.html, an ADR folder → docs/design-docs/, and so on. For each, cp assets/template.html <target> and compose from the gallery (see "Authoring the HTML"). Create index.html only if there are ≥2 HTML docs, and link only docs that exist. Don't manufacture a doc the audit gave you nothing for.
7. Enforce mechanically. CI: AGENTS.md under line limit, cross-links resolve, bash scripts/check-doc.sh passes on every HTML doc (proves each embeds the shell), docs/generated/* matches regen output.

Rules of Thumb

• If a doc would only contain its "why this doc exists" lede and placeholders, don't create it — its absence is the correct state until there's content.
• Only AGENTS.md and ARCHITECTURE.html are unconditional. Everything else must earn its place with real, repo-specific content.
• If implementation details are creeping into AGENTS.md, move them to docs/.
• If a section would need weekly updates, it does not belong in ARCHITECTURE.html.
• If a sub-directory has its own build toolchain, give it its own AGENTS.md.
• If a directory contains auto-generated content, state so at the top.
• If a link points at a line-numbered location in code, replace it with a name the reader can grep.

Review Cadence

• Add an earned doc the moment its content first exists — the first real security rule creates docs/SECURITY.html, the first execution plan creates docs/exec-plans/. The tree grows with the repo; it isn't poured up front.
• AGENTS.md / ARCHITECTURE.html: revisit 2×/yr or on major refactor.
• exec-plans/active/ → completed/: move when a plan closes.
• docs/generated/: regen in CI; the header must mark it machine-generated.

Additional Resources

Assets (copied into the target repo — the what to copy)

• assets/template.html — the canonical HTML shell. cp it to every new ARCHITECTURE.html / index.html / docs/*.html, then fill the <!-- … --> slots and compose <main> from the gallery. It bakes in the warm tokens, base CSS, sticky TOC + scroll-spy, ::selection, and the a.card anti-fill guard. Copying the file (not retyping the CSS) is what keeps every doc correct.

Scripts

• scripts/check-doc.sh <file.html> [...] — verifies a doc embeds the shell (TOC, scroll-spy, ::selection, the a.card guard, warm tokens). Whitespace-agnostic, so it passes formatted or minified docs. Run it after authoring and in CI; a non-zero exit means the doc was hand-written instead of copied from assets/template.html.

References (load when deciding how to apply the skill)

• references/principles.md — deeper rationale from the two source articles, plus anti-patterns.
• references/workflow-new-project.md — step-by-step new-project flow, including CI enforcement snippets.
• references/workflow-existing-project.md — step-by-step audit flow, including grep recipes for finding invariants.
• references/claude-md-best-practices.md — distilled from the official Claude Code memory docs (link); the @AGENTS.md import pattern, what stays in CLAUDE.md, .claude/rules/ path-scoped rules, and drift prevention.
• references/html-style.md — the why behind assets/template.html: the palette/token meanings, the design rules (one clay accent, never solid-fill clay, lead with a visual), and the optional paper-grain. Read it to use the aesthetic well; copy assets/template.html to get it. The CSS itself lives only in the asset (no duplication).
• references/examples.md — filled-in AGENTS.md, ARCHITECTURE, and nested AGENTS.md from a fictional project. The source to adapt when authoring the markdown AGENTS.md files — copy the shape, not the content.
• references/examples/ — the 20-artifact HTML gallery (plus its own index.html) in the warm aesthetic. The gold standard for the human-facing HTML; survey it and compose from the relevant examples (often several per doc) when authoring index.html, ARCHITECTURE.html, or any docs/*.html (see "Authoring the HTML").