@agentskillkit/agent-skills 1.0.1

package/.agent/skills/code-reviewer/scripts/validate_doctrine.js

@@ -0,0 +1,307 @@
+#!/usr/bin/env node
+/**
+ * CoinPika Doctrine Validator
+ * 
+ * Validates a single file or directory against CoinPika doctrines.
+ * Usage: node validate_doctrine.js <path> [--doctrine <name>]
+ * 
+ * @version 1.1.0
+ * @author DataGuruIn
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// ============================================================================
+// DOCTRINE RULES
+// ============================================================================
+
+const DOCTRINE_RULES = {
+    'Law-1': {
+        name: 'Truth Ownership',
+        description: 'Backend owns financial truth. Frontend only displays.',
+        checks: [
+            {
+                pattern: /localStorage\.(set|get)Item.*(?:price|balance|portfolio)/gi,
+                message: 'Price/balance data should not be stored in localStorage',
+                suggestion: 'Fetch from backend API instead of caching in localStorage'
+            },
+            {
+                pattern: /const\s+(?:price|balance)\s*=\s*(?:useState|useReducer)/gi,
+                message: 'Financial state should originate from backend, not frontend',
+                suggestion: 'Use SWR/React Query to fetch from backend API'
+            },
+            {
+                pattern: /calculatePrice|computeBalance|derivePortfolioValue/gi,
+                message: 'Price calculations should happen on backend',
+                suggestion: 'Move calculation logic to backend API'
+            }
+        ]
+    },
+    'Law-2': {
+        name: 'Historical Integrity',
+        description: 'Historical data is append-only and immutable.',
+        checks: [
+            {
+                pattern: /history.*\.(push|splice|pop|shift|unshift)/gi,
+                message: 'Historical arrays should not be mutated',
+                suggestion: 'Create new array instead of mutating: [...history, newItem]'
+            },
+            {
+                pattern: /UPDATE.*SET.*WHERE.*(?:timestamp|date|created_at)/gi,
+                message: 'Historical records should not be updated',
+                suggestion: 'Insert correction record instead of updating'
+            },
+            {
+                pattern: /DELETE.*FROM.*(?:history|prices|candles)/gi,
+                message: 'Historical data should not be deleted',
+                suggestion: 'Mark as obsolete instead of deleting'
+            }
+        ]
+    },
+    'Law-3': {
+        name: 'Realtime Ephemerality',
+        description: 'Realtime data is ephemeral and separate from historical.',
+        checks: [
+            {
+                pattern: /websocket.*(?:history|historical).*push/gi,
+                message: 'WebSocket ticks should not be pushed to historical arrays',
+                suggestion: 'Store realtime in separate buffer, aggregate before persisting'
+            },
+            {
+                pattern: /chart.*data.*=.*(?:ws|websocket|socket)/gi,
+                message: 'Charts should not consume raw WebSocket feeds',
+                suggestion: 'Use aggregated historical API for chart data'
+            },
+            {
+                pattern: /setInterval.*(?:history|chart).*push/gi,
+                message: 'Interval-based pushes to history violate ephemerality',
+                suggestion: 'Backend should aggregate ticks into OHLCV candles'
+            }
+        ]
+    },
+    'Law-4': {
+        name: 'Chart Truthfulness',
+        description: 'Charts display pre-aggregated backend data only.',
+        checks: [
+            {
+                pattern: /candlestick.*(?:realtime|websocket|live)/gi,
+                message: 'Candlestick charts should not use realtime data',
+                suggestion: 'Load candlesticks from /api/historical endpoint'
+            },
+            {
+                pattern: /ohlc.*(?:push|update|modify)/gi,
+                message: 'OHLC data should be immutable on frontend',
+                suggestion: 'Refetch from API instead of modifying locally'
+            }
+        ]
+    },
+    'Architecture': {
+        name: 'Architecture Boundaries',
+        description: 'System boundaries must be respected.',
+        checks: [
+            {
+                pattern: /fetch\(['"`]https?:\/\/(?:api\.coingecko|api\.binance|api\.coinbase)/gi,
+                message: 'Frontend should not call external APIs directly',
+                suggestion: 'Create backend proxy endpoint for external API calls'
+            },
+            {
+                pattern: /process\.env\.(?:API_KEY|SECRET|PRIVATE)/gi,
+                message: 'Secrets should not be accessed in frontend code',
+                suggestion: 'Keep secrets server-side only'
+            }
+        ]
+    },
+    'Performance': {
+        name: 'Performance Standards',
+        description: 'Optimization and caching required.',
+        checks: [
+            {
+                pattern: /useEffect.*fetch.*\[\s*\]/gi,
+                message: 'Empty dependency array may cause stale data',
+                suggestion: 'Consider using SWR or React Query for data fetching'
+            },
+            {
+                pattern: /fetch\([^)]+\)(?!.*\.then.*cache)/gi,
+                message: 'API calls should consider caching strategy',
+                suggestion: 'Add cache headers or use SWR/React Query'
+            }
+        ]
+    },
+    'Frontend-Mobile': {
+        name: 'Mobile UX Standards',
+        description: 'Mobile-first, touch-friendly interfaces.',
+        checks: [
+            {
+                pattern: /overflow.*hidden.*scroll/gi,
+                message: 'Hidden overflow may break native scroll',
+                suggestion: 'Use overflow-y: auto instead of hidden'
+            },
+            {
+                pattern: /touchmove.*preventDefault/gi,
+                message: 'Blocking touchmove breaks native scroll',
+                suggestion: 'Only preventDefault on intentional gestures'
+            }
+        ]
+    }
+};
+
+// ============================================================================
+// VALIDATION
+// ============================================================================
+
+function validateContent(content, filePath, targetDoctrines = null) {
+    const results = [];
+    const lines = content.split('\n');
+
+    const doctrinesToCheck = targetDoctrines
+        ? Object.entries(DOCTRINE_RULES).filter(([k]) => targetDoctrines.includes(k))
+        : Object.entries(DOCTRINE_RULES);
+
+    for (const [doctrineId, doctrine] of doctrinesToCheck) {
+        for (const check of doctrine.checks) {
+            for (let i = 0; i < lines.length; i++) {
+                const line = lines[i];
+                if (check.pattern.test(line)) {
+                    results.push({
+                        doctrine: doctrineId,
+                        doctrineName: doctrine.name,
+                        file: filePath,
+                        line: i + 1,
+                        message: check.message,
+                        suggestion: check.suggestion,
+                        code: line.trim().substring(0, 100)
+                    });
+                    // Reset regex lastIndex for global patterns
+                    check.pattern.lastIndex = 0;
+                }
+            }
+        }
+    }
+
+    return results;
+}
+
+function validateFile(filePath, targetDoctrines = null) {
+    if (!fs.existsSync(filePath)) {
+        console.error(`❌ File not found: ${filePath}`);
+        return [];
+    }
+
+    const content = fs.readFileSync(filePath, 'utf8');
+    return validateContent(content, filePath, targetDoctrines);
+}
+
+function validateDirectory(dirPath, targetDoctrines = null) {
+    const results = [];
+
+    function walkDir(dir) {
+        const files = fs.readdirSync(dir);
+        for (const file of files) {
+            const fullPath = path.join(dir, file);
+            const stat = fs.statSync(fullPath);
+
+            if (stat.isDirectory()) {
+                if (!file.startsWith('.') && file !== 'node_modules') {
+                    walkDir(fullPath);
+                }
+            } else if (/\.(js|ts|tsx|jsx|mjs)$/.test(file)) {
+                results.push(...validateFile(fullPath, targetDoctrines));
+            }
+        }
+    }
+
+    walkDir(dirPath);
+    return results;
+}
+
+// ============================================================================
+// OUTPUT
+// ============================================================================
+
+function printResults(results) {
+    if (results.length === 0) {
+        console.log('\n✅ No doctrine violations found!\n');
+        return;
+    }
+
+    console.log(`\n🔍 Found ${results.length} potential doctrine violation(s):\n`);
+
+    results.forEach((r, i) => {
+        console.log(`${i + 1}. [${r.doctrine}] ${r.doctrineName}`);
+        console.log(`   📍 ${r.file}:${r.line}`);
+        console.log(`   ⚠️  ${r.message}`);
+        console.log(`   💡 ${r.suggestion}`);
+        console.log(`   📝 ${r.code}...`);
+        console.log('');
+    });
+}
+
+// ============================================================================
+// CLI
+// ============================================================================
+
+function printHelp() {
+    console.log(`
+CoinPika Doctrine Validator v1.1.0
+
+USAGE:
+  node validate_doctrine.js <path> [OPTIONS]
+
+OPTIONS:
+  --doctrine <name>   Check specific doctrine only (Law-1, Law-2, etc.)
+  --json              Output as JSON
+  --help              Show this help
+
+DOCTRINES:
+  Law-1        Truth Ownership
+  Law-2        Historical Integrity
+  Law-3        Realtime Ephemerality
+  Law-4        Chart Truthfulness
+  Architecture System Boundaries
+  Performance  Caching & Optimization
+  Frontend-Mobile  Mobile UX
+
+EXAMPLES:
+  node validate_doctrine.js src/components/Chart.tsx
+  node validate_doctrine.js src/ --doctrine Law-3
+  node validate_doctrine.js . --json
+`);
+}
+
+function main() {
+    const args = process.argv.slice(2);
+
+    if (args.includes('--help') || args.length === 0) {
+        printHelp();
+        process.exit(0);
+    }
+
+    const targetPath = args[0];
+    const jsonOutput = args.includes('--json');
+    let targetDoctrines = null;
+
+    if (args.includes('--doctrine')) {
+        const idx = args.indexOf('--doctrine');
+        targetDoctrines = [args[idx + 1]];
+    }
+
+    let results;
+    const stat = fs.statSync(targetPath);
+
+    if (stat.isDirectory()) {
+        results = validateDirectory(targetPath, targetDoctrines);
+    } else {
+        results = validateFile(targetPath, targetDoctrines);
+    }
+
+    if (jsonOutput) {
+        console.log(JSON.stringify({ violations: results, count: results.length }, null, 2));
+    } else {
+        printResults(results);
+    }
+
+    process.exit(results.length > 0 ? 1 : 0);
+}
+
+main();

package/.agent/skills/context-engineering/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: context-engineering
+description: >-
+  Master context engineering for AI agent systems. Use when designing agent architectures,
+  debugging context failures, optimizing token usage, implementing memory systems,
+  building multi-agent coordination, evaluating agent performance, or developing
+  LLM-powered pipelines. Covers context fundamentals, degradation patterns, optimization
+  techniques (compaction, masking, caching), compression strategies, memory architectures,
+  multi-agent patterns, LLM-as-Judge evaluation, tool design, and project development.
+version: 1.0.0
+---
+
+# Context Engineering
+
+Context engineering curates the smallest high-signal token set for LLM tasks. The goal: maximize reasoning quality while minimizing token usage.
+
+## When to Activate
+
+- Designing/debugging agent systems
+- Context limits constrain performance
+- Optimizing cost/latency
+- Building multi-agent coordination
+- Implementing memory systems
+- Evaluating agent performance
+- Developing LLM-powered pipelines
+
+## Core Principles
+
+1. **Context quality > quantity** - High-signal tokens beat exhaustive content
+2. **Attention is finite** - U-shaped curve favors beginning/end positions
+3. **Progressive disclosure** - Load information just-in-time
+4. **Isolation prevents degradation** - Partition work across sub-agents
+5. **Measure before optimizing** - Know your baseline
+
+## Quick Reference
+
+| Topic | When to Use | Reference |
+|-------|-------------|-----------|
+| **Fundamentals** | Understanding context anatomy, attention mechanics | [context-fundamentals.md](./references/context-fundamentals.md) |
+| **Degradation** | Debugging failures, lost-in-middle, poisoning | [context-degradation.md](./references/context-degradation.md) |
+| **Optimization** | Compaction, masking, caching, partitioning | [context-optimization.md](./references/context-optimization.md) |
+| **Compression** | Long sessions, summarization strategies | [context-compression.md](./references/context-compression.md) |
+| **Memory** | Cross-session persistence, knowledge graphs | [memory-systems.md](./references/memory-systems.md) |
+| **Multi-Agent** | Coordination patterns, context isolation | [multi-agent-patterns.md](./references/multi-agent-patterns.md) |
+| **Evaluation** | Testing agents, LLM-as-Judge, metrics | [evaluation.md](./references/evaluation.md) |
+| **Tool Design** | Tool consolidation, description engineering | [tool-design.md](./references/tool-design.md) |
+| **Pipelines** | Project development, batch processing | [project-development.md](./references/project-development.md) |
+
+## Key Metrics
+
+- **Token utilization**: Warning at 70%, trigger optimization at 80%
+- **Token variance**: Explains 80% of agent performance variance
+- **Multi-agent cost**: ~15x single agent baseline
+- **Compaction target**: 50-70% reduction, <5% quality loss
+- **Cache hit target**: 70%+ for stable workloads
+
+## Four-Bucket Strategy
+
+1. **Write**: Save context externally (scratchpads, files)
+2. **Select**: Pull only relevant context (retrieval, filtering)
+3. **Compress**: Reduce tokens while preserving info (summarization)
+4. **Isolate**: Split across sub-agents (partitioning)
+
+## Anti-Patterns
+
+- Exhaustive context over curated context
+- Critical info in middle positions
+- No compaction triggers before limits
+- Single agent for parallelizable tasks
+- Tools without clear descriptions
+
+## Guidelines
+
+1. Place critical info at beginning/end of context
+2. Implement compaction at 70-80% utilization
+3. Use sub-agents for context isolation, not role-play
+4. Design tools with 4-question framework (what, when, inputs, returns)
+5. Optimize for tokens-per-task, not tokens-per-request
+6. Validate with probe-based evaluation
+7. Monitor KV-cache hit rates in production
+8. Start minimal, add complexity only when proven necessary
+
+## Scripts
+
+- [context_analyzer.py](./scripts/context_analyzer.py) - Context health analysis, degradation detection
+- [compression_evaluator.py](./scripts/compression_evaluator.py) - Compression quality evaluation

package/.agent/skills/context-engineering/references/context-compression.md

@@ -0,0 +1,84 @@
+# Context Compression
+
+Strategies for long-running sessions exceeding context windows.
+
+## Core Insight
+
+Optimize **tokens-per-task** (total to completion), not tokens-per-request.
+Aggressive compression causing re-fetching costs more than better retention.
+
+## Compression Methods
+
+| Method | Compression | Quality | Best For |
+|--------|-------------|---------|----------|
+| **Anchored Iterative** | 98.6% | 3.70/5 | Best balance |
+| **Regenerative Full** | 98.7% | 3.44/5 | Readability |
+| **Opaque** | 99.3% | 3.35/5 | Max compression |
+
+## Anchored Iterative Summary Template
+
+```markdown
+## Session Intent
+Original goal: [preserved]
+
+## Files Modified
+- file.py: Changes made
+
+## Decisions Made
+- Key decisions with rationale
+
+## Current State
+Progress summary
+
+## Next Steps
+1. Next action items
+```
+
+**On compression**: Merge new content into existing sections, don't regenerate.
+
+## Compression Triggers
+
+| Strategy | Trigger | Use Case |
+|----------|---------|----------|
+| Fixed threshold | 70-80% utilization | General purpose |
+| Sliding window | Keep last N turns + summary | Conversations |
+| Task-boundary | At logical completion | Multi-step workflows |
+
+## Artifact Trail Problem
+
+Weakest dimension (2.2-2.5/5.0). Coding agents need explicit tracking of:
+- Files created/modified/read
+- Function/variable names, error messages
+
+**Solution**: Dedicated artifact section in summary.
+
+## Probe-Based Evaluation
+
+| Probe Type | Tests | Example |
+|------------|-------|---------|
+| Recall | Factual retention | "What was the error?" |
+| Artifact | File tracking | "Which files modified?" |
+| Continuation | Task planning | "What next?" |
+| Decision | Reasoning chains | "Why chose X?" |
+
+## Six Evaluation Dimensions
+
+1. **Accuracy** - Technical correctness
+2. **Context Awareness** - Conversation state
+3. **Artifact Trail** - File tracking (universally weak)
+4. **Completeness** - Coverage depth
+5. **Continuity** - Work continuation
+6. **Instruction Following** - Constraints
+
+## Guidelines
+
+1. Use anchored iterative for best quality/compression
+2. Maintain explicit artifact tracking section
+3. Trigger compression at 70% utilization
+4. Merge into sections, don't regenerate
+5. Evaluate with probes, not lexical metrics
+
+## Related
+
+- [Context Optimization](./context-optimization.md)
+- [Evaluation](./evaluation.md)

package/.agent/skills/context-engineering/references/context-degradation.md

@@ -0,0 +1,93 @@
+# Context Degradation Patterns
+
+Predictable degradation as context grows. Not binary - a continuum.
+
+## Degradation Patterns
+
+| Pattern | Cause | Detection |
+|---------|-------|-----------|
+| **Lost-in-Middle** | U-shaped attention | Critical info recall drops 10-40% |
+| **Context Poisoning** | Errors compound via reference | Persistent hallucinations despite correction |
+| **Context Distraction** | Irrelevant info overwhelms | Single distractor degrades performance |
+| **Context Confusion** | Multiple tasks mix | Wrong tool calls, mixed requirements |
+| **Context Clash** | Contradictory info | Conflicting outputs, inconsistent reasoning |
+
+## Lost-in-Middle Phenomenon
+
+- Information in middle gets 10-40% lower recall
+- Models allocate massive attention to first token (BOS sink)
+- As context grows, middle tokens fail to get sufficient attention
+- **Mitigation**: Place critical info at beginning/end
+
+```markdown
+[CURRENT TASK]              # Beginning - high attention
+- Critical requirements
+
+[DETAILED CONTEXT]          # Middle - lower attention
+- Supporting details
+
+[KEY FINDINGS]              # End - high attention
+- Important conclusions
+```
+
+## Context Poisoning
+
+**Entry points**:
+1. Tool outputs with errors/unexpected formats
+2. Retrieved docs with incorrect/outdated info
+3. Model-generated summaries with hallucinations
+
+**Detection symptoms**:
+- Degraded quality on previously successful tasks
+- Tool misalignment (wrong tools/parameters)
+- Persistent hallucinations
+
+**Recovery**:
+- Truncate to before poisoning point
+- Explicit note + re-evaluation request
+- Restart with clean context, preserve only verified info
+
+## Model Degradation Thresholds
+
+| Model | Degradation Onset | Severe Degradation |
+|-------|-------------------|-------------------|
+| GPT-5.2 | ~64K tokens | ~200K tokens |
+| Claude Opus 4.5 | ~100K tokens | ~180K tokens |
+| Claude Sonnet 4.5 | ~80K tokens | ~150K tokens |
+| Gemini 3 Pro | ~500K tokens | ~800K tokens |
+
+## Four-Bucket Mitigation
+
+1. **Write**: Save externally (scratchpads, files)
+2. **Select**: Pull only relevant (retrieval, filtering)
+3. **Compress**: Reduce tokens (summarization)
+4. **Isolate**: Split across sub-agents (partitioning)
+
+## Detection Heuristics
+
+```python
+def calculate_health(utilization, degradation_risk, poisoning_risk):
+    """Health score: 1.0 = healthy, 0.0 = critical"""
+    score = 1.0
+    score -= utilization * 0.5 if utilization > 0.7 else 0
+    score -= degradation_risk * 0.3
+    score -= poisoning_risk * 0.2
+    return max(0, score)
+
+# Thresholds: healthy >0.8, warning >0.6, degraded >0.4, critical <=0.4
+```
+
+## Guidelines
+
+1. Monitor context length vs performance correlation
+2. Place critical info at beginning/end
+3. Implement compaction before degradation
+4. Validate retrieved docs before adding
+5. Use versioning to prevent outdated clash
+6. Segment tasks to prevent confusion
+7. Design for graceful degradation
+
+## Related Topics
+
+- [Context Optimization](./context-optimization.md) - Mitigation techniques
+- [Multi-Agent Patterns](./multi-agent-patterns.md) - Isolation strategies

package/.agent/skills/context-engineering/references/context-fundamentals.md

@@ -0,0 +1,75 @@
+# Context Fundamentals
+
+Context = all input provided to LLM for task completion.
+
+## Anatomy of Context
+
+| Component | Purpose | Token Impact |
+|-----------|---------|--------------|
+| System Prompt | Identity, constraints, guidelines | Stable, cacheable |
+| Tool Definitions | Action specs with params/returns | Grows with capabilities |
+| Retrieved Docs | Domain knowledge, just-in-time | Variable, selective |
+| Message History | Conversation state, task progress | Accumulates over time |
+| Tool Outputs | Results from actions | 83.9% of typical context |
+
+## Attention Mechanics
+
+- **U-shaped curve**: Beginning/end get more attention than middle
+- **Attention budget**: n^2 relationships for n tokens depletes with growth
+- **Position encoding**: Interpolation allows longer sequences with degradation
+- **First-token sink**: BOS token absorbs large attention budget
+
+## System Prompt Structure
+
+```xml
+<BACKGROUND_INFORMATION>Domain knowledge, role definition</BACKGROUND_INFORMATION>
+<INSTRUCTIONS>Step-by-step procedures</INSTRUCTIONS>
+<TOOL_GUIDANCE>When/how to use tools</TOOL_GUIDANCE>
+<OUTPUT_DESCRIPTION>Format requirements</OUTPUT_DESCRIPTION>
+```
+
+## Progressive Disclosure Levels
+
+1. **Metadata** (~100 words) - Always in context
+2. **SKILL.md body** (<5k words) - When skill triggers
+3. **Bundled resources** (Unlimited) - As needed
+
+## Token Budget Allocation
+
+| Component | Typical Range | Notes |
+|-----------|---------------|-------|
+| System Prompt | 500-2000 | Stable, optimize once |
+| Tool Definitions | 100-500 per tool | Keep under 20 tools |
+| Retrieved Docs | 1000-5000 | Selective loading |
+| Message History | Variable | Summarize at 70% |
+| Reserved Buffer | 10-20% | For responses |
+
+## Document Management
+
+**Strong identifiers**: `customer_pricing_rates.json` not `data/file1.json`
+**Chunk at semantic boundaries**: Paragraphs, sections, not arbitrary lengths
+**Include metadata**: Source, date, relevance score
+
+## Message History Pattern
+
+```python
+# Summary injection every 20 messages
+if len(messages) % 20 == 0:
+    summary = summarize_conversation(messages[-20:])
+    messages.append({"role": "system", "content": f"Summary: {summary}"})
+```
+
+## Guidelines
+
+1. Treat context as finite with diminishing returns
+2. Place critical info at attention-favored positions
+3. Use file-system-based access for large documents
+4. Pre-load stable content, just-in-time load dynamic
+5. Design with explicit token budgets
+6. Monitor usage, implement compaction triggers at 70-80%
+
+## Related Topics
+
+- [Context Degradation](./context-degradation.md) - Failure patterns
+- [Context Optimization](./context-optimization.md) - Efficiency techniques
+- [Memory Systems](./memory-systems.md) - External storage