cc-dev-template 0.1.51 → 0.1.52

package/package.json

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

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

@@ -1,6 +1,6 @@
 ---
 name: claude-md
-description: Manages CLAUDE.md files - the orientation prompts that help Claude understand codebases. Activates for auditing, creating, updating, or cleaning up CLAUDE.md files. Also activates before modifying any CLAUDE.md file to ensure best practices are followed.
+description: Manages CLAUDE.md files in a project. Activates when the user says "audit CLAUDE.md files", "update CLAUDE.md", "add to CLAUDE.md", or invokes /claude-md. With no arguments, audits all CLAUDE.md files. With arguments, intelligently updates the appropriate file.
 ---
 
 # CLAUDE.md Management
@@ -9,40 +9,12 @@ Base directory for this skill: ~/.claude/skills/claude-md
 
 ## What To Do
 
-Determine the task:
+Check if arguments were provided:
 
-| 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` |
+| Condition | Action |
+|-----------|--------|
+| No arguments | Read `references/audit.md` |
+| Arguments provided (add, update, modify request) | Read `references/modify.md` |
+| Explicitly asked to create a new CLAUDE.md | Read `references/create.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`.
+For principles reference: `references/principles.md`

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

@@ -1,84 +1,52 @@
-# Auditing CLAUDE.md Files
+# Audit CLAUDE.md Files
 
-## Process
+Perform a full audit of all CLAUDE.md files in this project. Fix issues automatically.
 
-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 and Map
 
-## Step 1: Discover
+Find all CLAUDE.md files: `Glob("**/CLAUDE.md")`
 
-Find all CLAUDE.md files using Glob pattern `**/CLAUDE.md`.
+Read every file found. Build a mental map of the hierarchy — which files are parents, which are children. Content flows down: children inherit from parents.
 
-## Step 2: Map Hierarchy
+## Step 2: Check Each File
 
-For each file, identify:
-- Its parent CLAUDE.md files (walking up the tree)
-- Its child CLAUDE.md files (in subdirectories)
+Evaluate each file against these criteria:
 
-This matters because content flows down. Children inherit from parents.
+**Length**
+- Over 100 lines → bloated, needs pruning
+- Over 150 lines → severely bloated
 
-## Step 3: Check Each File
+**Content that doesn't belong**
+- Step-by-step workflows → move to docs/ or skills/
+- Detailed examples → remove, trust the model
+- Credentials/passwords → move to dedicated docs
+- Content duplicated from parent → remove entirely
 
-Read each CLAUDE.md and check for these issues:
+**Structure**
+- Missing purpose statement at top → add one-line description
+- Walls of text → break into sections, use bullets
 
-### Length Issues
-| Check | Issue | Fix |
-|-------|-------|-----|
-| Over 100 lines | Probably bloated | Extract workflows to docs, remove duplication |
-| Over 150 lines | Definitely bloated | Aggressive pruning needed |
+**Hierarchy violations**
+- Child repeats parent content → remove from child
+- Child has general project info → move to root CLAUDE.md
+- Deep file (3+ levels) with no unique content → consider removing
 
-### 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 |
+## Step 3: Fix Issues
 
-### 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 |
+For each issue:
+1. Read the file
+2. Apply the fix using Edit
+3. Move extracted content to appropriate location if needed
 
-### 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 |
+**Extracting workflows:** Create `docs/workflows/[topic].md`, replace inline content with pointer.
 
-## Step 4: Fix Issues
+**Removing duplication:** Verify parent has content, delete from child.
 
-For each issue found:
+**Pruning over-explanation:** Reduce to 1-2 lines that trust the model.
 
-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
+## Step 4: Report
 
-### 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:
+After all fixes, summarize:
 
 ```
 CLAUDE.md Audit Summary
@@ -89,18 +57,7 @@ Issues fixed: Z
 
 Changes made:
 - [file]: [what was fixed]
-- [file]: [what was fixed]
 
 Remaining concerns:
-- [any issues that need human decision]
+- [any issues needing 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/modify.md

@@ -0,0 +1,52 @@
+# Modify CLAUDE.md
+
+The user provided a request to add, update, or modify something in the project's CLAUDE.md files. Determine the appropriate file and make the change.
+
+## Step 1: Understand the Request
+
+Parse what the user wants:
+- What content to add or change?
+- Is it project-wide or specific to a folder/component?
+- Is it a gotcha, convention, current focus, or structural info?
+
+## Step 2: Discover Existing Files
+
+Find all CLAUDE.md files: `Glob("**/CLAUDE.md")`
+
+Read each file to understand:
+- What scope each file covers
+- The hierarchy (root → subdirectories)
+- What content already exists
+
+## Step 3: Determine the Right File
+
+Match the request to the appropriate level:
+
+| Request Type | Appropriate File |
+|--------------|------------------|
+| Project-wide convention | Root CLAUDE.md |
+| Folder-specific rule | That folder's CLAUDE.md (create if needed) |
+| Component gotcha | Nearest parent CLAUDE.md covering that area |
+| Current focus/priority | Root CLAUDE.md (or active work area) |
+
+**Hierarchy principle:** Place content at the highest level where it applies. Child files only contain what's specific to that folder.
+
+If unsure which file is appropriate, ask the user.
+
+## Step 4: Make the Change
+
+Read the target file, then edit:
+
+- Add gotchas to a "Gotchas" section (create if missing)
+- Add conventions to relevant existing sections
+- Add current focus to "Current Focus" section
+- Keep additions concise — 1-2 lines, trust the model
+
+If the content would make the file exceed ~100 lines, consider:
+- Is this the right level? Maybe it belongs deeper.
+- Can existing content be pruned?
+- Should a workflow be extracted to docs/?
+
+## Step 5: Confirm
+
+Tell the user what was added and where. If creating a new CLAUDE.md file, explain why that location was chosen.

package/src/skills/research/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: research
+description: Deep research on unfamiliar paradigms, libraries, or patterns before implementation. Activates when the user says "research X", "how should we implement X", "best practices for X", or when spec-interview identifies research needs. Outputs to docs/research/ with YAML frontmatter.
+---
+
+# Research
+
+Conduct deep research on a topic to inform implementation decisions.
+
+## What To Do Now
+
+Identify the research topic from the user's request or the invoking skill's context.
+
+Read `references/step-1-check-existing.md` to check for existing research before conducting new research.

package/src/skills/research/references/step-1-check-existing.md

@@ -0,0 +1,25 @@
+# Step 1: Check Existing Research
+
+Before researching, check if this topic was already researched.
+
+## Search for Existing Research
+
+Look in `docs/research/` for existing research documents.
+
+Search approach:
+1. Glob for `docs/research/*.md`
+2. If files exist, read them and check YAML frontmatter for matching topics
+3. Consider semantic matches, not just exact names (e.g., "Convex real-time" matches "Convex subscriptions")
+
+## If Match Found
+
+Return the existing research to the caller:
+- State that research already exists
+- Provide the file path
+- Summarize the key findings from that document
+
+Do not re-research unless the user explicitly requests updated information.
+
+## If No Match
+
+Proceed to `references/step-2-conduct-research.md` to conduct new research.

package/src/skills/research/references/step-2-conduct-research.md

@@ -0,0 +1,63 @@
+# Step 2: Conduct Research
+
+Research the topic thoroughly and produce a reference document.
+
+## Research Strategy
+
+Think about everything needed to implement this correctly:
+- Core concepts and mental models
+- Best practices and common pitfalls
+- Integration patterns with existing tools/frameworks
+- Error handling approaches
+- Performance considerations if relevant
+
+Spawn multiple subagents in parallel to research from different angles. Each subagent focuses on one aspect. Use whatever web search tools are available.
+
+Synthesize findings into a coherent understanding. Resolve contradictions. Prioritize recent, authoritative sources.
+
+## Output Document
+
+Create `docs/research/<topic-slug>.md` (kebab-case, concise name).
+
+Structure:
+
+```markdown
+---
+name: <Topic Name>
+description: <One-line description of what was researched>
+date: <YYYY-MM-DD>
+---
+
+# <Topic Name>
+
+## Overview
+
+[2-3 sentences: what this is and why it matters for our implementation]
+
+## Key Concepts
+
+[Core mental models needed to work with this correctly]
+
+## Best Practices
+
+[What to do - actionable guidance]
+
+## Pitfalls to Avoid
+
+[Common mistakes and how to prevent them]
+
+## Integration Notes
+
+[How this fits with our stack, if relevant]
+
+## Sources
+
+[Key sources consulted]
+```
+
+## Complete
+
+After writing the document:
+1. Confirm the research is complete
+2. Summarize the key takeaways
+3. Return to the invoking context (spec-interview or user)

package/src/skills/spec-interview/references/step-2-deep-dive.md

@@ -74,4 +74,4 @@ Write to `docs/specs/<name>/spec.md` with this structure:
 
 ## When to Move On
 
-Move to `references/step-3-finalize.md` when all areas have been covered and the spec document is substantially complete.
+Move to `references/step-3-research-needs.md` when all areas have been covered and the spec document is substantially complete.

package/src/skills/spec-interview/references/step-3-research-needs.md

@@ -0,0 +1,44 @@
+# Step 3: Identify Research Needs
+
+Before finalizing, determine if implementation requires unfamiliar paradigms.
+
+## The Question
+
+For each major component in the spec, ask: **Does working code using this exact pattern already exist in this codebase?**
+
+This is not about whether Claude knows how to do something in general. It's about whether this specific project has proven, working examples of the same approach.
+
+## Evaluate Each Component
+
+Review the spec's integration points, data model, and behavior sections.
+
+For each significant implementation element:
+1. Search the codebase for existing examples of this pattern
+2. If found → this paradigm is established, no research needed
+3. If not found → this is a new paradigm requiring research
+
+Examples of "new paradigm" triggers:
+- Using a library not yet in the project
+- A UI pattern not implemented elsewhere in the app
+- An integration with an external service not previously connected
+- A data structure or flow unlike existing code
+
+## If Research Needed
+
+For each new paradigm identified:
+1. State what needs research and why (no existing example found)
+2. Ask the user if they want to proceed with research, or if they have existing knowledge to share
+3. If proceeding, invoke the `research` skill for that topic
+
+Wait for research to complete before continuing. The research output goes to `docs/research/` and informs implementation.
+
+## If No Research Needed
+
+State that all paradigms have existing examples in the codebase. Proceed to `references/step-4-finalize.md`.
+
+## When to Move On
+
+Proceed to `references/step-4-finalize.md` when:
+- All new paradigms have been researched, OR
+- User confirmed no research is needed, OR
+- All patterns have existing codebase examples

package/src/skills/spec-interview/references/{step-3-finalize.md → step-4-finalize.md}

@@ -1,4 +1,4 @@
-# Step 3: Finalize
+# Step 4: Finalize
 
 Review the spec for completeness and hand off.