initial: pi-setup workspace with skill + extension plan

2026-06-10 17:30:43 +08:00
commit 49e581247b
158 changed files with 28777 additions and 0 deletions
@@ -0,0 +1,52 @@
+# 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.