Create Spec

Create Spec Skill

You are initiating the spec creation workflow. This process gathers requirements through an adaptive, multi-round interview and generates a comprehensive specification document.

Critical Rules

AskUserQuestion is MANDATORY

IMPORTANT: You MUST use the AskUserQuestion tool for ALL questions to the user. Never ask questions through regular text output.

• Every interview round question → AskUserQuestion
• Confirmation questions → AskUserQuestion
• Yes/no consent questions → AskUserQuestion
• Clarifying questions → AskUserQuestion

Text output should only be used for:

• Summarizing what you've learned
• Presenting information
• Explaining context

If you need the user to make a choice or provide input, use AskUserQuestion.

NEVER do this (asking via text output):

What features are most important to you?
1. Performance
2. Usability
3. Security

ALWAYS do this (using AskUserQuestion tool):

AskUserQuestion:
  questions:
    - header: "Priority"
      question: "What features are most important to you?"
      options:
        - label: "Performance"
          description: "Speed and responsiveness"
        - label: "Usability"
          description: "Ease of use"
        - label: "Security"
          description: "Data protection"
      multiSelect: true

Plan Mode Behavior

CRITICAL: This skill generates a spec document, NOT an implementation plan. When invoked during Claude Code's plan mode:

• DO NOT create an implementation plan for how to build the spec's described features
• DO NOT defer spec generation to an "execution phase"
• DO proceed with the full interview and spec generation workflow immediately
• DO write the spec file to the output path as normal

The spec is a planning artifact itself — generating it IS the planning activity.

Load Reference Skills

When codebase exploration is triggered (Phase 2, "new feature" type), load the teams reference for the Parallel Specialists exploration pattern:

Read ${CLAUDE_PLUGIN_ROOT}/../claude-tools/skills/claude-code-teams/SKILL.md

This provides TeamCreate, SendMessage, and team lifecycle conventions used in the codebase exploration procedure.

Workflow Overview

This workflow has six phases:

1. Settings Check — Load user configuration
2. Initial Inputs — Gather spec name, type, depth, and description (includes team-based codebase exploration for "new feature" type)
3. Adaptive Interview — Multi-round depth-aware interview with recommendations and optional research
4. Recommendations Round — Dedicated round for accumulated best-practice suggestions (if applicable)
5. Pre-Compilation Summary — Present gathered requirements for user confirmation
6. Spec Compilation — Generate spec from template and write to file

Phase 1: Settings Check

Check if there is a settings file at .claude/agent-alchemy.local.md to get any custom configuration like output path or author name.

Phase 2: Initial Inputs & Context

Context Loading

If $ARGUMENTS is provided, load user-supplied context before gathering initial inputs:

1. Determine input type:

   • If the argument looks like a file path (ends in .md, .txt, or .markdown; or starts with /, ./, ../, or ~; or contains path separators and the file exists) → read the file using the Read tool
   • Otherwise → treat the entire argument string as inline context text

2. Store internally as "User-Supplied Context" for use throughout the interview

3. CRITICAL: User-supplied context makes the interview smarter, not shorter. Do NOT pre-fill answers or skip questions based on context. Instead:

   • Ask more targeted, specific questions informed by the context
   • Probe areas the context doesn't cover
   • Confirm implicit assumptions the context makes
   • Reference specific details from the context when asking questions

If $ARGUMENTS is empty, skip this subsection entirely — the skill behaves exactly as before.

Complexity Assessment

If user-supplied context was loaded, assess its complexity:

1. Read references/complexity-signals.md for signal definitions and thresholds
2. Scan the user-supplied context for complexity signals
3. If threshold is met (3+ high-weight signals OR 5+ any-weight signals), present a brief notice via AskUserQuestion:

   questions:
     - header: "Complexity"
       question: "This appears to involve significant complexity (e.g., {top 2-3 complexity areas}). The interview will be more thorough to ensure complete coverage. Ready to proceed?"
       options:
         - label: "Yes, let's be thorough"
           description: "Use expanded interview budgets for deeper coverage"
         - label: "Keep it brief"
           description: "Use standard interview budgets"
       multiSelect: false
   

4. If user selects "Yes, let's be thorough" → set internal complexity_detected flag for expanded budgets
5. If user selects "Keep it brief" → proceed with standard budgets
6. If no context was loaded or threshold was not met → proceed with standard budgets (no alert shown)

Gather Initial Inputs

Use AskUserQuestion to gather the essential starting information with these four questions:

Question 1 - Spec Name:

• Header: "Spec Name"
• Question: "What would you like to name this spec?"
• Options: Allow text input for a descriptive name

Question 2 - Type:

