Requirements Index
All requirements for an agent-compatible CLI framework, derived from the CLI Agent Spec's 73 documented failure modes.
155 total | 78 Framework-Automatic · 29 Command Contract · 48 Opt-In — amended 2026-05-09
By priority: P0: 51 · P1: 62 · P2: 33 · P3: 9 — REQ-O-048 added: destructive commands default to dry-run mode (§75)
Framework-Automatic (F)
78 requirements | P0: 33 · P1: 29 · P2: 15 · P3: 1
| ID | Priority | Title | Failure mode(s) |
|---|---|---|---|
| REQ-F-001 | P0 | Standard Exit Code Table | §1 |
| REQ-F-002 | P0 | Exit Code 2 Reserved for Validation Failures | §1 §14 |
| REQ-F-003 | P0 | JSON Output Mode Auto-Activation | §2 |
| REQ-F-004 | P0 | Consistent JSON Response Envelope | §2 |
| REQ-F-005 | P0 | Locale-Invariant Serialization | §2 |
| REQ-F-006 | P0 | Stdout/Stderr Stream Enforcement | §3 |
| REQ-F-007 | P0 | ANSI/Color Code Suppression | §8 |
| REQ-F-008 | P0 | NO_COLOR and CI Environment Detection | §8 |
| REQ-F-009 | P0 | Non-Interactive Mode Auto-Detection | §10 |
| REQ-F-010 | P0 | Pager Suppression | §10 |
| REQ-F-011 | P0 | Default Timeout Per Command | §11 |
| REQ-F-012 | P0 | Timeout Exit Code and JSON Error | §11 |
| REQ-F-013 | P0 | SIGTERM Handler Installation | §16 |
| REQ-F-014 | P0 | SIGPIPE Handler Installation | §16 |
| REQ-F-015 | P0 | Validate-Before-Execute Phase Order | §14 |
| REQ-F-016 | P1 | UTF-8 Sanitization Before Serialization | §9 |
| REQ-F-017 | P1 | Binary Field Base64 Encoding | §9 |
| REQ-F-018 | P0 | Pagination Metadata on List Commands | §5 |
| REQ-F-019 | P0 | Default Output Limit | §5 |
| REQ-F-020 | P2 | Stable Array Sorting in JSON Output | §7 |
| REQ-F-021 | P1 | Data/Meta Separation in Response Envelope | §7 |
| REQ-F-022 | P1 | Schema Version in Every Response | §22 |
| REQ-F-023 | P1 | Tool Version in Every Response | §22 §32 |
| REQ-F-024 | P2 | Request ID and Trace ID in Every Response | §33 |
| REQ-F-025 | P2 | TOOL_TRACE_ID Environment Variable Propagation | §33 |
| REQ-F-026 | P2 | Append-Only Audit Log | §33 |
| REQ-F-027 | P2 | CWD in Response Meta | §29 |
| REQ-F-028 | P1 | Config Source Tracking in Response Meta | §28 |
| REQ-F-029 | P1 | Auto-Update Suppression in Non-Interactive Mode | §32 |
| REQ-F-030 | P2 | Child Process Session Tracking | §17 |
| REQ-F-031 | P2 | SIGTERM Forwarding to Tracked Children | §17 |
| REQ-F-032 | P2 | Session-Scoped Temp Directory | §15 |
| REQ-F-033 | P2 | Lock Acquisition with Timeout and retry_after_ms | §15 |
| REQ-F-034 | P1 | Secret Field Auto-Redaction in Logs | §24 |
| REQ-F-035 | P1 | External Data Trust Tagging | §25 |
| REQ-F-036 | P1 | HTTP Client Proxy Environment Variable Compliance | §31 |
| REQ-F-037 | P1 | Network Error Context Block | §31 |
| REQ-F-038 | P2 | Verbosity Auto-Quiet in Non-TTY Context | §4 |
| REQ-F-039 | P1 | Duration Tracking in Response Meta | §11 §33 |
| REQ-F-040 | P2 | Absolute Path Output Enforcement | §29 |
| REQ-F-041 | P2 | Process CWD Immutability | §29 |
| REQ-F-042 | P3 | Log Rotation in Framework Logger | §30 |
| REQ-F-043 | P2 | Temp File Session-Scoped Auto-Cleanup | §30 |
| REQ-F-044 | P0 | Shell Argument Escaping Enforcement | §34 |
| REQ-F-045 | P0 | Agent Hallucination Input Pattern Rejection | §35 |
| REQ-F-046 | P0 | Pager Environment Variable Suppression | §10 |
| REQ-F-047 | P0 | REPL Mode Prohibition in Non-TTY Context | §37 |
| REQ-F-048 | P0 | Help Output Routing to Stderr in Non-TTY Mode | §3 |
| REQ-F-049 | P1 | Async Command Handler Enforcement | §40 |
| REQ-F-050 | P1 | Update Notifier Side-Channel Suppression | §41 |
| REQ-F-051 | P0 | Debug and Trace Mode Secret Redaction | §42 |
| REQ-F-052 | P0 | Response Size Hard Cap with Truncation Indicator | §43 |
| REQ-F-053 | P0 | Stdout Unbuffering in Non-TTY Mode | §60 |
| REQ-F-054 | P0 | Stdin Payload Size Cap with --input-file Fallback | §61 |
| REQ-F-055 | P0 | $EDITOR and $VISUAL No-Op in Non-TTY Mode | §62 |
| REQ-F-056 | P0 | Terminal Width Wrapping Disabled in JSON Mode | §63 |
| REQ-F-057 | P0 | Headless Environment Detection and GUI Suppression | §64 |
| REQ-F-058 | P1 | High-Entropy Field Masking | §59 |
| REQ-F-059 | P1 | JSON5 Input Normalization | §67 |
| REQ-F-060 | P1 | Third-Party Stdout Interception | §68 |
| REQ-F-061 | P1 | Symlink Loop Detection in Traversal Utilities | §66 |
| REQ-F-062 | P0 | Glob Expansion and Word-Splitting Prevention | §51 |
| REQ-F-063 | P1 | Credential Expiry Structured Error | §53 |
| REQ-F-064 | P1 | Output Truncation Detection and Warning | §55 |
| REQ-F-065 | P0 | Pipeline Exit Code Propagation | §56 |
| REQ-F-066 | P1 | Subprocess Locale Normalization | §57 |
| REQ-F-067 | P1 | Interspersed Option Parsing | §69 |
| REQ-F-068 | P0 | Help and Version Flag Purity | — |
| REQ-F-069 | P0 | SIGINT Handler Installation | §16 |
| REQ-F-070 | P1 | Atomic Write via Rename | §15 |
| REQ-F-071 | P1 | File Descriptor Leak Prevention | §17 |
| REQ-F-072 | P1 | LF Line Ending Enforcement | — |
| REQ-F-073 | P1 | Environment Variable Namespace Prefix | §65 |
| REQ-F-074 | P1 | JSON Null/Absent/Empty Convention | §2 |
| REQ-F-075 | P1 | Subcommand Additive Stability | §22 |
| REQ-F-076 | P1 | First-Run Init Isolation | — |
| REQ-F-077 | P2 | Telemetry Non-Blocking | §41 |
| REQ-F-078 | P2 | Retry Count in Response Meta | §11 |
Command Contract (C)
29 requirements | P0: 12 · P1: 14 · P2: 1 · P3: 2
| ID | Priority | Title | Failure mode(s) |
|---|---|---|---|
| REQ-C-001 | P0 | Command Declares Exit Codes | §1 |
| REQ-C-002 | P0 | Command Declares Danger Level | §23 |
| REQ-C-003 | P0 | Mutating Commands Declare effect Field | §12 |
| REQ-C-004 | P0 | Destructive Commands Must Support --dry-run | §23 |
| REQ-C-005 | P0 | Interactive Commands Must Support --yes / --non-interactive | §10 |
| REQ-C-006 | P0 | All Args Validated in Phase 1 | §14 |
| REQ-C-007 | P1 | Mutating Commands Accept --idempotency-key | §12 |
| REQ-C-008 | P1 | Multi-Step Commands Emit Step Manifest | §13 |
| REQ-C-009 | P1 | Multi-Step Commands Report completed/failed/skipped | §13 |
| REQ-C-010 | P2 | Background-Process Commands Declare Metadata | §17 |
| REQ-C-011 | P3 | Commands Declare Filesystem Side Effects | §30 |
| REQ-C-012 | P0 | Commands with Network I/O Support --timeout | §11 |
| REQ-C-013 | P0 | Error Responses Include Code and Message | §18 |
| REQ-C-014 | P1 | Error Responses Include retryable and retry_after_ms | §19 |
| REQ-C-015 | P1 | Commands Declare Input and Output Schema | §21 |
| REQ-C-016 | P1 | Secrets Accepted Only via Env Var or File | §24 |
| REQ-C-017 | P1 | Commands Register cleanup() Hook | §16 |
| REQ-C-018 | P3 | Commands Declare Platform Requirements | §27 |
| REQ-C-019 | P1 | Subprocess-Invoking Commands Declare Argument Schema | §34 |
| REQ-C-020 | P1 | Resource ID Fields Declare Validation Pattern | §35 |
| REQ-C-021 | P0 | Auth Commands Declare Headless Mode Support | §45 |
| REQ-C-022 | P0 | Async Commands Declare Job Descriptor Schema | §49 |
| REQ-C-023 | P1 | Editor-Requiring Commands Declare Non-Interactive Alternative | §62 |
| REQ-C-024 | P1 | GUI-Launching Commands Declare Headless Behavior | §64 |
| REQ-C-025 | P0 | Config-Writing Commands Declare Write Scope | §65 |
| REQ-C-026 | P1 | Commands Declare Conditional Argument Dependencies | §54 |
| REQ-C-027 | P1 | Commands Declare Option Placement Convention | §69 |
| REQ-C-028 | P1 | ALREADY_EXISTS Response Pattern | §12 |
| REQ-C-029 | P0 | Command Declares Required Scopes | §74 |
Opt-In (O)
48 requirements | P0: 6 · P1: 19 · P2: 17 · P3: 6
| ID | Priority | Title | Failure mode(s) |
|---|---|---|---|
| REQ-O-001 | P0 | --output Format Flag | §2 |
| REQ-O-002 | P2 | --fields Selector | §4 |
| REQ-O-003 | P0 | --limit and --cursor Pagination Flags | §5 |
| REQ-O-004 | P2 | --output jsonl / --stream Flag | §5 |
| REQ-O-005 | P3 | --output id Extraction Mode | §6 |
| REQ-O-006 | P3 | Stdin as ID Source (-) | §6 |
| REQ-O-007 | P3 | --stable-output Flag | §7 |
| REQ-O-008 | P1 | --quiet / --verbose / --debug Verbosity Flags | §4 |
| REQ-O-009 | P1 | --validate-only Flag | §14 |
| REQ-O-010 | P2 | --resume-from Flag for Multi-Step Commands | §13 |
| REQ-O-011 | P2 | --rollback-on-failure Flag | §13 |
| REQ-O-012 | P2 | --heartbeat-interval Flag | §11 |
| REQ-O-013 | P1 | --schema / --output-schema Flag | §21 |
| REQ-O-014 | P2 | --schema-version Compatibility Flag | §22 |
| REQ-O-015 | P1 | --show-config Flag | §28 |
| REQ-O-016 | P1 | --no-config Flag | §28 |
| REQ-O-017 | P2 | --cwd / --root Flag | §29 |
| REQ-O-018 | P3 | --no-cache and --cache-ttl Flags | §30 |
| REQ-O-019 | P2 | --proxy and --no-proxy Flags | §31 |
| REQ-O-020 | P1 | --no-update-check Flag | §32 |
| REQ-O-021 | P0 | --confirm-destructive Flag | §23 |
| REQ-O-022 | P1 | --secret-from-env / --secret-from-file Flags | §24 |
| REQ-O-023 | P3 | --no-injection-protection Flag | §25 |
| REQ-O-024 | P1 | --context / --config Override Flag | §26 |
| REQ-O-025 | P3 | --warnings-as-errors Flag | §3 |
| REQ-O-026 | P1 | tool doctor Built-In Command | §20 |
| REQ-O-027 | P2 | tool cleanup Built-In Command | §30 |
| REQ-O-028 | P2 | tool status Built-In Command | §26 §30 |
| REQ-O-029 | P2 | tool changelog Built-In Command | §22 |
| REQ-O-030 | P2 | tool audit-log Built-In Command | §33 |
| REQ-O-031 | P1 | Dependency Version Matrix Declaration | §38 |
| REQ-O-032 | P1 | --raw-payload Flag for Mutating Commands | §46 |
| REQ-O-033 | P0 | --headless and --token-env-var Flags for Auth Commands | §45 |
| REQ-O-034 | P2 | tool generate-skills Built-In Command | §44 |
| REQ-O-035 | P2 | tool mcp-validate Built-In Command | §47 |
| REQ-O-036 | P1 | --instance-id Flag for Agent State Namespacing | §58 |
| REQ-O-037 | P2 | --unmask Flag for High-Entropy Fields | §59 |
| REQ-O-038 | P1 | --heartbeat-ms Flag for Long-Running Commands | §60 §49 |
| REQ-O-039 | P1 | --input-file Flag for Stdin Commands | §61 §50 |
| REQ-O-040 | P1 | --no-follow-symlinks Flag for Traversal Commands | §66 |
| REQ-O-041 | P1 | tool manifest Built-In Command | §52 |
| REQ-O-042 | P2 | Output Format Environment Variable Default | §2 |
| REQ-O-043 | P1 | AGENTS.md Required Content | §44 §73 |
| REQ-O-044 | P1 | Non-Interactive Install Command Documentation | §71 |
| REQ-O-045 | P1 | Integration Artifact Version Declaration | §72 §47 |
| REQ-O-046 | P2 | AGENTS.md CI Validation | §73 §44 |
| REQ-O-047 | P0 | tool check-permissions Built-In Command | §74 |
| REQ-O-048 | P0 | Destructive Commands Default to Dry-Run Mode | §75 |
CLI Agent Spec v1.6 — 154 requirements (78 REQ-F + 29 REQ-C + 47 REQ-O). Updated 2026-05-07.