---
name: create-spec
description: Create an actionable product and engineering spec from an idea, planning document, or GitHub or Linear issue. Use when the user asks for a spec or PRD.
---

# Create Spec

Produce a working spec grounded in the user's goal and what already exists in the repository. A **project spec** covers a new product or large initiative; a **feature spec** covers a change to something that exists. Pick by the size of the work, not by whether the input was a file or an issue.

## Gather context

- Input is the current request plus any invocation text: an inline idea, a local file to read, or an issue. Fetch issues through an available GitHub or Linear connector, or `gh issue view <number> --repo <owner/repo>`. If you can't reach the issue, ask for its content rather than guessing.
- Look at the relevant code, manifests, docs, schema, and deployment config before asking anything those can answer. Read `.env.example` and variable names, never secret values.
- For a new project with no stack preference, [references/recommended_stacks.md](references/recommended_stacks.md) is an opinionated starting point; verify time-sensitive choices before recommending them.

## Ask only what matters

Ask about decisions that materially change scope or implementation and that the input and codebase don't settle: who it's for and the problem, what v1 must do and must not, how success is observed, acceptance criteria and edge cases, stack or deployment constraints, and which technical choices need research. Recommend an answer for each question when the evidence supports one, and label assumptions as assumptions. A well-specified issue may need no interview at all. Use a structured question tool if the host has one; plain conversation is fine.

## Write the spec

Use [project_spec_template.md](references/project_spec_template.md) or [feature_spec_template.md](references/feature_spec_template.md). Drop sections that don't apply, mark real unknowns explicitly, and don't invent milestones to fill the template. Distinguish observed repository facts from inferred affected files or proposed architecture.

Both spec types must define **Success and Verification**: the observable successful outcome, criteria paired with suitable verification methods and explicit passing results, and end-to-end proof of the main user journey. Include important failure cases, checks for existing behavior that must not break, and any verification constraints when relevant. Keep checks proportional to the work. Distinguish planned verification from actual results; writing the spec does not establish that any check has passed. Identify criteria that would remain unverified when access, credentials, user review, or observation time is unavailable.

Project specs need two extra pieces:

- **Architecture Map** — the building blocks, a simple text diagram of how they connect, and choices marked **(research needed)**. About a page, plain English.
- **Agent Decision Boundaries** — which decisions a future coding agent may make on its own, subject to repository instructions.

Keep it concise: this is a working document, not a formal PRD.

Save to the user's path, otherwise to the existing `specs/` or `docs/` directory with a descriptive filename. Don't overwrite an existing spec unless asked to revise it.

## Finish

Link the saved spec, summarize its scope, key assumptions, and open decisions, and apply any revisions the user asks for. Suggest the `research` skill (if available) for **(research needed)** items. Writing the spec does not mean implementing it; only continue into implementation if the user asked for both.