Skip to content
PETROVA

Petrova evolves into a control plane with a thin centre

Date: 2026-04-29 Status: closed Supersedes: none Superseded-by: none — current

Context

Section titled “Context”

Three pains have surfaced concurrently across the petrova line of consumer repos (currently kahn-hq, smo1-io, with more planned):

  1. Duplication. Methodology files (META-RULES, agent-fleet shape, prompt conventions) are bootstrapped into each consumer repo and then drift — the same content in N places, edited inconsistently.
  2. No cross-repo visibility. There is no aggregate view of phase status, open decisions, or in-flight milestones across the fleet of consumer repos.
  3. No agent-fleet write path. KAHN-style agentic fleets can diagnose and plan locally in a consumer repo but have no disciplined, MR-compliant way to act on changes (open decisions, update milestones, propose fixes) across the fleet.

A user-driven brainstorming round on 2026-04-29 weighed (a) keeping the current “template line” model, (b) collapsing all guidance into a central store (Postgres-backed or PR-into-petrova), and (c) a layered control-plane model that centralizes only methodology and action verbs, leaving project truth (north-star, decisions, milestones) in each consumer repo.

The trigger for committing this decision now, rather than evolving incrementally, is that KAHN’s agentic fleets are about to gain the ability to act across repos; without an agreed verb layer they would either bypass MR-7 (writing without dated, in-repo decision records) or stall.

Decision

Section titled “Decision”

Petrova-hq evolves into a control plane with a deliberately thin centre:

  • Centralized: methodology (META-RULES, agent fleet shape, prompts), action verb specifications, a registry of governed repos, and read-only cross-repo aggregation.
  • Not centralized: project intent (north-star), project decisions, project milestones — these stay in the consumer repo where the code lives, preserving MR-7 (append-only, dated, in-repo) and MR-12 (CLAUDE.md is a projection, not a source).
  • Action surface: a petrova CLI plus matching Claude Code skills (petrova-act, petrova-status) implementing typed verbs. Every write is PR-emitting, never a direct push; every PR cites the upheld MR-N; every verb is dry-run by default; auth is via a GitHub App with per-repo scope.

The full implementation is sequenced across eight tasksets (TASKSET 1–8), with this doc opened during TASKSET 1.

Alternatives considered

Section titled “Alternatives considered”
  • Status quo (template line only). Each consumer repo continues to receive bootstrapped copies of methodology files. Rejected — the duplication pain is real and growing, and there is no path to fleet-level agentic action without a verb layer.
  • Central database (Postgres) as source of truth for guidance. All north-star content, decisions, milestones moved to a central store with consumer repos pulling on demand. Rejected — violates MR-7 (decisions decouple from the code they govern, lose git blame, lose branch protection as the human gate) and MR-12 (consumer CLAUDE.md would project from a remote source not grounded in local spec).
  • Petrova as a versioned package only (no control plane). Publish petrova as an installable CLI used locally inside each consumer repo, no central registry, no aggregator. Rejected — works for solo low-volume use but provides no path for cross-repo orchestration by KAHN fleets, and GitHub-Projects-as-dashboard still amounts to central state hosted by GH.

Consequences

Section titled “Consequences”

For code:

  • New top-level registry.yaml declaring governed repos (this taskset).
  • New cli/ workspace and skills/ directory in subsequent tasksets.
  • New spec/verbs/ directory with one schema per verb (TASKSET 3).

For docs:

  • This decision doc opens petrova-hq’s own docs/decisions/ ledger.
  • core/templates/shared/ namespace will be introduced in TASKSET 2 to absorb cross-project methodology currently duplicated in consumers.

For in-flight phases:

  • None — petrova-hq has no open phases at time of writing.

For invariants:

  • No MR additions, modifications, or repeals. The decision is consistent with MR-1 through MR-12 as currently published. Specifically: MR-7 is upheld by keeping decisions in-repo and PR-emitting all writes; MR-12 is upheld by ensuring shared/ content is methodology only, never project-specific intent.

References

Section titled “References”
  • CLAUDE.md — petrova-hq project instructions (load-bearing invariants).
  • core/templates/META-RULES.md — full MR-1..MR-12 set.
  • core/templates/docs/decisions/README.md — decision doc conventions (mirrored at docs/decisions/README.md for petrova-hq’s own use).
  • TASKSET 1–8 implementation strategy (in conversation transcript; to be transcribed into docs/spec/ in a later taskset if it earns durable status).

Sign-off

Section titled “Sign-off”
  • Subagent: bootstrap-architect (conversation 2026-04-29)
  • Human: Devarno — alex@devarno.com