cp-toolkit 2.0.0

package/templates/skills/optional/architecture/pattern-selection.md

@@ -0,0 +1,68 @@
+# Pattern Selection Guidelines
+
+> Decision trees for choosing architectural patterns.
+
+## Main Decision Tree
+
+```
+START: What's your MAIN concern?
+
+┌─ Data Access Complexity?
+│  ├─ HIGH (complex queries, testing needed)
+│  │  → Repository Pattern + Unit of Work
+│  │  VALIDATE: Will data source change frequently?
+│  │     ├─ YES → Repository worth the indirection
+│  │     └─ NO  → Consider simpler ORM direct access
+│  └─ LOW (simple CRUD, single database)
+│     → ORM directly (Prisma, Drizzle)
+│     Simpler = Better, Faster
+│
+├─ Business Rules Complexity?
+│  ├─ HIGH (domain logic, rules vary by context)
+│  │  → Domain-Driven Design
+│  │  VALIDATE: Do you have domain experts on team?
+│  │     ├─ YES → Full DDD (Aggregates, Value Objects)
+│  │     └─ NO  → Partial DDD (rich entities, clear boundaries)
+│  └─ LOW (mostly CRUD, simple validation)
+│     → Transaction Script pattern
+│     Simpler = Better, Faster
+│
+├─ Independent Scaling Needed?
+│  ├─ YES (different components scale differently)
+│  │  → Microservices WORTH the complexity
+│  │  REQUIREMENTS (ALL must be true):
+│  │    - Clear domain boundaries
+│  │    - Team > 10 developers
+│  │    - Different scaling needs per service
+│  │  IF NOT ALL MET → Modular Monolith instead
+│  └─ NO (everything scales together)
+│     → Modular Monolith
+│     Can extract services later when proven needed
+│
+└─ Real-time Requirements?
+   ├─ HIGH (immediate updates, multi-user sync)
+   │  → Event-Driven Architecture
+   │  → Message Queue (RabbitMQ, Redis, Kafka)
+   │  VALIDATE: Can you handle eventual consistency?
+   │     ├─ YES → Event-driven valid
+   │     └─ NO  → Synchronous with polling
+   └─ LOW (eventual consistency acceptable)
+      → Synchronous (REST/GraphQL)
+      Simpler = Better, Faster
+```
+
+## The 3 Questions (Before ANY Pattern)
+
+1. **Problem Solved**: What SPECIFIC problem does this pattern solve?
+2. **Simpler Alternative**: Is there a simpler solution?
+3. **Deferred Complexity**: Can we add this LATER when needed?
+
+## Red Flags (Anti-patterns)
+
+| Pattern | Anti-pattern | Simpler Alternative |
+|---------|-------------|-------------------|
+| Microservices | Premature splitting | Start monolith, extract later |
+| Clean/Hexagonal | Over-abstraction | Concrete first, interfaces later |
+| Event Sourcing | Over-engineering | Append-only audit log |
+| CQRS | Unnecessary complexity | Single model |
+| Repository | YAGNI for simple CRUD | ORM direct access |

package/templates/skills/optional/architecture/patterns-reference.md

@@ -0,0 +1,50 @@
+# Architecture Patterns Reference
+
+> Quick reference for common patterns with usage guidance.
+
+## Data Access Patterns
+
+| Pattern | When to Use | When NOT to Use | Complexity |
+|---------|-------------|-----------------|------------|
+| **Active Record** | Simple CRUD, rapid prototyping | Complex queries, multiple sources | Low |
+| **Repository** | Testing needed, multiple sources | Simple CRUD, single database | Medium |
+| **Unit of Work** | Complex transactions | Simple operations | High |
+| **Data Mapper** | Complex domain, performance | Simple CRUD, rapid dev | High |
+
+## Domain Logic Patterns
+
+| Pattern | When to Use | When NOT to Use | Complexity |
+|---------|-------------|-----------------|------------|
+| **Transaction Script** | Simple CRUD, procedural | Complex business rules | Low |
+| **Table Module** | Record-based logic | Rich behavior needed | Low |
+| **Domain Model** | Complex business logic | Simple CRUD | Medium |
+| **DDD (Full)** | Complex domain, domain experts | Simple domain, no experts | High |
+
+## Distributed System Patterns
+
+| Pattern | When to Use | When NOT to Use | Complexity |
+|---------|-------------|-----------------|------------|
+| **Modular Monolith** | Small teams, unclear boundaries | Clear contexts, different scales | Medium |
+| **Microservices** | Different scales, large teams | Small teams, simple domain | Very High |
+| **Event-Driven** | Real-time, loose coupling | Simple workflows, strong consistency | High |
+| **CQRS** | Read/write performance diverges | Simple CRUD, same model | High |
+| **Saga** | Distributed transactions | Single database, simple ACID | High |
+
+## API Patterns
+
+| Pattern | When to Use | When NOT to Use | Complexity |
+|---------|-------------|-----------------|------------|
+| **REST** | Standard CRUD, resources | Real-time, complex queries | Low |
+| **GraphQL** | Flexible queries, multiple clients | Simple CRUD, caching needs | Medium |
+| **gRPC** | Internal services, performance | Public APIs, browser clients | Medium |
+| **WebSocket** | Real-time updates | Simple request/response | Medium |
+
+---
+
+## Simplicity Principle
+
+**"Start simple, add complexity only when proven necessary."**
+
+- You can always add patterns later
+- Removing complexity is MUCH harder than adding it
+- When in doubt, choose simpler option

