agent-bootstrap

A reusable, production-grade bootstrap repository for AI agents.
Use this repo as a source of truth when initializing, documenting, and operating on target repositories.

What this repository is

agent-bootstrap is a canonical scaffold and control-plane repository that an AI agent (or human) can point at any target repository to:

Perform structured discovery on the target repo.
Understand how projects should be structured and documented.
Create required operating files in the target repo.
Leave behind durable project state for future agent sessions.

It is not a library, CLI tool, or deployment pipeline.
It is a documentation and prompt system — the operating model for AI-assisted project work.

Why it exists

AI agent sessions are ephemeral. Without durable state, every new session re-discovers the same things, makes the same assumptions, and risks contradicting prior work.

This repository solves that by providing:

Machine-readable manifests that describe what a bootstrapped repo looks like.
Reusable prompt files that enforce inspection-before-change discipline.
Templates for the operating files every agent-assisted repo should have.
Schemas for validating structured artifacts.
A validation script to confirm a bootstrap repo is intact.

Applying bootstrap to a target repo

scripts/apply_bootstrap.py stages the canonical scaffold into a target repository. This is the fastest way to get a target repo ready for the discovery/bootstrap prompt.

Apply does not auto-populate repo-specific content. It copies template files with their {{PLACEHOLDER}} markers intact. A human or agent then inspects the target repo and fills those placeholders with real, evidence-based content.

Example commands

# Preview what would be created (no files written):
python scripts/apply_bootstrap.py --target-dir /path/to/target-repo --dry-run

# Apply the scaffold (skips files that already exist):
python scripts/apply_bootstrap.py --target-dir /path/to/target-repo

# Re-apply and overwrite existing files:
python scripts/apply_bootstrap.py --target-dir /path/to/target-repo --force

# Preview what --force would overwrite:
python scripts/apply_bootstrap.py --target-dir /path/to/target-repo --dry-run --force

What apply does

Creates required directories (docs/ai/, bootstrap/, artifacts/ai/).
Copies each canonical template to its target destination.
Writes bootstrap/BOOTSTRAP_SOURCE.md with the bootstrap source URL, version, and date filled in.
Skips any file that already exists (safe by default).
Prints a summary: created / skipped / would overwrite / overwritten / errors.

What apply does NOT do

It does not inspect the target repo or infer repo-specific content.
It does not fill {{PLACEHOLDER}} markers (except the bootstrap system markers in BOOTSTRAP_SOURCE.md).
It does not run discovery or populate artifacts/ai/repo_discovery.json with real findings.

After apply: run the bootstrap prompt

Once the scaffold is staged, point an agent at the target repo using one of the prompts:

prompts/new-repo-bootstrap.md         ← for new or empty repos
prompts/existing-repo-discovery.md    ← for repos with existing code

The agent will inspect the target repo and fill all remaining {{PLACEHOLDER}} markers with evidence found in the repo.

Validate the result

After the agent has populated the files:

python scripts/validate_bootstrap.py --target-dir /path/to/target-repo

This checks:

All required files are present.
No unfilled {{PLACEHOLDER}} markers remain.
JSON artifacts are valid.

Apply vs bootstrap prompt — key distinction

Step	Tool	What it does
Apply	`scripts/apply_bootstrap.py`	Stages canonical file structure and skeletal templates
Bootstrap prompt / discovery	`prompts/*.md` → agent session	Inspects target repo; fills templates with real evidence

These are two separate steps. Apply first, then run the prompt.

Bootstrap profiles

Profiles let you apply a slightly different scaffold shape depending on the target repository type. They provide more relevant starting guidance without inventing repo-specific content.

What profiles do and do not do

Profiles do:

Select profile-specific template variants where they materially improve guidance (currently: docs/ai/AI_AGENT_VENDOR_KNOWLEDGE_BASE.md has per-profile variants)
Record the selected profile in bootstrap/BOOTSTRAP_SOURCE.md for future reference
Allow refresh_bootstrap.py to use the same profile-specific templates when upgrading

Profiles do not:

Auto-populate repo-specific discovery content (that remains agent-led)
Replace the bootstrap prompt / discovery step
Infer which profile to use — you must select one explicitly

Supported profiles

Profile	Suitable for
`generic`	Any repo not covered by a more specific profile (default)
`python-service`	Python service or library repositories
`infra-repo`	Infrastructure/platform repos (Terraform, Pulumi, Ansible, etc.)
`vscode-extension`	VS Code extension repositories
`kubernetes-platform`	Kubernetes operator or platform repositories

Apply with a profile

