bootstrap skill
✓ VerifiedScaffolds or retrofits documentation-led conventions like AGENTS.md, ADR catalogues, and plan queues into new or existing repositories.
- GitHub stars
- 16
- Files
- 2
- Last commit
- Oct 22, 2026
- License
- MIT
- Allowed tools
- —
What does the bootstrap skill do?
bootstrap scaffolds or retrofits documentation-led conventions like AGENTS.md, ADR catalogues, and plan queues into new or existing repositories.
Summary generated from the skill's SKILL.md.
About the bootstrap skill
Developers looking to standardize how AI agents and humans interact within a codebase can use this tool to establish documentation-led conventions. It scaffolds or retrofits essential files like AGENTS.md, CLAUDE.md, and CONVENTIONS.md into new or existing repositories. By setting up these structures, the skill creates a environment where coding agents follow specific rules and decision records are managed through a formal ADR catalogue.
When an agent loads this skill, it first inspects the repository to determine if it is a fresh project, an existing repo needing a retrofit, or a repository that already follows these conventions. It can add optional layers such as a plan queue, a glossary, or an agent coordination contract. The process is designed to be non-destructive, merging new files and rules into the current structure rather than overwriting existing content. It also handles complex migrations, such as switching ADR shapes or moving from legacy numbering systems to declared metadata fields.
What an agent can do with it
- 1Initialize a new repositorySet up a complete documentation-led layout from scratch in a brand new project.
Written from the skill's SKILL.md. Every use case is checked against a quote from it.
How to install the bootstrap skill
Each command copies the skill folder into the client's skills directory. Restart the client or start a new session to load it.Install the bootstrap skill in Plugin
/plugin marketplace add EvolveHQ/docflow /plugin install docflow@evolvehq
Install the bootstrap skill in Claude Code
~/.claude/skills/bootstrap/SKILL.md
$ npx degit EvolveHQ/docflow/plugins/docflow/skills/bootstrap ~/.claude/skills/bootstrapInstall the bootstrap skill in Claude Code (project)
.claude/skills/bootstrap/SKILL.md
$ npx degit EvolveHQ/docflow/plugins/docflow/skills/bootstrap .claude/skills/bootstrapInstall the bootstrap skill in Codex
~/.agents/skills/bootstrap/SKILL.md
$ npx degit EvolveHQ/docflow/plugins/docflow/skills/bootstrap ~/.agents/skills/bootstrapInstall the bootstrap skill in Gemini CLI
~/.gemini/skills/bootstrap/SKILL.md
$ npx degit EvolveHQ/docflow/plugins/docflow/skills/bootstrap ~/.gemini/skills/bootstrapInstall the bootstrap skill in Claude.ai
npx degit EvolveHQ/docflow/plugins/docflow/skills/bootstrap bootstrap && zip -r bootstrap.zip bootstrap # claude.ai → Customize → Skills → + → Create skill → Upload a skill → bootstrap.zip
Automated checks
Ran Nov 15, 2026Full report →Passed our automated checks. That is not a security audit: read the scripts before you let an agent run them. How checks work · What to fix for more points
- Source repository linked and reachableevolvehq/docflow/plugins/docflow/skills/bootstrap is public and reachablegithub.com/evolvehq/docflow/tree/HEAD/plugins/docflow/skills ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit 2026-10-22github.com/evolvehq/docflow/commits ↗Pass
- No download-and-run or credential theft in scriptsNo scripts in the skill folderPass
- No hidden instructions in SKILL.mdNo override phrases, safeguard switches, credential requests or hidden charactersgithub.com/evolvehq/docflow/blob/HEAD/plugins/docflow/skills ↗Pass
- Pre-approved tools are scopedNo pre-approved tools; the agent asks before using onegithub.com/evolvehq/docflow/blob/HEAD/plugins/docflow/skills ↗Pass
- SKILL.md follows the Agent Skills formatSKILL.md is 860 lines; the spec suggests under 500github.com/evolvehq/docflow/blob/HEAD/plugins/docflow/skills ↗Finding
SKILL.md
View on GitHubbootstrap
You are installing (or retrofitting) a documentation-led convention set in the current repo. The end state is a repo that can be driven by both humans and coding agents off a small set of canonical files. Carry over the mechanism described here — nothing about any other project.
Step 1 — Detect the situation
Inspect the repo before asking anything. Reuse explicit answers and sign-off already supplied in this session; never replace them with profile defaults or ask for them again. Before writing, summarise the resolved artefact root, depth, queue, gate and coordination/integration modes against those answers. If a host mirrors a selected folder into a sandbox, identify the actual target path and how verified outputs reach the selected folder; never call an untouched target complete merely because a scratch mirror passed.
-
Fresh repo (no source, no docs): you are scaffolding from zero.
-
Existing repo: you are retrofitting.
- Read any current
README.md,CONTRIBUTING.md,AGENTS.md,CLAUDE.md,docs/,adr/,.github/before proposing changes. - Preserve existing content. Merge, don't overwrite. If existing conventions conflict with the ones below, surface the conflict in your assessment summary.
- If ADRs already exist in another format, propose a migration plan (renumber, keep, translate) rather than creating a parallel tree.
- Read any current
-
Already a docflow repo (carries
AGENTS.md+CONVENTIONS.md+ an ADR catalogue): you are adding to an existing setup, not scaffolding. Do not re-scaffold the core or re-ask settled questions — read the recorded choices fromCONVENTIONS.md/AGENTS.md(ADR shape, status lifecycle, artefact root, multi-agent mode, and which optional layers already exist). Then offer to enable any opted-out optional layer still absent —plan/,_agent/,GLOSSARY.md,domains/, or the second ADR shape (the technology template) — and write only the chosen ones, by merge, under the recorded artefact root, leaving everything else untouched. Ask only the questions the new layers need (e.g. the coordination question when enabling_agent/— where a single writer without both a recorded verify gate and a plan queue correctly ends up with no_agent/at all, and the layer is simply not needed). This is the entry point for adding a layer you deferred at first bootstrap. A repo still carrying coordination files an earlier scaffold wrote keeps them: leave them in place here and let the audit skill report the layout.Enabling
GLOSSARY.mdwrites the canonical shell, never a rewrite. When the layer is chosen and the file is absent, write it fromtemplates/GLOSSARY.md— the optional heading and prose, then the oneTerm | Definitiontable recorded in the generatedCONVENTIONS.md§Glossary. If the file already exists, leave it untouched: enabling the layer adds nothing, andadd-conventionextends the existing file in the canonical shape orauditoffers a consented migration.Enabling the second ADR shape is a scheme switch, not a file copy. It is the one deferred layer that changes a choice already recorded, so write all of it in one pass or none of it: replace §ADR Shapes in
CONVENTIONS.mdwith the two-shape text, add the technology section-order and shape bullets toAGENTS.md, writeadr/0000-template-technology.md, and regenerateINDEX.mdwith the Shape column. Existing ADRs keep their numbers and stay capability — an absentshape:field already means capability, so no ADR is rewritten and nothing is renumbered. Half of the switch strands the repo in the state the Step 4.5 cross-check calls a contradiction: a technology template that a single-shape scheme will never select.A repo already on the legacy range encoding gets the migration offer instead. Some two-shape repos were scaffolded before the shape became a declared field and encode it in the number: §ADR Shapes records a cutoff (capability below it, technology at or above), and
adr/holds a template numbered other than0000(e.g.adr/0100-template.md). Either signal alone identifies it. Such a repo is not missing a layer — it has both shapes already — so do not offer the scheme switch above, which would strand it with two rival encodings. Offer the migration onto the declared field, on the same terms the audit skill uses:- Show the old-to-new number map first, as a dry run: capability
ADRs keep their numbers; technology ADRs take the numbers following
the highest capability ADR, in their original relative order.
Alongside it, list the references that follow (
depends-on,supersedes/superseded-by, relativeadr/NNNN-*.mdlinks,INDEX.md, domainREADME.mdlistings,plan/todo/owning-ADR lines) and what is left as history (plan/done/footers, commit messages, tags). - Write nothing without an explicit confirmation of that map. Declining is a valid outcome: the repo keeps the range encoding and keeps passing its own rules.
- On confirmation, apply the migration exactly as the audit skill's
migration step specifies — renumber, stamp
shape:on every ADR, rewrite every in-catalogue reference, replace the boundary template withadr/0000-template-technology.md, rewrite §ADR Shapes to the declared field and drop any seed-ADR exception clause, regenerateINDEX.mdwith the Shape column — and land it as one commit whose message lists every old-to-new pair. That procedure is the single source of truth; do not paraphrase a second variant of it here. - Then continue the re-run normally for the layers that really are
absent (
plan/,_agent/,GLOSSARY.md,domains/).
- Show the old-to-new number map first, as a dry run: capability
ADRs keep their numbers; technology ADRs take the numbers following
the highest capability ADR, in their original relative order.
Alongside it, list the references that follow (
State which situation applies in one line before asking the assessment questions.
Step 2 — Target layout
<repo>/
AGENTS.md # hard rules for coding agents — entry point
CLAUDE.md # one-liner: @AGENTS.md
README.md # human-facing project summary (preserve if exists)
CONVENTIONS.md # authoring rules: ADRs, naming, status, audit, git
INDEX.md # generated table of all ADRs
GLOSSARY.md # shared terms (optional — see Q7)
adr/
0000-template.md # capability-ADR template (always)
0000-template-technology.md # technology-ADR template (only if two shapes — see Q2)
NNNN-<kebab-slug>.md # one ADR per decision, contiguous numbering
domains/<slug>/README.md # optional (see Q7)
plan/
README.md
todo/NNNN-<slug>.md
done/<YYYY-MM-DD>-<slug>.md
_agent/ # the agent operating contract (see Q5) — optional
ROLES.md # who writes what (several writers only)
LOCKS.md # the file-claim mutex (shared checkout only)
prompts/autonomous.md # how an unattended run behaves (only with a
# verify gate — Q8 — AND a plan queue — Q4a)
federation.md # multi-repo only (Q11): this repo's back-pointer
federation-index.md # multi-repo only (Q11): member index — home repo only
Placement. The tree above shows the root option. AGENTS.md and
CLAUDE.md always sit at the repository root; adr/, plan/, _agent/,
INDEX.md, and CONVENTIONS.md go under the artefact root chosen in
Q12 (default .docflow/, e.g. .docflow/adr/, .docflow/plan/).
Discovery. Tools locate the artefact root without reading
CONVENTIONS.md first: a .docflow/ directory at the repository
root is the root; for any other root, bootstrap writes a .docflow
file at the repository root — a one-line pointer, root: <path>
(e.g. root: docs/, root: .). Neither present means a pre-contract
repo (tools probe docs/, then the repository root, for a
CONVENTIONS.md naming an artefact root) or not a docflow repo.
_agent/ is the agent operating contract — who writes what, the one
real mutex, and how an unattended run behaves. It holds nothing git
already records: no duplicate shipped record, no dashboard of what is in
flight, no snapshot of the current state, no hand-off. Which of the
three files above exist follows entirely from Q5, Q8 and Q4a, and a repo
with no _agent/ directory at all is a valid outcome.
Core vs optional layers. Only the core is always written:
AGENTS.md, CLAUDE.md, CONVENTIONS.md, adr/0000-template.md, and
INDEX.md. A repo with just these is a valid, lightweight docflow repo — a
classic ADR catalogue with conventions. Everything else is an opt-in
layer: the plan/ queue (Q4a), the _agent/ contract (Q5 + Q8 + Q4a —
a single writer without both a verify gate and a plan queue gets none of
it), GLOSSARY.md and
domains/ (Q7). Omitting any optional layer is a valid state, not an
error; a lifecycle skill that needs an absent layer refuses cleanly and
names what is missing.
For a multi-repo product (one product spread across several repos —
see Q11), two extra files appear: federation.md, a small back-pointer
every member repo carries, and federation-index.md, the authoritative
member list that lives only in the home/establishing repo. All federation
artefacts — federation.md, federation-index.md, and the derived
roll-up ROLLUP.md — are placed under the configured artefact root.
A standalone repo has none of them.
Step 3 — Conventions to install
- ADRs are the source of truth. One decision per ADR. Splits become new ADRs that supersede; never expand scope inside an existing one.
- Up to two ADR shapes, declared by field. A repo that
distinguishes the two records the distinction in each ADR's
shape:metadata field (capabilityortechnology; an absent field means capability) — never in a number range. Every ADR takes the next contiguous number whatever its shape, and each shape has its own template, both numbered0000.- Capability ADR (what the system must do). Section order: metadata → Context → Capability statement → User stories / scenarios → Acceptance criteria → Out of scope → Open questions → References → Revision History → Approvals.
- Technology ADR (how it's built). Section order: metadata → Context → Decision → Rationale → Consequences → Acceptance criteria → Out of scope → Open questions → References → Revision History → Approvals. Rationale must name alternatives considered and give specific rejection reasons (not "simpler" / "more idiomatic").
- Status lifecycle:
Proposed → Accepted → Implemented → (Superseded | Deprecated). Terminal states reachable from any prior state. Status drives plan-folder placement:Accepted→plan/todo/,Implemented→plan/done/. - Filenames:
adr/NNNN-kebab-slug.md, zero-padded 4 digits, contiguous, no reserved gaps. Cross-references use relative paths. - Acceptance criteria are testable and numbered. Tests map back to them where practical.
- Audit discipline. Substantive ADR changes append a Revision
History row. Editorial changes (typos, formatting, link fixes) are
excluded but flagged
editorialin the commit message. Approvals table populates when an ADR is Accepted and updates on each later substantive revision. - INDEX.md is regenerated from ADR metadata after any ADR change. Treat as derived, not hand-edited.
plan/is the work queue. When work ships,git mv plan/todo/X plan/done/<date>-X, any plan-item Status removal, owning ADR status advance, andINDEX.mdregeneration are grouped in the completion commit. Under direct-to-main integration that commit is pushed to the integration branch and the moved file's footer names the HEAD SHA (and deploy artefact id if applicable). Under pull-request integration those changes are the last commit on the pull-request branch before it is marked ready, the footer names the pull request, and the merge is the completion event.- Coordination is a contract, not a log.
_agent/holds only what git cannot tell you, and each mode (Q5) prescribes exactly its own files — nothing else is written there. In a shared checkout, an agent appends a row to_agent/LOCKS.md(<agent-id> | <path> | <ISO-8601 timestamp>) before editing and removes it on commit; that ledger is the one real mutex, and a queue item is claimed on the item itself. In separate worktrees a queue item is claimed by pushingclaim/<item-key>— the queue file name without its extension — plus a draft pull request from it where integration is pull-request based; the push is what excludes the second writer, and no ledger is kept. Under a single writer there is nothing to serialise and nothing to claim. No mode keeps duplicate shipped state, a dashboard of what is in flight, or a snapshot of the current state: git history andplan/done/are the record, and the live branches and pull requests are what is in flight. - Git contract. Conventional Commits. Mandatory
Rationale:footer on commits touching an ADR. Signed commits unless the user opts out. NoCo-Authored-Bytrailer for agent work unless the user asks for one. - AGENTS.md is the hard-rules entry point; CLAUDE.md is the
one-liner
@AGENTS.mdfor compatible agents that read it. - ADRs are internal artefacts — never user-visible. ADR numbers,
ADR titles, and the existence of the ADR catalogue must NEVER
appear in product code paths that reach a user: UI strings, API
response bodies, error messages, log lines emitted to customers,
public documentation, release notes, marketing copy, or support
communications. ADRs are for builders, not users. References ARE
allowed in: code comments (
// see adr/0042-foo.md), commit messages, PR descriptions, internal docs,AGENTS.md,CONVENTIONS.md,INDEX.md, and theplan/queue. When in doubt, ask whether a non-builder would ever see this string — if yes, the ADR reference comes out.
Files in this skill
2bootstrap skill questions
How do I install the bootstrap skill in Claude Code?
Run npx degit EvolveHQ/docflow/plugins/docflow/skills/bootstrap ~/.claude/skills/bootstrap. Claude Code loads skills from ~/.claude/skills (all projects) or .claude/skills (one project) and uses a skill when its description matches the task.
Which clients can use the bootstrap skill?
Any client that reads the Agent Skills format: Claude Code, Codex, Gemini CLI and claude.ai (upload as a ZIP). Scripts in the skill run only where the client allows code execution.
Does this tool overwrite my existing files?
No, it preserves existing content and merges changes rather than overwriting. If existing conventions conflict with the new ones, it will surface the conflict in an assessment summary.
Can I add optional layers to an existing documentation setup?
Yes, if the repo already carries AGENTS.md and CONVENTIONS.md, you can enable optional layers like plan/, _agent/, GLOSSARY.md, or domains/.