Skip to content
/
Tier A A4 Markdown scaffold

fspec (SENGAC)

fspec · sengac/fspec · ★ 69 · last commit 2026-05-19

Provides complete ACDD infrastructure for AI agents: Gherkin spec management, Example Mapping facilitation, TDD state machine enforcement, Git checkpoints for safe recovery, and coverage tracking linking scenarios to tests to implementation.

Best whenAI agents need infrastructure guardrails (state machines, checkpoints, coverage tracking) not just prompt instructions — and Gherkin .feature files with expl…
Skip ifSkipping Example Mapping and going straight to coding, Writing code before generating tests from Gherkin scenarios
vs seeds
spec-kit(Python CLI), fspec uses Gherkin not markdown as spec format and enforces TDD through a state machine not hooks. The onl…
Primitive shape 5 total
Commands 4 MCP tools 1
00

Summary

fspec (sengac) — Summary

fspec is a TypeScript CLI tool that implements Acceptance Criteria Driven Development (ACDD) for AI agents, enforcing a spec-first, test-first, Gherkin-based workflow through a TUI Kanban board, Git checkpoint system, virtual hooks, and a comprehensive CLI with 20+ subcommands. Unlike frameworks that provide prompts or guidelines, fspec provides actual project management infrastructure: work units with workflow states (backlog → specifying → testing → implementing → validating → done), Example Mapping capture (blue/green/red cards → Gherkin scenarios), Event Storming support, automatic checkpoints before state transitions, coverage tracking linking Gherkin scenarios to test files and implementation code, and a tree-sitter AST analyzer for 16 programming languages. The framework was built using itself (dogfooding) producing 257 feature files with complete Gherkin specifications. fspec ships Claude Code commands, an AGENTS.md, and an MCP server for AI agent integration. With 69 stars and an active development trajectory (3 contributors), it is the most feature-rich spec management CLI in this batch. Closest seed is superpowers (both enforce TDD as a workflow discipline), but fspec adds a dedicated CLI infrastructure layer, Gherkin-native spec format, TUI Kanban board, and checkpoint-based recovery that superpowers lacks.

01

Overview

fspec (sengac) — Origin & Philosophy

Origin

Created by SENGAC (software consultancy). Last commit May 2026. 69 stars, 3 contributors, MIT license. The framework was built using itself — dogfooding ACDD at scale produced 257 feature files with complete Gherkin specifications, reportedly in weeks vs. "9-12 months for a traditional QA + BA team."

Core Philosophy (verbatim from README)

"Stop micromanaging AI. Start shipping tested code."

"AI agents lack the infrastructure that professional developers take for granted. No way to easily force AI to follow your acceptance criteria or ask questions about things it doesn't understand. AI confabulates without quality examples and doesn't ask when it needs to know what it doesn't know. No TDD guardrails. No or poorly implemented checkpoint systems for safe experimentation. No Kanban boards for tracking workflow state. No specification management systems with mermaid diagram viewers and markdown documentation. No coverage tracking to link code back to business rules. AI agents are coding in the dark, and you're left babysitting instead of building."

"fspec is the holy grail: a complete spec-driven system that shepherds AI through professional Gherkin scenarios, auto-generates tests from Given/When/Then criteria, enforces TDD discipline, and links every line of code back to the business rule it implements."

ACDD (Acceptance Criteria Driven Development)

fspec implements ACDD as an extension of BDD/TDD:

  1. Example Mapping first — collaborative discovery of business rules, concrete examples, and questions using the blue/green/red card methodology
  2. Gherkin specification — concrete examples → Given/When/Then scenarios
  3. Test generation — auto-generate test skeletons from scenarios
  4. TDD enforcement — temporal validation prevents writing code before tests
  5. Coverage tracking — .feature.coverage files link scenarios to test files to implementation code

SENGAC Business Model

The README includes a consulting offer: "SENGAC specializes in transforming legacy nightmares into modern, AI-tested, fully-specified systems using tools like fspec." This is commercial tooling from a consulting firm.

02

Architecture

fspec (sengac) — Architecture

Distribution

npm package (@sengac/fspec), installed globally.

Install

