Skip to content

Mark CLI commands with stability metadata (stable/preview/experimental) in --help #95

@JRS1986

Description

@JRS1986

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

  1. Annotate each subparser with stability: stable | preview | experimental.
  2. 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
    
  3. Add a wiki page docs/docs/wiki/Stability.md defining what each marker promises (breaking-change policy, deprecation window, version where it became stable).
  4. 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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions