When Specs Become Alignment Contracts: A Deep Dive into Warp's Three Spec-Driven Development Skills

This post examines the Spec-Driven Development (SDD) skills proposed by the Warp team, introduced in a tweet by Shao Meng. One correction up front: the tweet called the review skill /validate-changes-match-specs, but in the warpdotdev/common-skills repository it is actually named check-impl-against-spec. The repository contains 10 skills in total; this analysis focuses on the three at the core of spec-driven development.

Key points

The three skills at a glance

| Skill | Output | Perspective | Driver | |---|---|---|---| | write-product-spec | PRODUCT.md | User stories, invariants, business rules | Human-led | | write-tech-spec | TECH.md | Architecture, files, risks, validation | Human-led | | check-impl-against-spec | Embedded in review.json | Material mismatch between implementation and spec | Agent self-check |

The SDD five-step loop

1. Write product spec (human / skill) 2. Write tech spec (human / skill) 3. Agent implements to spec (agent) 4. Spec-consistency check (skill + human) 5. End-to-end verification (agent + sandbox)

As Shao Meng observed: "Agent errors are usually *misunderstood requirements*, not weak coding ability." The spec is the alignment contract between humans and agents.

Design philosophy of PRODUCT.md

• Broad definition of "User": not just end users, but also code that reads/writes a data model, callers of APIs/protocols/libraries, and developers invoking CLIs. Specs describe consumer-side contracts, not implementation footnotes.
• Behavior is the spec: Summary, Problem, and Goals are optional framing; Behavior—written as numbered, testable invariants—is the substance. Length scales with complexity (small: ~30–60 lines; medium: ~80–150 lines).
• Separation of concerns: Validation, success criteria, and testing are deliberately *not* in PRODUCT.md—that is TECH.md's job.
• Figma: explicit over implicit: when absent, specs must state Figma: none provided rather than omit it—anything unsaid gets arbitrarily filled in by agents.

TECH.md's agent-era adaptations

• Commit-SHA-pinned code references: e.g. ` app/src/workspace/mod.rs:42 @ <commit-sha> —captured via git rev-parse HEAD. This locks the spec's factual grounding in time; agents can't misread references that drifted on main.
• Mandatory Parallelization section: if run_agents is supported, TECH.md must specify each sub-agent's role, subtask, execution mode (local/remote), working directory/worktree paths, branch/PR strategy, and coordination boundaries.
• Reference numbered invariants rather than restating them: e.g., "Behavior §1.3 'retry within 5 seconds of network recovery must not lose requests' should be covered by test_retry_under_network_blip." This creates a traceability chain from tests up to product behavior and down to code locations.

check-impl-against-spec's restraint

• Flags only material mismatches: missing required behavior, contradictions with spec decisions, large unplanned scope, or omitted validation/migration/compatibility steps. Naming differences and structural choices do *not* count.
• No separate report: findings fold into the regular review.json, making spec alignment a sub-task of normal PR review.
• No speculation: it compares only what is written in spec_context.md`—prefer false negatives to false positives, a direct answer to hallucination risk.

Comparison with related methodologies

| Methodology | Source | Distinction | |---|---|---| | warpdotdev/common-skills | Warp team | Lightest; embeds alignment check into PR review | | GitHub Spec-Kit | GitHub | Constitution → Spec → Plan → Tasks; heavier, for large projects | | Kiro | AWS (2025) | IDE-bound specs → hooks → steering | | BMad-Method | Community | Multi-agent roles (PM/Architect/Dev/QA) | | Tessl | Tessl | Tests as specs; test-driven SDD |

Warp's edge: rather than reinventing process on top of IDE/CLI layers, it makes the spec side of the existing PR workflow real.

Value and limitations

Value: reduces hallucination cost by giving agents a shared source of truth; makes specs live, verifiable artifacts; codifies implicit team engineering habits into portable instructions.

Limitations: garbage in, garbage out (flawed invariants produce faithfully flawed implementations); agents can still dodge key decisions via naming/structure tweaks that escape the material-mismatch filter; specs must be updated on every behavior change.

When to adopt

• Good fit: medium+ features needing code review; complex business rules (finance, permissions, compliance); teams wanting to codify experience; agent collaboration centered on PRs.
• Skip it: trivial changes, exploratory prototypes, one-off scripts, or teams resistant to spec culture.

A three-step starting point

1. Borrow numbered invariants: list acceptance points as checkboxes in PR descriptions. 2. Borrow SHA-pinned references: embed the current commit SHA when linking code in specs—near-zero cost, high value. 3. Borrow the material-only filter: tell the reviewing agent that naming/structural differences don't count, only behavior/scope/validation deviations.

Conclusion

These skills recalibrate spec culture for the agent era: specs are no longer reports written after the fact, but built into the PR; not human-to-human descriptions, but human-to-agent alignment contracts; not disposable documents, but SHA-pinned, verifiable, traceable living artifacts. In one line: *treat the spec as the agent's contract, not a footnote to development.*

References: Shao Meng's original tweet · warpdotdev/common-skills · write-product-spec · write-tech-spec · check-impl-against-spec