procedure-builder

procedure-builder

根据结构化规范文件，构建完整的 ICM（Interpreted Context Methodology）流程。首次运行时引导创建 _core/，然后遵循 ICM workspace-builder 的五阶段流水线。

适用场景

• 构建新的多阶段工作流（speckit、deps-check、审查流水线等）
• 将现有的单体运行器技能转换为分阶段流程
• 为团队仓库创建特定领域的流程（营销、入职等）

不适用场景

• 单步操作——改用常规技能
• 每个步骤都需要与人类对话的交互式工作流

前提条件

test -f "$1" && echo "Spec found" || echo "ERROR: spec file not found"
grep -c '^## Stage' "$1"  # Must have at least 2 stages

规范文件必须遵循 references/spec-format.md 中的格式。

流程

此技能依次运行六个阶段。第一阶段是一次性引导；其余五个阶段与 ICM workspace-builder 完全一致。每个阶段都会生成一个供下一阶段使用的产物。

开始前请阅读 references/icm-conventions.md——所有约定均适用。

阶段 00：引导创建 _core/

在运行任何脚手架之前，确保工作区在仓库根目录下具有规范的 ICM _core/ 目录。 这样只需一条命令，就能让全新的仓库符合 ICM 规范，并确保后续阶段离线运行且结果确定。每次调用都运行；如果已完成引导，则不执行任何操作。

输入： 当前工作目录（必须是仓库根目录）。

流程：

1. 检查仓库根目录下是否存在 _core/：

   test -d "_core" && echo "present" || echo "missing"
   

2. 如果存在，跳至阶段 01。输出 [bootstrap] _core/ already present, skipping。
3. 如果不存在，将此技能中随附的模板复制到仓库根目录。解析此技能的安装位置（以下之一：.claude/skills/procedure-builder/、.agents/skills/procedure-builder/、~/.claude/skills/procedure-builder/）：

   for SKILL_DIR in \
       ".claude/skills/procedure-builder" \
       ".agents/skills/procedure-builder" \
       "$HOME/.claude/skills/procedure-builder"; do
     if [ -d "$SKILL_DIR/templates/_core" ]; then
       cp -R "$SKILL_DIR/templates/_core" "./_core"
       break
     fi
   done
   

4. 验证复制成功：
   • _core/CONVENTIONS.md 存在且非空
   • _core/placeholder-syntax.md 存在
   • _core/templates/ 包含 stage-context-template.md 和 questionnaire-template.md
   • _core/SOURCE.md 存在（记录来源）
5. 运行审计检查：
   • _core/ 是仓库根目录下的目录，而非嵌套在其他位置
   • 所有预期文件均存在且非空
   • 文件内容与随附模板逐字节一致（diff -r ./_core "$SKILL_DIR/templates/_core" 不返回任何差异）

输出： 将 bootstrap-result.md 写入工作目录：

# Bootstrap Result
- bootstrapped: yes | no
- core_files: <count>
- skill_dir: <path>
- audit: PASS | FAIL

如果审计失败，请停止流程——不要带着损坏的 _core/ 继续阶段 01。

Stage 01：发现

与 ICM workspace-builder Stage 01 相同，但读取规范文件，而非采访用户。

输入： $1 处的规范文件。

流程：

1. 完整阅读规范文件
2. 提取流程名称、单行用途、目标目录和参数
3. 对于规范中的每个阶段，提取：
   • 输入内容（文件、API 响应、参数、上一阶段的输出）
   • 输出内容（该阶段生成的产物及其格式）
   • Agent 需要了解的内容（参考资料、规则、约束）
4. 识别共享上下文——多个阶段都会用到的信息。这些内容将成为 shared/ 中的文件
5. 识别用户特定变量——因安装环境或团队而异的细节。这些内容将成为问卷中的 {{PLACEHOLDER}} 变量
6. 识别可选阶段——某些安装环境可能会跳过的阶段。这些内容将成为条件章节
7. 识别工具前置条件——所需的外部工具（CLI 工具、API、SDK）。注明哪些阶段需要这些工具
8. 识别相关技能——现有的 Claude Code 技能中，能够为流程各阶段提供领域知识的技能。扫描 ~/.claude/skills/ 和 ~/.agents/skills/，查找候选技能。列出匹配项，并简要说明每项技能能提供什么
9. 运行审计检查：
   • 每个阶段都有明确的单一职责和命名的输出产物
   • 每个阶段的输入均由用户提供、来自共享上下文，或由前一阶段生成
   • 跨阶段资源（共享上下文）与阶段专属参考资料分开列出
   • 每项用户特定细节都已记录为具名占位符变量

