Skip to content
PETROVA

docs/ scaffold

Every petrova-line consumer repo inherits a standard docs/ shape on bootstrap. This page describes each directory’s purpose and the rank graph that connects them.

The shape

Section titled “The shape”
<consumer-repo>/
├── CLAUDE.md                  # projection of north-star + spec + milestones
├── MILESTONES.md              # phase + milestone schedule
├── AGENTS.xml                 # subagent roster + handoff graph
├── docs/
│   ├── META-RULES.md          # MR-1..MR-12, copied verbatim from petrova-hq
│   ├── north-star/            # load-bearing intent (≤3 docs)
│   ├── decisions/             # ADRs, dated, append-only
│   ├── findings/              # diagnostic arcs, dated, timestamped
│   ├── runbooks/              # operator procedures
│   ├── spec/                  # SRS, schemas, acceptance corpus
│   ├── verification/          # traceability matrix
│   ├── backlog/               # deferred work
│   └── roles/                 # per-subagent session logs

Per-directory purpose

Section titled “Per-directory purpose”

docs/north-star/ (rank: north-star)

Section titled “docs/north-star/ (rank: north-star)”

Load-bearing intent. Every PR and planning session opens with “does this serve the north-star?” — if not, it goes to backlog unless it’s load-bearing infrastructure.

Cap of ≤3 docs. Typically: intent.md (the what), realignment-criteria.md (the gate), and at most one more.

docs/decisions/ (rank: decisions, outranks: backlog)

Section titled “docs/decisions/ (rank: decisions, outranks: backlog)”

ADR-style decision artefacts. Filename: YYYY-MM-DD-<slug>.md. Append-only per MR-7. Closed docs are not edited; supersession via successor doc.

Most petrova-emitted PRs that change project state land a decision doc here.

docs/findings/ (rank: findings)

Section titled “docs/findings/ (rank: findings)”

Diagnostic arcs and incidents. Filename: YYYYMMDD-HHMM-<slug>.md (timestamped, not just dated, because multiple findings per day is normal). Findings that warrant a verdict graduate to a decision doc.

docs/runbooks/ (rank: runbooks)

Section titled “docs/runbooks/ (rank: runbooks)”

Operator procedures. How to do recurring operations safely. The PETROVA-HQ doc site itself has a runbooks/ section that follows this same convention.

docs/spec/ (rank: spec)

Section titled “docs/spec/ (rank: spec)”

The grounded source for every claim a CLAUDE.md or invariant makes (MR-12). SRS, JSON Schemas, acceptance corpus. Where requirements actually live (the consumer’s analogue of PETROVA-HQ’s spec/verbs/).

docs/verification/ (rank: verification)

Section titled “docs/verification/ (rank: verification)”

Traceability matrix. Maps milestones to acceptance criteria to evidence. Closed phases reference these as their evidence paths.

docs/backlog/

Section titled “docs/backlog/”

Deferred work. docs/backlog/frozen/ holds items that don’t pass the north-star lens.

docs/roles/<role>/outputs/

Section titled “docs/roles/<role>/outputs/”

Per-subagent session logs. Pointed to by AGENTS.xml. Append-only.

The rank graph

Section titled “The rank graph”

Each directory’s README.md declares:

---
rank: <ranks-this-doc-lives-at>
outranks: [<ranks-this-overrides-on-conflict>]
---

The rank graph must be a DAG (validated by the docs-invariants CI workflow). Cycles are rejected.

Frontmatter conventions

Section titled “Frontmatter conventions”

Decision docs use specific structural frontmatter:

**Date:** YYYY-MM-DD
**Status:** open | closed | superseded
**Supersedes:** <prior decision doc paths, or "none">
**Superseded-by:** <successor doc path, or "none — current">

Findings use:

**Timestamp:** YYYY-MM-DDTHH:MM:SSZ
**Status:** open | resolved | superseded-by-decision

Where this shape comes from

Section titled “Where this shape comes from”

The scaffold lives at core/templates/docs/ in the templates submodule. The bootstrap prompt (/prompts/00-bootstrap/) copies it into each new consumer repo on day 1.

Existing consumers don’t need to migrate — their pre-existing docs/ shape is preserved. New consumers inherit the canonical shape from core/templates/docs/ automatically.

Anti-patterns

Section titled “Anti-patterns”
  • Subdirectories inside ranked folders. The date prefix already orders decision docs and findings. Subdirectories conflate axes.
  • Cross-rank includes. A backlog item must not be referenced as authoritative in a decision doc. The rank order is load-bearing.
  • Loose .md files at repo root other than the canonical set (README.md, CLAUDE.md, MILESTONES.md, AGENTS.xml, SECURITY.md, CONTRIBUTING.md, LICENSE). Pick a rank.

See also

Section titled “See also”