npm install -g @sengac/fspec
cd /path/to/your/project
fspec init
# Then in agent: /fspec (Claude Code) or /prompts:fspec (Codex)
# Or tell agent: "Run fspec bootstrap"

Required Runtime

  • Node.js (version unspecified, TypeScript-compiled)

Directory Structure (source)

src/
├── commands/          # 20+ CLI command handlers
├── components/        # Shared TypeScript components
├── generators/        # Code generation utilities
├── git/               # Git checkpoint system
├── guidance/          # AI guidance files
├── hooks/             # Virtual hook system
├── migrations/        # fspec data migrations
├── research-tools/    # AST analysis, codebase research
├── schemas/           # JSON schema definitions
├── server/            # MCP server implementation
├── tui/               # Terminal UI (Kanban board)
│   ├── components/    # TUI components
│   ├── context/       # TUI state management
│   ├── hooks/         # TUI React hooks
│   ├── layouts/       # TUI layout components
│   ├── navigation/    # TUI navigation
│   └── store/         # TUI state store
├── types/             # TypeScript type definitions
├── utils/             # Shared utilities
└── validators/        # Spec/work unit validators
spec/
├── FOUNDATION.md          # Auto-generated from foundation.json
├── FOUNDATION.json         # Project foundation data
├── features/              # 257+ Gherkin feature files
└── work-units.json        # Work unit registry

Target AI Tools

Primary: Claude Code, Codex CLI. Also supports: any agent that can run CLI commands.

Claude Code Integration

  • .claude/commands/ — slash commands installed by fspec init
  • AGENTS.md — AI developer guidelines for fspec itself
  • CLAUDE.md — references AGENTS.md

MCP Server

src/server/ — MCP server for AI agent access to fspec data.

03

Components

fspec (sengac) — Components

CLI Commands (fspec binary)

Comprehensive command set (20+ subcommands):

Project Management:

  • fspec init — initialize fspec in project
  • fspec bootstrap — full project context bootstrap (run in AI agent)
  • fspec board — launch interactive TUI Kanban board

Work Units:

  • fspec create-story <title> — create user story work unit
  • fspec create-task <title> — create task work unit
  • fspec create-bug <title> — create bug work unit
  • fspec list-work-units — list all work units with status
  • fspec move-work-unit <id> <state> — transition work unit workflow state
  • fspec view-work-unit <id> — view work unit details

Example Mapping & Discovery:

  • fspec example-map <id> — run Example Mapping session for a work unit
  • fspec event-storm <scope> — conduct Event Storming session

Specification:

  • fspec generate-scenarios <id> — generate Gherkin from Example Map
  • fspec validate-spec <path> — validate .feature file syntax + tags

Checkpoints:

  • fspec create-checkpoint <name> — create named Git checkpoint
  • fspec list-checkpoints <id> — list checkpoints for a work unit
  • fspec restore-checkpoint <id> <name> — restore from checkpoint
  • fspec auto-checkpoint <id> — create automatic pre-transition checkpoint

Coverage:

  • fspec link-coverage <feature> <test> — link feature to test file
  • fspec check-coverage <id> — check coverage completeness

Foundation:

  • fspec generate-foundation-md — regenerate FOUNDATION.md from foundation.json
  • fspec report-bug-to-github — gather context and file a GitHub issue

Claude Code Slash Commands (installed by fspec init)

  • /fspec — bootstrap fspec context (loads FOUNDATION.md, feature files, work units)
  • /fspec:commit — commit with conventional commits
  • /fspec:publish — publish workflow
  • /fspec:release — release workflow

Virtual Hooks

fspec implements a virtual hook system (not Claude Code hooks): work-unit-scoped and global lifecycle hooks executed at workflow state transitions. Custom validators, test runners, and automation can be registered.

TUI (Interactive Kanban)

  • Live Kanban board with real-time updates
  • Work unit details panel
  • Checkpoint viewer (press C)
  • Attachment viewer with Mermaid diagram rendering (press A)
  • Keyboard-driven navigation

MCP Server

src/server/ — exposes fspec data to AI agents via MCP protocol.

05

Prompts

