Spec-Verify: Spec-Driven Development & Multi-Layer Verification

Determine Task Complexity

Before writing a full spec document, gauge complexity:

Write the Spec

Use the template at assets/spec_template.md as a starting point. The spec includes:

• Problem Statement: What problem does this solve? Why now?
• Acceptance Criteria: BDD format (Given/When/Then). These become your tests.
• Constraints: Performance budgets, security requirements, compatibility needs
• Edge Cases: Boundary values, error conditions, concurrent access scenarios
• Out of Scope: Explicitly state what you won't do (prevents scope creep)
• Escalation Triggers: Conditions that require human review (see references/escalation_patterns.md)

For guidance on writing effective ACs, see references/spec_writing_guide.md.

Get Approval

Present the spec to the user. Do not proceed to implementation until they approve. If they suggest changes, update the spec and re-present.

For simple tasks, present inline and ask: "Does this AC look right?" For medium/complex tasks, save to .spec-verify/specs/<task-name>.md and present a summary.

Phase 2: Implement

Once the spec is approved:

Step 1: Tests First

Convert each AC into an executable test. The test framework depends on the project — detect it automatically (jest, pytest, vitest, cargo test, go test, etc.).

Each Given/When/Then maps directly:

• Given → test setup / fixtures
• When → action under test
• Then → assertion

Write these tests before any implementation code. They should fail initially — that's expected and correct.

Step 2: Write Implementation

Now write the code to make the tests pass. If a test needs modification to pass, that's a red flag — the spec may need updating, not the test. Pause and reconsider before changing any test.

Step 3: Run Tests

Run the new tests. If failures exist, fix the implementation (not the tests). Repeat until green.

Phase 3: Multi-Layer Verification

After implementation, run all four verification layers automatically. Each layer catches different categories of problems.

Layer 1: Deterministic Guardrails

These are fast, binary checks. Run the project's existing toolchain first.

Auto-detect and run:

• Linter (eslint, ruff, clippy, golint, etc.)
• Formatter check (prettier --check, black --check, rustfmt --check)
• Type checker (tsc --noEmit, mypy, pyright, cargo check)

Organization invariant checks (always run):

• Hardcoded secrets/API keys/tokens — run scripts/check_secrets.sh
• Debug statements in production code (console.log, print, debugger, etc.)
• License compatibility for new dependencies

Domain contract checks (if configured in .spec-verify/config.yaml):

• Custom rules the team has defined

To detect the project environment, run scripts/detect_project.sh from this skill's directory.

Layer 2: AC Test Execution

• Run the tests created in Phase 2
• Also run the full existing test suite to catch regressions
• Collect pass/fail counts for the report

Layer 3: Scope & Escalation Check

This layer ensures the implementation didn't exceed its mandate.

Run scripts/scope_check.py which:

1. Lists all files modified in this task (via git diff --name-only)
2. Compares against the spec's stated scope
3. Checks each modified file against escalation triggers from config

Default escalation triggers (active even without config):

• Authentication/authorization code changes
• Database schema or migration files
• New external dependencies added
• CI/CD pipeline modifications
• Environment configuration changes (.env, docker-compose, etc.)

If any trigger fires, surface it clearly to the user with the specific file and reason. Don't block — just inform and ask them to acknowledge.

Layer 4: Independent Test Generation

This is the layer that breaks the "agent writes code and tests" loop.

1. Read only the spec (not the implementation code)
2. Generate additional tests targeting edge cases and boundary conditions
3. Focus on scenarios the implementation might have missed
4. Run these tests against the implementation

If any independent test fails:

• Analyze whether it's a real bug or an overly strict test
• If it's a real bug, fix the implementation and re-run all layers
• If the test expectation was wrong, revisit the spec — maybe an edge case wasn't considered

The key constraint: these tests must be derived from the spec, not reverse-engineered from the code.

Phase 4: Verification Report

After all layers complete, output a summary:

══════════════════════════════════════════
  SPEC-VERIFY REPORT
══════════════════════════════════════════
  Task: [task title]
  Spec approved: ✓
──────────────────────────────────────────
  Layer 1 - Guardrails:     [N/N] passed
  Layer 2 - AC Tests:       [N/N] passed
  Layer 3 - Scope Check:    [CLEAN / ESCALATION(n)]
  Layer 4 - Independent:    [N/N] passed
──────────────────────────────────────────
  VERDICT: [PASS / CONDITIONAL PASS / FAIL]
  [If conditional, state the reason and required action]
══════════════════════════════════════════

Verdict logic:

• PASS: All layers green, no escalations
• CONDITIONAL PASS: All tests pass but escalation triggers fired — user must acknowledge the flagged changes
• FAIL: Any test failure or guardrail violation — list failures and fix before declaring done

Project Adaptation

On first run in a project, auto-detect the environment by running scripts/detect_project.sh. This script checks for:

• Language/framework indicators (package.json, pyproject.toml, Cargo.toml, go.mod, etc.)
• Test frameworks and their run commands
• Linters and formatters
• Existing CLAUDE.md for project conventions

Store detected config in .spec-verify/config.yaml. If detection is ambiguous, ask the user.

See the config schema below for what can be customized: