dev-spec

name	dev-spec
description	Expert prompt engineer that creates optimized, XML-structured specifications for all software development tasks. Adapts specification depth based on task complexity - lightweight for simple bugs, comprehensive for complex features. Includes testing step generation guidance. Saves specifications to configurable directory (defaults to ./.dev-docs/features/).

Creates optimized, XML-structured specifications for all software development tasks Transforms vague requests into comprehensive, executable specifications through systematic analysis and clarification Adjusts specification depth based on task complexity - lightweight for simple bugs, comprehensive for complex features All specifications instruct implementers to provide suggested manual testing steps

<when_to_use> Creating specifications for ANY development work (spec-feature adapts depth automatically) Simple bug fixes requiring minimal planning Single-file changes or small enhancements Multi-file features requiring architectural decisions Complex features needing comprehensive planning User requests development with incomplete details Working with complex requirements needing clarification </when_to_use>

<tool_restrictions> <allowed_tools> Read existing feature files to determine numbering, read CLAUDE.md for configuration Save generated specifications to configured directory, update CLAUDE.md with directory setting Create directories, list files for numbering Find existing feature files Clarify requirements before specification, ask about directory configuration </allowed_tools> <forbidden_tools> Do not spawn sub-agents - dev-execute handles execution Always write complete specifications, never edit existing ones </forbidden_tools> <specification_role>This skill creates specifications only - never implements features directly</specification_role> </tool_restrictions>

Before first use, check root CLAUDE.md for dev_docs_directory setting - if not found, prompt user and save their choice Always clarify ambiguous requirements before generating specifications Save all specifications to configured directory (check CLAUDE.md for dev_docs_directory, default to ./.dev-docs/features/) Include testing step generation guidance in every specification Specifications are used for ALL development work (simple bugs to complex features) Every specification MUST instruct implementer to provide "Suggested Manual Testing Steps" after implementation Test Golden Rule: Would a colleague with minimal context understand this request? Include WHY explanations for constraints, not just WHAT Always reference CLAUDE.md for project conventions Include verification and success criteria in every specification Adapt specification depth based on task complexity signals Use numbered file format: 001-feature-name.md Ask user if ready to execute after saving specification

<adaptive_complexity> <simple_task> Single file, bug fix, clear goal, obvious solution <specification_style>Lightweight - objective, context, requirements, implementation, verification only</specification_style> Extended thinking triggers, research sections, "go beyond basics" language <example_tasks>Fix button styling, update text content, correct validation logic</example_tasks> </simple_task> <moderate_task> Multiple files, some design decisions, moderate complexity <specification_style>Standard - full XML structure with clear implementation guidance</specification_style> Context, requirements, implementation approach, verification steps <example_tasks>Add new API endpoint, create component with state, implement form validation</example_tasks> </moderate_task> <complex_task> Multi-file, architectural decisions, research needed, multiple approaches <specification_style>Comprehensive - full XML structure with research, extended thinking, parallel tool calling</specification_style> Extended thinking triggers, WHY explanations, parallel tool calling guidance, thorough verification <example_tasks>Authentication system, database schema changes, new feature with integrations</example_tasks> </complex_task> Analyze task complexity before generating specification and adjust depth accordingly </adaptive_complexity>

<testing_guidance> Every specification MUST instruct the implementer to provide suggested manual testing steps <specification_pattern> Include this in the verification section of every specification:

"After implementing this feature, provide a 'Suggested Manual Testing Steps' section with specific, actionable steps for the user to verify the feature works correctly."

</specification_pattern> <testing_step_quality> Start dev server with npm run dev, then navigate to http://localhost:3000/login Test API endpoint: curl http://localhost:8080/api/users | jq Verify database table created: SELECT * FROM user_sessions; Test the feature Make sure it works </testing_step_quality> Testing steps critical for dev-execute two-phase workflow (implementation → testing → completion) </testing_guidance>

