Bootstrap Skill

Overview

This skill runs when the Bootstrap Gate is closed (missing CLAUDE.md, Session Config, or .orchestrator/bootstrap.lock) or when the user invokes /bootstrap directly. It scaffolds the minimum structure required by all session-orchestrator skills, commits it, and writes the lock file that opens the gate for all future invocations.

Anti-bureaucracy contract: On a first-time full bootstrap (no tier flags, no --no-interview), expect 7–9 AskUserQuestion prompts in three fixed blocks — not an open-ended wizard. (1) Tier/stack (Phase 2): one tier-confirmation question, plus an optional second archetype question when PATH_TYPE = public and archetype confidence is low (Standard/Deep only). (2) Owner persona (Phase 3.5): five questions from scripts/lib/owner-interview.mjs (first-run only). (3) Dispatcher autonomy (Phase 3.5.1): one question from scripts/lib/config/dispatcher-autonomy-capture.mjs. Flagged flows (--upgrade, --retroactive, --sync-rules, --ecosystem-health) and --no-interview skip some or all of these blocks.

Invocation Context

Before starting, determine how this skill was invoked:

• Transitive (gate-closed): Invoked from another skill's Phase 0. The user's original intent (their first prompt) is available in context. After bootstrap completes, execution must return to the original skill's Phase 1.
• Direct (/bootstrap): User invoked manually. Parse $ARGUMENTS for flags: --fast, --standard, --deep, --upgrade <tier>, --retroactive. See commands/bootstrap.md for flag semantics.

Store INVOCATION_MODE = transitive | direct.

Mode dispatch (direct invocation only):

• If --upgrade <tier> is present in $ARGUMENTS: jump to Upgrade Flow section. Do not proceed to Phase 1.
• If --retroactive is present in $ARGUMENTS: jump to Retroactive Flow section. Do not proceed to Phase 1.
• If --refresh-lock is present in $ARGUMENTS: jump to Refresh-Lock Flow section. Do not proceed to Phase 1.
• If --sync-rules is present in $ARGUMENTS: jump to Sync-Rules Flow section. Do not proceed to Phase 1.
• If --ecosystem-health is present in $ARGUMENTS: jump to Ecosystem-Health Flow section. Do not proceed to Phase 1.
• Otherwise: continue to Phase 1 below.

Phase 0.5: Determine Private vs. Public Path

Before dispatching to any tier template, read skills/bootstrap/public-fallback.md and execute Step 1 (PATH_TYPE detection). Store the result as PATH_TYPE = private | public. This detection is silent — no user interaction.

• private: the existing host-local config resolution found a baseline directory and its reduced contract validated. Use private-contract.md for selection, templates, commands, CI and rules.
• public: the resolved baseline is absent, empty, or points to a missing directory. Use plugin-bundled templates.
• Existing but invalid configured baseline: abort before dispatch; report the reader's sanitized error reason.

Pass PATH_TYPE into Phase 1 and all subsequent phases. All tier templates (fast-template.md, standard-template.md, deep-template.md) must consult public-fallback.md for CLAUDE.md generation and archetype file sourcing when PATH_TYPE = public.

Phase 1: Detect Tier + Archetype

Read skills/bootstrap/intensity-heuristic.md and execute the tier + archetype recommendation algorithm.

Inputs to the heuristic:

1. User's first prompt — the message that triggered this skill (most important signal)
2. Repo name — basename $(git rev-parse --show-toplevel) (secondary signal)
3. Existing files — ls -la of repo root (presence of package.json, pyproject.toml, etc. shifts archetype)
4. $ARGUMENTS flags — if --fast, --standard, or --deep is present, skip heuristic and use the specified tier directly

Output from Phase 1:

• RECOMMENDED_TIER = fast | standard | deep
• RECOMMENDED_ARCHETYPE = validated private contract ID, public ID, or null
• HEURISTIC_REASON = one-sentence explanation of why this tier was chosen (shown to user)
• PATH_TYPE = private (plan-baseline-path configured and path exists) | public (no baseline)

Detecting PATH_TYPE: Already determined in Phase 0.5 — use the stored PATH_TYPE value. Do not re-run detection.

Fast tier: RECOMMENDED_ARCHETYPE is always null. No stack selection needed.

Phase 2: Present Tier Confirmation (One Question)

Present exactly one AskUserQuestion unless:

• $ARGUMENTS includes --fast, --standard, or --deep (tier pre-selected, skip question)
• --retroactive flag (no scaffolding at all, skip to Phase 4)

