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)

Reverse ACDD Workflow (fspec reverse)

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)

How to use:

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

Your AI agent runs the fspec commands behind the scenes. Just talk naturally!

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

How to use:

User: Set the user story for AUTH-001: As a user I want to log in So that I can access my account
User: Generate scenarios from the example map for AUTH-001
User: Validate the Gherkin syntax
User: Add @critical tag to the user-login feature

Your AI agent runs the fspec commands behind the scenes. Just talk naturally!

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

How to use:

User: Move AUTH-001 to testing
User: Write tests for the "Login with valid credentials" scenario
User: Link the test coverage for "Login with valid credentials" in user-login feature

Your AI agent writes the tests and runs the fspec commands behind the scenes. Just talk naturally!

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

How to use:

User: Move AUTH-001 to implementing
User: Implement the login functionality to make the tests pass
User: Link the implementation coverage for the "Login with valid credentials" scenario

Your AI agent writes the code and runs the fspec commands behind the scenes. Just talk naturally!

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

How to use:

User: Move AUTH-001 to validating
User: Run all validation checks
User: Show me the coverage report for user-login
User: Move AUTH-001 to done

Your AI agent runs the fspec commands behind the scenes. Just talk naturally!

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

ACDD Enforcement & Quality Gates

fspec enforces ACDD discipline through automated quality gates that prevent common anti-patterns. These enforcement mechanisms ensure work is done IN the correct sequence, not BEFORE entering states.

Temporal Ordering Validation

What It Is: Temporal ordering validation prevents retroactive state walking - doing all the work first, then moving through states as theater. It compares file modification timestamps against state entry timestamps to ensure work happens in the correct sequence.

When It Triggers:

  • Moving to testing state: Feature files must be created/modified AFTER entering specifying
  • Moving to implementing state: Test files must be created/modified AFTER entering testing

Example Error:

$ fspec update-work-unit-status AUTH-001 testing
✗ ACDD temporal ordering violation detected!
 
Feature files were created/modified BEFORE entering specifying state.
 
Violations:
  - spec/features/user-auth.feature
    File modified: 2025-01-15T09:00:00.000Z
    Entered specifying: 2025-01-15T10:00:00.000Z
    Gap: 60 minutes BEFORE state entry
 
ACDD requires work to be done IN each state, not BEFORE entering it.
 
To fix:
  1. If this is reverse ACDD: Use --skip-temporal-validation flag
  2. If this is a mistake: Delete work unit and restart with proper ACDD
  3. If recovering from error: Move back to specifying and update files

The Escape Hatch: Use --skip-temporal-validation flag for legitimate cases:

# Reverse ACDD or importing existing work
fspec update-work-unit-status LEGACY-001 testing --skip-temporal-validation

When to use --skip-temporal-validation:

  • ✅ Reverse ACDD (documenting existing code)
  • ✅ Importing existing work into fspec
  • ✅ Recovering from temporal validation errors
  • ❌ Normal forward ACDD workflow
  • ❌ Writing new features from scratch

Estimation Validation

What It Is: Estimation validation prevents story point estimation before acceptance criteria are defined. Stories and bugs must have completed feature files (no placeholder text) before estimates can be set.

Why It Exists: Estimates should be based on actual acceptance criteria complexity, not guesses. This enforces Example Mapping → Feature File → Estimation workflow.

Example Error:

$ fspec update-work-unit-estimate AUTH-001 5
✗ ACDD VIOLATION: Cannot estimate story work unit without completed feature file.
 
Work unit AUTH-001 cannot be estimated because:
  - No feature file found with @AUTH-001 tag
  - ACDD requires feature file completion before estimation
 
Next steps:
  1. Complete the specifying phase first
  2. Use Example Mapping: fspec add-rule AUTH-001 "[rule]"
  3. Generate scenarios: fspec generate-scenarios AUTH-001
  4. Then estimate based on completed scenarios

Proper Workflow:

# 1. Example Mapping
fspec add-rule AUTH-001 "Password must be at least 8 characters"
fspec add-example AUTH-001 "User enters valid credentials and logs in"
 
# 2. Generate feature file
fspec generate-scenarios AUTH-001
 
# 3. NOW you can estimate (feature file is complete)
fspec update-work-unit-estimate AUTH-001 5

Exemptions:

  • Tasks can be estimated at any time (no feature file required)
  • Stories and Bugs require completed feature files

Prefill Detection

What It Is: Prefill detection identifies placeholder text in generated feature files (like [role], [action], [benefit], [precondition]) and blocks workflow progression until placeholders are replaced using CLI commands.

Common Prefill Placeholders:

  • [role], [action], [benefit] in Background sections
  • [precondition], [expected outcome] in scenario steps
  • TODO: markers in architecture notes
  • Generic tags like @component, @feature-group

How It Works: When prefill is detected, fspec emits system-reminders (visible to AI, invisible to users) and blocks state transitions:

$ fspec update-work-unit-status AUTH-001 testing
✗ Cannot advance: linked feature file contains prefill placeholders.
 
Found 3 placeholder(s):
  Line 8: [role]
  Line 9: [action]
  Line 10: [benefit]
 
Fix these using CLI commands:
  fspec set-user-story AUTH-001 --role "user" --action "log in" --benefit "access features"

Replacing Prefill (The Right Way):

# DON'T: Edit files directly with Write/Edit tools
# DO: Use fspec CLI commands
 
# Fix Background placeholders
fspec set-user-story AUTH-001 --role "developer" --action "validate specs" --benefit "catch errors"
 
# Fix step placeholders
fspec update-step my-feature "My scenario" "[precondition]" \
  --text "I have a valid feature file"
 
# Fix architecture notes
fspec add-architecture my-feature "Uses Cucumber parser. Validates all Gherkin keywords."
 
# Fix generic tags
fspec add-tag-to-feature spec/features/my-feature.feature @cli @validation

Why Prefill Matters:

  • Ensures AI agents use CLI commands (not direct file editing)
  • Maintains consistency across feature files
  • Validates that specifications are complete before progression

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

Quick StartKanban Workflow