atdd

What it is and what it does

ATDD is a command-line platform that turns vague work intent into a structured, evidence-gated train of execution phases. It uses pytest, YAML manifests, and JSON schema validation to enforce a deterministic lifecycle—INIT → PLANNED → RED → GREEN → SMOKE → REFACTOR → COMPLETE → MERGED—keeping planning, testing, and code synchronized. The toolkit is designed for AI agents to operate safely within clear boundaries: agents decompose work via gated planning sessions (Intent → Attach → Compose → Ratify → Author), then execute through supervised phases with mandatory evidence gates and validator dispositions.

The package depends on pyyaml for configuration, pytest and pytest-xdist for test execution and parallelization, jsonschema for validation, pytest-html for reporting, pytest-github-actions-annotate-failures for CI integration, and radon for code metrics. It is a CLI-first tool that integrates with GitHub Issues, Project v2 fields, and git worktrees to manage per-issue runtime isolation and prevent merge chaos. The train metaphor—route, stations, cargo, tickets, signals, conductor—maps to planned paths, lifecycle phases, features, WMBTs and acceptance claims, validators and CI, and operator supervision.

Use it for:

• Decompose ambiguous feature requests into executable work units with mandatory planning gates before implementation begins.
• Run multiple AI agents on the same codebase without merge conflicts by isolating each issue in a worktree and enforcing sequential phase advancement.
• Enforce red-green-refactor discipline by gating code advancement on passing tests, smoke evidence, and validator verdicts before merge.
• Recover from interrupted agent sessions using JSONL event logs and resumable train runs.
• Sync validation rules across different LLM providers (Claude, Codex, Gemini, GLM) via managed blocks that preserve user content.
• Catch regressions before review by binding validator rules to issue IDs and enforcing per-rule dispositions.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

ATDD is a CLI toolkit that structures AI agent work into evidence-gated phases—planning, testing, implementation, validation, refactor, and merge—using pytest, YAML configuration, and JSON schema validation to enforce deterministic workflows.

Yes, if you are building AI-agent-driven development workflows and need deterministic phase enforcement, evidence gates, and supervisor control. The low install friction, active maintenance, and permissive license make it safe to adopt. No, if you need a library for embedding in existing Python applications—ATDD is a CLI-first platform designed for GitHub-integrated local workflows. Verify that the decomposition target (resumable runs, optional Temporal backends) and multi-agent testing are production-ready for your use case.

Install

atdd on PyPI

pip install atdd

uv add atdd

poetry add atdd

Installing atdd

Before you install

Low friction: pure Python wheel with seven runtime dependencies (pyyaml, pytest, pytest-xdist, pytest-github-actions-annotate-failures, jsonschema, pytest-html, radon). Active maintenance—released 5 days ago with commits through 2026-08-09. Requires Python 3.10+.

License in practice

MIT license (permissive): you may use, modify, and distribute ATDD freely in commercial and private projects, with no copyleft obligations.

Quickstart

pipx install atdd
atdd init
atdd gate
atdd plan start --id my-feature --main-job "What job is to be done?"
atdd plan advance --id my-feature --step attach

Requires Python 3.10 or later; designed for use with GitHub Issues, Project v2, and git worktrees—local CLI-first workflow, not a library for embedding.

Verify before relying

• Whether the 'decomposition target' (resumable train runs, Temporal/LangGraph backends) is implemented or planned-only.
• Whether agents other than Claude are actively tested or documented.
• Performance characteristics under concurrent multi-agent execution.
• Maturity of the validator system and rule-ID binding mechanism.

Package facts

Evidence: atdd-4.40.0-py3-none-any.whl

Tags

More Quality Assurance packages

Further reading