Spec Generator
6 つの連続フェーズを通じて、複数の CLI による分析と対話形式での改善を行い、完全な仕様書パッケージ（製品概要、PRD、アーキテクチャ、エピック）を生成する構造化仕様書ジェネレーターです。ドキュメント生成のみを行い、既存のワークフロー（lite-plan、plan、req-plan）へ実行を引き継ぎます。
アーキテクチャ概要
Phase 0: Specification Study (Read specs/ + templates/ - mandatory prerequisite)
|
Phase 1: Discovery -> spec-config.json + discovery-context.json
| (includes spec_type selection)
Phase 1.5: Req Expansion -> refined-requirements.json (interactive discussion + CLI gap analysis)
| (-y auto mode: auto-expansion, skip interaction)
Phase 2: Product Brief -> product-brief.md + glossary.json (multi-CLI parallel analysis)
|
Phase 3: Requirements (PRD) -> requirements/ (_index.md + REQ-*.md + NFR-*.md)
| (RFC 2119 keywords, data model definitions)
Phase 4: Architecture -> architecture/ (_index.md + ADR-*.md, multi-CLI review)
| (state machine, config model, error handling, observability)
Phase 5: Epics & Stories -> epics/ (_index.md + EPIC-*.md)
|
Phase 6: Readiness Check -> readiness-report.md + spec-summary.md
| (terminology + scope consistency validation)
├── Pass (>=80%): Handoff to execution workflows
├── Review (60-79%): Handoff with caveats
└── Fail (<60%): Phase 6.5 Auto-Fix (max 2 iterations)
|
Phase 6.5: Auto-Fix -> Updated Phase 2-5 documents
|
└── Re-run Phase 6 validation
主な設計原則
- ドキュメントチェーン：各フェーズは前のフェーズの成果物を基に構築し、アイデアから実行可能なストーリーまで、追跡可能な仕様書チェーンを作成します
- 多角的な分析：CLI ツール（Gemini／Codex／Claude）が、製品、技術、ユーザーの視点を並行して提供します
- デフォルトで対話形式：各フェーズにユーザーの確認ポイントがあります。
-y フラグを指定すると、全自動モードが有効になります
- 再開可能なセッション：
spec-config.json が完了したフェーズを記録します。-c フラグを指定すると、最後のチェックポイントから再開します
- テンプレート駆動：すべてのドキュメントは、YAML フロントマターを含む標準テンプレートから生成されます
- ドキュメント専用：コードの生成や実行は行わず、既存の実行ワークフローへスムーズに引き継ぎます
- 仕様タイプへの特化：プロファイルを介して、ドメイン固有の詳細度に合わせてテンプレートを仕様タイプ（service/api/library/platform）に適応させます
- 反復的な品質向上：フェーズ 6.5 の自動修正ループで、レディネスチェックで見つかった問題を修正します（最大 2 回）
- 用語の一貫性：フェーズ 2 で glossary.json を生成し、以降のすべてのフェーズに適用します
必須の前提条件
省略しないでください：操作を行う前に、以下のドキュメントをすべて読み終えている必要があります。仕様書を読まずに進めると、品質基準を満たさない成果物が生成されます。
仕様書（必読）
テンプレートファイル（生成前に必読）
実行フロー
Input Parsing:
|- Parse $ARGUMENTS: extract idea/topic, flags (-y, -c, -m)
|- Detect mode: new | continue
|- If continue: read spec-config.json, resume from first incomplete phase
|- If new: proceed to Phase 1
Phase 1: Discovery & Seed Analysis
|- Ref: phases/01-discovery.md
|- Generate session ID: SPEC-{slug}-{YYYY-MM-DD}
|- Parse input (text or file reference)
|- Gemini CLI seed analysis (problem, users, domain, dimensions)
|- Codebase exploration (conditional, if project detected)
|- Spec type selection: service|api|library|platform (interactive, -y defaults to service)
|- User confirmation (interactive, -y skips)
|- Output: spec-config.json, discovery-context.json (optional)
Phase 1.5: Requirement Expansion & Clarification
|- Ref: phases/01-5-requirement-clarification.md
|- CLI gap analysis: completeness scoring, missing dimensions detection
|- Multi-round interactive discussion (max 5 rounds)
| |- Round 1: present gap analysis + expansion suggestions
| |- Round N: follow-up refinement based on user responses
|- User final confirmation of requirements
|- Auto mode (-y): CLI auto-expansion without interaction
|- Output: refined-requirements.json
Phase 2: Product Brief
|- Ref: phases/02-product-brief.md
|- 3 parallel CLI analyses: Product (Gemini) + Technical (Codex) + User (Claude)
|- Synthesize perspectives: convergent themes + conflicts
|- Generate glossary.json (terminology from product brief + CLI analysis)
|- Interactive refinement (-y skips)
|- Output: product-brief.md (from template), glossary.json
Phase 3: Requirements / PRD
|- Ref: phases/03-requirements.md
|- Gemini CLI: expand goals into functional + non-functional requirements
|- Generate acceptance criteria per requirement
|- RFC 2119 behavioral constraints (MUST/SHOULD/MAY)
|- Core entity data model definitions
|- Glossary injection for terminology consistency
|- User priority sorting: MoSCoW (interactive, -y auto-assigns)
|- Output: requirements/ directory (_index.md + REQ-*.md + NFR-*.md, from template)
Phase 4: Architecture
|- Ref: phases/04-architecture.md
|- Gemini CLI: core components, tech stack, ADRs
|- Codebase integration mapping (conditional)
|- State machine generation (ASCII diagrams for lifecycle entities)
|- Configuration model definition (fields, types, defaults, constraints)
|- Error handling strategy (per-component classification + recovery)
|- Observability specification (metrics, logs, health checks)
|- Spec type profile injection (templates/profiles/{type}-profile.md)
|- Glossary injection for terminology consistency
|- Codex CLI: architecture challenge + review
|- Interactive ADR decisions (-y auto-accepts)
|- Output: architecture/ directory (_index.md + ADR-*.md, from template)
Phase 5: Epics & Stories
|- Ref: phases/05-epics-stories.md
|- Gemini CLI: requirement grouping into Epics, MVP subset tagging
|- Story generation: As a...I want...So that...
|- Dependency mapping (Mermaid)
|- Interactive validation (-y skips)
|- Output: epics/ directory (_index.md + EPIC-*.md, from template)
Phase 6: Readiness Check
|- Ref: phases/06-readiness-check.md
|- Cross-document validation (completeness, consistency, traceability)
|- Quality scoring per dimension
|- Terminology consistency validation (glossary compliance)
|- Scope containment validation (PRD <= Brief scope)
|- Output: readiness-report.md, spec-summary.md
|- Handoff options: lite-plan, req-plan, plan, issue:new, export only, iterate
Phase 6.5: Auto-Fix (conditional, triggered when Phase 6 score < 60%)
|- Ref: phases/06-5-auto-fix.md
|- Parse readiness-report.md for Error/Warning items
|- Group issues by originating Phase (2-5)
|- Re-generate affected sections via CLI with error context
|- Re-run Phase 6 validation
|- Max 2 iterations, then force handoff
|- Output: Updated Phase 2-5 documents
Complete: Full specification package ready for execution
Phase 6 → Handoff Bridge (conditional, based on user selection):
├─ lite-plan: Extract first MVP Epic description → direct text input
├─ plan / req-plan: Create WFS session + .brainstorming/ bridge files
│ ├─ guidance-specification.md (synthesized from spec outputs)
│ ├─ feature-specs/feature-index.json (Epic → Feature mapping)
│ └─ feature-specs/F-{num}-{slug}.md (one per Epic)
├─ issue:new: Create issues per Epic
└─ context-search-agent auto-discovers .brainstorming/
→ context-package.json.brainstorm_artifacts populated
→ action-planning-agent consumes: guidance_spec (P1) → feature_index (P2)
ディレクトリの設定
// Session ID generation
const slug = topic.toLowerCase().replace(/[^a-z0-9\u4e00-\u9fff]+/g, '-').slice(0, 40);
const date = new Date().toISOString().slice(0, 10);
const sessionId = `SPEC-${slug}-${date}`;
const workDir = `.workflow/.spec/${sessionId}`;
Bash(`mkdir -p "${workDir}"`);
出力構成
.workflow/.spec/SPEC-{slug}-{YYYY-MM-DD}/
├── spec-config.json # Session configuration + phase state
├── discovery-context.json # Codebase exploration results (optional)
├── refined-requirements.json # Phase 1.5: Confirmed requirements after discussion
├── glossary.json # Phase 2: Terminology glossary for cross-doc consistency
├── product-brief.md # Phase 2: Product brief
├── requirements/ # Phase 3: Detailed PRD (directory)
│ ├── _index.md # Summary, MoSCoW table, traceability, links
│ ├── REQ-NNN-{slug}.md # Individual functional requirement
│ └── NFR-{type}-NNN-{slug}.md # Individual non-functional requirement
├── architecture/ # Phase 4: Architecture decisions (directory)
│ ├── _index.md # Overview, components, tech stack, links
│ └── ADR-NNN-{slug}.md # Individual Architecture Decision Record
├── epics/ # Phase 5: Epic/Story breakdown (directory)
│ ├── _index.md # Epic table, dependency map, MVP scope
│ └── EPIC-NNN-{slug}.md # Individual Epic with Stories
├── readiness-report.md # Phase 6: Quality report
└── spec-summary.md # Phase 6: One-page executive summary
状態管理
spec-config.json はコア状態ファイルです。
{
"session_id": "SPEC-xxx-2026-02-11",
"seed_input": "User input text",
"input_type": "text",
"timestamp": "ISO8601",
"mode": "interactive",
"complexity": "moderate",
"depth": "standard",
"focus_areas": [],
"spec_type": "service",
"iteration_count": 0,
"iteration_history": [],
"seed_analysis": {
"problem_statement": "...",
"target_users": [],
"domain": "...",
"constraints": [],
"dimensions": []
},
"has_codebase": false,
"refined_requirements_file": "refined-requirements.json",
"phasesCompleted": [
{ "phase": 1, "name": "discovery", "output_file": "spec-config.json", "completed_at": "ISO8601" },
{ "phase": 1.5, "name": "requirement-clarification", "output_file": "refined-requirements.json", "discussion_rounds": 2, "completed_at": "ISO8601" },
{ "phase": 3, "name": "requirements", "output_dir": "requirements/", "output_index": "requirements/_index.md", "file_count": 8, "completed_at": "ISO8601" }
]
}
再開の仕組み：-c|--continue フラグを指定すると、spec-config.json.phasesCompleted を読み込み、最初の未完了フェーズから再開します。
コアルール
- すぐに開始：最初に TaskCreate の初期化を行い、続いてフェーズ 0（仕様調査）、その後フェーズ 1 を実行します
- フェーズごとに読み込み：各フェーズの実行直前にのみ、そのフェーズのドキュメントを読み込みます
- 自動継続：すべてのフェーズを自律的に実行します。TaskList を確認して、次の未完了フェーズを実行します
- すべての出力を解析：各フェーズから必要なデータを抽出し、次のフェーズのコンテキストに渡します
- 停止しない：すべてのフェーズが完了するか、ユーザーが終了するまで、6 フェーズのパイプラインを継続します
- -y フラグに従う：自動モードでは、AskUserQuestion の呼び出しをすべてスキップし、推奨されるデフォルト値を使用します
- -c フラグに従う：続行モードでは、spec-config.json を読み込み、チェックポイントから再開します
- 用語集を適用：フェーズ 3 以降では、glossary.json の用語をすべての CLI プロンプトに適用します
- プロファイルを読み込む：templates/profiles/{spec_type}-profile.md を読み込み、その要件をフェーズ 2～5 のプロンプトに適用します
- 失敗時に反復：フェーズ 6 のスコアが 60% 未満の場合、フェーズ 6.5 を自動的に開始します（最大 2 回）
フェーズごとの参照ドキュメント
フェーズ 1：調査
フェーズ 1.5：要件の拡張と明確化
フェーズ 2：プロダクトブリーフ
フェーズ 3：要件
フェーズ 4：アーキテクチャ
フェーズ 5：エピックとストーリー
フェーズ 6：準備状況の確認
フェーズ 6.5：自動修正
デバッグとトラブルシューティング
エラー処理
| フェーズ | エラー | ブロッキング？ | アクション |
|---|
| フェーズ 1 | 入力が空 | はい | エラーを出して終了 |
| フェーズ 1 | CLI のシード分析に失敗 | いいえ | 基本的な解析によるフォールバックを使用 |
| フェーズ 1.5 | ギャップ分析 CLI に失敗 | いいえ | 基本的なプロンプトでユーザーへの質問に進む |
| フェーズ 1.5 | ユーザーがディスカッションをスキップ | いいえ | seed_analysis をそのまま使用して進む |
| フェーズ 1.5 | 最大ラウンド数に到達（5） | いいえ | 現在の状態で確認を強制する |
| フェーズ 2 | CLI の視点の一つで失敗 | いいえ | 利用可能な視点で続行 |
| フェーズ 2 | すべての CLI 呼び出しに失敗 | いいえ | シード分析から基本的なブリーフを生成 |
| フェーズ 3 | Gemini CLI に失敗 | いいえ | codex のフォールバックを使用 |
| フェーズ 4 | アーキテクチャレビューに失敗 | いいえ | レビューをスキップし、初期分析に基づいて進む |
| フェーズ 5 | ストーリー生成に失敗 | いいえ | 詳細なストーリーなしでエピックを生成 |
| フェーズ 6 | 検証 CLI に失敗 | いいえ | 利用可能なデータで部分的なレポートを生成 |
| フェーズ 6.5 | 自動修正 CLI に失敗 | いいえ | 失敗を記録し、ステータスを Review として引き継ぎに進む |
| フェーズ 6.5 | 最大反復回数に到達 | いいえ | 引き継ぎを強制し、残りの問題を報告する |
CLI フォールバックチェーン
Gemini -> Codex -> Claude -> 劣化モード（ローカル分析のみ）
