Work Commands

Overview

The Work commands help you track and manage work units through the complete ACDD (Acceptance Criteria Driven Development) workflow. These commands provide a Kanban-based project management system that integrates seamlessly with Gherkin specifications and test coverage tracking.

Use work commands when you need to:

• Create and organize work units (stories, bugs, tasks) into a backlog
• Move work through Kanban states (backlog → specifying → testing → implementing → validating → done)
• Prioritize work units and manage the backlog order
• Define and track dependencies between work units
• Block work units when external factors prevent progress
• Display a Kanban board showing the current state of all work
• Auto-advance work units that meet validation criteria
• Create checkpoints for safe experimentation and easy rollback
• Update work unit details like title, description, and story point estimates
• Search scenarios and implementation code across work units
• Compare implementation approaches and testing patterns between related work

These commands form the backbone of fspec's project management capabilities, ensuring that specifications, tests, and code stay aligned throughout development.

Commands Reference

WORK UNIT MANAGEMENT

WORK UNITS

Create Story

Creates a new story for user-facing features that require Example Mapping to clarify acceptance criteria through collaborative conversation. Stories use rules, examples, and questions to explore requirements before writing formal specifications.

After creation, system-reminders guide AI agents to use Example Mapping commands (add-rule, add-example, add-question, set-user-story) to build understanding before generating Gherkin scenarios. Stories must have tests before implementation (ACDD workflow).

Usage:

fspec create-story <prefix> <title>

Create Bug

Creates a new bug with research guidance for understanding existing code before fixing. The command emits system-reminders instructing AI agents to search scenarios (search-scenarios), search implementation (search-implementation), and check coverage (show-coverage) BEFORE attempting fixes.

This research-first approach prevents regressions by ensuring bugs are fixed in context of existing features, tests, and acceptance criteria.

Usage:

fspec create-bug <prefix> <title>

Create Task

Creates a new task for operational work that doesn't require user-facing features, tests, or acceptance criteria. Tasks are perfect for infrastructure work (CI/CD setup, monitoring), dependency updates, refactoring, and documentation.

Tasks have optional feature files and tests, can skip Example Mapping, and can move directly to implementing without the specifying phase. This makes them ideal for non-functional work.

Usage:

fspec create-task <prefix> <title>

Options:

• -e, --epic <epic> Associate with epic
• --description <desc> Work unit description

Examples:

fspec create-story AUTH "User login feature"
fspec create-bug AUTH "Fix login validation"
fspec create-task DASH "Setup dashboard infrastructure" -e user-management

List Work Units

Lists work units with optional filtering by status, prefix, or epic. Use --status to view work at specific workflow stages (backlog, specifying, testing, implementing, validating, done, blocked), --prefix to filter by component (AUTH, UI, API), or --epic to see work in a business initiative.

This command provides a quick overview of your backlog and work in progress across the entire project.

Usage:

fspec list-work-units

Options:

• -s, --status <status> Filter by status
• --prefix <prefix> Filter by prefix
• --epic <epic> Filter by epic

Examples:

fspec list-work-units
fspec list-work-units -s specifying

Show Work Unit

Displays detailed information about a work unit including status, type, description, Example Mapping data (rules, examples, questions, assumptions, architecture notes), dependencies (blocks/blockedBy/dependsOn/relatesTo), linked feature files with scenario line numbers, and attachments.

Use --format json for machine-readable output suitable for scripting. The command also displays system-reminders for missing estimates, empty Example Mapping, or other workflow issues.

Usage:

fspec show-work-unit <id>

Examples:

fspec show-work-unit AUTH-001

Update Work Unit

Updates work unit metadata including title, description, epic association, and parent-child relationships. Use this command to refine work units after creation, reorganize epic structure, or establish hierarchical relationships.

Note: Work unit type (story/bug/task) is immutable and cannot be changed. Parent-child relationships are validated to prevent circular references.

Usage:

fspec update-work-unit <id>

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"

Update Work Unit Status

