shield_lock
JinDaGe
← Back to skills
extension
Category: Development & EngineeringNo API key required

spec-generator

Specification Generator — Generate project requirements, design documents, and task lists. A skill for generating structured project specifications through interactive dialogue or quick generation. English triggers: - "Create requirements", "Generate requirements doc", "Summarize as requirements" - "Create design document", "Design the architecture", "Generate technical spec" - "Create task list", "Break down into tasks", "Generate tasks.md" - "Create full spec", "Generate all specs", "Create the complete specification" - After discussion: "Turn this into requirements", "Document this as spec" Japanese triggers: - 「要件定義を作って」「要件をまとめて」「仕様書を作成して」- 「設計書を作って」「技術設計をして」「アーキテクチャを設計して」- 「タスクリストを作って」「実装タスクに分解して」「tasks.mdを生成して」- 「仕様を全部まとめて」「フル仕様を作成」「3点セットを作って」- 会話で仕様が固まった後に「これを要件定義書にして」

personAuthor: jakexiaohubgithub
open_in_newRepositorydownloadDownload package

spec-generator — Specification Generator

Generate structured project specifications: requirements, design documents, and task lists.

⚠️ CRITICAL: First Steps (ALWAYS EXECUTE)

Auto mode short-circuit: If invoked with --auto --issue <n>, skip the interactive decision flow below and follow references/auto-mode.md (.ja.md) instead. Auto mode never calls AskUserQuestion, but its Japanese init and design steps still execute the specification-writing procedure in Step 1.5.

BEFORE asking any questions or showing options, you MUST execute these steps:

  1. Check current directory:

    • Run pwd to see where you are
    • Run ls -la to see directory contents
    • Understand the project context

  2. Detect existing source code:

    find . -maxdepth 3 -type f \( -name "*.py" -o -name "*.js" -o -name "*.ts" -o -name "*.java" -o -name "*.go" -o -name "SKILL.md" \) 2>/dev/null | head -20
    • Note what kind of project this is
    • Check for skills/ directory → might be adding a new skill
    • Check for existing application code → might be documenting existing features

  3. Check for .specs/ directory:

    ls -d .specs/ 2>/dev/null && ls -1 .specs/ 2>/dev/null
    • If exists → list existing projects
    • If not exists → this is a new spec workflow

  4. Check for coding-rules.md:

    • Check docs/coding-rules.md (default path)
    • If not found, check CLAUDE.md / AGENTS.md for alternative path
    • If found → load and use as design constraint during design phase

  5. Analyze context and decide:

    • If in a skills repository (has skills/ directory) → User likely wants to document a new skill
    • If .specs/ has projects → Ask user to select existing or create new
    • If no .specs/ and no clear context → Ask what they want to create

Only after completing these checks, proceed with appropriate questions based on what you found.