• Header: "Type"
• Question: "What type of product/feature is this?"
• Options:
  • "New product" - A completely new product being built from scratch
  • "New feature" - A new feature for an existing product

Question 3 - Depth:

• Header: "Depth"
• Question: "How detailed should the spec be?"
• Options:
  • "High-level overview (Recommended)" - Executive summary with key features and goals
  • "Detailed specifications" - Standard spec with acceptance criteria and phases
  • "Full technical documentation" - Comprehensive specs with API definitions and data models

Question 4 - Description:

• Header: "Description"
• If context was loaded: "I've loaded the context you provided. Is there anything it doesn't cover, or would you like to highlight specific priorities?"
• If no context: "Briefly describe the product/feature and its key requirements"
• Options: Allow text input describing the problem, main features, and constraints

Phase 3: Adaptive Interview

Prepare for Interview

Before starting Round 1, read these reference files to load the full question bank and trigger patterns:

1. references/interview-questions.md — Question bank organized by category and depth level
2. references/recommendation-triggers.md — Trigger patterns for proactive recommendations across all domains

Use these as your primary source for questions and trigger detection throughout the interview.

Interview Strategy

Depth-Aware Questioning

Adapt your interview depth based on the requested level:

High-level overview (2-3 rounds):

• Focus on problem, goals, key features, and success metrics
• Skip deep technical details
• Ask broader, strategic questions
• Total of 6-10 questions across all rounds

Detailed specifications (3-4 rounds):

• Balanced coverage of all categories
• Include acceptance criteria for features
• Cover technical constraints without deep architecture
• Total of 12-18 questions across all rounds

Full technical documentation (4-5 rounds):

• Deep probing on all areas
• Request specific API endpoints, data models
• Detailed performance and security requirements
• Total of 18-25 questions across all rounds

Question Categories

Cover all four categories, but adjust depth based on level:

1. Problem & Goals: Problem statement, success metrics, user personas, business value
2. Functional Requirements: Features, user stories, acceptance criteria, workflows
3. Technical Specs: Architecture, tech stack, data models, APIs, constraints
4. Implementation: Phases, dependencies, risks, out of scope items

Expanded Budgets

When complexity_detected is set (user opted in after complexity assessment), use expanded budgets from references/interview-questions.md (section "Expanded Budgets (Complexity Detected)") instead of the standard budgets above. Soft ceiling of ~8 rounds / ~35 questions applies.

Adaptive Behavior

• Build on previous answers: Reference what the user already told you
• Skip irrelevant questions: If user says "no preference" on tech stack, skip detailed tech questions
• Probe deeper on important areas: If user indicates something is critical, ask follow-up questions
• Explore codebase when helpful: For "new feature" type, offer to explore relevant code (with user approval)
• If something is unclear, ask for clarification rather than assuming

Context-Informed Questioning

When user-supplied context was loaded in Phase 2, apply these strategies throughout the interview:

1. Reference specifics from context when asking questions — e.g., "Your context mentions a notification service — what events should trigger notifications?"
2. Identify gaps in context and probe those first — areas the context doesn't address are the highest-value questions
3. Confirm assumptions the context implies but doesn't state — e.g., "The context describes multiple services. Should these be independently deployable microservices?"
4. Skip surface-level questions and go deeper — don't ask "what are you building?" when the context already describes it; instead ask about edge cases, constraints, and trade-offs
5. Cross-reference with complexity signals — ensure areas that drove the complexity assessment get thorough coverage in the interview

Round Structure

Each round MUST:

1. Summarize what you've learned so far (briefly) — use text output
2. Ask 3-5 focused questions using AskUserQuestion — REQUIRED, never use text for questions
3. Use a mix of multiple choice (for structured data) and open text (for details)
4. Detect triggers: Note any recommendation triggers in user responses
5. Offer inline insights (optional): If triggers detected, offer 1-2 brief recommendations
6. Acknowledge responses before moving to next round

Question Guidelines:

• Keep questions clear and specific
• Provide helpful options for multiple choice where appropriate
• Use "Other" option for flexibility
• Group related questions together
• Don't overwhelm — max 4 questions per AskUserQuestion call

Example Question Patterns:

For structured choices:

header: "Priority"
question: "What priority is this feature?"
options:
  - label: "P0 - Critical"
    description: "Must have for initial release"
  - label: "P1 - High"
    description: "Important but can follow fast"
  - label: "P2 - Medium"
    description: "Nice to have"

For open-ended input:

header: "Problem"
question: "What specific problem are you trying to solve?"
options:
  - label: "Efficiency"
    description: "Users spend too much time on manual tasks"
  - label: "Quality"
    description: "Current solution produces errors or poor results"
  - label: "Access"
    description: "Users can't do something they need to do"

