Docs/Recipes/Customization Recipes

Customization Recipes

Everything you can change without editing skill sources. Personas, integrations, and skill drop-ins all live behind spec-init customize.

Swap the persona

Persona drives CLAUDE.md verbosity and the "Why this step?" annotations. Swap safely - customize re-derives CLAUDE.md from the pristine .spec-init/base/ snapshot.

# switch from engineer to student
spec-init customize --persona student

Replays CLAUDE.md

--persona rewrites CLAUDE.md from the snapshot. User edits below the persona block are preserved; edits inside the persona block are replayed.

Toggle integrations

Graphify and Obsidian are additive. Toggling on drops in their config files and integration sections; toggling off removes both, leaving zero residual files.

# add
spec-init customize --add graphify
spec-init customize --add obsidian

# remove
spec-init customize --remove obsidian

Surgical re-derive

--add / --remove only replays files whose snapshot content contains that integration’s marker. Memory files without the marker are untouched.

Drop in a skill

Copy a skill definition from the payload catalog into your project’s .claude/skills/ directory. Custom same-named files override defaults.

spec-init add-skill spec-requirements
# then edit .claude/skills/spec-requirements/SKILL.md

Upgrade safely

A newer template payload merges through a three-way merge against the pristine snapshot. Conflicts surface as git-style fences for manual resolution - never silent overwrites.

spec-init upgrade
# review conflicts, then
git add . && git commit -m "chore: template upgrade"

Diagnose drift

doctor cross-checks the SRS §6 required-file list, the template-version field, and the .spec-init/base/ snapshot. Run it after any manual edit to CLAUDE.md.

spec-init doctor
# ✓ CLAUDE.md present
# ✓ template-version 1.0.0
# ✓ .spec-init/base/ snapshot intact

‹ Previous

Learning Map