# bootstrap

Adopt this skill: https://proskills.md/skills/other/drix10-agent-flow-agents-skills-bootstrap

Page: https://proskills.md/skills/other/drix10-agent-flow-agents-skills-bootstrap
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: .agents/skills/bootstrap/SKILL.md
size: 8028
upstream: https://github.com/drix10/agent-flow/blob/main/.agents/skills/bootstrap/SKILL.md

````text
---
name: bootstrap
tags: [setup, scaffolding, agents-md, context-drift]
description: Interactive agent-flow setup for a repository. Scans the repo read-only, proposes AGENTS.md (root + per module), DOCS_INDEX.md and CONTEXT_MANIFEST.json with a confidence marker on every claim, calibrates protected paths and risk boundaries with the user, and writes each file only after the human approves it. Use when setting up agent-flow, when context files are missing, or when migrating from Root_AGENT.md. Also use whenever the user wants an AGENTS.md (or CLAUDE.md/GEMINI.md) written for a repo that doesn't have one, says their coding agents keep getting confused about the codebase, asks to "onboard" or "document" a repo for AI agents, or wants to set protected paths / risk boundaries — even if they don't say "agent-flow" or "bootstrap" by name.
compatibility: Requires git and Node 20+; runs through `npx @drix10/agent-flow`, so no package.json or node_modules is needed (any language). Pi gets the bootstrap_scan/bootstrap_write tools; other harnesses use `npx @drix10/agent-flow scan`/`template`/`schema` plus normal file edits with the user's approval.
---

# Bootstrap

You propose. The human decides. Every claim you write carries a confidence marker, and every risk boundary is a question to the human, never an assumption.

Why this matters: a context file with confident wrong claims makes agents *worse* than having no context at all (FM-01). Fewer true claims beat many plausible ones.

## Phase 1: Reconnaissance (read-only)

1. Call `bootstrap_scan` (outside Pi: `npx @drix10/agent-flow scan --json`). Every field it returns was read from a file, so those are `[HIGH CONFIDENCE]`. That covers: languages, package managers, test frameworks, commands (from `package.json` scripts, the `Makefile`, CI workflow `run:` steps and `build.sh`/`test.sh` scripts), CI files, existing context files, docs, default branch, and recent commits. A command shown as `…/<name>.py (12 files: …)` stands for that many sibling commands in CI.
2. **Secrets gate.** If `secretSuspects` is not empty, stop and show the paths and kinds (never the values). Context files are sent to model providers.
   - A tracked `.env` or key file must be removed from git and **rotated** before bootstrap continues. No exceptions.
   - Anything else (a hardcoded password in a compose file, a sample key): ask the human, and act on the answer. *Fakes or local-only values* → add the path to `secret_scan.ignore_paths`. *Real, or unsure* → stop until it's moved out and rotated. *Continue but keep it flagged* → leave it out of `ignore_paths`; the pre-commit hook keeps warning on it, and say so in Local traps.
3. **Existing context.** If `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `.cursorrules` or `.github/copilot-instructions.md` exist, read them first. They are the user's own rules. You merge into them; you never replace them. If you find `Root_AGENT.md` or `Per-app_AGENT.md` (agent-flow ≤1.0.x), offer to move them to `AGENTS.md`. No harness loads the old names automatically.
   Their rules bind you during bootstrap too. A repo that says "no code change without a plan entry" or "one theme per commit" means bootstrap touches context files and agent-flow wiring only; anything else you'd change (a build script, CI) becomes a recommendation for the human, not an edit.
4. Read the entry points and 2–3 representative modules so you can describe them from the code itself. Anything you describe without reading gets `[INFERRED]`.

## Phase 2: Proposal (interactive, nothing written)

Why `AGENTS.md`: Pi, Codex, Cursor, Copilot, Windsurf and most agents load `AGENTS.md` automatically — it's a [shared, Linux-Foundation-stewarded convention](https://agents.md), not something specific to this project. Claude Code loads `CLAUDE.md`, which can import it with one line (`@AGENTS.md`). Gemini CLI loads it when `context.fileName` includes `AGENTS.md`. One source of truth, every harness.

Templates ship with agent-flow; print them instead of searching the disk: `npx @drix10/agent-flow template` lists them, `npx @drix10/agent-flow template AGENTS.md` prints one.

Show the root `AGENTS.md` (template: `AGENTS.md`) as a proposal, one section at a time:

```
Repository map
  src/api/      HTTP handlers (Express)          [HIGH CONFIDENCE — read src/api/index.ts]
  src/billing/  Stripe integration               [HIGH CONFIDENCE — read src/billing/charge.ts]
  scripts/      deploy helpers                   [INFERRED — names only]

