iec-cli

Companion CLI and example repository for Intent Engineering for Coding Agents.

iec (Intent Engineering Checker) is the book's concrete example of how Intent Engineering conventions can be structured in a real repository. The CLI is real and usable, but this repo exists primarily as an illustrative companion to the book rather than as production-grade tooling.

Why

The book argues that coding agents need explicit structure: clear instructions, decision records, change-sized specs, and test traceability. iec exists to make that structure concrete. It gives a worked example of a repo that encodes those conventions and a CLI that checks for some of them deterministically.

Installation

Prerequisites

iec is a Python CLI.

• Python 3.12 or newer
• uv
• git if you want to clone this repository locally

You can verify your environment with:

python --version
uv --version
git --version

If python points to an older interpreter on your machine, install Python 3.12+ first, or let uv use a managed Python version.

Recommended: Install as a shell tool from GitHub

Use this if you want the simplest installation path and want iec available directly in your shell.

uv tool install git+https://github.com/intent-engineering-for-coding-agents/cli.git
iec --version

Notes:

• this installs iec directly from the GitHub repository
• after installation, iec should be available on your PATH
• if iec is already installed, rerun with uv tool install --force git+https://github.com/intent-engineering-for-coding-agents/cli.git

Option 1: Run from a local checkout

Use this if you want to explore the companion repository itself and run iec from the checked-out source.

git clone https://github.com/intent-engineering-for-coding-agents/cli.git intent-cli
cd intent-cli
uv sync
uv run iec --version

What this does:

• clones the repository
• installs the project and dependencies into the local .venv
• runs iec through uv run

Option 2: Install as a shell tool from a local checkout

Use this if you already cloned the repository and want iec available directly in your shell without the uv run prefix.

# From the repository root
uv tool install .
iec --version

Notes:

• uv tool install . installs the CLI from the current repository checkout
• after installation, iec should be available on your PATH
• if iec is already installed, uv tool install . may report that the executable already exists; in that case, rerun with uv tool install --force .

Verify the installation

Both installation paths should let you run:

iec --help
iec --version

If you are using the local checkout approach, use:

uv run iec --help
uv run iec --version

Quick start

From a local checkout:

# Scaffold the example Intent Engineering structure in the current repo
uv run iec init

# Run the companion checks
uv run iec check

If you installed iec as a tool:

iec init
iec check

On a freshly scaffolded repo, iec check currently exits with 1 and an advisory warning because docs/decisions/INDEX.md and docs/design/INDEX.md are not generated by iec init.

Checks

iec check currently runs 19 checks split across two maturity tiers. These checks show the kinds of repository conventions the book discusses; they should be read as the current behavior of the companion tool, not as production policy.

Maturity	Behaviour	Typical use
ci-enforced	FAIL → exit 2; blocks CI	Example hard gate for repos adopting these conventions
advisory	WARN → exit 1; non-blocking	Example local audit or periodic review

CI-enforced (hard gates)

Check	What it validates
agents-exists	AGENTS.md present at repo root
agents-size	AGENTS.md under N lines (TOC, not encyclopedia)
agents-hub-structure	.agents/ has instructions/ and skills/ subdirs
docs-readme-exists	docs/README.md present with architecture overview
adr-format	All ADRs follow MADR template
adr-index	docs/decisions/README.md lists all ADRs
spec-ac-ids	Every spec scenario has a [PREFIX-NNN] AC ID
spec-test-category	Every scenario has a Test-type: field
secrets	No plaintext secrets in tracked files
test-traceability	Every non-Manual AC ID has a @pytest.mark.<AC_ID> test
tasks-complete	Active change folder has no unchecked tasks before merge
change-archived	Completed change folders are archived, not left on trunk

Advisory (non-blocking)

Check	What it validates
agents-links	Links in AGENTS.md have descriptive text
docs-index-exists	Every docs/ subdirectory has an INDEX.md
docs-index-stale	INDEX.md entries match actual files
docs-index-scope	Each INDEX.md maps only its own directory
spec-size	Spec files under configurable line limit
file-size	All .md files under configurable line limit
test-coverage	Non-Manual ACs have positive + negative test proofs

See docs/checks.md for exit codes, configuration, and the current CI integration examples used by the companion tool.

Exit codes

Exit code	Meaning
0	All checks passed
1	Advisory warnings only
2	One or more hard failures

CI integration

If you want to wire the example checks into CI:

- name: Self-check (fail on errors, allow warnings)
  run: iec check; code=$?; [ $code -le 1 ]

Configuration

Environment variable	Default	Affects
ASE_AGENTS_MAX_LINES	50	agents-size
ASE_FILE_MAX_LINES	500	file-size, spec-size

Contributing

See CONTRIBUTING.md for setup, the spec-driven workflow, and how to add a new checker.

License

Apache 2.0. See LICENSE.