张宗平
53 lines
2.7 KiB
Markdown
53 lines
2.7 KiB
Markdown
# 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](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
|
|
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](new-skill-landing.md) — the six derived surfaces a *skill*
|
|
edit regenerates (the sibling discipline for the skills axis).
|
|
- [gate-hygiene.md](gate-hygiene.md) — pre-push diff-scope check + pre-existing-vs-mine
|
|
red triage that keeps a command-landing PR one-shot-green.
|