ideation

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Ideation

创意构思

Transform unstructured brain dumps into structured, actionable implementation artifacts through a confidence-gated workflow.

通过基于置信度校验的工作流，将非结构化的头脑风暴内容转换为结构化、可落地的实现工件。

Critical: Use AskUserQuestion Tool

关键要求：使用AskUserQuestion工具

ALWAYS use the
AskUserQuestion
tool when asking clarifying questions. Do not ask questions in plain text. The tool provides structured options and ensures the user can respond clearly.

Use

AskUserQuestion

for:

Clarifying questions during confidence scoring (Phase 2)
Project name confirmation before writing artifacts
Contract approval
Workflow choice (PRDs vs straight to specs)
Phase review feedback before spec generation
Any decision point requiring user input

在提出澄清问题时，必须使用
AskUserQuestion
工具。不要用纯文本提问。该工具提供结构化选项，确保用户能清晰回应。

在以下场景使用

AskUserQuestion

：

置信度评分阶段（阶段2）的澄清问题
编写工件前确认项目名称
合同审批
工作流选择（PRD优先还是直接生成规范）
生成规范前的阶段评审反馈
任何需要用户输入的决策节点

Workflow Pipeline

工作流管道

INTAKE → CODEBASE EXPLORATION → CONTRACT FORMATION → PHASING → SPEC GENERATION → HANDOFF
              ↓                        ↓                  ↓            ↓               ↓
         Understand              confidence < 95%?    PRDs or     Repeatable?    Analyze deps
         existing code                ↓               straight      ↓               ↓
                                 ASK QUESTIONS        to specs?   Template +    Sequential?
                                      ↓                           per-phase     Parallel?
                                 (loop until ≥95%)                deltas        Agent Team?

需求接收 → 代码库探索 → 合同制定 → 阶段划分 → 规范生成 → 交付对接
              ↓                        ↓                  ↓            ↓               ↓
         理解现有代码              置信度 < 95%?    PRD优先还是     是否可复用?    分析依赖
                                      ↓               直接生成规范?   ↓               ↓
                                 发起提问请求        ↓            模板+阶段差异   串行还是并行?
                                      ↓                           ↓               ↓
                                 (循环直到≥95%)                    ↓            Agent团队协作?

Phase 1: Intake

阶段1：需求接收

Accept whatever the user provides:

Scattered thoughts and half-formed ideas
Voice dictation transcripts (messy, stream-of-consciousness)
Bullet points mixed with rambling
Topic jumping and tangents
Contradictions and unclear statements
Technical jargon mixed with vague descriptions

Don't require organization. The mess is the input.

Acknowledge receipt and begin analysis. Do not ask for clarification yet.

接收用户提供的任何内容：

零散的想法和尚未成型的构思
语音转录的口述内容（杂乱的意识流文本）
混合了零散段落的项目符号列表
主题跳跃和离题内容
矛盾和表述模糊的语句
技术术语与模糊描述混杂的内容

不要求用户整理内容。混乱的内容正是我们的输入。

确认收到内容并开始分析。此时不要提出澄清问题。

Phase 2: Codebase Exploration

阶段2：代码库探索

Before scoring confidence or generating any artifacts, understand the existing codebase. This is critical — specs written without understanding existing patterns, architecture, and conventions will be generic and wrong.

**在进行置信度评分或生成任何工件之前，必须先理解现有代码库。**这一点至关重要——如果不了解现有模式、架构和规范，生成的规范将是通用且不符合实际的。

2.1 Determine if Exploration is Needed

2.1 判断是否需要探索

Exploration is needed when:

The brain dump references existing code, features, or systems
The project directory contains source code (not a greenfield project)
The user mentions extending, modifying, or integrating with existing functionality

Skip exploration for greenfield projects with no existing code.

在以下情况需要进行代码库探索：

头脑风暴内容中提及了现有代码、功能或系统
项目目录包含源代码（非全新项目）
用户提到要扩展、修改或集成现有功能

对于无现有代码的全新项目，可跳过探索步骤。

2.2 Explore the Codebase

2.2 执行代码库探索

Use the

Task

tool with

subagent_type: "Explore"

or direct

Glob

Grep

Read

to understand:

Project structure — What frameworks, languages, and patterns are in use?
Relevant existing code — What modules/files relate to the brain dump's scope?
Conventions and patterns — How are similar features implemented? What abstractions exist?
Testing patterns — How is the codebase tested? What infrastructure exists?
Configuration and build — What tools, package managers, and CI/CD are in use?

