Create Technical Specification

Workflow

Gather Inputs

Ask the user to provide:

• •Product requirements: PRD, product brief, or similar. Accept local files (@path/to/file.md), URLs (fetch via appropriate tools), or pasted content.
• •Project tracking context: A project, epic, or initiative in their task management system (Linear, GitHub, Jira, etc.). Use available MCP tools to fetch details.
• •Output path: Where to write the spec (e.g., tmp/feature-tech-spec.md).

Be flexible about input sources. Don't assume specific tools or formats.

Explore Codebases

Discuss with the user which repositories need exploration:

• •Suggest likely candidates based on the project scope
• •Ask the user to confirm or identify additional repos
• •Dispatch background explore agents for breadth-first discovery while the user is away

Scan for:

• •Relevant existing patterns and conventions
• •Database schemas and models
• •API structure and routing
• •Frontend component architecture
• •Infrastructure and deployment configuration

Planning Interview

Invoke interview:plan to clarify requirements. Guide the interview toward:

• •Requirements clarification
• •Scope boundaries (what's in, what's out)
• •Technical constraints
• •Integration points
• •Rollout strategy

Write Initial Draft

Write incrementally to the output file. Use the template structure from references/template.md.

For architecture diagrams, always use mermaid:diagram to ensure proper syntax and rendering.

Write sections incrementally.

Expert Review

Invoke tech-spec:review on the draft spec.

Iterate

Continue refining until the user is satisfied. Long sessions with incremental changes create drift—validate consistency before concluding:

• •Stale references: Scope changes in one section may leave dangling references elsewhere
• •Contradictions: Later decisions may conflict with earlier sections
• •Orphaned details: Implementation details that no longer match the architecture
• •Milestone alignment: Ensure milestones still reflect the current scope

Also address:

• •Expanding under-specified sections
• •Adding missing edge cases or error handling
• •Refining milestones for incremental delivery

Design Decisions Table

Captures architecture trade-offs:

Populate this table throughout the process as decisions emerge. Focus on:

• •Choices that required deliberation
• •Trade-offs between valid alternatives
• •Decisions that future readers would question

Capture decision highlights, not interview dialogue.

Style

• •Describe structure and approach, not implementation details
• •Use Mermaid for architecture diagrams
• •Reference related code, docs, and issues inline