clauderc 1.0.6 → 1.1.0

package/bin/cli.js

@@ -180,7 +180,8 @@ function showSuccessBanner(stats, providerNames) {
   ${c.bold}Try these commands in Claude Code:${c.reset}
 
     ${c.cyan}Ask Claude:${c.reset} "Use project-setup-wizard to configure this project"
-    ${c.cyan}Slash commands:${c.reset} /test, /lint, /verify, /pr
+    ${c.cyan}Slash commands:${c.reset} /test, /lint, /verify, /pr, /fix, /worktree
+    ${c.cyan}Skills:${c.reset} /evolve-claude-md, /explain
 `);
 
   if (providerNames && providerNames.includes('cursor')) {
@@ -218,6 +219,7 @@ function listInstalled() {
     { name: 'Agents', path: join(CLAUDE_DIR, 'agents') },
     { name: 'Skills', path: join(CLAUDE_DIR, 'skills') },
     { name: 'Commands', path: join(CLAUDE_DIR, 'commands') },
+    { name: 'Hooks', path: join(CLAUDE_DIR, 'hooks') },
     { name: 'Templates', path: join(CLAUDE_DIR, 'templates') },
   ];
 
@@ -241,8 +243,9 @@ function listInstalled() {
           console.log(`    ${c.green}●${c.reset} ${entry.name}`);
           found = true;
         }
-      } else if (entry.isFile() && entry.name.endsWith('.md')) {
-        console.log(`    ${c.green}●${c.reset} ${entry.name.replace('.md', '')}`);
+      } else if (entry.isFile() && (entry.name.endsWith('.md') || entry.name.endsWith('.json'))) {
+        const displayName = entry.name.replace(/\.(md|json)$/, '');
+        console.log(`    ${c.green}●${c.reset} ${displayName}`);
         found = true;
       } else if (entry.isDirectory()) {
         console.log(`    ${c.green}●${c.reset} ${entry.name}/`);
@@ -333,7 +336,7 @@ async function init(options = {}) {
 
   // Create base directories
   if (providerIds.includes('claude')) {
-    const dirs = ['agents', 'skills', 'commands', 'templates'];
+    const dirs = ['agents', 'skills', 'commands', 'templates', 'hooks'];
     for (const dir of dirs) {
       ensureDir(join(CLAUDE_DIR, dir));
     }
@@ -638,6 +641,7 @@ function showHelp() {
     ├── agents/         ${c.dim}# Reusable agents${c.reset}
     ├── skills/         ${c.dim}# Reusable skills${c.reset}
     ├── commands/       ${c.dim}# Default commands${c.reset}
+    ├── hooks/          ${c.dim}# Pre/post tool use hooks${c.reset}
     └── templates/      ${c.dim}# Templates for project setup${c.reset}
 
     ${c.cyan}Global (~/.cursor/rules/)${c.reset}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clauderc",
-  "version": "1.0.6",
+  "version": "1.1.0",
   "description": "Setup Claude Code with best practices - agents, skills, commands, and templates",
   "type": "module",
   "bin": {

package/src/providers/claude.js

@@ -59,9 +59,24 @@ Use Plan Mode (Shift+Tab 2x) for:
 - Architecture changes
 - Database migrations
 
+### Parallel Workflow (Worktrees)
+For parallel tasks, use git worktrees:
+- Run \`/worktree\` to set up parallel workspaces
+- Use aliases: \`za\` (feature), \`zb\` (bugfix), \`zc\` (experiment), \`z0\` (main)
+- Each worktree runs its own Claude Code session independently
+
 ### Verification
 - ALWAYS run \`${commands.verify || 'tests'}\` before committing
 - NEVER skip tests without explicit approval
+
+### Advanced Prompting
+- Grill your changes: "Is this the best approach? What are the edge cases?"
+- Ask Claude to reimplement elegantly after a working prototype
+- Use subagents for focused tasks (security review, test writing)
+
+### Self-Improvement
+- Run \`/evolve-claude-md\` after fixing bugs to capture learnings
+- Claude is good at writing rules for itself - review its suggestions
 `;
 
   content += `
@@ -324,6 +339,80 @@ Create a well-structured commit following Conventional Commits.
 4. Write subject in imperative mood
 5. Add body if change needs explanation
 6. Execute \`git commit -m "<message>"\`
+`,
+
+    worktree: `# Git Worktree Management
+
+Manage parallel workspaces using git worktrees for concurrent Claude Code sessions.
+
+## Setup Worktrees
+
+\`\`\`bash
+REPO_NAME="$(basename "$(git rev-parse --show-toplevel)")"
+WORKTREE_BASE="../\${REPO_NAME}-worktrees"
+mkdir -p "\$WORKTREE_BASE"
+
+CURRENT="$(git branch --show-current)"
+for SUFFIX in a b c; do
+  BRANCH="\${CURRENT}-wt-\${SUFFIX}"
+  TREE_PATH="\${WORKTREE_BASE}/\${SUFFIX}"
+  if [ ! -d "\$TREE_PATH" ]; then
+    git worktree add -b "\$BRANCH" "\$TREE_PATH" HEAD
+    echo "Created worktree: \$TREE_PATH (\$BRANCH)"
+  else
+    echo "Worktree exists: \$TREE_PATH"
+  fi
+done
+\`\`\`
+
+## Shell Aliases
+
+Add to your shell profile:
+
+\`\`\`bash
+alias za='cd "\$(git rev-parse --show-toplevel)/../\$(basename "\$(git rev-parse --show-toplevel)")-worktrees/a"'
+alias zb='cd "\$(git rev-parse --show-toplevel)/../\$(basename "\$(git rev-parse --show-toplevel)")-worktrees/b"'
+alias zc='cd "\$(git rev-parse --show-toplevel)/../\$(basename "\$(git rev-parse --show-toplevel)")-worktrees/c"'
+alias z0='cd "\$(git rev-parse --show-toplevel)"'
+\`\`\`
+
+## Parallel Workflow
+
+1. Main tree (z0): Primary development
+2. Worktree A (za): Feature work with Claude Code
+3. Worktree B (zb): Bug fixes with Claude Code
+4. Worktree C (zc): Experiments
+
+## Cleanup
+
+\`\`\`bash
+git worktree remove "../\${REPO_NAME}-worktrees/a"
+git worktree prune
+\`\`\`
+`,
+
+    fix: `# Autonomous Bug Fix
+
+Investigate and fix a bug from a description or issue link.
+
+## Input
+
+Accepts: bug description, GitHub issue link, or error message/stack trace.
+
+## Workflow
+
+1. **Understand** - Fetch issue details, search for related errors
+2. **Reproduce** - Confirm the bug exists with a test or manual steps
+3. **Investigate** - Trace code path, identify root cause
+4. **Fix** - Write failing test, implement minimal fix, verify
+5. **Commit** - Use \`fix(<scope>): <description>\` format
+
+## Rules
+
+- ALWAYS write a reproducing test before fixing
+- NEVER fix more than the reported issue
+- ALWAYS run \`/verify\` after the fix
+- If fix spans > 5 files, stop and plan first
 `,
   };
 
