Skip to main content

Bootstrap

This is the canonical bootstrap contract for VibeGov.

Shorthand refs used in docs and chat:

  • BI = bootstrap init
  • BU = bootstrap update
  • BF = bootstrap feedback

Use the same contract in one of three explicit modes:

  • init
  • update
  • review

Mode differences are behavioral only:

  • init creates missing bootstrap state
  • update repairs/normalizes existing bootstrap state
  • review audits against the same contract without claiming missing work was completed

Bootstrap support docs​

Use the canonical contract here, then branch into the support docs when those topics first matter:

  • GitHub Project Bootstrap for GitHub preflight, canonical board selection, repo linkage, and final GitHub-state reconciliation
  • INIT-TODO.md for durable prerequisite/remediation capture during bootstrap and adoption/update work
  • Bootstrap Update for repair/normalization runs against an already bootstrapped repo
  • Bootstrap Review for audit-only runs against the same contract

Canonical bootstrap prompt​

Run VibeGov bootstrap in mode: <init|update|review>.
Read and follow:
- https://vibegov.io/agent.txt
- https://vibegov.io/bootstrap.json
- https://vibegov.io/docs/bootstrap/

Use the same canonical bootstrap contract for all modes.
Do not fork or weaken the pass gate by mode.

Before writing any product code (or before claiming bootstrap review is complete):
1. Create/normalize `.governance/rules/`, `.governance/project/`, and `.governance/specs/` as needed for the selected mode.
2. Ensure the active VibeGov rule set (`GOV-01` through `GOV-09`) is installed in `.governance/rules/`.
3. Detect existing provider-native rules directories and mirror `.governance/rules/*.mdc` only when they already exist.
4. Create or normalize `.governance/project/PROJECT_INTENT.md`.
5. Create `SPEC-001` as either:
   - `.governance/specs/SPEC-001-<feature>.md`, or
   - a bootstrap/governance-setup spec when product intent is still too vague.
6. Create or normalize a backlog mapped to the spec sections.
7. Install or verify strict Git workflow artifacts before implementation:
   - `AGENTS.md` (create this early so future agents have a repo-local entrypoint)
   - `INIT-TODO.md` (create/update this early during bootstrap/adoption/remediation work)
   - `.github/pull_request_template.md`
   - `.github/branch-protection-checklist.md`
   - documented default issue-pickup flow
8. Install or verify continuity bootstrap artifacts before implementation:
   - documented continuity layers (session/thread, recent/daily, project, and durable global/operator continuity when that scope exists)
   - repo-local continuity paths or equivalent scaffolding
   - checkpoint trigger guidance for instructions, decisions, blockers, phase changes, and compaction risk
   - session-diary guidance for recurring threads/contexts
   - promotion guidance between continuity layers
9. Classify starting repo state before edits or review conclusions:
   - current branch
   - clean/dirty working tree
   - untracked files
   - uncommitted changes
10. Run with explicit commit policy: `required`, `allowed`, or `forbidden`.
11. If repo is dirty, do exactly one: resolve first, stop blocked, or continue in explicit review mode.
12. If GitHub-hosted, run preflight before board mutation:
   - `git` available
   - `gh` available
   - GitHub auth
   - repo access
   - project read access
   - project write access
   - branch-protection/admin capability when relevant
   - if any required capability is missing, record it in `INIT-TODO.md` with the exact remediation command or next action before proceeding
   - if branch-protection verification is unavailable only because of a known hosted-feature/private-repo limitation, record it as degraded verification with exact evidence and next action rather than pretending the repo normalization failed
13. If GitHub automation is available, create/adopt/normalize one canonical board target:
   - if multiple matching boards exist, choose one canonical target explicitly and report why it was chosen
   - normalize `Status`: `Backlog`, `Ready`, `In progress`, `In review`, `Done`, `Blocked`
   - normalize `Priority`: `P0`, `P1`, `P2`
   - normalize `Size`: `XS`, `S`, `M`, `L`, `XL`
   - link the repo
   - import/attach existing issues
   - if no issues exist, report board as intentionally empty
   - clean accidental duplicate empty boards and report cleanup
14. If GitHub automation is unavailable, report exact missing capability and leave a tracked blocker artifact.
15. Write durable local bootstrap reporting artifacts using a two-surface layout:
   - current reporting surface: `.governance/project/bootstrap/`
     - `STATUS.md`
     - `ANALYSIS.md`
     - `FEEDBACK.md`
     - optional `BLOCKERS.md`
   - historical run bundles: `.governance/project/bootstrap/history/<timestamp>/`
     - `status.md`
     - `analysis.md`
     - `feedback.md`
     - optional `blockers.md`
   - current files should act as the latest current reporting surface
   - history folders should preserve the per-run bundle as historical evidence