输出： 在工作目录中写入 workflow-map.md。结构如下：

# Workflow Map: <procedure-name>

<One-line purpose>

## Target
- Directory: <target dir>
- Arguments: <invocation args>

## Stages
### 01-<name>
- Inputs: <list>
- Output: <artifact name and format>
- Agent needs: <reference material>
- Type: <creative | linear | build>

### 02-<name>
...

## Shared Context
- <name>: <description, which stages use it>

## User-Specific Variables
- {{VAR_NAME}}: <what it configures, which files it appears in>

## Optional Stages
- <stage>: <condition for removal>

## Tool Prerequisites
- <tool>: <which stages, required or optional>

## Selected Skills
- <skill-name>: <what it provides, which stages reference it>

Stage 02：映射

与 ICM workspace-builder Stage 02 相同。

输入： Stage 01 生成的 workflow-map.md。

流程：

1. 阅读工作流映射
2. 为每个阶段编写正式的 Inputs/Process/Outputs 契约，遵循 ICM Pattern 1（阶段契约）。使用 stage-context-template 格式：
   • 输入表，采用选择性章节路由（指定文件中的具体 SECTION，而不只是文件）
   • 编号的流程步骤——具体操作，而非笼统描述
   • 输出表，包含产物名称、位置和格式
3. 对每个阶段，确定：
   • 是否需要 Checkpoint 部分？（创作阶段：需要；线性阶段：不需要）
   • 是否需要 Audit 部分？（创作和构建阶段：需要；提取/转换阶段：不需要）
4. 绘制交叉引用：画出依赖关系图，展示各阶段从哪些阶段读取内容
5. 验证规范来源：每条信息只有一个归属位置
6. 验证单向引用：如果 A 引用 B，则 B 不得引用 A
7. 验证每个阶段的输出至少被一个下游阶段使用，或作为最终交付物
8. 运行审计检查：
   • 没有循环引用——依赖关系图只有一个方向
   • 每个阶段的输出都被下游阶段使用，或作为最终交付物
   • 每个阶段都包含 Inputs、Process 和 Outputs，且没有空字段
   • 没有信息在多个位置被定义为权威来源

输出： 在工作目录中写入 stage-contracts.md。结构如下：

# Stage Contracts: <procedure-name>

## Dependency Diagram

01-name --> 02-name --> 03-name
              \--> shared/config.md

## Stage 01: <name>

### Inputs
| Source | File/Location | Section/Scope | Why |
...

### Process
1. ...

### Checkpoints (if applicable)
| After Step | Agent Presents | Human Decides |
...

### Audit (if applicable)
| Check | Pass Condition |
...

### Outputs
| Artifact | Location | Format |
...

## Stage 02: <name>
...

阶段 03：搭建脚手架

与 ICM workspace-builder 阶段 03 相同。

**输入：**阶段 02 的 stage-contracts.md、阶段 01 的 workflow-map.md。

流程：

1. 阅读阶段契约
2. 阅读工作流映射，了解工具前置条件、选定的技能和共享上下文
3. 创建流程文件夹结构：

   <name>/
   ├── SKILL.md
   ├── CONTEXT.md
   ├── setup/
   │   └── questionnaire.md    (placeholder -- populated in Stage 04)
   ├── stages/
   │   ├── 01-<name>/
   │   │   ├── CONTEXT.md
   │   │   ├── references/
   │   │   └── output/.gitkeep
   │   ├── 02-<name>/
   │   │   ├── CONTEXT.md
   │   │   ├── references/
   │   │   └── output/.gitkeep
   │   └── ...
   └── shared/
   

4. 根据契约，使用 stage-context-template 编写各阶段的 CONTEXT.md：
   • 标题 + 一句话说明用途
   • 输入表（按照 ICM 模式 4 选择性地路由章节）
   • 流程步骤（具体、编号）
   • 检查点章节（如果阶段类型为创意型；否则删除该章节）
   • 审计章节（如适用）
   • 输出表
   • **最多 80 行。**如果超出，将内容移至 references/。
5. 编写流程级 CONTEXT.md：
   • 任务路由表
   • 阶段链表（阶段、输入来源、输出）
   • 共享上下文表
   • 最多 80 行。
