# Bootstrap

> Stamps any repo with the IMO-Creator doctrine skeleton. Trigger: Developer runs /bootstrap in any repo root. Output: Doctrine-compliant file skeleton stamped for detected tier (Garage / Car / Sub-Hub). Non-destructive — fills missing files only, never overwrites existing doctrine.

- Skill: `djb258/bootstrap` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add djb258/bootstrap`
- Raw SKILL.md: https://api.skillmd.com/api/skills/djb258/bootstrap/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: djb258 (https://skillmd.com/u/djb258)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/djb258/bootstrap

---


## IMO — Ingress / Middle / Egress

**Ingress (Trigger):** Developer runs /bootstrap in a repo root. Optionally passes
`--tier=garage|car|sub-hub` to declare tier explicitly.

**Middle (Processing):**
- Detect or accept tier declaration
- Read existing repo file inventory
- Compare against required skeleton for detected tier
- Stamp missing files only from imo-creator templates
- Confirm sovereign ID present or prompt for declaration
- Produce bootstrap report

**Egress (Output):** Missing doctrine files stamped at repo root and /ADRs/.
Bootstrap report listing what was created, what already existed, and sovereign ID status.

**Go/No-Go Gate:** Do not close until bootstrap report confirms zero missing required
files for the declared tier and sovereign ID is declared.

---

## Constants — What Is Fixed About Every Bootstrap Run

1. Bootstrap is always non-destructive. Existing files are never overwritten.
2. Tier determines the required file skeleton. Tier is always declared — never inferred silently.
3. Sovereign ID must be declared before bootstrap closes. No exceptions.
4. All stamped files come from imo-creator templates. No hand-written files during bootstrap.
5. Bootstrap produces a report. A run with no report is not complete.
6. ADR-000-template.md is always stamped regardless of tier.
7. Doctrine flows DOWN. Bootstrap reads from imo-creator. It never modifies imo-creator.
8. If imo-creator path cannot be resolved, bootstrap halts immediately — it does not guess.

---

## Variables — What Changes Per Invocation

| Variable | What It Is | Who Sets It |
|----------|-----------|-------------|
| `target_repo_path` | Absolute path to repo being bootstrapped | Detected from working directory |
| `tier` | Garage / Car / Sub-Hub | Developer declaration or Phase 1 detection |
| `sovereign_id` | Unique ID connecting this repo to its parent hub | Developer declaration |
| `imo_creator_path` | Path to imo-creator templates | Resolved from FLEET_REGISTRY or declared |
| `missing_files` | List of required files not yet present | Computed in Phase 2 |

---

## Hub-and-Spoke Configuration

The bootstrap process is a wheel. Hub is the stamped repo. Each spoke is a phase.

| Spoke | Input | Output | Interface to Hub |
|-------|-------|--------|-----------------|
| Detect | Repo path + optional --tier flag | Confirmed tier | Go/No-Go: tier is unambiguous |
| Inventory | Repo file list | Missing file list per tier | Go/No-Go: delta computed, no unknowns |
| Resolve | imo-creator path | Template file paths confirmed | Go/No-Go: all templates found |
| Stamp | Missing file list + templates | Files written to repo | Go/No-Go: all missing files now present |
| Sovereign | Repo state | Sovereign ID declared in CLAUDE.md | Go/No-Go: sovereign ID present |
| Report | Completed repo state | Bootstrap report | Final output — task complete |

**Hub rule:** Each spoke completes and returns to hub. Spokes do not call other spokes.

---

## Rules — What This Skill Never Does

- Never overwrite an existing file. If it exists, skip it and note it in the report.
- Never stamp files without a confirmed tier. Tier ambiguity halts bootstrap.
- Never generate sovereign ID automatically. Developer declares it — bootstrap confirms it.
- Never modify imo-creator templates. Read only. Doctrine flows down, never up.
- Never close without a bootstrap report. Silent completion is not completion.
- Never stamp a sub-hub without confirming its parent Car repo is already bootstrapped.
- Never put tool names or repo-specific values in the stamped CLAUDE.md Constants block.

---

## Tier Skeletons — Required Files Per Tier

### GARAGE (imo-creator itself)
```
CLAUDE.md
CONSTITUTION.md
README.md
FLEET_REGISTRY.yaml
ADR_INDEX.md
REPO_HOUSEKEEPING.md
/templates/  (already exists)
/ADRs/ADR-000-template.md
```

### CAR REPO (e.g. UT, barton-outreach-core)
```
CLAUDE.md              (9-section skeleton — defer to Garage)
README.md              (repo-specific orientation)
SYSTEM_MAP.md          (hub/spoke/data flow map)
/ADRs/ADR-000-template.md
/docs/OSAM.md          (routing contract)
/docs/PRD.md           (what this repo does + why)
```

### SUB-HUB (e.g. Fetcher, Parser Registry)
```
CLAUDE.md              (thin — identity + pointer to Car CLAUDE.md)
README.md              (sub-hub purpose, spokes, triggers)
/docs/PRD.md           (required — if you can't write it, don't build it)
/docs/OSAM.md          (routing contract)
/ADRs/ADR-000-template.md
```

---

## Workflow

### Phase 1 — Detect Tier (Spoke 1)

**Constants for this phase:**
- Tier must be one of exactly three values: Garage / Car / Sub-Hub.
- If --tier flag is passed, accept it. If not, ask — never infer silently.
- A repo that looks like a Car but has no FLEET_REGISTRY.yaml is a Car, not a Garage.

**Variables for this phase:**
- Whether --tier flag was passed.
- Repo contents used for detection hints.

**Execute:**
1. Check for --tier flag. If present, accept and proceed.
2. If no flag: scan repo root for FLEET_REGISTRY.yaml (Garage signal),
   CONSTITUTION.md (Garage signal), or neither (Car/Sub-Hub).
3. If ambiguous between Car and Sub-Hub, ask: "Does this repo have its own
   hub processing logic, or is it a domain within a Car repo?"
4. Confirm tier with developer before proceeding.

**Go/No-Go:** Tier is declared and confirmed. If not confirmed, halt and ask.

---

### Phase 2 — Inventory (Spoke 2)

**Constants for this phase:**
- Required file list is determined by tier skeleton above. It is a Constant per tier.
- A file that exists but is empty counts as present — bootstrap does not validate content.
- Only root-level and /docs/ and /ADRs/ files are in scope. Bootstrap does not recurse deeper.

**Variables for this phase:**
- Which specific files are missing in this repo.

**Execute:**
1. Load required file list for confirmed tier.
2. Check repo root, /docs/, and /ADRs/ for each required file.
3. Build two lists: PRESENT (skip) and MISSING (stamp).
4. Display both lists to developer before proceeding.

**Go/No-Go:** Missing file list is complete and confirmed. Developer has seen it.

---

### Phase 3 — Resolve Templates (Spoke 3)

**Constants for this phase:**
- All templates come from imo-creator. No other source.
- If imo-creator path cannot be resolved, halt immediately.
- Template paths are fixed per the CLAUDE.md locked file registry.

**Variables for this phase:**
- Actual resolved path to imo-creator on this machine.

**Execute:**
1. Check for imo-creator path in FLEET_REGISTRY.yaml or ask developer.
2. Verify each required template exists at resolved path.
3. Map: missing file → source template path.

**Go/No-Go:** Every missing file has a confirmed source template. If any template
is missing from imo-creator, halt and report — do not improvise.

---

### Phase 4 — Stamp (Spoke 4)

**Constants for this phase:**
- Stamp = copy template to target path. No modification of template content
  except replacing [REPO_NAME], [TIER], [DATE], [SOVEREIGN_ID] placeholders.
- Never overwrite. If file appeared between Phase 2 and Phase 4, skip it.
- Placeholder replacement is the only permitted modification during stamp.

**Variables for this phase:**
- The specific placeholder values for this repo.

**Execute:**
1. For each file in MISSING list:
   - Copy from source template to target path.
   - Replace placeholders: [REPO_NAME], [TIER], [DATE], [SOVEREIGN_ID].
   - Confirm file written.
2. Log each stamped file: path + source template.

**Go/No-Go:** Every file in MISSING list now exists in repo. Zero failures.

---

### Phase 5 — Sovereign ID (Spoke 5)

**Constants for this phase:**
- Sovereign ID is always declared by the developer. Never generated.
- Sovereign ID must appear in CLAUDE.md Section 01 (Repo Identity).
- Format follows HEIR naming convention: H.E.I.R notation per imo-creator doctrine.

**Variables for this phase:**
- The actual sovereign ID value for this repo.

**Execute:**
1. Check CLAUDE.md Section 01 for sovereign ID field.
2. If present: confirm with developer and proceed.
3. If absent: ask developer to declare it now. Insert into CLAUDE.md Section 01.

**Go/No-Go:** Sovereign ID is declared and present in CLAUDE.md. If not, do not close.

---

### Phase 6 — Report (Spoke 6)

**Constants for this phase:**
- Report always has four sections: Tier, Files Stamped, Files Skipped, Sovereign ID.
- A bootstrap with zero files stamped is still a valid run — it means the repo was
  already compliant. Report it as such.

**Execute:**
Produce bootstrap report in this format:

```
BOOTSTRAP REPORT
────────────────
Repo:         [repo name]
Tier:         [Garage / Car / Sub-Hub]
Date:         [date]
Sovereign ID: [value]

