Skip to content

Conformance Levels

A CLI claims a level, not a percentage. Each level is a fixed set of requirements, and each higher level contains every lower one.

167 requirements are written for framework authors. A team retrofitting an existing Cobra, Click, or Clap tool needs a smaller first target that removes the failures agents hit on every call. Levels give that target and a way to state progress that other people can verify.

The three levels

Level Name Contains Size
1 Agent-safe basics The twelve requirements listed below 12
2 Agent-reliable Level 1 plus every other P0 requirement 51
3 Full spec Every requirement 167

Every requirement in requirements/index.md carries a Level column with the lowest level that includes it. scripts/validate_links.py recomputes the column from this file and the priorities, so the two cannot drift.

Level 1 — Agent-safe basics

A Level 1 CLI never hangs an agent, always answers in one parseable shape, and signals failure through codes rather than prose. These twelve requirements address the Critical failure modes an agent meets on almost every invocation: hangs (§10, §50), unparseable output (§2, §3, §8), ambiguous exit codes (§1), and destructive calls without a preview (§23).

Requirement Why it is in Level 1
REQ-F-001 Retry decisions start from a fixed exit code table
REQ-F-002 Exit 2 guarantees nothing was written, so fixing input and reissuing is safe
REQ-F-003 JSON activates in a non-TTY without the agent knowing a flag
REQ-F-004 One envelope shape for every command and outcome
REQ-F-006 stdout carries only the envelope
REQ-F-007 No escape codes corrupt the JSON
REQ-F-008 NO_COLOR and CI are honored
REQ-F-009 No prompt waits for input that never comes
REQ-F-010 No pager swallows output
REQ-F-048 Help text never lands in parsed stdout
REQ-C-004 Destructive commands can be previewed
REQ-C-013 Every error has a stable code

Claiming a level

  1. Implement every requirement in the level and verify its acceptance criteria
  2. Run the conformance kit with a profile that includes read, invalid, and destructive probes and, for Level 3, a manifest command and stream probes (one with signal)
  3. Publish the kit's ConformanceResult next to the claim

The kit verifies the mechanically checkable part of each level. A pass verdict is necessary, not sufficient: requirements such as locale-invariant serialization or secret redaction still need their acceptance criteria reviewed. A level verdict of incomplete means the profile lacked a probe kind, and the claim cannot be made until the missing checks run.

Document Relationship
requirements/index.md Aggregates: the Level column for every requirement
conformance/README.md Enforces: deterministic checks tagged with the level they verify
IMPLEMENTING.md Composes: goal-based paths and the wave plan order work within and across levels
§10 · §1 · §2 Consumes: the failure modes Level 1 eliminates first