procedure-builder

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

procedure-builder

Build a complete ICM (Interpreted Context Methodology) procedure from a structured spec file. Bootstraps

_core/

on first run, then follows the five-stage pipeline of the ICM workspace-builder.

从结构化的规范文件构建完整的ICM（Interpreted Context Methodology）流程。首次运行时会初始化

_core/

目录，随后遵循ICM workspace-builder的五阶段流水线执行。

When to Use

使用场景

Building a new multi-stage workflow (speckit, deps-check, review pipeline, etc.)
Converting an existing monolithic runner skill into a staged procedure
Creating domain-specific procedures for a team repo (marketing, onboarding, etc.)

构建新的多阶段工作流（如speckit、依赖检查、审核流水线等）
将现有单体运行器skill转换为分阶段流程
为团队仓库创建特定领域的流程（如营销、入职等）

When NOT to Use

非适用场景

Single-step operations -- use a regular skill instead
Interactive workflows that need human dialog at every step

单步操作——请使用常规skill
每一步都需要人工对话的交互式工作流

Prerequisites

前置条件

bash

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

The spec file must follow the format in

references/spec-format.md

bash

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

中的格式。

Procedure

流程步骤

This skill runs six stages sequentially. The first is a one-time bootstrap; the remaining five mirror the ICM workspace-builder exactly. Each stage produces an artifact that feeds the next.

Read

references/icm-conventions.md

before starting -- every convention applies.

该skill会按顺序运行六个阶段。第一个阶段是一次性初始化；剩下的五个阶段与ICM workspace-builder完全一致。每个阶段都会生成一个工件，供下一个阶段使用。

开始前请阅读

references/icm-conventions.md

——所有约定均适用。

Stage 00: Bootstrap

_core/

阶段00：初始化

_core/

Ensure the workspace has the canonical ICM
_core/
directory at the repo root before any scaffolding runs. This makes a fresh repo ICM-compliant with one command and keeps later stages offline-deterministic. Run on every invocation; no-op if already bootstrapped.

Input: The current working directory (must be a repo root).

Process:

Check whether

_core/

exists at the repo root:

bash

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

If present, skip to Stage 01. Print

[bootstrap] _core/ already present, skipping

If missing, copy the vendored template from this skill into the repo root. Resolve the skill's installed location (one of:

.claude/skills/procedure-builder/

.agents/skills/procedure-builder/

~/.claude/skills/procedure-builder/

bash

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

Verify the copy succeeded:

```
_core/CONVENTIONS.md
```
exists and is non-empty
```
_core/placeholder-syntax.md
```
exists

_core/templates/

contains

stage-context-template.md

and

questionnaire-template.md

```
_core/SOURCE.md
```
exists (documents provenance)

Run the audit checks:
- ```
_core/
```
  is a directory at the repo root, not nested elsewhere
- All expected files are present and non-empty
- File contents match the bundled templates byte-for-byte (
```
diff -r ./_core "$SKILL_DIR/templates/_core"
```
  returns no differences)

Output: Write

bootstrap-result.md

to the working directory:

markdown

undefined

确保在任何脚手架运行之前，工作区的仓库根目录下存在标准的ICM
_core/
目录。这只需一条命令就能让新仓库符合ICM规范，并确保后续阶段可离线执行。每次调用都会运行此阶段；如果已完成初始化，则会执行空操作。

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

流程：

检查仓库根目录下是否存在

_core/

：

bash

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

如果已存在，则跳至阶段01。打印
```
[bootstrap] _core/ already present, skipping
```
。

如果不存在，则将该skill中的模板复制到仓库根目录。确定skill的安装位置（以下位置之一：

.claude/skills/procedure-builder/

、

.agents/skills/procedure-builder/

、

~/.claude/skills/procedure-builder/

）：

bash

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

验证复制是否成功：

```
_core/CONVENTIONS.md
```
存在且非空
```
_core/placeholder-syntax.md
```
存在

_core/templates/

包含

stage-context-template.md

和

questionnaire-template.md

```
_core/SOURCE.md
```
存在（记录来源）

运行审核检查：
- ```
_core/
```
  位于仓库根目录，而非嵌套在其他位置
