# AGENTS.md This file is the entry point for an LLM agent operating on this repository directly (cloned, opened in an editor, or handed a working directory), as distinct from [`README.md`](README.md), which is written for a human reader, and [`skills/plt-fill-template/SKILL.md`](skills/plt-fill-template/SKILL.md), which packages the same library for an agent framework that loads skills by convention. If you are an agent and you are reading this file first, everything below is enough to select a bundle, size it to your context budget, and fill it correctly without reading anything else first. The one fact to hold onto while reading the rest of this file: **nothing here has been proven to work.** Every bundle is researched and gate-green, and none of them is claimed to be more than that. Efficacy has been measured four times: three runs returned **VOID**, and the fourth, on 2026-09-03, cleared every validity gate on **two scenarios of one bundle** and found no measurable difference in whether a reader could answer their questions. See [What this library has not proven](#what-this-library-has-not-proven) before you trust a claim here more than it has earned. ## What this repository is A library of document-template **bundles** for product management and software delivery: a PRD, user stories, an ADR, a risk register, a test plan, and so on. A bundle is not one file. It is a folder under [`templates/`](templates/) named for the document type (for example [`templates/prd/`](templates/prd/)) that carries the blank template plus the research, guidance, and worked example that make it fast to fill correctly rather than merely fast to fill. Fifty bundles exist today, covering all 25 templatable Tier-1 ("must-have") document types in the library's researched 209-type catalog. That is the floor, not the ceiling: which types beyond Tier-1 get built, and in what order, is the maintainer's own choice ([ADR 0041](docs/internal/decisions/0041-maintainer-preference-sets-the-build-order.md)). An outside request is recorded and may be weighed; nothing waits for one. ## Selection flow Do not guess a bundle from its folder name or scan `templates/` by hand. Read [`manifest.json`](manifest.json) at the repository root first. It is generated from every bundle's `_meta.yaml` (never edited by hand; regenerated by [`tools/gen-manifest.py`](tools/gen-manifest.py) and checked fresh in CI) and it is the whole selection surface. Each entry carries: | Field | What it is for | |---|---| | `id`, `doc_type` | The bundle's identifier. Matches the folder name and the file prefix. | | `title`, `summary` | What the document type is, in plain language. `summary` is usually enough to disambiguate near-matches. | | `family` | Which of the 10 families the bundle belongs to (see [Families](#families-and-the-two-axes)). | | `phase` or `classification` | Exactly one of these two is present, never both. See [Families](#families-and-the-two-axes). | | `sizes_available`, `default_size` | Which variants exist (`lean`/`full`, or a single size) and which to reach for absent other guidance. | | `sizing_guidance` | A written rule for choosing a size, specific to this document type. | | `approx_tokens` | An estimated token count **per size variant**, keyed by size (and by format, for the few bundles that ship more than one format; see below). Budget context before loading anything. | | `status` | Maturity. Every bundle in this library is currently `beta`: offered for use, not yet settled. | | `tags`, `aliases` | Match these against the job you were asked to do. `aliases` covers what practitioners actually call the type ("decision record" for `adr`, "cost-benefit analysis" for `business-case`). | ### If you have the MCP server, you can skip the file reads Installed via the plugin, this library also serves an MCP server with five tools: `search_templates`, `get_template`, `get_grading_pack`, `validate_fill` and `stamp_and_strip`. They read the same two artifacts described here and wrap the same two Python tools, so **the answers are identical** - the server is a different door to the same room, not a second source of truth. Everything below still applies if you are reading the files directly. See [`installing.md`](docs/how-to/installing.md). One difference worth knowing: `search_templates` takes an `axis` filter that accepts a **phase or a classification** value, because 29 bundles carry a `phase` and the other 21 carry a `classification`. Filtering on phase alone silently reaches only 29 of the 50. And one axis value can hold more bundles than a single response returns: `search_templates` caps a response at 8 candidates, `deliver` and `utility` hold 10 each and `develop` 9, and `total_matched` is how a caller knows the list was cut. ### The second machine artifact: `sections.json` `manifest.json` answers **which bundle and which size**. It deliberately stops there: embedding the per-section detail was measured at 4.6x its size, which would have made the selection surface expensive to read for a question selection never asks. [`sections.json`](sections.json) answers **what is inside the one you picked**. It is generated the same way (from the template variants themselves, by [`tools/gen-sections.py`](tools/gen-sections.py), checked fresh in CI) and covers all 50 bundles: 418 sections and 313 frontmatter fill sites. Per bundle, per format, in document order, each section carries its `title` and heading `level`, the `in_sizes` that hold it, the `guidance_fields` its comment declares (WHAT, WHY, ASK, GOOD, WEAK, TRAP, and PRIORITY / ROW HINT on table sections), `has_table` and `has_row_hint`, and its `placeholders`. **Read it instead of re-deriving the same facts from the raw comments.** The section below tells you the guidance grammar so you can parse a template yourself; `sections.json` is that parse, already done and gate-checked. Use it to answer "what sections does this bundle have", "which are in lean", "which take a table", and "is this draft structurally complete". **One thing it deliberately does not give you.** Each section lists a placeholder **name** once, which is what a completeness check needs. It is not a substitution map: many names recur within a single file body (94 when this was measured on 2026-09-05, with fewer bundles than today), and `prd` reuses `{{owner}}` and `{{date}}` at unrelated sites, so a tool that asked one question per name would put the document owner into an open question's owner column. To fill a template, read the file. The flow: read `manifest.json`, match the job you were given against `doc_type`, `aliases`, and `tags`, disambiguate with `summary` if more than one entry matches, then pick a size from `approx_tokens` and `sizing_guidance`. Only then open a file, and open the template variant, not the companion. The companion is background reading for humans; loading it to select a bundle spends context the manifest already saved you. A handful of bundles ship more than one **format** in addition to size (for example `product-vision` ships `canvas`, `narrative`, and `prfaq`). On those, the meta adds `default_format`, `default_format_guidance`, and `additional_formats` (each with its own `guidance` and the sizes it comes in), and `approx_tokens` gains keys like `narrative-full` alongside the plain `lean`/`full` ones. Format is orthogonal to size: size is how much of the document you fill in, format is what shape it takes. ## The eight files, from an agent's point of view Every bundle folder holds eight files sharing one prefix (`_*`); a single-size bundle ships seven, omitting `_template-full.md`. What each one is for, and whether you should normally load it: | File | For | Load it? | |---|---|---| | `_template-lean.md` or `_template-full.md` | The blank shape. This is the artifact you are actually filling. | **Yes, exactly one.** The size you picked from the manifest. | | `_guide.md` | The operator card: when to use this type, when not to, and a scored rubric to self-grade the result. | Yes, when choosing a variant or grading a filled document. Short by design. | | `_example.md` | A real worked instance, fully filled, no placeholders. | Often, and often instead of reading the blank template line by line: seeing a filled section teaches the shape faster than reading its guidance comment cold. | | `_companion.md` | The deep explainer: what the type is, where it came from, where practitioners disagree, with tiered citations. | Rarely. It is written for a human who wants the reasoning, it is the largest file in the bundle, and every guidance comment in the template already links into the specific section that matters. Load it only if a specific claim needs tracing. | | `_meta.yaml` | The source `manifest.json` was generated from: catalog metadata, `pairs_with`, sizes. | Almost never. Everything in it that matters for selection is already in `manifest.json`. | | `_history.md` | The bundle's changelog by template version. | Almost never. Relevant only if you need to know what changed between two `template_version` values. | | `_research-log.md` | The evidence trail: every source the bundle drew on, its reliability tier, and what it supports. | Only to check a specific claim's provenance, not as part of a normal fill. | The practical rule: a normal fill loads the template and, if the shape is unclear, the guide and the example. Loading all eight files for one document defeats the point of a manifest that lets you budget context before you start. ## Guidance comments are structured, not prose Every section of every template carries an HTML comment directly above the blank space, in one fixed, parseable shape: ``` WHAT what the section is WHY why it exists, ending in a pointer to the relevant companion section ASK two to four questions whose answers become the content GOOD an illustration of a filled section WEAK an illustration of a bad one, and why it fails TRAP the specific mistake this section most often invites ``` These comments are visible in the source file and gone once the document renders (they are standard HTML comments). Because the six labels are fixed and always appear in the same order, you can parse a template's guidance mechanically rather than reading it as free text: `ASK` gives you the questions to resolve before you can write the section, `GOOD` and `WEAK` give you a one-line quality bar, and `TRAP` names the specific failure mode to check your own draft against before moving on. Placeholders inside the blank shape are `{{snake_case}}` throughout, so a substitution point is always findable by pattern rather than by reading prose. If a section does not apply to the document you are filling, the convention is to write one line saying so and why, rather than deleting the section: a reader (human or agent) cannot distinguish a deleted section from one nobody considered. Once every section is filled, the guidance comments are meant to be stripped before the document ships. Keep the `source_template` and `source_template_version` frontmatter fields: they are the only record of which bundle and which version produced the document. ## Families and the two axes Every bundle belongs to one of 10 families (`family` in the manifest), and every bundle is gated on exactly one of two axes, never both: - **`phase`** (`discover`, `define`, `develop`, `deliver`, `measure`, `iterate`): the bundle is tied to a point in the product lifecycle. Most bundles use this axis. - **`classification`** (`foundation`, `utility`, `tool`): the bundle is a standing artifact with no single lifecycle phase, agreed once and consulted repeatedly rather than authored per occasion (a definition of done, a runbook). A smaller number of bundles use this axis. A bundle's `_meta.yaml`, and therefore its `manifest.json` entry, carries `phase` XOR `classification`, enforced by [`tools/meta.schema.json`](tools/meta.schema.json) and gate check J. If you are filtering bundles programmatically by lifecycle stage, check for `phase` first and fall back to `classification` for the bundles that do not have one. ## What this library has not proven Stated as plainly here as it is in [`README.md`](README.md#the-claim-and-what-it-is-worth), because an agent selecting a bundle should not read more confidence into it than the library itself claims: - **A green gate is a structural claim, not a quality one.** Every bundle is `beta`. Nothing here is offered as proven, and the library does not assert that a document produced from one of these templates is better than one written without it. - **Efficacy has been measured four times, and the result still does not support a library-wide quality claim.** Two blinded runs on 2026-08-08 over three of the twenty-six bundles then in the library both returned **VOID** on the discrimination gate, as did a single-scenario run on 2026-08-21. **The fourth, on 2026-09-03, cleared every gate over two scenarios of the `prd` bundle**, and found the probe gap at **exactly 0.00**: no measurable difference in whether a reader could answer their questions. See [`2026-09-03_two-scenario.md`](evals/results/2026-09-03_two-scenario.md). What the runs show consistently is the circularity signature: documents written with these templates score well above a strong generic-prompt control on the **templates' own** rubric criteria (+0.85) and no better than it on decision-usefulness criteria drawn from neither the template nor its guide (-0.03, interval spanning zero). Read [`evals/results/2026-08-08_matched-rerun.md`](evals/results/2026-08-08_matched-rerun.md) before repeating any number from it. **Whether a filled document performs better than one written without the template remains unproven.** - **The quality gate proves structure, not truth.** [`tools/check-bundles.py`](tools/check-bundles.py) confirms every citation in a companion resolves to a real, listed source; it cannot confirm that source supports the claim attached to it. A manual pass in July 2026 found 28 defects across four bundles that had been passing the gate for weeks. [`STATE.md`](STATE.md) is the current source of truth on library coverage and outranks this file, the README, and every other document when they disagree. ## Honest limits on how to get this library There is **no HTTP API and no versioned package on any registry**. The acquisition path is `git clone`, or the Claude Code plugin route, which clones for you: ```bash git clone https://github.com/product-on-purpose/product-lifecycle-templates.git ``` Everything above, `manifest.json`, the eight files per bundle, the guidance comments, is read directly from the checked-out tree. There is no runtime dependency: every file is plain Markdown, YAML, or JSON, readable with nothing more than a file-read tool. > **This section said "there is no MCP server exposing these bundles" until 2026-09-21, and that had > been false since 2026-09-06.** The server shipped in `v0.6.0` and is described two sections above, so > this file spent five releases contradicting itself: an agent reading top to bottom was told how to use > a server and then told it did not exist. Nothing gates a sentence against another sentence. > > **There is now also a website**, , > which renders every bundle for human readers. It is a reading surface, not an acquisition path: it > serves no machine-readable artifact, so an agent still wants the tree or the MCP server. **There is an install step, and which one you use decides whether the bundles are present at all.** The Claude Code plugin route clones the whole repository, so everything above is on disk. The `npx skills add` route installs the **two skills only**, about 47 KB, and none of the 50 bundles; each skill detects this and stops rather than writing a document it has no template for. The routes and how to verify each are in [`docs/how-to/installing.md`](docs/how-to/installing.md). ## See also - [`README.md`](README.md) - the human-facing entry point: quick start, what makes a bundle best-in-class, and the full library table by family. - [`skills/plt-fill-template/SKILL.md`](skills/plt-fill-template/SKILL.md) - the same library packaged for an agent framework that discovers and loads skills by convention, with a fill-and-grade workflow. - [`templates/methodology.md`](templates/methodology.md) - the authoring process and per-bundle Definition of Done that every bundle in this library is held to. - [`STATE.md`](STATE.md) - what is actually true of this repository today. Outranks every other document, including this one.