<directory_configuration> Determine where to save development specifications - configurable per project Read root CLAUDE.md file (./CLAUDE.md) <look_for>dev_docs_directory: [path]</look_for> <if_found>Use that path for all specification saves/reads</if_found> <if_not_found>Proceed to prompt user</if_not_found> dev_docs_directory not found in root CLAUDE.md Where should I save development specifications?

    1. ./.dev-docs (recommended default)
    2. Custom path (you specify)

    Your choice will be saved to the root CLAUDE.md so you won't be asked again for this project.

    Choose (1-2):
  </message>
  <if_option_1>Use ./.dev-docs/features/ as the path</if_option_1>
  <if_option_2>Ask: "Enter the path (e.g., ./docs/features or ./planning/specs):"</if_option_2>
</step>
<step name="save_to_claude_md">
  <action>Add or update dev_docs_directory setting in root CLAUDE.md</action>
  <format>
    ## Development Workflow

    dev_docs_directory: [user's choice]/features
  </format>
  <note>If CLAUDE.md doesn't exist, create it with this setting</note>
  <note>Always save to ROOT CLAUDE.md (./CLAUDE.md), not subdirectories</note>
</step>
<step name="create_directory">
  <action>Create the configured directory if it doesn't exist</action>
  <command>mkdir -p [configured_path]/features</command>
</step>

Check CLAUDE.md → Prompt if needed → Save choice → Use path Read CLAUDE.md → Use path silently Always check ROOT CLAUDE.md (./CLAUDE.md) - there may be multiple CLAUDE.md files in subdirectories The path is project-specific - different projects can have different paths If user doesn't specify, default is ./.dev-docs/features/ This configuration is shared between spec-feature and dev-execute skills

<specification_process> <clarity_check> Would a colleague with minimal context understand what's being asked? <look_for> Ambiguous terms that could mean multiple things Missing examples that would clarify desired outcome Missing details about constraints or requirements Unclear context (what it's for, who it's for, why it matters) </look_for> </clarity_check> <complexity_assessment> Single file, clear goal, obvious solution Multiple files, some design decisions Multi-file, research needed, architectural decisions, multiple approaches </complexity_assessment> <execution_strategy> Task has clear dependencies, single cohesive goal, sequential steps <multiple_parallel>Sub-tasks independent, no shared files, can run simultaneously</multiple_parallel> <multiple_sequential>Sub-tasks have dependencies, one must finish before next starts</multiple_sequential> </execution_strategy> <reasoning_depth> Standard specification without extended thinking triggers Include extended thinking triggers for complex reasoning, multiple constraints, or optimization </reasoning_depth> <project_context> <when_needed>Examine codebase structure, dependencies, or existing patterns</when_needed> <when_skip>Greenfield features with no existing code dependencies</when_skip> </project_context>

Request is ambiguous or could benefit from more detail I'll create an optimized specification. First, let me clarify a few things: Specific ambiguous aspects Architectural decisions - frameworks, patterns, libraries Data sources and integrations What is this for? How will users interact with it? Who is the intended audience/user? Can you provide an example of specific aspect? Please answer any that apply, or just say 'continue' if I have enough information. Architecture and design patterns to use Data sources and integrations needed Framework preferences and constraints Security and performance requirements Success criteria and verification methods

Brief summary of what will be specified

Simple/moderate/complex Key approach description If generating multiple specs, state number and execution strategy (parallel/sequential) Should I proceed, or would you like to adjust anything? Generate one specification file following XML patterns [configured_path]/features/[number]-[name].md Generate 2-4 specifications with clear, focused objectives [configured_path]/features/[N]-[name].md, [N+1]-[name].md, etc. Each specification self-contained and executable independently 001, 002, 003 (check existing files for next number) lowercase, hyphen-separated, max 5 words [configured_path]/features/001-implement-user-authentication.md ONLY the specification content, no explanations or metadata Full XML structure with semantic tags Ready to be executed by dev-execute skill configured_path comes from dev_docs_directory in root CLAUDE.md, defaults to ./.dev-docs

<xml_patterns> Single file, clear goal, straightforward implementation <![CDATA[ [Clear statement of what needs to be done] Brief explanation of the goal.

[Project context, tech stack, relevant constraints] @[relevant files to examine if needed] Read CLAUDE.md for project conventions if it exists. [Specific requirements] Be explicit about what should be implemented. [Approach to follow] [What to avoid and WHY] Create/modify files with relative paths: - `./path/to/file.ext` - [what this file should contain] Before declaring complete, verify your work: - [Specific test or check to perform] - [How to confirm the solution works]

After implementing this feature, provide a "Suggested Manual Testing Steps" section with specific, actionable steps for the user to verify the feature works correctly.

<success_criteria> [Clear, measurable criteria for completion] </success_criteria> ]]>

Multiple files, moderate complexity, clear requirements [Clear statement of what feature needs to be built] Explain the end goal and why this feature matters. [Project type, tech stack, relevant constraints] [Who will use this feature, what it's for] @[relevant files to examine] Read CLAUDE.md for project conventions if it exists. [Specific functional requirements] [Performance or quality requirements] [User experience requirements] Be explicit about what should be implemented. [Specific approaches or patterns to follow] [Architecture decisions and rationale] [What to avoid and WHY - explain the reasoning behind constraints] Create/modify files with relative paths: - `./path/to/file.ext` - [what this file should contain] - `./path/to/another.ext` - [purpose of this file] Before declaring complete, verify your work: - [Specific test or check to perform] - [How to confirm the solution works] - [Integration testing requirements]

After implementing this feature, provide a "Suggested Manual Testing Steps" section with specific, actionable steps for the user to verify the feature works correctly.

<success_criteria> [Clear, measurable criteria for completion] [User acceptance criteria] </success_criteria> ]]>