# Apply with the default (generic) profile:
python scripts/apply_bootstrap.py --target-dir /path/to/target-repo

# Apply with a specific profile:
python scripts/apply_bootstrap.py --target-dir /path/to/target-repo --profile python-service
python scripts/apply_bootstrap.py --target-dir /path/to/target-repo --profile infra-repo
python scripts/apply_bootstrap.py --target-dir /path/to/target-repo --profile vscode-extension
python scripts/apply_bootstrap.py --target-dir /path/to/target-repo --profile kubernetes-platform

# Preview what a profile apply would create:
python scripts/apply_bootstrap.py --target-dir /path/to/target-repo --profile python-service --dry-run

An unknown profile name causes apply to exit with an error and list the supported options.

Common core vs profile-specific behavior

The common core (applied for all profiles) includes:

AGENTS.md — execution contract template
IMPLEMENTATION_TRACKER.md — live state template
docs/ai/REPO_MAP.md — repository map template
docs/ai/SOURCE_REFRESH.md — source refresh instructions
bootstrap/BOOTSTRAP_SOURCE.md — bootstrap origin marker
artifacts/ai/repo_discovery.json — discovery artifact template

The profile-specific overlay replaces:

docs/ai/AI_AGENT_VENDOR_KNOWLEDGE_BASE.md — a profile-tuned variant with guidance comments specific to that repo family (Python packaging, IaC providers, VS Code APIs, etc.)

All other files use the same common template regardless of profile.

How refresh interacts with profile metadata

refresh_bootstrap.py reads the Bootstrap profile field from bootstrap/BOOTSTRAP_SOURCE.md and uses the same profile-specific templates when upgrading managed files. If no profile is recorded (e.g., the repo was bootstrapped before Milestone 12), refresh falls back to the generic profile automatically.

Why profiles do not replace repo discovery

Profiles select which templates to stage — they do not fill those templates with repo-specific content. After apply, the {{PLACEHOLDER}} markers in profile-specific templates still require an agent to inspect the target repo and fill them with real evidence, using the bootstrap or discovery prompt.

Refreshing an already-bootstrapped target repo

scripts/refresh_bootstrap.py upgrades an already-bootstrapped target repository to align with the current canonical bootstrap source templates.

Refresh is safe by default. It never blindly overwrites repo-specific populated content. It classifies each managed file before taking action.

When to use refresh vs apply

Situation	Tool
Target repo has never been bootstrapped	`scripts/apply_bootstrap.py`
Target repo was bootstrapped before; templates have been updated	`scripts/refresh_bootstrap.py`
Checking status of a bootstrapped repo	`scripts/refresh_bootstrap.py --dry-run`

File classifications

Classification	Meaning	Default action
`missing`	File not present in target	Created
`unchanged`	File matches current template exactly	Skipped (already current)
`safe-refresh`	File differs from template but still has unfilled `{{PLACEHOLDER}}` markers	Refreshed (template updated; no local content to lose)
`populated`	File has been filled with real content (no remaining placeholders)	Skipped — flagged for manual review

Example commands

# Preview what would change (no files written):
python scripts/refresh_bootstrap.py --target-dir /path/to/target-repo --dry-run

# Run refresh (safe defaults — skips populated files):
python scripts/refresh_bootstrap.py --target-dir /path/to/target-repo

# Preview what --force would overwrite (including populated files):
python scripts/refresh_bootstrap.py --target-dir /path/to/target-repo --dry-run --force

# Refresh and overwrite even populated files (destructive — use with care):
python scripts/refresh_bootstrap.py --target-dir /path/to/target-repo --force

What refresh does

Detects whether the target repo was previously bootstrapped (checks for bootstrap/BOOTSTRAP_SOURCE.md).
Reads the prior bootstrap version and date from the marker if present.
Classifies each managed file (missing, unchanged, safe-refresh, or populated).
Creates missing files and refreshes unpopulated scaffold files by default.
Skips files that have been populated with real content (no remaining {{PLACEHOLDER}} markers).
Prints a summary of all classifications and actions taken.

What refresh does NOT do

It does not blindly overwrite populated files (unless --force is given).
It does not auto-merge repo-specific content with template changes.
It does not replace the agent population step — manually review flagged files.

Recommended workflow before and after refresh

# 1. Preview the impact (always start here):
python scripts/refresh_bootstrap.py --target-dir /path/to/target-repo --dry-run

# 2. Review which files would be skipped (populated) vs refreshed.
#    For populated files, manually compare them to the updated template.

# 3. Run the refresh:
python scripts/refresh_bootstrap.py --target-dir /path/to/target-repo

