SpecFlow Bundle

Spec-Driven Development for AI Infrastructure

---

Why SpecFlow?

The Promise vs The Reality

AI coding assistants promise "10x developer productivity" — just describe what you want and watch the code appear. The reality? A frustrating cycle:

Copy → Paste → Fix → Repeat. Hallucinated APIs. Lost context. Code that works once and breaks mysteriously. Every session starts from zero.

The Insight

The AI is the same. The architecture around it isn't.

The breakthrough isn't a better model — it's better scaffolding. When you give AI agents structure, constraints, and verification gates, they stop hallucinating and start engineering.

Code is a Liability

Cory Doctorow articulated what experienced developers know: code is a liability, not an asset. Every line requires maintenance. Every feature adds complexity. Probabilities are multiplicative — chain enough unreliable components and your system will fail.

SpecFlow embraces this truth. Instead of letting AI generate code freely, we force it through engineering discipline:

The Four-Phase Workflow

SPECIFY → PLAN → TASKS → IMPLEMENT

Phase	What Happens	Gate
SPECIFY	Interview-driven requirements. What are we building? Why?	Human approves spec
PLAN	Architecture decisions, data models, failure modes	Human approves design
TASKS	Break work into reviewable units with dependencies	Human approves breakdown
IMPLEMENT	TDD execution with verification	Tests pass, contracts verified

Each gate requires human approval. The AI cannot skip ahead. No code gets written until the spec, plan, and tasks are complete.

The Result

• No hallucinated features — everything traces back to approved specs
• No forgotten context — SQLite database tracks all features and progress
• No mysterious breakage — dependency tracking catches cascading failures
• Resumable anytime — interrupt and pick up exactly where you left off

The AI does the work. You provide direction and corrections.

---

FOR AI AGENTS: You are installing the SpecFlow Bundle into a PAI installation. Run the install wizard OR follow the manual installation steps below. Each package must be FULLY installed with ALL files. No shortcuts.

---

Quick Start

# Clone with submodules
git clone --recursive https://github.com/jcfischer/specflow-bundle.git
cd specflow-bundle

# Run the installer
bun run install.ts

# Or update an existing installation
bun run install.ts --update

---

What's Included

#	Package	Purpose
1	SpecFlow	Unified spec-driven workflow + CLI
2	specflow-ui	Progress dashboard
3	pai-deps	Dependency tracking

---

CRITICAL: Full Implementation Required

FOR AI AGENTS: This section is mandatory. Do not skip or simplify.

The Problem

AI agents systematically create "simplified" versions of installations, omitting files, shortening code, and creating broken setups. This is unacceptable.

The Rules

1. EVERY PACKAGE = FULL INSTALLATION - All files must be copied
2. EVERY FILE SPECIFIED = EVERY FILE CREATED - No omissions
3. EVERY DEPENDENCY = INSTALLED - Run bun install for each package
4. IF YOU CAN'T DO IT FULLY, STOP AND SAY SO - Permission to refuse

---

Manual Installation (For AI Agents)

If not using the install wizard, follow these steps exactly:

Prerequisites

