Write Tech Spec
Turn an approved product idea into a codebase-aware TECH.md implementation plan before agents or you start multi-module work.
Overview
write-tech-spec is an agent skill most often used in Validate (also Build PM, Build docs) that researches the Warp codebase and writes a TECH.md implementation plan tied to a product spec.
Install
npx skills add https://github.com/warpdotdev/common-skills --skill write-tech-specWhat is this skill?
- Researches the current Warp codebase and implementation constraints before writing
- Writes specs to specs/<id>/TECH.md with ids matched to Linear, gh-issues, or kebab feature names
- Aligns TECH.md with sibling PRODUCT.md when present and keeps specs/ as id-named directories only
- Documents architectural choices and tradeoffs so agents can execute and reviewers can evaluate
- Optional Linear MCP or gh CLI ticket creation only when the user explicitly asks
- Outputs to specs/<id>/TECH.md with Linear, gh-, or kebab-case id conventions
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 have product intent but no implementation plan that respects how this repo is actually structured and reviewed.
Who is it for?
Significant Warp features with multi-module impact, architectural choices, or agent-driven implementation after a product spec exists.
Skip if: One-line tweaks, hotfixes with no tradeoffs, or cases where an approved TECH.md and PRODUCT.md pair already exist and only code edits are needed.
When should I use this skill?
User asks for a technical spec, implementation plan, or architecture doc tied to a product spec for a significant Warp feature.
What do I get? / Deliverables
You get a specs/<id>/TECH.md document agents and humans can execute against, with optional ticket/issue ids aligned to PRODUCT.md when present.
- specs/<id>/TECH.md
- Documented architectural choices and implementation constraints
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Technical specs sit after product intent and before heavy implementation—they lock scope, architecture, and tradeoffs, which is the validate phase’s job even when execution happens in build. Scope is where solo builders define what will be built and how it fits the repo; TECH.md is the canonical artifact for that decision.
Where it fits
Draft TECH.md after PRODUCT.md so module boundaries and tradeoffs are fixed before coding.
Break a large Warp initiative into an agent-readable execution plan linked to APP-1234.
Capture architecture decisions in specs/gh-4567/TECH.md for future maintainers.
Give reviewers a TECH.md checklist before approving a wide refactor PR.
How it compares
Structured repo-local TECH.md planning—not a generic chat brainstorm or an MCP-only ticket fetch.
Common Questions / FAQ
Who is write-tech-spec for?
Solo and indie builders shipping Warp features who want agents and reviewers to follow a single, codebase-informed technical spec instead of improvised implementation notes.
When should I use write-tech-spec?
Use it in Validate when scoping a feature, in Build when preparing PM/docs for a large change, or before Ship when architecture must be agreed—especially when the user asks for a technical spec, implementation plan, or architecture doc tied to a product spec.
Is write-tech-spec safe to install?
Review the Security Audits panel on this Prism page before installing; the skill may use git, filesystem writes under specs/, and optionally network-backed Linear or GitHub CLI when you request tickets.
SKILL.md
READMESKILL.md - Write Tech Spec
# write-tech-spec Write a `TECH.md` spec for a significant feature in Warp. ## Overview The tech spec should translate product intent into an implementation plan that fits the existing codebase, documents architectural choices, and makes the work easier for agents to execute and reviewers to evaluate. Write specs to `specs/<id>/TECH.md`, where `<id>` is one of: - a Linear ticket number (e.g. `specs/APP-1234/TECH.md`) - a GitHub issue id, prefixed with `gh-` (e.g. `specs/gh-4567/TECH.md`) - a short kebab-case feature name (e.g. `specs/vertical-tabs-hover-sidecar/TECH.md`) Match the id used by the sibling `PRODUCT.md` when one exists. `specs/` should contain only id-named directories as direct children. Ticket / issue references are optional. If the user has a Linear ticket or GitHub issue, use its id. If they don't, ask them for a feature name to use as the directory. Only create a new Linear ticket or GitHub issue when the user explicitly asks for one; in that case use the Linear MCP tools or `gh` CLI respectively (and `ask_user_question` if team, labels, or repo are unclear). ## When to use Use this skill when the implementation spans multiple modules, has meaningful architectural tradeoffs, or when reviewers will benefit from seeing the plan before or alongside the code. For pure UI changes or straightforward fixes, a tech spec is often unnecessary. Prefer to have a `PRODUCT.md` first so the technical plan is anchored to agreed behavior. If the implementation is still too uncertain, build an e2e prototype first and then write the tech spec from what was learned. ## Research before writing Before drafting, read the product spec (if any), inspect the relevant code, and identify the main files, types, data flow, and ownership boundaries. Do not guess about current architecture when the code can be inspected directly. When referencing relevant code chunks in the spec, prefer commit-pinned references so future readers can inspect the exact code you researched. Capture the current commit SHA for each repository you inspected (for example, `git rev-parse HEAD`) and, when possible, make file references Markdown links to the corresponding GitHub `blob/<sha>/...#Lx-Ly` URL. Use the linked text to keep the path readable in the spec. ## Structure Required sections: 1. **Context** — What's being built, how the current system works in the area being changed, and the most relevant files with line references. Combine the "problem," "current state," and "relevant code" into one grounded section. Example references: - [`app/src/workspace/mod.rs:42 @ <commit-sha>`](https://github.com/warpdotdev/warp/blob/<commit-sha>/app/src/workspace/mod.rs#L42) — entry point for the user flow - [`app/src/workspace/workspace.rs (120-220) @ <commit-sha>`](https://github.com/warpdotdev/warp/blob/<commit-sha>/app/src/workspace/workspace.rs#L120-L220) — state and event handling that will likely change Reference `PRODUCT.md` for user-visible behavior rather than restating it. 2. **Proposed changes** — The implementation plan: which modules change, new types/APIs/state being introduced, data flow, ownership boundaries, and how the design follows existing patterns. Call out tradeoffs when there is more than one reasonable path. 3. **Testing and validation** — How the implementation will be verified against the product behavior. Owns everything about proving the feature works: unit tests, integration tests, manual steps, screenshots, videos, and any other verification. Reference the numbered Behavior invariants from `PRODUCT.md` directly rather than restating them; each important invariant should map to a concrete test or verification step. This section is where validatio