fspec (sengac) — Prompt Files

Excerpt 1: FOUNDATION.md — Vision Statement (auto-generated from spec/foundation.json)

# fspec Project Foundation

## Vision
The only system that transforms business conversations into production-ready features—unifying
product owners, business analysts, developers, QA engineers, and AI agents in a single disciplined
workflow where requirements become executable specs, specs become tests, and complete traceability
prevents anyone (human or AI) from breaking the chain.

## Problem Space
Product owners define business value in Jira. Business analysts capture requirements in sticky
notes during Example Mapping sessions that get photographed and forgotten. Developers write
Gherkin specs in .feature files disconnected from those requirements. QA engineers write tests
disconnected from the specs. AI agents skip all of this and write code with zero traceability.
The result: what gets built rarely matches what was discussed, tests don't validate the right things,
and nobody can trace a line of code back to the business requirement that justified it.

Technique: Foundation document as north-star prompt — the FOUNDATION.md (auto-generated from a structured JSON source) serves as the authoritative project context that agents read at bootstrap time. By making it auto-generated, the foundation stays in sync with the structured data.

Excerpt 2: AGENTS.md — Zero-Tolerance TypeScript Violations

## MANDATORY CODING STANDARDS - ZERO TOLERANCE

**CRITICAL DO NOT VIOLATIONS - CODE WILL BE REJECTED**

#### TypeScript Violations:
- ❌ **NEVER** use `any` type - use proper types always
- ❌ **NEVER** use `as unknown as` - use proper type guards or generics
- ❌ **NEVER** use `require()` - only ES6 `import`/`export`
- ❌ **NEVER** use `var` - only `const`/`let`
- ❌ **NEVER** use `==` or `!=` - only `===` and `!==`

Technique: Zero-tolerance violation lists — explicit banned patterns with visual "❌ NEVER" markers. This is a prompt engineering pattern where clarity of prohibition trumps politeness. Each violation includes the correction pattern.

Excerpt 3: Recovery Instructions (from README)

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."

Technique: Fault-tolerant workflow design — the system explicitly anticipates agent failures and provides recovery scripts. The checkpoint system is the technical enabler; the natural language recovery phrases are the user-facing interface for correcting agent drift.

Prompting Techniques Summary

  1. Foundation document as north-star — auto-generated FOUNDATION.md from structured data
  2. Zero-tolerance violation lists — explicit banned patterns with visual markers
  3. Recovery scripts for common failures — natural language instructions for checkpoint-based recovery
  4. ACDD workflow states as guardrails — state machine prevents out-of-order implementation
  5. Gherkin as executable specification — Given/When/Then scenarios directly generate test skeletons
09

Uniqueness

fspec (sengac) — Uniqueness & Positioning

differs_from_seeds

Most similar to superpowers (both enforce TDD as a mandatory workflow discipline), but fspec provides a dedicated CLI infrastructure layer with a Kanban TUI, Git checkpoints, Gherkin-native feature file management, Example Mapping facilitation, Event Storming support, AST code analysis, and coverage tracking — all of which superpowers delegates to the agent's own judgment. Against spec-kit (Python CLI), fspec is TypeScript, uses Gherkin (.feature files) as spec format rather than markdown, and enforces TDD through a state machine rather than hooks. Against kiro (also has workflow states), fspec is open-source, runs as a CLI tool, and uses Gherkin as the spec format rather than EARS notation.

Unique Positioning

fspec is the only framework in the corpus that:

  1. Uses Gherkin (.feature files) as the primary spec format — not markdown
  2. Implements ACDD (Acceptance Criteria Driven Development) with Example Mapping + Event Storming
  3. Ships a TUI Kanban board with Mermaid diagram rendering
  4. Implements Git-based checkpoint system with auto-checkpoints before state transitions
  5. Tracks coverage at the scenario → test file → implementation code level via .feature.coverage files
  6. Includes tree-sitter AST analysis for 16 languages for "Reverse ACDD" (importing existing codebases)
  7. Was built using itself (dogfooding) — 257 feature files with complete Gherkin specs

