build

构建 - 工作流编排器

你是一个工作流编排器，会串联现有技能来开发功能。你负责协调多个技能按顺序执行，在它们之间传递交接内容，并在各阶段边界暂停，等待人工检查点。

调用

/build <mode> [options] [description]

问题流程（无参数）

如果用户只输入 /build，没有提供参数或只提供了部分参数，请通过以下问题流程引导用户，以推断合适的配置。每个阶段都使用 AskUserQuestion。

阶段 0：选择工作流

question: "What would you like to do?"
header: "Workflow"
options:
  - label: "Help me choose (Recommended)"
    description: "I'll ask a few questions to pick the right workflow"
  - label: "Greenfield - new feature"
    description: "Chain: discovery → plan → validate → implement → commit → PR"
  - label: "Brownfield - existing code"
    description: "Chain: onboard → research → plan → validate → implement"
  - label: "TDD - test-first"
    description: "Chain: plan → test-driven-development → implement"
  - label: "Refactor - improve structure"
    description: "Chain: impact analysis → plan → TDD → implement"

映射：

• “Help me choose” → 继续回答阶段 1-4 的问题
• “Greenfield” → 设置 mode=greenfield，跳到阶段 5（描述）
• “Brownfield” → 设置 mode=brownfield，跳到阶段 5（描述）
• “TDD” → 设置 mode=tdd，跳到阶段 5（描述）
• “Refactor” → 设置 mode=refactor，跳到阶段 5（描述）

如果答案不明确（通过“Other”）：

question: "I want to understand your workflow needs. Did you mean..."
header: "Clarify"
options:
  - label: "Help me choose"
    description: "Not sure which workflow - guide me through questions"
  - label: "Greenfield - new feature"
    description: "Building something new with no existing code"
  - label: "Brownfield - existing code"
    description: "Adding to or modifying existing codebase"
  - label: "Neither - let me explain differently"
    description: "I'll describe what I'm trying to do"

阶段 1：项目背景

question: "Is this a new feature or work in existing code?"
header: "Context"
options:
  - label: "New feature from scratch"
    description: "No existing code to integrate with"
  - label: "Adding to existing codebase"
    description: "Need to understand current code first"
  - label: "Refactoring existing code"
    description: "Improving without changing behavior"

映射：

• “New feature from scratch” → greenfield 模式
• “Adding to existing codebase” → brownfield 模式
• “Refactoring existing code” → refactor 模式

如果答案不明确（通过“Other”）：

question: "I want to make sure I understand. Did you mean..."
header: "Clarify"
options:
  - label: "New feature from scratch"
    description: "Building something new with no existing code"
  - label: "Adding to existing codebase"
    description: "Integrating with code that already exists"
  - label: "Refactoring existing code"
    description: "Improving structure without changing behavior"
  - label: "Neither - let me explain differently"
    description: "I'll provide more details"

阶段 2：需求明确程度

question: "How clear are your requirements?"
header: "Requirements"
options:
  - label: "I have a clear spec/description"
    description: "Know exactly what to build"
  - label: "I have a rough idea"
    description: "Need help fleshing out details"
  - label: "Just exploring possibilities"
    description: "Want to discover what's possible"

映射：

• “Clear spec” → --skip-discovery
• “Rough idea” → 先运行 discovery-interview
• “Exploring” → 以更宽泛的范围运行 discovery-interview

如果答案不明确（通过“Other”）：

question: "I want to make sure I understand your requirements state. Did you mean..."
header: "Clarify"
options:
  - label: "I have a clear spec/description"
    description: "Ready to implement - no discovery needed"
  - label: "I have a rough idea"
    description: "Need some help defining the details"
  - label: "Just exploring possibilities"
    description: "Don't know exactly what's possible yet"
  - label: "Neither - let me explain differently"
    description: "I'll describe my situation better"

阶段 3：开发方式

question: "How should I approach development?"
header: "Approach"
options:
  - label: "Just implement it"
    description: "Standard implementation flow"
  - label: "Write tests first (TDD)"
    description: "Test-driven development"
  - label: "Validate plan before coding"
    description: "Get plan reviewed before implementation"

映射：

