⏳ This skill is pending AI review.
Scores will appear once the review pipeline completes.
bootstrap
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.
Choose how to use this skill
You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.
1. Native installer
This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.
Do not guess an installer command or replace an existing version without reviewing the diff.
2. Complete package recommended
Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.
No complete ProSkills package is published for this listing yet.3. Prompt-only
Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.
Need only the instruction file?
Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.
No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.
// RATINGS
// README
Leave your coding agent alone with your repo. Come back to a reviewed pull request, not a mess.
One agent builds. A second reviews. A third tests. A guard keeps all three out of what they must never touch.
Install · What you come back to · How it works · Harnesses · FAQ
Install
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:
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.
What you come back to
Real output from a run on a real repository (trimmed):
$ 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
mainand 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.
Try it first, nothing installed and nothing written:
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 (they call the CLI through npx, so there is still nothing to set up):
npx skills add Drix10/agent-flow
Install the harness files, then ask your coding agent to bootstrap the repository:
npx @drix10/agent-flow install --harness claude # nothing to install first
Or install it from npm and use the short agent-flow command:
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.
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:
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>.
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 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.
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, which also classifies pull request changes and can upload SARIF:
- uses: actions/checkout@v4
with: { fetch-depth: 0 }
- uses: Drix10/agent-f
// HOW IT'S BUILT
// FILES
2 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.
.agents/skills/bootstrap/SKILL.md7.8 KBupstream ↗
--- 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 gueREADME.mdupstream ↗
Contents are not inlined in the catalog. Open the upstream file.
Plain-text copy, no login: /skill-bundles/drix10-agent-flow-agents-skills-bootstrap.md