> For the complete documentation index, see [llms.txt](/llms.txt).
> Markdown versions of each page are available by appending .md to any URL.

# Write product and tech specs with agents

Use agents to turn a ready-to-implement issue into a product spec and a tech spec — the blueprints that guide implementation and anchor code review.

Once your [triage agent](/guides/agent-workflows/build-a-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](https://www.warp.dev))
    
-   A triaged issue labeled `ready-to-spec` or equivalent ([set up triaging](/guides/agent-workflows/build-a-triage-agent))
    
-   `common-skills` installed globally from [`warpdotdev/common-skills`](https://github.com/warpdotdev/common-skills):
    
    ```
    npx skills@latest add warpdotdev/common-skills --skill write-product-spec --agent warp --globalnpx 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`](https://github.com/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](/agent-platform/capabilities/planning). Plans can be saved, versioned, and attached to PRs without a full spec workflow.

## Next steps

-   [What is a software factory?](/agent-platform/cloud-agents/software-factory) — How specs fit into the full development loop.
-   [Set up your software factory: from triage to PR](/guides/agent-workflows/set-up-a-software-factory) — Connect the spec role to implementation and review.
-   [`warpdotdev/common-skills`](https://github.com/warpdotdev/common-skills) — The full set of shared skills including `write-product-spec`, `write-tech-spec`, and `validate-changes-match-specs`.
-   [Planning](/agent-platform/capabilities/planning) — Warp’s built-in planning feature for smaller tasks.
-   [Skills](/agent-platform/capabilities/skills) — How skill files work in Warp and Oz.