package/templates/skills/optional/architecture/trade-off-analysis.md

@@ -0,0 +1,77 @@
+# Trade-off Analysis & ADR
+
+> Document every architectural decision with trade-offs.
+
+## Decision Framework
+
+For EACH architectural component, document:
+
+```markdown
+## Architecture Decision Record
+
+### Context
+- **Problem**: [What problem are we solving?]
+- **Constraints**: [Team size, scale, timeline, budget]
+
+### Options Considered
+
+| Option | Pros | Cons | Complexity | When Valid |
+|--------|------|------|------------|-----------|
+| Option A | Benefit 1 | Cost 1 | Low | [Conditions] |
+| Option B | Benefit 2 | Cost 2 | High | [Conditions] |
+
+### Decision
+**Chosen**: [Option B]
+
+### Rationale
+1. [Reason 1 - tied to constraints]
+2. [Reason 2 - tied to requirements]
+
+### Trade-offs Accepted
+- [What we're giving up]
+- [Why this is acceptable]
+
+### Consequences
+- **Positive**: [Benefits we gain]
+- **Negative**: [Costs/risks we accept]
+- **Mitigation**: [How we'll address negatives]
+
+### Revisit Trigger
+- [When to reconsider this decision]
+```
+
+## ADR Template
+
+```markdown
+# ADR-[XXX]: [Decision Title]
+
+## Status
+Proposed | Accepted | Deprecated | Superseded by [ADR-YYY]
+
+## Context
+[What problem? What constraints?]
+
+## Decision
+[What we chose - be specific]
+
+## Rationale
+[Why - tie to requirements and constraints]
+
+## Trade-offs
+[What we're giving up - be honest]
+
+## Consequences
+- **Positive**: [Benefits]
+- **Negative**: [Costs]
+- **Mitigation**: [How to address]
+```
+
+## ADR Storage
+
+```
+docs/
+└── architecture/
+    ├── adr-001-use-nextjs.md
+    ├── adr-002-postgresql-over-mongodb.md
+    └── adr-003-adopt-repository-pattern.md
+```

package/templates/skills/optional/bash-linux/SKILL.md

