AGENTS.md

1# cmd — Agent Contract
2 
3## Scope
4 
5This subtree owns executable entrypoints for SDP CLIs, lab tools, smoke runners,
6benchmarks, and operational utilities.
7 
8## Contract
9 
10Command packages should parse flags, validate inputs, call internal packages, and
11return clear exit codes. Business logic belongs under `internal/`.
12 
13## Dependencies
14 
15Commands may depend on internal packages and stdlib. Avoid duplicating logic
16between commands; extract shared behavior to an internal package when reuse is
17real and current.
18 
19## Runtime Assumptions
20 
21Commands run from a developer workstation, CI, or harness dispatch. Any command
22that writes files, calls external providers, executes subprocesses, or requires
23credentials must make that behavior visible in help text and docs.
24 
25## Local Rules
26 
27- Keep `main.go` thin: flag parsing, validation, invocation, exit.
28- Prefer explicit `--dry-run`, `--format json`, and evidence path flags for
29  automation-facing commands.
30- Do not make experimental or lab-only commands part of the stable release
31  surface without updating release-surface docs.
32- If command help and docs conflict, inspect code and update the canonical owner.
33