AskUserQuestion({
  questions: [{
    question: "Leeres Repo erkannt. Basierend auf '<HEURISTIC_REASON>' empfehle ich **<RECOMMENDED_TIER>**. Passt das?",
    header: "Bootstrap",
    options: [
      { label: "fast", description: "Nur CLAUDE.md + .gitignore + README. Für Demos, Spikes, Playgrounds." },
      { label: "standard", description: "Fast + package.json/Manifest + TypeScript + Linting + Tests. Für MVPs und echte Produkte." },
      { label: "deep", description: "Standard + CI + CODEOWNERS + CHANGELOG. Für Production, Team, Langlebige Repos." },
      { label: "Abbrechen", description: "Bootstrap abbrechen. Das ursprüngliche Kommando wird ebenfalls abgebrochen." }
    ],
    multiSelect: false
  }]
})

Before rendering: append (Empfohlen) to whichever of the three tier labels equals <RECOMMENDED_TIER>, and move that option to position 1. The recommended tier is one of the three — listing it a fourth time as its own option made five options, one more than AskUserQuestion accepts, and repeated the same choice twice.

If user selects "Abbrechen": stop. Report "Bootstrap abgebrochen. Kein Kommando wird ausgeführt." Do not continue.

Store confirmed tier as CONFIRMED_TIER.

Optional Second Question (Public Path + Standard/Deep + Ambiguous Archetype Only)

If ALL of the following are true:

1. PATH_TYPE = public
2. CONFIRMED_TIER is standard or deep
3. intensity-heuristic.md returned ARCHETYPE_CONFIDENCE = low (truly ambiguous)

Then ask one more question — and only then:

AskUserQuestion({
  questions: [{
    question: "Welchen Tech-Stack soll ich für das Grundgerüst verwenden?",
    header: "Archetype",
    options: [
      { label: "node-minimal", description: "package.json + TypeScript + Vitest. Für CLIs, Tools, Libraries." },
      { label: "nextjs-minimal", description: "Next.js bare setup. Für Web Apps, SaaS, Fullstack." },
      { label: "static-html", description: "HTML/CSS/JS, kein Build-Step. Für Animationen, Landingpages, Visualisierungen." },
      { label: "python-uv", description: "pyproject.toml + uv + pytest. Für Python Scripts, APIs, ML." }
    ],
    multiSelect: false
  }]
})

Store as CONFIRMED_ARCHETYPE.

For PATH_TYPE = private and Standard/Deep, execute private-contract.md's Select section now. Reuse a valid detected or explicit ID; when evidence is insufficient, select from the returned catalog before scaffolding. Tier flags skip tier confirmation, not required private archetype selection. Never pass a null private ID into the public default. On upgrades, validate the lock's ID against the currently configured contract before generating any files.

The tier/stack block contributes 1–2 questions; a first-run full bootstrap adds 6 more from the owner interview (Phase 3.5, five questions) and dispatcher-autonomy capture (Phase 3.5.1, one question) — 7–9 total.

Upgrade Flow (--upgrade <tier>)

Entered when $ARGUMENTS contains --upgrade <tier>. No scaffolding questions are asked.

Steps:

1. Read existing lock. Read .orchestrator/bootstrap.lock. If missing, abort with: Error: No bootstrap.lock found. Run /bootstrap first to bootstrap this repo.

2. Parse current and target tier.

   • CURRENT_TIER = value of tier: field in the lock file.
   • TARGET_TIER = the <tier> argument supplied after --upgrade.
   • Valid values for both: fast | standard | deep.

3. Refuse downgrade. Tier order: fast < standard < deep. If TARGET_TIER ranks lower than or equal to CURRENT_TIER, abort with: Error: Cannot downgrade from <CURRENT_TIER> to <TARGET_TIER>. Upgrade path is one-directional (fast → standard → deep). Exit non-zero.

4. Resolve source and compute delta. Run Phase 0.5's read-only source detection before dispatching any template. For a private contract, validate the lock's archetype with --archetype; if the Fast lock has no archetype, select from the returned catalog using private-contract.md. Use its staged, additive scaffold and CI expectations; do not apply the public file matrix. For the public path, determine which files the target tier adds:

   • fast → standard: all Standard-tier files (package.json/pyproject.toml, tsconfig.json, eslint.config.mjs, .prettierrc, .editorconfig, tests/, src/)
   • standard → deep: all Deep-tier files (CI pipeline, CODEOWNERS, CHANGELOG.md, issue templates, MR/PR template, branch protection)
   • fast → deep: union of both deltas (apply Standard first, then Deep)

5. Check idempotency. For each file in the delta, skip if it already exists on disk. Only write files that are absent. This makes the operation safe to run twice.