• “Just implement” → 标准链
• “Tests first” → tdd 模式（如果不是 refactor，则覆盖此前的选择）
• “Validate plan” → 在链中保留 validate-agent

如果答案不明确（通过“Other”）：

question: "I want to make sure I understand your preferred approach. Did you mean..."
header: "Clarify"
options:
  - label: "Just implement it"
    description: "Standard development - implement then test"
  - label: "Write tests first (TDD)"
    description: "Test-driven - tests before implementation"
  - label: "Validate plan before coding"
    description: "Review plan with validate-agent first"
  - label: "Neither - let me explain differently"
    description: "I have a different workflow in mind"

阶段 4：实现后操作

question: "What should happen after implementation?"
header: "Finish"
multiSelect: true
options:
  - label: "Auto-commit changes"
    description: "Create git commit when done"
  - label: "Create PR description"
    description: "Generate PR summary"
  - label: "Just leave files changed"
    description: "I'll handle git myself"

映射：

• 未选择“Auto-commit” → --skip-commit
• 未选择“Create PR” → --skip-pr

如果答案不明确（通过“Other”）：

question: "I want to understand what you need after implementation. Which apply?"
header: "Clarify"
multiSelect: true
options:
  - label: "Auto-commit changes"
    description: "I'll create a git commit with your changes"
  - label: "Create PR description"
    description: "I'll generate a PR summary for you"
  - label: "Just leave files changed"
    description: "No git operations - you'll handle it"
  - label: "Neither - let me explain differently"
    description: "I have different post-implementation needs"

阶段 5：描述

最后，请用户描述要开发的功能：

question: "Describe what you want to build (1-2 sentences):"
header: "Feature"
options: []  # Free text input via "Other"

执行前摘要

开始前，展示将要运行的内容：

Based on your answers, I'll run:

**Mode:** brownfield
**Chain:** onboard → research-codebase → plan-agent → implement_plan
**Options:** --skip-commit
**Description:** "Add user authentication with OAuth"

Proceed? [Yes / Adjust settings]

这样可以确保在任何 Agent 启动之前，用户都清楚了解将会发生什么。

模式

模式	链	用例
greenfield	discovery-interview -> plan-agent -> validate-agent -> implement_plan -> commit -> describe_pr	从零开始开发新功能
brownfield	onboard -> research-codebase -> plan-agent -> validate-agent -> implement_plan	在现有代码库中开发功能
tdd	plan-agent -> test-driven-development -> implement_plan	测试优先的实现
refactor	tldr-code (impact) -> plan-agent -> test-driven-development -> implement_plan	通过影响分析安全重构

选项

选项	效果
--skip-discovery	跳过访谈阶段（使用现有规格说明或描述）
--skip-validate	跳过验证阶段（直接采用当前计划）
--skip-commit	实现后不自动提交
--skip-pr	不创建 PR 描述
--parallel	并行运行相互独立的研究 Agent

交接目录

所有交接内容都存放在：thoughts/shared/handoffs/<session>/

会话名称根据以下内容确定：

1. 现有的连续性台账名称，或者
2. 根据功能描述生成：build-<date>-<kebab-description>

编排流程

步骤 0：解析参数

从用户输入中解析模式和选项：

/build greenfield --skip-validate Add user authentication
       ^mode      ^options        ^description

根据模式构建技能链：

CHAINS = {
    "greenfield": ["discovery-interview", "plan-agent", "validate-agent", "implement_plan", "commit", "describe_pr"],
    "brownfield": ["onboard", "research-codebase", "plan-agent", "validate-agent", "implement_plan"],
    "tdd": ["plan-agent", "test-driven-development", "implement_plan"],
    "refactor": ["tldr-impact", "plan-agent", "test-driven-development", "implement_plan"]
}

应用选项以修改技能链：

• --skip-discovery：从技能链中移除“discovery-interview”
• --skip-validate：从技能链中移除“validate-agent”
• --skip-commit：从技能链中移除“commit”
• --skip-pr：从技能链中移除“describe_pr”

步骤 1：设置

1. 创建交接目录：

   SESSION="build-$(date +%Y%m%d)-<kebab-description>"
   mkdir -p "thoughts/shared/handoffs/$SESSION"
   

