Commands
Work Management

Work Management Commands

Commands for managing work units through Kanban workflow.

Overview

Use work management commands when you need to:

  • Create and organize work units into a backlog
  • Move work through Kanban states (backlog → specifying → testing → implementing → validating → done)
  • Prioritize work in the backlog
  • Manage dependencies between work units
  • Block work units when progress is prevented
  • Display the Kanban board showing current state
  • Auto-advance ready work units through workflow
  • Update work unit details (title, description, estimates)

Work Units

Create Work Unit

Create a new work unit with a prefix and title.

fspec create-work-unit <prefix> <title> [options]

Options:

  • -t, --type <type> - Work item type: story, task, or bug (default: story)
  • -e, --epic <epic> - Associate with an epic
  • --description <desc> - Work unit description

Work Unit Types:

  • story (default) - User-facing feature following full ACDD workflow (backlog → specifying → testing → implementing → validating → done)
  • task - Technical/maintenance work, skips testing phase, no feature file required (backlog → specifying → implementing → validating → done)
  • bug - Defect fix, must link to existing feature file, follows full workflow

Examples:

# Create story (default type - requires full ACDD workflow)
fspec create-work-unit AUTH "User login feature"
fspec create-work-unit DASH "Dashboard" -e user-management
 
# Create task (skips testing phase, no feature file needed)
fspec create-work-unit CLEAN "Audit coverage files" --type=task
fspec create-work-unit MAINT "Update dependencies" --type=task
 
# Create bug (must link to existing feature)
fspec create-work-unit BUG "Login fails with @ symbol" --type=bug
 
# With description
fspec create-work-unit API "REST endpoints" --description "Create REST API for user management"

Important Notes:

  • Work unit type is immutable after creation - delete and recreate if incorrect
  • Tasks skip the testing phase entirely (Example Mapping is optional)
  • Bugs must be linked to existing feature files before moving to testing
  • Stories require feature files before moving to testing

List Work Units

List all work units with optional filtering.

fspec list-work-units [options]

Options:

  • -s, --status <status> - Filter by status (backlog, specifying, testing, implementing, validating, done, blocked)
  • -t, --type <type> - Filter by type (story, task, bug)
  • --prefix <prefix> - Filter by prefix
  • --epic <epic> - Filter by epic

Examples:

fspec list-work-units
fspec list-work-units -s specifying
fspec list-work-units --type=task
fspec list-work-units --prefix AUTH
fspec list-work-units --epic user-management

Show Work Unit

Show detailed information about a specific work unit.

fspec show-work-unit <id>

Examples:

fspec show-work-unit AUTH-001

Update Work Unit

Update work unit details.

fspec update-work-unit <id> [options]

Options:

  • --title <title> - Update title
  • --description <desc> - Update description
  • --epic <epic> - Update epic
  • --parent <parent-id> - Set parent work unit

Examples:

fspec update-work-unit AUTH-001 --title "New Title"
fspec update-work-unit AUTH-001 --description "Updated description"
fspec update-work-unit AUTH-002 --parent AUTH-001

Update Work Unit Status

Move a work unit through the Kanban workflow.

fspec update-work-unit-status <id> <status>

Status values:

  • backlog - Not yet started
  • specifying - Writing specifications (Example Mapping + Gherkin)
  • testing - Writing tests
  • implementing - Writing implementation code
  • validating - Code review and validation
  • done - Completed
  • blocked - Progress prevented

Examples:

fspec update-work-unit-status AUTH-001 specifying
fspec update-work-unit-status AUTH-001 testing
fspec update-work-unit-status AUTH-001 implementing
fspec update-work-unit-status AUTH-001 blocked

Update Work Unit Estimate

Set story point estimate for a work unit.

fspec update-work-unit-estimate <id> <estimate>

Examples:

fspec update-work-unit-estimate AUTH-001 5
fspec update-work-unit-estimate DASH-002 13

Prioritize Work Unit

Change the priority order of a work unit in the backlog.

fspec prioritize-work-unit <id> [options]

Options:

  • --position <position> - Position: top, bottom, or number
  • --before <id> - Place before this work unit
  • --after <id> - Place after this work unit

Examples:

fspec prioritize-work-unit AUTH-003 --position=top
fspec prioritize-work-unit AUTH-001 --before=AUTH-002
fspec prioritize-work-unit DASH-001 --after=AUTH-003

Delete Work Unit

Delete a work unit.

fspec delete-work-unit <id>

Examples:

fspec delete-work-unit AUTH-001

Repair Work Units

Fix work unit state inconsistencies.

fspec repair-work-units

Examples:

fspec repair-work-units

Validate Work Units

Validate work units against schema.

fspec validate-work-units

Examples:

fspec validate-work-units

Export Work Units