- 所有预期文件均存在且非空
- 文件内容与捆绑模板完全一致（
```
diff -r ./_core "$SKILL_DIR/templates/_core"
```
  无差异）

输出： 在工作目录中写入

bootstrap-result.md

：

markdown

undefined

Bootstrap Result

bootstrapped: yes | no
core_files: <count>
skill_dir: <path>
audit: PASS | FAIL


If audit fails, stop the procedure -- do not proceed to Stage 01 with a broken `_core/`.

bootstrapped: yes | no
core_files: <count>
skill_dir: <path>
audit: PASS | FAIL


如果审核失败，则停止流程——不能在`_core/`目录损坏的情况下进入阶段01。

Stage 01: Discovery

阶段01：发现

Same as ICM workspace-builder Stage 01, but reads a spec file instead of interviewing the user.

Input: The spec file at

$1

Process:

Read the spec file completely
Extract the procedure name, one-line purpose, target directory, and arguments
For each stage in the spec, extract:
- What goes in (files, API responses, arguments, previous stage output)
- What comes out (the artifact this stage produces, its format)
- What the agent needs to know (reference material, rules, constraints)
Identify shared context -- information used across multiple stages. These become files in
```
shared/
```
Identify user-specific variables -- details that vary per installation or per team. These become
```
{{PLACEHOLDER}}
```
variables for the questionnaire
Identify optional stages -- stages some installations might skip. These become conditional sections
Identify tool prerequisites -- external tools needed (CLI tools, APIs, SDKs). Note which stages need them
Identify relevant skills -- existing Claude Code skills that provide domain knowledge for the procedure's stages. Scan
```
~/.claude/skills/
```
and
```
~/.agents/skills/
```
for candidates. List matches with a brief note on what each provides
Run the audit checks:
- Every stage has a clear single responsibility and a named output artifact
- Every stage's inputs are either user-provided, from shared context, or produced by a prior stage
- Cross-stage resources (shared context) are listed separately from stage-specific references
- Every user-specific detail is captured as a named placeholder variable

Output: Write

workflow-map.md

to the working directory. Structure:

markdown

undefined

与ICM workspace-builder的阶段01相同，但读取的是规范文件而非与用户交互。

输入：

$1

路径下的规范文件。

流程：

完整读取规范文件
提取流程名称、单行用途、目标目录和参数
对于规范中的每个阶段，提取：
- 输入内容（文件、API响应、参数、前一阶段输出）
- 输出内容（该阶段生成的工件及其格式）
- Agent需要了解的信息（参考资料、规则、约束）
识别共享上下文——多个阶段共用的信息。这些会成为
```
shared/
```
目录下的文件
识别用户特定变量——因安装或团队不同而变化的细节。这些会成为问卷中的
```
{{PLACEHOLDER}}
```
变量
识别可选阶段——部分安装可能会跳过的阶段。这些会成为条件性章节
识别工具前置条件——所需的外部工具（CLI工具、API、SDK）。记录哪些阶段需要它们
识别相关skill——为流程各阶段提供领域知识的现有Claude Code skill。扫描
```
~/.claude/skills/
```
和
```
~/.agents/skills/
```
寻找候选skill，并列出匹配项及其提供的功能简介
运行审核检查：
- 每个阶段都有明确的单一职责和命名的输出工件
- 每个阶段的输入要么是用户提供的，要么来自共享上下文，要么由前一阶段生成
- 跨阶段资源（共享上下文）与阶段特定参考内容分开列出
- 每个用户特定细节都被捕获为命名的占位符变量

输出： 在工作目录中写入

workflow-map.md

。结构如下：

markdown

undefined

Workflow Map: <procedure-name>

<One-line purpose>

Target

Directory: <target dir>
Arguments: <invocation args>

Directory: <target dir>
Arguments: <invocation args>

Stages

01-<name>

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

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>

<name>: <description, which stages use it>

User-Specific Variables

{{VAR_NAME}}: <what it configures, which files it appears in>

{{VAR_NAME}}: <what it configures, which files it appears in>

Optional Stages

<stage>: <condition for removal>

<stage>: <condition for removal>

Tool Prerequisites

<tool>: <which stages, required or optional>

