cc-dev-template 0.1.44 → 0.1.45

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cc-dev-template",
-  "version": "0.1.44",
+  "version": "0.1.45",
   "description": "Structured AI-assisted development framework for Claude Code",
   "bin": {
     "cc-dev-template": "./bin/install.js"

package/src/skills/claude-md/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: claude-md
+description: This skill should be used when working with CLAUDE.md files. Activate when the user asks to "audit CLAUDE.md", "create a CLAUDE.md", "update the CLAUDE.md", "clean up CLAUDE.md files", or "check CLAUDE.md best practices". Also activate proactively whenever about to create or modify any CLAUDE.md file - the skill contains required principles for how these files should be written.
+---
+
+# CLAUDE.md Management
+
+Base directory for this skill: ~/.claude/skills/claude-md
+
+## When This Activates
+
+- User asks to audit, create, update, or clean up CLAUDE.md files
+- You are about to create or modify any CLAUDE.md file
+
+**If you're about to touch a CLAUDE.md file, read this skill first.**
+
+## What To Do
+
+Determine the task:
+
+| Task | Action |
+|------|--------|
+| **Creating** a new CLAUDE.md | Read `references/create.md` |
+| **Modifying** an existing CLAUDE.md | Read `references/principles.md`, then edit |
+| **Auditing** a project's CLAUDE.md files | Read `references/audit.md` |
+
+## Core Principle
+
+CLAUDE.md files are **orientation prompts**. They answer: "Where am I? What matters here? What should I know that I can't read from the code?"
+
+The test: **Would Claude know where it is and what matters?**
+
+## Quick Reference
+
+**Belongs in CLAUDE.md:**
+- Why this folder/repo exists
+- Current focus (what matters NOW)
+- Where to find things (progressive disclosure)
+- Tribal knowledge, gotchas, non-obvious learnings
+- Project conventions not obvious from code
+
+**Does NOT belong:**
+- Content duplicated from parent CLAUDE.md (hierarchy is automatic)
+- Step-by-step workflows (put in docs or skills)
+- Detailed examples (trust the model)
+- Operational runbooks
+- Anything over ~100 lines (suspect)
+
+## Hierarchy Rule
+
+Claude automatically reads CLAUDE.md files up through the directory tree. A child file inherits everything from its parents.
+
+**Never duplicate parent content in child files.** Each file should only contain what's specific to that folder.
+
+For full principles, read `references/principles.md`.

package/src/skills/claude-md/references/audit.md

@@ -0,0 +1,115 @@
+# Auditing CLAUDE.md Files
+
+## Process
+
+1. **Discover** - Find all CLAUDE.md files in the project
+2. **Map hierarchy** - Understand parent-child relationships
+3. **Check each file** - Against principles
+4. **Fix issues** - Automatically apply best practices
+
+## Step 1: Discover
+
+Find all CLAUDE.md files:
+
+```bash
+find . -name "CLAUDE.md" -type f | head -20
+```
+
+Or use Glob:
+```
+**/CLAUDE.md
+```
+
+## Step 2: Map Hierarchy
+
+For each file, identify:
+- Its parent CLAUDE.md files (walking up the tree)
+- Its child CLAUDE.md files (in subdirectories)
+
+This matters because content flows down. Children inherit from parents.
+
+## Step 3: Check Each File
+
+Read each CLAUDE.md and check for these issues:
+
+### Length Issues
+| Check | Issue | Fix |
+|-------|-------|-----|
+| Over 100 lines | Probably bloated | Extract workflows to docs, remove duplication |
+| Over 150 lines | Definitely bloated | Aggressive pruning needed |
+
+### Content Issues
+| Check | Issue | Fix |
+|-------|-------|-----|
+| Step-by-step workflows | Doesn't belong | Move to docs/ or skills/, leave pointer |
+| Detailed examples | Over-explaining | Remove, trust the model |
+| Credentials/passwords | Security + bloat | Move to dedicated docs |
+| Duplicate of parent | Redundant | Remove entirely |
+
+### Structure Issues
+| Check | Issue | Fix |
+|-------|-------|-----|
+| No clear purpose statement | Disorienting | Add one-line description at top |
+| Missing "Current Focus" | For active projects | Add if this is active work |
+| Walls of text | Hard to scan | Break into sections, use bullets |
+
+### Hierarchy Issues
+| Check | Issue | Fix |
+|-------|-------|-----|
+| Child repeats parent content | Duplication | Remove from child |
+| Child has general project info | Wrong level | Move to root CLAUDE.md |
+| Deep file (3+ levels) exists | Probably unnecessary | Consider removing |
+
+## Step 4: Fix Issues
+
+For each issue found:
+
+1. **Read the file** (required before editing)
+2. **Apply the fix** using Edit tool
+3. **Move extracted content** to appropriate location (docs/, etc.)
+4. **Verify** the result
+
+### Common Fixes
+
+**Extracting a workflow:**
+1. Create `docs/workflows/[topic].md` with the detailed content
+2. Replace in CLAUDE.md with: "See `docs/workflows/[topic].md` for [description]"
+
+**Removing duplication:**
+1. Check parent file has the content
+2. Delete the duplicated section from child
+3. Optionally add: "Inherits [topic] from parent CLAUDE.md"
+
+**Pruning over-explanation:**
+1. Identify the core point
+2. Reduce to 1-2 lines that trust the model
+3. Remove examples, edge cases, detailed instructions
+
+## Audit Report
+
+After checking all files, summarize:
+
+```
+CLAUDE.md Audit Summary
+=======================
+Files checked: X
+Issues found: Y
+Issues fixed: Z
+
+Changes made:
+- [file]: [what was fixed]
+- [file]: [what was fixed]
+
+Remaining concerns:
+- [any issues that need human decision]
+```
+
+## Red Flags
+
+These indicate a CLAUDE.md that needs significant rework:
+
+- **200+ lines** - Needs major pruning
+- **Code blocks with >10 lines** - Workflows belong in docs
+- **Tables with >5 rows** - Probably too detailed
+- **Multiple "how to" sections** - Wrong content type
+- **Same content in parent and child** - Hierarchy violation

package/src/skills/claude-md/references/create.md

@@ -0,0 +1,72 @@
+# Creating a CLAUDE.md
+
+## Before Writing
+
+1. **Check the hierarchy** - Find all parent CLAUDE.md files up to the root
+2. **Read them** - Understand what's already covered
+3. **Identify the gap** - What does this folder need that parents don't provide?
+
+If the parent files already cover everything, you probably don't need a new CLAUDE.md.
+
+## Structure Template
+
+Use this as a starting point, not a rigid template. Include only sections that add value.
+
+```markdown
+# [Folder/Project Name]
+
+[One-line description of what this is and why it exists]
+
+## Current Focus
+
+[What's actively being worked on. What matters NOW.]
+
+## [Key Section]
+
+[Whatever is most important for this specific folder - could be dev commands, structure, rules, etc.]
+
+## Finding Information
+
+[Where to look for docs, workflows, detailed guides - progressive disclosure]
+
+## Gotchas
+
+[Non-obvious things that would save pain if known upfront]
+```
+
+## Guidelines
+
+### Keep It Short
+Aim for 40-80 lines. If you're going longer, you're probably including content that belongs elsewhere.
+
+### Lead with Purpose
+The first lines should orient Claude immediately. What is this? Why does it exist?
+
+### Current Focus Section
+Include this for active projects. It answers "what matters NOW?" and helps Claude prioritize.
+
+### Be Specific to This Folder
+Everything in this file should be specific to this directory. General project info belongs in the root CLAUDE.md.
+
+### Progressive Disclosure
+Point to docs, don't inline them:
+- Good: "See `docs/systems/M5_CLOUD.md` for server access"
+- Bad: [50 lines of SSH commands and credentials]
+
+## What NOT to Include
+
+- Content from parent CLAUDE.md files
+- Step-by-step workflows (put in docs/)
+- Detailed examples (trust the model)
+- Frequently changing content
+- Anything Claude could infer from the code
+
+## After Writing
+
+Verify:
+1. Under 100 lines?
+2. No duplication with parent files?
+3. Would Claude know where it is and what matters?
+4. Written as orientation, not documentation?
+
+If all yes, you're done.

package/src/skills/claude-md/references/principles.md

@@ -0,0 +1,132 @@
+# CLAUDE.md Principles
+
+## The Mental Model
+
+CLAUDE.md files are prompts for orienting Claude in a codebase. They're read automatically when Claude works in a directory.
+
+**Think of it as a briefing for a senior colleague joining the project** - not a manual for a junior who needs hand-holding.
+
+## The Test
+
+After reading a CLAUDE.md, would Claude know:
+1. Where it is (what is this folder/repo?)
+2. What matters NOW (current focus, active work)
+3. Where to find things (progressive disclosure to docs)
+4. What gotchas exist (tribal knowledge)
+
+If yes, the file is doing its job.
+
+## What Belongs
+
+### Purpose and Context
+- What this folder/repo is and why it exists
+- The mental model for how things fit together
+- Current focus - what's actively being worked on
+
+### Progressive Disclosure
+- Pointers to documentation ("See docs/INDEX.md for...")
+- Key reference docs listed by name
+- Where workflows and detailed guides live
+
+### Tribal Knowledge
+- Gotchas discovered during sessions
+- Non-obvious conventions
+- Things that would save pain if known upfront
+- "We use X instead of Y" (without spelling out examples)
+
+### Quick Reference (sparingly)
+- Dev commands if truly common (one-liners only)
+- Key URLs or entry points
+- Simple folder structure if it aids orientation
+
+## What Does NOT Belong
+
+### Duplicated Content
+Claude reads CLAUDE.md files up through the hierarchy automatically. If a parent file says "We use TypeScript", the child file should NOT repeat this.
+
+**Rule:** Before adding something, check if a parent already covers it.
+
+### Detailed Workflows
+Step-by-step processes belong in:
+- `docs/` folder
+- Skills (`.claude/skills/`)
+- Dedicated workflow files
+
+CLAUDE.md points to these, doesn't contain them.
+
+### Micromanagement
+Trust the model. If you say "We use Base UI instead of Radix", Claude understands the implications. Don't add:
+- Lists of every Radix component and its Base UI equivalent
+- Example code for each case
+- Exhaustive edge cases
+
+### Operational Runbooks
+SSH commands, database credentials, deployment scripts - these belong in dedicated docs, not CLAUDE.md.
+
+### Frequently Changing Content
+CLAUDE.md should be stable. If content changes often, it belongs elsewhere (like CURRENT_WORK.md or a status doc).
+
+## Length Guideline
+
+No hard limit, but **over 100 lines is suspect**.
+
+A good CLAUDE.md is typically 40-80 lines. If it's longer, ask:
+- Is there duplication with parent files?
+- Are there workflows that should be extracted?
+- Am I explaining things Claude already knows?
+
+## Writing Style
+
+CLAUDE.md files are prompts. Apply prompting best practices:
+
+### Explain WHY, Not Just WHAT
+Bad: "Run `npm run dev` to start the server"
+Good: "Dev server runs on :5173. Hot reload handles code changes - no restart needed."
+
+### Positive Framing
+Bad: "Don't put workflows in CLAUDE.md"
+Good: "Workflows belong in docs/ or skills/"
+
+### Be Direct
+Bad: "You might want to check the docs folder"
+Good: "Start at docs/INDEX.md for all documentation"
+
+### Trust Intelligence
+Bad: Listing every ShadCN component and how to use it
+Good: "Use ShadCN for all UI. Discuss before building custom components."
+
+## Hierarchy Examples
+
+**Root CLAUDE.md** (project level):
+- What the project is
+- Overall structure
+- Where documentation lives
+- External systems overview
+
+**Subdirectory CLAUDE.md** (e.g., `roost/CLAUDE.md`):
+- What this specific folder is
+- Rules specific to this codebase
+- Dev commands for this folder
+- Does NOT repeat project-level context
+
+**Deep subdirectory** (e.g., `src/components/CLAUDE.md`):
+- Only if there's something specific to know
+- Usually unnecessary - parent files cover it
+- If created, extremely focused (20-30 lines max)
+
+## Capturing Gotchas
+
+When a session reveals something painful:
+
+1. **Identify the learning** - What would have saved time if known upfront?
+2. **Find the right file** - Which CLAUDE.md is this specific to?
+3. **Add concisely** - One or two lines, not a full explanation
+4. **Trust the model** - State the gotcha, don't over-explain
+
+Example:
+```markdown
+## Gotchas
+
+- qrServer tracks `development` branch, not master
+- Convex queries can't be called from other queries - use actions for composition
+```