# specflow

Adopt this skill: https://proskills.md/skills/coding/specflow

Page: https://proskills.md/skills/coding/specflow
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: .gitignore
upstream: https://github.com/hulupeep/specflow/blob/HEAD/.gitignore

Content is not inlined in the catalog. Read the upstream file: https://github.com/hulupeep/specflow/blob/HEAD/.gitignore

## File: CI-INTEGRATION.md
upstream: https://github.com/hulupeep/specflow/blob/HEAD/CI-INTEGRATION.md

Content is not inlined in the catalog. Read the upstream file: https://github.com/hulupeep/specflow/blob/HEAD/CI-INTEGRATION.md

## File: CLAUDE-MD-TEMPLATE.md
upstream: https://github.com/hulupeep/specflow/blob/HEAD/CLAUDE-MD-TEMPLATE.md

Content is not inlined in the catalog. Read the upstream file: https://github.com/hulupeep/specflow/blob/HEAD/CLAUDE-MD-TEMPLATE.md

## File: CLAUDE.md
upstream: https://github.com/hulupeep/specflow/blob/HEAD/CLAUDE.md

Content is not inlined in the catalog. Read the upstream file: https://github.com/hulupeep/specflow/blob/HEAD/CLAUDE.md

## File: CONTRACT-SCHEMA-EXTENSIONS.md
upstream: https://github.com/hulupeep/specflow/blob/HEAD/CONTRACT-SCHEMA-EXTENSIONS.md

Content is not inlined in the catalog. Read the upstream file: https://github.com/hulupeep/specflow/blob/HEAD/CONTRACT-SCHEMA-EXTENSIONS.md

## File: CONTRACT-SCHEMA.md
upstream: https://github.com/hulupeep/specflow/blob/HEAD/CONTRACT-SCHEMA.md

Content is not inlined in the catalog. Read the upstream file: https://github.com/hulupeep/specflow/blob/HEAD/CONTRACT-SCHEMA.md

## File: CONTRACTS-README.md
upstream: https://github.com/hulupeep/specflow/blob/HEAD/CONTRACTS-README.md

Content is not inlined in the catalog. Read the upstream file: https://github.com/hulupeep/specflow/blob/HEAD/CONTRACTS-README.md

## File: FRONTIER_IMPROVEMENTS.md
upstream: https://github.com/hulupeep/specflow/blob/HEAD/FRONTIER_IMPROVEMENTS.md

Content is not inlined in the catalog. Read the upstream file: https://github.com/hulupeep/specflow/blob/HEAD/FRONTIER_IMPROVEMENTS.md

## File: LICENSE
upstream: https://github.com/hulupeep/specflow/blob/HEAD/LICENSE

Content is not inlined in the catalog. Read the upstream file: https://github.com/hulupeep/specflow/blob/HEAD/LICENSE

## File: LLM-MASTER-PROMPT.md
upstream: https://github.com/hulupeep/specflow/blob/HEAD/LLM-MASTER-PROMPT.md

Content is not inlined in the catalog. Read the upstream file: https://github.com/hulupeep/specflow/blob/HEAD/LLM-MASTER-PROMPT.md

## File: MID-PROJECT-ADOPTION.md
upstream: https://github.com/hulupeep/specflow/blob/HEAD/MID-PROJECT-ADOPTION.md

Content is not inlined in the catalog. Read the upstream file: https://github.com/hulupeep/specflow/blob/HEAD/MID-PROJECT-ADOPTION.md

## File: PROMPT-TEMPLATE.md
upstream: https://github.com/hulupeep/specflow/blob/HEAD/PROMPT-TEMPLATE.md

Content is not inlined in the catalog. Read the upstream file: https://github.com/hulupeep/specflow/blob/HEAD/PROMPT-TEMPLATE.md

## File: PUSH-TO-GITHUB.md
upstream: https://github.com/hulupeep/specflow/blob/HEAD/PUSH-TO-GITHUB.md

Content is not inlined in the catalog. Read the upstream file: https://github.com/hulupeep/specflow/blob/HEAD/PUSH-TO-GITHUB.md

## File: QUICKSTART.md
upstream: https://github.com/hulupeep/specflow/blob/HEAD/QUICKSTART.md

Content is not inlined in the catalog. Read the upstream file: https://github.com/hulupeep/specflow/blob/HEAD/QUICKSTART.md

## File: README.md
upstream: https://github.com/hulupeep/specflow/blob/HEAD/README.md

````text
# Specflow

**Specs that enforce themselves.**

LLMs drift. You write a rule; three iterations later the model "helpfully" ignores it. Specflow turns your specs into contract tests that break the build when violated — so drift can't ship.

---

## The Problem

```typescript
// Your spec: "Service workers MUST NOT use localStorage"
// LLM adds this anyway after iteration 3:
const token = localStorage.getItem('auth') // No crash. Just drift.
```

**LLMs don't read. They attend.** Your carefully worded spec competes with millions of training examples. Three hours into a session, the model drifts while presenting itself as knowing exactly what you're working on. You can't fix this with better prompts. You need a gate.

---

## The Solution

Contract tests scan your source code for forbidden patterns. Break a rule → CI fails before build. Journey tests run Playwright against your critical flows. If a journey doesn't pass, the feature isn't done.

