atdd-kit

atdd-kit

日本語

Run your development process with ATDD (Acceptance Test Driven Development) — a structured, test-first path from Issue to merge.

A Claude Code plugin that gives you a complete workflow: create an Issue, explore requirements, derive acceptance criteria, write tests first, implement, review, and merge.

Why atdd-kit?

AI coding assistants can write code, but they lack a structured development process. Without guardrails, they skip requirements exploration, write code before tests, and merge without verification.

atdd-kit solves this by enforcing an Issue-driven, test-first workflow:

• Every change starts with an Issue — no code without a tracked requirement
• Acceptance criteria are derived through dialogue — not assumed
• Tests are written before implementation — ATDD double loop (E2E first, then unit tests)
• Evidence-based verification — every AC is verified with test results before merge

Design principles: zero dependencies, plugin architecture, pure markdown + bash.

A 6-step flow carries each Issue from requirements to deploy: define requirements → extract user stories → write the plan + acceptance tests → run the ATDD cycle → review → merge & deploy. Each step is a skill you invoke directly, and the review step runs a dynamic lens panel in parallel to check every deliverable before merge.

The ATDD Double Loop

atdd-kit implements the Double-Loop TDD model from Freeman & Pryce's Growing Object-Oriented Software, Guided by Tests (2009):

┌─ Outer Loop: Acceptance Test ─────────────────────┐
│                                                     │
│  RED       Write a failing end-to-end test          │
│                                                     │
│    ┌─ Inner Loop: Unit Test ────────────────────┐   │
│    │  RED       Write a failing unit test        │   │
│    │  GREEN     Minimal implementation           │   │
│    │  REFACTOR                    ↻ repeat       │   │
│    └─────────────────────────────────────────────┘   │
│                                                     │
│  GREEN     Acceptance test passes                   │
│  REFACTOR                                           │
└─────────────────────────────────────────────────────┘

Also influenced by:

• ATDD by Example (Markus Gärtner, 2012) — The practical ATDD guide that popularized the term "ATDD"
• obra/superpowers — Process enforcement patterns (Red Flags, <HARD-GATE>, Iron Laws)
• BDD (Dan North) — Given/When/Then acceptance criteria format

Quick Start

# 1. Register the marketplace (first time only)
claude plugins marketplace add https://github.com/o3-ozono/atdd-kit.git

# 2. Install (project scope recommended)
claude plugins install atdd-kit --scope project

Setup happens automatically on the first session. The session-start skill auto-detects your platform (iOS, Web, Other), shows what will be installed, and asks for confirmation. You can also run setup commands manually (/atdd-kit:setup-github, /atdd-kit:setup-ios, etc.). See Getting Started — What Each Addon Installs for details.

Then describe what you want to build — atdd-kit handles the rest.

See Getting Started for a full end-to-end walkthrough.

How It Works

flowchart LR
  bug["bug (auto)"] --> dr
  dr["defining-requirements"] --> us["extracting-user-stories"]
  us --> plan["writing-plan-and-tests"]
  plan --> atdd["running-atdd-cycle"]
  atdd --> review["reviewing-deliverables"]
  review --> ship["merging-and-deploying"]

Skills

Core Workflow (6 steps)

Step	Skill	What it does
1	defining-requirements	Explore requirements through dialogue, derive Given/When/Then acceptance criteria, produce the PRD
2	extracting-user-stories	Derive user stories from the PRD
3	writing-plan-and-tests	Create a test-first implementation plan plus the acceptance tests
4	running-atdd-cycle	Execute the ATDD double loop — outer acceptance tests, inner unit tests
5	reviewing-deliverables	Review every deliverable (PRD/US/Plan/Code/AT) with a dynamic lens panel × parallel Workflow (#234) and produce a single PASS/FAIL
6	merging-and-deploying	Merge → deploy → re-run regression acceptance tests post-deploy

On-demand