Adopt it in a project

A project consumes the devbook by pinning a version and pointing its agent instructions at the pages that apply.

Rules

• A project MUST pin an exact devbook tag (for example v1.2.0), never track main.
• A project MUST have an AGENTS.md at its root built from the template. CLAUDE.md and .github/copilot-instructions.md only point to it.
• AGENTS.md MUST list only the devbook pages the project uses (usually 6–12), not the whole devbook. Irrelevant context makes agents worse.
• Project docs MUST NOT copy devbook text. Link to it, and write down only what differs or is unique.
• Upgrading the devbook version MUST be its own pull request with a changelog entry in the project.
• A rule a project discovers that would apply elsewhere SHOULD be proposed back to the devbook, then removed from the project docs once released.

Setup steps

# 1. Add the devbook as a pinned submodule
git submodule add https://github.com/<owner>/devbook.raturi.in docs/devbook
git -C docs/devbook checkout v1.0.0
git add .gitmodules docs/devbook && git commit -m "docs: pin devbook v1.0.0"

# 2. Copy the agent files and fill them in
cp docs/devbook/templates/AGENTS.md ./AGENTS.md
cp docs/devbook/templates/CLAUDE.md ./CLAUDE.md
mkdir -p .github && cp docs/devbook/templates/copilot-instructions.md .github/

# 3. Start the project docs
mkdir -p docs/adr
cp docs/devbook/templates/project-brief.md docs/
cp docs/devbook/templates/technical-spec.md docs/
cp docs/devbook/templates/project-readme.md docs/README.md

Clone with submodules: git clone --recurse-submodules <repo>. In CI, enable submodule checkout.

Alternative: if submodules are awkward for a project, a small script may copy a tagged release into docs/devbook/ and record the version in docs/devbook/VERSION. The copy MUST be treated as read-only.

Typical project docs/ layout

docs/
├── README.md              # how to use these docs, file map, pipeline
├── CHANGELOG.md
├── devbook/               # pinned devbook (read-only)
├── adr/                   # decisions, including any loosened rule
├── project-brief.md       # problem, users, scope, success measures
├── technical-spec.md      # architecture, data, interfaces, acceptance criteria
├── design-system.md       # tokens, components (if UI)
├── domain-rules.md        # content and safety rules specific to the domain
└── …                      # anything unique: research docs, motion specs, taxonomies

Upgrading

1. Read the devbook CHANGELOG.md between your version and the new one.
2. Bump the submodule, run the project’s checks, fix what fails.
3. Update AGENTS.md if pages were added, renamed or split.
4. Record the upgrade in the project changelog.

A major devbook version means some rule changed in a way that can fail existing checks. Read those entries carefully.