メニュー
Set up comprehensive AI-readable documentation strategy. Creates AGENTS.md, specs, ADRs, guides, plans, standards, and research templates. Triggers: /bootstrap-docs, set up documentation, create docs structure, bootstrap docs
デフォルトでは、最初にソースを確認する Prompt が選択されています。直接コマンドに切り替えるか、ローカルコピーをダウンロードすることもできます。
インストールを決める前に、SKILL.md と SkillsMP に表示されている付属ファイルをお読みください。
SOC 職業分類に基づく
Codex または Claude でインストール この Prompt をコピーして Codex、Claude、または他のアシスタントに貼り付けると、Skill ページを確認してインストールできます。
直接コマンドでは確認用 Prompt が省略されます。実行前にソースを確認してください。
npx skills add https://github.com/benjamcalvin/bootstraps --skill bootstrap-docsコマンドは1行のまま表示されます。コピー前に横へスクロールして全体を確認してください。
ローカルで確認しますか？SkillsMP が現在取得できるファイルをダウンロードできます。
SKILL.md を表示中
Address filtered review findings for implement workflow (runs as subagent)
Plan, implement code, tests, and create PR for implement workflow (runs as subagent)
Implementation, review, and merge — full lifecycle or any subset. Lean orchestrator that delegates all heavy work to isolated subagents. Triggers: /implement, $implement-lifecycle:implement, implement this, build this feature
| name | bootstrap-docs |
| description | Set up comprehensive AI-readable documentation strategy. Creates AGENTS.md, specs, ADRs, guides, plans, standards, and research templates. Triggers: /bootstrap-docs, set up documentation, create docs structure, bootstrap docs |
| argument-hint | [adr|specs|plans|guides|vision|standards|research|all] |
| context | fork |
| agent | general-purpose |
| allowed-tools | Read, Glob, Bash(cat *), Bash(find *) |
| license | MIT |
| metadata | {"version":"1.5.0","tags":["docs","documentation","strategy","scaffolding"],"author":"benjamcalvin","standards-sub-types":["testing","code","pr"]} |
Set up a comprehensive, AI-readable documentation strategy for this project.
Before starting, gather context by running these commands:
cat .bootstraps-preferences 2>/dev/null || echo "NO_PREFERENCES_FILE"find . -name "AGENTS.md" -not -path "./.git/*" -not -path "./node_modules/*" 2>/dev/null | head -20 || echo "NONE_FOUND"This skill runs six phases to set up project documentation. It is re-runnable — it checks what exists and only creates what's missing.
Argument handling:
all: run all phases for all enabled modulesadr, specs, plans, guides, vision, standards, research): run only Phase 0 (preferences) then the phases relevant to that module (directory, AGENTS.md, starter doc)adr,specsTemplate files are in the skill's assets/ directory at $SKILL_DIR/assets/. Read them on demand with the Read tool only when that phase needs them — e.g., Read $SKILL_DIR/assets/adr-template.md. Do NOT read all templates upfront; load each template only when creating the corresponding document.
Check if .bootstraps-preferences exists (from the context-gathering step above).
If NO_PREFERENCES_FILE (fresh repo):
On a fresh repo, the documentation strategy must be created before module selection. The strategy document defines the taxonomy and classification that inform which modules the user should enable.
Ask the user for:
docs/)Create a minimal .bootstraps-preferences in the project root with only project metadata and the strategy module:
project_name: "{name}"
docs_location: "docs/"
modules:
strategy:
status: pending
Create the {docs_location}/ root directory.
Create the strategy document now — execute the full Phase 2 logic (see below) to create {docs_location}/AGENTS.md and {docs_location}/CLAUDE.md. Since no modules have been selected or declined yet, include all modules in the taxonomy. Update strategy status to enabled in preferences.
Present module selection informed by the strategy. Now that the strategy document exists, present the user with module choices and reference the taxonomy it defines:
"Your documentation strategy has been created at
{docs_location}/AGENTS.md. It defines these documentation categories:
- vision/ — WHY: project vision, philosophy, strategy
- specs/ — WHAT: design documents (product, technical, standards)
- adr/ — WHY (decisions): immutable architecture decision records
- guides/ — HOW: step-by-step operational instructions
- research/ — WHAT (learned): compiled LLM research for future reference
- plans/ — WHEN: active execution work, ephemeral
Which modules would you like to enable? (default: all except
plans, which is opt-in)"
Ask which modules to enable (default: all except plans). Modules: adr, specs (with sub-options: product, technical, standards), plans, guides, vision, research.
If standards enabled, ask which standard types to include (default: all): testing, code, pr.
Update .bootstraps-preferences with the user's module selections. Modules the user selects start as pending. Modules the user declines are declined.
The full preferences file now looks like:
project_name: "{name}"
docs_location: "docs/"
modules:
strategy:
status: enabled
files:
- docs/AGENTS.md
- docs/CLAUDE.md
adr:
status: pending
specs:
status: pending
product:
status: pending
technical:
status: pending
standards:
status: pending
testing:
status: pending
code:
status: pending
pr:
status: pending
plans:
status: declined
guides:
status: pending
vision:
status: pending
research:
status: pending
Status values:
pending — user wants this module, not yet createdenabled — module is active, files have been created (listed in files)declined — user explicitly declined this module (don't ask again on re-runs)After files are created (in Phases 1–5), update each module's entry:
adr:
status: enabled
files:
- docs/adr/AGENTS.md
- docs/adr/CLAUDE.md
- docs/adr/001-first-decision.md
Confirm the preferences with the user before proceeding to Phase 1.
If preferences exist: Parse them from the Context above. Confirm with the user: "Found existing preferences for {project_name}. Proceeding with docs at {docs_location}." Check for any pending modules — these are work the user previously requested but hasn't completed yet. Check for any declined modules — don't offer these again unless the user explicitly asks. If strategy status is pending (interrupted previous run), create the strategy document (Phase 2 logic, including all modules in the taxonomy) before proceeding. If preferences contain no module entries besides strategy (indicating the previous run was interrupted before module selection), present module selection as in step 5 of the fresh-repo flow above. Move to Phase 1.
If a specific module argument was provided: Only that module matters — but preferences must still exist for project name and docs_location. If the module was previously declined, reset it to pending (the user is explicitly requesting it now).
Using the preferences, create the directory tree. Only process modules with status pending — skip enabled (already done) and declined (user said no). Also skip anything that already exists on disk.
For the docs location (e.g., docs/), create:
{docs_location}/ (root docs directory){docs_location}/adr/ (if adr is pending){docs_location}/specs/ (if any specs sub-module is pending){docs_location}/specs/product/ (if product is pending){docs_location}/specs/technical/ (if technical is pending){docs_location}/specs/standards/ (if any standards type is pending){docs_location}/plans/ (if plans is pending){docs_location}/guides/ (if guides is pending){docs_location}/vision/ (if vision is pending){docs_location}/research/ (if research is pending)For each directory created, also create the AGENTS.md + CLAUDE.md pair (these are populated in later phases — create empty files as placeholders if the content phase hasn't run yet).
Update .bootstraps-preferences after this phase: for each module that got directories created, add the directory and placeholder files to its files list (but keep status as pending — it becomes enabled once the content phases fill them in).
Report what was created and what was skipped.
Skip guard: If strategy status is already enabled in preferences (e.g., it was created during Phase 0 on a fresh repo), skip this phase entirely.
Create {docs_location}/AGENTS.md using the strategy template from $SKILL_DIR/assets/strategy-template.md.
Read the template, then customize it:
{PROJECT_NAME} with the project name from preferences{DATE} with today's date{DOCS_LOCATION} with the configured docs location{TAXONOMY_ENTRIES} block — include modules with status pending or enabled (not declined):
├── vision/ # WHY — project vision, philosophy, strategy├── specs/ with sub-entries for product/, technical/, standards/ as applicable├── adr/ # WHY (decisions) — immutable architecture decision records├── guides/ # HOW (do) — step-by-step operational instructions├── research/ # WHAT (learned) — compiled LLM research for future reference└── plans/ # WHEN — active execution work, ephemeral{TAXONOMY_DESCRIPTIONS} — include the description section for each non-declined module (vision, specs, adr, guides, research, plans). Use the descriptions from the strategy template but generalized for {PROJECT_NAME}.{CLASSIFICATION_ROWS} — include only rows for non-declined modules{FRONTMATTER_ROWS} — include only rows for non-declined document types:
**Decision:** Accepted | Superseded | Deprecated and **Superseded By:** ADR-NNN**Owner:** name**Owner:** name**Audience:** contributor | operator | consumer**Target Date:** YYYY-MM-DD**Topic:** area of researchAsk the user: "Use defaults for the master strategy, or customize interactively?" Defaults fill in all the template fields with sensible generic values. Interactive walks through each major section for the user's input.
Also create {docs_location}/CLAUDE.md containing only:
@AGENTS.md
Update .bootstraps-preferences: Set strategy status to enabled and record the files created.
For each module with status pending or enabled (not declined), create the AGENTS.md in its directory if it doesn't already have content. Each follows this pattern:
{Brief description of directory purpose}
## Contents
- (none yet — add entries as documents are created)
## Key Principles
- {principles specific to this doc type}
## Related Documents
- [Documentation Strategy](../AGENTS.md) — Rules governing all documentation
Module-specific content:
adr/AGENTS.md:
NNN-short-title.md. Sequential numbering, never reuse. Every ADR needs frontmatter: Status, Last Updated, Decision. Target: 200–600 lines (max 800).specs/AGENTS.md:
specs/product/AGENTS.md:
specs/technical/AGENTS.md:
specs/standards/AGENTS.md:
plans/AGENTS.md:
guides/AGENTS.md:
research/AGENTS.md:
auth-library-comparison.md, postgres-jsonb-performance.md. Include sources and applicability notes so future readers know when the research might be stale. Every research doc needs: Status, Last Updated, Topic.vision/AGENTS.md:
For each directory, also create a CLAUDE.md containing only @AGENTS.md.
Adjust relative links based on directory depth. For sub-directories under specs/, the link to the strategy doc is ../../AGENTS.md.
Update .bootstraps-preferences: For each module that got its AGENTS.md populated, add those files to the module's files list.
For each module with status pending (not declined or already enabled), ask the user if they want to create a starter document.
Present three options:
declined in preferences.Templates to use (read from $SKILL_DIR/assets/):
| Module | Template | Default filename |
|---|---|---|
| adr | adr-template.md | {docs_location}/adr/001-first-decision.md |
| specs/product | product-spec-template.md | {docs_location}/specs/product/overview.md |
| specs/technical | technical-spec-template.md | {docs_location}/specs/technical/architecture.md |
| standards/testing | standards-testing-template.md | {docs_location}/specs/standards/testing-standards.md |
| standards/code | standards-code-template.md | {docs_location}/specs/standards/code-conventions.md |
| standards/pr | standards-pr-template.md | {docs_location}/specs/standards/pr-standards.md |
| plans | plan-template.md | {docs_location}/plans/initial-plan.md |
| guides | guide-template.md | {docs_location}/guides/development-setup.md |
| vision | vision-template.md | {docs_location}/vision/philosophy.md |
| research | research-template.md | {docs_location}/research/initial-research.md |
Additional reference templates (not tied to a module — available for manual use):
changelog-template.md — Keep a Changelog format. Use when setting up a project CHANGELOG.md at the repository root.For defaults: replace {PROJECT_NAME} with project name, {DATE} with today's date, {NUMBER} with 001 for ADRs, {TITLE} with a sensible generic title, {OWNER} with "TBD", {TARGET_DATE} with "TBD". Leave section body content as template placeholders.
Standards sub-types: When creating standards starter docs, create one file per enabled standard type (testing, code, pr). Each uses its own template. Ask about all enabled types together — e.g., "Create starter standards docs? (testing, code, pr) — Defaults / Interactive / Skip". If the user picks Interactive, walk through each type separately. The {placeholders in braces} in standards templates mark sections the user should customize for their language/framework — during Interactive mode, ask what to fill in for each.
For interactive: present each section header and ask the user what to fill in. Build the document incrementally.
After creating each starter doc, update the corresponding directory's AGENTS.md Contents section to list the new file.
Update .bootstraps-preferences: For each module where a starter doc was created, set status to enabled and add the file to files. For modules the user skipped, set status to declined.
Check if the project has a root AGENTS.md (in the project root, not the docs directory).
If it exists: Offer to add a Documentation section with a link to the docs strategy:
## Documentation
- [Documentation Strategy]({docs_location}/AGENTS.md) — How we organize and maintain documentation
If it doesn't exist: Offer to create a minimal root AGENTS.md:
# {PROJECT_NAME}
## Documentation
- [Documentation Strategy]({docs_location}/AGENTS.md) — How we organize and maintain documentation
Also ensure a root CLAUDE.md exists. If creating one, content is @AGENTS.md. If one exists, offer to add @AGENTS.md if it's not already referenced.
Update .bootstraps-preferences: Record any root-level files created under the strategy module's files list.
Report to the user:
Created (enabled) — list all files and directories that were created this run
Skipped (enabled) — list anything that was already enabled from a previous run
Declined — list modules the user declined (can be re-enabled later with /bootstrap-docs {module})
Implementation sequence — present this ordered workflow as actionable next steps:
Recommended implementation sequence:
Work through your documentation in this order. Each step builds on the previous one.
- Documentation Strategy — If strategy status is
enabled: "✅ Complete. Establishes the rules for how all docs are organized, classified, and maintained." Ifpending: "Establish the rules for how all docs are organized, classified, and maintained. Ensure it's linked from your rootAGENTS.md/CLAUDE.mdso agents discover it automatically."- Vision — Articulate the product vision, philosophy, and success metrics
- Product Specs — Detail features, user stories, and requirements from the consumer perspective
- Tech Specs — Design the technical architecture and implementation approach
- Standards — Establish coding standards and engineering practices for the team
Skip any step whose module you declined. For execution tracking (tasks, milestones, delivery), use git issues and PRs — run
/implementto plan and track work against your specs.Run
/bootstrap-docs {module}to add individual modules later (including previously declined ones).
Audit mode (re-run on existing project):
When the skill detects an existing .bootstraps-preferences file, after reporting the Created/Skipped/Declined lists above, also report the implementation sequence progress:
Sequence progress:
For each step in the implementation sequence (Documentation Strategy → Vision → Product Specs → Tech Specs → Standards), check whether the corresponding module has status
enabledwith at least one non-placeholder file. Report:
- ✅ Documentation Strategy — complete (files: docs/AGENTS.md)
- ✅ Vision — complete (files: docs/vision/philosophy.md)
- ⬜ Product Specs — not started
- ⬜ Tech Specs — not started
- ⬜ Standards — not started
Suggest the user work on the first incomplete step next.