Bootstrap

/bootstrap

Quick Ref: Product/operations layer around the ao quick-start core seed. Progressive — bare repos get the golden path first, existing repos fill gaps only.

YOU MUST EXECUTE THIS WORKFLOW. Do not just describe it.

Quick Start

/bootstrap

That is it. One command. Every step below is idempotent — existing artifacts are never overwritten.

External Tools

• ao (optional) — AgentOps CLI. Required only for optional hook activation (Step 6). Bootstrap skips hooks gracefully when missing.
• bd (optional, recommended) — beads CLI. Bootstrap probes for bd in Step 0.5 and, when missing, points the user at scripts/install-bd.sh with a copy-paste command. Bootstrap never installs bd on the user's behalf.

Flags

Execution Steps

Step 0: Detect Repo State

git rev-parse --is-inside-work-tree >/dev/null 2>&1 || { echo "NOT_A_GIT_REPO"; exit 1; }
HAS_GOALS=$([[ -f GOALS.md ]] && echo true || echo false)
HAS_PRODUCT=$([[ -f PRODUCT.md ]] && echo true || echo false)
HAS_README=$([[ -f README.md ]] && echo true || echo false)
HAS_PROGRAM=$([[ -f PROGRAM.md || -f AUTODEV.md ]] && echo true || echo false)
HAS_AGENTS=$([[ -d .agents ]] && echo true || echo false)
HAS_HOOKS=$(grep -q "agentops" .claude/settings.json 2>/dev/null && echo true || echo false)
HAS_AO=$(command -v ao >/dev/null && echo true || echo false)
HAS_BD=$(command -v bd >/dev/null && echo true || echo false)

Classify the repo:

If --dry-run is set: report the state and what would be created, including whether bd would be recommended (when HAS_BD is false), then stop. Do not proceed to Steps 1-6.

If the repo is complete and --force is not set: report "Repo is fully bootstrapped. Nothing to do." and stop.

Step 0.5: Recommend bd

If HAS_BD is true: skip. Report "bd: present."

If HAS_BD is false: report "bd: not installed (recommended). Install with: `bash scripts/install-bd.sh`" and continue. Bootstrap does NOT run the installer — bd is optional, the user decides.

If scripts/install-bd.sh is absent at the repo root, drop the install hint and just report "bd: not installed (recommended). See https://github.com/steveyegge/beads".

Step 1: GOALS.md

If HAS_GOALS is false (or --force is set):

Run the goals skill to initialize GOALS.md interactively:

Skill(skill="goals", args="init")

If HAS_GOALS is true and --force is not set: skip. Report "GOALS.md exists -- skipped."

Step 2: PRODUCT.md

If HAS_PRODUCT is false (or --force is set):

Run the product skill to generate PRODUCT.md interactively:

Skill(skill="product")

If HAS_PRODUCT is true and --force is not set: skip. Report "PRODUCT.md exists -- skipped."

Step 3: README.md

If HAS_README is false (or --force is set) AND PRODUCT.md now exists:

Run the doc skill in README mode to generate README.md:

Skill(skill="doc", args="--mode=readme")

If HAS_README is true and --force is not set: skip. Report "README.md exists -- skipped."

If PRODUCT.md does not exist (Step 2 was skipped or failed): skip. Report "README.md skipped -- PRODUCT.md required first."

Step 4: Core Seed and .agents/ Structure

If HAS_AGENTS is false (or --force is set):

Prefer the CLI golden path:

ao quick-start --no-beads

If ao is unavailable, create the minimal directory structure and report the exact command to repair later:

mkdir -p .agents/learnings .agents/council .agents/research .agents/plans .agents/rpi .agents/patterns .agents/retro .agents/handoff

Create .agents/AGENTS.md if it does not exist:

# Agent Knowledge Store

This directory contains accumulated knowledge from agent sessions.

## Structure

| Directory | Purpose |
|-----------|---------|
| `learnings/` | Extracted lessons and patterns |
| `council/` | Council validation artifacts |
| `research/` | Research phase outputs |
| `plans/` | Implementation plans |
| `rpi/` | RPI execution packets and phase logs |

## Usage

Knowledge is automatically managed by the AgentOps flywheel:
- `/inject` surfaces relevant prior knowledge at session start
- `/post-mortem` extracts and processes new learnings
- `/compile` runs maintenance (mine, grow, defrag)

If HAS_AGENTS is true and --force is not set: skip. Report ".agents/ exists -- skipped."

