Quick Start

Get up and running with fspec in under 5 minutes.

See It In Action

Watch this demo showing how AI agents use fspec to build features with ACDD workflow:

Installation

Via npm (Recommended)

npm install -g @sengac/fspec

This installs the latest stable version globally.

From Source (For Development)

git clone https://github.com/sengac/fspec.git
cd fspec
npm install
npm run build
npm run install:local

See the Local Installation guide for detailed instructions and troubleshooting.

Prerequisites

Node.js >= 18.0.0

Initialize Your Project

Navigate to your project directory and initialize fspec:

cd /path/to/your/project
fspec init

This creates:

.claude/commands/fspec.md - ACDD slash command for Claude Code
spec/ directory - All specifications and work tracking

Using fspec with Claude Code (Recommended)

In Claude Code, simply type:

/fspec Build a user login feature

Claude will guide you through the ACDD workflow, automatically running fspec commands and asking questions as needed.

For reverse engineering existing code:

Analyze the authentication system in src/auth/ using fspec reverse

Manual Usage (Learning)

The examples below show the fspec commands manually for learning purposes. When using Claude Code, the AI agent runs these commands for you.

1. Create Work Unit

fspec create-work-unit AUTH "User login feature"

Output:

✓ Work unit AUTH-001 created successfully

2. Start Discovery (Example Mapping)

Move to specifying phase and add discovery artifacts:

# Move to specifying phase
fspec update-work-unit-status AUTH-001 specifying
 
# Add business rules
fspec add-rule AUTH-001 "Login requires valid email and password"
fspec add-rule AUTH-001 "Failed login shows error message"
 
# Add concrete examples
fspec add-example AUTH-001 "user@example.com with password 'secret123' succeeds"
fspec add-example AUTH-001 "user@example.com with wrong password fails"
 
# Ask questions (AI to human)
fspec add-question AUTH-001 "Should we support OAuth providers like Google?"

3. Set User Story

Define who, what, and why:

fspec set-user-story AUTH-001 \
  --role "registered user" \
  --action "log in with email and password" \
  --benefit "I can access my account securely"

4. Generate Scenarios

Once discovery is complete, generate Gherkin scenarios:

fspec generate-scenarios AUTH-001

This creates spec/features/user-login-feature.feature with scenarios based on your examples.

5. View Your Work

Check the Kanban board:

fspec board

Output shows work units across all workflow states:

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

6. Continue Through Workflow

# Move to testing - write tests BEFORE implementation
fspec update-work-unit-status AUTH-001 testing
 
# After writing tests, move to implementing
fspec update-work-unit-status AUTH-001 implementing
 
# After implementation, validate
fspec update-work-unit-status AUTH-001 validating
 
# Mark complete
fspec update-work-unit-status AUTH-001 done

Essential Commands

Work Management

fspec create-work-unit <PREFIX> "Description"    # Create work unit
fspec list-work-units                            # List all work units
fspec list-work-units --status=implementing      # Filter by status
fspec show-work-unit AUTH-001                    # Show details
fspec board                                      # Visual Kanban board

Specification Management

fspec create-feature "Feature Name"              # Create .feature file
fspec add-scenario <feature> "Scenario name"     # Add scenario
fspec validate                                   # Validate Gherkin syntax
fspec format                                     # Format all .feature files

Discovery (Example Mapping)

fspec add-rule <work-unit> "Rule text"           # Add business rule
fspec add-example <work-unit> "Example text"     # Add concrete example
fspec add-question <work-unit> "Question text"   # Ask clarifying question
fspec generate-scenarios <work-unit>             # Convert to Gherkin

Next Steps

Now that you've created your first work unit:

Learn ACDD - Understand the methodology fspec enforces
Explore Commands - Deep dive into all commands
Try Reverse ACDD - Reverse engineer an existing codebase
Use with Claude Code - Leverage the /fspec slash command

Getting Help

Every command has detailed help:

fspec --help                    # Main help
fspec help specs                # Command group help
fspec validate --help           # Specific command help

Common Patterns

Moving Work Units Backward

If you discover issues, move backward through workflow:

# Discovered specs are incomplete while testing
fspec update-work-unit-status AUTH-001 specifying
 
# Fix specs, then return to testing
fspec update-work-unit-status AUTH-001 testing

Managing Dependencies

Block work that depends on other work:

fspec add-dependency AUTH-002 AUTH-001
# AUTH-002 can't start until AUTH-001 is done

Creating Epics

Group related work units:

fspec create-epic user-management AUTH "All user-related features"
fspec create-work-unit AUTH "User registration" --epic=user-management

Ready to dive deeper? Continue to Core Concepts.

Introduction Local Development