<tool>: <which stages, required or optional>

Selected Skills

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

undefined

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

undefined

Stage 02: Mapping

阶段02：映射

Same as ICM workspace-builder Stage 02.

Input:

workflow-map.md

from Stage 01.

Process:

Read the workflow map
For each stage, write the formal Inputs/Process/Outputs contract following ICM Pattern 1 (Stage Contracts). Use the stage-context-template format:
- Inputs table with selective section routing (specify which SECTION of a file, not just the file)
- Numbered process steps -- concrete actions, not vague descriptions
- Outputs table with artifact name, location, format
For each stage, determine:
- Does it need a Checkpoint section? (creative stages: yes. linear stages: no)
- Does it need an Audit section? (creative and build stages: yes. extraction/conversion: no)
Map cross-references: draw the dependency graph showing which stages read from which
Verify canonical sources: each piece of information has ONE home
Verify one-way references: if A references B, B does NOT reference A
Verify every stage's output is consumed by at least one downstream stage or is the final deliverable
Run the audit checks:
- No circular references -- dependency graph flows one direction only
- Every stage's output is consumed downstream or is the final deliverable
- Every stage has Inputs, Process, and Outputs with no empty fields
- No information is defined as authoritative in more than one place

Output: Write

stage-contracts.md

to the working directory. Structure:

markdown

undefined

与ICM workspace-builder的阶段02相同。

输入： 阶段01生成的

workflow-map.md

。

流程：

读取工作流映射
为每个阶段编写符合ICM模式1（阶段契约）的正式输入/流程/输出契约。使用stage-context-template格式：
- 输入表，包含选择性章节路由（指定文件的哪个章节，而非仅文件路径）
- 编号的流程步骤——具体操作，而非模糊描述
- 输出表，包含工件名称、位置、格式
为每个阶段确定：
- 是否需要检查点章节？（创意阶段：是；线性阶段：否）
- 是否需要审核章节？（创意和构建阶段：是；提取/转换阶段：否）
映射交叉引用：绘制依赖图，显示哪些阶段读取哪些阶段的输出
验证标准来源：每条信息只有一个来源
验证单向引用：如果A引用B，则B不能引用A
验证每个阶段的输出至少被一个下游阶段使用，或作为最终交付物
运行审核检查：
- 无循环引用——依赖图仅单向流动
- 每个阶段的输出要么被下游使用，要么是最终交付物
- 每个阶段都有输入、流程和输出，且无空字段
- 没有信息在多个地方被定义为权威来源

输出： 在工作目录中写入

stage-contracts.md

。结构如下：

markdown

undefined

Stage Contracts: <procedure-name>

Dependency Diagram

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

Stage 01: <name>

Inputs

Process

Checkpoints (if applicable)

| After Step | Agent Presents | Human Decides | ...

Audit (if applicable)

| Check | Pass Condition | ...

Outputs

| Artifact | Location | Format | ...

Stage 02: <name>

...

undefined

...

undefined

Stage 03: Scaffolding

阶段03：脚手架搭建

Same as ICM workspace-builder Stage 03.

Input:

stage-contracts.md

from Stage 02,

workflow-map.md

from Stage 01.

Process:

Read the stage contracts
Read the workflow map for tool prerequisites, selected skills, and shared context

Create the procedure folder structure:

<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/

Write each stage CONTEXT.md from the contracts using the stage-context-template:
- Title + one-sentence purpose
- Inputs table (with selective section routing per ICM Pattern 4)
- Process steps (concrete, numbered)
- Checkpoints section (if stage type is creative -- delete section otherwise)
- Audit section (if applicable)
- Outputs table
- Hard cap: 80 lines. Move content to
```
references/
```
  if exceeded.
Write the procedure-level CONTEXT.md:
- Task routing table
- Stage chain table (stage, input from, output)
- Shared context table
- Hard cap: 80 lines.
Write the SKILL.md entry point using
```
templates/procedure-skill-template.md
```
as the base. Copy the template, then replace all
```
{{PLACEHOLDER}}
```
variables with values from the workflow map and contracts:
- ```
{{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}}
```
  for each stage
- The template handles: stage chain execution, output directory management,
```
--stage N
```
  resume,