# 4. Re-populate any refreshed files that need updated content.

# 5. Validate the final state:
python scripts/validate_bootstrap.py --target-dir /path/to/target-repo

Apply vs refresh vs validate — key distinction

Step	Tool	What it does
Apply	`scripts/apply_bootstrap.py`	Stages canonical file structure into a fresh target repo
Refresh	`scripts/refresh_bootstrap.py`	Updates managed files in an existing bootstrapped repo (safe by default)
Validate	`scripts/validate_bootstrap.py`	Checks file presence, placeholder completion, and JSON validity

Initializing a new target repo

Clone or reference this repository.
Open prompts/new-repo-bootstrap.md and paste it into your agent session, pointing the agent at your target repo.
The agent will inspect the target repo, create the required operating files, and record its work in IMPLEMENTATION_TRACKER.md.

Resuming work in a target repo

Open prompts/resume-work.md and paste it into a new agent session.
The agent will read the existing tracker and operating files before taking any action.

Running a bounded implementation milestone

After bootstrap is complete, use prompts/bounded-implementation.md.
The agent will scope itself to a single milestone and update the tracker on completion.

Closing out a session

Use prompts/closeout-and-handoff.md to finalize state, validate files, and prepare handoff notes.

End-to-end fixtures and self-test harness

fixtures/ contains controlled minimal target repositories and population data used to prove the bootstrap apply and validate workflow end-to-end.

scripts/run_fixture_selftest.py orchestrates the proof flow against each fixture.

Three fixture states

State	Description	Validation result
A — raw fixture	Fixture as committed; no bootstrap files present	N/A (starting point)
B — scaffold applied	`apply_bootstrap.py` run; placeholders present	Expected to fail (unfilled placeholders)
C — minimally populated	Placeholder values applied from `fixtures/population/*.json`	Expected to pass

State B failing is correct behavior — it proves the scaffold was staged but not yet populated, exactly as documented. State C passing proves the full population path works.

State C population data is fixture-only proof data. It is not the result of real discovery and does not replace evidence-driven agent work. It exists only to prove that a fully populated bootstrap passes validation.

Example commands

# Run all fixtures (State B + State C):
python scripts/run_fixture_selftest.py

# Run a specific fixture only:
python scripts/run_fixture_selftest.py --fixture minimal-python-service

# State B only (scaffold staging proof, skip population):
python scripts/run_fixture_selftest.py --state-b-only

# Verbose output + inspect working copies:
python scripts/run_fixture_selftest.py --verbose --keep-work-dir

Expected output

Bootstrap self-test
  ...
  minimal-python-service                    B:PASS  C:PASS
  minimal-infra-repo                        B:PASS  C:PASS

SELF-TEST PASSED.

Fixture descriptions

Fixture	Shape	Why
`minimal-python-service`	Code-oriented (Flask, pytest)	Proves bootstrap on a typical application repo
`minimal-infra-repo`	Infra/docs-oriented (Terraform)	Proves bootstrap on a non-application, docs-heavy repo

See fixtures/README.md for full fixture documentation.

An agent that receives a prompt from this repo's prompts/ directory should:

Read bootstrap-manifest.yaml to understand required outputs and stop conditions.
Inspect the target repo before making any changes.
Use the templates in templates/ as starting points, filling them with real evidence from the target repo.
Validate its outputs against the schemas in schemas/.
Run scripts/validate_bootstrap.py (or equivalent checks) before declaring bootstrap complete.
Update IMPLEMENTATION_TRACKER.md in the target repo with a full record of the run.

What files this system creates in a target repo

File	Purpose
`AGENTS.md`	Execution contract for AI agents working in that repo
`IMPLEMENTATION_TRACKER.md`	Live state file: milestones, decisions, gaps
`docs/ai/REPO_MAP.md`	Human + agent-readable map of the repository
`docs/ai/SOURCE_REFRESH.md`	Instructions for re-syncing agent knowledge
`docs/ai/AI_AGENT_VENDOR_KNOWLEDGE_BASE.md`	Vendor-specific AI knowledge relevant to the repo
`bootstrap/BOOTSTRAP_SOURCE.md`	Record of where the bootstrap originated
`artifacts/ai/repo_discovery.json`	Machine-readable discovery artifact

What "bootstrap complete" means for a target repo

A target repo is considered bootstrap-complete when:

All required files listed in bootstrap-manifest.yaml are present.
Each file is populated with repo-specific content (not generic placeholders).
IMPLEMENTATION_TRACKER.md records the run that created them.
The discovery artifact (repo_discovery.json) reflects actual findings.
A human or agent can open the tracker and understand the project state without chat history.

