{"id":44907997,"url":"https://github.com/swingerman/atdd","last_synced_at":"2026-02-26T22:09:55.779Z","repository":{"id":338977133,"uuid":"1159560676","full_name":"swingerman/atdd","owner":"swingerman","description":"Acceptance Test Driven Development for Claude Code — inspired by Uncle Bob's approach from empire-2025","archived":false,"fork":false,"pushed_at":"2026-02-17T21:37:39.000Z","size":41,"stargazers_count":66,"open_issues_count":0,"forks_count":3,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-02-21T05:51:32.486Z","etag":null,"topics":["acceptance-testing","ai-development","atdd","bdd","claude-code","claude-code-plugin","given-when-then","spec-driven-design","tdd","uncle-bob"],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/swingerman.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-16T21:54:12.000Z","updated_at":"2026-02-20T19:18:56.000Z","dependencies_parsed_at":"2026-02-19T00:01:03.018Z","dependency_job_id":null,"html_url":"https://github.com/swingerman/atdd","commit_stats":null,"previous_names":["swingerman/atdd"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/swingerman/atdd","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swingerman%2Fatdd","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swingerman%2Fatdd/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swingerman%2Fatdd/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swingerman%2Fatdd/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/swingerman","download_url":"https://codeload.github.com/swingerman/atdd/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/swingerman%2Fatdd/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29704400,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-21T23:35:04.139Z","status":"online","status_checked_at":"2026-02-22T02:00:08.193Z","response_time":110,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["acceptance-testing","ai-development","atdd","bdd","claude-code","claude-code-plugin","given-when-then","spec-driven-design","tdd","uncle-bob"],"created_at":"2026-02-17T23:12:05.109Z","updated_at":"2026-02-26T22:09:55.760Z","avatar_url":"https://github.com/swingerman.png","language":"Shell","readme":"# ATDD — Acceptance Test Driven Development for Claude Code\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n[![Claude Code Plugin](https://img.shields.io/badge/Claude%20Code-Plugin-blueviolet)](https://github.com/swingerman/atdd)\n[![Version](https://img.shields.io/badge/version-0.3.0-green)](https://github.com/swingerman/atdd)\n\nA [Claude Code](https://code.claude.com) plugin that enforces the **Acceptance Test Driven Development** (ATDD) methodology when building software with AI. Write human-readable Given/When/Then specs before code, generate project-specific test pipelines, and maintain the discipline of two-stream testing.\n\n**Inspired by [Robert C. Martin's](https://en.wikipedia.org/wiki/Robert_C._Martin) (Uncle Bob) acceptance test approach from [empire-2025](https://github.com/unclebob/empire-2025).** The ideas, methodology, and key insights in this plugin come directly from his work and public writings on Spec Driven Design (SDD) and ATDD.\n\n## Why ATDD with AI?\n\nWhen using AI to write code, two problems emerge:\n\n1. **AI writes code without constraints** — without acceptance tests anchoring behavior, AI can \"willy-nilly plop code around\" (Uncle Bob's words) and write unit tests that pass but don't verify the right behavior.\n2. **Implementation details leak into specs** — AI naturally tries to fill Given/When/Then statements with class names, API endpoints, and database tables instead of domain language.\n\nThis plugin solves both problems by enforcing the ATDD workflow and guarding against implementation leakage. The result: **two test streams** (acceptance + unit) that constrain AI development, producing better-structured, more reliable code.\n\n\u003e \"The two different streams of tests cause Claude to think much more deeply about the structure of the code. It can't just willy-nilly plop code around and write a unit test for it. It is also constrained by the structure of the acceptance tests.\"\n\u003e — Robert C. Martin\n\n## How It Works\n\n```\n1. Write Given/When/Then specs (natural language, domain-only)\n                    ↓\n2. Generate test pipeline (parser → IR → test generator)\n   Pipeline has DEEP knowledge of your codebase internals\n                    ↓\n3. Run acceptance tests → they FAIL (red)\n                    ↓\n4. Implement with TDD (unit tests + code) until BOTH streams pass\n                    ↓\n5. Review specs for implementation leakage\n                    ↓\n6. Mutation testing → verify tests actually catch bugs\n                    ↓\n7. Iterate — next feature, back to step 1\n```\n\nThe generated pipeline is NOT like Cucumber. It's what Uncle Bob calls \"a strange hybrid of Cucumber and the test fixtures\" — the parser/generator has **deep knowledge of your system's internals** and produces complete, runnable tests. No manual fixture code needed.\n\n## Installation\n\nAdd the marketplace and install the plugin:\n\n```shell\n/plugin marketplace add swingerman/atdd\n/plugin install atdd@swingerman-atdd\n```\n\nOr test locally by cloning:\n\n```bash\ngit clone https://github.com/swingerman/atdd.git\nclaude --plugin-dir ./atdd\n```\n\n## Getting Started\n\n### 1. Start the ATDD workflow\n\n```\n/atdd:atdd Add user authentication with email and password\n```\n\nClaude will guide you through understanding the feature, then help you write acceptance specs.\n\n### 2. Write your first spec\n\nCreate a file in `specs/` at your project root:\n\n```\n;===============================================================\n; User can register with email and password.\n;===============================================================\nGIVEN no registered users.\n\nWHEN a user registers with email \"bob@example.com\" and password \"secret123\".\n\nTHEN there is 1 registered user.\nTHEN the user \"bob@example.com\" can log in.\n```\n\n### 3. Generate the test pipeline\n\nClaude analyzes your codebase and generates a project-specific parser, IR format, and test generator tailored to your language and test framework (pytest, Jest, JUnit, Go testing, RSpec, etc.).\n\n### 4. Red → Green → Refactor\n\nRun the acceptance tests (they should fail), then implement with TDD until both acceptance tests AND unit tests pass.\n\n### 5. Check for leakage\n\n```\n/atdd:spec-check\n```\n\nThe spec-guardian agent reviews your specs for implementation details that shouldn't be there.\n\n## Team-Based ATDD Workflow\n\nFor larger features, you can orchestrate an agent team that follows the ATDD workflow. The team lead coordinates specialist agents — each with a clear role and strict instructions.\n\n\u003e **Tip:** The plugin includes an `atdd-team` skill that automates team setup and orchestration. Just say \"build [feature] with a team\" and the skill handles role creation, phase sequencing, and prompt generation.\n\n### Works With Existing Teams\n\nAlready running an agent team? The `atdd-team` skill detects active teams and gives you three options:\n\n- **Extend** — Add ATDD roles (spec-writer, implementer, reviewer) to your existing team. Roles that already exist by name are skipped.\n- **Replace** — Shut down the current team and create a fresh ATDD team.\n- **New team** — Create a separate ATDD team alongside your existing one.\n\nThis means you can spin up a team for any purpose, then later say \"add ATDD to my team\" or \"extend my team with ATDD\" and the spec-writer, implementer, and reviewer roles join your existing teammates without disrupting ongoing work.\n\n### Team Roles\n\n| Role | Agent Type | Responsibility |\n|------|-----------|----------------|\n| **Team Lead** | You (or a `general-purpose` agent) | Orchestrates workflow, reviews specs, approves all work, enforces discipline |\n| **Spec Writer** | `general-purpose` | Writes Given/When/Then specs from feature requirements using domain language only |\n| **Implementer** | `general-purpose` | Builds code using TDD — unit tests first, then implementation — until both test streams pass |\n| **Spec Guardian** | `general-purpose` (read-heavy) | Reviews specs for implementation leakage before and after implementation |\n\n### Setting Up the Team\n\n**Prompt to create the team:**\n\n```\nCreate a team called \"atdd-feature\" with the following teammates:\n\n1. \"spec-writer\" (general-purpose) — Writes Given/When/Then acceptance\n   test specs. Has the atdd plugin installed. Must follow the /atdd:atdd\n   skill strictly.\n\n2. \"implementer\" (general-purpose) — Implements features using TDD.\n   Writes unit tests first, then code, until both acceptance tests and\n   unit tests pass.\n\n3. \"reviewer\" (general-purpose) — Reviews specs for implementation\n   leakage and reviews code for quality. Uses /atdd:spec-check.\n```\n\n### Step-by-Step: Team Lead Instructions\n\n#### Phase 1 — Spec Writing\n\nSend to **spec-writer**:\n\n```\nWe're implementing [feature description].\n\nFollow the ATDD workflow from the atdd plugin. Your job:\n\n1. Read the existing codebase to understand the domain language\n   (how does the app refer to users, orders, sessions, etc.?)\n2. Write Given/When/Then specs in specs/[feature-name].txt\n3. Use ONLY external observables — no class names, no API endpoints,\n   no database tables, no framework terms\n4. Each spec file starts with a semicolon comment block describing\n   the behavior\n5. Use periods at the end of each statement\n6. Send me the specs for review before proceeding\n\nCRITICAL: If you're unsure whether a term is domain language or\nimplementation language, ask me. Do NOT guess.\n\nExample of what I expect:\n\n;===============================================================\n; User can register with email and password.\n;===============================================================\nGIVEN no registered users.\n\nWHEN a user registers with email \"bob@example.com\" and password \"secret123\".\n\nTHEN there is 1 registered user.\nTHEN the user \"bob@example.com\" can log in.\n```\n\n#### Phase 2 — Spec Review\n\nSend to **reviewer**:\n\n```\nReview the specs in specs/[feature-name].txt for implementation leakage.\n\nFlag ANY of these:\n- Class names, function names, method names\n- Database tables, columns, queries\n- API endpoints, HTTP methods, status codes\n- Framework terms (controller, service, repository, middleware)\n- Internal state or data structures\n- File paths or module names\n\nFor each violation, show the bad line and propose a rewrite using\ndomain language only.\n\nAlso check:\n- Is each spec testing ONE behavior?\n- Are the GIVEN/WHEN/THEN statements clear to a non-developer?\n- Could these specs work for a different implementation language?\n\nSend me your review.\n```\n\n#### Phase 3 — Pipeline Generation\n\nAs team lead, do this yourself or instruct:\n\n```\nGenerate the test pipeline for this project. Analyze:\n- Language and test framework in use\n- Project structure and existing test patterns\n- The specs in specs/[feature-name].txt\n\nCreate the 3-stage pipeline:\n1. Parser — reads specs/*.txt, outputs IR to acceptance-pipeline/ir/\n2. Generator — reads IR, produces runnable tests in generated-acceptance-tests/\n3. Runner script — run-acceptance-tests.sh\n\nThe generator must have DEEP knowledge of the codebase internals.\nThis is NOT Cucumber. Generated tests should call directly into the\nsystem — no manual fixture glue.\n\nRun the acceptance tests after generation. They MUST fail (red).\nIf they pass, either the behavior already exists or the generator\nisn't testing the right thing.\n```\n\n#### Phase 4 — Implementation\n\nSend to **implementer**:\n\n```\nThe acceptance specs are in specs/[feature-name].txt.\nThe test pipeline is set up — run ./run-acceptance-tests.sh to execute.\n\nImplement the feature using TDD:\n\n1. Run acceptance tests first — confirm they FAIL\n2. Pick the simplest failing acceptance test\n3. Write a unit test for the smallest piece needed\n4. Write minimal code to make the unit test pass\n5. Refactor\n6. Repeat 3-5 until that acceptance test passes\n7. Move to the next failing acceptance test\n8. Continue until ALL acceptance tests AND unit tests pass\n\nRULES:\n- Never modify spec files (specs/*.txt) — they are the contract\n- Never modify generated test files — only regenerate via the pipeline\n- If a spec seems wrong or ambiguous, STOP and ask me\n- Run both test streams before reporting done:\n  ./run-acceptance-tests.sh  (acceptance tests)\n  [project test command]      (unit tests)\n- Send me the results when both streams are green\n```\n\n#### Phase 5 — Post-Implementation Review\n\nSend to **reviewer**:\n\n```\nImplementation is complete. Do two reviews:\n\n1. SPEC REVIEW: Run /atdd:spec-check on specs/[feature-name].txt\n   Check if any implementation details leaked into specs during\n   development. Propose cleanups if found.\n\n2. CODE REVIEW: Review the implementation for:\n   - Test quality (are unit tests testing the right things?)\n   - Code structure (does it match what the specs describe?)\n   - Missing edge cases (any specs that should be added?)\n\nSend me both reviews.\n```\n\n### Tips for Team Leads\n\n- **Never let implementers modify specs.** Specs are YOUR contract. If an implementer says a spec is wrong, review it yourself before authorizing changes.\n- **Run spec-check twice** — once before implementation (catch leakage from spec writing) and once after (catch leakage from implementation pressure).\n- **Keep specs portable.** Ask yourself: \"Could these specs generate the same feature in a different language?\" If not, there's leakage.\n- **Scope tightly.** Each team cycle should cover one feature. Don't spec the whole system — spec what you're building now.\n- **Verify both streams.** Before accepting the implementer's work, run both the acceptance tests and unit tests yourself.\n\n## Mutation Testing\n\nMutation testing adds a **third validation layer**: after acceptance tests verify WHAT and unit tests verify HOW, mutation testing verifies that your tests **actually catch bugs**.\n\nIt works by introducing deliberate bugs (mutants) into your source code and checking whether your tests detect them. A project with 100% code coverage can still have a 60% mutation score — meaning 40% of bugs would go undetected.\n\n```\nThree validation layers:\n1. Acceptance tests  → verify WHAT (external behavior)\n2. Unit tests        → verify HOW  (internal structure)\n3. Mutation testing  → verify REAL? (do tests catch bugs?)\n```\n\n### Quick Start\n\n```\n/atdd:mutate                    # run mutation testing\n/atdd:mutate src/auth/          # target specific module\n/atdd:kill-mutants              # write tests to kill survivors\n```\n\n### Supported Frameworks\n\nThe plugin auto-detects your language and configures the right tool:\n\n| Language | Framework |\n|----------|-----------|\n| JavaScript/TypeScript | [Stryker](https://stryker-mutator.io/) |\n| Python | [mutmut](https://github.com/boxed/mutmut) |\n| Java/JVM | [PIT](https://pitest.org/) |\n| C# | [Stryker.NET](https://stryker-mutator.io/) |\n| Rust | [cargo-mutants](https://github.com/sourcefrog/cargo-mutants) |\n| Go | [go-mutesting](https://github.com/zimmski/go-mutesting) |\n| Ruby | [mutant](https://github.com/mbj/mutant) |\n| Scala | [Stryker4s](https://stryker-mutator.io/) |\n\n### In the Team Workflow\n\nWhen using the `atdd-team` skill, mutation testing is **Phase 6** — run after post-implementation review, before declaring the feature done.\n\n## GWT Spec Format\n\nSpecs use an opinionated, human-readable Given/When/Then format:\n\n```\n;===============================================================\n; Description of the behavior being specified.\n;===============================================================\nGIVEN [precondition in domain language].\n\nWHEN [action the user/system takes].\n\nTHEN [observable outcome].\n```\n\n### The Golden Rule: External Observables Only\n\nSpecs must describe what the system does, not how it does it:\n\n| Bad (implementation leakage) | Good (domain language) |\n|------------------------------|----------------------|\n| `GIVEN the UserService has an empty userRepository.` | `GIVEN there are no registered users.` |\n| `WHEN a POST request is sent to /api/users with JSON body.` | `WHEN a new user registers with email \"bob@example.com\".` |\n| `THEN the database contains 1 row in the users table.` | `THEN there is 1 registered user.` |\n\n\u003e \"Specs will be co-authored by the humans and the AI, but with final approval, ferociously defended, by the humans.\"\n\u003e — Robert C. Martin\n\n## Plugin Components\n\n| Component | Name | Purpose |\n|-----------|------|---------|\n| Skill | `atdd` | Core 7-step ATDD workflow: specs → pipeline → red/green → iterate |\n| Skill | `atdd-team` | Orchestrates an agent team for ATDD — handles team setup, role assignment, and phase sequencing |\n| Skill | `atdd-mutate` | Mutation testing workflow — setup framework, run mutations, analyze and kill surviving mutants |\n| Agent | `spec-guardian` | Catches implementation leakage in Given/When/Then statements |\n| Agent | `pipeline-builder` | Generates bespoke parser → IR → test generator for your project |\n| Command | `/atdd:atdd` | Start the ATDD workflow for a new feature |\n| Command | `/atdd:spec-check` | Audit specs for implementation leakage |\n| Command | `/atdd:mutate` | Run mutation testing to verify test quality |\n| Command | `/atdd:kill-mutants` | Analyze surviving mutants and write tests to kill them |\n| Hook | PreToolUse | Soft warning when writing code without acceptance specs |\n| Hook | Stop | Reminder to verify both test streams pass |\n\n## Key Principles\n\nThese principles from Uncle Bob's writings are encoded in the plugin:\n\n- **\"Just enough specs for this sprint\"** — Don't write all specs upfront. Spec the current feature, implement it, iterate. Avoid Big Up-Front Design.\n- **\"Two test streams constrain development\"** — Acceptance tests define WHAT (external behavior), unit tests define HOW (internal structure). Both must pass.\n- **\"Specs describe only external observables\"** — No class names, API endpoints, database tables, or framework terms in specs. Domain language only.\n- **\"Co-authored by humans and AI, ferociously defended by humans\"** — Claude proposes specs, you approve them. Always.\n- **\"Small steps\"** — Whether your sprint is a day, an hour, or a microsecond, the same rules apply.\n\n## What This Is NOT\n\n- **Not Cucumber.** The generated pipeline has deep knowledge of your system's internals. No generic fixture layer that requires manual glue code.\n- **Not a template library.** Claude analyzes your project fresh every time and generates a bespoke pipeline for your language, framework, and codebase.\n- **Not Big Up-Front Design.** Write just enough specs for the current feature. Iterate.\n\n## Works With Any Language\n\nThe pipeline-builder agent analyzes your project and generates the parser/generator in your project's language and test framework. Tested approaches include Python/pytest, TypeScript/Jest, Java/JUnit, Go/testing, Ruby/RSpec, Clojure/Speclj, and more.\n\n## Attribution\n\nThis plugin is an implementation of Robert C. Martin's (Uncle Bob) Acceptance Test Driven Development and Spec Driven Design methodology for Claude Code. The approach, insights, and principles come from:\n\n- [empire-2025](https://github.com/unclebob/empire-2025) — Uncle Bob's project where this approach was developed and refined\n- His public writings and tweets on ATDD, SDD, and AI-assisted development\n\nThis plugin does not contain any code from empire-2025. It adapts the methodology for use as a Claude Code plugin.\n\n## Contributing\n\nContributions are welcome! Please open an issue or PR on [GitHub](https://github.com/swingerman/atdd).\n\n## License\n\n[MIT](LICENSE)\n\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fswingerman%2Fatdd","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fswingerman%2Fatdd","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fswingerman%2Fatdd/lists"}