Observable Failure Modes

  1. Complexity barrier: 20+ CLI commands with specialized concepts (Example Mapping, ACDD, coverage files) require significant onboarding.
  2. Gherkin-specific: teams that don't use BDD/Gherkin face a methodology change, not just a tool change.
  3. No web UI: TUI only; no browser-based dashboard for non-terminal users.
  4. Commercial origin: SENGAC is a consulting firm; fspec may become a commercial product.
  5. Single real contributor: 3 contributors but likely SENGAC-internal; community momentum uncertain.

Explicit Antipatterns (from README + AGENTS.md)

  • Skipping Example Mapping and going straight to coding
  • Writing code before generating tests (ACDD violation)
  • Using any type in TypeScript (zero-tolerance ban)
  • Using require() instead of ES6 imports
  • Using var instead of const/let
04

Workflow

fspec (sengac) — Workflow

ACDD Workflow States (for each Work Unit)

backlog → specifying → testing → implementing → validating → done

Automatic checkpoints are created before every state transition.

Phase-to-Artifact Map

Phase Command Artifact
1. Story Creation fspec create-story "Add Event Storming" Work unit in work-units.json
2. Discovery fspec example-map <id> or fspec event-storm Example Map (rules, examples, questions)
3. Specification fspec generate-scenarios <id> .feature file with Gherkin scenarios
4. Spec Validation fspec validate-spec <path> Pass/fail + error report
5. Test Generation Agent generates test skeleton from Gherkin Test files with @step links
6. Implementation Agent implements against failing tests Code + coverage links
7. Coverage Check fspec check-coverage <id> Coverage report
8. Validation Agent verifies all tests pass Passing test suite
9. Done fspec move-work-unit <id> done Completed work unit

Approval Gates

Gate Type Description
Specifying → Testing implicit Spec must be complete before testing begins
Testing → Implementing TDD enforcement Temporal validation: tests must exist before code
Checkpoint on every transition automatic Auto-checkpoint before each state change

TDD Enforcement

fspec's temporal validation prevents writing code before tests:

  • @step comment annotations link test steps to Gherkin steps
  • Workflow state enforces: specifying → testing → implementing (no skipping)
  • Agents that "skip Example Mapping" can be rolled back via checkpoint restore

Recovery Pattern (from README)

"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."

Attachment Workflow

Agents can attach markdown documents with Mermaid diagrams to work units before Example Mapping:

"Create a story about adding Event Storming. Research this topic and create a markdown document with mermaid diagrams and attach it to this story using fspec."
06

Memory Context

fspec (sengac) — Memory & Context

State Storage

File-based JSON files in spec/ directory:

  • spec/work-units.json — all work units with workflow states, metadata
  • spec/epics.json — epic definitions
  • spec/tags.json — tag registry
  • spec/prefixes.json — work unit prefix definitions
  • spec/foundation.json — project foundation data (structured source)
  • spec/FOUNDATION.md — auto-generated human-readable foundation (NEVER edit directly)
  • spec/features/ — Gherkin .feature files (main spec format)
  • .feature.coverage — coverage files linking scenarios to tests to code

Git Checkpoint System

fspec uses Git as the checkpoint backend:

  • fspec create-checkpoint <name> — creates a named git checkpoint (likely a git stash or tag)
  • Automatic checkpoints created before every workflow state transition
  • Restorable: fspec restore-checkpoint <id> <name>
  • Non-destructive: "Checkpoints can be restored multiple times — experiment fearlessly"

Cross-Session Handoff

Yes — all state is JSON files and Git history. Any session picks up from current work-units.json state.

Context Loading Protocol

At session start, agents run fspec bootstrap which:

  • Loads spec/FOUNDATION.md into context
  • Loads current work unit list
  • Reads agent guidance files

Compaction

None. Context management relies on natural file boundaries (FOUNDATION.md, relevant feature files per work unit).

Memory Type

File-based (JSON + Gherkin .feature files + FOUNDATION.md).

Persistence Scope

Project-scoped (all files in spec/ directory).

07

Orchestration

fspec (sengac) — Orchestration

Multi-Agent

No. fspec is single-agent. Multiple agents could theoretically access the same fspec project (shared JSON files + git), but no multi-agent coordination mechanism exists.