> *Do what you like — explore, generate, surprise me — but I'm going to type-check you at the end.*

---

## Get Started

**One command installs everything:**

```bash
bash /path/to/Specflow/setup-project.sh /path/to/your/project
```

This creates contracts, agents, hooks, tests, and verifies everything passes.

**Then update CLAUDE.md** with your project context and tell Claude Code:

```
Execute waves
```

For all setup paths (manual, SKILL.md, Claude-assisted), see [Getting Started](docs/getting-started.md).

### Already have Specflow? Update it.

Paste this into Claude Code:

```
Pull the latest Specflow from /path/to/Specflow (or git pull it first).
Run bash /path/to/Specflow/setup-project.sh . to update my setup.
Then run bash /path/to/Specflow/verify-setup.sh and fix every failure.
I want 0 failures before we start any tickets.
```

The setup script is safe to re-run — it skips existing files and backs up settings before merging. See [Updating an Existing Setup](docs/getting-started.md#updating-an-existing-setup) for more options.

---

## What "Specflow-Compliant" Actually Means

An issue or spec is not Specflow-compliant just because it has `REQS` and `JOURNEYS`.

Minimum required sections:
- `REQS`
- `INVARIANTS`
- `Persona Simulation`
- `JOURNEYS`
- `TESTS`
- `DEFINITION OF DONE`

Minimum required traceability:
- every `MUST` requirement maps to at least one test
- each ticket/spec declares whether it has a direct UI surface
- direct UI surfaces must have Playwright coverage or an explicit `N/A` justification
- docs/discoverability work must either expose a real discovery surface or declare itself repo-only
- persona simulation must feed structured pre-flight findings (`simulation_status`, `CRITICAL`, `P1`, `P2`)

Test categories can include:
- feature
- contract
- security
- Playwright / e2e
- unit / integration when appropriate

If `INVARIANTS` or `TESTS` are missing, the issue/spec is not compliant.
If a workflow, UI, permissions, or automation ticket is missing `Persona Simulation`, it is not compliant.

---

## FAQ

**Isn't this just more testing?** No. Tests verify behaviour. Contracts verify architecture. "No localStorage for tokens" survives any refactor. "login() returns a token" doesn't.

**What if I don't have a perfect spec?** Start with "document what works today." Your first contract can be: whatever we're doing now, don't break it.

**Can LLMs actually follow contracts?** Yes — and even if they don't, tests catch it in CI. You don't need the LLM to behave. You need it to be checkable.

**How is this different from linting?** Linting: syntax and style. Contracts: architecture and business rules. Both valuable, different problems.

---

## Built on Real Projects

Delivered 280+ GitHub issues on a production project using Specflow. 0 critical E2E anti-patterns (down from 117). Autonomous wave execution across 30 waves. [Full story →](docs/team-workflows.md#production-track-record)

---

## Where Do You Want to Go?

| I want to... | Go here |
|---|---|
| Decide if Specflow is right for my project | [Should I use Specflow?](docs/should-i-use-specflow.md) |
| Install and configure Specflow | [Getting Started](docs/getting-started.md) |
| Understand how it works | [How It Works](docs/how-it-works.md) |
| Use Specflow with a team | [Team Workflows](docs/team-workflows.md) |
| Set up CI enforcement | [CI Integration](CI-INTEGRATION.md) |
| Browse all 23+ agents | [Agent Library](agents/README.md) |
| Commands and config reference | [Reference](docs/reference.md) |

---

*Made for developers who want specs that actually matter.*
[Colm Byrne](https://www.linkedin.com/in/colmbyrne/) · [GitHub](https://github.com/Hulupeep) · [MIT License](https://opensource.org/licenses/MIT) · [Issues / Ideas](https://github.com/Hulupeep/Specflow/issues)

---

## Try It (2 minutes)

```bash
cd demo && npm install && npm run demo
```

A working app. An LLM "optimisation" that breaks it. Contract tests catching what unit tests missed.
````

## File: README_FRONTIER.md
upstream: https://github.com/hulupeep/specflow/blob/HEAD/README_FRONTIER.md

Content is not inlined in the catalog. Read the upstream file: https://github.com/hulupeep/specflow/blob/HEAD/README_FRONTIER.md

## File: SKILL.md
upstream: https://github.com/hulupeep/specflow/blob/HEAD/SKILL.md

Content is not inlined in the catalog. Read the upstream file: https://github.com/hulupeep/specflow/blob/HEAD/SKILL.md

## File: SPEC-FORMAT.md
upstream: https://github.com/hulupeep/specflow/blob/HEAD/SPEC-FORMAT.md

Content is not inlined in the catalog. Read the upstream file: https://github.com/hulupeep/specflow/blob/HEAD/SPEC-FORMAT.md

## File: USER-JOURNEY-CONTRACTS.md
upstream: https://github.com/hulupeep/specflow/blob/HEAD/USER-JOURNEY-CONTRACTS.md

Content is not inlined in the catalog. Read the upstream file: https://github.com/hulupeep/specflow/blob/HEAD/USER-JOURNEY-CONTRACTS.md

## File: extract-to-project.sh
upstream: https://github.com/hulupeep/specflow/blob/HEAD/extract-to-project.sh

Content is not inlined in the catalog. Read the upstream file: https://github.com/hulupeep/specflow/blob/HEAD/extract-to-project.sh