Bootstrap

Environment Bootstrap

Create a working local dev environment from a repository with reproducible setup steps and verification output.

Table of Contents

• When to use
• Standards snapshot
• Philosophy
• Inputs
• Procedure
• Outputs
• Failure mode
• Constraints
• Validation
• Anti-patterns
• Variation
• Usage
• Example Output
• Troubleshooting
• Decision feedback protocol

When to use

Use this skill when the user asks to quickly stand up a new repo locally, reproduce onboarding setup, or validate that a project can run from a clean environment.

Standards snapshot (March 2026)

• Prefer deterministic bootstrap over one-off shell folklore.
• Detect the stack before installing dependencies or activating toolchains.
• Use repo-native setup and validation commands when they exist.
• Record what succeeded, what was skipped, and the first blocking step if bootstrap does not finish cleanly.

Philosophy

• Prefer deterministic setup over ad-hoc shell steps.
• Detect and report blockers early so users can recover quickly.
• Keep generated setup notes actionable for the next contributor.

Required inputs

• Repository URL (required).
• Optional target branch/tag/ref.
• Optional runtime/tooling constraints (Node/Python/Rust versions, package manager preference).

Procedure

1. Clone the requested repository into a clean workspace.
2. Detect project type(s) and required toolchain.
3. Install or activate required tools via mise where applicable.
4. Install project dependencies with the detected package manager/workflow.
5. Prepare environment scaffolding (.env, service dependencies, startup prerequisites).
6. Run a minimal startup/health verification command.
7. Record outcomes and next steps in setup artifacts.

Deliverables

• Bootstrapped local repository ready for development (or clear failure report).
• Concise setup summary (commands executed, detected stack, verification result).
• Follow-up artifact (SETUP.md or SETUP_FAILED.md) with reproducible instructions.
• If requested, a structured status report with schema_version: 1 aligned to references/contract.yaml.

Failure mode

If clone, toolchain activation, dependency install, or the first runnable health check fails, stop at that blocker, capture the exact outcome, and leave a documented partial state rather than claiming a successful bootstrap.

Constraints

• Redact secrets and sensitive data by default in logs, setup artifacts, and copied config values.
• Do not silently bypass failing prerequisites; surface explicit remediation steps.
• Avoid destructive system changes outside the requested repo context without user approval.

Validation

• Verify clone success and expected directory structure.
• Verify dependency install command exits successfully.
• Verify at least one project health check/start command outcome is recorded.
• Fail fast on unrecoverable setup gates and report first actionable blocker.

Anti-patterns

• Running broad system modifications without clear user consent.
• Suppressing setup failures to produce a false "success" status.
• Hardcoding environment-specific assumptions without documenting them.

Variation

• Adapt the workflow depth based on user intent: quick bootstrap, full developer setup, or audit-only verification.
• Use different validation strictness for exploratory setup versus handoff-ready environment preparation.
• Customize toolchain steps per detected project type while preserving the same preflight and safety gates.

Usage

/bootstrap https://github.com/owner/repo
/bootstrap https://github.com/owner/repo --branch develop

Example Output

• Bootstrap starts with repo URL and temp work directory.
• It clones, detects project type, installs tools/dependencies, verifies startup, and writes SETUP.md.
• Successful run ends with a clear completion marker and per-step status.

Troubleshooting

If bootstrap fails:

1. Check SETUP_FAILED.md in the workspace.
2. Review first failing command and remediation notes.
3. Re-run with explicit toolchain versions if auto-detection was ambiguous.

Decision feedback protocol

See Also

Topic map: [[backend-platform]]

Decision feedback protocol (required):

• If post-run feedback capture is enabled for this runtime, emit a non-blocking post_run_feedback event via request_user_input after result delivery.
• Capture: decision (accepted|partial|rejected|deferred), outcome (good|neutral|bad|unknown), and confidence (high|medium|low).
• Persist with: python3 utilities/skill-builder/scripts/record_skill_feedback.py --skill-path <path/to/SKILL.md> --decision <...> --outcome <...> --confidence <...> --notes "...".
• The recorder tags subject (for example ui, code_review, backend, security) for cross-domain quality analytics.

Gotchas

• None yet. Capture recurring failures here as symptom -> cause -> do instead -> check.

Converted and distributed by TomeVault — claim your Tome and manage your conversions.