Proactive Recommendations

Throughout the interview, watch for patterns in user responses that indicate opportunities for best-practice recommendations. When detected, offer relevant suggestions based on industry standards.

Trigger Detection: After receiving user responses each round, scan for trigger keywords from the loaded references/recommendation-triggers.md. The file covers domains including: Authentication, Scale & Performance, Security & Compliance, Real-Time Features, File & Media, API Design, Search & Discovery, Testing, and Accessibility.

When to Offer Recommendations:

• Inline insights: Brief suggestions during rounds when triggers detected (max 2 per round)
• Recommendations round: Accumulated recommendations presented in Phase 4
• Always present recommendations for user approval — never assume acceptance

Inline Insight Format:

AskUserQuestion:
  questions:
    - header: "Quick Insight"
      question: "{Brief recommendation}. Would you like to include this in the spec?"
      options:
        - label: "Include this"
          description: "Add to spec requirements"
        - label: "Tell me more"
          description: "Get more details"
        - label: "Skip"
          description: "Continue without this"
      multiSelect: false

For detailed recommendation templates, refer to: references/recommendation-format.md

Tracking Recommendations: Maintain internal tracking of detected triggers and accepted recommendations:

• Detected triggers with source round
• Accepted recommendations with target spec section
• Skipped/modified recommendations

Trigger Detection per Round:

• After receiving user responses, scan for trigger keywords
• Note triggers internally for the recommendations round
• For high-priority triggers (compliance, security), consider inline insight immediately

Codebase Exploration (New Feature Type)

If the product type is "New feature for existing product":

1. Read the exploration procedure: ${CLAUDE_PLUGIN_ROOT}/skills/create-spec/references/codebase-exploration.md
2. Follow all 4 steps (Quick Reconnaissance → Plan Focus Areas → Parallel Exploration → Synthesis)
3. After synthesis, store the merged findings internally as "Codebase Context" for use in subsequent interview rounds and spec compilation
4. Present a brief summary of key findings to the user before starting the interview

Error handling / fallback: If exploration agents fail (Task tool errors, agent timeouts, etc.):

1. If some agents succeeded: continue with partial findings — merge what's available
2. If all agents failed: use the reconnaissance findings from Step 1 as minimal context
3. If reconnaissance also failed, use AskUserQuestion to offer fallback:

   questions:
     - header: "Fallback"
       question: "Codebase exploration encountered an issue. How would you like to proceed?"
       options:
         - label: "Quick exploration"
           description: "Fall back to basic Glob/Grep/Read exploration"
         - label: "Skip"
           description: "Continue without codebase analysis"
       multiSelect: false
   

4. If quick exploration: use basic Glob/Grep/Read to understand existing patterns, related features, integration points, and data models
5. If skip: continue to Phase 3 Round 1 with whatever findings were gathered

Using Exploration Findings in Interview

When codebase exploration was performed (deep or quick), use the findings throughout the interview:

1. Tailor technical questions — Reference specific files, patterns, and conventions discovered during exploration
2. Skip answered questions — If exploration already revealed tech stack, data models, or architecture, confirm rather than ask open-ended questions
3. Ask targeted integration questions — e.g., "The codebase uses {pattern X} for similar features. Should this feature follow the same pattern?"
4. Surface risks early — If exploration found challenges (tight coupling, missing tests, complex dependencies), ask about acceptable trade-offs
5. Inform recommendations — Use exploration findings as evidence for recommendations in Phase 4

Store findings internally as "Codebase Context" and reference throughout interview and spec compilation.

External Research

Research can be invoked in two ways: on-demand when the user requests it, or proactively for specific high-value topics.

On-Demand Research

When the user explicitly requests research about technologies or general topics during the interview, invoke the research agent.

Technical research triggers:

• "Research the {API/library} documentation"
• "Look up what {technology} supports"
• "Check the docs for {feature}"
• "What does {library} provide for {feature}?"

General topic research triggers:

• "Research best practices for {area}"
• "How do competitors handle {feature}?"
• "What are the industry standards for {area}?"
• "Research {compliance} requirements" (GDPR, HIPAA, WCAG, etc.)
• "Help me understand the problem space for {domain}"
• "What do users expect from {feature type}?"

Proactive Research

You MAY proactively research (without explicit user request) for specific high-value topics:

Auto-research triggers:

• Compliance mentions: GDPR, HIPAA, PCI DSS, SOC 2, WCAG, ADA compliance
• User uncertainty: "I'm not sure", "what do you recommend?", "what's standard?"
• Complex trade-offs: When multiple valid approaches exist and current information would help

