Plan Requirements

This is the first step in the specification pipeline. Creates a requirements document based on the task context and project. The user provides a spec name and task description, and this command gathers context, asks targeted clarifying questions, and generates a structured requirements document.

When to use

Use this skill when the user needs to:

• Create a new feature specification

• Document requirements for a task

• Generate a structured requirements document for planning

Instructions

Step 1: Gather Information

Project context (optional): Before gathering information, check if .projects/ exists. If it does, scan for a specs.md that references the current spec name. If found:

• Read the project's vision.md for shared architectural decisions, technical constraints, and system goals

• Read the relevant spec entry from specs.md for pre-defined purpose, boundary, and dependencies

• Present this context to the user as a starting point — "This spec is part of project X. Here's the pre-defined context: [purpose, boundary, dependencies, shared decisions]. I'll use this as a starting point."

This is optional — if no project exists, proceed normally.

If the user hasn't provided sufficient context, use the AskUserQuestion tool to ask them interactively:

• What is the name for this specification? (used for folder name, e.g., "user-authentication", "payment-integration")

• What is the main goal or purpose of this feature/task?

• What are the key user stories or use cases?

• Are there any specific technical constraints or requirements?

After gathering initial context, use the AskUserQuestion tool to ask targeted clarifying questions about:

• Ambiguities — anything unclear or open to interpretation in the description

• Edge cases — boundary conditions, error scenarios, empty states

• Priorities — which aspects are most important, what can be deferred

• Scope boundaries — what is explicitly out of scope

Always use the AskUserQuestion tool for these questions — never output them as plain text. Provide meaningful options where possible to reduce user typing.

Do not proceed to codebase analysis until these questions are answered.

Step 2: Analyze the Codebase

Before writing requirements:

• Explore the relevant parts of the codebase to understand existing patterns

• Identify related services, components, or modules

• Note any dependencies or integrations that will be affected

Step 3: Create the Requirements Document

Create the document at .specs/<spec-name>/requirements.md with this structure:

Requirements Document

Introduction

[Brief description of what this feature/task aims to achieve and why it's needed]

Glossary

[Define key terms used throughout the document, formatted as:]

• Term: Definition

Requirements

Requirement 1: [Requirement Name]

User Story: As a [role], I want [feature] so that [benefit].

Acceptance Criteria

1. THE [Component] SHALL [action/behavior]
2. WHEN [condition] THEN [Component] SHALL [action/behavior]
3. THE [Component] SHALL NOT [prohibited action]

[Continue with additional requirements following the same pattern]

Superseded Behaviors

[If this feature modifies or removes existing functionality, list each change explicitly. If the feature is entirely new, omit this section.]

• [Old behavior] → REMOVED / REPLACED BY Requirement X.X

Writing Guidelines

• Use SHALL for mandatory requirements - "THE system SHALL..."

• Use WHEN-THEN for conditional behavior - "WHEN user clicks submit THEN system SHALL..."

• Use SHALL NOT for prohibitions - "THE system SHALL NOT expose..."

• Be specific and testable - Each criterion should be verifiable

• Reference existing code patterns - Align with project conventions

• Keep requirements atomic - One requirement per item

• Prioritize user experience - Every user flow must feel natural. When related entities exist (e.g., category and subcategory), requirements MUST include inline/contextual creation — the user should never be forced to navigate away from the current page to create a dependent entity and then return. For example, if a form needs a parent entity that doesn't exist yet, there must be a way to create it on the spot (inline dialog, quick-add in dropdown, etc.).

• Document intentional behavior changes - When the feature modifies or removes existing behavior, add a "Superseded Behaviors" section that explicitly lists what is being replaced or removed. This prevents the implementer from accidentally restoring old behavior (e.g., re-adding removed undo functionality to make old tests pass). Format:

Superseded Behaviors

• [Old behavior description] → REMOVED / REPLACED BY [new behavior or requirement reference]

Step 4: Confirm with User

After creating the document, show the user:

• The location of the created file

• A summary of the requirements

• Use the AskUserQuestion tool to ask if they want to make changes or proceed, with options like "Looks good, proceed to research", "I want to make changes", "Review requirements first"

Arguments

This skill accepts an optional argument:

• <args>

• Can include the spec name and/or description. Parse it to extract:

• Spec name (kebab-case, e.g., "user-auth" or "payment-flow")

• Task description or context

If <args> is provided, use it to determine the spec name and context. If not sufficient, ask the user for clarification.