Intended operating model

Inspect → Document → Bound → Validate → Record

Inspect: Read the target repo before touching anything.
Document: Create or update operating files with real evidence.
Bound: Limit each session to a declared milestone scope.
Validate: Confirm file presence, internal references, and schema compliance.
Record: Update the tracker; leave the repo resumable.

Quick-start

# Stage the bootstrap scaffold into a target repo (default generic profile):
python scripts/apply_bootstrap.py --target-dir /path/to/target-repo

# Stage with a profile (e.g., for a Python service repo):
python scripts/apply_bootstrap.py --target-dir /path/to/target-repo --profile python-service

# Then run the bootstrap prompt (new repo) or discovery prompt (existing repo)
# against the target repo to fill in the content.

# Validate after the agent has populated the files:
python scripts/validate_bootstrap.py --target-dir /path/to/target-repo

Repository layout

.
├─ README.md                          ← this file
├─ AGENTS.md                          ← execution contract for this repo
├─ IMPLEMENTATION_TRACKER.md          ← live state for this repo
├─ bootstrap-manifest.yaml            ← machine-readable control plane
├─ prompts/                           ← reusable agent prompt files
│  ├─ new-repo-bootstrap.md
│  ├─ existing-repo-discovery.md
│  ├─ resume-work.md
│  ├─ bounded-implementation.md
│  └─ closeout-and-handoff.md
├─ templates/                         ← canonical templates for target repos
│  ├─ AGENTS.md.template
│  ├─ IMPLEMENTATION_TRACKER.md.template
│  ├─ bootstrap/
│  │  └─ BOOTSTRAP_SOURCE.md.template
│  ├─ docs/ai/
│  │  ├─ REPO_MAP.md.template
│  │  ├─ SOURCE_REFRESH.md.template
│  │  └─ AI_AGENT_VENDOR_KNOWLEDGE_BASE.md.template   ← generic (default)
│  ├─ profiles/                       ← profile-specific template overrides
│  │  ├─ python-service/docs/ai/AI_AGENT_VENDOR_KNOWLEDGE_BASE.md.template
│  │  ├─ infra-repo/docs/ai/AI_AGENT_VENDOR_KNOWLEDGE_BASE.md.template
│  │  ├─ vscode-extension/docs/ai/AI_AGENT_VENDOR_KNOWLEDGE_BASE.md.template
│  │  └─ kubernetes-platform/docs/ai/AI_AGENT_VENDOR_KNOWLEDGE_BASE.md.template
│  └─ artifacts/ai/
│     └─ repo_discovery.json.template
├─ fixtures/                          ← fixture target repos + self-test data
│  ├─ README.md                       ← fixture documentation
│  ├─ targets/
│  │  ├─ minimal-python-service/      ← code-oriented fixture (Flask, pytest)
│  │  └─ minimal-infra-repo/          ← infra/docs-oriented fixture (Terraform)
│  └─ population/
│     ├─ minimal-python-service.json  ← State C proof data
│     └─ minimal-infra-repo.json      ← State C proof data
├─ examples/                          ← per-repo-type discovery notes
│  ├─ python-service/
│  ├─ infra-repo/
│  ├─ vscode-extension/
│  └─ kubernetes-platform/
├─ schemas/                           ← JSON schemas for structured artifacts
│  ├─ implementation_tracker.schema.json
│  ├─ repo_discovery.schema.json
│  └─ bootstrap_doctor_report.schema.json  ← doctor/audit JSON output contract (Milestone 19)
├─ scripts/
│  ├─ bootstrap_core.py            ← shared internal semantic helpers (Milestone 17)
│  ├─ validate_bootstrap.py        ← lightweight validation script
│  ├─ apply_bootstrap.py           ← scaffold apply script
│  ├─ refresh_bootstrap.py         ← safe upgrade/refresh script
│  ├─ run_fixture_selftest.py      ← end-to-end self-test harness
│  ├─ bootstrap_status.py          ← source/target repo status report
│  ├─ suggest_profile.py           ← target repo profile suggestion
│  └─ bootstrap_doctor.py          ← target repo health audit (read-only)
└─ tests/
   ├─ test_bootstrap_core.py       ← contract tests for shared semantics
   └─ test_bootstrap_doctor.py     ← contract tests for doctor/diagnosis semantics

Example workflow: initializing a target repo

