Docs/Recipes/Customization Recipes

Customization Recipes

Everything you can change without editing skill sources. Persona and integrations live behind spec-init customize; day-to-day preferences live in spec.config.js.

Edit spec.config.js

spec.config.js is the friendly front door to your project preferences. Claude reads it at the start of every session (see CLAUDE.md section 2) and honors it - no build step, and the CLI never parses it, so an edit can never break your scaffold. Use it to disable skills you do not want, tune the workflow, or add project-wide instructions.

module.exports = {
  skills: { disabled: ['spec-market-research'] },
  workflow: { phases: ['requirements','design','plan','feature'], allowSkip: false },
  settings: {
    commitSuggestions: true,
    customInstructions: ['Prefer Drizzle over Prisma'],
  },
};

Config vs customizespec.config.js holds advisory preferences Claude honors. Persona and integrations are machine-managed state - change those with spec-init customize, not in the config file.

Swap the persona

Persona drives CLAUDE.md verbosity and the "Why this step?" annotations. Swap safely - customize re-derives CLAUDE.md’s managed region from the shipped template and updates spec.config.js.

# 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 is applied by file class: CLI-owned files are replaced, your data files are preserved untouched, and CLAUDE.md has only its throughspec:managed regions refreshed - never a silent overwrite of your work.

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 spec.config.js. Run it after any manual edit to CLAUDE.md.

spec-init doctor
# ✓ CLAUDE.md present
# ✓ template-version 1.2.0
# ✓ spec.config.js valid