@@ -0,0 +1,199 @@
+---
+name: bash-linux
+description: Bash/Linux terminal patterns. Critical commands, piping, error handling, scripting. Use when working on macOS or Linux systems.
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash
+---
+
+# Bash Linux Patterns
+
+> Essential patterns for Bash on Linux/macOS.
+
+---
+
+## 1. Operator Syntax
+
+### Chaining Commands
+
+| Operator | Meaning | Example |
+|----------|---------|---------|
+| `;` | Run sequentially | `cmd1; cmd2` |
+| `&&` | Run if previous succeeded | `npm install && npm run dev` |
+| `\|\|` | Run if previous failed | `npm test \|\| echo "Tests failed"` |
+| `\|` | Pipe output | `ls \| grep ".js"` |
+
+---
+
+## 2. File Operations
+
+### Essential Commands
+
+| Task | Command |
+|------|---------|
+| List all | `ls -la` |
+| Find files | `find . -name "*.js" -type f` |
+| File content | `cat file.txt` |
+| First N lines | `head -n 20 file.txt` |
+| Last N lines | `tail -n 20 file.txt` |
+| Follow log | `tail -f log.txt` |
+| Search in files | `grep -r "pattern" --include="*.js"` |
+| File size | `du -sh *` |
+| Disk usage | `df -h` |
+
+---
+
+## 3. Process Management
+
+| Task | Command |
+|------|---------|
+| List processes | `ps aux` |
+| Find by name | `ps aux \| grep node` |
+| Kill by PID | `kill -9 <PID>` |
+| Find port user | `lsof -i :3000` |
+| Kill port | `kill -9 $(lsof -t -i :3000)` |
+| Background | `npm run dev &` |
+| Jobs | `jobs -l` |
+| Bring to front | `fg %1` |
+
+---
+
+## 4. Text Processing
+
+### Core Tools
+
+| Tool | Purpose | Example |
+|------|---------|---------|
+| `grep` | Search | `grep -rn "TODO" src/` |
+| `sed` | Replace | `sed -i 's/old/new/g' file.txt` |
+| `awk` | Extract columns | `awk '{print $1}' file.txt` |
+| `cut` | Cut fields | `cut -d',' -f1 data.csv` |
+| `sort` | Sort lines | `sort -u file.txt` |
+| `uniq` | Unique lines | `sort file.txt \| uniq -c` |
+| `wc` | Count | `wc -l file.txt` |
+
+---
+
+## 5. Environment Variables
+
+| Task | Command |
+|------|---------|
+| View all | `env` or `printenv` |
+| View one | `echo $PATH` |
+| Set temporary | `export VAR="value"` |
+| Set in script | `VAR="value" command` |
+| Add to PATH | `export PATH="$PATH:/new/path"` |
+
+---
+
+## 6. Network
+
+| Task | Command |
+|------|---------|
+| Download | `curl -O https://example.com/file` |
+| API request | `curl -X GET https://api.example.com` |
+| POST JSON | `curl -X POST -H "Content-Type: application/json" -d '{"key":"value"}' URL` |
+| Check port | `nc -zv localhost 3000` |
+| Network info | `ifconfig` or `ip addr` |
+
+---
+
+## 7. Script Template
+
+```bash
+#!/bin/bash
+set -euo pipefail  # Exit on error, undefined var, pipe fail
+
+# Colors (optional)
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+NC='\033[0m'
+
+# Script directory
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# Functions
+log_info() { echo -e "${GREEN}[INFO]${NC} $1"; }
+log_error() { echo -e "${RED}[ERROR]${NC} $1" >&2; }
+
+# Main
+main() {
+    log_info "Starting..."
+    # Your logic here
+    log_info "Done!"
+}
+
+main "$@"
+```
+
+---
+
+## 8. Common Patterns
+
+### Check if command exists
+
+```bash
+if command -v node &> /dev/null; then
+    echo "Node is installed"
+fi
+```
+
+### Default variable value
+
+```bash
+NAME=${1:-"default_value"}
+```
+
+### Read file line by line
+
+```bash
+while IFS= read -r line; do
+    echo "$line"
+done < file.txt
+```
+
+### Loop over files
+
+```bash
+for file in *.js; do
+    echo "Processing $file"
+done
+```
+
+---
+
+## 9. Differences from PowerShell
+
+| Task | PowerShell | Bash |
+|------|------------|------|
+| List files | `Get-ChildItem` | `ls -la` |
+| Find files | `Get-ChildItem -Recurse` | `find . -type f` |
+| Environment | `$env:VAR` | `$VAR` |
+| String concat | `"$a$b"` | `"$a$b"` (same) |
+| Null check | `if ($x)` | `if [ -n "$x" ]` |
+| Pipeline | Object-based | Text-based |
+
+---
+
+## 10. Error Handling
+
+### Set options
+
+```bash
+set -e          # Exit on error
+set -u          # Exit on undefined variable
+set -o pipefail # Exit on pipe failure
+set -x          # Debug: print commands
+```
+
+### Trap for cleanup
+
+```bash
+cleanup() {
+    echo "Cleaning up..."
+    rm -f /tmp/tempfile
+}
+trap cleanup EXIT
+```
+
+---
+
+> **Remember:** Bash is text-based. Use `&&` for success chains, `set -e` for safety, and quote your variables!

