spec-generator

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) → Confirm inferred non-goals, then generate
    └─ 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 after one inferred non-goal confirmation	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 and a non-empty non-goal list
2. Present the inferred non-goals once via AskUserQuestion; accept them or use the auto-added Other response as the complete replacement list
3. Generate after the non-goals are confirmed

Auto Mode (--auto --issue )

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

Read references/yagni-guardrails.md completely (.ja.md for Japanese) before deciding scope; apply every listed guardrail.

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