Epic: Cohesive Claude configuration design — review, consolidate, and restructure CLAUDE.md files, reference docs, and skills

[mdproctor]

Background

The Claude configuration system has grown organically across multiple layers:

• Global ~/.claude/ config files (engagement.md, working-style.md, document-boundaries.md, design-implementation.md)
• Project-level CLAUDE.md files (one per casehubio repo, symlinked from workspace)
• PLATFORM.md and docs/conventions/ in casehub-parent (read at session start)
• Installed skills in ~/.claude/skills/ (sourced from mdproctor/cc-praxis)

Each layer has accumulated guidance independently. A systematic audit (2026-05-08) found no conflicts but significant overlap, duplication, and structural problems. New additions have been made without a coherent design. The result is a system where important guidance gets skipped, forgotten mid-session, or duplicated across four places.

What the audit found

Duplications:

• Bug fix workflow ("write failing test first") appears in java-dev, python-dev, ts-dev, and code-review-principles — nearly word for word
• Test taxonomy (unit/integration/E2E) restated in each language skill despite testing-principles being the authoritative source
• IntelliJ three-tier strategy detailed in java-dev but silent in python-dev and ts-dev; only vaguely stated in design-implementation.md

Structural problems:

• java-dev is monolithic (~420 lines). IntelliJ guidance is at line 386 — after safety, testing, documentation, code quality. By the time Claude is working, it has faded. Moving it up is zero-sum: other important things move down.
• Skills are invoked once at session start; their guidance fades as context grows. Confirmed by repeated user experience of Claude forgetting IntelliJ usage, TDD, and code review mid-session.
• No single document shows the full skill invocation chain (dev → review → commit → design update).

Gaps:

• python-dev and ts-dev have no IntelliJ guidance
• No automation for non-Java documentation updates
• superpowers:brainstorming is nowhere in any dev skill as a prerequisite
• No per-project "living docs" list for drift checking

Core tension:
Adding new guidance to long documents makes the problem worse. Existing overlapping guidance must be removed or consolidated before new guidance is added. A new item added without removing a duplicate increases noise, not signal.

Approaches to evaluate

Option A — Decompose monolithic skills
Split java-dev, python-dev, ts-dev into focused sub-skills (tooling, testing, quality). Each is short enough that nothing gets buried.

• Pro: nothing deprioritised within a skill; invocation chain becomes explicit
• Con: more skills to manage; prerequisite chains need updating; invocation more complex

Option B — Preamble pattern
Each language skill gets a 10-line preamble covering non-negotiables (IntelliJ check, brainstorming, TDD). Rest of skill is reference.

• Pro: minimal restructuring; non-negotiables always at top
• Con: long document still fades mid-session

Option C — Strict layer discipline only
Remove duplicates, put each thing in exactly one place, add cross-references. No restructuring.

• Pro: minimal change; works with existing shape
• Con: doesn't solve mid-session fading; long monolithic skills remain

Option D — Prompt snippet as primary mechanism
Accept that long-session fading is unsolvable structurally. Design a short, opinionated prompt snippet covering non-negotiables. Skills and CLAUDE.md are reference material, not enforcement.

• Pro: honest about system limits; prompt is the only mechanism that doesn't fade
• Con: requires user to paste every session; not self-maintaining

Option E — Hybrid
Strict layer discipline (remove duplicates) + preamble pattern for skills + prompt snippet for session-critical items. Each mechanism used for what it's actually reliable at.

Layer architecture to define

Layer	Purpose	Should NOT contain
Global CLAUDE.md	Behavioral norms — how Claude engages	Project-specific facts, workflow procedures
Skill files	Comprehensive guidance for a specific task type	Repetition of other skills' content
Project CLAUDE.md	Project-specific facts and invocation hooks	Generic norms already in global config
PLATFORM.md	Platform architecture and coherence protocol	Workflow procedures, skill invocations
Prompt snippet	Session-critical non-negotiables that must not fade	Everything that can live elsewhere

Work sequence

1. Produce canonical topic → authoritative location map
2. Agree on layer architecture and restructuring approach
3. Remove duplicates and consolidate to single authoritative sources
4. Add missing guidance (IntelliJ for Python/TS, brainstorming prerequisite, living docs lists)
5. Create cc-praxis issues for any skill restructuring

Acceptance criteria

• Canonical topic → location map produced
• Each configuration layer has a clear stated purpose and boundary
• No topic in more than one authoritative location (cross-references allowed)
• java-dev, python-dev, ts-dev have consistent IntelliJ and testing guidance
• superpowers:brainstorming documented as prerequisite for design work
• Per-project living docs list in each project CLAUDE.md
• Short prompt snippet exists for session-critical non-negotiables
• cc-praxis issues created for any skill restructuring decisions

[mdproctor]

Phase 1 complete — low-hanging fruit done (2026-05-08)

What was done

PLATFORM.md (restored and expanded — had been accidentally emptied again):

• Prominent never-dogma language added to Protocol preamble
• New Development Session Protocol section: brainstorm → TDD → review sequence
• New IntelliJ MCP Tool Guide: full capability catalogue for both MCPs (mcp__intellij-index and mcp__intellij), operation→tool table, decision rule
• Updated conventions/ → protocols/ throughout
• Local file paths for all deep-dive references (with GitHub fallback note)

~/.claude/design-implementation.md (global, applies to all projects):

• Tooling Preference section expanded from vague principle to specific operation→tool table
• Names exact tools for rename, move, find-references, diagnostics, delete
• Added: "stop and inform user if MCP unavailable — do not silently fall back"

All casehubio project CLAUDE.md files (claudony, connectors, devtown, engine, ledger, parent, qhorus, work, aml):

• Added ## Development Workflow section with 3-line skill invocation hooks
• Added project-specific living docs list for drift checking

cc-praxis skills (committed and installed):

• java-dev: expanded intellij-index table with full capability list (6 missing tools added); added mcp__intellij table; clarified fallback behaviour
• python-dev: added ## Refactoring — IntelliJ First section (was missing entirely)
• ts-dev: same as python-dev
• Linked to: Improve IntelliJ guidance across java-dev, python-dev, ts-dev — consistency and completeness mdproctor/cc-praxis#61

What remains (restructuring phase)

Per the issue body — these are NOT done and require separate design decisions:

• Decompose monolithic skills vs preamble pattern vs strict layer discipline
• Move IntelliJ section from line ~386 to earlier in java-dev (zero-sum problem — needs restructuring decision first)
• Remove bug-fix workflow duplication across java-dev, python-dev, ts-dev, code-review-principles
• Add python-dev and ts-dev documentation update automation equivalent to java-update-design
• Produce canonical topic → authoritative location map
• Define formal layer architecture for what belongs where