6. 使用 templates/procedure-skill-template.md 作为基础，编写 SKILL.md 入口文件。复制模板，然后将所有 {{PLACEHOLDER}} 变量替换为工作流映射和契约中的值：
   • {{PROCEDURE_NAME}}、{{PROCEDURE_TITLE}}、{{PROCEDURE_PURPOSE}}、{{PROCEDURE_DESCRIPTION}}
   • {{ARGUMENT_HINT}}、{{PRIMARY_ARG_DESCRIPTION}}、{{ADDITIONAL_ARGS}}
   • {{WHEN_TO_USE_BULLETS}}、{{PREREQUISITES}}
   • 每个阶段对应的 {{STAGE_N_NAME}}、{{STAGE_N_ARTIFACT}}
   • 模板负责处理阶段链执行、输出目录管理、--stage N 恢复执行、--review 检查点关卡、错误处理和关键规则。不要修改执行、恢复执行或错误处理章节——这些内容在所有流程中采用统一标准。
7. 在 shared/ 中为工作流映射中的每个共享上下文项创建占位参考文件。使用 {{PLACEHOLDER}} 变量表示特定于用户的内容。
8. 在需要时，于 stages/NN/references/ 中创建特定于阶段的参考文件
9. 如果识别出技能，在 SKILL.md 的前置条件中注明。如果这些技能应打包（领域专属知识），则创建 skills/ 文件夹并记录该技能包。
10. 如果识别出工具前置条件，在相关阶段的 references/ 文件夹中编写设置指南
11. 在所有 output/ 目录中添加 .gitkeep
12. 运行审计检查：
    • 每个阶段都有 CONTEXT.md、output/ 和 references/
    • 每个阶段的 CONTEXT.md 都符合阶段 02 的契约
    • 所有占位符均使用 {{SCREAMING_SNAKE_CASE}}
    • 每个 output/ 目录都有 .gitkeep
    • 没有 CONTEXT.md 超过 80 行
    • 所有文件夹和文件均使用 lowercase-with-hyphens
    • 阶段文件夹使用零填充前缀（01-、02-）

**输出：**写入目标目录的完整流程文件夹。

阶段 04：问卷设计

与 ICM workspace-builder 阶段 04 相同。

输入： 阶段 01 中的 workflow-map.md（用于获取用户专属变量），以及阶段 03 搭建的流程。

流程：

1. 阅读工作流映射中的用户专属变量部分
2. 扫描搭建流程中的所有 Markdown 文件，查找 {{PLACEHOLDER}} 模式。列出所有匹配项。
3. 将变量分为两类：
   • 系统级： 每次运行时保持不变的内容（API 端点、凭据配置、团队身份、工具偏好）。这些内容将转化为设置问题。
   • 每次运行： 每次流水线运行时都会变化的内容（问题编号、仓库、目标分支）。这些内容不会成为设置问题，而是由 SKILL.md 作为参数收集。
4. 为每个系统级占位符编写一个问题：
   • 问题文本（使用通俗易懂的英语，不涉及技术术语）
   • 该问题填充的占位符
   • 这些占位符出现的文件
   • 输入类型（自由文本、选项、是/否）
   • 合理的默认值或示例
5. 对于有关可选阶段的“是/否”问题：如果答案为“否”，请指定要删除的阶段文件夹
6. 将所有问题写成一个连续编号的列表，不要按类别分组
7. 验证每个系统级占位符都有对应的问题
8. 验证每次运行的变量由 SKILL.md 参数处理，而不是由问卷处理
9. 运行审核检查：
   • 每个系统级占位符都有对应的问题
   • 问卷中没有每次运行的变量
   • 结构平铺（不按类别分组）
   • 每个问题都有默认值或示例

输出： 在流程文件夹中，按照 questionnaire-template 格式编写 setup/questionnaire.md。

如果流程没有用户专属变量（即纯系统流程，无需配置），请编写一份简短问卷，内容为“无需配置”，并跳过占位符替换。

阶段 05：验证

与 ICM workspace-builder 阶段 05 相同。共 13 项检查。

输入： 阶段 03 搭建的流程、阶段 04 的问卷。

流程：

逐项执行检查。记录通过/失败情况和发现的问题。

1. 交叉引用完整性。 CONTEXT.md 中任意 Inputs 表格里的每个文件路径都必须指向真实文件。列出失效引用。

2. 无循环依赖。 追踪引用关系图。确认它是有向无环图。

3. 占位符覆盖。 扫描所有文件中的 {{PLACEHOLDER}} 模式。每个占位符都必须对应问卷中的一个问题。每个问题都必须映射到至少一个文件。列出未匹配项。

