update

name	update
description	Re-analyze a repo and update its existing .claude/ configuration. Detects stack changes, new dependencies, and config drift without overwriting customizations. Use when the codebase has evolved since initial /claude-init.
allowed-tools	Read, Write, Edit, Bash, Glob, Grep, Agent

Update: Refresh AI-Native Config

Re-analyze the codebase and update the existing .claude/ configuration to match the current state.

Process

Step 1: Snapshot Current Config

Read and fingerprint every existing config file:

• CLAUDE.md — extract sections, note any <!-- custom --> or <!-- generated --> markers
• ARCHITECTURE.md — check if it exists and capture its Directory Structure section for drift comparison
• agents/ — list all agents and their model/tool config
• skills/ — list all skills and their paths: scopes (not just rules — skills can be path-scoped too)
• rules/ — list all rules and their paths: scopes
• settings.json — read hooks, permissions, and any outputStyle field
• output-styles/ — list any custom output styles (generated tdd.md, user-added ones)
• settings.local.json.example — check it exists so new contributors can bootstrap personal overrides

Step 2: Re-Analyze the Codebase

Run the same analysis as /claude-init (parallel subagents):

• Stack detection (languages, framework, package manager, monorepo)
• Architecture (DB, auth, API, state management)
• Testing & CI (test framework, runner, CI/CD)
• Conventions (commit style, linting, directory structure)

Step 2.5: Template Sync (catch stale generated config)

Codebase drift is not the only reason config goes stale — the templates themselves improve over time, and a project generated by an older claude-init keeps the old (sometimes buggy) output. /update must close that gap, because nothing auto-propagates: generated .claude/ files are static copies with no live link back to the templates.

Resolve the current templates the same way /claude-init does — first match wins:

1. ${CLAUDE_SKILL_DIR}/../../../templates/ (running from a cloned repo)
2. ~/.claude/claude-init-templates/ (global install)

If neither exists, skip this step (note it in the report so the user knows template-sync was unavailable) and continue with the codebase-drift diff.

Scan the project's generated config for known-stale patterns. These are fixes that landed in the templates after early projects were generated — flag each one found:

Stale pattern	Where	Fix
"decision": "allow" / "decision": "block" in a PreToolUse hook	.claude/settings.json	PreToolUse ignores this form. Rewrite to hookSpecificOutput.permissionDecision (deny + permissionDecisionReason; delete the else echo allow branch — silent exit 0 already allows).
Skill description: with no when-to-use trigger (Use when…, Use before…, Auto-triggered…)	.claude/skills/*/SKILL.md	Add a trigger phrase so the skill fires reliably.
Skill description: written in first/second person ("I …", "You …")	.claude/skills/*/SKILL.md	Rewrite in third person.
SKILL.md body over 500 lines	.claude/skills/*/SKILL.md	Split long examples/scripts into sibling reference files.
Missing settings.local.json.example while settings.json exists	.claude/	Generate the example so contributors can bootstrap personal overrides.

This list grows as templates evolve — treat it as "known fixes since generation", not an exhaustive lint. For a fuller config audit, point the user at /doctor.

Fold whatever you find here into the same proposal you present in Step 4, tagged (template sync) so the user can tell template fixes apart from codebase-drift updates. Apply only on approval (Step 5), preserving <!-- custom --> blocks exactly as for any other change.

Step 3: Diff

Compare the re-analysis against the current config. Identify:

New things to add:

• New framework/dependency detected → update CLAUDE.md architecture section
• New test framework → update QA agent and test skill
• New directories → add path-scoped rules
• New CI workflow → update commands section
• Missing ARCHITECTURE.md → generate one (follow Step 1.75 from /claude-init)

Stale things to update:

• Commands that no longer exist (e.g., npm test changed to vitest)
• Agent references to removed patterns
• Rules or skills scoped to paths that no longer exist (paths: globs match zero files)
• ARCHITECTURE.md sections that no longer match the codebase (new modules, changed data flow, removed dependencies)

ARCHITECTURE.md drift check (always run):

• Compare the Directory Structure section against the actual top-level directories (ls -d */)
• Compare the Entry Points section against files that actually exist
• Compare the External Dependencies section against package.json / Cargo.toml / requirements.txt
• If ANY of these drift more than ~15%, regenerate the ARCHITECTURE.md using the Step 1.75 template from /claude-init (present the new version as a diff against the old one; preserve <!-- custom --> blocks)
• Minor drift (one or two new/gone directories): propose Edit-level patches, not full regeneration

Things to preserve (never touch):

• Any content between <!-- custom --> markers
• Hand-written sections not matching generated patterns
• Custom agents, skills, or rules the user added manually
• Project-specific values in rules — if a rule mentions specific thresholds, library settings, or configuration values (e.g., "staleTime is 5 minutes", "avoid importing entire libraries"), keep them. These are real project details that Claude can't infer. You may restructure or add, but never drop specific values.

Step 4: Present Changes

Show a diff-style summary:

## Proposed Updates

### CLAUDE.md
+ Add: `bun test` (detected bun migration from npm)
- Remove: `npm test` (no longer in package.json)
~ Update: Architecture section (Drizzle detected, was Prisma)

### agents/developer.md
~ Update: Framework references (SvelteKit detected, was Next.js)

### rules/
+ Add: rules/api.md (new API routes detected in src/api/)

### settings.json (template sync)
~ Fix: PreToolUse hooks use legacy `{"decision":...}` form → `hookSpecificOutput.permissionDecision`

### No changes needed:
- agents/architect.md (still current)
- skills/plan/ (still current)

Wait for user approval before applying any changes.

Step 5: Apply

Apply approved changes. For each modified file:

• Use Edit (not Write) to preserve surrounding content
• Add <!-- generated by claude-init --> markers around generated sections
• Leave <!-- custom --> sections untouched

Rules

• NEVER overwrite without showing the diff first
• NEVER touch files the user added manually (not generated by /claude-init)
• Preserve all custom content — only update generated sections
• If in doubt, add new content rather than modifying existing content
• Template sync (Step 2.5) fixes stale GENERATED config only — never "upgrade" a file the user hand-wrote or customized
• Tag template-sync changes (template sync) in the proposal so the user can distinguish them from codebase-drift updates