Playbook Repo as Control-Loop Distribution

ELI5

Petrova-hq is a recipe book, not a kitchen. It hands a fresh repo three pieces of paper — a workspace map, a phase schedule, and a delegation grammar — and that is enough for an agent session to know what to do next without anyone explaining the project from scratch.

Technical Deep Dive

What petrova-hq emits versus what consumers own

flowchart LR
  subgraph PH[petrova-hq — thin centre]
    P[core/prompts/00..04]
    T[core/templates/*.tmpl]
    M[META-RULES.md]
    R[registry.yaml]
    V[spec/verbs + cli/]
  end
  subgraph CR[consumer repo — project truth]
    C[CLAUDE.md]
    MS[MILESTONES.md]
    AX[AGENTS.xml]
    NS[docs/north-star/]
    DD[docs/decisions/]
  end
  P -->|paste 00-bootstrap| C
  P --> MS
  P --> AX
  T --> C
  T --> MS
  T --> AX
  M -->|copied verbatim| CR
  V -->|emits PRs into| CR
  R -.governs.-> CR

The control plane is deliberately thin (docs/decisions/2026-04-29-petrova-control-plane.md):

• Centralised: methodology (META-RULES, prompt set, template skeletons), the verb specifications that define what agent fleets may do, the registry.yaml of governed repos, and the read-only cross-repo aggregator.
• Not centralised: north-star intent, decision docs, milestones — these stay in the consumer repo so MR-7 (append-only, dated, in-repo) and MR-12 (CLAUDE.md is a projection, not a source) hold.

Why no build, no tests, no entrypoint

CLAUDE.md in the petrova-hq root says it explicitly: “Nothing here gets executed against a stack.” Edits in petrova-hq mutate the control loop that downstream repos run, not any product surface. That makes correctness about whether the prompt still stops at its checkpoints and whether the template still places its <<PLACEHOLDER>> tokens, not whether a server boots.

The bootstrap path

The user-facing entrypoint is 00-bootstrap.md. A human pastes it into a fresh Claude Code session opened on a consumer repo with detailed spec docs already present. The prompt:

1. Reads ground truth (Phase 1 — docs/spec/, README, scaffold).
2. Asks Q1–Q7 calibration questions.
3. Generates CLAUDE.md, MILESTONES.md, AGENTS.xml, plus the docs/ scaffold from the templates.
4. Self-audits against MR-1…MR-12.

After bootstrap, four further prompts (01-phase-open, 02-phase-close, 03-verification-round, 04-drift-check) drive the loop for the rest of the project’s life.

Distribution mechanism

Templates use <<PLACEHOLDER>> tokens; the bootstrap agent fills them from Phase 1 reads + Phase 2 answers. The two core/ subtrees are git submodules so methodology changes propagate to all consumers via a single submodule pointer bump.

Key Terms

• Control loop — the closed cycle of phase open → implementer → auditor → reviewer → phase close → next phase that the playbook’s prompts plus AGENTS.xml drive.
• Thin centre — the architectural commitment that petrova-hq holds methodology only, never project intent.
• Consumer repo — any repo that has been registered in registry.yaml and adopts the three control-loop documents.

Q&A

Q: Why does petrova-hq deliberately ship no application code? A: Because the artefact it ships is a control loop, not a runtime. Adding a build target would invite drift toward “petrova as a framework” instead of “petrova as a methodology you instantiate per repo”.

Q: Which three documents does the playbook generate inside a consumer repo? A: CLAUDE.md (workspace projection), MILESTONES.md (phase schedule with acceptance gates), and AGENTS.xml (delegation grammar with <spawns_on> triggers and <handoff_to> chains).

Q: What lives centralised vs what stays in each consumer repo? A: Centralised: META-RULES, prompts, templates, verb specs, registry.yaml. Per-consumer: docs/north-star/, docs/decisions/, MILESTONES.md, the project’s own invariants I-N.

Examples

A new repo traceo-cat is added to the petrova line. The operator (1) opens a registry-update PR via petrova-onboard, (2) merges it so the slug becomes valid for the verb surface, (3) opens a Claude Code session in the consumer repo and pastes 00-bootstrap.md. After the bootstrap session, the consumer has its own CLAUDE.md, MILESTONES.md, AGENTS.xml, and docs/ scaffold — none of which lives back in petrova-hq.