```
--review
```
  checkpoint gates, error handling, and critical rules. Do not modify the execution, resume, or error handling sections -- they are standardized across all procedures.
Create placeholder reference files in
```
shared/
```
for each shared context item from the workflow map. Use
```
{{PLACEHOLDER}}
```
variables for user-specific content.
Create stage-specific reference files in
```
stages/NN/references/
```
where needed
If skills were identified, note them in the SKILL.md prerequisites. If they should be bundled (domain-specific knowledge), create a
```
skills/
```
folder and document the bundle.
If tool prerequisites were identified, write setup guides in the relevant stage's
```
references/
```
folder
Add
```
.gitkeep
```
in all
```
output/
```
directories
Run the audit checks:
- Every stage has CONTEXT.md,
```
output/
```
  , and
```
references/
```
- Every stage CONTEXT.md matches the contracts from Stage 02
- All placeholders use
```
{{SCREAMING_SNAKE_CASE}}
```
- Every
```
output/
```
  directory has
```
.gitkeep
```
- No CONTEXT.md exceeds 80 lines
- All folders and files use
```
lowercase-with-hyphens
```
- Stage folders use zero-padded prefixes (
```
01-
```
  ,
```
02-
```
  )

Output: The complete procedure folder written to the target directory.

与ICM workspace-builder的阶段03相同。

输入： 阶段02生成的

stage-contracts.md

，阶段01生成的

workflow-map.md

。

流程：

读取阶段契约
读取工作流映射中的工具前置条件、选定的skill和共享上下文

创建流程文件夹结构：

<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/

使用stage-context-template从契约中写入每个阶段的CONTEXT.md：
- 标题+单行用途
- 输入表（遵循ICM模式4的选择性章节路由）
- 流程步骤（具体、编号）
- 检查点章节（如果是创意阶段——否则删除该章节）
- 审核章节（如适用）
- 输出表
- 硬性限制：80行。 如果超出，将内容移至
```
references/
```
  目录。
编写流程级别的CONTEXT.md：
- 任务路由表
- 阶段链表（阶段、输入来源、输出）
- 共享上下文表
- 硬性限制：80行。
使用
```
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
```
  检查点门控、错误处理和关键规则。不要修改执行、恢复或错误处理部分——它们在所有流程中都是标准化的。
为工作流映射中的每个共享上下文项在
```
shared/
```
目录中创建占位符参考文件。对用户特定内容使用
```
{{PLACEHOLDER}}
```
变量。
在需要的
```
stages/NN/references/
```
目录中创建阶段特定的参考文件
如果识别到skill，在SKILL.md的前置条件中注明。如果需要捆绑（领域特定知识），创建
```
skills/
```
文件夹并记录捆绑内容。
如果识别到工具前置条件，在相关阶段的
```
references/
```
目录中编写设置指南
在所有
```
output/
```
目录中添加
```
.gitkeep
```
运行审核检查：
- 每个阶段都有CONTEXT.md、
```
output/
```
  和
```
references/
```
- 每个阶段的CONTEXT.md与阶段02的契约一致
- 所有占位符使用
```
{{SCREAMING_SNAKE_CASE}}
```
  格式
- 每个
```
output/
```
  目录都有
```
.gitkeep
```
- 没有CONTEXT.md超过80行
- 所有文件夹和文件使用
```
lowercase-with-hyphens
```
  格式
- 阶段文件夹使用零填充前缀（
```
01-
```
  、
```
02-
```
  ）

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

Stage 04: Questionnaire Design

阶段04：问卷设计

Same as ICM workspace-builder Stage 04.

Input:

workflow-map.md

from Stage 01 (for user-specific variables), the scaffolded procedure from Stage 03.

Process:

Read the workflow map's user-specific variables section
Scan all markdown files in the scaffolded procedure for
```
{{PLACEHOLDER}}
```
patterns. Build a complete list.
Split variables into two buckets:
- System-level: Things that stay the same across runs (API endpoints, credentials config, team identity, tool preferences). These become setup questions.
- Per-run: Things that change each pipeline run (issue number, repo, target branch). These do NOT become setup questions -- the SKILL.md collects them as arguments.
For each system-level placeholder, write a question:
- Question text (plain English, non-technical)
- The placeholder(s) it populates
- The files where those placeholders appear
- Input type (free text, selection, yes/no)
- A sensible default or example
For yes/no questions about optional stages: specify which stage folder to remove if NO
Write ALL questions as a flat numbered list -- no category groupings
Verify every system-level placeholder has a corresponding question
Verify per-run variables are handled by SKILL.md arguments, not the questionnaire
Run the audit checks:
- Every system-level placeholder has a question
- No per-run variables in the questionnaire
- Flat structure (no category groupings)
- Every question has a default or example

Output: Write

setup/questionnaire.md

in the procedure folder, following the questionnaire-template format.

If the procedure has NO user-specific variables (pure system procedure with no configuration), write a minimal questionnaire that says "No configuration needed" and skip placeholder replacement.

与ICM workspace-builder的阶段04相同。

输入： 阶段01生成的

workflow-map.md

（用于用户特定变量），阶段03搭建的脚手架流程。

流程：

读取工作流映射中的用户特定变量部分
扫描脚手架流程中的所有markdown文件，查找
```
{{PLACEHOLDER}}
```
模式，构建完整列表。
将变量分为两类：
- 系统级： 每次运行保持不变的内容（API端点、凭证配置、团队标识、工具偏好）。这些会成为设置问题。
- 每次运行： 每次流水线运行都会变化的内容（问题编号、仓库、目标分支）。这些不会成为设置问题——由SKILL.md作为参数收集。
为每个系统级占位符编写问题：
- 问题文本（通俗易懂的英文，非技术术语）
- 它填充的占位符
- 这些占位符出现的文件
- 输入类型（自由文本、选择、是/否）
- 合理的默认值或示例
对于关于可选阶段的是/否问题：指定如果选择“否”要移除哪个阶段文件夹
将所有问题编写为扁平编号列表——不分组
验证每个系统级占位符都有对应的问题
验证每次运行变量由SKILL.md参数处理，而非问卷
运行审核检查：
- 每个系统级占位符都有问题
- 问卷中没有每次运行变量
- 扁平结构（无类别分组）
- 每个问题都有默认值或示例

输出： 在流程文件夹中写入

setup/questionnaire.md

，遵循questionnaire-template格式。

如果流程没有用户特定变量（无需配置的纯系统流程），则编写一个极简问卷，内容为“No configuration needed”，并跳过占位符替换。

Stage 05: Validation

阶段05：验证

Same as ICM workspace-builder Stage 05. All 13 checks.

Input: The scaffolded procedure from Stage 03, the questionnaire from Stage 04.

Process:

Run each check. Record pass/fail and issues found.

Cross-reference integrity. Every file path in any CONTEXT.md Inputs table must point to a real file. List broken references.
No circular dependencies. Trace the reference graph. Confirm it is a directed acyclic graph.
Placeholder coverage. Scan all files for
```
{{PLACEHOLDER}}
```
patterns. Every placeholder must have a question in the questionnaire. Every question must map to at least one file. List orphans.
Conditional section validity. Every
```
{{?SECTION}}...{{/SECTION}}
```
block wraps a complete section (heading + content). No inline conditionals.
Stage handoff chain. Stage N's output location matches Stage N+1's Inputs table reference. List the chain, flag gaps.
CONTEXT.md purity. No CONTEXT.md contains actual reference content. Only: title, description, Inputs table, Process steps, Checkpoints (optional), Audit (optional), Outputs table.
Checkpoints in creative stages. Creative stages have at least one checkpoint. Checkpoint tables reference valid step numbers.
Audits in creative/build stages. Creative and build stages have Audit sections with specific pass conditions.
Contract purity. Spec stages define WHAT and WHEN, not HOW. No implementation details in spec outputs.
Line count check. Flag any CONTEXT.md over 80 lines. Flag any reference file over 200 lines.
Naming conventions.
```
lowercase-with-hyphens
```
. Zero-padded stage prefixes.
```
.gitkeep
```
in empty
```
output/
```
folders.
Tool prerequisites. If tool setup guides exist: each listed tool has a guide, guides include install steps and verification commands.
Quality scan. No em dashes (replace with
```
--
```
). No jargon without explanation. Clean markdown formatting.

