[abrichr]

Why

CAPABILITIES.md's "Every command, by capability" listed each capability's commands on one line. Any two pull requests that added commands to the same capability edited that line and conflicted. Each conflict meant another push and a full PR pipeline rerun (about 40 jobs). Since 2026-10-17, PR branches have made 17 commits to CAPABILITIES.md, not counting the PR merges themselves.

What changes

• One file per command: packages/flow/docs/commands/<group>/<verb>.md.
  • The group directory names the capability. Its README.md holds the title, and the numeric prefix sets the order.
  • A command's file is empty or holds a one-line note. Today only serve-reward and undo have notes.
  • Markdown keeps these files out of flow's artifact inventory, so adding a command adds no inventory row.
• scripts/build_command_map.py (--check) renders the list between generated markers in CAPABILITIES.md. It writes one command per line, sorted within each capability.
• packages/flow/tests/test_capabilities_map.py reads the command names from those files. It fails when:
  • an openadapt-flow command has no file;
  • a file names no command;
  • a command is listed in two capabilities;
  • the list in CAPABILITIES.md is out of date.
• CLAUDE.md now gives the new instruction for adding a command.

All 65 commands keep their current capability groups. Within a group, the list is now alphabetical instead of hand-ordered.

Verified

• tests/test_capabilities_map.py: 2 passed. With seal.md removed, both tests fail with an "add the file / run the script" message.
• scripts/check_release_consistency.py and the root tests/test_source_boundary.py: pass.
• I did not regenerate llms-full.txt. It is already stale on main, and refreshing it would pull in unrelated changes. The pre-release refresh picks this list up.

Savings

Two pull requests that each add a command now edit different files. They touch the same line of CAPABILITIES.md only when both commands land in the same capability and sort next to each other. That avoids a rebase and a full PR pipeline rerun (about 40 jobs) per collision.

Not covered

The hand-written map table rows above this list still conflict when two PRs add rows next to each other. Those rows are prose, not generated data, so I left them alone.

No changes to packages.yml, desktop-release.yml or main.yml.

🤖 Generated with Claude Code