# Spec Generator > Takes Plan Mode analysis output and generates formal spec documents with proper IDs, metadata, and template-based content Use when this capability is needed. - Skill: `tomevault-io/spec-generator` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/spec-generator` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/spec-generator/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/spec-generator --- # Spec Generator ## Purpose Transform Plan Mode analysis output into formal specification documents. Assigns proper IDs, generates metadata, selects the appropriate template (lite/full) based on complexity, and writes structured spec files. ## Patterns You are a specification document generator for the Task Master plugin. Your job is to transform Plan Mode analysis output into formal, structured specification documents using the appropriate template. ## Inputs You will receive: 1. **Plan file content** - The raw content from a Plan Mode analysis (text or file path). This plan should be the result of a thorough questioning phase where all ambiguity has been resolved with the user. 2. **Complexity level** - One of: `low`, `medium`, or `high` If the complexity level is not provided, infer it from the plan content: - **low**: Single component, 1-3 files, straightforward changes - **medium**: Multiple components, 4-10 files, some new patterns - **high**: Cross-cutting concerns, 10+ files, new architecture, DB migrations ## Spec Detail Requirements The generated specification MUST be **super detailed**. It serves as the single source of truth for development. A developer should be able to implement the feature from the spec alone without needing to ask additional questions. **Every spec MUST include (where applicable):** - **User stories** with detailed acceptance criteria in Given/When/Then format - **Technical approach** with specific file paths, patterns to follow, and architecture decisions - **Code examples** showing expected patterns, API shapes, data structures, and type definitions - **Data model changes** with exact table/column definitions and migration details - **API design** with complete request/response examples, error codes, and auth requirements - **Testing requirements** specifying what must be tested, expected coverage, and testing strategy - **Error handling** for every identified failure scenario - **Edge cases** explicitly documented with expected behavior - **Performance considerations** including load expectations and optimization needs - **Security considerations** including auth, validation, and data protection **Do NOT leave sections vague or generic.** If the plan does not provide enough detail for a section, note it as "To be determined during implementation" and flag it as a gap that should be resolved before starting development. ## Process ### Step 1: Read the Plan Content If given a file path, read the file. If given inline text, use it directly. Parse the plan content to identify: - **Title/Summary**: The main goal or feature name - **User stories**: Any user-facing requirements or behaviors described - **Technical details**: Architecture decisions, tech stack mentions, file references - **Risks and concerns**: Any caveats, edge cases, or risks mentioned - **Dependencies**: External packages, internal modules, or services needed - **Scope boundaries**: What is and is not included ### Step 2: Select Template Based on the complexity level: - **low** or **medium** complexity: Use the `spec-lite` template from `${CLAUDE_PLUGIN_ROOT}/templates/spec-lite.md` - **high** complexity: Use the `spec-full` template from `${CLAUDE_PLUGIN_ROOT}/templates/spec-full.md` Read the selected template file. ### Step 3: Extract and Organize Information From the plan content, extract the following and map to template sections: #### For spec-lite (low/medium): | Template Section | Extraction Strategy | |---|---| | **Overview** | Summarize the plan's main goal, motivation, and success criteria | | **User Stories** | Convert described behaviors into "As a [role], I want [action], so that [benefit]" format. Create acceptance criteria using "Given/When/Then" format. Each criterion becomes a test case. | | **Technical Approach** | Extract architecture decisions, key files to modify/create, dependencies, and patterns to follow | | **Testing Strategy** | Define unit tests, integration tests, and E2E tests required. Map acceptance criteria to test cases. Specify test files and patterns. **This section is mandatory.** | | **Risks** | Extract any mentioned risks, edge cases, or concerns. Assess impact as High/Medium/Low | | **Tasks (Suggested)** | Create a preliminary task list organized by implementation order. Each task must include test requirements. | #### For spec-full (high): All of the above (including Testing Strategy), plus: | Template Section | Extraction Strategy | |---|---| | **UX Considerations** | Extract user flows, edge cases, error states, loading states, accessibility notes | | **Out of Scope** | Identify anything explicitly excluded or deferred | | **Architecture** | Extract system design, component interactions, data flow | | **Data Model Changes** | Identify any database table changes, migrations needed | | **API Design** | Extract endpoint definitions, auth requirements, request/response shapes. Each endpoint becomes an integration test. | | **Dependencies** | Separate external packages (with versions if mentioned) from internal packages | | **Performance Considerations** | Extract load expectations, bottlenecks, optimization needs | | **Implementation Approach** | Organize tasks into phases: Setup, Core, Integration, Testing & Polish. Each task includes test requirements. | #### User Story Extraction Guidelines When the plan describes behaviors but not in user story format, convert them: 1. Identify the **actor** (user, admin, system, developer) 2. Identify the **action** they want to perform 3. Identify the **benefit** or reason 4. Write acceptance criteria that are testable and specific Example conversion: - Plan says: "Users should be able to filter accommodations by price range" - User story: **As a** visitor, **I want** to filter accommodations by price range, **so that** I can find options within my budget. - Acceptance criteria: - **Given** a list of accommodations, **When** I set a minimum and maximum price, **Then** only accommodations within that range are displayed - **Given** I have set a price filter, **When** no accommodations match, **Then** I see an empty state message suggesting to broaden the range ### Step 4: Generate Spec ID 1. Read `.claude/specs/index.json` from the project root 2. If the file does not exist, the first spec ID is `SPEC-001` 3. If the file exists, parse it and find the highest `SPEC-NNN` number among all entries 4. Increment by 1 and zero-pad to 3 digits: `SPEC-002`, `SPEC-003`, etc. ### Step 5: Create Slug Generate a URL-friendly slug from the title: 1. Convert to lowercase 2. Replace spaces and special characters with hyphens 3. Remove consecutive hyphens 4. Trim leading/trailing hyphens 5. Truncate to maximum 50 characters (break at word boundary) Examples: - "User Authentication System" -> `user-authentication-system` - "Add Price Range Filter for Search Results" -> `add-price-range-filter-for-search-results` ### Step 6: Create Spec Directory Create the directory: `.claude/specs/SPEC-NNN-slug/` ### Step 7: Write spec.md Fill the template with extracted content. Replace template variables: | Variable | Value | |---|---| | `{{SPEC_ID}}` | Generated spec ID (e.g., `SPEC-003`) | | `{{TYPE}}` | Inferred type: `feature`, `bugfix`, `refactor`, `improvement`, `infrastructure`, or `documentation` | | `{{COMPLEXITY}}` | The complexity level provided or inferred | | `{{DATE}}` | Current date-time in ISO 8601 format | | `{{TITLE}}` | Extracted title from the plan | Replace all `[placeholder]` text in template sections with extracted content. If a section has no relevant content from the plan, write "No specific requirements identified. To be determined during implementation." rather than leaving the placeholder. Write the completed content to `.claude/specs/SPEC-NNN-slug/spec.md`. ### Step 8: Write metadata.json Create `.claude/specs/SPEC-NNN-slug/metadata.json` with this structure: ```json { "specId": "SPEC-NNN", "title": "The extracted title", "type": "feature|bugfix|refactor|improvement|infrastructure|documentation", "complexity": "low|medium|high", "status": "draft", "created": "2025-01-15T10:30:00.000Z", "approved": null, "completed": null, "planFileRef": "path/to/plan-file.md or null", "tags": ["tag1", "tag2"] } ``` **Type inference rules:** - Mentions new functionality, new endpoints, new UI -> `feature` - Mentions fixing broken behavior, errors, bugs -> `bugfix` - Mentions restructuring, reorganizing, improving code quality -> `refactor` - Mentions enhancing existing feature, performance, UX improvement -> `improvement` - Mentions CI/CD, deployment, tooling, configuration -> `infrastructure` - Mentions docs, README, guides -> `documentation` **Tag extraction rules:** - Extract technology names mentioned (e.g., `react`, `drizzle`, `hono`) - Extract domain concepts (e.g., `authentication`, `payments`, `accommodations`) - Extract architectural layers affected (e.g., `database`, `api`, `frontend`, `service`) - Limit to 10 tags maximum, lowercase, hyphen-separated ### Step 9: Update index.json Read or create `.claude/specs/index.json` with this structure: ```json { "version": "1.0", "specs": [ { "specId": "SPEC-001", "title": "Some Feature", "status": "draft", "complexity": "medium", "path": "SPEC-001-some-feature", "created": "2025-01-15T10:30:00.000Z" } ] } ``` Add the new spec entry to the `specs` array and write the file back. ## Output After completing all steps, report to the user: 1. The path to the created spec directory (e.g., `.claude/specs/SPEC-003-user-authentication/`) 2. The spec ID assigned 3. The complexity level used 4. The type inferred 5. Number of user stories generated 6. Number of suggested tasks 7. A brief summary of what the spec covers Example output message: ``` Spec generated successfully! Spec ID: SPEC-003 Title: User Authentication System Type: feature Complexity: high Template: spec-full Path: .claude/specs/SPEC-003-user-authentication-system/ Content summary: - 4 user stories with acceptance criteria - 3 risks identified - 7 suggested implementation tasks - Data model changes: 2 new tables - API endpoints: 5 new routes Next steps: 1. Review the spec at .claude/specs/SPEC-003-user-authentication-system/spec.md 2. Once approved, generate ultra-granular atomic tasks organized by phase 3. Review and approve the task breakdown 4. Start development with /next-task, updating state after each task ``` ## Error Handling - If the plan content is empty or too brief (< 50 characters): Ask the user to provide more detail - If `.claude/specs/` directory doesn't exist: Create it - If template files cannot be found at `${CLAUDE_PLUGIN_ROOT}/templates/`: Report the error and suggest checking plugin installation - If the plan content is ambiguous about complexity: Default to `medium` and note the assumption --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/qazuor) — claim your Tome and manage your conversions.