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

Workflow:

fspec create-work-unit AUTH "User login" --type=story
# Follows: backlog → specifying → testing → implementing → validating → done

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

Workflow:

fspec create-work-unit AUTH "Fix session timeout bug" --type=bug
# Follows: backlog → specifying → testing → implementing → validating → done

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

Workflow:

fspec create-work-unit INFRA "Configure CI/CD pipeline" --type=task
# Follows: backlog → specifying → implementing → validating → done
# Note: Tasks can skip testing phase

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

Commands:

fspec create-work-unit AUTH "User login"
# Work unit starts in backlog

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

Commands:

fspec update-work-unit-status AUTH-001 specifying
fspec add-rule AUTH-001 "Email required"
fspec generate-scenarios AUTH-001

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

Commands:

fspec update-work-unit-status AUTH-001 testing
fspec link-coverage user-login --scenario "Login" --test-file src/__tests__/auth.test.ts --test-lines 10-20
 
# Tasks skip this phase entirely
fspec update-work-unit-status CLEAN-001 implementing  # Goes straight from specifying

4. implementing

Purpose: Write code to make tests pass

Activities:

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

Commands:

fspec update-work-unit-status AUTH-001 implementing
fspec link-coverage user-login --scenario "Login" --test-file src/__tests__/auth.test.ts --impl-file src/auth.ts --impl-lines 5-15

5. validating

Purpose: Verify all acceptance criteria met

Activities:

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

Commands:

fspec update-work-unit-status AUTH-001 validating
fspec check
fspec show-coverage user-login

6. done

Purpose: Work complete

Activities:

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

Commands:

fspec update-work-unit-status AUTH-001 done

7. blocked

Purpose: Work cannot proceed

Activities:

• Waiting for external dependency
• Clarification needed
• Technical blocker

Commands:

fspec update-work-unit-status AUTH-001 blocked --blocked-reason "Waiting for API documentation"

Workflow Enforcement

fspec enforces the workflow - you cannot skip states:

# ✅ Allowed: Forward progression
fspec update-work-unit-status AUTH-001 specifying  # backlog → specifying
fspec update-work-unit-status AUTH-001 testing     # specifying → testing
 
# ❌ Blocked: Skipping states
fspec update-work-unit-status AUTH-001 implementing  # specifying → implementing (skips testing!)
# Error: Must move to 'testing' state first

Moving Backward

You CAN move backward when needed:

# Discovered incomplete specs while testing
fspec update-work-unit-status AUTH-001 specifying
# Fix specs
fspec update-work-unit-status AUTH-001 testing

Visualizing Progress

Use the Kanban board:

fspec 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:

fspec create-work-unit AUTH "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:

fspec create-work-unit CLEAN "Audit coverage files" --type=task
fspec update-work-unit-status CLEAN-001 specifying
fspec update-work-unit-status CLEAN-001 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:

fspec create-work-unit BUG "Login fails with @ symbol" --type=bug
# 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