Verify It’s Working

After installation, confirm that Specflow is active and enforcing contracts automatically.

Table of contents

  1. What’s Automatic (No Prompting Needed)
  2. Quick Verification Test
    1. Test 1: Contract Awareness
    2. Test 2: Journey Contracts and Hooks
  3. What You Should NOT Need to Say
  4. If It’s Not Working
    1. 1. Contract section is at the TOP of CLAUDE.md
    2. 2. File is named exactly CLAUDE.md in the project root
    3. 3. You are in the right directory when starting the session
    4. 4. Contracts exist in docs/contracts/*.yml
    5. 5. Run the verification script
  5. Commands That Trigger the Agent System
  6. The Litmus Test
  7. Related Pages

What’s Automatic (No Prompting Needed)

Once Specflow is installed, you do not need to tell Claude to use it. These things happen automatically:

Behavior How It Works You Say Nothing
CLAUDE.md is read at session start Claude Code reads CLAUDE.md in the project root when a session begins. Contract rules, agent registries, and auto-trigger rules are loaded automatically. You never say “use specflow.”
Contract checking on protected files When Claude modifies a file listed in a contract’s protected_files, it checks the contract rules first. You never say “check contracts.”
Hooks fire on build/commit Journey verification hooks run Playwright tests automatically after pnpm build or git commit. You never say “run tests.”
Security/accessibility gates are active If default contract templates are installed (docs/contracts/security_defaults.yml, etc.), those patterns are enforced on every change. You never say “check for security issues.”

You just work normally. The guardrails are there. If something violates a contract, the build fails and tells you why.

Quick Verification Test

After installation, start a new Claude Code session in your project directory and run these two verification prompts.

Test 1: Contract Awareness

Ask Claude:

What contracts are active in this project?

Expected Response (Specflow is working):

Claude should list contracts from docs/contracts/ with their IDs and rules:

Active contracts in this project:

Feature contracts:
  - feature_authentication.yml: AUTH-001 through AUTH-004
  - security_defaults.yml: SEC-001 through SEC-005
  - accessibility_defaults.yml: A11Y-001 through A11Y-004

Journey contracts:
  - journey_user_signup.yml: J-USER-SIGNUP (critical)
  - journey_checkout.yml: J-CHECKOUT (critical)

Total: 5 contracts, 18 invariants enforced.

Unexpected Response (Specflow is NOT working):

If Claude says any of these, the setup is incomplete:

  • “I don’t see any contracts in this project.”
  • “What contracts are you referring to?”
  • “I’m not familiar with Specflow.”

This means CLAUDE.md is not being read, or contracts are not installed in docs/contracts/.

Test 2: Journey Contracts and Hooks

Ask Claude:

Are journey contracts being executed? Are hooks running for specflow?

Expected Response (Hooks and journeys are working):

Claude should check for the hook infrastructure and journey test files:

Checking journey contract execution setup...

Hooks:
  - .claude/hooks/post-build.sh: Installed (runs journey tests after successful builds)
  - .claude/hooks/post-commit.sh: Installed (runs journey tests after commits)
  - Hook enforcement: Active (will block on test failures)

Journey contracts:
  - docs/contracts/journey_user_signup.yml: Maps to tests/e2e/journey_user_signup.spec.ts
  - docs/contracts/journey_checkout.yml: Maps to tests/e2e/journey_checkout.spec.ts

Test execution:
  - Hooks extract issue numbers from recent commits (e.g., #123)
  - Each issue is checked for journey contract ID (e.g., J-USER-SIGNUP)
  - Playwright runs only the relevant journey tests
  - Build/commit blocked if tests fail

Status: Journey enforcement is active.

Unexpected Response (Hooks/journeys NOT working):

If Claude says any of these, the hook setup is incomplete:

  • “I’m not sure what journey contracts are.”
  • “I don’t see any hooks installed.”
  • “Where should I look for journey tests?”

This means:

  • Hooks were not installed via install-hooks.sh
  • Journey contracts are missing from docs/contracts/
  • Journey test files are missing from tests/e2e/
  • CLAUDE.md does not include the Journey Verification Hooks section

What You Should NOT Need to Say

If Specflow is set up correctly, you should never need to prompt Claude with:

Do Not Say This Why It Means Setup Is Broken
“Re-read CLAUDE.md” Claude Code reads it automatically at session start
“Use specflow for this” CLAUDE.md auto-trigger rules handle this
“Remember to check contracts” Contract checking is triggered by protected file modification
“Follow the rules in CLAUDE.md” Rules are loaded into context automatically
“Run the tests before closing” Hooks and auto-trigger rules handle test execution

If you find yourself saying these things, your CLAUDE.md configuration needs attention.

If It’s Not Working

Check these five things in order:

1. Contract section is at the TOP of CLAUDE.md

Claude Code attends most strongly to content at the beginning of files. If the contract rules are buried after 500 lines of other instructions, they may not be followed consistently.

Fix: Move the ## Architectural Contracts section to the first major heading in CLAUDE.md.

2. File is named exactly CLAUDE.md in the project root

Not claude.md, not Claude.md, not .claude.md. The filename must be CLAUDE.md (all caps, in the project root directory).

ls -la CLAUDE.md
# Should show: -rw-r--r-- ... CLAUDE.md

3. You are in the right directory when starting the session

Claude Code reads the CLAUDE.md from the current working directory when the session starts. If you start Claude Code in a parent directory or a subdirectory, it reads a different CLAUDE.md (or none at all).

# Correct: start in the project root
cd /path/to/your-project
claude

# Wrong: starting from a parent directory
cd /path/to
claude  # Will not read your-project/CLAUDE.md

4. Contracts exist in docs/contracts/*.yml

The CLAUDE.md tells Claude to check contracts, but if no contract files exist, there is nothing to enforce. Install the default templates if you have not already:

# Check if contracts exist
ls docs/contracts/*.yml

# If empty, install defaults
cp Specflow/templates/contracts/*.yml docs/contracts/

5. Run the verification script

Run the 13-section verification:

npx @colmbyrne/specflow verify

# Or from a local clone:
# bash /path/to/Specflow/verify-setup.sh

Checks: directory structure, contract files, YAML validation, test infrastructure, CLAUDE.md, CI/CD, E2E setup, hooks (installed + executable + wired), agent library, fix patterns, contract metadata, graph validator, and version check (local vs source).

Commands That Trigger the Agent System

For projects with the full agent library installed, these explicit commands invoke specific agents:

Command What It Does
"Execute waves" Runs waves-controller: full backlog execution in dependency-ordered waves
"Execute issues #50, #51, #52" Runs waves-controller for specific issues only
"Execute waves for milestone v1.0" Runs waves-controller filtered by milestone
"Run board-auditor" Audits which GitHub issues are specflow-compliant
"Run e2e-test-auditor" Finds tests that silently pass when broken
"Run test-runner" Executes tests and reports failures with file:line details
"Run journey-enforcer" Checks journey coverage and release readiness
"Run contract-validator" Verifies implementation matches contract spec
/specflow Activates SKILL.md methodology (if SKILL.md installed)
/specflow verify Runs contract verification scan against codebase
/specflow spec Generates contracts from requirements
/specflow heal Attempts auto-fix of contract violations

These are explicit invocations. The automatic behaviors described above (CLAUDE.md reading, contract checking, hook firing) do not require any of these commands.

The Litmus Test

If Claude modifies a file in src/ without mentioning contracts, the CLAUDE.md is not being read.

When Specflow is working correctly, any modification to a protected file should produce output like:

Checking contracts before modifying src/features/auth/signup.ts...
  - feature_authentication.yml: AUTH-001 through AUTH-004
  - security_defaults.yml: SEC-001 through SEC-005
  No violations found. Proceeding with edit.

If you see Claude edit src/ files with no mention of contracts, go back to the troubleshooting checklist above.

View on GitHub