draft-spec

name	draft-spec
description	Guide a collaborative discussion that produces a specification document at .turbo/specs/<slug>.md. Use when the user asks to "draft a spec", "create a spec", "write a spec", "discuss a project plan", "spec out a project", "design a system", "let's plan this project", "help me scope this", "architect a solution", or "let's discuss before building".

Draft Spec

Guide a collaborative discussion to explore a project idea, then synthesize the conversation into a comprehensive specification at .turbo/specs/<slug>.md.

Task Tracking

At the start, use update_plan to track each step, restating any remaining steps of a parent workflow alongside them:

1. Capture the vision and pick a slug
2. Consult task-specific skills and docs
3. Deep-dive discussion
4. Draft the spec
5. Resolve open questions
6. Present and finalize

Step 1: Capture the Vision and Pick a Slug

Absorb whatever the user has provided — a sentence, a paragraph, a brain dump. Do not interrupt or ask questions yet. Restate the vision back in two or three sentences to confirm understanding.

Pick a slug for the spec file derived from the project or feature name:

• Lowercase
• Replace non-alphanumeric characters with hyphens
• Collapse consecutive hyphens
• Trim leading and trailing hyphens
• Truncate to 40 characters at a word boundary

Example: "Photo Sorter v2" → photo-sorter-v2. The user may pass an explicit slug; if so, honor it.

If .turbo/specs/<slug>.md already exists, use request_user_input to ask whether to overwrite, append a numeric suffix (-2, -3, ...), or pick a different slug.

State the chosen slug and the resulting spec path before continuing.

Then use request_user_input to ask 1-3 focused opening questions targeting the biggest unknowns. Skip anything the user already answered. Prioritize from:

• What problem does this solve, and for whom?
• Is this greenfield or does existing code/infrastructure exist?
• Are there strong technology preferences or constraints?
• What does the MVP look like versus the full vision?
• Are there hard deadlines, budget limits, or team size constraints?

Step 2: Consult Task-Specific Skills and Docs

Ground architecture and tech-stack choices in current reality before the deep-dive discussion.

1. Scan for matching skills. Compare the vision and opening-question answers against available skill trigger descriptions. For each unambiguous match, run the skill by reading and following the installed skill instructions. This loads decision-level guidance (idiomatic patterns, known pitfalls, version constraints) before architectural choices are made. If unsure, do not load.
2. Look up library or framework docs. For any library, framework, or platform the user mentioned or the project clearly needs, query documentation MCP tools (or web search as a fallback) when the decision hinges on current capabilities, supported versions, or known constraints.

Keep findings at the decision level: what tools can do, which approaches are idiomatic, which versions to target. Do not embed specific API signatures or code snippets into the spec. Those belong in implementation-time skill loads.

Step 3: Deep-Dive Discussion

Interview the user relentlessly until you reach shared understanding of the project. Gather behavioral requirements (the "what") before architectural design (the "how"), so design decisions land against a concrete set of requirements instead of being taken in the abstract. Track coverage internally but do not present the list as a rigid checklist. When the user jumps to architecture early, engage briefly then circle back to confirm the behavioral picture is complete.

Requirements (gather first)

Category	What to explore
Users and personas	Who uses this? Goals, pain points, technical sophistication
Core behaviors	Primary capabilities and user-facing workflows — the behaviors the system must exhibit
Non-functional requirements	Performance, security, accessibility, i18n, compliance — which of these do this project's users and deployment require?
Scale and operational rigor	How many users and operators, now and realistically? Concurrent writers? Which rigor tier is proportionate — personal tool, small team, or business-critical — and what failure tolerance does that imply?

Design (gather after requirements are clear)

Category	What to explore
Architecture	Client/server split, monolith vs services, real-time needs, offline support
Tech stack	Languages, frameworks, databases, hosting — preferences and constraints
Data model	Key entities, relationships, storage strategy
Integrations	Third-party APIs, auth providers, external data sources

Cross-cutting

Category	What to explore
MVP scope	What ships first? What is explicitly deferred?
Open questions	Unknowns needing research, prototyping, or external input

Discussion Guidelines

• If a question can be answered by exploring the codebase, explore the codebase instead
• When a question defines a boundary, contract, or data shape, add a Get a second opinion option and hold the concrete options to two so the question stays within the three-option limit. It runs the $consult-claude skill for the soundest answer on technical merit alone, independent of the task's original scope; on a question of product intent, run it for what each answer commits to and what reversing it costs. Then resolve the question with that answer in hand, re-asking when the choice stays the user's.
• Use request_user_input to ask one question at a time. Use options with descriptions to frame trade-offs and offer concrete suggestions. When choices are not mutually exclusive, ask the user free-form which combination applies.
• When the user gives a short answer, probe deeper before moving on
• For each question, recommend an answer with reasoning
• Walk down each branch of the design tree, resolving dependencies between decisions one-by-one
• When all categories have sufficient depth or the user signals readiness, confirm before moving to drafting

Step 4: Draft the Spec