Proactive research limit: Maximum 2 proactive research calls per interview to avoid slowing down the process.

Before proactive research, briefly inform the user:

Since you mentioned GDPR compliance, let me quickly research the current requirements to ensure we capture them accurately.

Invoking Research

Use the Task tool with subagent_type researcher:

Task prompt template:
"Research {topic} for spec '{spec_name}'.

Context: {What section of the spec this relates to}
Depth level: {high-level/detailed/full-tech}

Specific questions:
- {Question 1}
- {Question 2}

Return findings in spec-ready format."

Incorporating Research Findings

After receiving research results:

1. Add to interview notes under the appropriate category:

   • Technical findings → Technical Specifications
   • Best practices → Functional Requirements
   • Compliance → Non-Functional Requirements
   • Competitive → Problem Statement / Solution Overview

2. Use findings for recommendations: Research-backed recommendations are more valuable; include source attribution

3. Use findings to ask informed follow-ups: Research may reveal new areas to explore

4. Credit sources: Include research sources in spec references section

Tracking Research Usage

Track proactive research usage during the interview:

Proactive Research: 1/2 used
- [Round 2] GDPR requirements - informed compliance recommendation

Early Exit

If the user indicates they want to wrap up early (signals like "I think that's enough", "let's wrap up", "that covers it", "skip the rest"), handle it gracefully:

1. Acknowledge the request
2. Present a truncated summary of what was gathered so far using the Pre-Compilation Summary format (Phase 5)
3. Use AskUserQuestion to confirm:

   questions:
     - header: "Early Completion"
       question: "Here's what I've gathered so far. Should I generate the spec with this information, or would you like to add anything?"
       options:
         - label: "Generate spec"
           description: "Proceed with what we have"
         - label: "Add more"
           description: "I want to provide additional details"
       multiSelect: false
   

4. If generating, add **Status**: Draft (Partial) to the spec metadata to indicate incomplete coverage
5. Proceed to Phase 6 (Spec Compilation)

Phase 4: Recommendations Round

After completing the main interview rounds and before the summary, present a dedicated recommendations round.

When to Include

• Skip for high-level depth: High-level specs focus on problem/goals; recommendations may be premature
• Include for detailed/full-tech: These depths benefit from architectural and technical recommendations
• Skip if no triggers detected: If no recommendation triggers were found, proceed directly to Phase 5

Recommendation Categories

Present recommendations organized by category:

1. Architecture: Patterns, scaling approaches, data models
2. Security: Authentication, encryption, compliance
3. User Experience: Accessibility, performance, error handling
4. Operational: Monitoring, deployment, testing strategies

Presentation Format

Introduce the recommendations round briefly:

Based on what you've shared, I have a few recommendations based on industry best practices.
I'll present each for your review — you can accept, modify, or skip any of them.

Then present each recommendation using AskUserQuestion:

AskUserQuestion:
  questions:
    - header: "Recommendation {N} of {Total}: {Category}"
      question: "{Recommendation}\n\n**Why this matters:**\n{Brief rationale}"
      options:
        - label: "Accept"
          description: "Include in spec"
        - label: "Modify"
          description: "Adjust this recommendation"
        - label: "Skip"
          description: "Don't include"
      multiSelect: false

Handling Modifications

If user selects "Modify":

1. Ask what they'd like to change using AskUserQuestion
2. Present the modified recommendation for confirmation
3. Add the modified version to accepted recommendations

Tracking

After the recommendations round, update internal tracking:

• Mark each recommendation as accepted, modified, or skipped
• Note the target spec section for accepted recommendations
• Modified recommendations include the user's adjustments

Phase 5: Pre-Compilation Summary

Before compilation, present a comprehensive summary:

## Requirements Summary

### Problem & Goals
- Problem: {summarized problem statement}
- Success Metrics: {list metrics}
- Primary User: {persona description}
- Business Value: {why this matters}

### Functional Requirements
{List each feature with acceptance criteria}

### Technical Specifications
- Tech Stack: {choices or constraints}
- Integrations: {systems to integrate with}
- Performance: {requirements}
- Security: {requirements}

### Implementation
- Phases: {list phases}
- Dependencies: {list dependencies}
- Risks: {list risks}
- Out of Scope: {list exclusions}

### Agent Recommendations (Accepted)
*The following recommendations were suggested based on industry best practices and accepted during the interview:*

1. **{Category}**: {Recommendation title}
   - Rationale: {Why this was recommended}
   - Applies to: {Which section/feature}

{Continue for all accepted recommendations, or note "No recommendations accepted" if none}