4. 条件区段有效性。 每个 {{?SECTION}}...{{/SECTION}} 块都必须包裹完整区段（标题 + 内容）。不得有行内条件语句。

5. 阶段交接链。 阶段 N 的输出位置必须与阶段 N+1 的 Inputs 表格引用一致。列出交接链并标记缺口。

6. CONTEXT.md 内容纯净性。 不得有任何 CONTEXT.md 包含实际参考内容。仅允许包含：标题、描述、Inputs 表格、流程步骤、检查点（可选）、审核（可选）、Outputs 表格。

7. 创作阶段的检查点。 创作阶段至少有一个检查点。检查点表格必须引用有效的步骤编号。

8. 创作/构建阶段的审核。 创作和构建阶段必须包含审核部分，并注明具体的通过条件。

9. 契约纯净性。 规范阶段定义 WHAT 和 WHEN，而非 HOW。规范输出中不得包含实现细节。

10. 行数检查。 标记任何超过 80 行的 CONTEXT.md。标记任何超过 200 行的参考文件。

11. 命名规范。 小写字母-连字符。阶段前缀使用零填充。空的 output/ 文件夹中包含 .gitkeep。

12. 工具前置条件。 如果存在工具设置指南：每个列出的工具都必须有对应指南，且指南必须包含安装步骤和验证命令。

13. 质量扫描。 不得使用 em dash（替换为 --）。不得出现未经解释的术语。Markdown 格式应整洁。

修复搭建流程中的所有失败项，然后重新运行失败的检查。

输出： 在工作目录中写入 validation-report.md。格式如下：

# Validation Report: <procedure-name>

## Results

| # | Check | Result | Notes |
|---|-------|--------|-------|
| 1 | Cross-reference integrity | PASS/FAIL | <details> |
| 2 | No circular dependencies | PASS/FAIL | <details> |
| ... | ... | ... | ... |
| 13 | Quality scan | PASS/FAIL | <details> |

## Issues Fixed
- <description of fix>

## Summary
<N>/13 checks passed. <Procedure is ready / Issues remain.>

错误处理

规范少于 2 个阶段 -- 停止。单阶段流程属于 skill，而非 procedure。

阶段 CONTEXT.md 超过 80 行 -- 将内容移至 references/。这是硬性上限。

发现循环依赖 -- 报告循环。必须重构规范。

尝试修复后验证检查仍失败 -- 报告失败。不得带着已知问题交付。

描述规则

ICM procedure 的描述尤其容易写成机制说明。阶段数量、并行说明和“SEQUENTIAL”标记应放在 procedure 正文中，绝不能写在 description: frontmatter 中。

好的示例	不好的示例
“在将已审核的 PR 合并到发布分支时使用。”	“一个包含 8 个阶段、完全顺序执行的 ICM procedure，用于合并 N 个已审核的 PR……”
“在运行完整的 issue-to-PR 流程时使用。”	“作为 ICM procedure 的 issue-to-PR 流程——从预检开始，共 7 个阶段……”
“在运行 CTO 流程优化循环时使用。”	“流程优化器运行循环——WIP 扫描、聚焦当前 epic、分类……”

写入 SKILL.md 前先自检： 从描述中删去所有阶段数量和并行说明。剩余内容仍必须回答“我应该在什么时候使用此 procedure？”。如果不能，就重写描述。

可接受的触发形式：“在……时使用”“用于……”。阶段数量和“SEQUENTIAL / PARALLEL”说明应放在正文中（## Procedure、## Stages 或 ## When to Use 部分）。

关键规则

• 遵循所有 ICM 约定。 CONVENTIONS.md 中的 15 种模式全部适用，不得遗漏。
• 生成全部五项产物。 workflow-map.md、stage-contracts.md、procedure 文件夹、questionnaire.md 和 validation-report.md。即使某个阶段看起来很简单，也要生成对应产物。
• CONTEXT.md 的 80 行上限是硬性限制。 不是指导建议。将内容移至参考资料。
• 参考文件的 200 行上限是硬性限制。 超出时拆分文件。
• 选择性章节路由。 输入表必须指定要加载的 SECTION，而不只是文件路径。
• 工作产物应放在仓库中，而不是技能目录中。 输出路径：$REPO_DIR/.procedure-output/<name>/。
• 不得使用 em dash。 使用 --。
• 每项验证检查都必须通过。 存在已知失败时，不得报告成功。
• 模板为必需项。 使用 _core/templates/ 中的 stage-context-template 和 questionnaire-template 格式。不得自行设计格式。