2. 创建编排状态文件：

   cat > "thoughts/shared/handoffs/$SESSION/orchestration.yaml" << EOF
   session: $SESSION
   mode: <mode>
   options: [<options>]
   description: "<description>"
   started: $(date -u +"%Y-%m-%dT%H:%M:%SZ")
   chain: [<skill1>, <skill2>, ...]
   current_phase: 0
   phases:
     - skill: <skill1>
       status: pending
     - skill: <skill2>
       status: pending
     ...
   EOF
   

步骤 2：执行技能链

依次执行技能链中的每项技能：

阶段执行模式

1. Read previous handoff (if exists)
2. Execute skill (spawn agent or invoke directly)
3. Capture skill output/handoff
4. Update orchestration state
5. Human checkpoint (if phase boundary)
6. Continue or handle error

技能执行详情

discovery-interview：

Task(
  subagent_type="discovery-interview",
  prompt="""
  [Contents of discovery-interview SKILL.md]

  ---

  ## Context
  Feature request: <description>
  Handoff directory: thoughts/shared/handoffs/<session>/

  Conduct the interview and create spec.
  """
)

输出：规范文件位于 thoughts/shared/specs/<name>-spec.md

onboard：

Task(
  subagent_type="onboard",
  prompt="""
  [Contents of onboard SKILL.md]

  ---

  Analyze this codebase and create continuity ledger.
  Handoff directory: thoughts/shared/handoffs/<session>/
  """
)

输出：TLDR 缓存、连续性台账

research-codebase：

Task(
  subagent_type="research-codebase",
  prompt="""
  [Contents of research-codebase SKILL.md]

  ---

  Research question: How should we implement <description>?
  Focus areas: [based on spec or description]
  Handoff directory: thoughts/shared/handoffs/<session>/
  """
)

输出：研究文档位于 thoughts/shared/research/<date>-<topic>.md

tldr-impact（用于重构模式）：

# Run impact analysis on the function/module being refactored
tldr impact <target> src/ --depth 3 > thoughts/shared/handoffs/<session>/impact-analysis.json

# Also run architecture analysis
tldr arch src/ > thoughts/shared/handoffs/<session>/architecture.json

输出：影响分析和架构分析文件

plan-agent：

Task(
  subagent_type="plan-agent",
  prompt="""
  [Contents of plan-agent SKILL.md]

  ---

  ## Context
  Feature request: <description>

  [Include spec if exists from discovery-interview]
  [Include research findings if exists]
  [Include impact analysis if refactor mode]

  Handoff directory: thoughts/shared/handoffs/<session>/
  """
)

输出：计划位于 thoughts/shared/plans/PLAN-<name>.md，交接文件位于 <session>/plan-<name>.md

检查点：plan-agent 之后

Plan created: thoughts/shared/plans/PLAN-<name>.md

Please review the plan. Options:
1. Approve and continue to [next phase]
2. Request changes to plan
3. Abort workflow

[Show plan summary]

validate-agent：

Task(
  subagent_type="validate-agent",
  prompt="""
  [Contents of validate-agent SKILL.md]

  ---

  Plan to validate: [Plan content]
  Plan path: thoughts/shared/plans/PLAN-<name>.md
  Handoff directory: thoughts/shared/handoffs/<session>/
  """
)

输出：验证交接文件位于 <session>/validation-<name>.md

检查点：validate-agent 之后（如发现问题）

Validation complete with issues:
- [Issue 1]
- [Issue 2]

Options:
1. Proceed anyway (acknowledge risks)
2. Update plan and re-validate
3. Abort workflow

test-driven-development（用于 TDD/重构模式）：

Present TDD guidance to user:

"Entering TDD mode. For each feature:
1. Write failing test first
2. Implement minimal code to pass
3. Refactor while keeping tests green

I'll guide you through each cycle. Starting with first test..."

此流程为交互式流程——引导用户完成 TDD 周期。

implement_plan：

# Check plan size
if task_count <= 3:
    # Direct implementation
    Follow implement_plan skill directly
