@qazuor/claude-code-config 0.1.0

package/templates/skills/utils/add-memory.md

@@ -0,0 +1,295 @@
+---
+name: add-memory
+category: utils
+description: Capture and document learnings, decisions, patterns, and best practices for knowledge continuity
+usage: After making decisions, discovering patterns, solving problems, or establishing conventions
+input: Learning topic, decision rationale, pattern description, context
+output: Structured memory file in configured memory directory
+config_required:
+  - memory_path: "Path to memory storage directory"
+  - categories: "List of memory categories to use"
+  - index_file: "Path to memory index file"
+  - date_format: "Date format for file naming"
+---
+
+# Add Memory
+
+## ⚙️ Configuration
+
+| Setting | Description | Example |
+|---------|-------------|---------|
+| `memory_path` | Memory storage directory | `.claude/memory/`, `docs/decisions/` |
+| `categories` | Memory categories | `arch`, `patterns`, `gotchas`, `config` |
+| `index_file` | Index file location | `memory/INDEX.md` |
+| `date_format` | File naming date format | `YYYY-MM-DD` |
+| `auto_index` | Auto-update index | `true` |
+
+## Purpose
+
+Capture architectural decisions, patterns, gotchas, and best practices for future reference and knowledge continuity across the team.
+
+## Capabilities
+
+- Document architectural decisions with rationale
+- Record reusable code patterns
+- Capture configuration learnings
+- Track gotchas and solutions
+- Build searchable knowledge base
+
+## Memory Categories
+
+| Category | Purpose | Examples |
+|----------|---------|----------|
+| `arch/` | Architecture decisions | Tech stack, system design, integrations |
+| `patterns/` | Code patterns | RO-RO, base classes, factory patterns |
+| `config/` | Configuration | Environment setup, tool config |
+| `gotchas/` | Issues & solutions | Platform quirks, error fixes |
+| `performance/` | Optimizations | Caching, query optimization |
+| `security/` | Security patterns | Auth patterns, data protection |
+
+## Memory Template
+
+```markdown
+---
+topic: Brief topic name
+category: arch|patterns|config|gotchas|performance|security
+date: YYYY-MM-DD
+tags: [tag1, tag2, tag3]
+related: [file1.md, file2.md]
+---
+
+# Topic Title
+
+## Context
+
+When this is relevant and why it matters.
+
+## Decision/Learning
+
+What was decided or learned.
+
+## Rationale
+
+Why this approach was chosen over alternatives.
+
+## Alternatives Considered
+
+- **Option 1**: Description, pros/cons
+- **Option 2**: Description, pros/cons
+
+## Implementation
+
+How to implement this decision/pattern.
+
+### Example
+
+\`\`\`typescript
+// Code example demonstrating the pattern
+\`\`\`
+
+## Implications
+
+- Impact on system
+- Trade-offs accepted
+- Future considerations
+
+## References
+
+- Related documentation
+- External resources
+```
+
+## Example: Architectural Decision
+
+```markdown
+---
+topic: Monorepo with TurboRepo
+category: arch
+date: 2024-01-15
+tags: [monorepo, turborepo, build-system]
+---
+
+# Monorepo Structure with TurboRepo
+
+## Context
+
+Need to organize multiple apps and shared packages with code reuse.
+
+## Decision
+
+Adopt TurboRepo monorepo with apps/ and packages/ structure.
+
+## Rationale
+
+- Superior build caching (3x faster builds)
+- Parallel task execution
+- Simple configuration
+- Atomic commits across changes
+- Shared dependencies
+
+## Alternatives Considered
+
+- **Nx**: More features but steeper learning curve
+- **Lerna**: Less active development
+- **Separate repos**: Complex versioning
+
+## Implementation
+
+\`\`\`
+project/
+├── apps/          # Applications
+├── packages/      # Shared packages
+└── turbo.json     # Build pipeline
+\`\`\`
+
+## References
+
+- [TurboRepo Docs](https://turbo.build)
+```
+
+## Example: Pattern
+
+```markdown
+---
+topic: RO-RO Pattern
+category: patterns
+date: 2024-01-20
+tags: [pattern, function-design, maintainability]
+---
+
+# RO-RO Pattern (Receive Object, Return Object)
+
+## Context
+
+Functions with multiple parameters become hard to maintain.
+
+## Learning
+
+Always use object parameters and return objects.
+
+## Rationale
+
+- Easy to add parameters without breaking changes
+- Named parameters improve readability
+- Better TypeScript autocomplete
+- Easier to mock in tests
+
+## Implementation
+
+\`\`\`typescript
+// ❌ Bad
+function create(userId, itemId, quantity, notes) { }
+
+// ✅ Good
+interface CreateInput {
+  userId: string;
+  itemId: string;
+  quantity: number;
+  notes?: string;
+}
+
+interface CreateOutput {
+  item: Item;
+  success: boolean;
+}
+
+function create(input: CreateInput): CreateOutput { }
+\`\`\`
+```
+
+## Example: Gotcha
+
+```markdown
+---
+topic: Shell For Loop Limitation
+category: gotchas
+date: 2024-02-01
+tags: [shell, bash, fish]
+---
+
+# Fish Shell For Loop Limitation
+
+## Issue
+
+Fish shell hangs on bash-style for loops with no error message.
+
+## Solution
+
+Use alternatives:
+
+\`\`\`bash
+# ❌ Don't (hangs in Fish)
+for file in *.md; do echo $file; done
+
+# ✅ Do (works everywhere)
+find . -name "*.md" -exec echo {} \;
+\`\`\`
+
+## Prevention
+
+- Use find -exec for file operations
+- Create bash scripts for complex loops
+- Check shell type before commands
+```
+
+## Workflow
+
+### 1. Identify Type
+
+Choose appropriate category for the learning.
+
+### 2. Create File
+
+Use configured naming: `{memory_path}/{category}/{date}-{topic-slug}.md`
+
+### 3. Write Content
+
+Follow template structure with all sections.
+
+### 4. Update Index
+
+If `auto_index` enabled, index updates automatically. Otherwise:
+
+```markdown
+# Memory Index
+
+## Architectural Decisions
+
+| Date | Topic | Tags |
+|------|-------|------|
+| 2024-01-15 | [Monorepo Structure](arch/2024-01-15-monorepo.md) | monorepo, turborepo |
+
+## Patterns
+
+| Date | Topic | Tags |
+|------|-------|------|
+| 2024-01-20 | [RO-RO Pattern](patterns/2024-01-20-ro-ro.md) | pattern, functions |
+```
+
+### 5. Link Related
+
+Add cross-references to related memories.
+
+## Best Practices
+
+| Practice | Description |
+|----------|-------------|
+| **Be Specific** | Capture concrete decisions, not vague thoughts |
+| **Include Context** | Explain when and why this matters |
+| **Provide Examples** | Code examples are invaluable |
+| **Explain Rationale** | Why this over alternatives |
+| **Link Related** | Create knowledge graph |
+| **Use Tags** | Make memories searchable |
+| **Date Everything** | Track when decisions made |
+| **Review Regularly** | Update or archive outdated |
+
+## Checklist
+
+- [ ] Appropriate category selected
+- [ ] File named correctly with date
+- [ ] All template sections filled
+- [ ] Code examples provided
+- [ ] Rationale clearly explained
+- [ ] Tags added for searchability
+- [ ] Index updated
+- [ ] Related memories linked