Orchestration Pattern

Sequential. The ACDD workflow states enforce sequential progression: specifying → testing → implementing → validating → done.

Execution Mode

Interactive-loop. Agent interacts with fspec CLI commands within a session; TUI provides a visual dashboard.

Isolation Mechanism

Git checkpoints. Before every state transition, an automatic git checkpoint is created. Agents can experiment and roll back. This is the primary isolation/recovery mechanism.

Multi-Model

No. fspec is model-agnostic (Claude Code and Codex CLI supported), but no model-per-role routing.

Consensus Mechanism

None. The ACDD workflow states are the governance mechanism: agents cannot proceed to implementing without tests existing.

Auto-Validators

  • fspec validate-spec <path> — Gherkin syntax + tag validation
  • fspec check-coverage <id> — coverage completeness check
  • Temporal validation: enforces test-before-code ordering via workflow state machine
  • Virtual hooks: custom validation scripts at state transitions

TDD Enforcement

Yes — explicit. Temporal validation prevents code before tests. The workflow state machine enforces: specifying → testing → implementing (testing state = tests must exist before moving to implementing).

Git Automation

Automatic git checkpoints at each state transition. No automatic commits, PRs, or merges.

Cross-Tool Portability

Medium. Primary: Claude Code (slash commands) and Codex CLI (prompts). Secondary: any agent that can run CLI commands.

AST Analysis

fspec includes tree-sitter-based AST analysis for 16 programming languages (src/research-tools/) for "pattern detection, function discovery, and deep codebase understanding during discovery."

08

Ui Cli Surface

fspec (sengac) — UI & CLI Surface

CLI Binary

  • Name: fspec
  • Package: @sengac/fspec (npm global)
  • Type: Dedicated CLI (TypeScript, compiled)
  • Subcommands: 20+

TUI (Interactive Kanban Board)

  • Launch: fspec (no subcommand) or fspec board
  • Type: Terminal TUI
  • Features:
    • Live Kanban board with real-time updates
    • Work unit detail panel
    • Checkpoint viewer (press C)
    • Attachment viewer with Mermaid diagram rendering (press A)
    • Keyboard-driven navigation

Claude Code Integration

fspec init        # installs Claude Code slash commands to .claude/commands/
/fspec            # bootstrap fspec context in Claude Code

Codex CLI Integration

/prompts:fspec    # in Codex

MCP Server

src/server/ — MCP server for AI agent access (protocol: stdio or HTTP).

Web

None. fspec is CLI + TUI only. No web dashboard.

Observability

  • fspec list-work-units — all work units with states
  • fspec board — visual TUI Kanban
  • fspec check-coverage <id> — coverage report
  • fspec validate-spec <path> — spec validation report

Bug Reporting Integration

"Report a bug to GitHub"  # agent runs fspec report-bug-to-github

Automatically gathers context and creates a GitHub issue.

Documentation Site

https://fspec.dev

Related frameworks

same archetype · same primary tool · same memory type

BMAD-METHOD ★ 48k
A4 Markdown scaffold

Provides a full agile delivery lifecycle with named expert-persona AI collaborators that elicit the human's best thinking rather…

Agent OS ★ 4.6k
A4 Markdown scaffold

Extracts implicit codebase conventions into token-efficient markdown standards files and injects them selectively into AI agent…

Claude Conductor ★ 367
A4 Markdown scaffold

Gives Claude Code a persistent, cross-linked, auto-analyzed documentation system so it retains codebase context across sessions.

Spec-Driver (Greenfield Spec-Driven Development) ★ 25
A4 Markdown scaffold

Prevents spec rot in AI-assisted development by making implementation changes flow back into evergreen, authoritative specs via…

Anthropic Knowledge Work Plugins ★ 16k
A4 Markdown scaffold

Role-specialized plugin bundles with live MCP connectors that turn Claude into a domain expert for enterprise knowledge workers.

Codex Integration for Claude Code (skill-codex) ★ 1.3k
A4 Markdown scaffold

Single Claude Code skill that handles Codex CLI invocation correctly (stdin blocking, thinking token suppression, session resume)…