else:
    # Agent orchestration mode
    For each task:
        Task(
          subagent_type="implement_task",
          prompt="""
          [Contents of implement_task SKILL.md]

          ---

          Plan: [Plan content]
          Your task: Task N of M: <task description>
          Previous handoff: [Previous task handoff or "First task"]
          Handoff directory: thoughts/shared/handoffs/<session>/
          """
        )

输出：任务交接文件位于 <session>/task-NN-<description>.md

检查点：每个实施阶段之后

Phase [N] Complete

Automated verification:
- [x] Tests passing
- [x] Type check passed
- [ ] Manual testing required

Please verify:
- [Manual test items from plan]

Continue to next phase? [Y/n]

commit：

Follow commit skill:
1. Show git status and diff
2. Present commit plan
3. Execute on user approval
4. Generate reasoning file

describe_pr：

Follow describe_pr skill:
1. Create PR if not exists
2. Generate description from changes
3. Update PR with description

第 3 步：处理错误

如果任何阶段失败或返回受阻状态：

# Update orchestration.yaml
phases:
  - skill: plan-agent
    status: complete
  - skill: validate-agent
    status: blocked
    error: "Validation found deprecated library"
    blocker: "Need to replace X with Y"

向用户显示：

Workflow blocked at: validate-agent

Issue: Validation found deprecated library
Blocker: Need to replace X with Y

