@dzhechkov/p-replicator 1.0.0

package/templates/.claude/skills/cc-toolkit-generator-enhanced/references/templates/insights-system.md

@@ -0,0 +1,349 @@
+# Insights System Templates
+
+Templates for generating the insights knowledge base system.
+Architecture: **index file + individual detail files** (like llms.txt pattern).
+
+---
+
+## 1. Command Template: `/myinsights`
+
+Generate as `.claude/commands/myinsights.md`:
+
+````markdown
+---
+description: Capture a development insight or manage existing insights.
+  Creates structured entry in myinsights/ folder with auto-indexing.
+  $ARGUMENTS: brief title OR subcommand (archive INS-NNN, status INS-NNN [active|workaround|obsolete])
+---
+
+# /myinsights $ARGUMENTS
+
+## What You Do
+
+Manage the project's living knowledge base in `myinsights/` folder.
+Each insight is stored as an individual file for precise context loading.
+
+## Subcommands
+
+- `/myinsights [title]` — capture a new insight (default)
+- `/myinsights archive INS-NNN` — move insight to archive (obsolete)
+- `/myinsights status INS-NNN [active|workaround|obsolete]` — change insight status
+
+## Capture Flow (default)
+
+### Step 0. Duplicate Detection
+
+**BEFORE creating a new insight**, search the index for duplicates:
+
+1. Read `myinsights/1nsights.md`
+2. Search the `Error Signatures` column for matching error strings from the current issue
+3. Search the `Summary` column for semantically similar descriptions
+
+**If potential duplicate found:**
+```
+⚠️ Possible duplicate of [INS-NNN] Title
+   File: myinsights/INS-NNN-slug.md
+   
+   Options:
+   1. View existing insight and update it with new info
+   2. Create new insight anyway (different root cause)
+   3. Cancel
+```
+
+If the user chooses to update — append new info to the existing detail file under
+a `### Update YYYY-MM-DD` subsection and update the index entry if needed.
+
+### Step 1. Collect Information
+
+Ask the user (or reconstruct from conversation context) these details:
+
+- **Title:** One-line summary of the problem/finding
+- **Error Signatures:** Exact error strings, codes, or exception names that can be grepped
+  (e.g., `ECONNREFUSED`, `P1001`, `TypeError: Cannot read properties of undefined`)
+- **Symptoms:** What went wrong? What was the unexpected behavior?
+- **Diagnostic Steps:** What steps were taken to identify the root cause?
+- **Root Cause:** What was the actual underlying problem?
+- **Solution:** What fixed it? Step-by-step resolution.
+- **Prevention:** How to avoid this in the future? Any guards, tests, or checks to add?
+- **Tags:** Relevant categories (e.g., `docker`, `auth`, `deployment`, `database`, `config`)
+- **Related:** Links to other insights, docs, or issues (e.g., `INS-003`, `INS-017`)
+
+### Step 2. Create Individual Detail File
+
+**File naming:** `myinsights/INS-NNN-slug.md` where slug is a short kebab-case description.
+
+```markdown
+# [INS-NNN] Title
+
+**Date:** YYYY-MM-DD
+**Status:** 🟢 Active | 🟡 Workaround | 🔴 Obsolete
+**Severity:** 🔴 Critical / 🟡 Medium / 🟢 Low
+**Tags:** `tag1`, `tag2`, `tag3`
+**Hits:** 0
+
+## Error Signatures
+```
+EXACT_ERROR_STRING_1
+EXACT_ERROR_STRING_2
+error code or exception name
+```
+
+## Symptoms
+[What went wrong — error messages, unexpected behavior, failing tests]
+
+## Diagnostic Steps
+1. [What was checked first]
+2. [What was tried]
+3. [What led to the root cause]
+
+## Root Cause
+[The actual underlying problem — be specific]
+
+## Solution
+1. [Step-by-step fix]
+2. [Code changes, config changes]
+3. [Verification that it works]
+
+## Prevention
+- [How to avoid this in the future]
+- [Tests to add, checks to implement]
+
+## Related
+- [INS-XXX](INS-XXX-slug.md) — related insight description
+- [Link to external doc or issue]
+```
+
+### Step 3. Update Index (`myinsights/1nsights.md`)
+
+If `myinsights/1nsights.md` doesn't exist, create it:
+
+```markdown
+# 🔍 Development Insights Index
+
+Living knowledge base. **Read this file first** — then load specific detail files as needed.
+
+> **For Claude Code:** When you encounter an error, `grep` the Error Signatures column below.
+> If you find a match, read ONLY the linked detail file — don't load everything.
+
+| ID | Error Signatures | Summary | Status | Hits | File |
+|----|-----------------|---------|--------|------|------|
+```
+
+Then append a new row:
+
+```markdown
+| INS-NNN | `ERROR_SIG_1`, `ERROR_SIG_2` | One-line summary | 🟢 Active | 0 | [INS-NNN-slug.md](INS-NNN-slug.md) |
+```
+
+### Step 4. Auto-numbering
+
+List existing `INS-*.md` files in `myinsights/` (including `archive/`),
+find the highest `INS-NNN` number, increment by 1. First entry is `INS-001`.
+
+### Step 5. Notify
+
+After saving:
+```
+✅ Insight captured: [INS-NNN] Title
+📄 myinsights/INS-NNN-slug.md created
+📋 myinsights/1nsights.md index updated
+🔄 Will be auto-committed on session end (Stop hook)
+```
+
+If this is the FIRST insight in the project, also notify:
+```
+📌 myinsights/ reference added to CLAUDE.md as knowledge source
+```
+
+## Archive Flow (`/myinsights archive INS-NNN`)
+
+1. Move `myinsights/INS-NNN-slug.md` → `myinsights/archive/INS-NNN-slug.md`
+2. Update status in `1nsights.md` index to `🔴 Obsolete`
+3. Add `(archived)` suffix to the file link in index
+4. Notify: `📦 INS-NNN archived → myinsights/archive/`
+
+## Status Flow (`/myinsights status INS-NNN [status]`)
+
+1. Update `**Status:**` line in the detail file
+2. Update status column in `1nsights.md` index
+3. If new status is `obsolete` — suggest archiving: `💡 Consider: /myinsights archive INS-NNN`
+4. Notify: `🔄 INS-NNN status → [new status]`
+
+## Hit Counter
+
+When an insight is used to solve a problem (matched via grep or manual lookup):
+1. Increment `**Hits:**` counter in the detail file
+2. Increment `Hits` column in `1nsights.md` index
+3. Note: `📊 INS-NNN hit count → N (helped solve current issue)`
+
+Insights with higher hit counts are more valuable — consider this when prioritizing
+which insights to check first during debugging.
+````
+
+---
+
+## 2. Rule Template: `insights-capture.md`
+
+Generate as `.claude/rules/insights-capture.md`:
+
+````markdown
+# Insights Capture Protocol
+
+## 🔍 Error-First Lookup (CRITICAL — do this BEFORE debugging)
+
+**IMPORTANT:** When you encounter ANY error, ALWAYS do this before starting to debug:
+
+```bash
+# Step 1: Check if index exists
+if [ -f "myinsights/1nsights.md" ]; then
+  # Step 2: Grep for the error signature in the index
+  grep -i "ERROR_STRING_OR_CODE" myinsights/1nsights.md
+fi
+```
+
+**Pattern:**
+1. User reports a problem or an error occurs
+2. Extract the key error string (error code, exception name, or unique message fragment)
+3. `grep` the error string against `myinsights/1nsights.md` Error Signatures column
+4. **If match found** → read ONLY the linked detail file → suggest documented solution FIRST
+5. **If match found AND solution works** → increment hit counter in both index and detail file
+6. **If no match** → debug normally → after resolution, suggest capturing with `/myinsights`
+
+**Example lookup flow:**
+```
+Error: ECONNREFUSED 127.0.0.1:5432
+→ grep "ECONNREFUSED" myinsights/1nsights.md
+→ Match: INS-001 | `ECONNREFUSED`, `port 5432` | Postgres in Docker... | INS-001-docker-pg-network.md
+→ cat myinsights/INS-001-docker-pg-network.md
+→ Apply documented solution
+→ Increment hit counter
+```
+
+## When to Suggest Capturing an Insight
+
+Proactively suggest `/myinsights` when ANY of these occur:
+
+1. **Error → Fix cycle**: A non-trivial bug was debugged and resolved
+   - Especially: errors that took >3 attempts to fix
+   - Especially: misleading error messages that pointed wrong direction
+
+2. **Configuration surprise**: A config setting behaved unexpectedly
+   - Docker networking quirks
+   - Environment variable gotchas
+   - Build tool configuration issues
+
+3. **Dependency issue**: A library/package caused problems
+   - Version conflicts
+   - Undocumented breaking changes
+   - Platform-specific behavior
+
+4. **Architecture decision under pressure**: A design choice was made
+   during debugging that should be documented
+
+5. **Workaround applied**: A temporary fix was applied that needs
+   future attention (suggest status: 🟡 Workaround)
+
+## How to Suggest
+
+After resolving a tricky issue, say:
+```
+💡 This looks like a valuable insight. Want me to capture it?
+   Run `/myinsights [brief title]` or say "да, запиши"
+```
+
+## When NOT to Suggest
+
+- Trivial typos or syntax errors
+- Well-known framework patterns
+- Issues already documented in `myinsights/` (check index first!)
+- User explicitly said they don't want to capture
+
+## Lifecycle Awareness
+
+When reviewing insights during lookup, check the status:
+- `🟢 Active` — trusted solution, apply directly
+- `🟡 Workaround` — temporary fix, may need better solution. Apply but flag to user.
+- `🔴 Obsolete` — should be in archive. If found in main folder, suggest `/myinsights archive INS-NNN`
+
+When a workaround gets a proper fix, suggest:
+```
+💡 INS-NNN was a workaround. Now we have a proper fix — update it?
+   Run `/myinsights status INS-NNN active` and I'll update the solution.
+```
+````
+
+---
+
+## 3. Hook Template: Stop Event
+
+Add to `.claude/settings.json` hooks section:
+
+```json
+{
+  "hooks": {
+    "Stop": [
+      {
+        "matcher": "",
+        "command": "bash -c '\nDIR=\"myinsights\"\nINDEX=\"myinsights/1nsights.md\"\nCLAUDE=\"CLAUDE.md\"\n\n# Check if myinsights/ has any uncommitted changes\nif [ -d \"$DIR\" ] && (git diff --name-only -- \"$DIR\" 2>/dev/null | grep -q . || git diff --name-only --cached -- \"$DIR\" 2>/dev/null | grep -q . || git ls-files --others --exclude-standard -- \"$DIR\" 2>/dev/null | grep -q .); then\n  \n  # Auto-add insights reference to CLAUDE.md on first time\n  if ! grep -q \"myinsights\" \"$CLAUDE\" 2>/dev/null; then\n    printf \"\\n## 🔍 Development Insights (живая база знаний)\\nIndex: [myinsights/1nsights.md](myinsights/1nsights.md) — check here FIRST before debugging.\\n⚠️ On error → grep the error string in the index → read only the matched detail file.\\nCapture new findings: \\`/myinsights [title]\\`\\n\" >> \"$CLAUDE\"\n    git add \"$CLAUDE\"\n    echo \"📌 myinsights/ reference added to CLAUDE.md\"\n  fi\n  \n  # Auto-commit all changes in myinsights/\n  git add \"$DIR\"\n  git commit -m \"docs(insights): update knowledge base\"\n  echo \"✅ myinsights/ auto-committed\"\nfi\n'"
+      }
+    ]
+  }
+}
+```
+
+**Readable version:**
+
+```bash
+#!/bin/bash
+DIR="myinsights"
+INDEX="myinsights/1nsights.md"
+CLAUDE="CLAUDE.md"
+
+# Check if myinsights/ has any uncommitted or untracked changes
+if [ -d "$DIR" ] && \
+   (git diff --name-only -- "$DIR" 2>/dev/null | grep -q . || \
+    git diff --name-only --cached -- "$DIR" 2>/dev/null | grep -q . || \
+    git ls-files --others --exclude-standard -- "$DIR" 2>/dev/null | grep -q .); then
+  
+  # Auto-add insights reference to CLAUDE.md on first time
+  if ! grep -q "myinsights" "$CLAUDE" 2>/dev/null; then
+    cat >> "$CLAUDE" << 'EOF'
+
+## 🔍 Development Insights (живая база знаний)
+Index: [myinsights/1nsights.md](myinsights/1nsights.md) — check here FIRST before debugging.
+⚠️ On error → grep the error string in the index → read only the matched detail file.
+Capture new findings: `/myinsights [title]`
+EOF
+    git add "$CLAUDE"
+    echo "📌 myinsights/ reference added to CLAUDE.md"
+  fi
+  
+  # Auto-commit all changes in myinsights/
+  git add "$DIR"
+  git commit -m "docs(insights): update knowledge base"
+  echo "✅ myinsights/ auto-committed"
+fi
+```
+
+**Why `Stop` event:**
+- Non-intrusive — doesn't interrupt work flow
+- Catches ALL changes in `myinsights/` — new files, edits, hit counter updates, archives
+- Handles **untracked** new files (the old version only caught modified tracked files)
+- Ensures the entire knowledge base folder is always committed
+- First-time CLAUDE.md update happens seamlessly
+
+---
+
+## 4. CLAUDE.md Integration
+
+When generating CLAUDE.md, ALWAYS include this section (even before first insight exists):
+
+```markdown
+## 🔍 Development Insights (живая база знаний)
+Index: [myinsights/1nsights.md](myinsights/1nsights.md) — check here FIRST before debugging.
+⚠️ On error → grep the error string in the index → read only the matched detail file.
+Capture new findings: `/myinsights [title]`
+```
+
+The Stop hook will add this section automatically if it's missing (safety net), but generating
+it upfront ensures Claude Code reads insights from the very first session.

