Create a new specification through an adaptive interview process with proactive recommendations and optional research. Use when user says "create spec", "new spec", "generate spec", or wants to start a specification document.
Creates comprehensive product specifications through adaptive interviews with proactive recommendations and optional research.
/plugin marketplace add sequenzia/agent-alchemy/plugin install agent-alchemy-sdd-tools@agent-alchemyThis skill is limited to using the following tools:
references/codebase-exploration.mdreferences/complexity-signals.mdreferences/interview-questions.mdreferences/recommendation-format.mdreferences/recommendation-triggers.mdreferences/templates/detailed.mdreferences/templates/full-tech.mdreferences/templates/high-level.mdYou are initiating the spec creation workflow. This process gathers requirements through an adaptive, multi-round interview and generates a comprehensive specification document.
IMPORTANT: You MUST use the AskUserQuestion tool for ALL questions to the user. Never ask questions through regular text output.
Text output should only be used for:
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
CRITICAL: This skill generates a spec document, NOT an implementation plan. When invoked during Claude Code's plan mode:
The spec is a planning artifact itself — generating it IS the planning activity.
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.
This workflow has six phases:
Check if there is a settings file at .claude/agent-alchemy.local.md to get any custom configuration like output path or author name.
If $ARGUMENTS is provided, load user-supplied context before gathering initial inputs:
Determine input type:
.md, .txt, or .markdown; or starts with /, ./, ../, or ~; or contains path separators and the file exists) → read the file using the Read toolStore internally as "User-Supplied Context" for use throughout the interview
CRITICAL: User-supplied context makes the interview smarter, not shorter. Do NOT pre-fill answers or skip questions based on context. Instead:
If $ARGUMENTS is empty, skip this subsection entirely — the skill behaves exactly as before.
If user-supplied context was loaded, assess its complexity:
references/complexity-signals.md for signal definitions and thresholdsAskUserQuestion:
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
complexity_detected flag for expanded budgetsUse AskUserQuestion to gather the essential starting information with these four questions:
Question 1 - Spec Name:
Question 2 - Type:
Question 3 - Depth:
Question 4 - Description:
Before starting Round 1, read these reference files to load the full question bank and trigger patterns:
references/interview-questions.md — Question bank organized by category and depth levelreferences/recommendation-triggers.md — Trigger patterns for proactive recommendations across all domainsUse these as your primary source for questions and trigger detection throughout the interview.
Adapt your interview depth based on the requested level:
High-level overview (2-3 rounds):
Detailed specifications (3-4 rounds):
Full technical documentation (4-5 rounds):
Cover all four categories, but adjust depth based on level:
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.
When user-supplied context was loaded in Phase 2, apply these strategies throughout the interview:
Each round MUST:
AskUserQuestion — REQUIRED, never use text for questionsQuestion Guidelines:
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"
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 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:
Trigger Detection per Round:
If the product type is "New feature for existing product":
${CLAUDE_PLUGIN_ROOT}/skills/create-spec/references/codebase-exploration.mdError handling / fallback: If exploration agents fail (Task tool errors, agent timeouts, etc.):
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
When codebase exploration was performed (deep or quick), use the findings throughout the interview:
Store findings internally as "Codebase Context" and reference throughout interview and spec compilation.
Research can be invoked in two ways: on-demand when the user requests it, or proactively for specific high-value topics.
When the user explicitly requests research about technologies or general topics during the interview, invoke the research agent.
Technical research triggers:
General topic research triggers:
You MAY proactively research (without explicit user request) for specific high-value topics:
Auto-research triggers:
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.
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."
After receiving research results:
Add to interview notes under the appropriate category:
Use findings for recommendations: Research-backed recommendations are more valuable; include source attribution
Use findings to ask informed follow-ups: Research may reveal new areas to explore
Credit sources: Include research sources in spec references section
Track proactive research usage during the interview:
Proactive Research: 1/2 used
- [Round 2] GDPR requirements - informed compliance recommendation
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:
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
**Status**: Draft (Partial) to the spec metadata to indicate incomplete coverageAfter completing the main interview rounds and before the summary, present a dedicated recommendations round.
Present recommendations organized by category:
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
If user selects "Modify":
AskUserQuestionAfter the recommendations round, update internal tracking:
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.
Choose the appropriate template based on depth level:
| Depth Level | Template | Use Case |
|---|---|---|
| High-level overview | references/templates/high-level.md | Executive summaries, stakeholder alignment, initial scoping |
| Detailed specifications | references/templates/detailed.md | Standard development specs with clear requirements |
| Full technical documentation | references/templates/full-tech.md | Complex features requiring API specs, data models, architecture |
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.
Read the appropriate template based on depth level
Check for settings at .claude/agent-alchemy.local.md for:
Apply spec metadata formatting:
# {spec-name} PRD**Spec Type**: The product type selected during the interview**Spec Depth**: The depth level selected**Description**: The initial description provided by the user**Status**: Draft (Partial)Organize information into template sections
Fill gaps by inferring logical requirements (flag assumptions clearly)
Add acceptance criteria for each functional requirement
Define phases with clear completion criteria
Insert checkpoint gates at critical decision points
Review for completeness before writing
Write the spec to the configured output path (default: specs/{name}-SPEC.md)
Present the completed spec location to the user
### 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.
**As a** [user type]
**I want** [capability]
**So that** [benefit/value]
#### Endpoint: `METHOD /path`
**Purpose**: Brief description
**Request**:
- Headers: `Content-Type: application/json`
- Body:
```json
{
"field": "type - description"
}
Response:
200 OK: Success response schema400 Bad Request: Validation errors401 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
Activates when the user asks about AI prompts, needs prompt templates, wants to search for prompts, or mentions prompts.chat. Use for discovering, retrieving, and improving prompts.
Search, retrieve, and install Agent Skills from the prompts.chat registry using MCP tools. Use when the user asks to find skills, browse skill catalogs, install a skill for Claude, or extend Claude's capabilities with reusable AI agent components.
This skill should be used when the user asks to "create a slash command", "add a command", "write a custom command", "define command arguments", "use command frontmatter", "organize commands", "create command with file references", "interactive command", "use AskUserQuestion in command", or needs guidance on slash command structure, YAML frontmatter fields, dynamic arguments, bash execution in commands, user interaction patterns, or command development best practices for Claude Code.