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.

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.)

When NOT to Use

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

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

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.

Stage 00: Bootstrap

_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

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

Stage 01: Discovery

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

# 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

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

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

Stage 03: Scaffolding

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.

Stage 04: Questionnaire Design

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.

Stage 05: Validation

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

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

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.

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).

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.

procedure-builder

NPX Install

Tags

SKILL.md Content

procedure-builder

When to Use

When NOT to Use

Prerequisites

Procedure

Stage 00: Bootstrap
`_core/`

Stage 01: Discovery

Stage 02: Mapping

Stage 03: Scaffolding

Stage 04: Questionnaire Design

Stage 05: Validation

Error Handling

Description Rule

Critical Rules