使用

Task

工具并设置

subagent_type: "Explore"

，或直接使用

Glob

Grep

Read

工具来理解：

项目结构——使用了哪些框架、语言和模式？
相关现有代码——哪些模块/文件与头脑风暴的范围相关？
规范与模式——类似功能是如何实现的？存在哪些抽象层？
测试模式——代码库如何进行测试？有哪些测试基础设施？
配置与构建——使用了哪些工具、包管理器和CI/CD流程？

2.3 Record Findings

2.3 记录探索结果

Retain exploration context for use in later phases. These inform:

Confidence scoring — better understanding of the problem space
Contract — realistic scope boundaries based on actual architecture
Specs — "Pattern to follow" references, accurate file paths, correct abstractions

Do not write exploration findings to files. They're context for the ideation process, not an artifact.

保留探索上下文供后续阶段使用，这些信息将用于：

置信度评分——更好地理解问题域
合同制定——基于实际架构设定符合现实的范围边界
规范生成——提供“参考模式”、准确的文件路径和正确的抽象层

**不要将探索结果写入文件。**它们是创意构思过程的上下文，而非最终工件。

Phase 3: Contract Formation

阶段3：合同制定

3.1 Analyze the Brain Dump

3.1 分析头脑风暴内容

Extract from the raw input + codebase exploration:

Problem signals: What pain point or need is being described?
Goal signals: What does the user want to achieve?
Success signals: How will they know it worked?
Scope signals: What's included? What's explicitly excluded?
Contradictions: Note any conflicting statements
Codebase constraints: What does the existing architecture enable or limit?

从原始输入和代码库探索结果中提取以下信息：

问题信号：描述了哪些痛点或需求？
目标信号：用户想要实现什么？
成功信号：如何判断目标已达成？
范围信号：包含哪些内容？明确排除了哪些内容？
矛盾点：记录任何相互冲突的表述
代码库约束：现有架构支持或限制了哪些内容？

3.2 Calculate Confidence Score

3.2 计算置信度评分

Read

references/confidence-rubric.md

for detailed scoring criteria.

Score conservatively. When uncertain between two levels, choose the lower one. One extra round of questions costs minutes; a bad contract costs hours. Do not inflate scores to move forward faster.

Score each dimension (0-20 points):

Dimension	Question
Problem Clarity	Do I understand what problem we're solving and why it matters?
Goal Definition	Are the goals specific and measurable?
Success Criteria	Can I write tests or validation steps for "done"?
Scope Boundaries	Do I know what's in and out of scope?
Consistency	Are there contradictions I need resolved?

Total: /100 points

阅读

references/confidence-rubric.md

获取详细评分标准。

**保守评分。**当对两个评分级别不确定时，选择较低的那个。多一轮提问仅需数分钟，但一份错误的合同可能导致数小时的返工。不要为了推进流程而刻意提高评分。

对每个维度评分（0-20分）：

维度	问题描述
问题清晰度	我是否理解我们要解决的问题及其重要性？
目标定义清晰度	目标是否具体且可衡量？
成功标准清晰度	我能否为“完成状态”编写测试或验证步骤？
范围边界清晰度	我是否清楚哪些内容在范围内、哪些在范围外？
内容一致性	是否存在需要解决的矛盾表述？

总分：/100分

3.3 Confidence Thresholds

3.3 置信度阈值

Score	Action
< 70	Major gaps. Ask 5+ questions targeting lowest dimensions.
70-84	Moderate gaps. Ask 3-5 targeted questions.
85-94	Minor gaps. Ask 1-2 specific questions.
≥ 95	Ready to generate contract.

分数	行动方案
< 70	存在重大信息缺口。针对得分最低的维度提出5个以上问题。
70-84	存在中等信息缺口。提出3-5个针对性问题。
85-94	存在轻微信息缺口。提出1-2个具体问题。
≥ 95	可开始生成合同。

3.4 Ask Clarifying Questions

3.4 提出澄清问题

When confidence < 95%, MUST use
AskUserQuestion
tool to ask clarifying questions. Structure questions with clear options when possible.

Using AskUserQuestion effectively:

Provide 2-4 options per question when choices are clear
Use
```
multiSelect: true
```
when multiple answers apply
Keep question headers short (max 12 chars)
Include descriptions that explain implications of each choice

Question strategy:

