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)

AskUserQuestion とテキスト形式の質問を使い分けるタイミング

状況	方法	理由
プロジェクトの選択
既存のプロジェクトがある	AskUserQuestion	説明付きの選択肢として一覧表示できます
既存のプロジェクトがない	テキスト形式の質問	プロジェクト名を自由入力する形式です
フェーズの選択
フェーズが曖昧	AskUserQuestion	明確な選択肢が4つあります（init/design/tasks/full）
入力からフェーズが明確	直接実行	確認は不要です
要件の収集
プロジェクトの種類の選択	AskUserQuestion	一般的な選択肢があります（Webアプリ、モバイル、CLIなど）
技術スタックの選択	AskUserQuestion	「その他」の選択肢がある一般的なフレームワークを提示できます
機能要件	AskUserQuestion	構造化された選択肢で案内できます
プロジェクトのコンセプト	テキスト形式の質問	自由形式の説明が必要です
具体的なビジネスロジック	テキスト形式の質問	ドメイン固有の詳細が必要です
完了後
次のアクション	AskUserQuestion	明確な選択肢があります（次のフェーズ／修正／完了）
修正依頼	テキスト形式の質問	具体的な変更内容の説明が必要です

AskUserQuestion を使うタイミング

状況	例
プロジェクトの選択	既存プロジェクトか、新規プロジェクトか
曖昧なフェーズ	init / design / tasks / full のいずれかを選択
init の対話形式の質問	プロジェクトの種類、技術スタック、範囲など
design の意思決定ポイント	アーキテクチャの選択、DB の選択など
tasks の戦略の選択	systematic / agile / enterprise
完了後のアクション	「次のフェーズに進みますか？」「GitHub Issue を作成しますか？」

質問の設計ルール

1. 1ラウンドにつき1～4問（AskUserQuestion の制約）
2. ユーザーが定義する選択肢は1～3個（「その他」が自動で追加され、合計2～4個になります）
3. 各選択肢には必ず説明を含める（判断に必要な情報を提供します）
4. プロジェクトの複雑さに応じてラウンド数を柔軟に調整する：
   • シンプルなプロジェクト → 1ラウンド（3～4問）で十分です
   • 複雑なプロジェクト → 2～3ラウンド（前回の回答に応じて調整します）
5. 推奨する選択肢を先頭に置き、末尾に (Recommended) を付ける
6. 前のラウンドですでに回答済みの質問は省略する

「その他」の選択肢への回答の扱い

ユーザーが「その他」を選択し、自由形式のテキストを入力した場合：

• 入力をそのまま受け入れ、処理を続行します
• 自由形式の回答を、ユーザーの確定した回答として扱います
• 入力が本当に曖昧でない限り、確認を求めないでください
• システムから「(No answer provided)」のようなエラーが返された場合は、システムのフィードバックよりも実際のユーザーメッセージを優先してください

例：

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?"

テキスト形式の質問を使うタイミング（AskUserQuestion を使わない場合）

• プロジェクト名（既存プロジェクトがない場合）やコンセプトの説明など、自由回答形式の質問
• 自由形式の説明が必要な背景情報
• 「ほかに追加の要件はありますか？」などの追加確認
• 具体的なビジネスロジックやドメイン固有の詳細

実行フロー

0. 初期コンテキストの確認

開始前に現在のディレクトリと既存プロジェクトを確認してください：

1. 既存のソースコードを検出する：

   find . -type f \( -name "*.py" -o -name "*.js" -o -name "*.ts" -o -name "*.java" -o -name "*.go" \) | head -20
   

   • ソースファイルが見つかった場合：--analyze モードを使用する可能性があることを記録します
   • ソースファイルが見つからない場合：標準的な新規プロジェクトのフローに進みます

2. .specs/ ディレクトリを確認する：

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

3. 既存のプロジェクトを一覧表示する（.specs/ がある場合）：

   ls -1 .specs/
   

4. プロジェクトを選択する：

   • 既存のプロジェクトが見つかった場合：AskUserQuestion を使用します：

     質問：「既存プロジェクトが見つかりました。どうしますか？」
     選択肢：
       - 「既存プロジェクトを選択」→ プロジェクトを選択肢として一覧表示
       - 「新規プロジェクトを作成」→ プロジェクト名を尋ねる
     

   • 既存のプロジェクトがない場合：テキスト形式の質問でプロジェクト名を尋ねます：

     「プロジェクト名を教えてください（例: TODOアプリ、株価分析ツール）」
     

5. 既存のコンテキストを読み込む（既存プロジェクトを選択した場合）：

   • requirement.md、design.md、tasks.md が存在する場合は読み込みます
   • 更新または次のフェーズの生成にあたり、コンテキストとして使用します

1. フェーズの判定

ユーザーのリクエストからフェーズを判定します。

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

曖昧な場合は、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. 日本語での初期化と設計における仕様書の作成