Moves work units through the ACDD workflow stages: backlog → specifying → testing → implementing → validating → done. The command enforces strict temporal ordering: feature files must be created AFTER entering specifying, test files AFTER entering testing.

ACDD ensures tests are written before implementation. Use --skip-temporal-validation for reverse ACDD or importing existing work. Dependencies are checked: work units with incomplete blocking dependencies cannot move to active states.

Usage:

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

Examples:

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

Update Work Unit Estimate

Sets story point estimates using Fibonacci scale (1, 2, 3, 5, 8, 13, 21). For story/bug work units, feature files must be complete (no prefill placeholders) before estimation. Task work units can be estimated anytime.

Estimates > 13 trigger warnings recommending breakdown into smaller units. Estimate AFTER generating scenarios from Example Mapping when you have sufficient information about complexity.

Usage:

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

Examples:

fspec update-work-unit-estimate AUTH-001 5

Prioritize Work Unit

Reorders work units within their current Kanban column (cannot move between columns). Use --position top/bottom for absolute positioning, or --before/--after for relative positioning. Works on all columns except done (backlog, specifying, testing, implementing, validating, blocked).

Critical: Can only reorder within the same column. Done items are ordered by completion time and cannot be reordered.

Usage:

fspec prioritize-work-unit <id>

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

Delete Work Unit

Permanently deletes a work unit and all associated data including Example Mapping results, dependencies, and state tracking. Cannot be undone. Use --cascade-dependencies to remove all dependency relationships automatically before deletion.

Work units with children must have children deleted first or parent relationships removed. Use --force to bypass validation checks and --skip-confirmation for scripted deletions.

Usage:

fspec delete-work-unit <id>

Examples:

fspec delete-work-unit AUTH-001

Repair Work Units

Repairs work unit data integrity issues such as broken references, invalid status transitions, or orphaned work units. Use --dry-run to preview changes before applying fixes. The command creates backups before modifying data.

Run this command when validate-work-units reports issues that need fixing.

Usage:

fspec repair-work-units

Description: Fix work unit state inconsistencies

Examples:

fspec repair-work-units

Validate Work Units

Validates work unit data integrity and relationships, checking for missing dependencies, invalid status transitions, orphaned work units, and other structural issues. Use --fix to automatically repair issues where possible.

Run this command periodically to catch data inconsistencies early, especially after manual JSON edits or complex operations.

Usage:

fspec validate-work-units

Description: Validate work units against schema

Examples:

fspec validate-work-units

Export Work Units

Exports work units to JSON or CSV format with optional filtering by status, epic, or other criteria. Useful for reporting, external integrations, backups, or analyzing work unit data with external tools.

JSON format includes all work unit fields, while CSV provides a simplified tabular view suitable for spreadsheets.

Usage:

fspec export-work-units

Options:

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

Examples:

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

Query Work Units

Queries work units with advanced filters including status, type (story/bug/task), tags, epic, and prefix. Supports multiple output formats: table (human-readable), JSON (scripting), and CSV (spreadsheet).

Combine filters to create complex queries like "all completed stories tagged @cli" or "all implementing work units in the AUTH epic".

Usage:

fspec query-work-units

Options:

• --status <status> Filter by status
• --prefix <prefix> Filter by prefix
• --epic <epic> Filter by epic
• --tag <tag> Filter by tag
• --format <format> Output: text, table, or json

Examples:

fspec query-work-units --status=implementing --format=json
fspec query-work-units --tag=@cli --format=table

ANALYSIS & COMPARISON

Search Scenarios

Searches scenario names across all feature files using literal text or regex patterns. Results include feature file paths and work unit IDs for traceability. Use --regex for pattern matching like "login|logout|signin".

This command helps find related scenarios when working on bugs, refactoring, or understanding feature coverage across the project.

Usage:

fspec search-scenarios --query=<pattern>

Description: Search scenarios across all feature files

Options:

• --regex Use regex pattern matching
• --json Output in JSON format