Fix any failures in the scaffolded procedure, then re-run the failed checks.

Output: Write

validation-report.md

to the working directory. Format:

markdown

undefined

与ICM workspace-builder的阶段05相同。包含全部13项检查。

输入： 阶段03搭建的脚手架流程，阶段04生成的问卷。

流程：

运行每项检查，记录通过/失败情况及发现的问题。

交叉引用完整性。 任何CONTEXT.md输入表中的文件路径都必须指向真实文件。列出损坏的引用。
无循环依赖。 追踪引用图，确认其为有向无环图。
占位符覆盖。 扫描所有文件查找
```
{{PLACEHOLDER}}
```
模式。每个占位符必须在问卷中有对应的问题。每个问题必须至少映射到一个文件。列出孤立项。
条件章节有效性。 每个
```
{{?SECTION}}...{{/SECTION}}
```
块必须包裹完整的章节（标题+内容）。不允许内联条件。
阶段交接链。 阶段N的输出位置与阶段N+1的输入表引用匹配。列出链条，标记缺口。
CONTEXT.md纯净度。 CONTEXT.md中不得包含实际参考内容。只能包含：标题、描述、输入表、流程步骤、检查点（可选）、审核（可选）、输出表。
创意阶段的检查点。 创意阶段至少有一个检查点。检查点表引用有效的步骤编号。
创意/构建阶段的审核。 创意和构建阶段有包含具体通过条件的审核章节。
契约纯净度。 规范阶段定义做什么和何时做，而非怎么做。规范输出中不得包含实现细节。
行数检查。 标记任何超过80行的CONTEXT.md。标记任何超过200行的参考文件。
命名约定。 使用
```
lowercase-with-hyphens
```
格式。阶段前缀使用零填充。空的
```
output/
```
文件夹中有
```
.gitkeep
```
。
工具前置条件。 如果存在工具设置指南：每个列出的工具都有指南，指南包含安装步骤和验证命令。
质量扫描。 无破折号（替换为
```
--
```
）。无不加解释的行话。markdown格式整洁。

修复脚手架流程中的任何失败项，然后重新运行失败的检查。

输出： 在工作目录中写入

validation-report.md

。格式如下：

markdown

undefined

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>

#	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>

<description of fix>

Summary

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

undefined

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

undefined

Error Handling

错误处理

Spec has fewer than 2 stages -- stop. A single-stage process is a skill, not a procedure.

Stage CONTEXT.md exceeds 80 lines -- move content to

references/

. This is a hard cap.

Circular dependency found -- report the cycle. The spec must be restructured.

Validation check fails after fix attempt -- report the failure. Do not ship with known failures.

规范包含少于2个阶段——停止。单阶段流程是skill，而非流程。

阶段CONTEXT.md超过80行——将内容移至

references/

。这是硬性限制。

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

修复尝试后验证检查仍失败——报告失败。不得在存在已知失败的情况下交付。

Description Rule

描述规则

ICM procedure descriptions are especially prone to mechanics descriptions. Stage counts, parallelism notes, and "SEQUENTIAL" flags belong in the procedure body -- never in the

description:

frontmatter.

Good	Bad
"Use when merging reviewed PRs into a release branch."	"8-stage FULLY SEQUENTIAL ICM procedure that merges N reviewed PRs..."
"Use when running the full issue-to-PR pipeline."	"Issue-to-PR pipeline as an ICM procedure -- 7 stages from pre-flight..."
"Use when running the CTO flow-optimization loop."	"Flow optimizer operating loop -- WIP scan, active epic focus, triage..."

Self-check before writing SKILL.md: Strip the description of all stage counts and parallelism notes. What remains must still answer "when do I reach for this procedure?" If not, rewrite it.

