Spec Driven Implementation
Run a spec-first implementation loop with ticket-scoped PRODUCT.md and TECH.md in `specs/`, synced to Linear issues, for substantial agent-driven features.
Overview
spec-driven-implementation is an agent skill most often used in Build (also Validate, Ship) that drives PRODUCT.md and TECH.md specs in `specs/<ticket>/` before and during substantial feature work.
Install
npx skills add https://github.com/warpdotdev/common-skills --skill spec-driven-implementationWhat is this skill?
- PRODUCT.md before implementation; TECH.md when technical ambiguity warrants it
- Specs live under `specs/<linear-ticket-number>/` with ticket-only top-level folders
- Linear MCP flow: list_teams, list_issue_labels, save_issue—create issues before writing specs
- Pragmatic scope: substantial features only, not every small change
- Ask-user guardrail when team or labels are unclear instead of guessing
- 2 spec file types: PRODUCT.md and TECH.md
- Specs path pattern: specs/<linear-ticket-number>/
Adoption & trust: 3.5k installs on skills.sh; 18 GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
You are about to let an agent implement a large feature without a durable product or tech spec checked into the repo.
Who is it for?
Solo or small-team builders using Warp, Cursor, or Claude Code on non-trivial features where ambiguity would waste agent tokens and review time.
Skip if: One-line bugfixes, typo edits, or tasks where specs already exist and are approved—skip the full spec loop there.
When should I use this skill?
Starting a significant feature, planning agent-driven implementation, or when the user wants product and tech specs checked into source control.
What do I get? / Deliverables
You have ticket-scoped PRODUCT.md and optional TECH.md under `specs/`, linked to a Linear issue, that stay updated as implementation lands—ready for review and follow-on coding passes.
- specs/<ticket>/PRODUCT.md
- specs/<ticket>/TECH.md when warranted
- Linked Linear issue for the feature
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Build is the canonical shelf because written specs directly precede and guide implementation and review in source control. PM subphase fits product/tech spec authoring, ticket naming discipline, and keeping docs current as code evolves.
Where it fits
Create the Linear issue and empty `specs/APP-1234/` before committing to a multi-week agent build.
Draft PRODUCT.md outcomes and TECH.md constraints, then point the agent at both files for implementation.
Reconcile TECH.md with the merged PR so reviewers see intent and final design in one place.
How it compares
Repo-checked PRODUCT/TECH specs tied to Linear tickets—not ad-hoc chat planning or unstructured TODO comments.
Common Questions / FAQ
Who is spec-driven-implementation for?
Builders shipping substantial features with coding agents who want product and technical intent versioned beside the code.
When should I use spec-driven-implementation?
At Validate when scoping a major feature into a Linear ticket; at Build pm when authoring specs before coding; at Ship review when updating docs to match what shipped.
Is spec-driven-implementation safe to install?
Review the Security Audits panel on this Prism page; the workflow may invoke Linear MCP and filesystem writes under `specs/`—confirm MCP permissions in your environment.
SKILL.md
READMESKILL.md - Spec Driven Implementation
# spec-driven-implementation Drive a spec-first workflow for substantial features in Warp. ## Overview Use this skill for significant features where a written spec will improve implementation quality, reduce ambiguity, or make review easier. Be pragmatic: not every change needs specs. Specs should usually live in: - `specs/<linear-ticket-number>/PRODUCT.md` - `specs/<linear-ticket-number>/TECH.md` For example: - `specs/APP-1234/PRODUCT.md` - `specs/APP-1234/TECH.md` `specs/` should contain only ticket-named directories as direct children. Do not create engineer-named subdirectories or feature-slug directories there. If a relevant Linear issue does not already exist, create one before writing specs. Use the Linear MCP tools directly: - `list_teams` to find the appropriate team - `list_issue_labels` to inspect the expected labels/tags - `save_issue` to create the issue with the appropriate team and labels If the correct team or labels are not obvious from the request and surrounding context, use `ask_user_question` to clarify rather than guessing. These specs should largely be written by agents, not by hand, and should be checked into source control so they can be reviewed and kept current with the code. ## When specs are required Strongly prefer specs when the change is substantial, such as: - product or architectural ambiguity - expected implementation size around 1k+ LOC - deep or cross-cutting stack changes - risky behavior changes where regressions would be expensive - work where agent quality will improve materially from clearer inputs Specs are often unnecessary for: - small, local bug fixes - straightforward refactors - narrow UI tweaks with little ambiguity For pure UI changes, the product spec is often useful while the tech spec may be unnecessary. ## Workflow ### 1. Decide whether the feature needs specs Evaluate the size, ambiguity, and risk of the feature. If specs will not meaningfully improve execution or review, skip them and focus on verification instead. ### 2. Write the product spec first Before implementation, create `PRODUCT.md` describing the desired user-facing behavior. Use the `write-product-spec` skill to produce it. The product spec should define: - what problem is being solved - the desired user experience - invariants and edge cases - success criteria - how the behavior will be validated If the feature has UI or interaction design, ask for a Figma mock if one exists. If there is no mock, continue but call that out explicitly in the product spec. Reference the Linear issue in the spec when one exists. Because specs live under `specs/<linear-ticket-number>/...`, this should usually be straightforward. ### 3. Write the tech spec when warranted Use the `write-tech-spec` skill for substantial or ambiguous implementation work. Prefer a tech spec when: - the implementation spans multiple subsystems - architecture or extensibility matters - there are meaningful tradeoffs to document - reviewers will benefit more from reviewing the plan than the raw code It is acceptable to write the tech spec after an e2e prototype if that leads to a more accurate implementation plan. Do not force a premature tech spec when the implementation details are still too uncertain. ### 4. Implement approved specs After the specs are approved, use the `implement-specs` skill to build from the approved `PRODUCT.md` and `TECH.md`. The implementation can often be pushed in the same PR as the product and tech specs. As the engineer iterates, keep `PRODUCT.md`, `TECH.md`, code changes, and tests in that same PR so