Problem
The CLI exposes ~54 commands across onboarding, sessions, memory, knowledge, context, skills, team sync, policy, evals, and tool adapters. Some are battle-tested (e.g. setup run, doctor); others are recent additions (e.g. context lint, parts of memory, parts of mcp). There is no signal in --help for which commands a team can depend on long-term vs. which are still moving.
Why it matters
Experienced devs and teams adopting the tool need to know what they can build infrastructure around. Without stability markers, every command looks equally final, which either over-promises ("we depend on this" → breakage later) or under-promises ("avoid the whole tool").
Proposed approach
- Annotate each subparser with
stability: stable | preview | experimental.
- Render the marker in
--help next to the command name:
COMMANDS (DAILY WORKFLOW):
session init [stable] create a reviewable session trace
memory capture [preview] capture a memory candidate for review
team push [experimental] propose changes back to a team manifest
- Add a wiki page
docs/docs/wiki/Stability.md defining what each marker promises (breaking-change policy, deprecation window, version where it became stable).
- CI test: every command has a stability marker, and the markers in
--help match the wiki table.
Acceptance criteria
- Every CLI command carries a stability marker rendered in
--help.
Stability.md defines the contract.
- CHANGELOG mentions changes that move a command between markers.
Problem
The CLI exposes ~54 commands across onboarding, sessions, memory, knowledge, context, skills, team sync, policy, evals, and tool adapters. Some are battle-tested (e.g.
setup run,doctor); others are recent additions (e.g.context lint, parts ofmemory, parts ofmcp). There is no signal in--helpfor which commands a team can depend on long-term vs. which are still moving.Why it matters
Experienced devs and teams adopting the tool need to know what they can build infrastructure around. Without stability markers, every command looks equally final, which either over-promises ("we depend on this" → breakage later) or under-promises ("avoid the whole tool").
Proposed approach
stability: stable | preview | experimental.--helpnext to the command name:docs/docs/wiki/Stability.mddefining what each marker promises (breaking-change policy, deprecation window, version where it became stable).--helpmatch the wiki table.Acceptance criteria
--help.Stability.mddefines the contract.