FILES STAMPED (created)
  → [file path] (from [template source])
  → ...

FILES SKIPPED (already present)
  → [file path]
  → ...

STATUS: COMPLETE — repo is doctrine-compliant for [tier] tier.
```

**Go/No-Go:** Report produced and shown to developer. Task complete.

---

## Phase Failure Handling

**IMO of a Phase Failure:**
- **Ingress:** Phase produces unexpected result not matching defined output.
- **Middle:** Log three fields — (1) which phase failed, (2) what was attempted,
  (3) what was returned. Do not guess. Do not retry silently.
- **Egress:** Escalate to developer with three-field log. Ask for direction.

**OTHER path:** If failure cannot be classified, log to error with
`phase_failed`, `attempted_action`, `raw_output`. Do not resolve without developer input.

---

## CTB Backbone Mapping

Bootstrap output maps to repo structure:
- CLAUDE.md → constitutional layer (CANONICAL — do not modify after stamp without ADR)
- SYSTEM_MAP.md → architectural declaration
- /docs/PRD.md → transformation proof (CONST → VAR)
- /docs/OSAM.md → routing contract
- /ADRs/ → decision log

Bootstrap IS the Day 0 structural proof. A repo that has passed bootstrap has
satisfied the structural instantiation requirement per CONSTITUTION.md.

---

## Reference Files

| File | Contains | Load When |
|------|----------|-----------|
| `references/tier-skeletons.md` | Full required file list per tier with template mappings | Phase 2 — building missing file list |
| `references/placeholder-map.md` | All valid placeholders and replacement rules | Phase 4 — stamping files |

---

## Observability

- Bootstrap report IS the telemetry. Every run produces one.
- Failed phases log three-field entries before escalating.
- A bootstrap run with no report = audit violation. Treat as Phase 6 failure.