Core Concepts
ACDD Methodology

ACDD Methodology

Acceptance Criteria Driven Development (ACDD) is the methodology that fspec enforces to ensure AI agents build quality software reliably.

Forward ACDD Workflow (fspec)

💡 Use the zoom buttons (top right) or scroll wheel to zoom. Click and drag to pan.

Reverse ACDD Workflow (fspec reverse)

💡 Use the zoom buttons (top right) or scroll wheel to zoom. Click and drag to pan.

What is ACDD?

ACDD builds on Specification by Example and Behavior-Driven Development (BDD) by enforcing a rigorous workflow where acceptance criteria come FIRST, followed by tests, then code.

Building Blocks

Specification by Example

  • Use concrete examples instead of abstract requirements
  • "Login succeeds with email user@example.com and password 12345678"
  • NOT "The system shall authenticate users"

BDD (Behavior-Driven Development)

  • Adds Given/When/Then structure in Gherkin format
  • Scenarios become both documentation AND automated tests
  • Shared language between stakeholders and developers

ACDD (Acceptance Criteria Driven Development)

  • Enforces the ORDER: Acceptance Criteria (specs) FIRST → Tests SECOND → Code LAST
  • AI agents build exactly what's specified - no more, no less
  • Prevents over-implementation (features not specified) and under-implementation (missing criteria)

The ACDD Workflow

fspec enforces a 5-phase workflow:

1. Discovery (Example Mapping)

Purpose: Understand WHAT to build through collaborative discovery

Activities:

  • Capture business rules (yellow cards)
  • Gather concrete examples (green cards)
  • Ask clarifying questions (red cards)
  • Document assumptions (blue cards)

fspec Commands:

fspec add-rule AUTH-001 "Login requires valid email and password"
fspec add-example AUTH-001 "user@example.com with password 'secret123' succeeds"
fspec add-question AUTH-001 "Should we support OAuth providers?"
fspec add-assumption AUTH-001 "Password must be at least 8 characters"

Exit Criteria: All red cards (questions) answered

2. Specification (Gherkin)

Purpose: Convert examples into validated Gherkin scenarios

Activities:

  • Set user story (As a... I want... So that...)
  • Generate scenarios from examples
  • Validate Gherkin syntax
  • Add feature-level and scenario-level tags

fspec Commands:

fspec set-user-story AUTH-001 --role "user" --action "log in" --benefit "access my account"
fspec generate-scenarios AUTH-001
fspec validate
fspec add-tag-to-feature spec/features/user-login.feature @critical

Exit Criteria: All scenarios validated, no prefill placeholders

3. Testing Phase (TDD Red)

Purpose: Write tests that FAIL to prove they work

Activities:

  • Write tests mapping to Gherkin scenarios
  • Tests MUST fail (red phase)
  • Link tests to scenarios via coverage tracking
  • Document test-to-scenario mappings

fspec Commands:

fspec update-work-unit-status AUTH-001 testing
# Write tests in src/__tests__/auth.test.ts
fspec link-coverage user-login --scenario "Login with valid credentials" \
  --test-file src/__tests__/auth.test.ts --test-lines 45-62

Exit Criteria: All scenarios have failing tests

4. Implementation Phase (TDD Green)

Purpose: Write MINIMUM code to make tests pass

Activities:

  • Implement just enough code for tests to pass
  • Keep tests green (passing)
  • Refactor while maintaining green tests
  • Link implementation to test coverage

fspec Commands:

fspec update-work-unit-status AUTH-001 implementing
# Write implementation in src/auth/login.ts
fspec link-coverage user-login --scenario "Login with valid credentials" \
  --test-file src/__tests__/auth.test.ts \
  --impl-file src/auth/login.ts --impl-lines 10-24

Exit Criteria: All tests passing, coverage linked

5. Validation & Done

Purpose: Verify all acceptance criteria met

Activities:

  • Run full test suite (not just new tests)
  • Validate Gherkin still valid
  • Check coverage is complete
  • Quality gates pass

fspec Commands:

fspec update-work-unit-status AUTH-001 validating
fspec check  # Runs validate, validate-tags, format check
fspec show-coverage user-login
fspec update-work-unit-status AUTH-001 done

Exit Criteria: All checks pass, feature complete

Why This Order Matters

Specifications First

  • Know WHAT to build before building
  • Prevents scope creep and over-engineering
  • Enables collaborative clarification via Example Mapping

Tests Before Code

  • Proves tests work by failing first (red phase)
  • Ensures tests actually validate requirements
  • Prevents "tests that always pass"

Just Enough Code

  • Build exactly what's specified, no more
  • Reduces complexity and maintenance burden
  • Focuses effort on real requirements

The Challenge for AI Agents

AI agents naturally violate ACDD workflow without tooling:

  • ❌ Jump straight to implementation
  • ❌ Skip discovery and specification
  • ❌ Write code before tests
  • ❌ Build what THEY think is needed

fspec solves this by:

  • ✅ Enforcing workflow with state transitions
  • ✅ Blocking invalid transitions (can't skip phases)
  • ✅ Providing structured discovery tools
  • ✅ Requiring scenarios before testing phase
  • ✅ Validating specifications automatically

Example: Complete ACDD Workflow

Let's walk through a complete example:

# 1. DISCOVERY - Example Mapping
fspec create-work-unit AUTH "User login"
fspec update-work-unit-status AUTH-001 specifying
fspec add-rule AUTH-001 "Email must be valid format"
fspec add-example AUTH-001 "user@example.com succeeds"
fspec add-question AUTH-001 "Max login attempts?"
# Human answers: "5 attempts"
fspec answer-question AUTH-001 0 --answer "5 attempts"
 
# 2. SPECIFICATION - Gherkin
fspec set-user-story AUTH-001 --role "user" --action "log in" --benefit "access account"
fspec generate-scenarios AUTH-001
fspec validate
 
# 3. TESTING - TDD Red
fspec update-work-unit-status AUTH-001 testing
# Write failing tests
npm test  # Tests FAIL ✓
 
# 4. IMPLEMENTATION - TDD Green
fspec update-work-unit-status AUTH-001 implementing
# Write minimal code
npm test  # Tests PASS ✓
 
# 5. VALIDATION & DONE
fspec update-work-unit-status AUTH-001 validating
fspec check  # All checks pass ✓
fspec update-work-unit-status AUTH-001 done

Moving Backward

ACDD is iterative - you can move backward when needed:

# Discovered incomplete specs while testing
fspec update-work-unit-status AUTH-001 specifying
# Add missing scenarios
fspec update-work-unit-status AUTH-001 testing
 
# Quality checks failed in validation
fspec update-work-unit-status AUTH-001 implementing
# Fix code
fspec update-work-unit-status AUTH-001 validating

Key principle: Move backward to fix issues, don't create new work units for corrections.

Next Steps

Claude Code IntegrationKanban Workflow