procedure-builder

procedure-builder

構造化された spec ファイルから、完全な ICM（Interpreted Context Methodology）プロシージャを構築します。初回実行時に _core/ をブートストラップし、その後は ICM workspace-builder の 5 段階パイプラインに従います。

使用する場合

• 新しい複数段階のワークフロー（speckit、deps-check、レビュー用パイプラインなど）を構築する場合
• 既存のモノリシックなランナースキルを段階的なプロシージャに変換する場合
• チームのリポジトリ向けにドメイン固有のプロシージャ（マーケティング、オンボーディングなど）を作成する場合

使用しない場合

• 1 段階の操作の場合――代わりに通常のスキルを使用してください
• 各段階で人との対話が必要なインタラクティブなワークフローの場合

前提条件

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

spec ファイルは references/spec-format.md の形式に従う必要があります。

プロシージャ

このスキルは 6 段階を順番に実行します。最初の段階は 1 回限りのブートストラップです。残りの 5 段階は ICM workspace-builder と完全に同じです。各段階で、次の段階に渡す成果物を生成します。

開始前に references/icm-conventions.md を読んでください。すべての規約が適用されます。

Stage 00: _core/ のブートストラップ

足場を構築する前に、ワークスペースのリポジトリルートに正規の ICM _core/ ディレクトリがあることを確認してください。 これにより、新しいリポジトリを 1 つのコマンドで ICM に準拠させ、後続の段階をオフラインで決定論的に実行できます。毎回の実行時に確認し、すでにブートストラップ済みの場合は何もしません。

入力： 現在の作業ディレクトリ（リポジトリのルートである必要があります）。

プロセス：

1. リポジトリルートに _core/ があるか確認します。

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

2. 存在する場合は Stage 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/ が不完全なまま Stage 01 に進んではいけません。

Stage 01: Discovery

ICM workspace-builder の Stage 01 と同じですが、ユーザーへの聞き取りではなく、仕様ファイルを読み込みます。

入力： $1 にある仕様ファイル。

プロセス：

1. 仕様ファイルをすべて読み込みます
2. 手順名、目的を示す1行の説明、対象ディレクトリ、引数を抽出します
3. 仕様に記載されている各ステージについて、次の情報を抽出します。
   • 入力となるもの（ファイル、API レスポンス、引数、前のステージの出力）
   • 出力されるもの（このステージが生成する成果物とその形式）
   • エージェントが把握しておくべきこと（参考資料、ルール、制約）
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: Mapping

ICM workspace-builder の Stage 02 と同じです。

入力： Stage 01 で作成した workflow-map.md。

プロセス：

1. ワークフローマップを読み込みます
2. 各ステージについて、ICM Pattern 1（Stage Contracts）に従い、正式な Inputs/Process/Outputs コントラクトを作成します。形式には stage-context-template を使用します。
   • 必要なセクションだけを指定して振り分ける Inputs テーブル（ファイル名だけでなく、ファイル内のどの SECTION かを指定します）
   • 番号付きのプロセス手順（曖昧な説明ではなく、具体的な作業を記載します）
   • 成果物名、場所、形式を記載した Outputs テーブル
3. 各ステージについて、次の点を判断します。
   • Checkpoint セクションが必要か（クリエイティブなステージでは必要、直線的なステージでは不要）
   • Audit セクションが必要か（クリエイティブなステージと構築ステージでは必要、抽出／変換では不要）
4. 相互参照をマッピングします。どのステージがどのステージから読み取るかを示す依存関係グラフを作成します
5. 正規の情報源を確認します。各情報の情報源は1か所だけにします
6. 一方向の参照を確認します。A が B を参照する場合、B は A を参照しません
7. すべてのステージの出力が、少なくとも1つの後続ステージで使用されるか、最終成果物であることを確認します
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 を作成します：
   • タイトルと目的を示す1文
   • 入力テーブル（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-）を使用している

出力： 対象ディレクトリに作成された、完全な手順フォルダー。

Stage 04: アンケートの設計

ICM ワークスペースビルダーの Stage 04 と同じです。

入力： Stage 01 の workflow-map.md（ユーザー固有の変数用）、Stage 03 でスキャフォールディングした手順。

プロセス：

1. ワークフローマップのユーザー固有の変数セクションを読みます
2. スキャフォールディングした手順に含まれるすべての Markdown ファイルを確認し、{{PLACEHOLDER}} のパターンを探します。完全なリストを作成します。
3. 変数を次の 2 つのグループに分けます。
   • システムレベル： 実行のたびに変わらないもの（API エンドポイント、認証情報の設定、チームの識別情報、ツールの設定など）。これらはセットアップ時の質問になります。
   • 実行ごと： パイプラインの実行ごとに変わるもの（Issue 番号、リポジトリ、対象ブランチなど）。これらはセットアップ時の質問にはなりません。SKILL.md が引数として収集します。
4. システムレベルの各プレースホルダーについて、質問を作成します。
   • 質問文（平易な英語で、専門用語を使わない）
   • 値を設定するプレースホルダー
   • プレースホルダーが記載されているファイル
   • 入力形式（自由記述、選択式、はい／いいえ）
   • 適切なデフォルト値または例
5. オプションのステージに関する「はい／いいえ」の質問では、「いいえ」の場合に削除するステージフォルダーを指定します
6. すべての質問を、カテゴリでグループ分けせず、フラットな番号付きリストとして記述します
7. すべてのシステムレベルのプレースホルダーに対応する質問があることを確認します
8. 実行ごとの変数はアンケートではなく、SKILL.md の引数で処理されることを確認します
9. 次の監査項目を確認します。
   • すべてのシステムレベルのプレースホルダーに質問がある
   • アンケートに実行ごとの変数が含まれていない
   • フラットな構成になっている（カテゴリでグループ分けされていない）
   • すべての質問にデフォルト値または例がある