If ao is unavailable after fallback creation: report "Core seed repair command: ao quick-start --dry-run after installing ao."

Step 5: PROGRAM.md / AUTODEV.md

If HAS_PROGRAM is false (or --force is set):

Use the existing autodev CLI path:

ao autodev init "your current objective"

If ao is unavailable: do not create a placeholder. Report "PROGRAM.md skipped -- install ao, then run: ao autodev init \"your current objective\"."

If HAS_PROGRAM is true and --force is not set: skip. Report "PROGRAM.md/AUTODEV.md exists -- skipped."

Step 6: Optional Hook Activation

Do not activate runtime agent hooks. AgentOps 3.0 is runtime-hookless: ao quick-start, execution packets, explicit validation, and knowledge compounding deliver first value without Claude/Codex runtime hooks. Routine release authority is the local cockpit gate (ao gate check plus the installed Git pre-push/pawl proof path); GitHub Actions are PR/tag/manual backstop telemetry. There is no ao command or flag that installs runtime hooks — hooks were removed from the CLI.

If the user explicitly requests hooks, they are opt-in and author-it-yourself: point them at the hooks-authoring skill, which scaffolds project-local hooks into .claude/settings.json. Bootstrap itself never writes hooks.

If hooks were not explicitly requested: skip. Report "Runtime hooks optional -- skipped. AgentOps 3.0 is runtime-hookless; routine release authority is the local cockpit gate. To author your own, use the hooks-authoring skill."

If HAS_HOOKS is true: report "Hooks already present in .claude/settings.json -- left untouched."

Step 7: Report

Output a summary table:

Bootstrap complete.

| Artifact      | Status  |
|---------------|---------|
| GOALS.md      | created / skipped / failed |
| PRODUCT.md    | created / skipped / failed |
| README.md     | created / skipped / failed |
| PROGRAM.md    | created / skipped / failed |
| .agents/      | created / skipped / failed |
| Hooks         | optional / activated / skipped / failed |
| bd            | present / recommended (not installed) |

Repo is now AgentOps-ready. Next: /rpi "your first goal"

Examples

Bare Repo

User says: /bootstrap

What happens: Agent detects no AgentOps artifacts. Runs /goals init, /product, /doc --mode=readme, creates .agents/ structure, leaves hooks optional. Reports all five core artifacts created.

Partial Repo (has GOALS.md and .agents/)

User says: /bootstrap

What happens: Agent detects existing artifacts. Skips GOALS.md and .agents/. Runs /product, /doc --mode=readme. Leaves hooks optional unless explicitly requested. Reports two created, three skipped.

Dry Run

User says: /bootstrap --dry-run

What happens: Agent detects repo state and reports what would be created. No files are written.

Troubleshooting

See Also

• goals -- Fitness specification and directive management
• product -- Product definition generation
• doc -- README generation (--mode=readme) + repo docs
• status -- New user onboarding (lighter than bootstrap)
• related operator runbooks -- host-hygiene runbooks (PATH rationalization, etc.)

Reference Documents

• references/bootstrap.feature — Executable spec: bare repo gets golden path, existing repo fills gaps only, idempotent never-overwrite (soc-qk4b)

Related Operator Runbooks

Bootstrap touches .agents/ state and bd state (and shell rc files only via PATH hygiene, not hook activation — AgentOps 3.0 is hookless). These runbooks cover the operator-side hygiene that bootstrap assumes is healthy on entry. Read the relevant entry when bootstrap reports an unexpected skip, when the operator's environment looks suspicious, or when handing a fresh host to a new agent.

Index

docs/runbooks/path-rationalization.md

Audits and cleans shell PATH pollution across .bashrc, .zshrc, .zshenv, .profile, .zprofile, and .bash_profile. Walks through inventory, classification, idempotent prepends, subshell verification, and rollback from a timestamped backup.

When to read: The host has accumulated many PATH entries, which ao or which bd resolves to a stale or temp-dir copy, shells are slow to start, or a previous installer has left /tmp/*-install lines in an rc file. Run before bootstrap on a long-lived host where the operator has not pruned PATH in a while.

Adding a runbook to this list

When a new runbook lands under docs/runbooks/, add a sub-section above with a one-paragraph description and an explicit "When to read" line. Keep entries scoped to runbooks bootstrap callers actually need — operational concerns adjacent to repo initialization, host hygiene, or the rc files bootstrap may end up touching.

---

Pattern adopted from path-rationalization (ACFS skill corpus). Methodology only — no verbatim text.