longranger2/project-doc-bootstrap/project-doc-bootstrap

Project Doc Bootstrap

Use this skill to set up a repository so future AI sessions can reach useful context in a few reads instead of re-deriving structure from source every time.

Default convention:

• CLAUDE.md is the source of truth.
• AGENTS.md is a sibling symlink to CLAUDE.md.
• Every directory that has a `CLAUDE.md` must also have an `AGENTS.md` symlink as a sibling. This is a hard invariant — never create one without the other.
• Docs follow a fractal hierarchy: L1 root guide, L2 directory guides, L3 file-header notes only where needed.

If the user explicitly wants different filenames or a different source-of-truth file, adapt the convention. Otherwise default to CLAUDE.md + AGENTS.md.

When to Use

Use this skill when the user wants to:

• initialize a new project's AI-facing docs
• set up CLAUDE.md / AGENTS.md
• design a directory-level documentation hierarchy
• make a repo easier for AI to understand and maintain
• standardize how docs are updated when files move or modules grow
• install a pre-commit hook that enforces doc-sync at commit time

Quick Start Workflow

1. Read references/blueprint.md to choose the documentation model.
2. Read references/workflow.md to bootstrap the repo in the right order.
3. Read references/templates.md for ready-to-copy templates: CLAUDE.md skeletons, symlink commands, and pre-commit hook scripts.

Core Outcomes

By the end of the task, the repo should have:

• one root CLAUDE.md that explains architecture, rules, and the doc system
• one root AGENTS.md -> CLAUDE.md symlink
• L2 docs for top-level and core module directories
• L2 docs for subdirectories that cross the documentation threshold
• explicit rules for when new L2 docs should be created later
• a pre-commit hook (.git/hooks/pre-commit) that warns when staged source files are in a documented directory whose CLAUDE.md was not also staged (hook is local-only, not committed)
• a verification pass confirming symlink integrity, hook installation, and obvious gaps

Operating Rules

• Prefer small, stable documentation rules over exhaustive directory-by-directory prose.
• Keep each SKILL.md and each L2 doc concise; move detail into references when it grows.
• Prefer symmetry for repeated trees such as locales, themes, provider categories, or parallel route groups.
• Do not create L2 docs for every leaf by default; stop when parent docs keep the tree understandable.
• Treat doc maintenance as part of code maintenance: if a directory changes shape, update its CLAUDE.md in the same task.

Decision Rules

Create an L2 doc when a directory meets any of these:

• it is a top-level or core module directory
• it has 4 or more direct child items or source files
• it is a clear module boundary or high-frequency entrypoint
• its parent doc can no longer explain it within 3 reads

Do not create an L2 doc when all of these are true:

• the directory has only 1-3 files
• it is a leaf route or narrow implementation detail
• its parent doc already provides enough context

Delivery Checklist

• [ ] Root CLAUDE.md exists and defines the doc hierarchy.
• [ ] Root AGENTS.md is a symlink to CLAUDE.md.
• [ ] Top-level/core directories have L2 docs where appropriate.
• [ ] Every directory with a `CLAUDE.md` has a sibling `AGENTS.md` symlink. This is a hard invariant — never create one without the other.
• [ ] Repeated structures are symmetric where that helps maintenance.
• [ ] New AGENTS.md files are symlinks, not duplicated files.
• [ ] .git/hooks/pre-commit exists and is executable (local-only, not committed).
• [ ] The final audit lists any intentionally undocumented directories.

Final Verification

Before closing the task, run these checks in order and do not skip any:

1. List every CLAUDE.md in the repo.
2. For each CLAUDE.md, verify a sibling AGENTS.md symlink exists and points to that CLAUDE.md.
3. Verify .git/hooks/pre-commit exists and is executable.
4. Spot-check 2-3 representative L2 docs for format consistency.
5. Report what was intentionally left undocumented and why.

Use the audit commands in references/templates.md to automate steps 1-2.