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