Export work units to JSON or CSV format.

fspec export-work-units [options]

Options:

  • --format <format> - Output format: json or csv
  • --output <file> - Output file path

Examples:

fspec export-work-units --format=json --output=work.json
fspec export-work-units --format=csv --output=work.csv

Query Work Units

Query work units with filtering and custom output formats.

fspec query-work-units [options]

Options:

  • --status <status> - Filter by status
  • --type <type> - Filter by type (story, task, bug)
  • --prefix <prefix> - Filter by prefix
  • --epic <epic> - Filter by epic
  • --format <format> - Output format: text or json

Examples:

fspec query-work-units --status=implementing --format=json
fspec query-work-units --type=task --format=json
fspec query-work-units --prefix=AUTH

Dependencies

Add Dependency

Add dependency relationship between work units.

fspec add-dependency <id> [depends-on-id] [options]

Options:

  • --blocks <id> - Work unit that this blocks
  • --blocked-by <id> - Work unit that blocks this
  • --depends-on <id> - Work unit this depends on
  • --relates-to <id> - Related work unit

Examples:

# Shorthand: AUTH-002 depends on AUTH-001
fspec add-dependency AUTH-002 AUTH-001
 
# AUTH-002 blocks API-001
fspec add-dependency AUTH-002 --blocks=API-001
 
# UI-001 is blocked by API-001
fspec add-dependency UI-001 --blocked-by=API-001

Add Multiple Dependencies

Add multiple dependencies at once.

fspec add-dependencies <id> <dep1> <dep2> ...

Examples:

fspec add-dependencies DASH-001 AUTH-001 AUTH-002

Remove Dependency

Remove a dependency relationship.

fspec remove-dependency <id> [depends-on-id] [options]

Options:

  • --blocks <id> - Remove blocks relationship
  • --blocked-by <id> - Remove blockedBy relationship
  • --depends-on <id> - Remove dependsOn relationship
  • --relates-to <id> - Remove relatesTo relationship

Examples:

# Remove dependsOn relationship
fspec remove-dependency AUTH-002 AUTH-001
 
# Remove blocks relationship
fspec remove-dependency AUTH-002 --blocks=API-001

Clear Dependencies

Remove all dependencies for a work unit.

fspec clear-dependencies <id>

Examples:

fspec clear-dependencies AUTH-002

Show Dependencies

Show all dependencies for a work unit.

fspec dependencies <id>

Examples:

fspec dependencies AUTH-002

Export Dependencies

Export dependency graph in JSON or Mermaid format.

fspec export-dependencies [options]

Options:

  • --format <format> - Output format: json or mermaid
  • --output <file> - Output file path

Examples:

fspec export-dependencies --format=mermaid --output=deps.md
fspec export-dependencies --format=json --output=deps.json

Query Dependency Stats

Show dependency statistics for the project.

fspec query-dependency-stats [options]

Options:

  • --format <format> - Output format: text or json

Examples:

fspec query-dependency-stats
fspec query-dependency-stats --format=json

Workflow Automation

Auto-Advance

Automatically advance work units that are ready to move forward.

fspec auto-advance [--dry-run]

Options:

  • --dry-run - Show what would be advanced without making changes

Examples:

fspec auto-advance --dry-run
fspec auto-advance

Board

Display Kanban board showing all work units organized by status.

fspec board [options]

Options:

  • --format <format> - Output format: text or json (default: text)
  • --limit <limit> - Max items per column (default: 25)

Examples:

fspec board
fspec board --format=json
fspec board --limit=50

Workflow Automation

Check if a work unit can auto-advance to the next status.

fspec workflow-automation <id>

Examples:

fspec workflow-automation AUTH-001

ACDD Workflow Integration

fspec's work management integrates with the ACDD (Acceptance Criteria Driven Development) workflow:

  1. Create Work Unit → Add to backlog
  2. Move to Specifying → Perform Example Mapping, write Gherkin scenarios
  3. Move to Testing → Write failing tests (red phase)
  4. Move to Implementing → Write code to make tests pass (green phase)
  5. Move to Validating → Code review, quality checks
  6. Move to Done → Work complete

Moving Backward Through States:

fspec allows moving work units backward through the Kanban workflow when mistakes are discovered:

# Realized specs are incomplete while writing tests
fspec update-work-unit-status AUTH-001 specifying
 
# Need to refactor tests based on implementation learnings
fspec update-work-unit-status AUTH-001 testing

When to move backward:

  • Tests revealed incomplete acceptance criteria → Move to specifying
  • Need to add or fix test cases → Move to testing
  • Quality checks failed → Move to appropriate earlier state
  • Discovered missing scenarios → Move to specifying

See ACDD Concepts for more details on the workflow.

See Also

Specification CommandsDiscovery (Example Mapping)