Examples:

fspec search-scenarios --query="validation"
fspec search-scenarios --query="user.*login" --regex

Search Implementation

Searches implementation code for specific function usage across work units. Use --show-work-units to see which work units use each file. Supports regex patterns for advanced matching like "readFile|writeFile".

This command is essential for impact analysis before refactoring, identifying code reuse opportunities, and detecting manual implementations that could use existing utilities.

Usage:

fspec search-implementation --function=<name>

Description: Search for function usage across work units

Options:

• --show-work-units Show which work units use each file
• --json Output in JSON format

Examples:

fspec search-implementation --function=validateInput
fspec search-implementation --function=queryWorkUnits --show-work-units

Compare Implementations

Compares implementation approaches across work units with the same tag to identify patterns and inconsistencies. Automatically detects naming convention differences (camelCase, snake_case, kebab-case) and highlights architectural pattern divergence.

Use --show-coverage to include test and implementation file paths from coverage data, enabling side-by-side comparison to identify best practices and opportunities for standardization.

Usage:

fspec compare-implementations --tag=<tag>

Description: Compare implementation approaches across work units

Options:

• --show-coverage Include coverage data
• --json Output in JSON format

Examples:

fspec compare-implementations --tag=@cli
fspec compare-implementations --tag=@authentication --show-coverage

Show Test Patterns

Analyzes and displays common testing patterns across work units with the same tag. Identifies common frameworks, utilities, test structure, and coverage metrics. Use --include-coverage to show test file paths and line numbers.

This command helps maintain test consistency across similar features, detect outliers or inconsistent testing approaches, and discover reusable test utilities.

Usage:

fspec show-test-patterns --tag=<tag>

Description: Analyze common testing patterns across work units

Options:

• --include-coverage Include coverage information
• --json Output in JSON format

Examples:

fspec show-test-patterns --tag=@high
fspec show-test-patterns --tag=@cli --include-coverage

DEPENDENCIES

Add Dependency

Adds dependency relationships between work units to track blockers and dependencies. Use shorthand (fspec add-dependency AUTH-002 AUTH-001) or explicit flags (--blocks, --blocked-by, --depends-on, --relates-to) for clarity.

Circular dependencies are automatically detected and rejected. Dependencies create bidirectional relationships where appropriate and affect workflow transitions (blocked work units cannot move to active states).

Usage:

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