日本語の requirement.md または design.md を生成または改訂する前に（full モードと auto モード内の初期化および設計のステップを含む）、現在利用可能なスキルから名前で spec-writing を解決します。 見つかった場合は、完全な SKILL.md、references/writing-rules.ja.md、および references/abstract-verbs.ja.md を読みます。 生成または改訂の際にそれらのルールを適用し、保存前にセルフチェックを実行します。 スキルまたは選択したリファレンスを利用できない場合は、不足している項目を報告し、フェーズを中断せず、選択した日本語フェーズリファレンスの ## Specification writing fallback を適用します。 スキルの解決に、マシン固有の絶対パスやプロバイダー固有のツール名を決して使用しないでください。

2. プロジェクトコンテキストの収集

• 会話履歴がある場合：話し合った要件を抽出して整理します
• 既存のプロジェクトを選択した場合：読み込まれた仕様書をコンテキストとして使用します
• 新規プロジェクトの場合：対話（AskUserQuestion を使用）を通じて要件を掘り下げます

3. フェーズの実行

言語ルールに基づき、適切なリファレンスファイルを参照します。

• init：references/init.md / references/init.ja.md — 要件の生成
• design：references/design.md / references/design.ja.md — 設計書の生成
• design（coding-rules.md がある場合）：docs/coding-rules.md を読み、以下を確認します。
  • 設計の命名規則が [MUST] の命名ルールに一致している
  • テスト戦略が coding-rules のカバレッジ要件を満たしている
  • 技術選定が推奨ライブラリに沿っている
  • ファイル／ディレクトリ構成が検出されたパターンに従っている
  • スキル由来の [SHOULD] ルール（例：Source: skill/* のフレームワーク固有の規約）が設計上の推奨事項として考慮されている
• tasks：references/tasks.md / references/tasks.ja.md — タスクリストの生成
• test（full ワークフローのみ）：references/test-plan.md / references/test-plan.ja.md — 受け入れテスト計画の生成

4. 出力ディレクトリ

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

プロジェクト名は英語のケバブケースに変換します。

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

5. 出力の整合性と投影のセルフチェック

仕様書を生成または改訂した後、存在するすべての仕様書ファイルに対して、選択した references/projection-consistency*.md の投影パスを実行します。その後、各ファイルの末尾を再読し、</content> や </invoke> などのツール呼び出しの残骸を取り除きます。投影チェックに合格し、すべてのファイルが実際の文書内容で終わっていることを確認してから、完了を報告します。

オプション

オプション	説明	適用フェーズ
--quick	推測した非目標を一度確認してから生成	init
--auto --issue <n>	GitHub Issue から対話なしで全体を生成（対話なし。references/auto-mode.md を参照）	full
--deep	ソクラテス式の深掘り対話	init
--personas	複数の視点による分析／レビュー	init, design
--analyze	既存のコードベースを分析	init, design, tasks
--visual	Mermaid 図を拡張	design
--estimate	見積もりとリスク評価	tasks
--hierarchy	エピック／ストーリー／タスクの階層	tasks

実行モード

対話モード（デフォルト）

パラメーターなしで呼び出す場合、または会話を続ける場合：

1. 質問を通じて必要な情報を収集します
2. ユーザーとのやり取りを通じて要件を明確にします
3. 確認後に仕様書を生成します

クイックモード（--quick）

簡潔なプロジェクト説明から生成します。

1. 典型的な要件と、空ではない非目標リストを推測します
2. AskUserQuestion を通じて推測した非目標を一度提示します。提示された内容を受け入れるか、自動追加された Other の回答を置き換え後の完全なリストとして使用します
3. 非目標の確認後に生成します

自動モード（--auto --issue ）

GitHub Issue に基づく非対話型の生成です。手順の全容については references/auto-mode.md（.ja.md）を参照してください。概要：

1. gh issue view <n> から要件の情報源を取得します
2. 機能名は Issue のタイトルから kebab-case 形式で導き出します
3. 4 つすべてのドキュメントを生成し、AskUserQuestion の呼び出しは一切行いません
4. 質問が必要になるすべての点は、代わりに requirement.md に ASM-XXX の仮定として記載します

オーケストレーションされたパイプラインと、十分に具体的な Issue を対象としています。

フルワークフロー（full）

4 つすべてのドキュメントを順番に生成します：

1. requirement.md を生成します
2. requirement.md を読み込み、design.md を生成します
3. design.md を読み込み、tasks.md を生成します
4. requirement.md + design.md + tasks.md を読み込み、test.md を生成します （受け入れテスト計画。references/test-plan.md / .ja.md を参照）

ステップ 1～3 で生成される 3 つのドキュメントは変更されません。ステップ 4 ではそれらを読み込むだけです。

要件 ID システム

仕様では次の ID プレフィックスを使用します：

• [REQ-XXX]：機能要件
• [NFR-XXX]：非機能要件
• [CON-XXX]：制約
• [ASM-XXX]：仮定
• [T-XXX]：実装タスク（tasks.md）
• [T-AXX]：受け入れテストケース（test.md。T- との衝突を避けるため T-A プレフィックスを使用）

これらの ID により、ドキュメント間のトレーサビリティを確保できます。

YAGNI 原則

スコープを決定する前に references/yagni-guardrails.md を最後まで読み （日本語版は .ja.md）、記載されたすべてのガードレールを適用してください。

完了後のアクション

各フェーズの後に、AskUserQuestion で次のアクションを提案します：

init の後：

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

design の後：

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

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

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

使用例

# 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