Spec Generator

⚠️ CRITICAL: First Steps (ALWAYS EXECUTE)

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:
   bash

   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:
   bash

   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

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", "日本語で")

• English →

  references/init.md

  ,

  references/design.md

  ,

  references/tasks.md

• Japanese →

  references/init.ja.md

  ,

  references/design.ja.md

  ,

  references/tasks.ja.md

Phases

Interaction Policy: AskUserQuestion

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

When to Use AskUserQuestion

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

• 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

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

1. Detect existing source code:
   bash

   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:
   bash

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

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

   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

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

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

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

• 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

4. Output Directory

.specs/[project-name]/
├── requirement.md  (init)
├── design.md       (design)
└── tasks.md        (tasks)

• "TODO app" →

  todo-app

• "株価分析ツール" →

  stock-analysis-tool

• "Stock analysis tool" →

  stock-analysis-tool

Options

--quick

--deep

--personas

--analyze

--visual

--estimate

--hierarchy

Execution Modes

Dialogue Mode (default)

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

Quick Mode (--quick)

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

Full Workflow (full)

1. Generate requirement.md
2. Read requirement.md → generate design.md
3. Read design.md → generate tasks.md

Requirement ID System

• [REQ-XXX]

  : Functional requirements

• [NFR-XXX]

  : Non-functional requirements

• [CON-XXX]

  : Constraints

• [ASM-XXX]

  : Assumptions

• [T-XXX]

  : Tasks

YAGNI Principle

❌ 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

Optional Enhancements

• 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

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

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

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

question: "All three spec documents 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