### Open Questions
{Any unresolved items}

Important: Clearly distinguish the "Agent Recommendations" section from user-provided requirements. This transparency helps stakeholders understand which requirements came from the user versus agent suggestions.

Then use AskUserQuestion to confirm:

questions:
  - header: "Summary Review"
    question: "Is this requirements summary accurate and complete?"
    options:
      - label: "Yes, proceed to spec"
        description: "Summary is accurate, generate the spec"
      - label: "Needs corrections"
        description: "I have changes or additions"
    multiSelect: false

If user selects "Needs corrections", ask what they'd like to change using AskUserQuestion, then update the summary and confirm again.

Never skip the summary confirmation step. Only proceed to compilation after user explicitly confirms via AskUserQuestion.

Phase 6: Spec Compilation

Template Selection

Choose the appropriate template based on depth level:

Diagram Guidance (Detailed/Full-Tech Only)

For "Detailed specifications" and "Full technical documentation" depth levels, load the technical-diagrams skill before compilation:

Read ${CLAUDE_PLUGIN_ROOT}/../core-tools/skills/technical-diagrams/SKILL.md

Apply its styling rules when generating Mermaid diagrams in the spec — use classDef with color:#000 for all node styles. For "High-level overview" depth, skip diagram loading.

Compilation Steps

1. Read the appropriate template based on depth level

2. Check for settings at .claude/agent-alchemy.local.md for:

   • Custom output path
   • Author name

3. Apply spec metadata formatting:

   • Use the title format # {spec-name} PRD
   • Include these metadata fields in the header block after Status:
     • **Spec Type**: The product type selected during the interview
     • **Spec Depth**: The depth level selected
     • **Description**: The initial description provided by the user
   • If early exit was used, set **Status**: Draft (Partial)

4. Organize information into template sections

5. Fill gaps by inferring logical requirements (flag assumptions clearly)

6. Add acceptance criteria for each functional requirement

7. Define phases with clear completion criteria

8. Insert checkpoint gates at critical decision points

9. Review for completeness before writing

10. Write the spec to the configured output path (default: specs/{name}-SPEC.md)

11. Present the completed spec location to the user

Writing Guidelines

Requirement Formatting

### REQ-001: [Requirement Name]

**Priority**: P0 (Critical) | P1 (High) | P2 (Medium) | P3 (Low)

**Description**: Clear, concise statement of what is needed.

**Acceptance Criteria**:
- [ ] Criterion 1
- [ ] Criterion 2

**Notes**: Any additional context or constraints.

User Story Format

**As a** [user type]
**I want** [capability]
**So that** [benefit/value]

API Specification Format (Full Tech Only)

#### Endpoint: `METHOD /path`

**Purpose**: Brief description

**Request**:
- Headers: `Content-Type: application/json`
- Body:
  ```json
  {
    "field": "type - description"
  }

Response:

• 200 OK: Success response schema
• 400 Bad Request: Validation errors
• 401 Unauthorized: Authentication required

---

## Core Principles

These principles guide how specs should be structured:

### 1. Phase-Based Milestones (Not Timelines)

Specs should define clear phases with completion criteria rather than time estimates:

- **Phase 1: Foundation** - Core infrastructure and data models
- **Phase 2: Core Features** - Primary user-facing functionality
- **Phase 3: Enhancement** - Secondary features and optimizations
- **Phase 4: Polish** - UX refinement, edge cases, documentation

### 2. Testable Requirements

Every requirement should include:
- **Clear acceptance criteria** - Specific, measurable conditions for completion
- **Test scenarios** - How to verify the requirement is met
- **Edge cases** - Known boundary conditions to handle

### 3. Human Checkpoint Gates

Define explicit points where human review is required:
- Architecture decisions before implementation begins
- API contract review before integration work
- Security review before authentication/authorization features
- UX review before user-facing changes ship

### 4. Context for AI Consumption

Structure specs for optimal AI assistant consumption:
- Use consistent heading hierarchy
- Include code examples where applicable
- Reference existing patterns in the codebase
- Provide clear file location guidance

---

## Reference Files

- `references/interview-questions.md` — Question bank organized by category and depth level (includes expanded budgets for complex projects)
- `references/complexity-signals.md` — Signal definitions, thresholds, and assessment format for complexity detection
- `references/recommendation-triggers.md` — Trigger patterns for proactive recommendations
- `references/recommendation-format.md` — Templates for presenting recommendations
- `references/templates/high-level.md` — Streamlined executive overview template
- `references/templates/detailed.md` — Standard spec template with all sections
- `references/templates/full-tech.md` — Extended template with technical specifications