Commands
  npm test          [HIGH CONFIDENCE — package.json#scripts.test]
  npm run typecheck [HIGH CONFIDENCE — package.json#scripts.typecheck]
```

Rules for the proposal:
- **Keep it short.** Aim for under 150 lines at the root. Agents pay for every line on every task.
- **No directory-tree dumps.** They go stale on the first rename. Describe what each module is *for*.
- **Paths go in `backticks`.** `/doctor` checks every backticked path against the filesystem, so a wrong path gets caught. For a path you mention on purpose even though it no longer exists (history, a warning), add `<!-- agent-flow:ignore-refs -->` on that line.
- **Only real commands.** Only commands that exist in `package.json`, the `Makefile`, or CI.

Ask: *"What here is wrong or missing? What do new people always get wrong in this repo?"* Their answer to the second question gives you the **Local traps**, the most valuable part of the file.

For monorepos: propose `<package>/AGENTS.md` for each package that has its own rules (template: `module-AGENTS.md`). Skip packages that have nothing specific to say.

## Phase 3: Risk calibration (interactive)

Ask these one at a time. Never pre-fill the answers.

1. **Protected paths.** "Which paths must agents never modify?" These are usually migrations, lockfiles, CI, security modules, and vendored code. They go into `protected_paths`, and the guard and pre-commit hook enforce them (directories included: `rm`, `mv` and whole-tree git rewrites that reach them are refused). Also ask which files an agent must never read (credentials, key material beyond `.env*`, which is always denied): those go into `deny_read`. Never invent either list; the human owns it.
2. **Critical paths.** "Where are money, auth, contracts or PII?" These become `risk_boundaries` with `risk_level: critical`. Changes there get high-reasoning review, a draft PR, and human approval.
3. **Low-risk paths.** "What is safe for mechanical edits?" (docs, tests, generated code). These become `risk_level: low`.
4. **Auto-merge.** "Should low-risk changes that pass QA auto-merge?" Recommend **no** until the pipeline has shipped about 10 clean PRs in this repo. This sets `pipeline.auto_merge_low_risk`.
5. **Gates.** "Which commands prove a change works?" Offer the scan's commands (CI is the best source: it's what already guards `main`). These become `gates`, which the pipeline runs itself and judges by exit code. For each, settle:
   - **Where it can run.** A gate that needs a Linux toolchain or a POSIX filesystem (chmod tests, `fsync`, `/proc`) gets `"os": ["linux"]`; on other machines it's reported as skipped, never as a pass, and CI judges it. On Windows, string gates run in Git Bash.
   - **How long it takes.** Set `timeout_seconds` above the slowest honest run (default 600).
   - **Fast ones for the stop gate.** Lint, typecheck and unit tests can be `on_stop: true`; full builds can't.
   Prefer one gate per CI job over one per file. A loop in a string command is fine: `for t in a b; do python3 tests/$t.py || exit 1; done`.
6. **Models (only if there are critical areas).** "Should critical changes be reviewed by a stronger model than routine ones?" This sets `pipeline.models.high_reasoning` (and `pipeline.models.fast` for everything else), spelled the way their harness does (`opus` and `sonnet` on Claude Code). Left unset, a critical review runs on the same model as any other, and `status` and `run` say so. If they don't know, leave it unset; don't gue
````

## File: README.md
upstream: https://github.com/drix10/agent-flow/blob/main/README.md

````text
<div align="center">

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="assets/logo-dark.svg">
  <img src="assets/logo.svg" alt="Agent Flow" width="320">
</picture>

*Leave your coding agent alone with your repo. Come back to a reviewed pull request, not a mess.*

[![npm version](https://img.shields.io/npm/v/@drix10/agent-flow?style=flat-square&color=111111&label=npm)](https://www.npmjs.com/package/@drix10/agent-flow)
[![npm downloads](https://img.shields.io/npm/dm/@drix10/agent-flow?style=flat-square&color=111111&label=downloads)](https://www.npmjs.com/package/@drix10/agent-flow)
[![CI](https://img.shields.io/github/actions/workflow/status/Drix10/agent-flow/ci.yml?branch=main&style=flat-square&label=CI)](https://github.com/Drix10/agent-flow/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/license-MIT-111111?style=flat-square)](./LICENSE)

**One agent builds. A second reviews. A third tests. A guard keeps all three out of what they must never touch.**

[Install](#install) · [What you come back to](#what-you-come-back-to) · [How it works](#how-it-works) · [Harnesses](docs/HARNESS-MATRIX.md) · [FAQ](#faq)

</div>

---

## Install

```bash
npx @drix10/agent-flow install --harness claude
```

Then tell your agent *"use the agent-flow-bootstrap skill"*: it reads the repo and asks what must never be touched. After that, hand it a task:

```bash
npx @drix10/agent-flow run "Add a --json flag so CI can parse the output"
```

That's all of it. It runs in its own git worktree and stops with checked work and a draft pull request waiting for you. Works with Claude Code, Codex, Gemini CLI, Cursor, Copilot, Windsurf, Pi and anything that reads `AGENTS.md`: swap `claude` for `codex`, `gemini`, `cursor`, `copilot`, `windsurf` or `agents`. Node.js 20+, no runtime dependencies, no `package.json` needed in your repo.

**The guard blocks tool calls directly on Claude Code and Pi.** On the other hosts the skills guide the agent and a pre-commit hook and CI catch the slips: [what each host enforces](docs/HARNESS-MATRIX.md).

## What you come back to

Real output from a run on a real repository (trimmed):

```text
$ agent-flow status

Protection
  ✓ Claude Code guard hook is active
  ✓ 11 protected paths, 7 critical areas
  ✓ 1 review-only path: agents may add lines (a new CI test), a person reviews the pull request

Work
  · #100000 is ready: reviewed, checked, not pushed
      → agent-flow run 100000 --pr  to open the pull request
```

## Without it, and with it

| | ❌ Without Agent Flow | ✅ With Agent Flow |
|---|---|---|
| **Who checks the work** | The agent that wrote it | A second agent reviews, a third runs the checks |
| **The new test isn't in the CI list** | It edits the workflow or loosens the check to get green | It adds one line; every other CI change is refused |
| **Push to `main`, force-push, `--no-verify`** | Nothing stops it | Refused by the guard (Claude Code, Pi) or caught by the pre-commit hook |
| **A check fails** | You find out when you're back | It goes back to the Implementer, up to a round cap |
| **When you're back** | A whole diff to read | A draft pull request and a short list of what needs you |
| **Docs and context** | `AGENTS.md` describes the old behaviour | `agent-flow doctor` flags it |
| **What happened** | Ask the agent | A hash-chained audit log |

## From one real repo

Agent Flow ran for five days on a real C++ and Python research repository (294 role runs, about $83). The audit log recorded:

- **150 tool calls blocked**, among them 20 reads of secret files, 2 pushes to `main` and 1 `--no-verify`. Not every block was right: 16 were false alarms from a Windows path bug, fixed in 1.2.6.
- **15 lines added to the CI workflow, none changed or deleted.**
- **A median finished issue cost $0.90 and took 17 minutes**, over 63 issues.

One repository, one maintainer: an example, not a benchmark.

<details>
<summary><b>More ways to install and run</b></summary>

**Try it first, nothing installed and nothing written:**

```bash
npx @drix10/agent-flow scan
```

A read-only X-ray of any repository: languages, test and lint commands, CI, secret suspects. Or take just the skills, with any agent, via [skills.sh](https://skills.sh) (they call the CLI through `npx`, so there is still nothing to set up):

```bash
npx skills add Drix10/agent-flow
```

Install the harness files, then ask your coding agent to bootstrap the repository:

```bash
npx @drix10/agent-flow install --harness claude     # nothing to install first
```

Or install it from npm and use the short `agent-flow` command:

```bash
npm install --global @drix10/agent-flow             # the agent-flow command everywhere
agent-flow install --harness claude

npm install --save-dev @drix10/agent-flow           # or pin it in a Node project's package.json
npx agent-flow install --harness claude
```

On Claude Code you can also add the skills as a plugin: `/plugin marketplace add Drix10/agent-flow`, then `/plugin install agent-flow@agent-flow-marketplace`. **The plugin installs the skills only. The guard that blocks edits is wired by `install`, so run it too.** `agent-flow status` says whether the guard is on.

Use `codex`, `gemini`, `cursor`, `copilot`, `windsurf` or `agents` instead of `claude` for those tools. Pi users can install the package with `pi install npm:@drix10/agent-flow`.

In repositories without `package.json`, `install` vendors the small runtime needed by local hooks into `.agent-flow-runtime/`. Commit that directory so the hooks work for other clones; Agent Flow adds no package files or dependencies to the project.

To have your coding agent do the whole setup for you, give it the prompt in [SETUP.md](SETUP.md).

Bootstrap scans the code read-only and proposes `AGENTS.md`, `CONTEXT_MANIFEST.json` and related context files. It asks about protected paths and risk boundaries before writing. Review every proposal before accepting it.

For Claude Code, run a task with observable acceptance criteria:

```bash
npx @drix10/agent-flow run "Add a --json flag so CI can parse the output"
```

The command runs in a worktree and leaves checked work local by default. Add `--dry-run` to see setup gaps without launching roles. Add `--pr` to push the branch and open a pull request. Add `--auto-merge` only when you want eligible low-risk PRs queued for merge and the repository also sets `pipeline.auto_merge_low_risk: true`.

On other harnesses, ask the agent to use the `agent-flow-invoking-agents` skill for an issue or task. It applies the same state, risk, review and QA checks using that harness's launch procedure. Pi also provides `/implement <issue>`.

</details>

<details>
<summary><b>Keep it current, and run it in CI</b></summary>

```bash
npx @drix10/agent-flow@latest update --yes
npx @drix10/agent-flow doctor
npx @drix10/agent-flow audit-risk --fail-on-new
```

`update` refreshes unedited skills, hooks and the vendored runtime; it preserves files you customized. `doctor` checks context paths, commands, links and manifest freshness. `audit-risk` compares dependencies, secrets and other risk surfaces with `.risk-baseline.json`. See [Adoption](docs/ADOPTION.md) for update behavior by install type.

**Add CI checks**

The CLI works in Python, Go, C++, Rust and other repositories without adding `package.json` or `node_modules`. Node.js is needed in the CI job to run it.

```yaml
name: agent-context
on: [push, pull_request]
jobs:
  context:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 22 }
      - run: npx @drix10/agent-flow doctor
      # Create and review .risk-baseline.json before enabling this gate.
      - run: npx @drix10/agent-flow audit-risk --fail-on-new
```

Or use the [composite GitHub Action](action.yml), which also classifies pull request changes and can upload SARIF:

```yaml
- uses: actions/checkout@v4
  with: { fetch-depth: 0 }
- uses: Drix10/agent-f
````