Synthesize the consulted skill and doc context plus the entire discussion into .turbo/specs/<slug>.md using the slug picked in Step 1. Use the fixed skeleton below.

# <Project or Feature Name>

## Overview

<One or two paragraphs stating the problem being solved and the vision for the solution.>

## Users

<Personas and their goals. Omit this section if the project has no meaningful user role distinction (e.g., a single-integrator internal library).>

## Requirements

Enumerated behavioral requirements with stable IDs. Number requirements `R1`, `R2`, `R3`, ... IDs must stay stable once drafted so downstream artifacts can reference them reliably.

Pick either format per requirement; both can appear in the same spec.

**EARS format** — for unambiguous, testable behaviors:

- **R1.** When , the system shall .

Adapt the slot to the EARS pattern that fits:  (event-driven),  (state-driven),  (optional feature),  (unwanted behavior), or a bare  (ubiquitous).

 — for user-facing capabilities with acceptance criteria:

  As a , I want  so that .
 Acceptance: 
 Acceptance: 

Group related requirements under  when the list grows past ~8 items. IDs stay contiguous across subheadings.



Technical approach that satisfies the requirements above. Cover the elements that apply:

  — component split, deployment shape, communication patterns
  — languages, frameworks, libraries, hosting
  — key entities, relationships, storage strategy
  — third-party APIs, auth providers, external data sources
  — sequence or data flow for any non-trivial interaction

State decisions, not options. Where a decision was deferred, move it to Open Questions.

Drafting Rules

• ## Overview, ## Requirements, and ## Design are mandatory. ## Users, ## MVP Scope, and ## Open Questions are omitted when they would be empty.
• Use concrete details from the discussion, not vague generalizations.
• Every Design element must trace to at least one requirement. If a design element has no requirement to justify it, either add the requirement or drop the element.
• Every specified component (data model entity, API endpoint, utility, service) must trace to a consumer in the spec. If a component exists only to "support future work," either spec the future work as a requirement or defer the component.
• State the deployment's bounds in the Overview or a requirement: user and operator count, concurrency, and the rigor tier the user chose.
• Consistency and durability machinery (leases, locks, queues, versioning schemes, state machines beyond simple status fields) is a cost decision. Surface it in the discussion with its carrying cost; never add it to the draft unasked.
• Where the user deferred a decision, capture it in Open Questions.
• Where recommendations were accepted, state them in Design with brief rationale.

Create the .turbo/specs/ directory if it does not exist. Accept a different output path if the user provides one.

Step 5: Resolve Open Questions

If the spec's Open Questions section is empty, contains "None," or does not exist, skip this step.

For each open question:

1. Analyze the question against the spec, prior discussion, and consulted-docs context from Step 2. State the trade-offs of the leading options in plain text so the user can see the reasoning.
2. Use request_user_input to offer up to 2 concrete resolution options with short descriptions, plus a Defer to implementation option (leaves the question in Open Questions to be surfaced again when shells are expanded). Mark the strongest option "(Recommended)" and place it first. The auto-appended "Other" lets the user supply a freeform answer. Offer a Get a second opinion option whenever the question is costly to reverse (it establishes a pattern others will follow, defines an interface, commits to a data shape, or imports a pattern the codebase has not used), and whenever no option earns "(Recommended)" with conviction. Keeping the question at three options, present it in place of Defer to implementation when the question is answerable from what already exists, and in place of the weaker resolution option when the answer needs code or survey context that implementation will produce. It runs the $consult-claude skill for the soundest option on technical merit alone, independent of the task's original scope, naming any scope cost with the answer. On a question of product intent, run it for what each option commits to, what reversing it costs, and what the prevailing convention is. Then resolve the question with that answer in hand, re-asking when the choice stays the user's.
3. Fold the chosen answer into the relevant spec section and remove the question from Open Questions.

If the user selects "Other" and provides a freeform answer, accept it and proceed. When that answer defers the question rather than resolving it, leave the question in Open Questions instead of folding it into the spec.

Default to resolving. Defer only when the answer genuinely needs codebase or pattern-survey context that is not yet available. If every question resolves, delete the Open Questions section entirely.

Step 6: Present and Finalize

Present a brief summary of the drafted spec: the problem, the chosen solution, and the shape of the requirements, short enough to read at a glance so the user does not have to read the full spec. Fit the summary to the spec rather than a fixed template.

Then use request_user_input to offer two paths:

• Approve (Recommended) — the spec is final.
• Revise — the user describes what to change, whether specific edits or areas to rethink. Apply the edits, reopening the Step 3 discussion when the change needs exploration, then re-summarize and re-present.

After approval:

The spec is ready at the resolved spec path. To break it into shells, run $draft-shells.

Then call update_plan to mark this step completed and continue with the next step of the active workflow.

Rules

• Never skip Step 3 — even with extensive initial context, confirm understanding and probe gaps
• The spec and workflow-state bookkeeping under .turbo/ are the only outputs — do not create code, scaffolding, or other project files
• If the project is trivially small (single-file script, simple config), say so and suggest skipping the spec process