@agentskillkit/agent-skills 1.0.1

package/.agent/skills/governance/scripts/learn.js

@@ -0,0 +1,161 @@
+#!/usr/bin/env node
+/**
+ * My Agent Skill Learning Script
+ * 
+ * The "Teacher" script. Adds new lessons to the system memory.
+ * Usage: node learn.js --add --pattern "regex" --message "why bad"
+ * 
+ * @version 1.0.0
+ * @author MyAgentSkill
+ */
+
+const fs = require('fs');
+const path = require('path');
+const yaml = require('js-yaml');
+
+// ============================================================================
+// CONFIGURATION
+// ============================================================================
+
+// Prioritize user's project root for persistence, fallback to local skill folder for defaults
+const USER_KNOWLEDGE_PATH = path.join(process.cwd(), '.myagentskill', 'knowledge', 'lessons-learned.yaml');
+const INTERNAL_KNOWLEDGE_PATH = path.join(__dirname, '..', 'knowledge', 'lessons-learned.yaml');
+
+// We always write to the USER path to ensure persistence
+const KNOWLEDGE_PATH = USER_KNOWLEDGE_PATH;
+
+// ============================================================================
+// CORE FUNCTIONS
+// ============================================================================
+
+function loadKnowledge() {
+    try {
+        if (!fs.existsSync(KNOWLEDGE_PATH)) {
+            // Create if missing
+            const initial = { lessons: [] };
+            fs.mkdirSync(path.dirname(KNOWLEDGE_PATH), { recursive: true });
+            fs.writeFileSync(KNOWLEDGE_PATH, yaml.dump(initial), 'utf8');
+            return initial;
+        }
+        const content = fs.readFileSync(KNOWLEDGE_PATH, 'utf8');
+        return yaml.load(content) || { lessons: [] };
+    } catch (error) {
+        console.error('❌ Failed to load knowledge base:', error.message);
+        process.exit(1);
+    }
+}
+
+function saveKnowledge(data) {
+    try {
+        const str = yaml.dump(data, { lineWidth: -1 });
+        fs.writeFileSync(KNOWLEDGE_PATH, str, 'utf8');
+        console.log('✅ Knowledge base updated successfully.');
+    } catch (error) {
+        console.error('❌ Failed to save knowledge base:', error.message);
+        process.exit(1);
+    }
+}
+
+function addLesson(pattern, message, severity = 'WARNING') {
+    const db = loadKnowledge();
+
+    // Validate Regex
+    try {
+        new RegExp(pattern);
+    } catch (e) {
+        console.error('❌ Invalid Regex pattern:', e.message);
+        process.exit(1);
+    }
+
+    const id = `LEARN-${String(db.lessons.length + 1).padStart(3, '0')}`;
+
+    const lesson = {
+        id,
+        pattern,
+        message,
+        severity,
+        addedAt: new Date().toISOString()
+    };
+
+    db.lessons.push(lesson);
+    saveKnowledge(db);
+
+    console.log(`\n🎓 Lesson Learned: [${id}]`);
+    console.log(`   Pattern: /${pattern}/`);
+    console.log(`   Message: ${message}`);
+    console.log('\nP.S. ⚡ Knowledge captured by My Agent Skill Learning Engine');
+}
+
+function listLessons() {
+    const db = loadKnowledge();
+    if (db.lessons.length === 0) {
+        console.log('ℹ️  No lessons learned yet.');
+        return;
+    }
+
+    console.log('\n🧠 My Agent Skill Knowledge Base:\n');
+    db.lessons.forEach(l => {
+        console.log(`  [${l.id}] /${l.pattern}/ -> ${l.message} (${l.severity})`);
+    });
+    console.log('');
+}
+
+// ============================================================================
+// CLI
+// ============================================================================
+
+function printHelp() {
+    console.log(`
+My Agent Skill Learning Tool v1.0.0
+
+USAGE:
+  node learn.js --add --pattern "..." --message "..."
+  node learn.js --list
+  node learn.js --help
+
+OPTIONS:
+  --add       Add a new lesson
+  --pattern   Regex pattern to flag
+  --message   Explanation message
+  --severity  Severity (WARNING/ERROR), default WARNING
+  --list      List all learned lessons
+`);
+}
+
+function main() {
+    const args = process.argv.slice(2);
+
+    if (args.includes('--help') || args.length === 0) {
+        printHelp();
+        process.exit(0);
+    }
+
+    if (args.includes('--list')) {
+        listLessons();
+        process.exit(0);
+    }
+
+    if (args.includes('--add')) {
+        const pIdx = args.indexOf('--pattern');
+        const mIdx = args.indexOf('--message');
+        const sIdx = args.indexOf('--severity');
+
+        if (pIdx === -1 || mIdx === -1) {
+            console.error('❌ --pattern and --message are required for --add');
+            process.exit(1);
+        }
+
+        const pattern = args[pIdx + 1];
+        const message = args[mIdx + 1];
+        const severity = sIdx !== -1 ? args[sIdx + 1] : 'WARNING';
+
+        if (!pattern || !message) {
+            console.error('❌ Missing values for pattern/message');
+            process.exit(1);
+        }
+
+        addLesson(pattern, message, severity);
+    }
+}
+
+main();

