ai-native-cli

Agent-Friendly CLI Spec v0.1

When building or modifying CLI tools, follow these rules to make them safe and reliable for AI agents to use.

Core Philosophy

1. Agent-only -- output is always JSON, no human-friendly mode
2. Agent is untrusted -- validate all input at the same level as a public API
3. Fail-Closed -- when validation logic itself errors, deny by default
4. Verifiable -- every rule is written so it can be automatically checked

Layer Model

This spec now uses two orthogonal axes:

• Layer answers rollout scope: core, recommended, ecosystem
• Priority answers severity: P0, P1, P2

Use layers for migration and certification:

• core -- execution contract: JSON, errors, exit codes, stdout/stderr, safety
• recommended -- better machine UX: self-description, explicit modes, richer schemas
• ecosystem -- agent-native integration: agent/, skills, feedback, inline context

Certification maps to layers:

• Agent-Friendly -- all core rules pass
• Agent-Ready -- all core + recommended rules pass
• Agent-Native -- all layers pass

Output Mode

Output is always JSON. No human-friendly mode. No flags needed.

$ mycli list              # JSON output, always

• All output is JSON to stdout. Period.
• No --human, no --agent, no mode switching.
• If a human needs to read it, pipe through jq.

agent/ Directory Convention

Every CLI tool MUST have an agent/ directory at its project root. This is the tool's identity and behavior contract for AI agents.

agent/
├── brief.md          # One paragraph: who am I, what can I do
├── rules/            # Behavior constraints (auto-registered)
│   ├── trigger.md    # When should an agent use this tool
│   ├── workflow.md   # Step-by-step usage flow
│   └── writeback.md  # MANDATORY auto-feedback behavior
└── skills/           # Extended capabilities (auto-registered)
    └── getting-started.md

File Format

agent/brief.md — plain text, one paragraph. No frontmatter needed.