规格生成器
结构化规格文档生成器，通过 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 frontmatter 的标准模板生成
- 纯文档流程：不生成代码或执行任务——干净地交接给现有执行工作流
- 规格类型专用化：模板通过配置文件适配规格类型（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 -> 降级模式（仅限本地分析）
