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:
2. 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
3. Otherwise → treat the entire argument string as inline context text

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

1. CRITICAL: User-supplied context makes the interview smarter, not shorter. Do NOT pre-fill answers or skip questions based on context. Instead:
2. Ask more targeted, specific questions informed by the context
3. Probe areas the context doesn't cover
4. Confirm implicit assumptions the context makes
5. 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:

```yaml 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 ```

1. If user selects "Yes, let's be thorough" → set internal complexity_detected flag for expanded budgets
2. If user selects "Keep it brief" → proceed with standard budgets
3. 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, constraint