package/.agent/skills/governance/scripts/validate_doctrine.js

@@ -0,0 +1,286 @@
+#!/usr/bin/env node
+/**
+ * CoinPika Doctrine Validator
+ * 
+ * Validates code files against CoinPika Architecture Doctrine
+ * 
+ * Usage:
+ *   node scripts/validate_doctrine.js <file-path>
+ *   node scripts/validate_doctrine.js --dir <directory>
+ * 
+ * Exit codes:
+ *   0 = All checks passed
+ *   1 = Violations found
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// Colors for output
+const colors = {
+    reset: '\x1b[0m',
+    red: '\x1b[31m',
+    green: '\x1b[32m',
+    yellow: '\x1b[33m',
+    cyan: '\x1b[36m',
+    dim: '\x1b[2m',
+};
+
+class DoctrineValidator {
+    constructor(filepath) {
+        this.filepath = filepath;
+        this.content = fs.readFileSync(filepath, 'utf-8');
+        this.errors = [];
+        this.warnings = [];
+        this.info = [];
+    }
+
+    // Law 1: Backend is source of truth
+    checkTruthOwnership() {
+        const violations = [];
+
+        // Check for frontend managing financial data
+        if (this.content.match(/localStorage\.setItem.*price|localStorage\.setItem.*balance|localStorage\.setItem.*portfolio/i)) {
+            violations.push({
+                law: 'Law 1: Truth Ownership',
+                severity: 'ERROR',
+                message: 'Frontend persisting financial data to localStorage',
+                doctrine: 'constitution/coinpika-master-constitution.md',
+                line: this.findLineNumber(/localStorage\.setItem.*price|localStorage\.setItem.*balance/i),
+            });
+        }
+
+        // Check for frontend calling external APIs directly (production code)
+        if (this.content.match(/fetch\(['"]https:\/\/api\.(coingecko|binance|coinbase)/i) &&
+            !this.filepath.includes('test') &&
+            !this.filepath.includes('example')) {
+            violations.push({
+                law: 'Law 1: Truth Ownership',
+                severity: 'ERROR',
+                message: 'Frontend calling external API directly (should go through backend)',
+                doctrine: 'doctrines/architecture/coinpika-architecture-doctrine.md',
+                line: this.findLineNumber(/fetch\(['"]https:\/\/api\./i),
+            });
+        }
+
+        // Check for frontend calculating aggregates
+        if (this.content.match(/\.reduce\([^)]*avg|\.reduce\([^)]*mean|Math\.average/i) &&
+            this.content.match(/price|balance|volume/i)) {
+            violations.push({
+                law: 'Law 1: Truth Ownership',
+                severity: 'WARNING',
+                message: 'Frontend calculating financial aggregates (consider moving to backend)',
+                doctrine: 'doctrines/backend/coinpika-backend-data-engine-doctrine.md',
+                line: this.findLineNumber(/\.reduce/i),
+            });
+        }
+
+        return violations;
+    }
+
+    // Law 2: Historical data immutability
+    checkHistoricalImmutability() {
+        const violations = [];
+
+        // Check for array mutation methods
+        const mutationMethods = ['.splice(', '.shift(', '.pop(', '.push(', '.unshift('];
+        const historyPatterns = ['history', 'chart', 'candle', 'ohlc', 'sparkline'];
+
+        for (const method of mutationMethods) {
+            for (const pattern of historyPatterns) {
+                const regex = new RegExp(`${pattern}[^\\n]*${method.replace('(', '\\(')}`, 'i');
+                if (this.content.match(regex)) {
+                    violations.push({
+                        law: 'Law 2: Historical Integrity',
+                        severity: 'ERROR',
+                        message: `Array mutation detected on historical data: ${method}`,
+                        doctrine: 'constitution/coinpika-master-constitution.md',
+                        line: this.findLineNumber(regex),
+                    });
+                }
+            }
+        }
+
+        // Check for direct object mutation
+        if (this.content.match(/\.(data|history|candles)\[.*\]\s*=/)) {
+            violations.push({
+                law: 'Law 2: Historical Integrity',
+                severity: 'ERROR',
+                message: 'Direct mutation of historical data array index',
+                doctrine: 'constitution/coinpika-master-constitution.md',
+                line: this.findLineNumber(/\.(data|history|candles)\[.*\]\s*=/),
+            });
+        }
+
+        return violations;
+    }
+
+    // Law 3: Realtime ephemerality
+    checkRealtimeEphemerality() {
+        const violations = [];
+
+        // Check for websocket data being added to charts
+        if (this.content.match(/websocket|ws\.on|socket\.on/i) &&
+            this.content.match(/\.update\(|\.setData\(|\.addTo/i) &&
+            this.content.match(/chart|series|candle/i)) {
+            violations.push({
+                law: 'Law 3: Realtime Ephemerality',
+                severity: 'ERROR',
+                message: 'Potential realtime data injection into chart detected',
+                doctrine: 'constitution/coinpika-master-constitution.md',
+                line: this.findLineNumber(/\.update\(|\.setData\(/i),
+            });
+        }
+
+        // Check for persisting websocket data
+        if (this.content.match(/websocket|ws\.on/i) &&
+            this.content.match(/\.create\(|\.insert\(|\.save\(/i)) {
+            violations.push({
+                law: 'Law 3: Realtime Ephemerality',
+                severity: 'WARNING',
+                message: 'Realtime data being persisted (ensure proper aggregation)',
+                doctrine: 'doctrines/data/coinpika-chart-data-doctrine.md',
+                line: this.findLineNumber(/\.create\(|\.insert\(/i),
+            });
+        }
+
+        return violations;
+    }
+
+    // Architecture: System boundaries
+    checkSystemBoundaries() {
+        const violations = [];
+
+        // Check for frontend importing backend code
+        if (this.content.match(/from ['"]@\/(?:lib|api|db|server)/i) &&
+            this.filepath.match(/components|pages|app\/.*\.(tsx?|jsx?)$/)) {
+            violations.push({
+                law: 'System Boundary Law',
+                severity: 'WARNING',
+                message: 'Frontend importing backend modules (check dependency direction)',
+                doctrine: 'doctrines/architecture/coinpika-architecture-doctrine.md',
+                line: this.findLineNumber(/from ['"]@\/(?:lib|api|db)/i),
+            });
+        }
+
+        return violations;
+    }
+
+    // Performance: Caching
+    checkCachingStrategy() {
+        const info = [];
+
+        // Check if API route has caching
+        if (this.filepath.match(/api\/.*\.(ts|js)$/) &&
+            !this.content.match(/Cache-Control|stale-while-revalidate|redis|kv/i)) {
+            info.push({
+                law: 'Performance Doctrine',
+                severity: 'INFO',
+                message: 'API route may benefit from caching strategy',
+                doctrine: 'doctrines/performance/coinpika-performance-doctrine.md',
+            });
+        }
+
+        return info;
+    }
+
+    findLineNumber(regex) {
+        const lines = this.content.split('\n');
+        for (let i = 0; i < lines.length; i++) {
+            if (lines[i].match(regex)) {
+                return i + 1;
+            }
+        }
+        return null;
+    }
+
+    validate() {
+        this.errors = [
+            ...this.checkTruthOwnership(),
+            ...this.checkHistoricalImmutability(),
+            ...this.checkRealtimeEphemerality(),
+            ...this.checkSystemBoundaries(),
+        ];
+
+        this.info = [
+            ...this.checkCachingStrategy(),
+        ];
+
+        return {
+            errors: this.errors.filter(v => v.severity === 'ERROR'),
+            warnings: this.errors.filter(v => v.severity === 'WARNING'),
+            info: this.info,
+        };
+    }
+
+    report() {
+        const results = this.validate();
+        const hasIssues = results.errors.length > 0 || results.warnings.length > 0;
+
+        console.log('\n' + colors.cyan + '═'.repeat(70) + colors.reset);
+        console.log(colors.cyan + `CoinPika Doctrine Validator` + colors.reset);
+        console.log(colors.dim + `File: ${this.filepath}` + colors.reset);
+        console.log(colors.cyan + '═'.repeat(70) + colors.reset + '\n');
+
+        if (results.errors.length > 0) {
+            console.log(colors.red + `❌ ${results.errors.length} ERROR(S) FOUND\n` + colors.reset);
+            results.errors.forEach((error, i) => {
+                console.log(colors.red + `[${i + 1}] ${error.law}` + colors.reset);
+                console.log(`    ${error.message}`);
+                if (error.line) console.log(colors.dim + `    Line ${error.line}` + colors.reset);
+                console.log(colors.dim + `    Source: ${error.doctrine}` + colors.reset);
+                console.log();
+            });
+        }
+
+        if (results.warnings.length > 0) {
+            console.log(colors.yellow + `⚠️  ${results.warnings.length} WARNING(S) FOUND\n` + colors.reset);
+            results.warnings.forEach((warning, i) => {
+                console.log(colors.yellow + `[${i + 1}] ${warning.law}` + colors.reset);
+                console.log(`    ${warning.message}`);
+                if (warning.line) console.log(colors.dim + `    Line ${warning.line}` + colors.reset);
+                console.log(colors.dim + `    Source: ${warning.doctrine}` + colors.reset);
+                console.log();
+            });
+        }
+
+        if (results.info.length > 0) {
+            console.log(colors.cyan + `ℹ️  ${results.info.length} SUGGESTION(S)\n` + colors.reset);
+            results.info.forEach((info, i) => {
+                console.log(colors.cyan + `[${i + 1}] ${info.law}` + colors.reset);
+                console.log(`    ${info.message}`);
+                console.log(colors.dim + `    Source: ${info.doctrine}` + colors.reset);
+                console.log();
+            });
+        }
+
+        if (!hasIssues && results.info.length === 0) {
+            console.log(colors.green + `✅ All doctrine checks passed!` + colors.reset + '\n');
+        }
+
+        console.log(colors.cyan + '═'.repeat(70) + colors.reset + '\n');
+
+        return results.errors.length > 0 ? 1 : 0;
+    }
+}
+
+// Main execution
+const filepath = process.argv[2];
+
+if (!filepath) {
+    console.error('Usage: node validate_doctrine.js <file-path>');
+    process.exit(1);
+}
+
+if (!fs.existsSync(filepath)) {
+    console.error(`Error: File not found: ${filepath}`);
+    process.exit(1);
+}
+
+const validator = new DoctrineValidator(filepath);
+const exitCode = validator.report();
+process.exit(exitCode);

package/.agent/skills/i18n-localization/SKILL.md

@@ -0,0 +1,154 @@
+---
+name: i18n-localization
+description: Internationalization and localization patterns. Detecting hardcoded strings, managing translations, locale files, RTL support.
+allowed-tools: Read, Glob, Grep
+---
+
+# i18n & Localization
+
+> Internationalization (i18n) and Localization (L10n) best practices.
+
+---
+
+## 1. Core Concepts
+
+| Term | Meaning |
+|------|---------|
+| **i18n** | Internationalization - making app translatable |
+| **L10n** | Localization - actual translations |
+| **Locale** | Language + Region (en-US, tr-TR) |
+| **RTL** | Right-to-left languages (Arabic, Hebrew) |
+
+---
+
+## 2. When to Use i18n
+
+| Project Type | i18n Needed? |
+|--------------|--------------|
+| Public web app | ✅ Yes |
+| SaaS product | ✅ Yes |
+| Internal tool | ⚠️ Maybe |
+| Single-region app | ⚠️ Consider future |
+| Personal project | ❌ Optional |
+
+---
+
+## 3. Implementation Patterns
+
+### React (react-i18next)
+
+```tsx
+import { useTranslation } from 'react-i18next';
+
+function Welcome() {
+  const { t } = useTranslation();
+  return <h1>{t('welcome.title')}</h1>;
+}
+```
+
+### Next.js (next-intl)
+
+```tsx
+import { useTranslations } from 'next-intl';
+
+export default function Page() {
+  const t = useTranslations('Home');
+  return <h1>{t('title')}</h1>;
+}
+```
+
+### Python (gettext)
+
+```python
+from gettext import gettext as _
+
+print(_("Welcome to our app"))
+```
+
+---
+
+## 4. File Structure
+
+```
+locales/
+├── en/
+│   ├── common.json
+│   ├── auth.json
+│   └── errors.json
+├── tr/
+│   ├── common.json
+│   ├── auth.json
+│   └── errors.json
+└── ar/          # RTL
+    └── ...
+```
+
+---
+
+## 5. Best Practices
+
+### DO ✅
+
+- Use translation keys, not raw text
+- Namespace translations by feature
+- Support pluralization
+- Handle date/number formats per locale
+- Plan for RTL from the start
+- Use ICU message format for complex strings
+
+### DON'T ❌
+
+- Hardcode strings in components
+- Concatenate translated strings
+- Assume text length (German is 30% longer)
+- Forget about RTL layout
+- Mix languages in same file
+
+---
+
+## 6. Common Issues
+
+| Issue | Solution |
+|-------|----------|
+| Missing translation | Fallback to default language |
+| Hardcoded strings | Use linter/checker script |
+| Date format | Use Intl.DateTimeFormat |
+| Number format | Use Intl.NumberFormat |
+| Pluralization | Use ICU message format |
+
+---
+
+## 7. RTL Support
+
+```css
+/* CSS Logical Properties */
+.container {
+  margin-inline-start: 1rem;  /* Not margin-left */
+  padding-inline-end: 1rem;   /* Not padding-right */
+}
+
+[dir="rtl"] .icon {
+  transform: scaleX(-1);
+}
+```
+
+---
+
+## 8. Checklist
+
+Before shipping:
+
+- [ ] All user-facing strings use translation keys
+- [ ] Locale files exist for all supported languages
+- [ ] Date/number formatting uses Intl API
+- [ ] RTL layout tested (if applicable)
+- [ ] Fallback language configured
+- [ ] No hardcoded strings in components
+
+---
+
+## Script
+
+| Script | Purpose | Command |
+|--------|---------|---------|
+| `scripts/i18n_checker.py` | Detect hardcoded strings & missing translations | `python scripts/i18n_checker.py <project_path>` |