CLAUDE.md Lifecycle

End-to-end management of CLAUDE.md files: scaffold from project-type templates, sync with project state (audit + fix + optimize), and edit sections interactively. Targets both project-local CLAUDE.md and global ~/.claude/CLAUDE.md.

When to Use

• User asks to create a CLAUDE.md from scratch (new project, missing file)
• User asks to sync / update / audit / fix / optimize an existing CLAUDE.md
• User asks to edit a specific section with preview and validation
• File is over the 150-line budget and needs trimming via pointer architecture
• Version/count drift detected between CLAUDE.md and project sources (plugin.json, DESCRIPTION, etc.)

When NOT to Use

The boundary with insights-apply: that skill is the rule-applier for one specific source (the /insights report → global CLAUDE.md). This skill is the editor for the full lifecycle (init/sync/edit) of any CLAUDE.md. They share the underlying sync pipeline (utils/claude_md_sync.py) but enter it from different intents.

Three Phases

Phase 1: Init (scaffold)

Create a new CLAUDE.md from a project-type template (lean, < 150 lines, pointer architecture).

Flags: --type, --force (overwrite), --dry-run, --global (target ~/.claude/CLAUDE.md)

Refusal: if file exists and --force not set, redirect to sync.

Phase 2: Sync (update + audit + fix + optimize)

Four-phase pipeline against an existing CLAUDE.md.

Anti-patterns blocked (refuse to add to CLAUDE.md):

Budget resolution order: .claude-plugin/config.json → package.json claudeMd.budget → default 150. Never store in plugin.json (strict schema rejects it).

Sections: --section status|commands|testing|all (default all).

Phase 3: Edit (interactive section editing)

Open one or more sections in an external editor with TODO hints, validate after.

iA Writer integration (default): open via AppleScript

osascript -e 'tell application "iA Writer"
    activate
    open POSIX file "/path/to/CLAUDE.md"
end tell'

Pointer Architecture

The 150-line budget is enforced by pointing out of CLAUDE.md rather than inlining detail:

## References

-> Release history: [VERSION-HISTORY.md](docs/VERSION-HISTORY.md)
-> Architecture: [ARCHITECTURE.md](docs/ARCHITECTURE.md)
-> Contributing: [CONTRIBUTING.md](CONTRIBUTING.md)
-> Command reference: [COMMANDS.md](docs/COMMANDS.md)

Claude Code follows markdown links naturally — keep CLAUDE.md as an index, not an encyclopedia.

Global vs Project Targeting

All three phases accept --global / -g:

if "--global" in args or "-g" in args:
    target = Path.home() / ".claude" / "CLAUDE.md"
else:
    target = Path.cwd() / "CLAUDE.md"

Use global for cross-project rules (workflow, git, safety); use project-local for project-specific commands and structure.

Underlying Utilities

Decision Flow

User intent ─┐
             ├─► file missing?       → Init (Phase 1)
             ├─► drift / audit needed?→ Sync (Phase 2)
             ├─► specific section?    → Edit (Phase 3)
             └─► /insights source?    → use `insights-apply` skill

Error Recovery

See Also

• insights-apply — apply /insights report suggestions to global CLAUDE.md (specific source)
• doc-classifier — decide what doc types a feature needs (sibling in skills/docs/)
• changelog-automation — release notes / CHANGELOG generation (sibling)
• /craft:check — invokes sync internally as part of pre-commit validation