• Bun runtime installed (curl -fsSL https://bun.sh/install | bash)
• Claude Code installed (~/.claude/ directory exists)
• Git with submodule support

Step 1: Clone Repository

git clone --recursive https://github.com/jcfischer/specflow-bundle.git
cd specflow-bundle

Verify:

• packages/specflow/ exists with files
• packages/specflow-ui/ exists with files
• packages/pai-deps/ exists with files (submodule)

Step 2: Install SpecFlow Skill

cp -r packages/specflow ~/.claude/skills/SpecFlow
cd ~/.claude/skills/SpecFlow && bun install

Verify SpecFlow installation:

• ~/.claude/skills/SpecFlow/SKILL.md exists
• ~/.claude/skills/SpecFlow/src/index.ts exists
• ~/.claude/skills/SpecFlow/src/commands/ directory with 19 files
• ~/.claude/skills/SpecFlow/src/lib/ directory with lib files + eval/
• ~/.claude/skills/SpecFlow/templates/ directory with 6 files
• ~/.claude/skills/SpecFlow/evals/ directory with rubrics
• ~/.claude/skills/SpecFlow/workflows/ directory
• ~/.claude/skills/SpecFlow/node_modules/ exists (after bun install)

Step 3: Install specflow-ui

mkdir -p ~/.config/specflow
cp -r packages/specflow-ui ~/.config/specflow/ui
cd ~/.config/specflow/ui && bun install

Create launcher script:

mkdir -p ~/.local/bin
cat > ~/.local/bin/specflow-ui << 'EOF'
#!/bin/bash
cd ~/.config/specflow/ui
exec bun run src/server.ts "$@"
EOF
chmod +x ~/.local/bin/specflow-ui

Verify specflow-ui installation:

• ~/.config/specflow/ui/src/server.ts exists
• ~/.config/specflow/ui/src/pages/ directory with 9 files
• ~/.config/specflow/ui/src/lib/ directory with 8 files
• ~/.config/specflow/ui/node_modules/ exists (after bun install)
• ~/.local/bin/specflow-ui exists and is executable

Step 4: Install pai-deps

cp -r packages/pai-deps ~/.config/specflow/pai-deps
cd ~/.config/specflow/pai-deps && bun install

Create launcher script:

cat > ~/.local/bin/pai-deps << 'EOF'
#!/bin/bash
cd ~/.config/specflow/pai-deps
exec bun run src/index.ts "$@"
EOF
chmod +x ~/.local/bin/pai-deps

Verify pai-deps installation:

• ~/.config/specflow/pai-deps/src/index.ts exists
• ~/.config/specflow/pai-deps/node_modules/ exists (after bun install)
• ~/.local/bin/pai-deps exists and is executable

Step 5: Verify PATH

Ensure ~/.local/bin is in your PATH:

echo $PATH | grep -q "$HOME/.local/bin" || echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc

---

Full Bundle Installation Checklist

After completing all steps, verify:

• SpecFlow - FULLY installed in ~/.claude/skills/SpecFlow/

  • All 19 command files in src/commands/
  • All lib files in src/lib/ including eval/ subdirectory
  • All 6 template files in templates/
  • evals/ directory with rubrics
  • workflows/ directory
  • SKILL.md present
  • Dependencies installed

• specflow-ui - FULLY installed in ~/.config/specflow/ui/

  • All 9 page files in src/pages/
  • All 8 lib files in src/lib/
  • Launcher at ~/.local/bin/specflow-ui
  • Dependencies installed

• pai-deps - FULLY installed in ~/.config/specflow/pai-deps/

  • Source files in src/
  • Launcher at ~/.local/bin/pai-deps
  • Dependencies installed

• PATH configured - ~/.local/bin in PATH

---

Usage After Installation

SpecFlow CLI (Unified Commands)

# Core workflow
specflow init my-project     # Initialize a new project
specflow add "New feature"   # Add a feature
specflow status              # Check progress
specflow specify F-1         # Create specification
specflow plan F-1            # Create implementation plan
specflow tasks F-1           # Generate task breakdown
specflow implement F-1       # Execute with TDD enforcement
specflow complete F-1        # Mark feature complete

# Contribution preparation
specflow contrib-prep F-1              # Full workflow with 5 approval gates
specflow contrib-prep F-1 --inventory  # Generate file inventory only
specflow contrib-prep F-1 --sanitize   # Run secret/PII scanning only
specflow contrib-prep F-1 --extract    # Extract to clean contrib branch
specflow contrib-prep F-1 --verify     # Verify contribution branch
specflow contrib-prep F-1 --dry-run    # Preview without changes

# Quality & management
specflow eval run            # Run quality evaluations
specflow phase F-1 implement # Get or set feature phase
specflow revise F-1          # Revise spec/plan/tasks artifact
specflow ui                  # Launch dashboard

pai-deps CLI

pai-deps health              # Show ecosystem health
pai-deps verify              # Verify all contracts
pai-deps blast-radius <tool> # Impact analysis
pai-deps deps <tool>         # Show dependencies

specflow-ui Dashboard

specflow-ui --port 3000      # Launch on port 3000
# Open http://localhost:3000

---

The Full Lifecycle

SPECIFY -> PLAN -> TASKS -> IMPLEMENT -> CONTRIB-PREP -> RELEASE

Phase	What	Output
SPECIFY	Define requirements, success criteria	spec.md
PLAN	Design architecture, data models	plan.md
TASKS	Break into reviewable units	tasks.md
IMPLEMENT	Build with TDD (RED->GREEN->BLUE)	Working code
CONTRIB-PREP	Extract clean contribution from private trunk	Tagged branch
RELEASE	Publish verified contribution	Released package

Each phase is gated - you cannot advance until the current phase is validated.

Quality Gates

SpecFlow includes built-in quality evaluations using YAML rubrics scored by AI:

• Spec Quality - Validates specification completeness (8 weighted criteria)
• Plan Quality - Validates technical design and architecture decisions
• Tasks Quality - Validates task granularity, dependencies, test coverage, and phased organization
• Quality threshold: >= 80% to proceed

specflow eval run                    # Run all applicable evals
specflow eval run --rubric spec-quality  # Run specific rubric

---

Collaborative Development with pai-collab

SpecFlow's contrib-prep command bridges private development with the pai-collab shared ecosystem:

1. Your Private Workspace -- Develop features in your private trunk using the full SpecFlow workflow
2. Contrib-Prep -- Extract clean contributions through 5 human-approved gates (inventory, sanitize, extract, verify, approve)
3. Shared Blackboard -- Submit via fork + PR to the pai-collab coordination repo
4. Review Pipeline -- Automated checks, Maestro playbook review, community agents, human sign-off
5. Ecosystem -- Released contributions available to all operators via the Daemon Registry

AI agents submit PRs like humans -- the operator is accountable. Fork model means no write access needed.

---

Architecture

+-------------------------------------------------------------+
|                    specflow-ui                               |
|              (Progress Dashboard)                            |
|         http://localhost:3000                                |
+----------------------------+---------------------------------+
                             | reads
                             v
+-------------------------------------------------------------+
|                    SpecFlow                                  |
|         (Unified CLI + Spec-Driven Workflow)                 |
|   specflow specify -> plan -> tasks -> implement             |
+----------------------------+---------------------------------+
                             | validates against
                             v
+-------------------------------------------------------------+
|                    pai-deps                                  |
|           (Dependency Registry)                              |
|   pai-deps verify | blast-radius | health                    |
+-------------------------------------------------------------+

---

Migration from Separate SpecKit

If you previously had SpecKit installed separately:

1. Remove the old SpecKit skill: rm -rf ~/.claude/skills/SpecKit
2. Install the updated SpecFlow (this bundle)
3. Update any references from /speckit.* commands to specflow CLI

Old Command	New Command
/speckit.specify	specflow specify F-N
/speckit.plan	specflow plan F-N
/speckit.tasks	specflow tasks F-N
/speckit.implement	specflow implement F-N

---

Support Development

This bundle is free and open source under the MIT license.

If SpecFlow Bundle helps you build better AI infrastructure, consider supporting continued development:

• Support on InVisible Store
• GitHub Sponsors

---

Links

• InVisible GmbH - Company behind SpecFlow Bundle
• Product Page - Full documentation
• Supertag CLI - Our Tana CLI tool
• pai-deps - Dependency management

---

License

MIT License - Use it, modify it, build on it.

---

Built with 35+ years of experience in complex IT environments.