write-tech-spec

Name: write-tech-spec
Author: warpdotdev

146stars1forks

How to install write-tech-spec?

warpdotdev/common-skills/write-tech-spec

$npx -y skills add warpdotdev/common-skills --skill write-tech-spec

Installs into the current project.

Summary

Write a TECH.md spec for a significant Warp feature after researching the current codebase and implementation constraints. Use when the user asks for a technical spec, implementation plan, or architecture doc tied to a product spec.

Files · 1

View on GitHub

SKILL.md

1	# write-tech-spec
2
3	Write a `TECH.md` spec for a significant feature in Warp.
4
5	## Overview
6
7	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.
8
9	Write specs to `specs/<id>/TECH.md`, where `<id>` is one of:
10
11	- a Linear ticket number (e.g. `specs/APP-1234/TECH.md`)
12	- a GitHub issue id, prefixed with `gh-` (e.g. `specs/gh-4567/TECH.md`)
13	- a short kebab-case feature name (e.g. `specs/vertical-tabs-hover-sidecar/TECH.md`)
14
15	Match the id used by the sibling `PRODUCT.md` when one exists. `specs/` should contain only id-named directories as direct children.
16
17	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).
18
19	## When to use
20
21	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.
22
23	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.
24
25	## Research before writing
26
27	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.
28	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.
29
30	## Structure
31
32	Required sections:
33
34	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:
35	- [`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
36	- [`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
37	Reference `PRODUCT.md` for user-visible behavior rather than restating it.
38	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.
39	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 validation lives — `PRODUCT.md` intentionally does not have a Validation section.
40	4. Parallelization — Actively evaluate whether parallel sub-agents (launched via `run_agents`) would meaningfully reduce wall-clock time or isolate work. Skip this section if `run_agents` is not available. When the spec proposes using sub-agents, include for each proposed agent:
41	- A short name/role and the subtask it owns.
42	- Execution mode (`local` or `remote`) with a one-line rationale.
43	- For local agents: the working directory or git worktree it should use, so parallel agents do not collide on the same checkout or files.
44	- For remote agents: which environment to use or an explicit note that the agent will run in an empty environment.
45	- Branch and PR strategy: which branch each agent works on, the worktree path each agent will use, and how their work lands (one PR per agent, a single combined PR, etc.).
46	- Coordination boundaries: which files/services each agent owns and how it syncs with sib

People who liked this also viewed

6 picks

Type

write-tech-spec

146stars1forks

View on GitHub

How to install write-tech-spec?

warpdotdev/common-skills/write-tech-spec

$npx -y skills add warpdotdev/common-skills --skill write-tech-spec

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# write-tech-spec
2
3	Write a `TECH.md` spec for a significant feature in Warp.
4
5	## Overview
6
7	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.
8
9	Write specs to `specs/<id>/TECH.md`, where `<id>` is one of:
10
11	- a Linear ticket number (e.g. `specs/APP-1234/TECH.md`)
12	- a GitHub issue id, prefixed with `gh-` (e.g. `specs/gh-4567/TECH.md`)
13	- a short kebab-case feature name (e.g. `specs/vertical-tabs-hover-sidecar/TECH.md`)
14
15	Match the id used by the sibling `PRODUCT.md` when one exists. `specs/` should contain only id-named directories as direct children.
16
17	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).
18
19	## When to use
20
21	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.
22
23	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.
24
25	## Research before writing
26
27	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.
28	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.
29
30	## Structure
31
32	Required sections:
33
34	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:
35	- [`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
36	- [`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
37	Reference `PRODUCT.md` for user-visible behavior rather than restating it.
38	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.
39	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 validation lives — `PRODUCT.md` intentionally does not have a Validation section.
40	4. Parallelization — Actively evaluate whether parallel sub-agents (launched via `run_agents`) would meaningfully reduce wall-clock time or isolate work. Skip this section if `run_agents` is not available. When the spec proposes using sub-agents, include for each proposed agent:
41	- A short name/role and the subtask it owns.
42	- Execution mode (`local` or `remote`) with a one-line rationale.
43	- For local agents: the working directory or git worktree it should use, so parallel agents do not collide on the same checkout or files.
44	- For remote agents: which environment to use or an explicit note that the agent will run in an empty environment.
45	- Branch and PR strategy: which branch each agent works on, the worktree path each agent will use, and how their work lands (one PR per agent, a single combined PR, etc.).
46	- Coordination boundaries: which files/services each agent owns and how it syncs with sib

People who liked this also viewed

6 picks

Type