Write product and tech specs with agents

Once your triage agent is labeling issues as ready-to-spec, use agents to turn those issues into two spec files: a product spec that describes what the feature should do from the user’s perspective, and a tech spec that describes how to implement it. Implementation agents use these specs as blueprints; reviewers use them as acceptance criteria. The agent does the drafting — you do the reviewing.

Specs serve two purposes: they give implementation agents the context they need to make good decisions, and they give human reviewers a benchmark to judge the result against. Without a spec, an agent implements what it infers from the issue — which may not be what you intended. With one, it implements against an explicit contract you’ve approved.

Note

Writing a good spec requires understanding the problem. The agent drafts the structure, but you need to read and approve it before implementation begins. A wrong spec produces a correct implementation of the wrong thing — catching that after the code is written is more expensive than catching it in the spec.

Prerequisites

• A Warp account (sign up at warp.dev)

• A triaged issue labeled ready-to-spec or equivalent (set up triaging)

• common-skills installed globally from warpdotdev/common-skills:

  npx skills@latest add warpdotdev/common-skills --skill write-product-spec --agent warp --global
  npx skills@latest add warpdotdev/common-skills --skill write-tech-spec --agent warp --global

1. Write the product spec

A product spec defines what the feature should do from the user’s perspective: user stories, acceptance criteria, and edge cases. It is the “what,” not the “how.”

1. Open the issue you want to spec in Warp and run:

   /write-product-spec

2. Review the generated PRODUCT.md in specs/[issue-number]/. The file includes:

   • A summary of the feature
   • User stories in the format “As a [user], I want [behavior] so that [outcome]”
   • Acceptance criteria the implementation agent and reviewers can verify
   • Edge cases and constraints

   Correct any misunderstandings before moving to the tech spec. A wrong product spec leads to a correct implementation of the wrong thing.

2. Write the tech spec

A tech spec defines how the feature will be implemented: architecture decisions, relevant code locations, API shapes, and implementation notes. It is the “how.”

1. After reviewing the product spec, run:

   /write-tech-spec

2. Review the generated TECH.md in the same specs/[issue-number]/ directory. The file includes:

   • An overview of the implementation approach
   • The specific files and functions that need to change
   • Any new data structures, API endpoints, or interfaces
   • Testing strategy
   • Known risks or tradeoffs

   An accurate TECH.md reduces the number of implementation iterations and gives reviewers context for why the code looks the way it does.

3. Validate that the implementation matches the specs

When an implementation agent opens a PR for this issue, run the validation skill to check the diff against both spec files:

/validate-changes-match-specs

The agent checks the PR diff against PRODUCT.md and TECH.md and returns a list of any inconsistencies for you to review before submitting the PR for human review. This skill is also available from warpdotdev/common-skills.

4. Include specs in the implementation PR

The specs/[issue-number]/ directory should be committed alongside the code changes in the implementation PR. This gives reviewers the full picture: what was intended (PRODUCT.md), how it was planned (TECH.md), and what was built (the code diff). There is no need to cross-reference separately.

Productivity tips

• Spec before you code, not after — The biggest value from specs is catching misaligned assumptions before any code is written. Running /write-product-spec first forces that alignment to happen early, when fixing it is cheap.
• Attach Figma mocks — If your feature has a UI component, attach a Figma screenshot or mockup to your prompt when running /write-product-spec. The agent incorporates visual context into the acceptance criteria.
• Use /plan for smaller tasks — For changes that don’t warrant a full PRODUCT.md and TECH.md, use Warp’s built-in planning feature. Plans can be saved, versioned, and attached to PRs without a full spec workflow.

Next steps

• What is a software factory? — How specs fit into the full development loop.
• Set up your software factory: from triage to PR — Connect the spec role to implementation and review.
• warpdotdev/common-skills — The full set of shared skills including write-product-spec, write-tech-spec, and validate-changes-match-specs.
• Planning — Warp’s built-in planning feature for smaller tasks.
• Skills — How skill files work in Warp and Oz.