create-spec

What this skill does

# 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):
```yaml
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`:
   ```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
   ```
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, constrain