Bootstrap

For every missing file, create it from the template repo pattern. Stack-specific files (.gitignore, Makefile targets, linting, .vscode/extensions.json) are adapted to the detected stack.

Core files (see references/modules.md for full manifest):

• Root: CLAUDE.md, ARCHITECTURE.md, Makefile, README.md, LICENSE, .env.example, .editorconfig, .gitignore, .gitattributes
• .claude/rules/: 5 governance rules (mission, phase gates, truth hierarchy, doc sync, DoD)
• .claude/docs/: 5 agent context files (architecture, conventions, testing, project-state, cheatsheet-standard)
• docs/: decisions (ADRs), discovery, sessions, log
• templates/: design-doc, feature-spec, session-note
• .github/: PR template, issue templates, CI workflow
• .vscode/: settings, extensions
• .githooks/: pre-push (blocks main)

Never overwrite existing files. If a file exists, skip it.

Step 3: Module Prompts

Check for optional modules. Auto-detect where possible, ask one yes/no each otherwise:

• Docker: detected (Dockerfile exists or stack is web app/API) — adds Dockerfile, compose, .dockerignore
• Linting: detected (by stack) — adds Biome/ESLint/Ruff + pre-commit hooks
• Testing: detected (by stack) — adds test config + example stub
• Migration: asked ("Porting an existing project?") — adds migration docs + stance framework
• Community health: asked ("Is this repo public?") — adds CONTRIBUTING, SECURITY, CODE_OF_CONDUCT, CODEOWNERS
• Deployment: asked ("Does this project deploy somewhere?") — adds deploy config
• Security scanning: auto-added if GitHub repo — Dependabot + CodeQL

See references/modules.md for module file manifests.

Step 4: Two Questions

Ask exactly two questions:

1. "Use git worktrees for feature work? Yes / No"
2. "Auto-commit on session end? Yes / No"

If worktrees: document in .claude/docs/conventions.md. If auto-commit: add Stop hook to .claude/settings.json:

{
  "hooks": {
    "Stop": [
      {
        "type": "command",
        "command": "cd \"$PROJECT_DIR\" && git add -A && git diff --cached --quiet || git commit -m \"auto: session checkpoint $(date +%Y-%m-%d-%H%M)\""
      }
    ]
  }
}

Step 5: GitHub Audit

If a remote exists, run the github-audit skill. Report the score and what the scaffold fixed vs. what still needs manual attention.

Step 6: Validate

Before committing, verify:

• All CLAUDE.md pointers resolve to real files in .claude/docs/
• All Makefile targets reference valid configs
• All internal doc links resolve
• .claude/docs/project-state.md reflects actual modules installed

Report any issues found and fix them.

Step 7: Seal

git init -b main                    # if not already a repo
gh repo create (private/public)     # if no remote, ask
git config core.hooksPath .githooks # activate hooks
git add -A
git commit -m "Bootstrap project governance"
git push -u origin main             # if remote exists

Create memory file at ~/.claude/projects/.../memory/project_{name}.md. Add entry to MEMORY.md.

Step 8: Handoff

Print recap:

• Files created (count)
• Files skipped (already existed)
• Modules installed
• GitHub audit score (if applicable)
• Current phase: Gate 0 (Discovery) — in progress

Log the operation to docs/log.md.

If invoked from /spec, return control to spec with governance confirmed.

Stack-Specific Adaptations