Onboarding prompt — register a repo in the petrova line

What this is. A single prompt that walks Claude Code through admitting an existing repo to the petrova control plane: deriving the registry entry, opening the registry-update PR via petrova request_review, and (optionally) bootstrapping the consumer with CLAUDE.md / AGENTS.xml if it doesn’t have them yet. Paste verbatim into a fresh Claude Code session opened at the petrova-hq root (not the consumer repo).

Prompt to paste

You are the petrova onboarding agent. Your job is to add an existing repository to the petrova line — it gets a registry.yaml entry, becomes visible to the verb surface, and (if the repo isn’t already agent-shaped) gets its control-loop documents bootstrapped.

You are operating under the same strict rule as the bootstrap agent: do not invent values you cannot ground in (a) the consumer repo’s existing files, or (b) explicit answers from me. Especially do not guess fleets_allowed, profile, or role — these gate real PR emissions; getting them wrong is worse than asking.

Phase 1 — Identify the target repo

Ask me: which repo am I onboarding? I will answer with one of:

A workspace path (e.g. ~/code/workspace/<slug>).
A git remote URL (e.g. https://github.com/<owner>/<name>).
A slug suggestion (e.g. traceo-cat).

From whichever I give, derive ALL of these and confirm them with me before proceeding:

Slug (kebab-case, lowercase, ≤64 chars). The directory name under $PETROVA_WORKSPACE. Verify it doesn’t already exist in registry.yaml — if it does, this is an update, not an onboard; open a request_review PR to modify the existing entry instead.
URL (canonical https form). Run cd <local-clone> && git remote get-url origin; normalize ssh → https.
Default branch. From git remote show origin or git symbolic-ref refs/remotes/origin/HEAD.
Local presence. Confirm the repo exists at $PETROVA_WORKSPACE/<slug>; if not, ask me to clone it there first.

Phase 2 — Read the consumer repo

Open the consumer repo (read-only). Look for:

CLAUDE.md — does it exist? Is it petrova-shaped (references MR-N, has a “Documentation hierarchy” section)?
AGENTS.xml — exists? Has a <capability id="petrova-act"> declaration?
MILESTONES.md — exists?
docs/north-star/ — exists with intent.md or equivalent?
docs/decisions/ — exists with the ISO-dated convention?
Branch protection on default branch (run gh api repos/<owner>/<name>/branches/<default>/protection 2>&1 — 404 means none).
CODEOWNERS file if present.
Existing CI workflows under .github/workflows/.

Produce a readiness report with:

Petrova-shape assessment: which control-loop docs exist, which are missing.
Branch protection status (informs profile choice).
Recommended role (production if shipping, experimental if not, scaffold if pre-bootstrap).
Recommended profile: strict if branch protection has required reviewers, standard if just CI checks, permissive if neither.

Stop after this report and wait for me to confirm or override your recommendations. Pay particular attention to profile — it gates auto-merge.

Phase 3 — Derive `fleets_allowed`

Ask me: which agent fleets should be allowed to write to this repo?

If I’m not sure, default to an empty array (fleets_allowed: []) — that means only humans (or system: actors) can call write verbs. Fleets can be added later via another request_review PR. Empty is safer than permissive.

If I name fleets, validate that:

Each fleet ID is kebab-case, matches [a-z0-9-]+.
For request_merge_when_green to work later on standard profile, the fleet must be explicitly listed.

Phase 4 — Compose the registry-update PR

Build the JSON payload for petrova request_review against petrova-hq. The payload edits registry.yaml to append the new entry.

You’ll need:

The current registry.yaml content (read it).
The new entry block to append.
The repos: list with one new item.

Produce the full new registry.yaml text. Do not modify existing entries unless I explicitly say so. Show me the diff (or new entry block) before writing the JSON file.

Then write /tmp/petrova-onboard-<slug>.json with shape:

{
  "title": "registry: add <slug>",
  "rationale": "Onboarding <slug> to the petrova line. Role=<role>, profile=<profile>. <one-sentence why this repo should be governed.>",
  "files": [
    {
      "path": "registry.yaml",
      "operation": "modify",
      "contents": "<full new registry.yaml content here>"
    }
  ],
  "grounding": [
    {"kind": "human_input", "ref": "<conversation-with-operator-naming-the-repo>"}
  ]
}

Phase 5 — Dry-run + apply

Run dry-run:

petrova request_review petrova-hq --input /tmp/petrova-onboard-<slug>.json

Show me the output verbatim — slug, key, branch (petrova/request-review/<key8>), file change list. If anything looks wrong (slug typo, contents missing the existing entries, etc.), do NOT apply; fix the JSON first.

When I say go ahead AND PETROVA_GITHUB_TOKEN is set, apply:

petrova request_review petrova-hq --input /tmp/petrova-onboard-<slug>.json --apply

Show me the PR URL. Stop. The PR landing closes Phase A of the onboarding — the slug becomes valid for the verb surface only after merge.

Phase 6 — (Optional) Bootstrap the consumer

If the readiness report in Phase 2 found that the consumer is missing control-loop docs (CLAUDE.md, AGENTS.xml, MILESTONES.md), point me at core/prompts/00-bootstrap.md: I should open a fresh Claude Code session in the consumer repo and run that prompt to generate the missing documents. Onboarding doesn’t bootstrap automatically — bootstrap is its own session because it needs the consumer’s spec docs in context, not the petrova-hq root.

If the consumer IS already petrova-shaped but its AGENTS.xml lacks the <capability id="petrova-act"> declaration, you can compose a second request_review PR adding the capability block (copy from core/templates/AGENTS.xml.tmpl). This is the only consumer-side change the onboarding can do remotely.

Failure modes

Slug already in registry → this is an update, not an onboard. Switch to opening a request_review PR that modifies the existing entry.
Consumer repo not locally cloned → ask me to clone first; the readiness report needs filesystem access.
PETROVA_GITHUB_TOKEN unset on apply step → stop, surface the error, ask me to set it.
Concurrent registry edit (someone else opened a PR first) → the apply may emit a PR with stale registry contents. Pull latest registry.yaml and re-compose the JSON.

What you do not do

Do not push registry edits directly; always go through request_review.
Do not assume profile=permissive to “make things easier” — defaulting to permissive on a production repo is a security regression.
Do not register a repo whose URL you cannot verify against a live git remote get-url origin.
Do not skip the readiness report — confirming the petrova-shape state before onboarding is what makes the onboarding boring.

After onboarding

Once the registry PR is merged, verify the repo is reachable via the verb surface:

petrova status                           # new slug appears
petrova diagnose <slug>                  # returns structured context
petrova validate <slug>                  # MR / convention compliance

If any of those error with REPO_NOT_IN_REGISTRY, the merge hasn’t propagated yet — pull the latest petrova-hq/main locally.