Getting Started
Introduction

Introduction

Welcome to fspec - a Kanban-based project management and specification tool designed specifically for AI agents.

What is fspec?

fspec enables AI agents (like Claude Code, GitHub Copilot) to build quality software reliably by combining two essential systems:

1. Specification Management

Ensures specs are valid, concrete (Specification by Example), and follow BDD conventions:

  • Gherkin Validation - Official @cucumber/gherkin-parser ensures valid syntax
  • Tag Discipline - JSON-backed registry prevents tag chaos
  • Architecture Docs - Mermaid diagrams with syntax validation
  • Ecosystem Compatibility - Works with all Cucumber tooling

2. Kanban-Based Project Management

Provides persistent queryable state with enforced workflow:

  • Kanban Workflow - 7 states: backlog → specifying → testing → implementing → validating → done (+ blocked)
  • Work Units - Persistent project state with dependencies, epics, example mapping
  • Example Mapping - Structured discovery with rules, examples, and questions
  • Queryable State - AI queries current state instead of relying on conversation context

Why fspec Matters

AI agents naturally violate ACDD workflow without tooling enforcement:

  • They get sidetracked and lose context
  • They skip discovery and jump to implementation
  • They write code before specifications or tests
  • They build what THEY think is needed, not what YOU need

fspec solves this by providing:

  • ✅ Persistent state that survives context loss
  • ✅ Enforced workflow preventing phase skipping
  • ✅ Collaborative discovery through Example Mapping
  • ✅ Validated specifications that become automated tests

The ACDD Workflow

Acceptance Criteria Driven Development (ACDD) is the methodology fspec enforces:

1. Discovery (Example Mapping)
   ↓
2. Specification (Gherkin)
   ↓
3. Testing (TDD Red Phase)
   ↓
4. Implementation (TDD Green Phase)
   ↓
5. Validation & Done

This ensures:

  • Specifications first - Know what to build before building
  • Tests before code - Prove requirements work by failing first
  • Just enough code - Build exactly what's specified, no more
  • Collaborative clarity - Human and AI align on requirements

Who Should Use fspec?

Developers Using AI Coding Agents

You need reliable ACDD workflow with persistent state and collaborative discovery.

Teams Practicing BDD/ACDD

You want AI agents that follow methodology rigorously without sacrificing discipline.

Product Owners & Stakeholders

You need clear visibility through work units and Kanban, ensuring right features are built.

Next Steps

Ready to get started? Continue to the Installation guide to set up fspec in your project.

Or explore:

▲ HomeQuick Start