Description: Add dependency relationship (shorthand or 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:

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

Add Dependencies

Adds multiple dependency relationships to a work unit in a single command. All options accept space-separated lists of work unit IDs. More efficient than calling add-dependency multiple times when setting up complex dependency graphs.

Use --depends-on for prerequisites, --blocks to mark blockers, --blocked-by for blocking dependencies, and --relates-to for non-blocking associations.

Usage:

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

Examples:

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

Remove Dependency

Removes dependency relationships between work units to clean up outdated blockers. Use shorthand or explicit flags like add-dependency. Blocks/blocked-by and relates-to relationships are bidirectional—removing from one side removes from both.

The command is idempotent (succeeds even if the relationship doesn't exist) and supports the same shorthand and flag syntax as add-dependency.

Usage:

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

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:

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

Clear Dependencies

Removes all dependency relationships from a work unit (blocks, blockedBy, dependsOn, relatesTo). Requires confirmation unless --force is used. This command is useful when cleaning up work units or restructuring dependency graphs.

Use with caution as this operation removes all relationships at once.

Usage:

fspec clear-dependencies <id>

Examples:

fspec clear-dependencies AUTH-002

Dependencies

Shows all dependency relationships for a work unit (blocks, blockedBy, dependsOn, relatesTo). Use --graph to visualize the dependency tree. This command is essential for understanding work unit relationships and planning implementation order.

The output shows which work units it blocks, is blocked by, depends on, and relates to—helping you understand the impact of completing or starting work.

Usage:

fspec dependencies <id>

Description: Show dependencies for a work unit

Examples:

fspec dependencies AUTH-002

Export Dependencies

Exports the dependency graph visualization in various formats: dot (Graphviz), mermaid (Mermaid.js), or json (machine-readable). Useful for documentation, presentations, or integration with external visualization tools.

The exported graph shows all work unit relationships and can be rendered in compatible visualization tools.

Usage:

fspec export-dependencies

Options:

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

Examples:

fspec export-dependencies --format=mermaid

Query Dependency Stats

Shows dependency statistics including total dependencies, blocking work units, blocked work units, and work units with no dependencies. Use --show-critical-path to highlight the critical path through dependencies.

This command helps identify dependency bottlenecks and plan work order based on the critical path.

Usage:

fspec query-dependency-stats

Options:

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

Examples:

fspec query-dependency-stats

WORKFLOW AUTOMATION

Auto Advance

Automatically advances work units through the workflow when they meet ACDD criteria (e.g., all questions answered → move to testing, tests written → move to implementing). Use --dry-run to preview changes without executing them.

This command is safe to run multiple times (idempotent) and checks workflow criteria for each state transition automatically.

Usage:

fspec auto-advance

Description: Automatically advance ready work units

Options:

• --dry-run Show what would be advanced

Examples:

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

Board

Displays a Kanban board showing all work units organized by status column (backlog, specifying, testing, implementing, validating, blocked, done). Use --format json for machine-readable output or --limit to control items per column.

The board provides a visual overview of your project's workflow state and helps identify bottlenecks or blocked work.

Usage:

fspec board

Description: Display Kanban board of all work

Options:

• --format <format> Output: 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

Workflow automation utilities including recording iterations (red→green cycles), auto-advancing states after events (tests-pass, validation-pass, specs-complete), and validating spec alignment. Used primarily by AI agents for metrics tracking and automated workflow transitions.

Use record-iteration to track TDD cycles, auto-advance with --event and --from-state for safe state transitions, and validate-alignment to check if work units have corresponding Gherkin scenarios.

Usage:

fspec workflow-automation <id>

Description: Check if work unit can auto-advance

Examples:

fspec workflow-automation AUTH-001

Checkpoint

Creates manual checkpoints for work units, capturing all file changes (including untracked files) as git stashes. Checkpoints enable safe experimentation by providing rollback points you can restore later. Use before risky refactoring or experimental approaches.

Checkpoints capture ALL changes including untracked files (respecting .gitignore) and persist until explicitly deleted. Manual checkpoints are marked with 📌 emoji in listings.

Usage:

fspec checkpoint <id> <name>

Description: Create manual checkpoint for experimentation

Examples:

fspec checkpoint AUTH-001 baseline
fspec checkpoint AUTH-001 before-refactor

Restore Checkpoint

Restores previously created checkpoints, applying saved file changes back to the working directory. Uses git stash apply which preserves the checkpoint for re-restoration. If working directory is dirty, prompts for how to proceed. If conflicts occur, emits system-reminders for AI-assisted resolution.

Same checkpoint can be restored multiple times, and conflicts trigger AI-assisted resolution with clear guidance on using Read and Edit tools.

Usage:

fspec restore-checkpoint <id> <name>

Description: Restore previously created checkpoint

Examples:

fspec restore-checkpoint AUTH-001 baseline

List Checkpoints

Lists all checkpoints for a work unit, showing both automatic (🤖) and manual (📌) checkpoints with creation timestamps. Use before restoring to see available checkpoints, verify checkpoint creation, or decide which old checkpoints to cleanup.

Checkpoints are sorted by creation time (newest first) and include both user-created manual checkpoints and automatically-created checkpoints from status transitions.

Usage:

fspec list-checkpoints <id>

Description: List all checkpoints (🤖 auto, 📌 manual)

Examples:

fspec list-checkpoints AUTH-001

Cleanup Checkpoints

Deletes old checkpoints while preserving the N most recent checkpoints. Deletion is based on creation timestamp (oldest deleted first). Use --keep-last to specify how many checkpoints to preserve. Deletion is permanent and cannot be undone.

Both automatic and manual checkpoints are included in cleanup. Use after many experiments leave too many checkpoints or as part of work unit completion workflow.

Usage:

fspec cleanup-checkpoints <id> --keep-last <N>

Description: Delete old checkpoints, keep N most recent

Examples:

fspec cleanup-checkpoints AUTH-001 --keep-last 5

STABLE INDICES & SOFT-DELETE

Show Deleted

Displays all soft-deleted items (rules, examples, questions, architecture notes) with stable IDs, text, and deletedAt timestamps. Use this command before restore operations to see what's available to restore, or before compaction to preview what will be permanently removed.

Shows items with deleted: true flag and their stable IDs that can be used directly with restore commands.

Usage:

fspec show-deleted <work-unit-id>

Description: Display all soft-deleted items with IDs and timestamps

Examples:

fspec show-deleted AUTH-001

Restore Rule

Restores soft-deleted business rules by stable ID. Use --ids for bulk restore with comma-separated IDs (e.g., "2,5,7"). IDs are stable and never shift when items are removed, making restoration predictable.

Restoration sets deleted=false and clears the deletedAt timestamp. Bulk restore is atomic: all succeed or all fail.

Usage:

fspec restore-rule <work-unit-id> <index>

Description: Restore soft-deleted rule by stable ID

Options:

• --ids <ids> Restore multiple rules (comma-separated)

Examples:

fspec restore-rule AUTH-001 2
fspec restore-rule AUTH-001 --ids 2,5,7

Restore Example

Restores soft-deleted examples by stable ID. Use --ids for bulk restore with comma-separated IDs. Stable IDs never shift when items are removed and are never reused, even after compaction.

Restoring an already-active item is idempotent (succeeds with message). Non-existent IDs fail with clear error messages.

Usage:

fspec restore-example <work-unit-id> <index>

Description: Restore soft-deleted example by stable ID

Options:

• --ids <ids> Restore multiple examples (comma-separated)

Examples:

fspec restore-example AUTH-001 2
fspec restore-example AUTH-001 --ids 2,5,7

Restore Question

Restores soft-deleted questions by stable ID. Use --ids for bulk restore with comma-separated IDs. Bulk restore validates all IDs before restoring any items, ensuring atomic operations.

Use show-deleted to see deleted items with IDs before restoring. IDs remain stable throughout the work unit's lifecycle.

Usage:

fspec restore-question <work-unit-id> <index>

Description: Restore soft-deleted question by stable ID

Options:

• --ids <ids> Restore multiple questions (comma-separated)

Examples:

fspec restore-question AUTH-001 2
fspec restore-question AUTH-001 --ids 2,5,7

Restore Architecture Note

Restores soft-deleted architecture notes by stable ID. Use --ids for bulk restore with comma-separated IDs. Restoration operations set deleted=false and clear the deletedAt field.

All restore commands use the same stable ID system and support both single and bulk restoration patterns.

Usage:

fspec restore-architecture-note <work-unit-id> <index>

Description: Restore soft-deleted architecture note by stable ID

Options:

• --ids <ids> Restore multiple notes (comma-separated)

Examples:

fspec restore-architecture-note AUTH-001 2
fspec restore-architecture-note AUTH-001 --ids 2,5,7

Compact Work Unit

Permanently removes soft-deleted items and renumbers IDs sequentially (destructive operation). Use --force to skip confirmation and compact during non-done status. Warning: Compaction is PERMANENT and cannot be undone.

Auto-compact triggers automatically when moving work units to "done" status. Manual compact is useful for cleaning up during development, but use show-deleted first to preview what will be removed.

Usage:

fspec compact-work-unit <work-unit-id>

Description: Permanently remove soft-deleted items (destructive!)

Options:

• --force Skip confirmation, compact during non-done status

Examples:

fspec compact-work-unit AUTH-001
fspec compact-work-unit AUTH-001 --force