how-it-works.md

description	Load when evaluating code-docs for adoption, onboarding to the system, or seeking an end-to-end understanding of the documentation lifecycle.
lastValidated	2026-03-28
maxAgeDays	90
tags	architecture lifecycle onboarding
title	How it works

How it works

This document walks through the full lifecycle of the code-docs system: how docs are written, how agents find them, and how automation keeps everything current. Each section builds on the previous one and includes concrete examples from this repo.

Writing a doc

Every doc lives in the docs/ directory at the repo root. Each file covers a single topic, workflow, or area of the codebase. The key difference from ordinary Markdown files is a YAML frontmatter block at the top that gives the doc a machine-readable identity.

Here is the frontmatter from this repo's frontmatter-schema.md:

---
description: "Load when authoring new docs, reviewing frontmatter validation, or modifying the build-index script."
lastValidated: "2026-03-12"
maxAgeDays: 90
paths:
  - "docs/**"
  - "scripts/agents/build-index.py"
  - ".agentsrc.yaml"
tags:
  - frontmatter
  - schema
  - validation
title: "Frontmatter schema"
---

The fields break down into two groups based on ownership:

Field	Owner	Purpose
title	LLM (generated)	Short name for the doc. Appears in the AGENTS.md index.
description	LLM (generated)	Trigger condition that tells agents when to load the doc.
paths	LLM (generated)	Glob patterns linking the doc to code paths. Used for staleness detection.
tags	LLM (generated)	Lowercase category labels.
lastValidated	Human	ISO 8601 date. Set by the author when the doc is confirmed accurate.
maxAgeDays	Human	Staleness threshold in days. Defaults to the value in .agentsrc.yaml if omitted.

The description field is the most important. It is written as a trigger condition, not a topic summary. An agent reads this field and makes a binary decision: load the doc, or skip it.

A good description: "Load when modifying auth, tokens, session handling, or debugging login failures."

A bad description: "This document covers the authentication system." The agent cannot make a reliable load decision from a content summary.

For the full field-by-field specification, see Frontmatter schema.

Agent routing via AGENTS.md

AGENTS.md is the entry point for every agent session. It sits at the repo root and acts as a lazy-load index. Instead of reading every doc in docs/, an agent reads AGENTS.md first, scans the table, and loads only the docs relevant to its current task.

The file has three sections:

1. Preamble — a short block that orients the agent (what this repo is, what kind of work happens here).
2. Repo-level context — instructions for how to use the index (load a doc if its description matches your task; skip it if not).
3. Index table — one row per doc, generated by build-index.py.

Here is the index table from this repo:

| Doc | When to load | Last validated | Status | Paths |
| --- | --- | --- | --- | --- |
| [Frontmatter schema](docs/frontmatter-schema.md) | Load when authoring new docs, reviewing frontmatter validation, or modifying the build-index script. | 2026-03-12 | current | `docs/**`<br>`scripts/agents/build-index.py`<br>`.agentsrc.yaml` |

The agent reads the "When to load" column for each row. If the condition matches the current task, it fetches the linked doc. If not, it moves on. This is lazy loading: token usage stays proportional to task complexity, not repo size.

The preamble and repo-level context are human-authored and never touched by automation. The index table is fully regenerated on every run of build-index.py. Boundary markers (<!-- AGENTS-INDEX-START --> and <!-- AGENTS-INDEX-END -->) tell the script where the table begins and ends.

For the full specification of AGENTS.md structure, preamble guidelines, and column definitions, see AGENTS.md structure.

Automation: frontmatter generation and index sync

The docs-sync.yml workflow runs whenever a file in docs/ is added or modified on any branch. It has two jobs: generate frontmatter for the changed files, then regenerate the AGENTS.md index.

How it works

1. The workflow detects which docs/*.md files were added or modified in the push.
2. It passes those file paths to Claude Code with a task prompt (.github/agents/frontmatter-prompt.md) that instructs it to populate any missing LLM-owned fields (title, description, paths, tags).
3. Claude Code reads each file, checks which fields are missing or empty, generates values, and edits only the frontmatter block. It never touches lastValidated or maxAgeDays, and it never overwrites a field that already has a value.
4. After all files are processed, build-index.py regenerates the AGENTS.md index table.
5. If anything changed, the workflow opens a PR targeting the triggering branch so a human can review the generated values before they merge.

What the automation does and does not control

The automation generates title, description, paths, and tags on first creation. After that initial generation, it never overwrites them. This means a poorly generated description must be manually corrected — it will not be auto-fixed on subsequent runs. Reviewing generated descriptions on the first PR is the strongest safeguard.

The automation never writes lastValidated or maxAgeDays. Those fields belong to humans. Setting lastValidated is how a human signals "I have confirmed this doc is still accurate as of this date."

For the full workflow specification and failure modes, see Automation workflow. For the task prompt that drives frontmatter generation, see LLM prompt design for Claude Code.

Automation: staleness detection

The docs-staleness.yml workflow detects docs that may need review. It runs on two triggers: a weekly cron schedule and any push that touches tracked code paths.

Two staleness signals

Time-based: The workflow compares today's date against lastValidated + maxAgeDays for each doc. If a doc is past its threshold, it is flagged as stale. For example, a doc with lastValidated: "2026-01-01" and maxAgeDays: 90 becomes time-stale after April 1, 2026.

Path-based: For each doc that has a paths field, the workflow runs git log --since=<lastValidated> against those paths. If any commits have touched the tracked code since the doc was last validated, it is flagged as path-stale. This catches situations where the code has changed but the doc has not been reviewed.

A doc can be flagged as stale (time), stale (paths), or stale (time + paths). Docs with no staleness signals show as current in the AGENTS.md index.

What happens when a doc is flagged

The staleness workflow regenerates the AGENTS.md index with updated status flags and opens a PR. The PR lists each flagged doc, its staleness reason, and the relevant paths or date. A human reviews the PR, confirms whether the flagged docs need updates, sets lastValidated to today's date in the relevant frontmatter, and merges.

Docs that omit the paths field (such as architectural overviews or onboarding guides) only receive time-based staleness checks. This is by design — not every doc maps to specific code paths.

For the full staleness logic, threshold configuration, and the check script, see Automation workflow.