spec-driven-implementation

Spec-first planning creates a PRODUCT.md file before coding to define the problem, user outcomes, success criteria, and acceptance criteria. This approach aligns team and code effort with documented product specifications to reduce ambiguity and rework.

Create specifications by adding a PRODUCT.md file under the specs/<ticket-number>/ directory before implementation. When warranted, add a TECH.md file in the same location to outline architecture, constraints, risks, and implementation notes.

You need a TECH.md file when technical alignment is required for complex feature work. It outlines architecture, constraints, risks, and implementation notes, complementing the PRODUCT.md to support spec maintenance throughout the development lifecycle.

Maintain spec traceability by keeping PRODUCT.md and TECH.md updated as implementation evolves and linking to Linear issues via MCP tooling. This ensures specifications remain accurate and connected to active development tickets throughout the lifecycle.

Spec-first implementation planning applies to planning, scoping, and reviewing complex feature work. It establishes clear product and technical specifications beforehand, ensuring substantial features are properly scoped with documented success and acceptance criteria.

Store specs under specs/<ticket-number>/ directories to maintain a scalable, reviewable repository structure. This governance approach keeps PRODUCT.md and TECH.md files organized by their corresponding ticket numbers for easy retrieval and review.