ANCC

Agent-Native CLI Convention

ANCC is a contract for CLI tools that agents can safely run and compose. It standardizes install, JSON output, readiness checks, scope boundaries, and handoffs — so tools don't bloat into god-objects as agents evolve them.

Before and after

A normal CLI tool that an agent tries to use:

# Agent guesses flags from --help
$ mytool check --output json
unknown flag: --output

# Agent tries another guess
$ mytool check -f json
{"ok": true, "msg": "all good"}

# Agent has no idea what "ok" means structurally
# No exit code contract. No schema. No way to know what this tool won't do.
# Agent wraps it in a retry loop and hopes.

The same tool, ANCC-compliant:

# Agent reads SKILL.md — knows exact flags, output schema, exit codes
$ mytool check --format json
{
  "status": "healthy",
  "checks": [
    {"name": "config", "status": "pass", "message": "valid"},
    {"name": "database", "status": "pass", "message": "reachable"}
  ]
}
# Exit code 0 = all checks pass. Exit code 1 = failures found.
# SKILL.md declares: "Does not remediate — diagnosis only."
# Agent knows exactly what it got, what to trust, and what to hand off.

The difference: the agent never guesses. It reads the contract, runs the command, parses structured output, and acts. No plugins. No SDKs. One markdown file.

What ANCC is NOT

Not dashboards. Agents cannot squint at Grafana. They need structured output with exit codes.
Not AIOps. No ML anomaly detection. Deterministic tools with declared behavior.
Not agent tracing. This is not about observing agents. It is about building tools agents can observe with.
Not a framework. No runtime, no library, no dependency. A convention — six requirements and a markdown file.
Not unbounded self-improvement. Tools evolve under governed conventions with explicit scope boundaries.

What it prevents

Without scope constraints, agents optimize locally: nearest tool, cheapest modification, fastest path to green tests. After five iterations, your focused diagnostic tool also deploys, manages databases, sends alerts, and runs backups. That is uncontrolled growth — and it is the default outcome when agents modify tools.

ANCC prevents this structurally:

"What this does NOT do" is a required section with minimum 3 boundary statements. Enforced by ancc validate — the tool fails validation without it.
Scope pressure detection flags tools with 10+ commands — automatic signal that a tool needs splitting.
Handoff contracts force tools to declare where they stop and what comes next. Composition by design, not by accident.
30 validation checks run in CI on every push. Convention compliance is not optional — it is gated.

Quick start

# Install
brew install ppiankov/tap/ancc

# Create a complete tool project in 30 seconds
ancc scaffold my-scanner --type scanner
cd my-scanner && go mod tidy && make build

# Validate — must pass before the tool enters the ecosystem
ancc validate .
# 28 pass, 0 fail, 2 warn

The scaffolded project includes: Go binary, Makefile, CI workflows, docs/SKILL.md, tests, README with badge. It builds, tests pass, and validates on first run.

See Getting Started for the full walkthrough, or Tool Genesis for the full creation loop.

Tools

28+ tools following this convention across security, diagnostics, enforcement, and investigation.

chainwatch

AI agent execution control plane. Policy gates, approval workflows, audit logging.

vaultspectre

HashiCorp Vault secrets security auditor. One of 14 Spectre scanners, all ANCC-compliant.

pgpulse

PostgreSQL health diagnostics. Replication lag, connections, query performance.

clickpulse

ClickHouse heartbeat monitor. Merge pressure, stuck mutations, replica lag, replication discrepancies.

ancc

The validator itself. 30 checks across structure, semantics, and ecosystem fitness.

See Ecosystem for the full tool inventory, or Lifecycle for how tools are created, versioned, and retired.