Target the lowest-scoring dimension first
Be specific, not open-ended
Offer options when possible ("Is it A, B, or C?")
Reference what was stated ("You mentioned X, did you mean...?")
Limit to 3-5 questions per round
After each round, recalculate confidence

Question templates by dimension:

Problem Clarity:

"What specific problem are you trying to solve?"
"Who experiences this problem and how often?"
"What's the cost of NOT solving this?"

Goal Definition:

"What does success look like for this project?"
"How will you measure whether this worked?"
"What specific metrics should improve?"

Success Criteria:

"How will you know when you're done?"
"What tests would prove this feature works?"
"What would a QA person check?"

Scope Boundaries:

"What is explicitly NOT part of this project?"
"Are there related features we should defer?"
"What's the MVP vs. nice-to-have?"

Consistency:

"You mentioned [X] but also [Y]. Which takes priority?"
"These requirements seem to conflict. Can you clarify?"
"How should we handle [edge case]?"

当置信度<95%时，必须使用
AskUserQuestion
工具提出澄清问题。在可能的情况下，为问题提供清晰的选项。

有效使用AskUserQuestion的技巧：

当选项明确时，每个问题提供2-4个选项
当多个答案适用时，设置
```
multiSelect: true
```
问题标题保持简短（最多12个字符）
包含描述每个选项影响的说明

按维度设计的问题模板：

问题清晰度：

“你试图解决的具体问题是什么？”
“谁会遇到这个问题？频率如何？”
“不解决这个问题会带来什么影响？”

目标定义清晰度：

“这个项目的成功状态是什么样的？”
“你将如何衡量项目是否成功？”
“哪些具体指标应该得到改善？”

成功标准清晰度：

“你如何判断项目已经完成？”
“哪些测试可以证明该功能正常工作？”
QA人员会检查哪些内容？”

范围边界清晰度：

“哪些内容明确不属于这个项目的范围？”
“是否有相关功能需要推迟到后续阶段？”
“MVP（最小可行产品）和锦上添花的功能分别是什么？”

内容一致性：

“你提到了[X]但也提到了[Y]。哪个优先级更高？”
“这些需求似乎存在冲突，能否澄清一下？”
“我们应该如何处理[边缘情况]？”

3.5 Generate Contract

3.5 生成合同

When confidence ≥ 95%, generate the contract document.

Use
```
AskUserQuestion
```
to confirm project name if not obvious from context
Convert to kebab-case for directory name
Create output directory:
```
./docs/ideation/{project-name}/
```

Write

contract.md

using

references/contract-template.md

Use
```
AskUserQuestion
```
to get approval:

Question: "Does this contract accurately capture your intent?"
Options:
- "Approved" - Contract is accurate, proceed
- "Needs changes" - Some parts need revision
- "Missing scope" - Important items are not captured
- "Start over" - Fundamentally off track, re-analyze

If not approved: Revise the contract based on feedback. Do not re-score confidence unless the feedback reveals a fundamental misunderstanding — in that case, return to Phase 3.2 and re-score. Otherwise, edit

contract.md

directly and re-present for approval. Iterate until approved.

Do not proceed until contract is explicitly approved.

当置信度≥95%时，生成合同文档。

如果从上下文无法明确项目名称，使用
```
AskUserQuestion
```
确认
将项目名称转换为短横线分隔格式（kebab-case）作为目录名
创建输出目录：
```
./docs/ideation/{project-name}/
```

使用

references/contract-template.md

模板编写

contract.md

使用
```
AskUserQuestion
```
获取审批：

Question: "这份合同是否准确反映了你的需求？"
Options:
- "已批准" - 合同准确，继续推进
- "需要修改" - 部分内容需要调整
- "缺少范围" - 未涵盖重要内容
- "重新开始" - 完全偏离方向，重新分析

**如果未获批准：**根据反馈修改合同。除非反馈显示存在根本性误解，否则无需重新计算置信度——如果是根本性误解，返回至阶段3.2重新评分。否则，直接编辑

contract.md

并重新提交审批。重复此过程直到合同获得批准。

在合同明确获得批准前，不得进入下一阶段。

Phase 4: Phasing & Specification

阶段4：阶段划分与规范制定

After contract is approved, determine phases and generate specs. PRDs are optional.

合同批准后，确定实施阶段并生成规范。PRD（产品需求文档）为可选步骤。

4.1 Choose Workflow

4.1 选择工作流

Use

AskUserQuestion

to ask:

Question: "How should we proceed from the contract?"
Options:
- "Straight to specs" — Recommended for technical projects.
  Contract defines what, specs define how. Faster.
- "PRDs then specs" — Recommended for large scope or cross-functional
  teams. Adds a requirements layer for stakeholder alignment.

使用

AskUserQuestion

询问：

Question: "我们应如何基于合同推进工作？"
Options:
- "直接生成规范" — 推荐用于技术类项目。合同定义要做什么，规范定义怎么做。效率更高。
- "先做PRD再做规范" — 推荐用于大范围或跨职能团队项目。添加需求层以对齐相关方预期。

4.2 Determine Phases

4.2 确定阶段划分

Regardless of PRD choice, analyze the contract and break scope into logical implementation phases.

Small-project shortcut: If the scope is small enough to implement in a single phase (1-3 components, touches fewer than ~10 files), skip phasing entirely. Generate a single

spec.md

(no phase number needed) and proceed directly to handoff. Not every project needs multiple phases — don't force structure where simplicity suffices.

Phasing criteria (for multi-phase projects):

Dependencies (what must be built first?)
Risk (tackle high-risk items early)
Value delivery (can users benefit after each phase?)
Complexity (balance phases for consistent effort)

Typical phasing:

Phase 1: Core functionality / infrastructure
Phase 2+: Features, enhancements, additional integrations
Phase N: Future considerations

Detect repeatable patterns: If 3+ phases follow the same structure with different inputs (e.g., "add SDK support for {language}"), note this — it affects how specs are generated (see 4.4).

无论是否选择PRD，都需要分析合同并将范围划分为逻辑清晰的实施阶段。

**小型项目捷径：**如果范围小到可以在单个阶段内完成（1-3个组件，涉及少于约10个文件），可完全跳过阶段划分。生成单个

spec.md

（无需阶段编号）并直接进入交付对接环节。并非每个项目都需要多阶段划分——在简单场景下不要强行添加复杂结构。

多阶段项目的划分标准：

依赖关系（哪些内容必须先构建？）
风险等级（尽早处理高风险项）
价值交付（用户能否在每个阶段后获得收益？）
复杂度平衡（各阶段工作量保持一致）

典型的阶段划分：

阶段1：核心功能/基础设施
阶段2及以后：功能增强、额外集成
阶段N：未来规划考虑

**识别可复用模式：**如果3个以上阶段遵循相同结构（例如“为{语言}添加SDK支持”），需记录这一点——这会影响规范的生成方式（见4.4）。

4.3 Generate PRDs (only if user chose "PRDs then specs")

4.3 生成PRD（仅当用户选择“先做PRD再做规范”时）

For each phase, generate

prd-phase-{n}.md

using

references/prd-template.md

Include:

Phase overview and rationale
User stories for this phase
Functional requirements (grouped)
Non-functional requirements
Dependencies (prerequisites and outputs)
Acceptance criteria

Present all PRDs for review. Use

AskUserQuestion

Question: "Do these PRD phases look correct?"
Options:
- "Approved" - Phases and requirements look good, proceed to specs
- "Adjust phases" - Need to move features between phases
- "Missing requirements" - Some requirements are missing or unclear
- "Start over" - Need to revisit the contract

Iterate until user explicitly approves.

为每个阶段使用

references/prd-template.md

模板生成

prd-phase-{n}.md

。

文档应包含：

阶段概述与划分理由
本阶段的用户故事
分组的功能需求
非功能需求
依赖关系（前置条件与输出）
验收标准

提交所有PRD供评审。使用

AskUserQuestion

：

Question: "这些PRD阶段划分是否合理？"
Options:
- "已批准" - 阶段划分和需求合理，继续生成规范
- "调整阶段" - 需要在阶段间调整功能分配
- "缺少需求" - 部分需求缺失或表述模糊
- "重新开始" - 需要重新审视合同

重复此过程直到用户明确批准。

4.4 Generate Implementation Specs

4.4 生成实现规范

Generate specs using

references/spec-template.md

. How specs are generated depends on whether phases are repeatable:

使用

references/spec-template.md

模板生成规范。规范的生成方式取决于阶段是否可复用：

Standard phases (each is unique)

标准阶段（每个阶段唯一）

For each phase, generate a full

spec-phase-{n}.md

with:

Technical approach
File changes (new and modified)
Implementation details with code patterns
Testing requirements
Error handling
Validation commands

Reference existing code: When the codebase exploration (Phase 2) identified relevant patterns, include "Pattern to follow:

