cc-dev-template 0.1.51 → 0.1.53

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cc-dev-template",
-  "version": "0.1.51",
+  "version": "0.1.53",
   "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/creating-agent-skills/references/create-step-2-design.md

@@ -19,6 +19,43 @@ There are two types. Pick one:
 
 **How to decide:** If the skill describes a process with distinct sequential phases, it is procedural. If it captures principles or knowledge applied whenever relevant, it is informational.
 
+## Determine Invocation Mode
+
+Ask the user: "Should Claude be able to auto-activate this skill, or is it user-invoked only (via `/skill-name`)?"
+
+**User-invoked only** — The user explicitly triggers with `/skill-name`. Use for:
+- Actions with side effects (deploy, commit, publish)
+- Workflows the user wants full control over
+- Tasks that should never run unexpectedly
+
+Configuration: `disable-model-invocation: true` + minimal description (just states what it does, no trigger phrases needed)
+
+**Agent-invocable** — Claude detects when to activate based on conversation. Use for:
+- Knowledge and guidance skills
+- Workflows triggered by natural language patterns
+- Skills where "just knowing when" is valuable
+
+Configuration: No special flag + rich description with trigger phrases
+
+## Determine Execution Context
+
+Ask the user: "Should this skill run inline (in the main conversation) or as a sub-agent (isolated context)?"
+
+**Inline** — Skill runs in the main conversation. The agent sees all prior context and can continue the conversation naturally after the skill completes. Use for:
+- Most skills
+- Skills that need conversation history
+- Skills where follow-up interaction is expected
+
+Configuration: No special setting needed
+
+**Sub-agent (fork)** — Skill runs in an isolated context. The sub-agent cannot see prior conversation and returns a single result. Use for:
+- Heavy research or exploration tasks
+- Parallel execution of independent work
+- Skills that should not pollute the main context
+- Long-running tasks that benefit from isolation
+
+Configuration: `context: fork` (optionally add `agent: Explore` or `agent: Plan` for specialized behavior)
+
 ## Design the Frontmatter
 
 Every skill has YAML frontmatter. Required and optional fields:
@@ -54,6 +91,10 @@ Every skill has YAML frontmatter. Required and optional fields:
 
 ## Craft the Description
 
+The description's purpose depends on the invocation mode:
+
+### For Agent-Invocable Skills
+
 The description determines when Claude activates the skill. This is the most important piece of metadata.
 
 Collect 5-10 trigger phrases from the user: "When you need this skill, what would you say to Claude?"
@@ -66,7 +107,14 @@ Combine into a description that:
 
 **Key insight:** If the description explains too much about WHAT the skill does, Claude believes it already knows enough and will not activate. Keep it about WHEN.
 
-**Context budget note:** Skill descriptions load at startup and share a character budget (default 15,000 chars across all skills). Keep descriptions tight — they cost tokens every session.
+### For User-Invoked Only Skills
+
+The description just needs to tell the user what the skill does. Keep it minimal:
+- One sentence stating the action
+- No trigger phrases needed (Claude will not use them)
+- Example: "Deploy the application to production"
+
+**Context budget note:** Skill descriptions load at startup and share a character budget (default 15,000 chars across all skills). Keep descriptions tight — they cost tokens every session. User-invoked skills with `disable-model-invocation: true` should have especially minimal descriptions since Claude does not need activation cues.
 
 ## Plan the File Layout
 
@@ -103,6 +151,8 @@ List out the steps. Each step becomes one markdown file in `references/`. For ea
 Present the design:
 - Name
 - Type (informational or procedural)
+- Invocation mode (agent-invocable or user-invoked only)
+- Execution context (inline or sub-agent)
 - Frontmatter configuration
 - Description text
 - File layout
@@ -110,4 +160,9 @@ Present the design:
 
 Ask: "Does this design look right?"
 
-Read `references/create-step-3-write.md` when the design is confirmed.
+## Next Step
+
+| Context | Action |
+|---------|--------|
+| Creating a new skill | Read `references/create-step-3-write.md` |
+| Fixing an existing skill (came from fix-step-1-diagnose) | Read `references/fix-step-2-apply.md` to apply the structural changes |

package/src/skills/creating-agent-skills/references/fix-step-1-diagnose.md

@@ -80,4 +80,31 @@ Present the diagnosis to the user:
 - What principle it violates
 - What the fix would look like
 
-Read `references/fix-step-2-apply.md` when diagnosis is complete and findings are summarized.
+## Classify the Fix Type
+
+Based on your diagnosis, determine which type of fix is needed:
+
+**Surface fixes** — wording, style, dead ends, missing chain links, description tweaks:
+- Fixing second person to imperative
+- Adding positive framing
+- Removing meta-descriptions
+- Fixing broken file references
+- Small description improvements
+
+**Structural changes** — anything that changes the skill's architecture:
+- Converting between informational and procedural types
+- Adding or removing step files
+- Adding new workflow branches
+- Redesigning the file layout
+- Adding scripts/ or templates/ directories
+- Significantly rewriting the description and trigger phrases
+- Changing frontmatter configuration (allowed-tools, context, agent, etc.)
+
+Tell the user which type of fix is needed.
+
+## Next Step
+
+| Fix Type | Action |
+|----------|--------|
+| Surface fixes only | Read `references/fix-step-2-apply.md` |
+| Structural changes needed | Read `references/create-step-2-design.md` first to design the new structure, then read `references/fix-step-2-apply.md` to apply |

package/src/skills/creating-agent-skills/references/fix-step-2-apply.md

@@ -2,6 +2,17 @@
 
 Fix the issues identified in diagnosis. Plan the changes, confirm with the user, then apply.
 
+## If Coming From Design Step
+
+If you just read `create-step-2-design.md` for structural changes, you now have:
+- The skill type decision (informational vs procedural)
+- The frontmatter configuration
+- The crafted description with trigger phrases
+- The file layout plan
+- For procedural: the step breakdown
+
+Use that design as the blueprint for your changes. The writing principles below still apply to all content you write.
+
 ## Plan Changes First
 
 Before editing, state:
@@ -87,4 +98,6 @@ Does this justify its token cost? If Claude already knows it — remove it. If i
 
 Make all planned modifications now.
 
+For structural changes that involve writing new files (new step files, new SKILL.md sections, new scripts), reference `references/create-step-3-write.md` for the complete writing guidance — it covers size targets, step file structure, MCP tool references, and anti-patterns in more depth than the principles above.
+
 Read `references/fix-step-3-validate.md` when all fixes are applied.

package/src/skills/creating-agent-skills/references/fix-step-3-validate.md

@@ -1,5 +1,7 @@
 # Step 3: Validate and Test
 
+For structural changes, use the full review checklist from `references/create-step-4-review.md` — it covers additional criteria like size targets, frontmatter validation, and description quality that matter when you've changed the skill's architecture.
+
 ## Public Knowledge Audit
 
 Go through every changed file. Find each code block, CLI command, API call, and implementation detail.

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 → step-3-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-4-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-6-finalize.md}

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