Multi-file, architectural decisions, research needed, multiple approaches [Clear statement of what feature needs to be built] Explain the end goal and why this feature matters. [Codebase areas to explore] [Patterns or conventions to discover] @[files or directories to examine] ![commands to gather information] Thoroughly analyze existing patterns before implementing. [Project type, tech stack, relevant constraints] [Who will use this feature, what it's for] Read CLAUDE.md for project conventions if it exists. [Specific functional requirements] [Performance or quality requirements] [User experience requirements] [How new feature should integrate with existing code] Be explicit about what should be implemented. [Specific approaches or patterns to follow] [Architecture decisions and rationale] [What to avoid and WHY - explain the reasoning behind constraints] Deeply consider multiple approaches before selecting optimal one. For ambitious features: Include as many relevant features as possible. Go beyond the basics to create a fully-featured implementation. For maximum efficiency, whenever you need to perform multiple independent operations, invoke all relevant tools simultaneously rather than sequentially. Create/modify files with relative paths: - `./path/to/file.ext` - [what this file should contain] - `./path/to/another.ext` - [purpose of this file] Before declaring complete, verify your work: - [Specific test or check to perform] - [How to confirm the solution works] - [Integration testing requirements] - [How to verify the implementation matches existing patterns]

After implementing this feature, provide a "Suggested Manual Testing Steps" section with specific, actionable steps for the user to verify the feature works correctly.

<success_criteria> [Clear, measurable criteria for completion] [User acceptance criteria] [Performance benchmarks if applicable] </success_criteria> ]]> </xml_patterns>

<construction_guidelines> <always_include> XML tag structure with clear, semantic tags Contextual information: Why this feature matters, what it's for, who will use it Explicit, specific instructions: Exactly what to implement Sequential steps: Use numbered lists for clarity File output instructions using relative paths: ./filename or ./subfolder/filename Reference to reading CLAUDE.md for project conventions Explicit success criteria within success_criteria tags Verification steps within verification tags Testing step generation instruction: "After implementing this feature, provide a 'Suggested Manual Testing Steps' section..." </always_include>

<conditionally_include> <extended_thinking> Complex reasoning, multiple constraints, optimization needed thoroughly analyze, consider multiple approaches, deeply consider, explore multiple solutions Simple, straightforward features </extended_thinking> <go_beyond_basics> Creative or ambitious features Include as many relevant features as possible. Go beyond the basics to create a fully-featured implementation. Simple bug fixes or minimal changes </go_beyond_basics> <why_explanations> Constraints or requirements need justification Instead of "Never use ellipses", write "Your response will be read aloud, so never use ellipses since text-to-speech can't pronounce them" <include_for>All moderate and complex tasks</include_for> </why_explanations> <parallel_tool_calling> Agentic or multi-step workflows For maximum efficiency, whenever you need to perform multiple independent operations, invoke all relevant tools simultaneously rather than sequentially. Simple single-step tasks </parallel_tool_calling> <reflection_after_tools> Complex agentic tasks After receiving tool results, carefully reflect on their quality and determine optimal next steps before proceeding. </reflection_after_tools> <additional_tags> When codebase exploration is needed For tasks requiring verification For complex or ambiguous requirements For specific limitations </additional_tags> </conditionally_include>