package/templates/skills/utils/json-data-auditor.md

@@ -0,0 +1,283 @@
+---
+name: json-data-auditor
+category: utils
+description: Validate, transform, and audit JSON data for quality, consistency, and schema compliance
+usage: When validating API data, auditing database exports, transforming formats, or ensuring data quality
+input: JSON data, validation schemas, transformation rules, quality criteria
+output: Validation results, transformed data, quality reports, anomaly detection
+config_required:
+  - validation_library: "Schema validation library (Zod, Joi, AJV)"
+  - quality_threshold: "Minimum data quality score"
+  - required_fields: "Fields that must be present"
+  - anomaly_sensitivity: "Z-score threshold for outlier detection"
+---
+
+# JSON Data Auditor
+
+## ⚙️ Configuration
+
+| Setting | Description | Example |
+|---------|-------------|---------|
+| `validation_library` | Schema validator | `zod`, `joi`, `ajv` |
+| `quality_threshold` | Min quality score | `90` (0-100) |
+| `completeness_target` | Min completeness % | `95` |
+| `anomaly_z_score` | Outlier threshold | `3` (standard deviations) |
+| `max_duplicates` | Max allowed duplicates | `0` |
+| `required_fields` | Must-have fields | `['id', 'email', 'createdAt']` |
+
+## Purpose
+
+Validate, transform, and audit JSON data for quality, consistency, and schema compliance across APIs and databases.
+
+## Capabilities
+
+- Schema validation with detailed errors
+- Data quality metrics and scoring
+- Anomaly detection (outliers, nulls)
+- Data transformation and normalization
+- Comprehensive audit reporting
+- Format validation (email, UUID, dates)
+
+## Data Analysis
+
+### Structure Detection
+
+```typescript
+interface DataAnalysis {
+  totalRecords: number;
+  fields: Record<string, {
+    type: string;
+    nullable: boolean;
+    unique: boolean;
+    pattern: string;
+  }>;
+}
+
+function analyzeJSON(data: unknown[]): DataAnalysis {
+  // Detect types, patterns, uniqueness
+  // Return structure analysis
+}
+```
+
+### Pattern Recognition
+
+| Pattern | Detection |
+|---------|-----------|
+| Email | `/^[^\s@]+@[^\s@]+\.[^\s@]+$/` |
+| UUID | `/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i` |
+| Date | `!isNaN(Date.parse(value))` |
+| Phone | Country-specific patterns |
+
+## Schema Validation
+
+### With Zod
+
+```typescript
+import { z } from 'zod';
+
+const schema = z.object({
+  id: z.string().uuid(),
+  email: z.string().email(),
+  createdAt: z.string().datetime(),
+  status: z.enum(['active', 'inactive']),
+});
+
+interface ValidationResult {
+  valid: boolean;
+  errors: Array<{ path: string; message: string }>;
+  validRecords: number;
+  invalidRecords: number;
+}
+
+function validate(data: unknown[], schema: z.ZodSchema): ValidationResult {
+  // Validate each record
+  // Collect errors with paths
+  // Return summary
+}
+```
+
+## Quality Metrics
+
+### Completeness
+
+```typescript
+// Percentage of complete records (all required fields present)
+completeness = (completeRecords / totalRecords) * 100
+```
+
+### Uniqueness
+
+```typescript
+// Percentage of unique values per field
+uniqueness[field] = (uniqueValues / totalValues) * 100
+```
+
+### Validity
+
+```typescript
+// Percentage of values matching expected format
+validity[field] = (validValues / totalValues) * 100
+```
+
+### Quality Score
+
+```typescript
+score = 100
+  - (100 - completeness) * 0.4
+  - (100 - validity) * 0.4
+  - min(duplicates / 10, 10)
+  - min(anomalies / 5, 10)
+```
+
+## Anomaly Detection
+
+### Statistical Outliers
+
+```typescript
+// Z-score method for numeric fields
+const mean = values.reduce((sum, v) => sum + v, 0) / values.length;
+const variance = values.reduce((sum, v) => sum + (v - mean) ** 2, 0) / values.length;
+const stdDev = Math.sqrt(variance);
+const zScore = Math.abs((value - mean) / stdDev);
+
+// Flag if z-score > configured threshold (default: 3)
+if (zScore > config.anomaly_z_score) {
+  flagAsAnomaly();
+}
+```
+
+### Null Anomalies
+
+```typescript
+// Flag unexpected nulls (field usually not null but <10% nulls)
+const nullPercentage = (nullCount / totalRecords) * 100;
+if (nullPercentage > 0 && nullPercentage < 10) {
+  flagAsAnomaly();
+}
+```
+
+## Data Transformation
+
+### Field Mapping
+
+```typescript
+interface TransformRule {
+  source: string;
+  target: string;
+  transform?: (value: unknown) => unknown;
+}
+
+const rules: TransformRule[] = [
+  { source: 'user_id', target: 'userId' },
+  {
+    source: 'price',
+    target: 'priceInCents',
+    transform: (v) => Math.round((v as number) * 100)
+  },
+  {
+    source: 'created_at',
+    target: 'createdAt',
+    transform: (v) => new Date(v as string).toISOString()
+  }
+];
+```
+
+### Common Transformations
+
+```typescript
+// Snake case to camel case
+function snakeToCamel(obj: Record<string, unknown>): Record<string, unknown> {
+  return Object.fromEntries(
+    Object.entries(obj).map(([key, value]) => [
+      key.replace(/_([a-z])/g, (_, letter) => letter.toUpperCase()),
+      value
+    ])
+  );
+}
+
+// Flatten nested objects
+function flatten(obj: Record<string, unknown>, prefix = ''): Record<string, unknown> {
+  return Object.entries(obj).reduce((acc, [key, value]) => {
+    const newKey = prefix ? `${prefix}.${key}` : key;
+    if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+      return { ...acc, ...flatten(value as Record<string, unknown>, newKey) };
+    }
+    return { ...acc, [newKey]: value };
+  }, {});
+}
+```
+
+## Audit Report
+
+```typescript
+interface AuditReport {
+  summary: {
+    totalRecords: number;
+    validRecords: number;
+    qualityScore: number;
+  };
+  validation: {
+    errors: ValidationError[];
+  };
+  quality: {
+    completeness: number;
+    uniqueness: Record<string, number>;
+    validity: Record<string, number>;
+  };
+  anomalies: Anomaly[];
+  recommendations: string[];
+}
+```
+
+### Recommendations
+
+Generated based on findings:
+
+- Completeness < 95%: "Improve data completeness"
+- Duplicates found: "Remove N duplicate records"
+- Validation errors: "Fix N validation errors"
+- High-severity anomalies: "Investigate N critical anomalies"
+
+## Best Practices
+
+| Practice | Description |
+|----------|-------------|
+| **Schema First** | Define schemas for all data structures |
+| **Boundary Validation** | Validate at system boundaries (API, DB) |
+| **Track Metrics** | Monitor quality trends over time |
+| **Tune Thresholds** | Adjust anomaly detection for your data |
+| **Preserve Originals** | Never modify source data |
+| **Automate** | Run audits in CI/CD pipeline |
+| **Fix Root Cause** | Address quality at data source |
+
+## Usage Example
+
+```typescript
+import { auditJSON } from './json-auditor';
+
+const data = await fetchData();
+const schema = z.array(recordSchema);
+
+const report = await auditJSON(data, {
+  schema,
+  qualityThreshold: 90,
+  requiredFields: ['id', 'email', 'status'],
+  anomalyZScore: 3,
+});
+
+if (report.summary.qualityScore < 90) {
+  console.log('Quality issues found:');
+  report.recommendations.forEach(r => console.log(`- ${r}`));
+}
+```
+
+## Checklist
+
+- [ ] Schema defined for validation
+- [ ] Required fields configured
+- [ ] Quality thresholds set
+- [ ] Anomaly detection tuned
+- [ ] Validation errors addressed
+- [ ] Quality score above threshold
+- [ ] No critical anomalies
+- [ ] Recommendations reviewed