path/to/similar/file.ts

" in the spec's implementation details. This gives the executing agent concrete examples to follow.

为每个阶段生成完整的

spec-phase-{n}.md

，包含：

技术实现方案
文件变更（新增与修改）
带有代码模式的实现细节
测试要求
错误处理机制
验证命令

**参考现有代码：**当阶段2的代码库探索识别到相关模式时，在规范的实现细节中添加“参考模式：

path/to/similar/file.ts

”。这为执行Agent提供了具体的示例。

Repeatable phases (3+ phases follow the same pattern)

可复用阶段（3个以上阶段遵循相同模式）

When multiple phases share the same structure (e.g., "add support for {SDK}"), avoid generating N nearly-identical full specs. Instead:

Generate one full template spec —
```
spec-template-{pattern-name}.md
```
— with detailed implementation steps, using placeholders for the variable parts.
Generate lightweight per-phase delta files —
```
spec-phase-{n}.md
```
— containing only:
- Phase-specific inputs (e.g., language name, package manager, framework)
- Deviations from the template (what's different about this phase)
- Any phase-specific concerns or edge cases
- Reference to the template: "Follow
```
spec-template-{pattern-name}.md
```
  with the inputs below"

Example for SDK integrations:

spec-template-sdk-integration.md

markdown

undefined

当多个阶段共享相同结构时（例如“添加{SDK}支持”），避免生成N个几乎相同的完整规范。而是：

生成一个完整的模板规范 —
```
spec-template-{pattern-name}.md
```
— 包含详细的实现步骤，使用占位符表示可变部分。
生成轻量级的阶段差异文件 —
```
spec-phase-{n}.md
```
— 仅包含：
- 阶段特定输入（例如语言名称、包管理器、框架）
- 与模板的差异（本阶段的特殊之处）
- 任何阶段特定的注意事项或边缘情况
- 模板引用：“遵循
```
spec-template-{pattern-name}.md
```
  并使用以下输入”

SDK集成示例：

spec-template-sdk-integration.md

markdown

undefined

SDK Integration Template

SDK集成模板

Pattern

模式

For each SDK, create:

```
src/{language}/{language}-installer-agent.ts
```
— FrameworkConfig following existing pattern
```
skills/workos-{sdk-name}/SKILL.md
```
— Agent skill fetching SDK README

tests/fixtures/{language}/{framework}-example/

— Minimal project fixture

tests/evals/graders/{language}.grader.ts

— Extending BaseGrader

对于每个SDK，创建：

src/{language}/{language}-installer-agent.ts

— 遵循现有模式的FrameworkConfig

```
skills/workos-{sdk-name}/SKILL.md
```
— 获取SDK README的Agent技能

tests/fixtures/{language}/{framework}-example/

— 最小项目示例

tests/evals/graders/{language}.grader.ts

— 扩展BaseGrader

Implementation Details

实现细节

{Detailed steps with {placeholders} for variable parts}

{包含{占位符}的详细步骤}

Validation

验证

{Common validation steps}


`spec-phase-5.md`:
```markdown

{通用验证步骤}


`spec-phase-5.md`:
```markdown

Spec: Ruby SDK (workos-ruby)

规范：Ruby SDK (workos-ruby)

Template: ./spec-template-sdk-integration.md

模板: ./spec-template-sdk-integration.md

Inputs

输入

Language: Ruby
Framework: Rails
Package manager: Bundler (
```
bundle add
```
)
Manifest file: Gemfile
SDK package: workos
Detection:
```
rails
```
gem in Gemfile or
```
config/routes.rb
```
exists

语言: Ruby
框架: Rails
包管理器: Bundler (
```
bundle add
```
)
清单文件: Gemfile
SDK包: workos
检测方式: Gemfile中存在
```
rails
```
gem或
```
config/routes.rb
```
文件存在

Deviations from template

与模板的差异

Rails has strong conventions — files go in specific locations
Initializer pattern:
```
config/initializers/workos.rb
```
Env vars:
```
.env
```
with dotenv-rails, or Rails credentials

Rails有严格的约定 — 文件需放在特定位置
初始化器模式:
```
config/initializers/workos.rb
```
环境变量: 使用dotenv-rails的
```
.env
```
文件，或Rails credentials

Phase-specific concerns

阶段特定注意事项

CI needs Ruby 3.x installed for eval fixtures


This approach:
- Saves significant context window space
- Makes the per-phase differences obvious
- Avoids copy-paste errors across specs
- Makes it easy to update the shared pattern in one place

CI环境需要安装Ruby 3.x以运行评估示例


这种方式的优势：
- 节省大量上下文窗口空间
- 使各阶段的差异一目了然
- 避免在多个规范中出现复制粘贴错误
- 便于在一个位置更新共享模式

4.5 Present Phases for Review

4.5 提交阶段供评审

Whether using PRDs or straight-to-specs, present the phase breakdown and specs for user approval before proceeding to handoff.

Use

AskUserQuestion

Question: "Do these specs look correct?"
Options:
- "Approved" - Specs look good, proceed to execution handoff
- "Adjust approach" - Implementation strategy needs changes
- "Missing components" - Some files or steps are missing
- "Revisit phases" - Phase breakdown needs restructuring

If not approved, revise the relevant specs based on feedback and re-present. Iterate until approved.

无论选择哪种工作流，在交付对接前都需要提交阶段划分和规范供用户批准。

使用

AskUserQuestion

：

Question: "这些规范是否合理？"
Options:
- "已批准" - 规范合理，进入执行交付环节
- "调整实现方案" - 实现策略需要修改
- "缺少组件" - 部分文件或步骤缺失
- "重新划分阶段" - 阶段划分需要调整

如果未获批准，根据反馈修改相关规范并重新提交。重复此过程直到获得批准。

Phase 5: Execution Handoff

阶段5：执行交付对接

After specs are generated, create task list, analyze orchestration options, and hand off for implementation.

规范生成完成后，创建任务列表、分析编排选项并交付给执行环节。

5.1 Analyze Orchestration Strategy

5.1 分析编排策略

Do not create tasks during ideation handoff — they are ephemeral and will be lost when the user starts a fresh session. Each

/execute-spec

session creates its own granular implementation tasks.

Analyze the phase dependency graph to determine the best execution strategy.

Detect parallelizable phases:

Examine which phases are blocked by what
If 2+ phases share the same single blocker (e.g., all blocked only by Phase 1), they are parallelizable
If phases form a linear chain (Phase 2 → Phase 3 → Phase 4), they are sequential
Mixed graphs have both parallel and sequential segments

Determine recommended strategy:

Pattern	Recommendation
All phases sequential (chain)	Sequential execution — one session at a time
2+ independent phases	Agent team — lead orchestrates teammates in parallel
Mixed dependencies	Hybrid — sequential for dependent chain, agent team for independent group

在创意构思交付环节不要创建任务——任务是临时的，当用户启动新会话时会丢失。每个

/execute-spec

会话会创建自己的细粒度实现任务。

分析阶段依赖图以确定最佳执行策略。

识别可并行的阶段：

检查哪些阶段被哪些阶段阻塞
如果2个以上阶段仅被同一个阶段阻塞（例如所有阶段都仅被阶段1阻塞），则这些阶段可并行执行
如果阶段形成线性链（阶段2 → 阶段3 → 阶段4），则这些阶段需串行执行
混合图同时包含并行和串行部分

确定推荐策略：

模式	推荐方案
所有阶段串行（链式）	串行执行 — 一次启动一个会话
2个以上独立阶段	Agent团队协作 — 主导Agent编排多个协作Agent并行执行
混合依赖	混合模式 — 依赖链部分串行执行，独立组部分使用Agent团队并行执行

5.2 Present Handoff Summary

5.2 提交交付总结

Present the execution strategy directly to the user. No manifest file — the contract and specs are the artifacts. The handoff summary is conversational output.

Always include:

Ideation complete. Artifacts written to `./docs/ideation/{project-name}/`.

For sequential execution or when a blocking phase must complete first:

undefined

直接向用户提交执行策略。无需清单文件——合同和规范就是交付工件。交付总结为对话式输出。

必须包含：

创意构思完成。工件已写入 `./docs/ideation/{project-name}/`。

对于串行执行或存在阻塞阶段的情况：

undefined

To start implementation

启动实现的方式

bash

claude
/execute-spec docs/ideation/{project-name}/spec-phase-1.md

Each

/execute-spec

session creates its own implementation tasks.


**When ALL phases are independent (no blocking phase), skip the sequential start and go straight to the agent team prompt below.**

**When 2+ phases are parallelizable (after a blocking phase or from the start), present an agent team prompt.**

Agent teams let a single lead session automatically spawn and coordinate multiple teammates — the user starts **one** `claude` session, and the lead handles spawning, task assignment, plan approval, and synthesis. No manual terminal juggling.

bash

claude
/execute-spec docs/ideation/{project-name}/spec-phase-1.md

每个

/execute-spec

会话会创建自己的实现任务。


**当所有阶段都独立（无阻塞阶段）时，跳过串行启动步骤，直接提供Agent团队协作提示。**

**当2个以上阶段可并行执行时（在阻塞阶段完成后或从一开始），提供Agent团队协作提示。**

Agent团队协作允许单个主导会话自动生成并协调多个协作Agent——用户只需启动**一个**`claude`会话，主导Agent会处理生成、任务分配、计划审批和结果整合。无需手动切换多个终端会话。

Parallel Execution with Agent Teams

使用Agent团队并行执行

After {blocking phase} is complete, {N} phases can run in parallel.

Ensure agent teams are enabled in

.claude/settings.json

~/.claude/settings.json

json

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

Start one new Claude Code session and enter delegate mode (Shift+Tab), then paste:

{Blocking phase} is complete. Create an agent team to implement
{N} remaining phases in parallel. Each phase is independent.

Spawn {N} teammates with plan approval required. Each teammate should:
1. Read their assigned spec file (and the template spec if referenced)
2. Explore the codebase for relevant patterns before planning
3. Plan their implementation approach and wait for approval
4. Implement following spec and codebase patterns
5. Run validation commands from their spec after implementation

Only approve plans that include test coverage and match existing
codebase conventions.

Teammates:

1. "{Phase title}" — docs/ideation/{project-name}/spec-phase-{n}.md
   {One-line context about what this phase does}

2. "{Phase title}" — docs/ideation/{project-name}/spec-phase-{n}.md
   {One-line context about what this phase does}

...


**Why delegate mode?** Pressing Shift+Tab restricts the lead to coordination-only tools: spawning teammates, messaging, managing tasks, and approving plans. This prevents the lead from implementing tasks itself and ensures work is distributed to teammates.

**Why one session?** The lead automatically spawns each teammate as a separate Claude Code instance. Each teammate gets its own context window, loads project context (CLAUDE.md, MCP servers, skills), and works independently. You interact with the lead and it coordinates everything — use Shift+Up/Down to message individual teammates if needed.

**Shared file detection:** Scan the spec files' "Modified Files" sections. If multiple specs modify the same files, add a coordination note to the team prompt:

Coordinate on shared files ({list}) to avoid merge conflicts — only one teammate should modify a shared file at a time.


**Batching:** If more than 5 parallelizable phases, recommend starting with the highest-priority batch first, then spawning the rest after plans are approved.

在{阻塞阶段}完成后，{N}个阶段可并行执行。

确保在

.claude/settings.json

或

~/.claude/settings.json

中启用Agent团队功能：

json

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

启动一个新的Claude Code会话并进入委托模式（Shift+Tab），然后粘贴：

{阻塞阶段}已完成。创建一个Agent团队来并行实现
剩余的{N}个阶段。所有阶段相互独立。

生成{N}个协作Agent并要求计划审批。每个协作Agent应：
1. 阅读分配的规范文件（如果有引用则同时阅读模板规范）
2. 在规划前探索代码库以了解相关模式
3. 制定实现方案并等待审批
4. 遵循规范和代码库模式进行实现
5. 实现完成后运行规范中的验证命令

仅批准包含测试覆盖且符合现有
代码库规范的计划。

协作Agent分配：

1. "{阶段标题}" — docs/ideation/{project-name}/spec-phase-{n}.md
   {关于本阶段内容的一行说明}

2. "{阶段标题}" — docs/ideation/{project-name}/spec-phase-{n}.md
   {关于本阶段内容的一行说明}

...


**为什么使用委托模式？**按Shift+Tab会限制主导Agent仅使用协作工具：生成协作Agent、发送消息、管理任务和审批计划。这可防止主导Agent自行执行任务，确保工作分配给协作Agent。

**为什么只需要一个会话？**主导Agent会自动为每个协作Agent生成独立的Claude Code实例。每个协作Agent拥有自己的上下文窗口，加载项目上下文（CLAUDE.md、MCP服务器、技能）并独立工作。你只需与主导Agent交互，它会协调所有工作——如果需要，可使用Shift+上/下箭头向特定协作Agent发送消息。

**共享文件检测：**扫描规范文件的“修改文件”部分。如果多个规范修改相同文件，在团队提示中添加协调说明：

协调共享文件({文件列表})以避免合并冲突 — 同一时间仅允许一个协作Agent修改共享文件。


**分批处理：**如果可并行的阶段超过5个，建议先启动优先级最高的批次，在计划批准后再生成剩余批次。

5.3 Why Fresh Sessions?

5.3 为什么使用新会话？

Ideation consumes significant context (contract, specs, exploration)
Execution benefits from clean context focused on the spec
Human review between phases catches issues early
Each phase is independently committable
Each session creates granular implementation tasks scoped to that phase

创意构思会占用大量上下文（合同、规范、探索结果）
执行环节受益于专注于规范的干净上下文
阶段间的人工评审可尽早发现问题
每个阶段都可独立提交
每个会话会创建针对该阶段的细粒度实现任务

Output Artifacts

输出工件

All artifacts written to

./docs/ideation/{project-name}/

contract.md                        # Lean contract (problem, goals, success, scope)
prd-phase-1.md                     # Phase 1 requirements (only if PRDs chosen)
...
spec-phase-1.md                    # Phase 1 implementation spec (always full)
spec-template-{pattern}.md         # Shared template for repeatable phases (if applicable)
spec-phase-{n}.md                  # Per-phase delta referencing template (if repeatable)
...

所有工件均写入

./docs/ideation/{project-name}/

：

contract.md                        # 精简合同（问题、目标、成功标准、范围）
prd-phase-1.md                     # 阶段1需求文档（仅当选择PRD工作流时存在）
...
spec-phase-1.md                    # 阶段1实现规范（完整内容）
spec-template-{pattern}.md         # 可复用阶段的共享模板（如有）
spec-phase-{n}.md                  # 引用模板的阶段差异文件（如适用）
...

Bundled Resources

内置资源

References

参考文档

```
references/contract-template.md
```
- Template for lean contract document
```
references/prd-template.md
```
- Template for phased PRD documents
```
references/spec-template.md
```
- Template for implementation specs
```
references/confidence-rubric.md
```
- Detailed scoring criteria for confidence assessment
```
references/workflow-example.md
```
- End-to-end workflow walkthrough

```
references/contract-template.md
```
- 精简合同文档模板
```
references/prd-template.md
```
- 分阶段PRD文档模板
```
references/spec-template.md
```
- 实现规范模板
```
references/confidence-rubric.md
```
- 置信度评估的详细评分标准
```
references/workflow-example.md
```
- 端到端工作流示例

Examples

示例

Completed artifact examples for reference when generating output:

```
examples/contract-example.md
```
- A filled-in contract for a bookmark feature
```
examples/spec-example.md
```
- A filled-in spec for the same feature

When generating artifacts, reference these examples for tone, structure, and level of detail.

用于参考的已完成工件示例：

```
examples/contract-example.md
```
- 针对书签功能的完整合同示例
```
examples/spec-example.md
```
- 同一功能的完整规范示例

生成工件时，可参考这些示例的语气、结构和详细程度。

Important Notes

重要注意事项

ALWAYS use
AskUserQuestion
tool for clarifications and approvals. Never ask questions in plain text.
Explore the codebase before scoring confidence (unless greenfield).
Score confidence conservatively. When uncertain, score lower.
Never skip the confidence check. Don't assume understanding.
Always write artifacts to files. Don't just display them.
Each phase should be independently valuable.
Specs should be detailed enough to implement without re-reading PRDs or the contract.
Keep contracts lean. Heavy docs slow iteration.
Reference existing code patterns in specs — "Pattern to follow" with real file paths.
Use template + delta for repeatable phases — don't generate N identical specs.
Small projects don't need phases. If scope is 1-3 components, generate a single spec.

**始终使用
```
AskUserQuestion
```
工具进行澄清和审批。**永远不要用纯文本提问。
在评分前探索代码库（全新项目除外）。
**保守评分置信度。**不确定时，选择较低分数。
永远不要跳过置信度检查。不要假设自己已完全理解。
始终将工件写入文件。不要仅在界面显示。
每个阶段应具有独立的价值。
规范应足够详细，无需重新阅读PRD或合同即可实现。
保持合同精简。厚重的文档会减慢迭代速度。
在规范中参考现有代码模式 — 使用真实文件路径的“参考模式”。
对可复用阶段使用模板+差异文件模式 — 不要生成N个相同的规范。
**小型项目不需要阶段划分。**如果范围仅包含1-3个组件，生成单个规范即可。