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