package/templates/.claude/skills/cc-toolkit-generator-enhanced/references/templates/mcp.md

@@ -0,0 +1,274 @@
+# MCP Configuration Template
+
+Use this template to generate .mcp.json for Claude Code projects.
+
+---
+
+## Base Structure
+
+```json
+{
+  "mcpServers": {
+    
+  },
+  "disabledMcpServers": []
+}
+```
+
+---
+
+## Common MCP Server Configs
+
+### GitHub
+```json
+{
+  "mcpServers": {
+    "github": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-github"],
+      "env": {
+        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
+      }
+    }
+  }
+}
+```
+
+### PostgreSQL
+```json
+{
+  "mcpServers": {
+    "postgres": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-postgres"],
+      "env": {
+        "DATABASE_URL": "${DATABASE_URL}"
+      }
+    }
+  }
+}
+```
+
+### Supabase
+```json
+{
+  "mcpServers": {
+    "supabase": {
+      "command": "npx",
+      "args": ["-y", "@supabase/mcp-server"],
+      "env": {
+        "SUPABASE_URL": "${SUPABASE_URL}",
+        "SUPABASE_KEY": "${SUPABASE_KEY}"
+      }
+    }
+  }
+}
+```
+
+### Slack
+```json
+{
+  "mcpServers": {
+    "slack": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-slack"],
+      "env": {
+        "SLACK_BOT_TOKEN": "${SLACK_BOT_TOKEN}"
+      }
+    }
+  }
+}
+```
+
+### Notion
+```json
+{
+  "mcpServers": {
+    "notion": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-notion"],
+      "env": {
+        "NOTION_TOKEN": "${NOTION_TOKEN}"
+      }
+    }
+  }
+}
+```
+
+### Brave Search
+```json
+{
+  "mcpServers": {
+    "brave-search": {
+      "command": "npx",
+      "args": ["-y", "@anthropic/mcp-server-brave-search"],
+      "env": {
+        "BRAVE_API_KEY": "${BRAVE_API_KEY}"
+      }
+    }
+  }
+}
+```
+
+### Puppeteer
+```json
+{
+  "mcpServers": {
+    "puppeteer": {
+      "command": "npx",
+      "args": ["-y", "@anthropic/mcp-server-puppeteer"]
+    }
+  }
+}
+```
+
+### Sequential Thinking
+```json
+{
+  "mcpServers": {
+    "sequential-thinking": {
+      "command": "npx",
+      "args": ["-y", "@anthropic/mcp-server-sequential-thinking"]
+    }
+  }
+}
+```
+
+### Memory (KV Store)
+```json
+{
+  "mcpServers": {
+    "memory": {
+      "command": "npx",
+      "args": ["-y", "@anthropic/mcp-server-memory"]
+    }
+  }
+}
+```
+
+### Filesystem
+```json
+{
+  "mcpServers": {
+    "filesystem": {
+      "command": "npx",
+      "args": ["-y", "@anthropic/mcp-server-filesystem", "/path/to/allowed/dir"]
+    }
+  }
+}
+```
+
+---
+
+## Combined Example
+
+For a project with GitHub, PostgreSQL, and Slack:
+
+```json
+{
+  "mcpServers": {
+    "github": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-github"],
+      "env": {
+        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
+      }
+    },
+    "postgres": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-postgres"],
+      "env": {
+        "DATABASE_URL": "${DATABASE_URL}"
+      }
+    },
+    "slack": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-slack"],
+      "env": {
+        "SLACK_BOT_TOKEN": "${SLACK_BOT_TOKEN}"
+      }
+    }
+  },
+  "disabledMcpServers": []
+}
+```
+
+---
+
+## Generation Rules
+
+### From Architecture.md
+
+1. Extract `External Integrations` or `Third-Party Services` section
+2. Match each integration to known MCP servers
+3. Generate config with appropriate env vars
+4. Add unmatched integrations as comments
+
+### Matching Priority
+
+1. **Exact match** — use official server
+2. **Category match** — use generic server (e.g., any SQL → postgres)
+3. **No match** — add comment for custom consideration
+
+### Environment Variables
+
+Always use `${VAR_NAME}` syntax for secrets:
+- Never hardcode tokens/keys
+- Use descriptive names: `GITHUB_TOKEN`, `DATABASE_URL`
+- Document required vars in INSTALL.md
+
+---
+
+## Best Practices
+
+1. **Minimal** — only include servers actually needed
+2. **Disabled by default** — use `disabledMcpServers` for optional ones
+3. **Env vars** — never hardcode secrets
+4. **Test locally** — verify servers work before committing
+
+## Context Window Considerations
+
+| Servers Enabled | Approximate Context Impact |
+|-----------------|---------------------------|
+| 1-5 | Minimal (~5k tokens) |
+| 5-10 | Moderate (~15k tokens) |
+| 10-20 | Significant (~30k tokens) |
+| 20+ | High risk of overflow |
+
+**Recommendation:** Keep <10 servers enabled per project.
+
+## File Location
+
+- Project-level: `.mcp.json` in project root
+- User-level: `~/.config/claude-code/mcp.json`
+
+Project-level takes precedence.
+
+---
+
+## Complete Server Reference
+
+| Integration | Package | Env Vars |
+|-------------|---------|----------|
+| GitHub | @modelcontextprotocol/server-github | GITHUB_TOKEN |
+| GitLab | @modelcontextprotocol/server-gitlab | GITLAB_TOKEN |
+| PostgreSQL | @modelcontextprotocol/server-postgres | DATABASE_URL |
+| MySQL | @modelcontextprotocol/server-mysql | DATABASE_URL |
+| SQLite | @modelcontextprotocol/server-sqlite | DB_PATH |
+| MongoDB | @modelcontextprotocol/server-mongodb | MONGODB_URI |
+| Redis | @modelcontextprotocol/server-redis | REDIS_URL |
+| Supabase | @supabase/mcp-server | SUPABASE_URL, SUPABASE_KEY |
+| Slack | @modelcontextprotocol/server-slack | SLACK_BOT_TOKEN |
+| Notion | @modelcontextprotocol/server-notion | NOTION_TOKEN |
+| Linear | mcp-linear | LINEAR_API_KEY |
+| Jira | mcp-atlassian | JIRA_TOKEN |
+| AWS | @aws/mcp-server | AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY |
+| Vercel | mcp-vercel | VERCEL_TOKEN |
+| Stripe | @stripe/mcp-server | STRIPE_API_KEY |
+| Twilio | mcp-twilio | TWILIO_SID, TWILIO_TOKEN |
+| Brave Search | @anthropic/mcp-server-brave-search | BRAVE_API_KEY |
+| Puppeteer | @anthropic/mcp-server-puppeteer | (none) |
+| Playwright | mcp-playwright | (none) |
+| Memory | @anthropic/mcp-server-memory | (none) |
+| Sequential Thinking | @anthropic/mcp-server-sequential-thinking | (none) |
+| Filesystem | @anthropic/mcp-server-filesystem | (path arg) |