1. Agent receives prompt from prompts/new-repo-bootstrap.md
2. Agent inspects target repo → records findings in repo_discovery.json
3. Agent creates AGENTS.md, IMPLEMENTATION_TRACKER.md, docs/ai/* from templates
4. Agent fills templates with real evidence (no guessing)
5. Agent runs validate_bootstrap.py against target repo
6. Agent updates IMPLEMENTATION_TRACKER.md with completion status
7. Session ends — repo is resumable by any future agent or human

Shared bootstrap core

scripts/bootstrap_core.py is a small internal module that centralises the bootstrap semantics reused across multiple scripts.

Why it exists

As the tool set grew across milestones, several scripts independently defined the same logic: placeholder regex patterns, SEMVER validation, marker field parsing, era classification, profile resolution, and template mapping. Duplicated definitions drift over time — a fix in one script silently leaves others inconsistent.

bootstrap_core.py is the single source of truth for:

PLACEHOLDER_RE and SEMVER_RE (shared regex constants)
read_version() — reads the VERSION file
load_manifest() — reads the bootstrap-manifest.yaml as text
get_supported_profiles() / resolve_profile() — profile names and validation
parse_bootstrap_marker() — parses the bootstrap marker table
classify_marker_era() — classifies markers as pre-version, pre-profile, versioned, or unknown
is_placeholder(), has_placeholders(), find_placeholders() — placeholder helpers
resolve_template_mappings() — effective template mappings per profile

Scripts remain the main operator interfaces. Only the shared semantic primitives live in the core. CLI behaviour, output formatting, and script-specific logic stay in each script.

Contract tests

tests/test_bootstrap_core.py contains bounded contract tests that prove the shared semantics are stable:

regex behaviour
version file parsing
manifest loading
profile enumeration and validation
template mapping resolution for all profiles
marker parsing from sample text
era classification (all four states)
placeholder helpers

tests/test_bootstrap_doctor.py contains bounded contract tests that prove the target-repo diagnosis semantics are stable:

all six health state classifications
version comparison helpers (materially-behind logic)
marker status, required-files status, and placeholder status helpers
profile alignment classification (aligned / mismatch / insufficient-evidence / not-recorded)
recommended next-action guidance for every health state (conservative by default — no --force)
era classification alignment between bootstrap_doctor and bootstrap_core
audit() integration for key states using real temporary directories

Doctor behavior is intentionally conservative and stable: it never recommends --force, never shells out to external processes, and never mutates any files. These properties are proved by the contract tests and must remain stable.

Run the contract tests locally:

python -m unittest discover -s tests -p 'test_*.py' -v

When to update the core

Update bootstrap_core.py and its contract tests when:

a shared semantic changes (e.g., new marker field, new era state)
a new profile is added (update PROFILES and its tests)
a placeholder pattern changes

Do not add script-specific output logic to the core.

Continuous integration

A GitHub Actions workflow at .github/workflows/ci.yml runs automatically on every push, pull request, and manual trigger.

What it checks

Step	Command
Script syntax	`python -m py_compile scripts/*.py`
Bootstrap repo structure	`python scripts/validate_bootstrap.py`
Contract tests	`python -m unittest discover -s tests -p 'test_*.py'`
Fixture end-to-end self-tests	`python scripts/run_fixture_selftest.py`

When it runs

Every push to any branch
Every pull request
On demand via the GitHub Actions "Run workflow" button

Relationship to local validation

CI runs the same commands you should run locally before pushing:

python scripts/validate_bootstrap.py
python -m unittest discover -s tests -p 'test_*.py'
python scripts/run_fixture_selftest.py

If CI fails, the failure maps directly to one of these commands — inspect the step that failed to identify which check broke.

What regressions it catches

Missing required bootstrap repo files
Broken or invalid JSON schemas and templates
apply_bootstrap.py failures (scaffold apply path)
validate_bootstrap.py failures (validation path)
Fixture self-test failures (State B, State C, or State D refresh)
Python syntax errors in any of the three scripts

Note for maintainers: After merging changes that update the CI workflow or add new scripts, confirm that GitHub Actions is actually firing on subsequent pushes and pull requests by checking the Actions tab in the repository. The workflow was added in Milestone 10 and should run automatically for all branches.

Profile suggestion — choosing the right profile

Before applying a bootstrap scaffold, you can inspect a target repository and get a suggested profile based on its file-system evidence.

What profile suggestion does

scripts/suggest_profile.py scans the target directory for well-known signal files and directories (e.g., pyproject.toml, *.tf, Chart.yaml) and reports:

The most likely bootstrap profile.
A confidence level (high, medium, or low).
The specific signals that matched.
Any alternative candidate profiles.
The recommended apply_bootstrap.py command to run next.

The tool is read-only. It never creates, modifies, or deletes any files.

What profile suggestion does NOT do

It does not apply the suggested profile automatically.
It does not replace the maintainer's judgment.
It does not guarantee the suggestion is correct — it is advisory only.
It does not run discovery or populate {{PLACEHOLDER}} markers.

Supported profiles

Profile	Key signals
`python-service`	`pyproject.toml`, `requirements.txt`, `src/`, `tests/`, `.py` files
`infra-repo`	`*.tf` files, `environments/`, `modules/`, `inventory/`, no app runtime
`vscode-extension`	`package.json` with vscode content, `extension.ts`, `.vscodeignore`
`kubernetes-platform`	`Chart.yaml`, `values.yaml`, `kustomization.yaml`, `manifests/`, `clusters/`
`generic`	Fallback — weak, mixed, or absent evidence

Example commands

# Basic suggestion (human-readable output):
python scripts/suggest_profile.py --target-dir /path/to/repo

# Verbose output (shows alternative candidates and all scores):
python scripts/suggest_profile.py --target-dir /path/to/repo --verbose

# JSON output (useful for scripting):
python scripts/suggest_profile.py --target-dir /path/to/repo --json

How to use suggestion output before apply

Run the suggestion tool against the target repo.
Review the evidence and confidence level.
If the suggestion looks right, use the recommended command shown in the output.
If uncertain, review the signals and choose manually.
The final profile choice is always yours.

# Step 1: inspect
python scripts/suggest_profile.py --target-dir /path/to/repo

# Step 2: apply with the suggested (or chosen) profile
python scripts/apply_bootstrap.py --target-dir /path/to/repo --dry-run --profile python-service

# Step 3: apply for real once dry-run looks right
python scripts/apply_bootstrap.py --target-dir /path/to/repo --profile python-service

Why the final choice belongs to the maintainer

Profile selection determines which template variant is staged into the target repo. The suggestion tool uses simple file-system heuristics — it cannot know team conventions, architectural intent, or edge cases that an experienced maintainer would recognize. Treat the suggestion as a fast starting point, not an authoritative decision.

Bootstrap doctor — target repo audit

scripts/bootstrap_doctor.py is a read-only diagnostic tool that inspects a target repository and explains its bootstrap health, drift, and recommended next action.

What bootstrap doctor does

Runs a single command that answers:

Is this repo bootstrapped at all?
What bootstrap version, profile, and era is recorded?
Are all required managed files present?
Are {{PLACEHOLDER}} markers still present in managed files?
What health state is the repo in?
Does the recorded profile match the currently suggested profile?
Is a refresh likely needed?
What exact next command should the operator run?

The doctor is read-only. It never creates, modifies, or deletes any files.

What bootstrap doctor does NOT do

It does not apply the bootstrap scaffold.
It does not run refresh automatically.
It does not fill {{PLACEHOLDER}} markers.
It does not validate — that is validate_bootstrap.py's job.
It does not recommend --force flags by default.

Example commands

# Human-readable audit report:
python scripts/bootstrap_doctor.py --target-dir /path/to/repo

# Verbose output (lists missing files, files with placeholders):
python scripts/bootstrap_doctor.py --target-dir /path/to/repo --verbose

# JSON output (useful for scripting):
python scripts/bootstrap_doctor.py --target-dir /path/to/repo --json

Health states

State	Meaning
`unbootstrapped`	No marker found; repo has not been bootstrapped
`scaffold-applied-unpopulated`	Marker present; all managed files still have placeholder markers
`partially-populated`	Marker present; some files populated, some placeholders remain
`populated-and-healthy`	Marker present; all required files present; no placeholder markers
`stale-version-review-recommended`	Recorded version is materially behind current source version
`profile-mismatch-review-recommended`	Recorded profile differs from suggested with meaningful evidence

Using doctor before apply, refresh, or validate

Run the doctor first to understand what the target repo needs before taking any action.

# Step 1: audit the target repo
python scripts/bootstrap_doctor.py --target-dir /path/to/repo

# Step 2: follow the recommended command from the output
#   (e.g., suggest_profile, apply --dry-run, validate, or refresh --dry-run)

# Step 3: run the actual action once confident

The doctor output always includes a "Recommended next action(s)" section with ready-to-run commands based on the actual health state it detected.

Machine-readable JSON output contract

The --json flag produces stable machine-readable output for automation, CI consumers, and bulk audit tooling. Downstream tools should depend on the JSON output, not on parsing human-readable terminal text.

python scripts/bootstrap_doctor.py --target-dir /path/to/repo --json

Schema: schemas/bootstrap_doctor_report.schema.json

The JSON contract guarantees:

A schema_version field (semver) identifying the JSON contract version — this is independent of the bootstrap repo's VERSION file. The two version axes serve different purposes: schema_version tracks the shape of this JSON output; VERSION tracks the bootstrap tooling release. Do not conflate them.
Stable, bounded health_state values — the six health state strings are the stable vocabulary and will not be renamed without a semver minor version bump.
Structured recommendations — each item is an object with type ("command" or "note") and value. Consumers must branch on type to distinguish runnable commands from informational notes — do not parse value to infer the type.
Bounded enum values for marker_status, marker_era, profile_confidence, profile_alignment, required_files_status, and placeholder_status.

Stability guarantees:

Change type	Schema version bump
Additive optional fields or clarifying documentation	patch
New required fields or new enum values	minor
Renamed/removed required fields or changed semantics	major

Enum growth note: A minor version bump may add new enum values (e.g., a new health_state). Consumers must handle unknown enum values defensively — do not treat the current enum sets as permanently frozen.

Human-readable output (the default, without --json) may change phrasing across releases. Only the JSON output is the stable contract.

Bulk multi-repo audit

scripts/bulk_audit.py is a read-only bulk audit tool that inspects multiple target repositories and produces a concise aggregate health summary.

What bulk audit does

Accepts one or more explicit --repo paths and/or a --root-dir to scan.
Runs the bootstrap doctor audit (read-only) on each discovered repo.
Reports per-repo health state, version, and profile.
Produces aggregate counts by health state and profile.
Identifies high-priority repos that need attention.
Outputs machine-readable JSON when --json is specified.

Bulk audit is read-only. It never creates, modifies, or deletes any files.

What bulk audit does NOT do

It does not apply the bootstrap scaffold to any repo.
It does not run refresh or validate on any repo.
It does not fill {{PLACEHOLDER}} markers.
It does not clone or fetch remote repos.
It does not build a database or dashboard backend.

Example commands

# Audit explicit repos:
python scripts/bulk_audit.py --repo /path/to/repo-a --repo /path/to/repo-b

# Discover repos in a parent directory (looks for .git/ in immediate subdirs):
python scripts/bulk_audit.py --root-dir /path/to/repos

# Scan up to 2 directory levels deep:
python scripts/bulk_audit.py --root-dir /path/to/repos --max-depth 2

# JSON output to stdout:
python scripts/bulk_audit.py --root-dir /path/to/repos --json

# JSON output to file:
python scripts/bulk_audit.py --repo /path/to/repo-a --json --output /tmp/bulk.json

# Mix explicit repos and root-dir:
python scripts/bulk_audit.py --repo /extra/repo --root-dir /path/to/repos --json

Repo discovery under --root-dir

Only directories containing a .git/ subdirectory are treated as repositories. This is conservative by design. Do not assume every folder under --root-dir will be scanned — the tool only picks up clear git repos.

Default max depth is 1 (immediate subdirectories only). Use --max-depth 2 to scan one level deeper.

Human-readable vs JSON output

The default terminal output is concise and operator-friendly:

Scan summary and aggregate counts by health state.
Profile distribution.
High-priority repos (stale, mismatch, partially-populated, unbootstrapped).
Per-repo concise lines.

The --json output is the stable machine-readable contract for automation and downstream tooling. Downstream tools should consume the JSON output, not parse terminal text.

Schema: schemas/bootstrap_bulk_audit_report.schema.json

Key fields in the bulk JSON report:

schema_version — tracks the bulk report JSON contract version (independent of VERSION).
generated_at — ISO 8601 UTC timestamp.
bootstrap_source_version — current bootstrap tooling version.
repo_count — total repos considered (audited + errors).
summary.by_health_state — aggregate counts per health state.
summary.by_profile — aggregate counts per profile.
repos — array of per-repo results, using the same semantic fields as the doctor JSON contract.
errors — repos that could not be audited, with error details.

Per-repo entries in the bulk report use the same field vocabulary as bootstrap_doctor.py --json output. Consumers must handle unknown enum values defensively — a minor version bump may add new values.

Bootstrap status and release workflow

Checking bootstrap repo status

python scripts/bootstrap_status.py

Reports: version, git revision, CHANGELOG presence, core docs and scripts, supported profiles, and version/changelog coherence.

Inspecting a target repo marker

python scripts/bootstrap_status.py --target-dir /path/to/target-repo

Reports: bootstrap source, version, revision, date, agent, prompt, profile, and era classification (pre-version, pre-profile, or versioned).

Version/changelog coherence check

The coherence check (run automatically by validate_bootstrap.py and bootstrap_status.py) confirms:

VERSION exists and contains a valid semver string.
CHANGELOG.md exists.
The current version appears in CHANGELOG.md as a release heading, OR an [Unreleased] section is present (version in progress).

python scripts/validate_bootstrap.py  # includes coherence check
python scripts/bootstrap_status.py    # human-readable summary

Release workflow

See docs/BOOTSTRAP_RELEASE_WORKFLOW.md for the full step-by-step release checklist, including:

When to use patch/minor/major bumps.
What files to update.
What local checks to run before merge.
How to tag a release.

Bootstrap versioning

Version source of truth

The bootstrap version is defined in the VERSION file at the root of this repository. It contains a single semantic version string (e.g., 0.13.0).

cat VERSION
# 0.13.0

apply_bootstrap.py and refresh_bootstrap.py read this file at run time to record the bootstrap version in the target repo's marker.

What the marker records

When apply_bootstrap.py runs, it writes two version fields into bootstrap/BOOTSTRAP_SOURCE.md:

Field	Value	Example
Bootstrap source version	semver from `VERSION` file	`0.13.0`
Bootstrap source revision	git SHA of the bootstrap repo	`abc1234`

The refresh_bootstrap.py script reads the prior version from the marker, shows it alongside the current version, and emits a warning if the major version has changed.

Patch / minor / major semantics

Change type	Example	Refresh safety
Patch	Doc corrections, script bug fixes	Safe — no manual review expected
Minor	New templates, new profiles, additive marker fields	Bounded review — new files created; existing populated files skipped
Major	Marker field renames, structural policy changes	Manual review required — run `--dry-run` first

How to bump the version

Update the VERSION file.
Add an entry to CHANGELOG.md.
Commit and tag: git tag vX.Y.Z.

Full policy details are in docs/BOOTSTRAP_VERSIONING.md.

Limitations and non-goals

This repo does not implement a CLI for end-users.
This repo does not contain target-repo-specific content.
This repo does not automate deployments or CI pipelines.
Templates contain placeholders, not real project data.
The validation script checks file presence, not semantic correctness.
Schemas enforce shape, not business logic.

Name		Name	Last commit message	Last commit date
Latest commit History 62 Commits
.github/workflows		.github/workflows
docs		docs
examples		examples
fixtures		fixtures
prompts		prompts
schemas		schemas
scripts		scripts
templates		templates
tests		tests
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
IMPLEMENTATION_TRACKER.md		IMPLEMENTATION_TRACKER.md
LICENSE		LICENSE
README.md		README.md
VERSION		VERSION
bootstrap-manifest.yaml		bootstrap-manifest.yaml

Folders and files

Latest commit

History

Repository files navigation

agent-bootstrap

What this repository is

Why it exists

Applying bootstrap to a target repo

Example commands

What apply does

What apply does NOT do

After apply: run the bootstrap prompt

Validate the result

Apply vs bootstrap prompt — key distinction

Bootstrap profiles

What profiles do and do not do

Supported profiles

Apply with a profile

Common core vs profile-specific behavior

How refresh interacts with profile metadata

Why profiles do not replace repo discovery

Refreshing an already-bootstrapped target repo

When to use refresh vs apply

File classifications

Example commands

What refresh does

What refresh does NOT do

Recommended workflow before and after refresh

Apply vs refresh vs validate — key distinction

Initializing a new target repo

Resuming work in a target repo

Running a bounded implementation milestone

Closing out a session

End-to-end fixtures and self-test harness

Three fixture states

Example commands

Expected output

Fixture descriptions

What files this system creates in a target repo

What "bootstrap complete" means for a target repo

Intended operating model

Quick-start

Repository layout

Example workflow: initializing a target repo

Shared bootstrap core

Why it exists

Contract tests

When to update the core

Continuous integration

What it checks

When it runs

Relationship to local validation

What regressions it catches

Profile suggestion — choosing the right profile

What profile suggestion does

What profile suggestion does NOT do

Supported profiles

Example commands

How to use suggestion output before apply

Why the final choice belongs to the maintainer

Bootstrap doctor — target repo audit

What bootstrap doctor does

What bootstrap doctor does NOT do

Example commands

Health states

Using doctor before apply, refresh, or validate

Machine-readable JSON output contract

Bulk multi-repo audit

What bulk audit does

What bulk audit does NOT do

Example commands

Repo discovery under --root-dir

Human-readable vs JSON output

Bootstrap status and release workflow

Checking bootstrap repo status

Inspecting a target repo marker

Version/changelog coherence check

Release workflow

Bootstrap versioning

Version source of truth

Packages