package/templates/skills/optional/code-review-checklist/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: code-review-checklist
+description: Code review guidelines covering code quality, security, and best practices.
+allowed-tools: Read, Glob, Grep
+---
+
+# Code Review Checklist
+
+## Quick Review Checklist
+
+### Correctness
+- [ ] Code does what it's supposed to do
+- [ ] Edge cases handled
+- [ ] Error handling in place
+- [ ] No obvious bugs
+
+### Security
+- [ ] Input validated and sanitized
+- [ ] No SQL/NoSQL injection vulnerabilities
+- [ ] No XSS or CSRF vulnerabilities
+- [ ] No hardcoded secrets or sensitive credentials
+- [ ] **AI-Specific:** Protection against Prompt Injection (if applicable)
+- [ ] **AI-Specific:** Outputs are sanitized before being used in critical sinks
+
+### Performance
+- [ ] No N+1 queries
+- [ ] No unnecessary loops
+- [ ] Appropriate caching
+- [ ] Bundle size impact considered
+
+### Code Quality
+- [ ] Clear naming
+- [ ] DRY - no duplicate code
+- [ ] SOLID principles followed
+- [ ] Appropriate abstraction level
+
+### Testing
+- [ ] Unit tests for new code
+- [ ] Edge cases tested
+- [ ] Tests readable and maintainable
+
+### Documentation
+- [ ] Complex logic commented
+- [ ] Public APIs documented
+- [ ] README updated if needed
+
+## AI & LLM Review Patterns (2025)
+
+### Logic & Hallucinations
+- [ ] **Chain of Thought:** Does the logic follow a verifiable path?
+- [ ] **Edge Cases:** Did the AI account for empty states, timeouts, and partial failures?
+- [ ] **External State:** Is the code making safe assumptions about file systems or networks?
+
+### Prompt Engineering Review
+```markdown
+// ❌ Vague prompt in code
+const response = await ai.generate(userInput);
+
+// ✅ Structured & Safe prompt
+const response = await ai.generate({
+  system: "You are a specialized parser...",
+  input: sanitize(userInput),
+  schema: ResponseSchema
+});
+```
+
+## Anti-Patterns to Flag
+
+```typescript
+// ❌ Magic numbers
+if (status === 3) { ... }
+
+// ✅ Named constants
+if (status === Status.ACTIVE) { ... }
+
+// ❌ Deep nesting
+if (a) { if (b) { if (c) { ... } } }
+
+// ✅ Early returns
+if (!a) return;
+if (!b) return;
+if (!c) return;
+// do work
+
+// ❌ Long functions (100+ lines)
+// ✅ Small, focused functions
+
+// ❌ any type
+const data: any = ...
+
+// ✅ Proper types
+const data: UserData = ...
+```
+
+## Review Comments Guide
+
+```
+// Blocking issues use 🔴
+🔴 BLOCKING: SQL injection vulnerability here
+
+// Important suggestions use 🟡
+🟡 SUGGESTION: Consider using useMemo for performance
+
+// Minor nits use 🟢
+🟢 NIT: Prefer const over let for immutable variable
+
+// Questions use ❓
+❓ QUESTION: What happens if user is null here?
+```

package/templates/skills/optional/database-design/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: database-design
+description: Database design principles and decision-making. Schema design, indexing strategy, ORM selection, serverless databases.
+allowed-tools: Read, Write, Edit, Glob, Grep
+---
+
+# Database Design
+
+> **Learn to THINK, not copy SQL patterns.**
+
+## 🎯 Selective Reading Rule
+
+**Read ONLY files relevant to the request!** Check the content map, find what you need.
+
+| File | Description | When to Read |
+|------|-------------|--------------|
+| `database-selection.md` | PostgreSQL vs Neon vs Turso vs SQLite | Choosing database |
+| `orm-selection.md` | Drizzle vs Prisma vs Kysely | Choosing ORM |
+| `schema-design.md` | Normalization, PKs, relationships | Designing schema |
+| `indexing.md` | Index types, composite indexes | Performance tuning |
+| `optimization.md` | N+1, EXPLAIN ANALYZE | Query optimization |
+| `migrations.md` | Safe migrations, serverless DBs | Schema changes |
+
+---
+
+## ⚠️ Core Principle
+
+- ASK user for database preferences when unclear
+- Choose database/ORM based on CONTEXT
+- Don't default to PostgreSQL for everything
+
+---
+
+## Decision Checklist
+
+Before designing schema:
+
+- [ ] Asked user about database preference?
+- [ ] Chosen database for THIS context?
+- [ ] Considered deployment environment?
+- [ ] Planned index strategy?
+- [ ] Defined relationship types?
+
+---
+
+## Anti-Patterns
+
+❌ Default to PostgreSQL for simple apps (SQLite may suffice)
+❌ Skip indexing
+❌ Use SELECT * in production
+❌ Store JSON when structured data is better
+❌ Ignore N+1 queries