@@ -347,7 +436,7 @@ export function generateProjectFiles(config) {
     type: 'settings.json',
   });
 
-  for (const cmd of ['test', 'lint', 'verify', 'setup', 'pr', 'commit']) {
+  for (const cmd of ['test', 'lint', 'verify', 'setup', 'pr', 'commit', 'worktree', 'fix']) {
     files.push({
       path: join(claudeDir, 'commands', `${cmd}.md`),
       content: generateCommandFile(cmd, config),

package/src/providers/cursor.js

@@ -13,6 +13,8 @@ const RULE_DESCRIPTIONS = {
   setup: 'Install dependencies and setup project',
   pr: 'Create a semantic pull request',
   commit: 'Create a semantic commit',
+  worktree: 'Manage git worktrees for parallel development',
+  fix: 'Autonomous bug investigation and fixing',
 };
 
 function mdcFrontmatter({ description, globs, alwaysApply }) {
@@ -255,6 +257,65 @@ Create a well-structured commit following Conventional Commits.
 4. Write subject in imperative mood
 5. Add body if change needs explanation
 6. Execute \`git commit -m "<message>"\`
+`,
+
+    worktree: mdcFrontmatter({ description, alwaysApply: false }) +
+`# Git Worktree Management
+
+Manage parallel workspaces using git worktrees.
+
+## Setup
+\`\`\`bash
+REPO_NAME="$(basename "$(git rev-parse --show-toplevel)")"
+WORKTREE_BASE="../\${REPO_NAME}-worktrees"
+mkdir -p "\$WORKTREE_BASE"
+CURRENT="$(git branch --show-current)"
+for SUFFIX in a b c; do
+  BRANCH="\${CURRENT}-wt-\${SUFFIX}"
+  TREE_PATH="\${WORKTREE_BASE}/\${SUFFIX}"
+  if [ ! -d "\$TREE_PATH" ]; then
+    git worktree add -b "\$BRANCH" "\$TREE_PATH" HEAD
+    echo "Created worktree: \$TREE_PATH (\$BRANCH)"
+  else
+    echo "Worktree exists: \$TREE_PATH"
+  fi
+done
+\`\`\`
+
+## Aliases
+\`\`\`bash
+alias za='cd "\$(git rev-parse --show-toplevel)/../\$(basename "\$(git rev-parse --show-toplevel)")-worktrees/a"'
+alias zb='cd "\$(git rev-parse --show-toplevel)/../\$(basename "\$(git rev-parse --show-toplevel)")-worktrees/b"'
+alias zc='cd "\$(git rev-parse --show-toplevel)/../\$(basename "\$(git rev-parse --show-toplevel)")-worktrees/c"'
+alias z0='cd "\$(git rev-parse --show-toplevel)"'
+\`\`\`
+
+## Cleanup
+\`\`\`bash
+git worktree remove "../\${REPO_NAME}-worktrees/a"
+git worktree prune
+\`\`\`
+`,
+
+    fix: mdcFrontmatter({ description, alwaysApply: false }) +
+`# Autonomous Bug Fix
+
+Investigate and fix a bug from a description or issue link.
+
+## Workflow
+
+1. **Understand** - Fetch issue details, search for related errors
+2. **Reproduce** - Confirm the bug exists
+3. **Investigate** - Trace code path, identify root cause
+4. **Fix** - Write failing test, implement minimal fix, verify
+5. **Commit** - Use \`fix(<scope>): <description>\` format
+
+## Rules
+
+- ALWAYS write a reproducing test before fixing
+- NEVER fix more than the reported issue
+- Run full verification after the fix
+- If fix spans > 5 files, stop and plan first
 `,
   };
 
@@ -272,7 +333,7 @@ export function generateProjectFiles(config) {
     type: '.cursorrules',
   });
 
-  for (const name of ['test', 'lint', 'verify', 'setup', 'pr', 'commit']) {
+  for (const name of ['test', 'lint', 'verify', 'setup', 'pr', 'commit', 'worktree', 'fix']) {
     files.push({
       path: join(cursorDir, `${name}.mdc`),
       content: generateRule(name, config),

package/templates/commands/fix.md

@@ -0,0 +1,73 @@
+# Autonomous Bug Fix
+
+Investigate and fix a bug from a description or issue link. Works autonomously through investigation, root cause analysis, fix, and verification.
+
+## Input
+
+Accepts one of:
+- Bug description in natural language
+- GitHub issue link (`gh issue view <number>`)
+- Error message or stack trace
+
+## Workflow
+
+### 1. Understand the Bug
+
+```bash
+# If given an issue number, fetch details
+gh issue view <number> --json title,body,comments
+
+# Search for related error messages in codebase
+grep -r "error message" src/ --include="*.{js,ts,py,go,rs}" -l
+
+# Check recent commits that might have introduced the bug
+git log --oneline -20 --all
+```
+
+### 2. Reproduce
+
+- Identify the reproduction steps from the bug report
+- Run the relevant test or command to confirm the bug exists
+- If no test exists, note the manual reproduction steps
+
+### 3. Investigate Root Cause
+
+- Read the relevant source files identified from error traces
+- Trace the code path from entry point to error
+- Identify the exact line/logic causing the issue
+- Check git blame to understand when/why the code was written this way
+
+### 4. Implement Fix
+
+- Write a failing test that reproduces the bug
+- Implement the minimal fix
+- Run the test to verify it passes
+- Run the full test suite to check for regressions
+
+### 5. Verify
+
+```bash
+# Run full verification
+/verify
+
+# Check that the fix doesn't break anything
+git diff --stat
+```
+
+### 6. Commit
+
+```bash
+# Commit with fix type and reference the issue
+git add <specific-files>
+git commit -m "fix(<scope>): <description>
+
+Fixes #<issue-number>"
+```
+
+## Rules
+
+- ALWAYS write a test that reproduces the bug before fixing
+- NEVER fix more than the reported issue (avoid scope creep)
+- ALWAYS run full verification after the fix
+- If the fix requires changes to more than 5 files, stop and plan first
+- Reference the issue number in the commit message

package/templates/commands/worktree.md

@@ -0,0 +1,66 @@
+# Git Worktree Management
+
+Manage parallel workspaces using git worktrees for concurrent Claude Code sessions.
+
+## Setup Worktrees
+
+```bash
+# Create worktree directory structure
+REPO_NAME="$(basename "$(git rev-parse --show-toplevel)")"
+WORKTREE_BASE="../${REPO_NAME}-worktrees"
+mkdir -p "$WORKTREE_BASE"
+
+# Create worktrees (a, b, c) from current branch
+CURRENT="$(git branch --show-current)"
+for SUFFIX in a b c; do
+  BRANCH="${CURRENT}-wt-${SUFFIX}"
+  TREE_PATH="${WORKTREE_BASE}/${SUFFIX}"
+  if [ ! -d "$TREE_PATH" ]; then
+    git worktree add -b "$BRANCH" "$TREE_PATH" HEAD
+    echo "Created worktree: $TREE_PATH ($BRANCH)"
+  else
+    echo "Worktree exists: $TREE_PATH"
+  fi
+done
+```
+
+## Shell Aliases
+
+Add these to your `~/.zshrc` or `~/.bashrc`:
+
+```bash
+# Quick worktree switching
+alias za='cd "$(git rev-parse --show-toplevel)/../$(basename "$(git rev-parse --show-toplevel)")-worktrees/a"'
+alias zb='cd "$(git rev-parse --show-toplevel)/../$(basename "$(git rev-parse --show-toplevel)")-worktrees/b"'
+alias zc='cd "$(git rev-parse --show-toplevel)/../$(basename "$(git rev-parse --show-toplevel)")-worktrees/c"'
+alias z0='cd "$(git rev-parse --show-toplevel)"'  # back to main
+```
+
+## Parallel Workflow
+
+1. **Main tree (z0):** Primary development, integration
+2. **Worktree A (za):** Feature work - run `claude` here
+3. **Worktree B (zb):** Bug fixes - run `claude` here
+4. **Worktree C (zc):** Experiments/spikes - run `claude` here
+
+Each worktree runs its own Claude Code session independently.
+
+## Cleanup
+
+```bash
+# Remove a specific worktree
+git worktree remove "../${REPO_NAME}-worktrees/a"
+
+# Remove all worktrees
+git worktree list | grep -v "bare\|$(git rev-parse --show-toplevel)$" | awk '{print $1}' | xargs -I{} git worktree remove {}
+
+# Prune stale worktree references
+git worktree prune
+```
+
+## Tips
+
+- Each worktree has its own working directory but shares git history
+- Install dependencies separately in each worktree (`npm install` etc.)
+- Commits in any worktree are visible from all others
+- Merge worktree branches back when done: `git merge feature-wt-a`

package/templates/hooks/auto-approve.json

@@ -0,0 +1,16 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node -e \"const cmd = process.env.CLAUDE_TOOL_INPUT || '{}'; const parsed = JSON.parse(cmd); const cmdStr = parsed.command || ''; if (/[;&|`$()]/.test(cmdStr)) process.exit(1); const safe = /^(git\\s+(status|log|diff|branch|show|stash)|ls|cat|head|tail|wc|find|grep|echo|pwd|which|node\\s+--version|npm\\s+(test|list|outdated)|npm\\s+run\\s+(test|lint|format|check|typecheck|build)|pnpm\\s+(test|list)|pnpm\\s+run\\s+(test|lint|format|check|typecheck|build)|bun\\s+(test|run\\s+(test|lint|format|check|typecheck|build))|yarn\\s+(test|run\\s+(test|lint|format|check|typecheck|build))|pytest|go\\s+(test|vet|build)|cargo\\s+(test|build|check|clippy)|dotnet\\s+(test|build)|mix\\s+(test|deps)|bundle\\s+exec\\s+(rspec|rubocop))$/.test(cmdStr); process.exit(safe ? 0 : 1)\""
+          }
+        ]
+      }
+    ]
+  },
+  "_comment": "Auto-approves read-only and test commands. Installed by clauderc to ~/.claude/hooks/. Customize by editing this file."
+}

package/templates/manifest.json

@@ -1,6 +1,6 @@
 {
-  "version": "2.0.0",
-  "generatedAt": "2025-01-24T00:00:00.000Z",
+  "version": "1.1.0",
+  "generatedAt": "2026-02-03T00:00:00.000Z",
   "files": {
     "agents/project-setup-wizard.md": {
       "version": "1.0.0",
@@ -17,6 +17,16 @@
       "added": "1.0.0",
       "description": "Quick reference for Claude Code templates"
     },
+    "skills/evolve-claude-md/SKILL.md": {
+      "version": "1.0.0",
+      "added": "1.1.0",
+      "description": "Self-improving CLAUDE.md - analyzes errors and suggests rule updates"
+    },
+    "skills/explain/SKILL.md": {
+      "version": "1.0.0",
+      "added": "1.1.0",
+      "description": "Codebase visualization and architecture explanation skill"
+    },
     "commands/test.md": {
       "version": "1.0.0",
       "added": "1.0.0",
@@ -47,6 +57,21 @@
       "added": "1.1.0",
       "description": "Semantic commit command"
     },
+    "commands/worktree.md": {
+      "version": "1.0.0",
+      "added": "1.1.0",
+      "description": "Git worktree management for parallel Claude Code sessions"
+    },
+    "commands/fix.md": {
+      "version": "1.0.0",
+      "added": "1.1.0",
+      "description": "Autonomous bug investigation and fixing"
+    },
+    "hooks/auto-approve.json": {
+      "version": "1.0.0",
+      "added": "1.1.0",
+      "description": "Auto-approve hooks for safe read-only and test commands"
+    },
     "templates/project-setup/CLAUDE_MD_TEMPLATE.md": {
       "version": "1.0.0",
       "added": "1.0.0",
@@ -74,26 +99,50 @@
     },
     "cursor/rules/project-analysis.mdc": {
       "version": "1.0.0",
-      "added": "2.0.0",
+      "added": "1.0.5",
       "provider": "cursor",
       "description": "Project analysis rule for Cursor"
     },
     "cursor/rules/code-templates.mdc": {
       "version": "1.0.0",
-      "added": "2.0.0",
+      "added": "1.0.5",
       "provider": "cursor",
       "description": "Code templates reference for Cursor"
     },
     "cursor/rules/setup-wizard.mdc": {
       "version": "1.0.0",
-      "added": "2.0.0",
+      "added": "1.0.5",
       "provider": "cursor",
       "description": "Setup wizard rule for Cursor"
     }
   },
   "changelog": [
     {
-      "version": "2.0.0",
+      "version": "1.1.0",
+      "date": "2026-02-03",
+      "changes": {
+        "added": [
+          "skills/evolve-claude-md - Self-improving CLAUDE.md from error analysis",
+          "skills/explain - Codebase visualization and architecture explanation",
+          "commands/worktree.md - Git worktree management for parallel sessions",
+          "commands/fix.md - Autonomous bug investigation and fixing",
+          "hooks/auto-approve.json - Auto-approval for safe commands",
+          "Worktree workflow section in generated CLAUDE.md",
+          "Advanced prompting section in generated CLAUDE.md",
+          "Self-improvement section in generated CLAUDE.md",
+          "Subagent pattern guidance in CLAUDE_MD_TEMPLATE"
+        ],
+        "changed": [
+          "CLAUDE_MD_TEMPLATE.md updated with Boris Cherny productivity insights",
+          "CLI init now creates hooks/ directory",
+          "CLI list now shows installed hooks"
+        ],
+        "removed": [],
+        "deprecated": []
+      }
+    },
+    {
+      "version": "1.0.5",
       "date": "2025-01-25",
       "changes": {
         "added": [

package/templates/project-setup/CLAUDE_MD_TEMPLATE.md

@@ -21,22 +21,57 @@ Use this template as base for generating project-specific CLAUDE.md files.
 
 # Build
 {{BUILD_COMMANDS}}
+
+# Full verification
+{{VERIFY_COMMAND}}
 ```
 
 ## Code Style
 {{CODE_STYLE_RULES}}
 
 ## Workflow
-- Plan Mode for: refactors > 3 files, new features, architecture changes
-- Always run `{{VERIFY_COMMAND}}` before commit
-- Parallel work OK for: independent modules, test files, docs
+
+### Plan Mode
+Use Plan Mode (Shift+Tab 2x) for:
+- Refactoring > 3 files
+- New feature implementation
+- Architecture changes
+- Database migrations
+
+### Parallel Workflow (Worktrees)
+For parallel tasks, use git worktrees:
+- Run `/worktree` to set up parallel workspaces
+- Use aliases: `za` (feature), `zb` (bugfix), `zc` (experiment), `z0` (main)
+- Each worktree runs its own Claude Code session independently
+- Merge branches back when done
+
+### Verification
+- ALWAYS run `{{VERIFY_COMMAND}}` before committing
+- NEVER skip tests without explicit approval
+
+### Advanced Prompting
+- When reviewing changes, grill them: "Is this the best approach? What are the edge cases?"
+- Ask Claude to reimplement elegantly after a working prototype
+- Use subagents for focused tasks (security review, test writing, code review)
+
+### Subagents as Default Pattern
+For complex tasks, prefer dispatching subagents:
+- Security review: dedicated security reviewer agent
+- Test generation: dedicated test writer agent
+- Code review: dedicated code reviewer agent
+- Each agent has focused context and expertise
 
 ## Conventions
 - Commits: [Conventional Commits](https://conventionalcommits.org) — `<type>(<scope>): <subject>`
 - Types: feat, fix, docs, style, refactor, perf, test, chore, ci
 - Breaking changes: `!` suffix or `BREAKING CHANGE:` footer
 - PRs: same title format, structured body (Summary, Changes, Test Plan)
-- Versioning: feat → MINOR, fix → PATCH, breaking → MAJOR
+- Versioning: feat -> MINOR, fix -> PATCH, breaking -> MAJOR
+
+## Self-Improvement
+- After fixing bugs, run `/evolve-claude-md` to capture learnings
+- Claude is good at writing rules for itself - let it suggest CLAUDE.md updates
+- Review and approve suggestions before applying
 
 ## Architecture
 {{ARCHITECTURE_NOTES}}
@@ -54,3 +89,5 @@ Use this template as base for generating project-specific CLAUDE.md files.
 3. **Focus on what's different** - Don't repeat language defaults
 4. **Use @imports for details** - `@docs/architecture.md` instead of inline
 5. **Update the date** - Add `Last updated: YYYY-MM-DD` at bottom
+6. **Self-improve** - Run `/evolve-claude-md` after incidents to capture learnings
+7. **Parallel-ready** - Document worktree workflow if team uses it

package/templates/skills/evolve-claude-md/SKILL.md

@@ -0,0 +1,121 @@
+# Evolve CLAUDE.md
+
+Analyze recent errors, PR feedback, and debugging sessions to suggest improvements to the project's CLAUDE.md. Claude is surprisingly good at writing rules for itself.
+
+## When to Use
+
+- After fixing a bug that could have been prevented by better instructions
+- After a PR review reveals missing conventions
+- After a debugging session uncovers undocumented patterns
+- Periodically (weekly/sprint) to refine project rules
+- After onboarding a new team member who hit friction
+
+## Workflow
+
+### 1. Gather Context
+
+Collect recent signals about what went wrong or could be improved:
+
+```bash
+# Recent commits (look for fix/refactor patterns)
+git log --oneline -20 --grep="fix\|refactor\|revert"
+
+# Recent PR comments (if using GitHub)
+gh pr list --state merged --limit 5 --json number,title | head -20
+```
+
+### 2. Analyze Current CLAUDE.md
+
+Read the existing CLAUDE.md and identify:
+- Missing commands or outdated commands
+- Missing conventions that caused recent bugs
+- Missing architecture notes that led to wrong approaches
+- Missing workflow guidance
+
+### 3. Identify Improvement Categories
+
+| Category | Signal | Example Rule to Add |
+|----------|--------|---------------------|
+| **Missing Convention** | Repeated style fixes in PRs | "Always use named exports" |
+| **Undocumented Pattern** | Bug from wrong usage | "Use `trx` for DB transactions" |
+| **Outdated Command** | Command fails or changed | Update test/build commands |
+| **Missing Guard Rail** | Repeated mistake | "Never modify migration files" |
+| **Architecture Gap** | Wrong file placement | "API routes go in `src/routes/`" |
+| **Missing Context** | Wrong assumptions | "This is a multi-tenant app" |
+
+### 4. Generate Suggestions
+
+For each improvement, provide:
+
+```markdown
+## Suggested Addition: [Category]
+
+**Signal:** [What happened that revealed this gap]
+
+**Current CLAUDE.md:** [What it says now, or "missing"]
+
+**Proposed Change:**
+[Exact text to add/modify in CLAUDE.md]
+
+**Rationale:** [Why this prevents future issues]
+```
+
+### 5. Apply Changes
+
+After approval, update CLAUDE.md with the accepted suggestions.
+Keep CLAUDE.md under 100 lines - use @imports for detailed docs.
+
+## Rules
+
+- NEVER remove existing rules without explicit approval
+- ALWAYS explain WHY a rule is being added (cite the incident)
+- PREFER specific rules over vague guidelines
+- KEEP rules actionable - "do X" not "consider X"
+- GROUP related rules under existing sections when possible
+- USE @imports if CLAUDE.md exceeds 100 lines
+
+## Examples
+
+### Example 1: After a bug fix
+
+**Signal:** Fixed a bug where API response wasn't validated
+
+**Proposed Addition to CLAUDE.md:**
+```markdown
+## API Conventions
+- Always validate API responses with zod schemas before using data
+- Never trust external API response shapes - they can change
+```
+
+### Example 2: After PR feedback
+
+**Signal:** PR reviewer noted inconsistent error handling
+
+**Proposed Addition to CLAUDE.md:**
+```markdown
+## Error Handling
+- Use `AppError` class for all application errors
+- Always include error code, message, and context
+- Log errors with structured logging (`logger.error({ err, context })`)
+```
+
+### Example 3: After debugging session
+
+**Signal:** Spent 30 minutes debugging because test DB wasn't reset
+
+**Proposed Addition to CLAUDE.md:**
+```markdown
+## Testing
+- Run `npm run db:reset:test` before test suites
+- Tests use isolated DB transactions (auto-rolled back)
+```
+
+## Checklist
+
+- [ ] Reviewed recent git history for fix/refactor commits
+- [ ] Checked recent PR comments for recurring feedback
+- [ ] Identified gaps in current CLAUDE.md
+- [ ] Generated specific, actionable suggestions
+- [ ] Each suggestion cites the originating signal
+- [ ] CLAUDE.md stays under 100 lines (use @imports if needed)
+- [ ] No existing rules were removed without approval

package/templates/skills/explain/SKILL.md

@@ -0,0 +1,130 @@
+# Explain Codebase
+
+Learning mode - generates visual explanations of codebase architecture, data flows, and component relationships using ASCII diagrams or HTML presentations.
+
+## When to Use
+
+- Onboarding to a new codebase
+- Understanding a complex module before modifying it
+- Documenting architecture for the team
+- Before a major refactoring to understand current state
+- Explaining a subsystem to a colleague
+
+## Workflow
+
+### 1. Identify Scope
+
+Ask: "What part of the codebase do you want to understand?"
+
+Options:
+- **Full architecture** - High-level system overview
+- **Module deep-dive** - One module/package in detail
+- **Data flow** - How data moves through the system
+- **Dependency map** - What depends on what
+- **API surface** - Public interfaces and endpoints
+
+### 2. Gather Information
+
+```bash
+# Project structure
+find . -type f -name "*.{js,ts,py,go,rs}" | head -50
+
+# Entry points
+ls src/index.* src/main.* src/app.* app/main.* cmd/main.* 2>/dev/null
+
+# Dependencies between modules
+grep -r "import.*from" src/ --include="*.{js,ts}" | head -30
+# or for Python
+grep -r "^from\|^import" src/ --include="*.py" | head -30
+```
+
+### 3. Generate Explanation
+
+Choose output format based on complexity:
+
+#### ASCII Diagram (default - works everywhere)
+
+```
++------------------+     +------------------+
+|   API Gateway    |---->|   Auth Service   |
++------------------+     +------------------+
+        |                         |
+        v                         v
++------------------+     +------------------+
+|  Request Router  |     |   User Store     |
++------------------+     +------------------+
+        |
+   +----+----+
+   |         |
+   v         v
++------+  +------+
+| Users |  | Posts |
++------+  +------+
+```
+
+#### Data Flow Diagram
+
+```
+Request -> Middleware -> Controller -> Service -> Repository -> Database
+                                         |
+                                         v
+                                      Cache
+                                         |
+                                         v
+                                     Response
+```
+
+#### Module Dependency Map
+
+```
+src/
+  index.js ─────────> app.js
+                        |
+                  +-----+-----+
+                  |           |
+              routes/     middleware/
+                |             |
+            controllers/  auth.js
+                |
+            services/
+                |
+            models/
+```
+
+### 4. Add Context
+
+For each component in the diagram, provide:
+
+| Component | Purpose | Key Files | Dependencies |
+|-----------|---------|-----------|--------------|
+| API Gateway | HTTP entry point | `src/app.js` | express, cors |
+| Auth Service | JWT validation | `src/auth/` | jsonwebtoken |
+| User Store | User CRUD | `src/models/user.js` | mongoose |
+
+### 5. Generate HTML (optional, for richer output)
+
+If requested, generate a self-contained HTML file with:
+- Interactive component diagram (SVG)
+- Collapsible sections for each module
+- Color-coded dependency visualization
+- Search functionality
+
+Save to: `docs/architecture-explanation.html`
+
+## Output Formats
+
+| Format | Best For | Command |
+|--------|----------|---------|
+| ASCII | Quick overview, terminal | Default |
+| Markdown table | Documentation | "explain as markdown" |
+| HTML | Presentations, sharing | "explain as HTML" |
+| Mermaid | GitHub-rendered diagrams | "explain as mermaid" |
+
+## Checklist
+
+- [ ] Identified the scope (full/module/flow/deps/api)
+- [ ] Gathered file structure and imports
+- [ ] Generated appropriate diagram type
+- [ ] Added context table for each component
+- [ ] Verified diagram matches actual code structure
+- [ ] Saved output in requested format