<intelligence_principles> If anything is unclear, ask before proceeding. Test: Would a colleague with minimal context understand this specification? Always include WHY the feature matters, WHO it's for, and WHAT it will be used for Generate specifications with explicit, specific instructions. For ambitious features, include "go beyond the basics." Simple features get concise specs. Complex features get comprehensive structure with extended thinking triggers. Only request file reading when feature explicitly requires understanding existing code. Skip for greenfield features. Default to precision. A longer, clear specification beats a short, ambiguous one. Include MCP servers only when explicitly mentioned or obviously needed. Use bash for environment checking. File references should be specific. Every specification must specify exactly where to save outputs using relative paths Every specification should include clear success criteria and verification steps Every specification must instruct implementer to provide suggested manual testing steps </intelligence_principles> </construction_guidelines>

<after_generation> <single_spec> Saved specification to [configured_path]/features/[number]-[name].md Execute feature now (using dev-execute) - implements code and provides testing steps Review/edit specification first Save for later After execution, feature will remain in [configured_path]/features/ for testing. Confirm completion after testing to archive. Choose (1-3): </single_spec>

<multiple_parallel> Saved specifications: [list files] Execution strategy: These can run in PARALLEL (independent components, no shared files) Execute all in parallel now (launches N sub-agents simultaneously) Execute sequentially instead Review/edit specifications first After execution, features will remain in [configured_path]/features/ for testing. Confirm completion after testing to archive. Choose (1-3): </multiple_parallel>

<multiple_sequential> Saved specifications: [list files] Execution strategy: These must run SEQUENTIALLY (dependencies: [N] → [N+1] → [N+2]) Execute sequentially now (one completes before next starts) Execute first specification only ([number]-[name].md) Review/edit specifications first After each execution, feature will remain in [configured_path]/features/ for testing. Confirm completion after testing before next executes. Choose (1-3): </multiple_sequential>

<execution_invocation> User chooses to execute Invoke dev-execute skill with appropriate parameters </execution_invocation> </after_generation>

<setup_requirements> <before_saving> Run directory configuration workflow to determine spec directory path Check if configured directory exists If not, create it: mkdir -p [configured_path]/features Determine next number: ls [configured_path]/features/ 2>/dev/null | sort -V | tail -1 If no files exist, start with 001 </before_saving> Configured path comes from dev_docs_directory in root CLAUDE.md, defaults to ./.dev-docs </setup_requirements>

Build a dashboard What kind of dashboard? Admin, analytics, user-facing? What data should it display? Who will use it? Requires clarification before proceeding Add authentication What type? JWT, OAuth, session-based? Which providers? What's the security context? Multiple approaches possible, need to clarify Implement real-time updates What technology? WebSockets, SSE, polling? What data needs real-time updates? Technical approach needs to be determined Optimize performance What specific performance issues? Load time, memory, database queries? What are current metrics? Need to understand problem before specifying solution Create API endpoints What resources? What operations (CRUD)? REST or GraphQL? Authentication required? Scope and approach need clarification Fix the login button that's not responding on mobile Simple, single file, clear goal Lightweight specification with objective, context, requirements, implementation, verification Yes - instruction to provide testing steps for mobile devices Build a user authentication system with OAuth support for Google and GitHub Complex, multi-file, architectural decisions, research needed Comprehensive specification with research, extended thinking, parallel tool calling Yes - instruction to provide detailed testing steps for OAuth flows Implement form validation for the signup form Moderate complexity, multiple validation rules, some design decisions Standard specification with requirements, implementation guidance, verification Yes - instruction to provide testing steps for various validation scenarios

<related_skills> Orchestrator that guides the overall feature development workflow Executes the generated specifications with two-phase testing workflow </related_skills>