Language Rules

  1. Auto-detect input language → output in the same language
  2. Japanese input → Japanese output, use references/*.ja.md as phase references
  3. English input → English output, use references/*.md as phase references
  4. Explicit override takes priority (e.g., "in English", "日本語で")

Reference file selection: Based on the detected output language, use the corresponding reference files:

  • English → references/init.md, references/design.md, references/tasks.md, references/test-plan.md, references/auto-mode.md, references/projection-consistency.md
  • Japanese → references/init.ja.md, references/design.ja.md, references/tasks.ja.md, references/test-plan.ja.md, references/auto-mode.ja.md, references/projection-consistency.ja.md

Phases

| Phase | Output | Trigger Examples | |-------|--------|-----------------| | init | requirement.md | "Create requirements", "要件定義を作って" | | design | design.md | "Create design doc", "設計書を作って" | | tasks | tasks.md | "Create task list", "タスクリストを作って" | | full | All three above + test.md | "Create full spec", "仕様を全部" |

Interaction Policy: AskUserQuestion

Use AskUserQuestion for all user decisions. Present structured choices rather than free-form questions.

Decision Flow

Skill Invoked
    ↓
Check .specs/ directory
    ↓
┌───────────────────┐
│ Existing projects │
│ found?            │
└─────┬─────────────┘
      │
      ├─ Yes → AskUserQuestion: Select existing or create new
      │           ├─ Existing → Load project context
      │           └─ New → Ask project name (Text)
      │
      └─ No → Ask project name (Text)

    ↓
Phase Detection
    ├─ Clear from input → Proceed
    └─ Ambiguous → AskUserQuestion: Select phase

    ↓
Dialogue Mode
    ├─ Quick mode (--quick) → Generate directly
    └─ Dialogue → AskUserQuestion: Gather requirements

    ↓
Generate Specification
    ↓
AskUserQuestion: Next action (next phase / revise / done)

When to Use AskUserQuestion vs Text Questions

| Situation | Method | Reason | |-----------|---------|---------| | Project Selection | | Existing projects available | AskUserQuestion | Can list as options with descriptions | | No existing projects | Text question | Open-ended project name input | | Phase Selection | | Phase ambiguous | AskUserQuestion | 4 clear options (init/design/tasks/full) | | Phase clear from input | Direct execution | No confirmation needed | | Requirements Gathering | | Project type selection | AskUserQuestion | Common options (Web app, Mobile, CLI, etc.) | | Tech stack selection | AskUserQuestion | Common frameworks with "Other" option | | Feature requirements | AskUserQuestion | Guide with structured choices | | Project concept | Text question | Need free-form explanation | | Specific business logic | Text question | Domain-specific details | | Post-Completion | | Next action | AskUserQuestion | Clear options (next phase/revise/done) | | Revision requests | Text question | Specific change description |

When to Use AskUserQuestion

| Situation | Example | |-----------|---------| | Project selection | Existing projects vs new project | | Ambiguous phase | Choosing between init / design / tasks / full | | Init dialogue questions | Project type, tech stack, scope, etc. | | Design decision points | Architecture choices, DB selection, etc. | | Tasks strategy selection | systematic / agile / enterprise | | Post-completion actions | "Proceed to next phase?", "Create GitHub Issue?" |

Question Design Rules

  1. 1–4 questions per round (AskUserQuestion constraint)
  2. User-defined options: 1-3 (Other is auto-appended, totaling 2-4 options)
  3. Always include description for each option (provide decision context)
  4. Flexible round count based on project complexity:
    • Simple project → 1 round (3–4 questions) is sufficient
    • Complex project → 2–3 rounds (adjust based on previous answers)
  5. Place recommended option first with (Recommended) suffix
  6. Skip questions already answered in previous rounds

Handling "Other" Option Responses

When a user selects "Other" and provides free-form text input:

  • Accept the input as-is and proceed with processing
  • Treat the free-form response as the user's definitive answer
  • Do NOT ask for clarification unless the input is genuinely ambiguous
  • If system returns an error like "(No answer provided)", trust the user's actual message over system feedback

Example:

Question: "どのスキルの仕様を作成しますか？"
Options: spec-constitution / spec-review / spec-analyze / spec-impl

User selects "Other" and writes: "仕様書自体をレビューするコマンド"

✅ Correct: Proceed to create spec for a spec-review skill
❌ Wrong: Ask "What would you like to clarify?"

When to Use Text Questions (Not AskUserQuestion)

  • Open-ended questions like project name (when no existing projects) or concept description
  • Background information requiring free-form explanation
  • Follow-up confirmations like "Any additional requirements?"
  • Specific business logic or domain-specific details

Execution Flow

0. Initial Context Check

Check the current directory and existing projects before starting:

  1. Detect existing source code:

    find . -type f \( -name "*.py" -o -name "*.js" -o -name "*.ts" -o -name "*.java" -o -name "*.go" \) | head -20
    • If source files found: Note for potential --analyze mode
    • If no source files: Standard new project flow

  2. Check for .specs/ directory:

    ls -d .specs/ 2>/dev/null

  3. List existing projects (if .specs/ exists):

    ls -1 .specs/

  4. Project selection:

    • Existing projects found: Use AskUserQuestion: 
      question: "既存プロジェクトが見つかりました。どうしますか？" / "Found existing projects. What would you like to do?"
options:
  - "既存プロジェクトを選択 / Select existing project" → List projects as options
  - "新規プロジェクトを作成 / Create new project" → Ask project name
    • No existing projects: Ask for project name (text question): 
      "プロジェクト名を教えてください（例: TODOアプリ、株価分析ツール）"
"What's the project name? (e.g., todo app, stock analyzer)"

  5. Load existing context (if existing project selected):

    • Read existing requirement.md, design.md, tasks.md if they exist
    • Use as context for updates or next phase generation

1. Phase Detection

Determine the phase from the user's request:

"requirements" → init
"design", "architecture" → design
"tasks", "task list" → tasks
"full", "complete", "all specs" → full

If ambiguous, confirm with AskUserQuestion:

question: "Which specification do you want to generate?"
options:
  - "Requirements document (requirement.md)" → init
  - "Design document (design.md)" → design
  - "Task list (tasks.md)" → tasks
  - "All three documents" → full

1.5. Specification Writing for Japanese Init and Design

Before generating or revising a Japanese requirement.md or design.md—including init and design steps inside full and auto modes—resolve spec-writing by name from the currently available skills. If found, read its complete SKILL.md, references/writing-rules.ja.md, and references/abstract-verbs.ja.md. Apply those rules during generation or revision and run their self-check before saving. If the skill or a selected reference is unavailable, report the missing item and apply ## Specification writing fallback from the selected Japanese phase reference without stopping the phase. Never depend on a machine-specific absolute path or provider-specific tool name when resolving the skill.

2. Project Context Gathering

  • Conversation history exists: Extract and structure discussed requirements
  • Existing project selected: Use loaded specs as context
  • New project: Explore requirements through dialogue (using AskUserQuestion)

3. Phase Execution

Refer to the appropriate reference file (based on Language Rules):

  • init: references/init.md / references/init.ja.md — Requirements generation
  • design: references/design.md / references/design.ja.md — Design document generation
  • design (with coding-rules.md): If docs/coding-rules.md exists, read it and ensure:
    • Naming conventions in design match [MUST] naming rules
    • Test strategy satisfies coverage requirements from coding-rules
    • Technology choices align with recommended libraries
    • File/directory structure follows detected patterns
    • Skill-derived [SHOULD] rules (e.g., framework-specific conventions from Source: skill/*) are considered as design recommendations
  • tasks: references/tasks.md / references/tasks.ja.md — Task list generation
  • test (full workflow only): references/test-plan.md / references/test-plan.ja.md — Acceptance test plan generation

4. Output Directory

.specs/[project-name]/
├── requirement.md  (init)
├── design.md       (design)
├── tasks.md        (tasks)
└── test.md         (full workflow only — acceptance test plan)

Project names are converted to English kebab-case:

  • "TODO app" → todo-app
  • "株価分析ツール" → stock-analysis-tool
  • "Stock analysis tool" → stock-analysis-tool

5. Output Integrity and Projection Self-Check

After generating or revising a spec, run the projection pass in the selected references/projection-consistency*.md across every present spec file. Then re-read each tail and remove tool-call residue such as </content> or </invoke>. Report completion only after projection checks pass and every file ends with real document content.

Options

| Option | Description | Applicable Phase | |--------|-------------|-----------------| | --quick | Generate without dialogue | init | | --auto --issue <n> | Non-interactive full generation from a GitHub Issue (no dialogue; see references/auto-mode.md) | full | | --deep | Socratic deep-dive dialogue | init | | --personas | Multi-perspective analysis/review | init, design | | --analyze | Analyze existing codebase | init, design, tasks | | --visual | Enhanced Mermaid diagrams | design | | --estimate | Estimates and risk assessment | tasks | | --hierarchy | Epic/Story/Task hierarchy | tasks |

Execution Modes

Dialogue Mode (default)

When invoked without parameters or continuing from conversation:

  1. Collect necessary information through questions
  2. Clarify requirements through user interaction
  3. Generate specification after confirmation

Quick Mode (--quick)

Generate from a brief project description:

  1. Infer typical requirements from the description
  2. Generate based on best practices
  3. Complete without dialogue

Auto Mode (--auto --issue <n>)

Non-interactive generation driven by a GitHub Issue. See references/auto-mode.md (.ja.md) for the full procedure. Summary:

  1. gh issue view <n> supplies the requirement source
  2. Feature name is derived from the Issue title as kebab-case
  3. All four documents are generated with zero AskUserQuestion calls
  4. Every point that would need a question is written as an ASM-XXX assumption in requirement.md instead

Intended for orchestrated pipelines and sufficiently concrete Issues.

Full Workflow (full)

Generate all four documents sequentially:

  1. Generate requirement.md
  2. Read requirement.md → generate design.md
  3. Read design.md → generate tasks.md
  4. Read requirement.md + design.md + tasks.md → generate test.md (acceptance test plan; see references/test-plan.md / .ja.md)

The three-document output of steps 1–3 is unchanged; step 4 only reads them.

Requirement ID System

Specifications use the following ID prefixes:

  • [REQ-XXX]: Functional requirements
  • [NFR-XXX]: Non-functional requirements
  • [CON-XXX]: Constraints
  • [ASM-XXX]: Assumptions
  • [T-XXX]: Implementation tasks (tasks.md)
  • [T-AXX]: Acceptance test cases (test.md; T-A prefix avoids collision with T-)

These IDs ensure traceability across documents.

YAGNI Principle

Do not include unless explicitly requested or discussed:

❌ Authentication & Authorization

  • Complex permission management (when basic auth suffices)
  • Role-based access control with multiple roles (admin/user is usually enough)
  • Social login integration (when basic email/password auth is sufficient)
  • Fine-grained permission systems

❌ Analytics & Monitoring

  • Advanced analytics/reporting dashboards
  • Detailed audit logging (unless compliance requirements exist)
  • Real-time metrics and monitoring
  • User behavior tracking
  • A/B testing infrastructure

❌ Infrastructure & Scalability

  • Multi-tenant support (unless explicitly required)
  • API versioning (unless external integration requirements exist)
  • Async processing (unless performance requirements demand it)
  • Batch processing/scheduled jobs (unless specified)
  • Auto-scaling infrastructure
  • Load balancing configuration

❌ User Experience

  • Real-time notifications/updates (unless explicitly required)
  • Advanced search/filtering (when basic search suffices)
  • Data export features (PDF, Excel, etc.)
  • Offline mode support
  • Push notifications

❌ Development & Operations

  • Data migration plans (for brand new projects)
  • Multi-language/i18n support (unless specified)
  • Admin dashboards (when simple CRUD interfaces suffice)
  • Complex deployment pipelines
  • Automated backup systems

✅ Include by Default

  • Basic authentication (email/password)
  • Simple CRUD operations
  • Basic error handling and validation
  • Essential security (HTTPS, password hashing, input sanitization)
  • Core business logic only
  • Simple, clear user interfaces
  • Basic data persistence

When in doubt: Ask via AskUserQuestion rather than assuming the feature is needed.

Optional Enhancements

When advanced analysis tools are available in your environment, consider using them for:

  • Systematic analysis of complex, interconnected requirements
  • Framework-specific best practices and pattern lookup
  • Existing codebase semantic analysis and symbol navigation
  • UI/UX pattern recommendations

Post-Completion Actions

After each phase, suggest next actions with AskUserQuestion:

After init:

question: "Requirements document generated. What's next?"
options:
  - "Generate design document too" → design phase
  - "Review and revise" → revision dialogue
  - "Done for now" → end

After design:

question: "Design document generated. What's next?"
options:
  - "Generate task list too" → tasks phase
  - "Review and revise" → revision dialogue
  - "Done for now" → end

After tasks:

question: "Task list generated. What's next?"
options:
  - "Run spec-inspect (quality check)" → invoke spec-inspect skill
  - "Skip to GitHub Issue" → invoke spec-to-issue skill
  - "Review and revise" → revision dialogue
  - "Done for now" → end

After full:

question: "All four spec documents (3-set + test.md) are complete."
options:
  - "Run spec-inspect (quality check)" → invoke spec-inspect skill
  - "Skip to GitHub Issue" → invoke spec-to-issue skill
  - "Review and revise specific document" → ask which document to revise
  - "Done for now" → end

Usage Examples

# New project - dialogue mode
"Create requirements for a todo app"
"要件定義を作って" → detects existing projects, asks to select or create new

# Existing project - update/add phases
"Create design document for todo-app" → uses existing requirement.md as context
「todo-appのタスクリストを作って」 → uses existing design.md as context

# Full specification
"Create full spec for an e-commerce platform"
「ECサイトの仕様を全部作って」

# Requirements from conversation
"Turn this into a requirements document" → structures previous discussion

# Quick mode
"Create requirements for a blog platform --quick"

# Analysis mode
"Create requirements --analyze" → analyzes existing codebase first