pi-skills/.agents/skills/evolve/references/ao-command-landing.md

AO-Command Landing — the surfaces a new ao command must regenerate

Adding (or renaming/removing) an ao command or subcommand touches more than the generated CLI reference. scripts/regen-all.sh regenerates the bulk of the derived surfaces, but it only WARNS about two that it cannot regenerate for you — those are the dominant fix-and-repush cause when landing a command. Regenerate them in the same pass before opening the PR, not piecemeal.

This is the command-surface parallel of new-skill-landing.md (the six derived surfaces a skill edit must regenerate).

The shortcut

scripts/regen-all.sh regenerates cli/docs/COMMANDS.md, registry.json, the skill/context maps, the embedded skills, and the cli-surface inventory in one pass — prefer it over running the individual generators. Then hand-fix the two surfaces it only warns about (below), and finally run scripts/regen-all.sh --check.

The two surfaces regen-all only WARNS about

1. Cobra expectedCmds (x2 lists) — cli/cmd/ao/cobra_commands_test.go hardcodes the registered-command list twice: once in TestCobraCommandTreeRegistration and once in TestCobraExpectedCmdsMatchRegistration (the second comment even says "Same list as TestCobraCommandTreeRegistration"). Both expectedCmds slices must gain the new top-level command name, or the second test fails with "registered command %q is not in expectedCmds — add it to keep the list in sync".

2. cli-command-surface heading counts — the generated reference's ao heading counts (top/sub/all) are asserted in two offline canaries that must move together:

   • evals/agentops-core/fixtures/cli-command-surface-smoke.sh — the top_count/sub_count/all_count literals (currently 76/192/268).
   • evals/agentops-core/cli-command-surface-matrix.json — the public canary that enumerates every documented command/subcommand help page.

   Run the smoke fixture to read the exact new counts rather than computing them by hand:

   bash evals/agentops-core/fixtures/cli-command-surface-smoke.sh
   # On a count mismatch it prints: unexpected command heading counts: top=.. sub=.. all=..
   # Update the literals in the fixture (and the matrix.json cases) to the printed values.
   

   (Automating this regen is tracked as ag-jy12.)

See also

• new-skill-landing.md — the six derived surfaces a skill edit regenerates (the sibling discipline for the skills axis).
• gate-hygiene.md — pre-push diff-scope check + pre-existing-vs-mine red triage that keeps a command-landing PR one-shot-green.