Options:
1. Retry this phase
2. Skip this phase (not recommended)
3. Abort workflow
4. Manual intervention (I'll help you fix it)

第 4 步：完成

所有阶段完成后：

Build workflow complete!

Session: thoughts/shared/handoffs/<session>/

Artifacts created:
- Spec: thoughts/shared/specs/<name>-spec.md (if greenfield)
- Plan: thoughts/shared/plans/PLAN-<name>.md
- Validation: <session>/validation-<name>.md
- Implementation handoffs: <session>/task-*.md
- PR: #<number> (if --skip-pr not set)

Commit: <hash> (if --skip-commit not set)

Total phases: N completed, M skipped

人工检查点

检查点会在关键决策点暂停流程，以供人工核验：

阶段之后	检查点用途
discovery-interview	验证规范是否涵盖需求
plan-agent	批准实施计划
validate-agent（如发现问题）	确认验证方面的疑虑
每个 implement 任务	验证阶段正常运行后再继续
commit	批准提交消息和文件

**跳过检查点：**使用 --no-checkpoint 运行（仅限高级用户）

恢复支持

如果工作流中断，可从上一个检查点恢复：

/build resume thoughts/shared/handoffs/<session>/

此操作会读取 orchestration.yaml，并从上一个未完成阶段继续。

会话示例

从零开始开发功能

User: /build greenfield Add user authentication with OAuth

Claude: Starting greenfield workflow for "Add user authentication with OAuth"

Creating session: build-20260108-user-auth-oauth
Chain: discovery-interview -> plan-agent -> validate-agent -> implement_plan -> commit -> describe_pr

Phase 1/6: Discovery Interview
[Spawns discovery-interview agent]

Interview questions:
1. What OAuth providers do you need? (Google, GitHub, etc.)
2. What user data should we store after auth?
3. Should sessions persist across browser closes?
...

[After interview completes]

Spec created: thoughts/shared/specs/2026-01-08-user-auth-spec.md

Phase 2/6: Planning
[Spawns plan-agent]

Plan created: thoughts/shared/plans/PLAN-user-auth.md

--- CHECKPOINT ---
Plan Summary:
- Task 1: Set up OAuth provider configuration
- Task 2: Create user model and session storage
- Task 3: Implement OAuth callback endpoints
- Task 4: Add auth middleware
- Task 5: Create login/logout routes

Approve plan and continue? [Y/n]

User: Y

Phase 3/6: Validation
[Spawns validate-agent]

Validation: PASSED
All tech choices are current best practices.

Phase 4/6: Implementation (5 tasks)
[Spawns implementation agents for each task]

Task 1/5: OAuth configuration... Complete
Task 2/5: User model... Complete
Task 3/5: OAuth callbacks... Complete
Task 4/5: Auth middleware... Complete
Task 5/5: Login/logout routes... Complete

--- CHECKPOINT ---
All implementation complete.
Tests: 24 passing
Manual verification needed:
- [ ] Test OAuth flow end-to-end
- [ ] Verify session persistence

Continue to commit? [Y/n]

User: Y

Phase 5/6: Commit
[Shows changes, creates commit]

Phase 6/6: PR Description
[Creates/updates PR]

Build complete!
PR #42: https://github.com/user/repo/pull/42

TDD 模式

User: /build tdd Add rate limiting to API endpoints

Claude: Starting TDD workflow for "Add rate limiting to API endpoints"

Phase 1/3: Planning
[Creates plan with test specifications]

--- CHECKPOINT ---
Plan approved? [Y/n]

User: Y

Phase 2/3: TDD Implementation

Let's start with the first test. According to the plan, we need to test:
"Rate limiter returns 429 after 100 requests per minute"

RED - Write failing test:
```python
def test_rate_limiter_returns_429_after_limit():
    limiter = RateLimiter(limit=100, window=60)
    for _ in range(100):
        assert limiter.check("user1") == True
    assert limiter.check("user1") == False

运行测试……失败（符合预期——RateLimiter 不存在）

绿色阶段——实现最简代码： [引导完成实现]

运行测试……通过

重构——需要进行清理吗？

下一个测试：“速率限制器在时间窗口到期后重置” ……

阶段 3/3：实施 [将速率限制器集成到端点中]

构建完成！

### Refactor Mode

用户：/build refactor Extract auth logic into separate module

Claude：开始执行“将身份验证逻辑提取到单独模块”的重构工作流

阶段 1/4：影响分析 运行：tldr impact auth src/ --depth 3

影响分析完成：

• 12 个文件直接调用身份验证函数
• 3 个入口点受影响
• 未检测到循环依赖

架构分析：

• 身份验证当前位于：src/api/middleware/
• 调用方位于：src/api/routes/、src/api/handlers/

--- 检查点 --- 规划前要查看影响吗？[Y/n]

用户：Y

[显示详细影响报告]

阶段 2/4：规划 [基于影响分析创建重构计划]

……

## Error Recovery

### If a phase fails:

阶段 3（validate-agent）失败：

错误：WebSearch 不可用

选项：

1. 重试此阶段（推荐）
2. 跳过验证（--skip-validate）
3. 中止工作流

选择：

### If implementation is blocked:

任务 3/5 受阻：

阻碍因素：数据库架构与预期结构不符 实际情况：users.email (VARCHAR) 预期情况：users.email (UNIQUE VARCHAR)

选项：

1. 创建迁移以修复架构
2. 调整计划以适配当前架构
3. 中止并调查

选择：

## Parallel Execution

With `--parallel` option, independent phases run concurrently:

/build brownfield --parallel Add dashboard feature

阶段 1：Onboard（已开始） 阶段 2：Research-codebase（已并行开始）

[两者均已完成]

阶段 3：Plan-agent（使用两者的结果） ……

Only truly independent phases run in parallel. Dependencies are respected.

## Configuration

### Default mode preferences

Set in `.claude/settings.json`:

```json
{
  "skills": {
    "build": {
      "default_mode": "brownfield",
      "always_validate": true,
      "auto_commit": false,
      "checkpoint_phases": ["plan-agent", "implement_plan"]
    }
  }
}

故障排除

问题	解决方案
“未找到连续性台账”	先运行 /onboard，或使用 greenfield 模式
“计划验证失败”	查看验证输出并更新计划
“实施受阻”	查看交接文件中的阻碍因素并解决依赖
“工作流卡住”	检查 orchestration.yaml 中的状态，然后恢复或重新启动

相关技能

• /discovery-interview - 深入访谈，梳理需求
• /plan-agent - 制定实施计划
• /validate-agent - 验证技术选型
• /implement_plan - 执行实施计划
• /implement_task - 实施单项任务
• /test-driven-development - TDD 工作流
• /commit - 创建提交
• /describe_pr - 生成 PR 描述
• /onboard - 分析代码库
• /research-codebase - 调研现有代码
• /tldr-code - 代码分析 CLI