6. Apply delta files. Execute only the relevant template steps for the missing files. Read the appropriate template (standard-template.md and/or deep-template.md) and execute ONLY the steps that produce the delta files. Do NOT re-run already-completed steps.

7. Update bootstrap.lock atomically. Overwrite .orchestrator/bootstrap.lock with tier: <TARGET_TIER>. Preserve a validated existing archetype; when upgrading a null Fast archetype, record the newly confirmed ID and scaffold source. Update timestamp to now. Preserve the prior source otherwise. Write plugin-version from $PLUGIN_ROOT/package.json (current plugin version at upgrade time).

8. Commit. Stage only the delta files that were just written and commit:

   # DELTA_FILES must be populated with the explicit list of files written in step 6
   for _f in "${DELTA_FILES[@]}"; do
     [[ -e "$_f" ]] && git add -- "$_f"
   done
   git commit -m "chore: bootstrap upgrade to <TARGET_TIER>"
   

9. Report. Print a one-line summary: Bootstrap upgraded from <CURRENT_TIER> to <TARGET_TIER>. <N> files added.

---

Retroactive Flow (--retroactive)

Entered when $ARGUMENTS contains --retroactive. Writes the lock file and, per #182, optionally patches missing mandatory Session Config fields with defaults.

Purpose: Adopt an existing repo that already has CLAUDE.md + ## Session Config but was bootstrapped manually (no bootstrap.lock). Writes the lock so the gate passes on all future invocations, and ensures the Session Config block satisfies the validated schema defined in scripts/lib/config-schema.mjs.

Steps:

1. Verify preconditions. Confirm CLAUDE.md (or AGENTS.md) exists and contains ## Session Config. If not, abort: Error: CLAUDE.md with Session Config required for retroactive bootstrap.

2. Check lock not already present. If .orchestrator/bootstrap.lock already exists and has valid version + tier fields, report: bootstrap.lock already present (tier: <tier>). Nothing to do. and exit 0 (idempotent).

3. Infer tier from file inventory. Examine the repo root:

   Condition (evaluated in order)	Inferred Tier
   CI file present (.gitlab-ci.yml OR .github/workflows/) AND CHANGELOG.md present	deep
   Package manifest present (package.json OR pyproject.toml)	standard
   Neither of the above	fast

   Store as INFERRED_TIER.

4. Infer archetype. Run Phase 0.5's read-only source detection. For a private contract, use its detected selected.id; retain null with an explicit insufficient-evidence report if no markers match. An invalid configured contract aborts. Do not scaffold or apply rules in this retroactive flow. For the public path, use best-effort detection from existing files:

   • pyproject.toml present → python-uv
   • package.json with next in dependencies → nextjs-minimal
   • package.json without next → node-minimal
   • No manifest → null

   Store as INFERRED_ARCHETYPE.

5. Write bootstrap.lock. Create .orchestrator/ if needed, then write:

   # .orchestrator/bootstrap.lock
   version: 1
   tier: <INFERRED_TIER>
   archetype: <INFERRED_ARCHETYPE or null>
   timestamp: <current ISO 8601 UTC>
   source: retroactive
   plugin-version: <current plugin version from $PLUGIN_ROOT/package.json>
   

6. Patch Session Config (#182). Run the validator against the current ## Session Config block; append any missing mandatory fields with defaults. The 7 mandatory fields (per scripts/lib/config-schema.mjs) are: test-command, typecheck-command, lint-command, agents-per-wave, waves, persistence, enforcement.

   CONFIG_OUT="$(node "$PLUGIN_ROOT/scripts/parse-config.mjs" 2>&1 >/dev/null)"
   # parse-config.mjs emits validation warnings to stderr when enforcement=warn.
   # Grep for 'must be' lines (issued by validate-config.mjs) to detect missing fields.
   MISSING_FIELDS="$(echo "$CONFIG_OUT" | grep -oE '(test-command|typecheck-command|lint-command|agents-per-wave|waves|persistence|enforcement)' | sort -u || true)"
   if [[ -n "$MISSING_FIELDS" ]]; then
     # Detect package manager to pick sensible defaults for commands.
     PM_DEFAULTS="$(node --input-type=module -e "
       import {detectPackageManager, defaultQualityGateCommands} from '$PLUGIN_ROOT/scripts/lib/package-manager.mjs';
       const pm = detectPackageManager(process.cwd());
       const cmds = defaultQualityGateCommands(pm);
       console.log('test-command: ' + cmds.test.command);
       console.log('typecheck-command: ' + cmds.typecheck.command);
       console.log('lint-command: ' + cmds.lint.command);
     " 2>/dev/null)"
   
     CONFIG_FILE="CLAUDE.md"
     [[ -f "AGENTS.md" ]] && CONFIG_FILE="AGENTS.md"
   
     # Append each missing field under the ## Session Config block.
     for field in $MISSING_FIELDS; do
       case "$field" in
         test-command|typecheck-command|lint-command)
           default_line="$(echo "$PM_DEFAULTS" | grep "^$field:")" ;;
         agents-per-wave) default_line="agents-per-wave: 6" ;;
         waves)           default_line="waves: 5" ;;
         persistence)     default_line="persistence: true" ;;
         enforcement)     default_line="enforcement: warn" ;;
       esac
       # Insert after `## Session Config` line if not already present.
       grep -q "^$field:" "$CONFIG_FILE" \
         || awk -v insert="$default_line" '/^## Session Config/ && !done { print; print ""; print insert; done=1; next } { print }' "$CONFIG_FILE" > "$CONFIG_FILE.tmp" \
         && mv "$CONFIG_FILE.tmp" "$CONFIG_FILE"
     done
     echo "Patched $CONFIG_FILE with defaults for: $MISSING_FIELDS"
   fi
   

   This patch is best-effort: existing fields are never overwritten. If no fields are missing, this step is a no-op.

