Installation
Local Development

Installation Guide

Important: fspec is designed to be used by AI agents, not run directly by users. You give high-level commands to your AI agent (like /fspec or /rspec in Claude Code), and the agent uses fspec to manage the workflow.

Prerequisites

  • Node.js >= 18.0.0

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

This will:

  1. Clone the repository
  2. Install dependencies (including @cucumber/gherkin-parser)
  3. Build the TypeScript code
  4. Link the fspec command globally for development

Verify Installation

fspec --version
fspec --help

You should see the fspec version and help output.

AI Agent Integration

fspec provides command files that enable AI-driven ACDD workflows:

# Initialize fspec in your project
fspec init

This creates command files in .claude/commands/:

  • fspec.md - Forward ACDD command for building new features
  • rspec.md - Reverse ACDD command for existing codebases
  • ../spec/CLAUDE.md - Specification management guidelines

Using with AI Agents:

  • Claude Code: Use /fspec and /rspec slash commands directly
  • Other AI agents: Map the generated fspec.md and rspec.md files to your agent's command system. Rename spec/CLAUDE.md to spec/AGENTS.md for clarity.

Directory Structure

After initialization, your project will have:

your-project/
├── .claude/
│   └── commands/
│       ├── fspec.md        # Forward ACDD command
│       └── rspec.md        # Reverse ACDD command
└── spec/
    ├── CLAUDE.md           # Process guidelines
    ├── FOUNDATION.md       # Project foundation (auto-generated)
    ├── foundation.json     # Foundation data (source of truth)
    ├── TAGS.md             # Tag documentation (auto-generated)
    ├── tags.json           # Tag registry (source of truth)
    ├── work-units.json     # Work tracking
    ├── epics.json          # Epic definitions
    └── features/           # Gherkin .feature files

Updating fspec

If installed via npm:

npm update -g @sengac/fspec

If installed from source:

# Navigate to your fspec installation directory
cd fspec
git pull origin main
npm install
npm run build
npm run install:local

Uninstall

If installed via npm:

npm uninstall -g @sengac/fspec

If installed from source:

npm unlink -g @sengac/fspec

Troubleshooting

Command not found

If fspec command is not found after installation:

# Check npm global bin path
npm bin -g
 
# Add to PATH if needed (add to ~/.bashrc or ~/.zshrc)
export PATH="$(npm bin -g):$PATH"

Permission errors

On Linux/Mac, you may need sudo:

sudo npm run install:local

Or configure npm to use a different directory:

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH

Next Steps

Quick StartClaude Code Integration