package/templates/skills/optional/database-design/database-selection.md

@@ -0,0 +1,43 @@
+# Database Selection (2025)
+
+> Choose database based on context, not default.
+
+## Decision Tree
+
+```
+What are your requirements?
+│
+├── Full relational features needed
+│   ├── Self-hosted → PostgreSQL
+│   └── Serverless → Neon, Supabase
+│
+├── Edge deployment / Ultra-low latency
+│   └── Turso (edge SQLite)
+│
+├── AI / Vector search
+│   └── PostgreSQL + pgvector
+│
+├── Simple / Embedded / Local
+│   └── SQLite
+│
+└── Global distribution
+    └── PlanetScale, CockroachDB, Turso
+```
+
+## Comparison
+
+| Database | Best For | Trade-offs |
+|----------|----------|------------|
+| **PostgreSQL** | Full features, complex queries | Needs hosting |
+| **Neon** | Serverless PG, branching | PG complexity |
+| **Turso** | Edge, low latency | SQLite limitations |
+| **SQLite** | Simple, embedded, local | Single-writer |
+| **PlanetScale** | MySQL, global scale | No foreign keys |
+
+## Questions to Ask
+
+1. What's the deployment environment?
+2. How complex are the queries?
+3. Is edge/serverless important?
+4. Vector search needed?
+5. Global distribution required?

package/templates/skills/optional/database-design/indexing.md

@@ -0,0 +1,39 @@
+# Indexing Principles
+
+> When and how to create indexes effectively.
+
+## When to Create Indexes
+
+```
+Index these:
+├── Columns in WHERE clauses
+├── Columns in JOIN conditions
+├── Columns in ORDER BY
+├── Foreign key columns
+└── Unique constraints
+
+Don't over-index:
+├── Write-heavy tables (slower inserts)
+├── Low-cardinality columns
+├── Columns rarely queried
+```
+
+## Index Type Selection
+
+| Type | Use For |
+|------|---------|
+| **B-tree** | General purpose, equality & range |
+| **Hash** | Equality only, faster |
+| **GIN** | JSONB, arrays, full-text |
+| **GiST** | Geometric, range types |
+| **HNSW/IVFFlat** | Vector similarity (pgvector) |
+
+## Composite Index Principles
+
+```
+Order matters for composite indexes:
+├── Equality columns first
+├── Range columns last
+├── Most selective first
+└── Match query pattern
+```

package/templates/skills/optional/database-design/migrations.md

@@ -0,0 +1,48 @@
+# Migration Principles
+
+> Safe migration strategy for zero-downtime changes.
+
+## Safe Migration Strategy
+
+```
+For zero-downtime changes:
+│
+├── Adding column
+│   └── Add as nullable → backfill → add NOT NULL
+│
+├── Removing column
+│   └── Stop using → deploy → remove column
+│
+├── Adding index
+│   └── CREATE INDEX CONCURRENTLY (non-blocking)
+│
+└── Renaming column
+    └── Add new → migrate data → deploy → drop old
+```
+
+## Migration Philosophy
+
+- Never make breaking changes in one step
+- Test migrations on data copy first
+- Have rollback plan
+- Run in transaction when possible
+
+## Serverless Databases
+
+### Neon (Serverless PostgreSQL)
+
+| Feature | Benefit |
+|---------|---------|
+| Scale to zero | Cost savings |
+| Instant branching | Dev/preview |
+| Full PostgreSQL | Compatibility |
+| Autoscaling | Traffic handling |
+
+### Turso (Edge SQLite)
+
+| Feature | Benefit |
+|---------|---------|
+| Edge locations | Ultra-low latency |
+| SQLite compatible | Simple |
+| Generous free tier | Cost |
+| Global distribution | Performance |