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, constraint