From eafa097f8d110ec59282f967f8b268417e6b22bc Mon Sep 17 00:00:00 2001 From: Sahil Ahuja Date: Sat, 20 Jun 2026 19:27:38 +0530 Subject: [PATCH] docs: backfill SPEC mirrors for the two CLI partials Every src/kit/skills/*.md had a docs/specs/skills/SPEC-*.md twin except the two CLI reference partials. Backfill SPEC-_cli-fab.md and SPEC-_cli-external.md so the constitution's SPEC-mirror rule holds across the whole skills tree (the gap surfaced during the #440 optimization pass, which added TOCs to both partials with no mirror to update). Each SPEC follows the partial-SPEC shape (Summary + Command Inventory + Tools/Sub-agents) with a reference-catalog framing instead of a procedural Flow. The Command Inventory tables mirror each partial's ## section list exactly (23 rows for _cli-fab, 7 for _cli-external). --- docs/specs/skills/SPEC-_cli-external.md | 33 +++++++++++++++++ docs/specs/skills/SPEC-_cli-fab.md | 49 +++++++++++++++++++++++++ 2 files changed, 82 insertions(+) create mode 100644 docs/specs/skills/SPEC-_cli-external.md create mode 100644 docs/specs/skills/SPEC-_cli-fab.md diff --git a/docs/specs/skills/SPEC-_cli-external.md b/docs/specs/skills/SPEC-_cli-external.md new file mode 100644 index 00000000..6a662f19 --- /dev/null +++ b/docs/specs/skills/SPEC-_cli-external.md @@ -0,0 +1,33 @@ +# _cli-external + +## Summary + +External CLI tool reference — the non-fab command-line tools used for multi-agent coordination: **wt** (worktree manager), **idea** (backlog manager), **hop** (multi-repo navigator), **tmux**, **rk** (run-kit: context/iframe/proxy/visual-display + notify), and **/loop**. It is a hand-authored *gist* per tool — the operator-critical commands, flags, and integration semantics — and deliberately delegates each tool's exhaustive command/flag surface to that tool's own `help-dump` at use-time. Like `_cli-fab.md`, it is a **reference catalog**, not a procedure. + +This is an internal partial (`user-invocable: false`, `disable-model-invocation: true`, `metadata: internal: true`) — never invoked directly. It is **loaded by operator skills only** (not part of the always-load layer): `/fab-operator` declares `helpers: [_cli-fab, _cli-external]`. Carrying the `rk` and tmux detail here means only operator skills pay for it — every other skill still carries just the inline `rk` detection/fail-silent rule from `_preamble.md` § Run-Kit. Canonical source is the flat `src/kit/skills/_cli-external.md`; `fab sync` deploys it to `.claude/skills/_cli-external/SKILL.md`. + +> **No prior SPEC mirror existed** (260620): this file and `SPEC-_cli-fab.md` backfill the two missing CLI-partial mirrors so the constitution's SPEC-mirror rule holds across the whole `src/kit/skills/` tree. + +## Command Inventory + +One `##` section per tool (plus the framing Reference Model), mirroring the partial's section order. Each section documents the operator-critical surface of its tool, not the full command set. + +| Section | Covers | +|---------|--------| +| Reference Model | The hand-authored-gist-plus-`help-dump`-at-use-time convention; the universal silent-fail detection rule (`command -v `, skip silently when absent) shared by every external tool | +| wt (Worktree Manager) | Worktree create/list/remove; worktree directory naming (`{adjective}-{noun}`); the operator's spawn-in-worktree rules | +| idea (Backlog Manager) | Backlog entry management feeding the change pipeline (backlog IDs consumed by `_intake` Step 0) | +| hop (Multi-Repo Navigator) | Cross-repo navigation for the operator spanning multiple repos on one tmux server | +| tmux | Pane/session primitives the operator builds on (`send-keys`, session/pane addressing) layered under `fab pane` | +| rk (run-kit) | `rk context` (server-URL discovery, iframe windows, the proxy URL pattern, the Visual Display Recipe) and `rk notify` (the operator's default notification send) — the full body the `_preamble.md` § Run-Kit pointer forwards to | +| /loop | The recurring-interval driver the operator uses for its monitoring tick | + +> The inventory mirrors the file's `##` section order. `_preamble.md` § Run-Kit carries only the `rk` detection/fail-silent rule and points here for the command body; a change to either side must keep the pointer accurate (cross-reference rule), and by the mirror rule, this SPEC's corresponding row. + +### Tools used + +None — `_cli-external.md` is a reference document consumed by operator skills (looked up, not executed). The tools it documents are run by the consuming skills via Bash; the file itself defines no flow and runs nothing. + +### Sub-agents + +None. diff --git a/docs/specs/skills/SPEC-_cli-fab.md b/docs/specs/skills/SPEC-_cli-fab.md new file mode 100644 index 00000000..a8a5a9de --- /dev/null +++ b/docs/specs/skills/SPEC-_cli-fab.md @@ -0,0 +1,49 @@ +# _cli-fab + +## Summary + +Fab CLI command reference — the exhaustive companion to the **Common fab Commands** headline table in `_preamble.md`. The preamble documents the 6 most-used command families (`preflight`, `score`, `log command`, `change`, `resolve`, `status`); this partial documents everything else plus the full flag/argument surface, the calling convention, the extended `fab score` formula and `.status.yaml` schema details, and the common error messages. It is a **reference catalog**, not a procedure: skills look up command signatures here rather than running a defined flow. + +This is an internal partial (`user-invocable: false`, `disable-model-invocation: true`, `metadata: internal: true`) — never invoked directly. It is loaded selectively via a skill's `helpers: [_cli-fab]` frontmatter (per `_preamble.md` § Skill Helper Declaration); `/fab-operator` is its primary consumer (`helpers: [_cli-fab, _cli-external]`). Canonical source is the flat `src/kit/skills/_cli-fab.md`; `fab sync` deploys it to `.claude/skills/_cli-fab/SKILL.md`. + +> **No prior SPEC mirror existed** (260620): the two CLI-partial mirrors (`SPEC-_cli-fab.md`, `SPEC-_cli-external.md`) were missing while every other `src/kit/skills/*.md` had a `docs/specs/skills/SPEC-*.md` twin. This file backfills the gap so the constitution's SPEC-mirror rule (every skill/partial edit pairs with its mirror) holds across the whole `src/kit/skills/` tree. + +## Command Inventory + +The partial is organized as one `##` section per command (or command group), plus framing sections. Each documents the command's purpose, arguments, flags, and output contract. The `_preamble.md`-covered families (`change`, `status`, `score`, `preflight`, `log`, `resolve`) appear here in **extended** form — additional subcommands and exhaustive flag detail beyond the preamble headline. + +| Section | Covers | +|---------|--------| +| Calling Convention | How fab commands are invoked (paths relative to repo root), exit-code/stderr contract, the best-effort vs. fail-fast distinction | +| fab change (extended subcommand details) | Lifecycle subcommands beyond the preamble headline (`new`, `switch`, `rename`, `list`, `archive`, `restore`, `resolve`) | +| fab status (extended subcommand details) | State-machine subcommands beyond the headline (`finish`, `advance`, `start`, `reset`, `skip`, `fail`, `set-*`, `add-issue`, `add-pr`, …) and their state transitions | +| fab score (extended) | The confidence formula, the SRAD `.status.yaml` schema, `--check-gate` / `--stage` semantics, status-template details | +| fab preflight (extended) | The structured-YAML output fields and internal validation steps | +| fab log (extended) | Append-only `.history.jsonl` logging beyond the `log command` headline | +| fab resolve (extended) | Query flags (`--id` / `--folder` / `--dir` / `--status` / `--pane`) and canonical-output forms | +| fab resolve-agent | Per-stage model/effort tier resolution (`` → tier → `{model, effort}`); `--alias` for the Agent-tool short alias | +| fab hook | Claude Code hook subcommands (PostToolUse artifact hooks, etc.) | +| fab pane | Tmux pane operations (`map`, `--all-sessions`, `--json`) used by the operator | +| fab doctor | Prerequisite validation | +| fab migrations-status | Which migrations apply between local and engine versions | +| fab kit-path | Resolve the kit directory path (`$(fab kit-path)/templates/…`) | +| fab shell-init | Emit the shell-completion script | +| fab impact | Git diff line-count math (added/deleted/net) between two refs | +| fab pr-meta | Render a fab PR's `## Meta` block as final markdown | +| fab memory-index | Deterministically (re)generate `docs/memory/` index + log files | +| fab fab-help | The workflow overview / command summary (backs `/fab-help`) | +| fab help-dump | Machine-readable command dump | +| fab operator | Launch the operator in a dedicated tmux tab (singleton); degraded-behavior contract | +| fab spawn-command | Print a repo's configured agent spawn command | +| fab batch | Multi-target batch operations | +| Common Error Messages | The shared error strings and their meanings | + +> The inventory mirrors the file's `##` section order. When a command's signature changes, the constitution requires updating `_cli-fab.md` **and** its consumers' tests — and, by the mirror rule, this SPEC's corresponding row. + +### Tools used + +None — `_cli-fab.md` is a reference document consumed by skills (looked up, not executed). The commands it documents are run by the consuming skills via Bash; the file itself defines no flow and runs nothing. + +### Sub-agents + +None.