7. Commit. Stage the lock file (and the patched config file, if it changed) and commit:

   mkdir -p .orchestrator
   git add .orchestrator/bootstrap.lock
   # Also stage CLAUDE.md/AGENTS.md if step 6 patched it.
   git diff --name-only --cached CLAUDE.md AGENTS.md 2>/dev/null | head -1 >/dev/null || {
     [[ -f CLAUDE.md ]] && git diff --quiet CLAUDE.md || git add CLAUDE.md
     [[ -f AGENTS.md ]] && git diff --quiet AGENTS.md || git add AGENTS.md
   }
   git commit -m "chore: bootstrap lock (retroactive)"
   

8. Report. Print: Retroactive bootstrap complete. Lock written (tier: <INFERRED_TIER>, source: retroactive). Include a second line Patched Session Config: <fields> when step 6 applied any patches, otherwise No config changes..

---

Refresh-Lock Flow (--refresh-lock)

Entered when $ARGUMENTS contains --refresh-lock. No scaffolding questions are asked, and — unlike the Retroactive Flow above — this is NOT a no-op once the lock already has valid version/tier fields: refreshing is the load-bearing action.

Purpose (#57): Acknowledge the current plugin version and reset the freshness clock on an existing, already-valid bootstrap.lock without disturbing its original bootstrap provenance. This closes the gap left by the Retroactive Flow: once a lock already has version + tier, re-running /bootstrap --retroactive reports "bootstrap.lock already present ... Nothing to do." and changes nothing — exactly the no-op the bootstrap-lock-freshness probe (#186/#290) was recommending as its remediation. --refresh-lock is the actual remediation for a present-but-stale or version-drifted lock.

Steps:

1. Precondition check. Read .orchestrator/bootstrap.lock. If missing, or present but missing a non-empty version or tier field, abort with: Error: No valid bootstrap.lock found. Run /bootstrap or /bootstrap --retroactive first. Do not fabricate a lock — this flow only refreshes an existing one.

2. Resolve the current plugin version. Read plugin-version from $PLUGIN_ROOT/package.json (same source Phase 4 uses).

3. Call the refresh writer.

   import { refreshBootstrapLock } from '$PLUGIN_ROOT/scripts/lib/bootstrap-lock-refresh.mjs';
   const result = refreshBootstrapLock({
     repoRoot: REPO_ROOT,
     currentPluginVersion: PLUGIN_VERSION,
   });
   

   refreshBootstrapLock writes (or replaces, if already present) exactly two lines — refreshed-at: <ISO 8601 UTC> and refreshed-plugin-version: <current plugin version> — via the same atomic tmp-file + rename pattern used by the Retroactive Flow's lock write: write to a sibling tmp file, then rename over the target so the lock is never observed half-written. Every other line of the lock — bootstrapped-at, timestamp, plugin-version, tier, archetype, source, … — is left byte-identical. This is the provenance-honesty guarantee: a refresh is an acknowledgement, not a re-bootstrap. On failure (result.ok === false), surface result.message and stop — do not retry with a fabricated lock.

4. No auto-commit. Unlike the Retroactive Flow, --refresh-lock does not stage or commit. The refreshed lock is a small, reviewable diff (two changed/added lines); the user commits it alongside their own work at their own cadence.

5. Report. Print: Lock refreshed (refreshed-at: <now>, plugin-version: <current>). Original bootstrap provenance unchanged.

Idempotency. Running /bootstrap --refresh-lock twice in a row replaces the same two lines in place — it never duplicates them.

---

Sync-Rules Flow (--sync-rules)

Entered when $ARGUMENTS contains --sync-rules. This standalone flow skips tier selection, scaffolding and initial commit. Rule selection may read the lock ID.

Purpose: Vendor canonical rules from the plugin's rules/ library (rules/always-on/*.md, and in the future rules/opt-in-stack/*.md and rules/opt-in-domain/*.md) into the consumer repo's .claude/rules/. Plugin-sourced files (identified by a <!-- source: session-orchestrator plugin … --> header) are overwritten on re-run; files without that header are preserved as local overrides. See rules/_index.md for the canonical manifest and scripts/lib/rules-sync.mjs for the implementation.

Steps:

1. Resolve plugin root. The plugin's rules/_index.md lives next to SKILL.md's plugin directory. Use the plugin root inferred by the harness (PLUGIN_ROOT).

2. Invoke the bootstrap rule action. It reloads a configured private contract and supplies required plugin basenames to scripts/lib/rules-sync.mjs. With no baseline, the writer's public/default behavior is unchanged. Map an explicit --archetype ID to CONFIRMED_ARCHETYPE, --dry-run to DRY_RUN=true, and optional category selections to comma-separated RULES_CATEGORIES; otherwise leave those variables unset. Run from the repo:

   export PLUGIN_ROOT CONFIRMED_ARCHETYPE DRY_RUN RULES_CATEGORIES
   node --input-type=module <<'NODE'
   import { pathToFileURL } from 'node:url';
   const { syncBootstrapRules } = await import(pathToFileURL(`${process.env.PLUGIN_ROOT}/scripts/lib/baseline-archetypes.mjs`));
   const categories = (process.env.RULES_CATEGORIES || '').split(',').map(value => value.trim()).filter(Boolean);
   const result = await syncBootstrapRules({ repoRoot: process.cwd(), archetype: process.env.CONFIRMED_ARCHETYPE || undefined,
     dryRun: process.env.DRY_RUN === 'true', categories: categories.length ? categories : null });
   process.stdout.write(`${JSON.stringify(result)}\n`);
   if (result.status === 'error') process.exitCode = 2;
   NODE
   

   The canonical writer reads all selected categories in rules/_index.md and writes into .claude/rules/. Required private targets remain subject to its provenance and pre-write checks. Explicit ID takes precedence over lock ID, then repository markers. Invalid private contracts abort before writes. A valid Fast lock with archetype: null and no matching markers retains ordinary plugin rule delivery after contract validation. Stdout includes status, created[], written[], skipped[], preserved[], and errors[]. Any error exits non-zero.

   Add --dry-run to preview without writing.

3. Interpret the output. Report a human summary:

   • written: files newly created OR plugin-owned files overwritten with fresh canonical content.
   • skipped: plugin-owned files already up-to-date (byte-identical).
   • preserved: existing .claude/rules/*.md files that do NOT carry the plugin source header — left untouched as local overrides.
   • errors: per-file failures (missing source, read/write errors, malformed _index.md).

4. Commit (optional). --sync-rules does not auto-commit. If rules changed, prompt the user to review git status and stage/commit the updates manually. Rationale: rules are canonical artifacts and should travel with an intentional review, not land silently.

5. Report. Print: rules-sync complete. Written: <N>. Skipped: <N>. Preserved: <N>. Warnings: <N>. Errors: <N>. warnings[] carries WARN-severity validation findings (e.g. zero-match-globs, foreign-glob) surfaced by validateRuleContent — these do NOT block the write; they are informational only. If errors > 0, non-zero exit.

Local overrides. Any .claude/rules/<name>.md without the plugin source header is considered local and never overwritten. To replace a local override with the canonical version, delete it before re-running.

Idempotency. Running /bootstrap --sync-rules twice in a row with no upstream changes emits written: 0, skipped: <N>. Safe to wire into CI or scheduled maintenance.

---

Phase 3: Dispatch to Template

Based on CONFIRMED_TIER, read and execute the corresponding template file:

Tier	Template File
fast	skills/bootstrap/fast-template.md
standard	skills/bootstrap/standard-template.md
deep	skills/bootstrap/deep-template.md

Pass the following context into the template execution:

• CONFIRMED_TIER
• CONFIRMED_ARCHETYPE
• PATH_TYPE
• REPO_ROOT = $(git rev-parse --show-toplevel)
• REPO_NAME = $(basename "$REPO_ROOT")
• PLATFORM = detected platform from skills/_shared/platform-tools.md

Follow the template's instructions precisely. The template is responsible for creating all files and the initial git commit.