Kanban Workflow

fspec uses a 7-state Kanban workflow to manage work units through the ACDD process.

Work Unit Types

fspec supports three types of work units to distinguish different kinds of work:

Story

User-facing features or functionality

Stories represent new capabilities that deliver value to end users. They follow the full ACDD workflow including Example Mapping, Gherkin scenarios, tests, and implementation.

Examples:

• User login feature
• Payment checkout flow
• Dashboard widgets

How to use:

User: Create a story for user login
# Follows: backlog → specifying → testing → implementing → validating → done

Your AI agent figures out the prefix and runs the fspec commands. Just talk naturally!

Requirements:

• Must complete Example Mapping (rules, examples, questions)
• Must generate Gherkin scenarios
• Must write tests before implementation
• Must have feature file with acceptance criteria

Bug

Something broken that needs fixing

Bugs represent defects in existing functionality. They should link to existing feature files and include regression tests.

Examples:

• Login session timeout not working
• Password validation allows weak passwords
• Dashboard crashes on mobile

How to use:

User: Create a bug to fix the session timeout issue
# Follows: backlog → specifying → testing → implementing → validating → done

Your AI agent figures out the prefix and runs the fspec commands. Just talk naturally!

Requirements:

• Should link to existing feature file
• Must write regression test to reproduce bug
• Must fix code to make test pass

Task

Non-user-facing operational work

Tasks represent technical work like refactoring, infrastructure, or documentation. They can skip the testing phase since they may not require automated tests.

Examples:

• Refactor authentication middleware
• Update API documentation
• Configure CI/CD pipeline
• Database migration

How to use:

User: Create a task to configure CI/CD pipeline
# Follows: backlog → specifying → implementing → validating → done
# Note: Tasks can skip testing phase

Your AI agent figures out the prefix and runs the fspec commands. Just talk naturally!

Requirements:

• Example Mapping optional (may not need formal specs)
• Can skip testing phase (no automated tests required)
• Focus on technical completion criteria

The 7 States

1. backlog

Purpose: Work that hasn't started yet

Activities:

• Work unit created but not actively worked on
• Waiting for dependencies
• Prioritized in backlog

How to use:

User: Create a story for user login
# Work unit starts in backlog

Your AI agent runs the commands. Just talk naturally!

2. specifying

Purpose: Discovery and specification phase

Activities:

• Example Mapping (rules, examples, questions)
• Setting user stories
• Generating Gherkin scenarios

Work Type Differences:

• Stories: Must complete Example Mapping and generate scenarios
• Tasks: Example Mapping is optional (technical work may not need specs)
• Bugs: Should link to existing feature file

How to use:

User: Move AUTH-001 to specifying
User: Add a rule to AUTH-001: "Email required"
User: Generate scenarios for AUTH-001

Your AI agent runs the commands. Just talk naturally!

3. testing

Purpose: Write tests BEFORE implementation

Activities:

• Write test files
• Tests must FAIL (red phase)
• Link tests to scenarios

Work Type Differences:

• Stories: Required - must write tests from Gherkin scenarios
• Tasks: SKIPPED - tasks go directly from specifying → implementing
• Bugs: Required - write regression tests for the bug

How to use:

User: Move AUTH-001 to testing
User: Link the test coverage for the "Login" scenario in user-login

# Tasks skip this phase entirely
User: Move CLEAN-001 to implementing  # Goes straight from specifying

Your AI agent runs the commands. Just talk naturally!

4. implementing

Purpose: Write code to make tests pass

Activities:

• Implement minimum code
• Tests must PASS (green phase)
• Link implementation to tests

How to use:

User: Move AUTH-001 to implementing
User: Link the implementation coverage for the "Login" scenario

Your AI agent runs the commands. Just talk naturally!

5. validating

Purpose: Verify all acceptance criteria met

Activities:

• Run full test suite
• Validate specifications
• Check coverage
• Quality gates

How to use:

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

Your AI agent runs the commands. Just talk naturally!

6. done

Purpose: Work complete

Activities:

• All tests passing
• All acceptance criteria met
• Documentation complete

How to use:

User: Move AUTH-001 to done

Your AI agent runs the commands. Just talk naturally!

7. blocked

Purpose: Work cannot proceed

Activities:

• Waiting for external dependency
• Clarification needed
• Technical blocker

How to use:

User: Move AUTH-001 to blocked because we're waiting for API documentation

Your AI agent runs the commands. Just talk naturally!

Workflow Enforcement

fspec enforces the workflow - you cannot skip states:

# ✅ Allowed: Forward progression
User: Move AUTH-001 to specifying  # backlog → specifying
User: Move AUTH-001 to testing     # specifying → testing

# ❌ Blocked: Skipping states
User: Move AUTH-001 to implementing  # specifying → implementing (skips testing!)
AI: Error: Must move to 'testing' state first

Moving Backward

You CAN move backward when needed:

# Discovered incomplete specs while testing
User: Move AUTH-001 back to specifying
# Fix specs
User: Move AUTH-001 to testing

Visualizing Progress

Use the Kanban board:

User: Show me the kanban board

Output:

┌──────────┬──────────┬──────────┬──────────┬──────────┬──────────┬──────────┐
│BACKLOG   │SPECIFYING│TESTING   │IMPLEMENTI│VALIDATING│DONE      │BLOCKED   │
├──────────┼──────────┼──────────┼──────────┼──────────┼──────────┼──────────┤
│AUTH-002 [│AUTH-001 [│          │          │          │          │          │
│API-001 [ │          │          │          │          │          │          │
└──────────┴──────────┴──────────┴──────────┴──────────┴──────────┴──────────┘

Work Unit Types

fspec supports three types of work units, each with different workflow requirements:

Story (Default)

User-facing features that follow the full ACDD workflow.

Workflow: backlog → specifying → testing → implementing → validating → done

Requirements:

• Must complete Example Mapping (rules, examples, user story)
• Must generate Gherkin feature file
• Must write tests from scenarios
• Feature file required before moving to testing

Use Cases:

• New user-facing features
• API endpoints with acceptance criteria
• UI components with behavior specifications

Example:

User: Create a story for user login feature
# Defaults to type=story

Task

Technical or maintenance work that doesn't require acceptance criteria.

Workflow: backlog → specifying → implementing → validating → done

Note: Tasks skip the testing phase entirely!

Requirements:

• Example Mapping is optional
• No feature file required
• Can move directly from specifying to implementing

Use Cases:

• Refactoring existing code
• Updating dependencies
• Configuration changes
• Infrastructure work
• Documentation updates

Example:

User: Create a task to audit coverage files
User: Move CLEAN-001 to specifying
User: Move CLEAN-001 to implementing  # Skips testing!

Bug

Defect fixes that must be linked to existing features.

Workflow: backlog → specifying → testing → implementing → validating → done

Requirements:

• Must link to existing feature file
• Must write regression tests
• If no feature file exists, create a story instead

Use Cases:

• Fixing defects in existing features
• Regression fixes
• Security patches for specified features

Example:

User: Create a bug for login failing with @ symbol
# Must link to existing feature before moving to testing

Work Type Comparison

Next Steps

• ACDD Methodology - Understand the full workflow
• Example Mapping - Master discovery
• Commands Reference - Learn work management commands