Key Points
- Three core spec skills in
warpdotdev/common-skillsform the value loop:write-product-spec,write-tech-spec, andcheck-impl-against-spec. The repository actually contains 10 skills in three categories (spec workflow, dev workflow, skill authoring). - Naming correction: the third skill is
check-impl-against-spec, not/validate-changes-match-specs. - Spec as a contract: specifications live in
specs/<issue>/and are committed alongside the PR. They are not documents but alignment contracts between intent and implementation. - Five-step closed loop: 1. Write product spec → PRODUCT.md 2. Write technical spec → TECH.md (referencing PRODUCT.md) 3. Agent or human implements against the spec 4.
- PRODUCT.md design philosophy:
- "User" is broadly defined as any consumer of system output—human, service, or other agent.
- Behaviors are the substance of the spec—observable, testable, falsifiable.
- Avoid vague terms ("fast", "friendly"); use Given-When-Then or numbered invariants (INV-1, INV-2, ...).
- Length scales with complexity: ~30–60 lines for small features, ~80–150 for medium, 150+ for large systems.
- Figma-style explicit artifacts preferred over prose descriptions.
- TECH.md agent-era adaptations:
- Code references pinned to commit SHAs and file:line (e.g.,
src/api/auth.ts:42-58) rather than module names. - Mandatory Parallelization section forces authors to declare which subtasks are agent-parallelizable.
- Testing sections must back-reference PRODUCT.md invariant numbers (INV-1, INV-2) without restating them—creating a traceable chain.
- Restrained verification philosophy in
check-impl-against-spec: - Flags only three classes of material mismatch: missing behaviors, scope creep, and missing tests.
- Naming and structural differences are not flagged as drift.
- Outputs are merged into PR
review.json, not a standalone report. - Does not speculate beyond what is written—avoiding subjective bias common in AI review tools.
- Lowers context-rebuilding cost in PR review.
- Forces clarification before coding.
- Tool-agnostic and portable.
- Auditable spec/code co-evolution timeline.
- Garbage In, Garbage Out: bad specs pass meaningless checks.
- Maintenance burden—specs decay without upkeep.
- Agents may exhibit "formal compliance, substantive drift."
- Does not solve the upstream problem of clarifying requirements; only externalizes them.
- Poor fit for rapid iteration, prototypes, POCs.
- Depends on agent discipline—skipping the spec is still possible.
- Multi-person medium/long-term projects
- Codebases with high agent participation
- Regulated industries (finance, healthcare, government)
- Cross-team or cross-organization collaboration
- Solo projects or POCs
- Exploratory research code
- Time-pressured hackathons
- Highly experimental creative code
- Original post: https://x.com/shao__meng/status/2065234132431675439
- Repository: https://github.com/warpdotdev/common-skills
- write-product-spec SKILL.md: https://github.com/warpdotdev/common-skills/tree/main/.agents/skills/write-product-spec
- write-tech-spec SKILL.md: https://github.com/warpdotdev/common-skills/tree/main/.agents/skills/write-tech-spec
- check-impl-against-spec SKILL.md: https://github.com/warpdotdev/common-skills/tree/main/.agents/skills/check-impl-against-spec
check-impl-against-spec validates consistency
5. computer-use skill runs end-to-end verification
Comparison With Other SDD Approaches
| Dimension | Warp SDD | GitHub Spec-Kit | AWS Kiro | BMad Method |
|---|---|---|---|---|
| Spec carrier | specs/ in PR | separate .specify/ | IDE-side spec files | stories + tasks |
| AI role | skill orchestration | template generation | tool invocation | multi-agent collaboration |
| Workflow intrusiveness | low (overlays PR) | medium (separate stage) | high (IDE-centric) | high (full-process takeover) |
| Learning curve | medium | high | high | very high |
| Portability | cross-IDE | cross-IDE | AWS-locked | cross-tool |
| Core idea | spec as alignment contract | spec as single source of truth | spec as dev artifact | spec as collaboration script |
Warp's distinguishing value is minimal workflow disruption—it strengthens the spec side of the existing PR flow rather than inventing a new process.
Strengths and Limitations
Strengths
Limitations
When To Adopt
Good fit
Poor fit
Three Low-Cost Steps To Start
1. Number every acceptance criterion in the PR description (INV-1, INV-2, INV-3, ...).
2. Pin all code links to the current commit SHA (blob/<sha>/...) to prevent rot.
3. Tell agents to flag only material mismatches; ignore naming and structural differences.
These require no tools—just a PR template change. Pilot on five PRs before adopting the full Skills suite.
Bottom Line
Specs constrain current decisions rather than describe the future in detail. write-product-spec constrains "what the user wants" into testable invariants; write-tech-spec constrains "how to build" into traceable sections; check-impl-against-spec constrains "is the implementation correct" into material mismatches. The loop externalizes decisions as auditable dialogue without replacing them. In the agent era, the human skill of writing specs becomes more valuable: agents execute, and specs ensure they execute what was intended.