Skill — add-cli-command

When to use this skill

• Adding a new doctrina <command> or a subcommand to an existing one.
• Renaming/removing a command, or changing its flags or summary line.

Procedure

The surface is named in exactly one place; everything else is generated or gate-checked from it. Touch the steps in this order:

1. Implement the handler in packages/doctrina-cli/src/commands/<command>.js (subcommands go in the existing file's dispatch switch). Update its help export: a Usage line that enumerates subcommands names every one in SUBCOMMANDS, and every flag in the module's flags declaration is described in the help — test/o-help-lista-todo-subcomando.test.js fails otherwise. A flag a command reads more than once (--op a --op b) is read with flagAll; flagString keeps only the last value.
2. Register the operation in OPERATIONS in packages/doctrina-cli/src/lib/commands.js (workflow order, not alphabetical). Top-level --help is generated from this list. A new top-level command also goes in COMMAND_NAMES and in the imports + COMMANDS map of packages/doctrina-cli/src/index.js.
3. Add the command line to the ## Commands block of the root AGENTS.md — the hub agents read first. It is capped at 150 lines: fold read-only siblings into a comment (`spec list` lists them) rather than exceeding the cap.
4. Document it in docs/en/cli-reference.md AND docs/pt/cli-reference.md in the same change (see the keep-docs-en-pt-parity skill): a ## doctrina <op> heading in backticks, a one-paragraph description, a fenced example, a flags table.
5. Add/extend tests: behaviour in packages/doctrina-cli/test/integration.test.js; the drift tests in packages/doctrina-cli/test/commands.test.js (catalog ↔ dispatch ↔ help ↔ docs) fail loudly if steps 2–4 were skipped — run them first when in doubt.
6. Update the operation count in docs/en/README.md / docs/pt/README.md ("27 commands, NN operations") and the surface list in .doctrina/specs/cli/spec.md (gate semantics belong in .doctrina/specs/gates/spec.md). Then doctrina spec set cli --bump minor.
7. Write the CHANGELOG entry. A new or renamed command IS a documented surface change, so close refuses without one — and it asks a different question from the docs: the reference says how the command works, the changelog says that it appeared. Add it under the unreleased heading.
8. Gates: node --test inside packages/doctrina-cli/, then doctrina validate (AGENTS.md drift gate) at the repo root.

Anti-patterns

• Shipping a working subcommand that --help never mentions. It happened: spec set and change abandon were implemented, spec'd, and invisible in help/AGENTS.md/docs for multiple releases — nobody discovers them. It happened again with the Documented surface: declaration, which shipped into the code and the CLI reference and into neither the proposal template nor the refusal that needed it.
• Documenting a command in a diagram (docs/en/flow.md) but giving it no cli-reference section: readers see it exists but cannot learn it.
• Adding a subcommand to the dispatcher and the help BODY but not to the Usage line, or declaring a flag the help never names (delivery tick, work --delivery in 0.20.0): the first line a reader sees describes a smaller command than the one that runs.
• A command that rewrites a file the person owns (a tick, a header stamp) writing LF into a CRLF file. Read the ending with eolOf and write back with withEol (lib/fs-ops.js), and test it from a CRLF fixture: a Linux run never sees the bug.
• Updating the EN docs and leaving PT for "later".

Related material

• packages/doctrina-cli/src/lib/commands.js — the canonical surface.
• .doctrina/specs/cli/spec.md — the surface contract.
• ADR 0010 (adoption ergonomics); the v0.10.0 CHANGELOG entry (hub-freshness gate).