Accepted trigger forms: "Use when ...", "Use to ...". Stage counts and "SEQUENTIAL / PARALLEL" notes live in the body (## Procedure, ## Stages, or ## When to Use sections).

ICM流程描述尤其容易包含机制性描述。阶段数量、并行性说明和"SEQUENTIAL"标志应放在流程主体中——绝不能放在

description:

前置元数据中。

正确示例	错误示例
"Use when merging reviewed PRs into a release branch."	"8-stage FULLY SEQUENTIAL ICM procedure that merges N reviewed PRs..."
"Use when running the full issue-to-PR pipeline."	"Issue-to-PR pipeline as an ICM procedure -- 7 stages from pre-flight..."
"Use when running the CTO flow-optimization loop."	"Flow optimizer operating loop -- WIP scan, active epic focus, triage..."

编写SKILL.md前的自我检查： 移除描述中的所有阶段数量和并行性说明。剩余内容仍需能回答“何时使用此流程？”如果不能，则重写。

接受的触发形式："Use when ..."、"Use to ..."。阶段数量和"SEQUENTIAL / PARALLEL"说明放在主体中（## Procedure、## Stages或## When to Use章节）。

Critical Rules

关键规则

Follow every ICM convention. All 15 patterns from CONVENTIONS.md apply. Do not skip any.
Produce all five artifacts. workflow-map.md, stage-contracts.md, the procedure folder, questionnaire.md, validation-report.md. Even if a stage seems trivial, produce its artifact.
80-line CONTEXT.md cap is hard. Not a guideline. Move content to references.
200-line reference file cap is hard. Split if exceeded.
Selective section routing. Inputs tables specify which SECTION to load, not just file paths.
Working artifacts in repo, not skill. Output path:
```
$REPO_DIR/.procedure-output/<name>/
```
.
No em dashes. Use
```
--
```
.
Every validation check must pass. Do not report success with known failures.
Templates are mandatory. Use the stage-context-template and questionnaire-template formats from
```
_core/templates/
```
. Do not invent your own format.

遵循所有ICM约定。 CONVENTIONS.md中的所有15种模式均适用。不得跳过任何一种。
生成全部五个工件。 workflow-map.md、stage-contracts.md、流程文件夹、questionnaire.md、validation-report.md。即使某个阶段看似简单，也要生成其工件。
CONTEXT.md的80行限制是硬性的。 不是指南。将内容移至参考文件。
参考文件的200行限制是硬性的。 如果超出，拆分文件。
选择性章节路由。 输入表指定要加载的章节，而非仅文件路径。
工作工件位于仓库中，而非skill中。 输出路径：
```
$REPO_DIR/.procedure-output/<name>/
```
。
无破折号。 使用
```
--
```
。
所有验证检查必须通过。 不得在存在已知失败的情况下报告成功。
模板是强制性的。 使用
```
_core/templates/
```
中的stage-context-template和questionnaire-template格式。不得自行发明格式。

procedure-builder

Original

Translation

procedure-builder

procedure-builder

When to Use

使用场景

When NOT to Use

非适用场景

Prerequisites

前置条件

Procedure

流程步骤

Stage 00: Bootstrap _core/

阶段00：初始化_core/

Bootstrap Result

Bootstrap Result

Stage 01: Discovery

阶段01：发现

Workflow Map: <procedure-name>

Workflow Map: <procedure-name>

Target

Target

Stages

Stages

01-<name>

01-<name>

02-<name>

02-<name>

Shared Context

Shared Context

User-Specific Variables

User-Specific Variables

Optional Stages

Optional Stages

Tool Prerequisites

Tool Prerequisites

Selected Skills

Selected Skills

Stage 02: Mapping

阶段02：映射

Stage Contracts: <procedure-name>

Stage Contracts: <procedure-name>

Dependency Diagram

Dependency Diagram

Stage 01: <name>

Stage 01: <name>

Inputs

Inputs

Process

Process

Checkpoints (if applicable)

Checkpoints (if applicable)

Audit (if applicable)

Audit (if applicable)

Outputs

Outputs

Stage 02: <name>

Stage 02: <name>

Stage 03: Scaffolding

阶段03：脚手架搭建

Stage 04: Questionnaire Design

阶段04：问卷设计

Stage 05: Validation

阶段05：验证

Validation Report: <procedure-name>

Validation Report: <procedure-name>

Results

Results

Issues Fixed

Issues Fixed

Summary

Summary

Error Handling

错误处理

Description Rule

描述规则

Critical Rules

关键规则

Stage 00: Bootstrap
`_core/`

阶段00：初始化
`_core/`