16. Reconcile generated docs against final live git/GitHub state before claiming completion.
17. Distinguish final current state from historical evidence gathered earlier in the run.
18. If migrating a repo from the older flat layout (`BOOTSTRAP_*.md` and `bootstrap-runs/<timestamp>-*.md`), normalize it into the current-surface plus historical-run-bundle structure instead of extending the legacy shape.

Support docs for this contract:
- use [GitHub Project Bootstrap](/docs/github-project-bootstrap) when the repo is GitHub-hosted and board/project setup is in scope
- use [INIT-TODO.md](/docs/init-todo) when prerequisites, blockers, or exact remediation steps need durable capture
- use [Bootstrap Update](/docs/bootstrap-update) for remediation/normalization runs
- use [Bootstrap Review](/docs/bootstrap-review) for audit-only runs against the same contract

Mode-specific behavior:
- `init`: create the missing bootstrap state required by the contract
- `update`: preserve valid existing artifacts and repair stale/missing/contradictory ones, including missing operational bootstrap artifacts, until the same contract is satisfied; if that cannot be done, leave explicit status/blocker artifacts plus a settled end-state classification (`committed/pushed`, `pending-review`, or `blocked`)
- `review`: audit the repo against the same contract, write findings and blockers, and do not claim missing work was completed

Then stop before product-code implementation.

Pass Gate #1​

Continue only if all are true:

  • .governance/rules/ exists with GOV-01 through GOV-09
  • .governance/project/PROJECT_INTENT.md exists
  • .governance/specs/ has SPEC-001 (feature spec or bootstrap-setup spec for vague repos)
  • backlog maps to spec scope
  • AGENTS.md exists and points to canonical governance sources
  • INIT-TODO.md exists for bootstrap/adoption/remediation work and records any missing prerequisite with exact remediation when relevant
  • strict Git workflow artifacts exist
  • continuity structure and continuity operating guidance exist
  • starting repo state and commit-policy mode are reported
  • for GitHub repos, preflight results are reported with explicit state (configured, blocked-with-tracked-issue, not-applicable), and known hosted-feature verification limits are distinguished from core bootstrap failure
  • for GitHub repos with automation, canonical board target is adopted/created/normalized, repo-link status is reported, and multiple-match selection is explained when relevant
  • current bootstrap reporting artifacts exist under .governance/project/bootstrap/
  • historical bootstrap run bundles are written under .governance/project/bootstrap/history/<timestamp>/
  • if update cannot complete all gaps or only reaches degraded verification, blocker reporting makes the incomplete state explicit with exact next actions
  • final docs are reconciled with final live git/GitHub state
  • no product code was written

If any fail:

  • init and update are incomplete
  • review must report the exact gaps and blockers without pretending the repo is bootstrapped

Reporting structure​

Bootstrap reporting should separate current state from history.

Current reporting surface​

Use .governance/project/bootstrap/ for the current bootstrap reporting surface:

  • STATUS.md
  • ANALYSIS.md
  • FEEDBACK.md
  • optional BLOCKERS.md

These files should describe or point to the current settled bootstrap picture, not act as a pile of historical reruns.

Historical run bundles​

Use .governance/project/bootstrap/history/<timestamp>/ for historical bootstrap run evidence.

Each run bundle should group the run’s artifacts together:

  • status.md
  • analysis.md
  • feedback.md
  • optional blockers.md

One folder per run is preferred because it makes each bootstrap/reporting pass legible as a single reporting bundle.

Migration guidance​

If a repo still uses the older flat layout:

  • .governance/project/BOOTSTRAP_STATUS.md
  • .governance/project/BOOTSTRAP_ANALYSIS.md
  • .governance/project/BOOTSTRAP_FEEDBACK.md
  • .governance/project/BOOTSTRAP_BLOCKERS.md
  • .governance/project/bootstrap-runs/<timestamp>-*.md

normalize it toward:

  • .governance/project/bootstrap/STATUS.md
  • .governance/project/bootstrap/ANALYSIS.md
  • .governance/project/bootstrap/FEEDBACK.md
  • .governance/project/bootstrap/BLOCKERS.md
  • .governance/project/bootstrap/history/<timestamp>/...

During transition, older flat artifacts may remain as legacy history, but new bootstrap work should use the structured reporting layout.