出力： アンケートテンプレートの形式に従って、手順フォルダー内に setup/questionnaire.md を作成します。

手順にユーザー固有の変数がない場合（設定不要の純粋なシステム手順）は、「No configuration needed」と記載した最小限のアンケートを作成し、プレースホルダーの置換を省略します。

Stage 05: 検証

ICM workspace-builder Stage 05と同じです。13項目すべてを確認します。

入力： Stage 03で作成したスキャフォールド済みの手順、Stage 04の質問票。

プロセス：

各項目を確認します。合否と、見つかった問題を記録します。

1. 相互参照の整合性。 どのCONT​EXT.mdのInputs表にあるファイルパスも、実在するファイルを指している必要があります。参照切れを一覧表示します。

2. 循環依存がないこと。 参照グラフをたどります。有向非巡回グラフであることを確認します。

3. プレースホルダーの網羅性。 すべてのファイルをスキャンして、{{PLACEHOLDER}}パターンを探します。すべてのプレースホルダーに、質問票内の質問が必要です。すべての質問が、少なくとも1つのファイルに対応している必要があります。対応先のない項目を一覧表示します。

4. 条件付きセクションの妥当性。 すべての{{?SECTION}}...{{/SECTION}}ブロックが、完全なセクション（見出し＋内容）を囲んでいる必要があります。インライン条件分岐は使用できません。

5. ステージ間の引き継ぎチェーン。 Stage Nの出力先が、Stage N+1のInputs表にある参照先と一致している必要があります。チェーンを一覧表示し、欠落箇所に印を付けます。

6. CONTEXT.mdの内容の純粋性。 CONTEXT.mdに実際の参照コンテンツが含まれていないことを確認します。含めてよいのは、タイトル、説明、Inputs表、Processの手順、Checkpoints（任意）、Audit（任意）、Outputs表のみです。

7. 創造的なステージのチェックポイント。 創造的なステージには、少なくとも1つのチェックポイントが必要です。チェックポイント表で参照されているステップ番号が有効であることを確認します。

8. 創造的なステージ／ビルドステージの監査。 創造的なステージとビルドステージには、具体的な合格条件を含むAuditセクションが必要です。

9. 仕様の純粋性。 仕様ステージでは、HOWではなくWHATとWHENを定義します。仕様の出力に実装の詳細を含めてはいけません。

10. 行数チェック。 80行を超えるCONTEXT.mdに印を付けます。200行を超える参照ファイルに印を付けます。

11. 命名規則。 lowercase-with-hyphens形式を使用します。ステージのプレフィックスはゼロ埋めします。空の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つ未満の場合 -- 停止します。単一ステージのプロセスは手順ではなく、スキルです。

ステージのCONTEXT.mdが80行を超える場合 -- 内容をreferences/に移します。これは厳守すべき上限です。

循環依存が見つかった場合 -- 循環箇所を報告します。仕様を再構成する必要があります。

修正を試みた後も検証項目に失敗する場合 -- 失敗を報告します。既知の失敗がある状態でリリースしてはいけません。

説明のルール

ICM手順の説明には、仕組みの説明が含まれがちです。ステージ数、並列性に関する注記、「SEQUENTIAL」フラグは手順の本文に記載し、description:フロントマターには決して記載しないでください。

良い例	悪い例
「レビュー済みPRをリリースブランチにマージするときに使用します。」	「N件のレビュー済みPRをマージする8ステージの完全順次型ICM手順...」
「課題からPRまでの完全なパイプラインを実行するときに使用します。」	「ICM手順としての課題からPRまでのパイプライン -- プリフライトから始まる7ステージ...」
「CTOのフロー最適化ループを実行するときに使用します。」	「フロー最適化の運用ループ -- WIPスキャン、アクティブなエピックへの集中、トリアージ...」

SKILL.mdを作成する前のセルフチェック： 説明から、ステージ数と並列性に関する注記をすべて取り除きます。残った説明だけで、「どのようなときにこの手順を使うか」に答えられる必要があります。答えられない場合は、書き直します。

使用できるトリガー形式：「次の場合に使用します...」、「...するために使用します」。ステージ数と「SEQUENTIAL／PARALLEL」に関する注記は本文の（## Procedure、## Stages、または## When to Useセクション）に記載します。

重要なルール

• ICM のすべての規約に従ってください。 CONVENTIONS.md の 15 個のパターンをすべて適用します。省略しないでください。
• 5 つの成果物をすべて作成してください。 workflow-map.md、stage-contracts.md、procedure フォルダー、questionnaire.md、validation-report.md を作成します。あるステージが単純に見える場合でも、その成果物を作成してください。
• CONTEXT.md の 80 行上限は厳守してください。 目安ではありません。内容は references に移してください。
• 参照ファイルの 200 行上限は厳守してください。 超える場合は分割してください。
• セクションを選択して読み込んでください。 Inputs テーブルには、ファイルパスだけでなく読み込む SECTION を指定します。
• 作業用成果物はスキル内ではなく、リポジトリ内に置いてください。 出力先のパス：$REPO_DIR/.procedure-output/<name>/。
• em dash は使用しないでください。 -- を使用してください。
• すべての検証チェックに合格する必要があります。 既知の失敗がある状態で成功を報告しないでください。
• テンプレートは必須です。 _core/templates/ の stage-context-template と questionnaire-template の形式を使用してください。独自の形式を考案しないでください。