Quick Start

Get up and running with fspec in minutes.

Installation

Install fspec globally
```
npm install -g @sengac/fspec
```
Go to your project directory
```
cd /path/to/your/project
```
Initialize fspec
```
fspec init
```
Run your AI agent (e.g., Claude Code, Codex)
Bootstrap fspec context
- Use a bootstrapping command: /fspec (Claude Code) or /prompts:fspec (Codex)
- Or tell your agent: "Run fspec bootstrap"

Talk naturally with fspec

"I want to create a bug to fix this issue"
"Create a checkpoint for this work"
"Show me the kanban board"
"Generate scenarios from the example map"

Launch the interactive kanban
```
fspec
```
Watch live changes, view work unit details, manage checkpoints, and navigate your kanban board with an intuitive TUI.
When your AI goes off track (and it will)

AI agents sometimes rush ahead, skip Example Mapping, or write code before tests. That's okay—fspec has your back.

Auto checkpoints are created automatically before every state transition, so you can always roll back:
```
"You skipped Example Mapping. Move back to specifying status and let's do discovery properly."
"You wrote code before tests. Restore from the auto checkpoint and follow ACDD this time."
"List the auto checkpoints so I can see what you saved."
```
Recovery is simple:
- Tell your agent to move the work unit backward (e.g., from testing back to specifying)
- Have it restore from the most recent auto checkpoint: fspec restore-checkpoint <id> <checkpoint-name>
- Checkpoints can be restored multiple times—experiment fearlessly
The workflow enforcer prevents disasters, and checkpoints provide instant recovery. No work is ever lost.
Keep context fresh
- Over time, your agent's context gets cluttered
- Clear your agent's context and bootstrap fspec again
- Repeat as needed to maintain clean workflow

Natural Language Examples

Checkpoints

Save your work state before experimenting:

"Create a checkpoint called 'before-refactor' so I can safely experiment"
"Show me all checkpoints for this work unit"
"Restore from the checkpoint we made earlier"
"List auto checkpoints created by fspec"

View and restore checkpoints from the interactive kanban by pressing the C key.

Attachments

Attach rich documentation before starting Example Mapping:

"Create a story about adding Event Storming. I want you to research this
topic on the web and create a markdown document with mermaid diagrams
and attach it to this story using fspec."

"Attach the architecture diagram we created to this work unit"
"Show me the attachments for this story"

View attachments in the interactive kanban by pressing the A key, with full markdown and mermaid diagram rendering.

Virtual Hooks

Quality gates that prevent bad practices:

"What virtual hooks are enabled for this project?"
"Enable the pre-implement hook to enforce TDD"
"Show me why the hook blocked this transition"

Virtual hooks enforce ACDD discipline by blocking workflow transitions when quality gates aren't met.

Next Steps

📖 Learn ACDD - Understanding the methodology
🤝 Example Mapping - Discovery techniques
📊 Kanban Board - Managing work units
💾 Git Checkpoints - Safe experimentation
⚡ Virtual Hooks - Quality gates

Getting Help

Don't know what to do next? Just ask your agent—it knows fspec inside and out and will suggest the best ways to use it for your workflow.

Every command also has detailed help:

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

Introduction ACDD Methodology