npm - @agentskillkit/agent-skills - Versions diffs - 1.0.1 - Mend

@agentskillkit/agent-skills 1.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (552) hide show

package/.agent/skills/git-conventions/resources/BEST_PRACTICES.md ADDED Viewed

@@ -0,0 +1,121 @@
+# Commit Message Best Practices
+## CoinPika-Specific Guidelines
+### 1. Always Include Context
+For fintech applications, context is critical:
+```
+# ❌ Bad - No context
+fix: update price
+# ✅ Good - Clear context
+fix(api): correct BTC price rounding to 2 decimals [doctrine: Law-1]
+Fixes floating-point precision issue that caused 0.01% price drift.
+Affects display only, not stored values.
+```
+### 2. Doctrine Tags Are Mandatory
+When changing critical areas, ALWAYS include doctrine tags:
+| Change Type | Required Tags |
+|-------------|---------------|
+| Price/balance logic | `[doctrine: Law-1]` |
+| Historical data | `[doctrine: Law-2]` |
+| Chart components | `[doctrine: Law-3, Law-4]` |
+| Mobile gestures | `[doctrine: Frontend-Mobile]` |
+| API endpoints | `[doctrine: Architecture]` |
+| Caching | `[doctrine: Performance]` |
+### 3. Breaking Changes
+Breaking changes in fintech are HIGH RISK:
+```
+feat(api)!: change price response format [doctrine: Commercial]
+BREAKING CHANGE: /api/coins/[id]/price now returns object
+Before: { price: 50000 }
+After: { currentPrice: 50000, timestamp: "...", source: "..." }
+Migration:
+1. Deploy v2 endpoint alongside v1
+2. Update all consumers
+3. Deprecate v1 after 30 days
+Rollback: Revert to commit abc123
+```
+### 4. Document WHY, Not What
+```
+# ❌ Bad - Describes WHAT
+refactor(chart): change data loading
+# ✅ Good - Explains WHY
+refactor(chart): separate realtime from historical data loading
+Historical chart data was contaminated by WebSocket ticks,
+causing visual artifacts during high-frequency trading.
+Realtime price now displays in separate ticker component.
+[doctrine: Law-3, Law-4]
+```
+## Anti-Patterns to Avoid
+### ❌ Vague Messages
+```
+fix: bug
+update: stuff
+changes
+wip
+```
+### ❌ Missing Scope for Critical Changes
+```
+feat: add caching  # Which caching? Where?
+```
+### ❌ Multiple Unrelated Changes
+```
+feat: add chart, fix login, update deps  # Split into 3 commits
+```
+### ❌ Past Tense
+```
+feat(api): added caching  # Should be "add caching"
+```
+### ❌ Period at End
+```
+feat(api): add caching.  # No period needed
+```
+## Quick Reference
+### Commit Types
+| Type | Description | Bump |
+|------|-------------|------|
+| feat | New feature | MINOR |
+| fix | Bug fix | PATCH |
+| perf | Performance | PATCH |
+| refactor | Code restructure | - |
+| docs | Documentation | - |
+| style | Formatting | - |
+| test | Tests | - |
+| chore | Maintenance | - |
+| doctrine | Constitutional | - |
+### Commit Template
+```
+<type>(<scope>): <description> [doctrine: <tags>]
+<body - explain WHY>
+<footer - breaking changes, issue refs>
+```

package/.agent/skills/git-conventions/resources/references.md ADDED Viewed

@@ -0,0 +1,53 @@
+# References & Resources
+## Specifications
+### Conventional Commits
+- [Conventional Commits 1.0.0](https://www.conventionalcommits.org/en/v1.0.0/)
+- [Angular Commit Message Format](https://github.com/angular/angular/blob/main/CONTRIBUTING.md#commit)
+- [Commitizen](https://commitizen-tools.github.io/commitizen/)
+### Semantic Versioning
+- [Semantic Versioning 2.0.0](https://semver.org/)
+- [npm Semver Calculator](https://semver.npmjs.com/)
+## CoinPika Doctrines
+### Constitutional Laws
+| Law | Name | Description |
+|-----|------|-------------|
+| Law-1 | Truth Ownership | Backend owns financial truth |
+| Law-2 | Historical Integrity | Historical data is immutable |
+| Law-3 | Realtime Ephemerality | Realtime data is ephemeral |
+| Law-4 | Chart Truthfulness | Charts from backend only |
+### Doctrine Files
+- [Master Constitution](../coinpika-doctrine-pack/constitution/coinpika-master-constitution.md)
+- [Architecture Doctrine](../coinpika-doctrine-pack/doctrines/architecture/)
+- [Backend Doctrine](../coinpika-doctrine-pack/doctrines/backend/)
+- [Chart Data Doctrine](../coinpika-doctrine-pack/doctrines/data/)
+- [Mobile Doctrine](../coinpika-doctrine-pack/doctrines/frontend/)
+- [Performance Doctrine](../coinpika-doctrine-pack/doctrines/performance/)
+- [Commercial Doctrine](../coinpika-doctrine-pack/doctrines/commercial/)
+## Git Tools
+### Commit Helpers
+- [Commitizen CLI](https://github.com/commitizen/cz-cli)
+- [Commitlint](https://commitlint.js.org/)
+- [Husky Git Hooks](https://typicode.github.io/husky/)
+### Changelog Generation
+- [Conventional Changelog](https://github.com/conventional-changelog/conventional-changelog)
+- [Release It!](https://github.com/release-it/release-it)
+- [Standard Version](https://github.com/conventional-changelog/standard-version)
+## Learning Resources
+### Articles
+- [How to Write Good Commit Messages](https://cbea.ms/git-commit/)
+- [A Note About Git Commit Messages](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html)
+- [Git Commit Best Practices](https://gist.github.com/luismts/495d982e8c5b1a0ced4a57cf3d93cf60)
+### Videos
+- [Conventional Commits Explained](https://www.youtube.com/results?search_query=conventional+commits)

package/.agent/skills/git-conventions/scripts/format-commit.js ADDED Viewed

@@ -0,0 +1,393 @@
+#!/usr/bin/env node
+/**
+ * CoinPika Commit Message Formatter
+ *
+ * Interactive CLI to format commit messages following Conventional Commits
+ * with CoinPika doctrine tags.
+ *
+ * Usage: node format-commit.js [--quick "message"]
+ *
+ * @version 1.2.0
+ * @author DataGuruIn
+ */
+const readline = require('readline');
+const { execSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+const yaml = require('js-yaml');
+// ============================================================================
+// CONFIGURATION
+// ============================================================================
+const SKILL_ROOT = path.resolve(__dirname, '..');
+const CONFIG_PATH = path.join(SKILL_ROOT, 'metadata', 'commit-config.yaml');
+function loadConfiguration() {
+    try {
+        if (!fs.existsSync(CONFIG_PATH)) {
+            console.warn('⚠️  Configuration file not found, using internal defaults.');
+            return null;
+        }
+        const fileContents = fs.readFileSync(CONFIG_PATH, 'utf8');
+        return yaml.load(fileContents);
+    } catch (e) {
+        console.error('❌ Failed to load configuration:', e);
+        return null;
+    }
+}
+// Fallback defaults in case config is missing
+const DEFAULT_CONFIG = {
+    commitTypes: [
+        { value: 'feat', description: 'New feature or capability' },
+        { value: 'fix', description: 'Bug fix' },
+        { value: 'refactor', description: 'Code refactor without behavior change' },
+        { value: 'perf', description: 'Performance improvement' },
+        { value: 'style', description: 'Code style/formatting (no logic change)' },
+        { value: 'docs', description: 'Documentation only' },
+        { value: 'test', description: 'Adding or updating tests' },
+        { value: 'chore', description: 'Build process, dependencies, tooling' },
+        { value: 'doctrine', description: 'Constitutional/doctrinal enforcement' },
+    ],
+    scopes: [
+        { value: 'api', description: 'Backend API' },
+        { value: 'data', description: 'Data pipeline or persistence' },
+        { value: 'chart', description: 'Chart components' },
+        { value: 'mobile', description: 'Mobile UI/gestures' },
+        { value: 'worker', description: 'Background jobs/workers' },
+        { value: 'cache', description: 'Caching layer' },
+        { value: 'auth', description: 'Authentication' },
+        { value: 'ui', description: 'General UI components' },
+    ],
+    doctrines: [
+        { value: 'Law-1', description: 'Truth Ownership - Backend owns truth' },
+        { value: 'Law-2', description: 'Historical Integrity - Data is immutable' },
+        { value: 'Law-3', description: 'Realtime Ephemerality - Separate realtime/historical' },
+        { value: 'Law-4', description: 'Chart Truthfulness - Charts from backend only' },
+        { value: 'Architecture', description: 'System boundaries' },
+        { value: 'Performance', description: 'Caching & optimization' },
+        { value: 'Frontend-Mobile', description: 'Mobile UX standards' },
+        { value: 'Commercial', description: 'Commercial guardrails' },
+    ],
+    scopeMapping: {
+        'api': ['Law-1', 'Architecture', 'Performance'],
+        'data': ['Law-1', 'Law-2', 'Architecture'],
+        'chart': ['Law-3', 'Law-4'],
+        'mobile': ['Frontend-Mobile'],
+        'worker': ['Performance', 'Architecture'],
+        'cache': ['Performance'],
+    }
+};
+const config = loadConfiguration() || DEFAULT_CONFIG;
+const COMMIT_TYPES = config.commitTypes || DEFAULT_CONFIG.commitTypes;
+const SCOPES = config.scopes || DEFAULT_CONFIG.scopes;
+const DOCTRINES = config.doctrines || DEFAULT_CONFIG.doctrines;
+const SCOPE_DOCTRINE_MAP = config.scopeMapping || DEFAULT_CONFIG.scopeMapping;
+// ============================================================================
+// UTILITIES
+// ============================================================================
+function getChangedFiles() {
+    try {
+        const output = execSync('git diff --cached --name-only', { encoding: 'utf8' });
+        return output.trim().split('\n').filter(Boolean);
+    } catch {
+        return [];
+    }
+}
+function suggestScope(files) {
+    // Naive suggestion logic - could also be moved to config (regex mapping) but keeping simple for now
+    for (const file of files) {
+        const lower = file.toLowerCase();
+        // Check against known scopes if they match file path parts
+        for (const scope of SCOPES) {
+            if (lower.includes(scope.value)) return scope.value;
+        }
+        // Manual fallbacks from original script if not covered by scope names
+        if (lower.includes('server')) return 'api';
+        if (lower.includes('graph')) return 'chart';
+        if (lower.includes('gesture')) return 'mobile';
+        if (lower.includes('db')) return 'data';
+    }
+    return null;
+}
+function suggestDoctrines(scope) {
+    return SCOPE_DOCTRINE_MAP[scope] || [];
+}
+// ============================================================================
+// INTERACTIVE MODE
+// ============================================================================
+async function prompt(question) {
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout
+    });
+    return new Promise(resolve => {
+        rl.question(question, answer => {
+            rl.close();
+            resolve(answer.trim());
+        });
+    });
+}
+async function selectFromList(title, items, defaultValue = null) {
+    console.log(`\n${title}`);
+    items.forEach((item, i) => {
+        const marker = defaultValue === item.value ? ' (suggested)' : '';
+        console.log(`  ${i + 1}. ${item.value} - ${item.description}${marker}`);
+    });
+    console.log(`  0. Skip/None`);
+    const answer = await prompt('\nSelect (number): ');
+    const idx = parseInt(answer, 10);
+    if (idx === 0 || isNaN(idx)) return null;
+    return items[idx - 1]?.value || null;
+}
+async function multiSelectFromList(title, items, suggested = []) {
+    console.log(`\n${title}`);
+    items.forEach((item, i) => {
+        const marker = suggested.includes(item.value) ? ' ★' : '';
+        console.log(`  ${i + 1}. ${item.value} - ${item.description}${marker}`);
+    });
+    console.log(`  (Enter comma-separated numbers, e.g., 1,3,4)`);
+    console.log(`  (Press Enter to skip)`);
+    const answer = await prompt('\nSelect: ');
+    if (!answer) return [];
+    const indices = answer.split(',').map(s => parseInt(s.trim(), 10));
+    return indices
+        .filter(i => !isNaN(i) && i > 0 && i <= items.length)
+        .map(i => items[i - 1].value);
+}
+async function interactiveMode() {
+    console.log('\n🔧 CoinPika Commit Message Formatter\n');
+    console.log('─'.repeat(50));
+    // Detect context
+    const changedFiles = getChangedFiles();
+    if (changedFiles.length > 0) {
+        console.log(`\n📁 Staged files:`);
+        changedFiles.slice(0, 5).forEach(f => console.log(`   - ${f}`));
+        if (changedFiles.length > 5) {
+            console.log(`   ... and ${changedFiles.length - 5} more`);
+        }
+    }
+    const suggestedScope = suggestScope(changedFiles);
+    // Step 1: Type
+    const type = await selectFromList('Select commit type:', COMMIT_TYPES);
+    if (!type) {
+        console.log('❌ Type is required');
+        process.exit(1);
+    }
+    // Step 2: Scope
+    const scope = await selectFromList('Select scope (optional):', SCOPES, suggestedScope);
+    // Step 3: Description
+    const description = await prompt('\nEnter description (imperative mood, lowercase, no period):\n> ');
+    if (!description) {
+        console.log('❌ Description is required');
+        process.exit(1);
+    }
+    // Step 4: Breaking change
+    const breaking = await prompt('\nIs this a breaking change? (y/N): ');
+    const isBreaking = breaking.toLowerCase() === 'y';
+    // Step 5: Doctrine tags
+    const suggestedDoctrines = scope ? suggestDoctrines(scope) : [];
+    const doctrines = await multiSelectFromList(
+        'Select applicable doctrines:',
+        DOCTRINES,
+        suggestedDoctrines
+    );
+    // Step 6: Body (optional)
+    console.log('\nEnter body (optional, press Enter twice to finish):');
+    let body = '';
+    const bodyRl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout
+    });
+    let emptyLines = 0;
+    for await (const line of bodyRl) {
+        if (line === '') {
+            emptyLines++;
+            if (emptyLines >= 2) break;
+        } else {
+            emptyLines = 0;
+            body += line + '\n';
+        }
+    }
+    bodyRl.close();
+    body = body.trim();
+    // Build message
+    let message = type;
+    if (scope) message += `(${scope})`;
+    if (isBreaking) message += '!';
+    message += `: ${description}`;
+    if (doctrines.length > 0) {
+        message += ` [doctrine: ${doctrines.join(', ')}]`;
+    }
+    if (body) {
+        message += `\n\n${body}`;
+    }
+    if (isBreaking) {
+        message += `\n\nBREAKING CHANGE: ${description}`;
+    }
+    // Output
+    console.log('\n' + '═'.repeat(50));
+    console.log('📝 Generated Commit Message:');
+    console.log('═'.repeat(50));
+    console.log(`\n${message}\n`);
+    console.log('═'.repeat(50));
+    // Copy option
+    const copy = await prompt('\nCopy to clipboard? (Y/n): ');
+    if (copy.toLowerCase() !== 'n') {
+        try {
+            if (process.platform === 'win32') {
+                execSync(`echo ${message.replace(/\n/g, '& echo.')} | clip`);
+            } else if (process.platform === 'darwin') {
+                execSync(`echo "${message}" | pbcopy`);
+            } else {
+                execSync(`echo "${message}" | xclip -selection clipboard`);
+            }
+            console.log('✅ Copied to clipboard!');
+        } catch {
+            console.log('⚠️  Could not copy to clipboard');
+        }
+    }
+    // Commit option
+    const commit = await prompt('Run git commit with this message? (y/N): ');
+    if (commit.toLowerCase() === 'y') {
+        try {
+            execSync(`git commit -m "${message.replace(/"/g, '\\"')}"`, { stdio: 'inherit' });
+        } catch {
+            console.log('⚠️  Git commit failed');
+        }
+    }
+    console.log('\n' + '─'.repeat(50));
+    console.log('P.S. ⚡ Formatted by CoinPika Commit Engine');
+}
+// ============================================================================
+// QUICK MODE
+// ============================================================================
+function quickFormat(input) {
+    // Parse input: "type(scope): message"
+    const match = input.match(/^(\w+)(?:\((\w+)\))?(!)?:\s*(.+)$/);
+    if (!match) {
+        console.log('❌ Invalid format. Expected: type(scope): description');
+        console.log('   Example: feat(api): add caching layer');
+        process.exit(1);
+    }
+    const [, type, scope, breaking, description] = match;
+    // Validate type
+    if (!COMMIT_TYPES.find(t => t.value === type)) {
+        console.log(`❌ Invalid type: ${type}`);
+        console.log(`   Valid types: ${COMMIT_TYPES.map(t => t.value).join(', ')}`);
+        process.exit(1);
+    }
+    // Suggest doctrines
+    const suggestedDoctrines = scope ? suggestDoctrines(scope) : [];
+    let message = input;
+    if (suggestedDoctrines.length > 0) {
+        message += ` [doctrine: ${suggestedDoctrines.join(', ')}]`;
+    }
+    console.log('\n📝 Formatted Message:');
+    console.log(`\n${message}\n`);
+    if (suggestedDoctrines.length > 0) {
+        console.log(`💡 Suggested doctrines based on scope "${scope}":`);
+        suggestedDoctrines.forEach(d => {
+            const doc = DOCTRINES.find(x => x.value === d);
+            console.log(`   - ${d}: ${doc?.description || ''}`);
+        });
+    }
+}
+// ============================================================================
+// CLI
+// ============================================================================
+function printHelp() {
+    console.log(`
+CoinPika Commit Message Formatter v1.2.0
+USAGE:
+  node format-commit.js              Interactive mode
+  node format-commit.js --quick "..."  Quick format
+  node format-commit.js --help       Show help
+OPTIONS:
+  --quick   Format a quick message with doctrine suggestions
+  --help    Show this help
+EXAMPLES:
+  node format-commit.js
+  node format-commit.js --quick "feat(api): add caching layer"
+COMMIT TYPES:
+  ${COMMIT_TYPES.map(t => t.value).join(', ')}
+SCOPES:
+  ${SCOPES.map(s => s.value).join(', ')}
+`);
+}
+async function main() {
+    const args = process.argv.slice(2);
+    if (args.includes('--help')) {
+        printHelp();
+        process.exit(0);
+    }
+    if (args.includes('--quick')) {
+        const idx = args.indexOf('--quick');
+        const message = args[idx + 1];
+        if (!message) {
+            console.log('❌ --quick requires a message');
+            process.exit(1);
+        }
+        quickFormat(message);
+    } else {
+        await interactiveMode();
+    }
+}
+main().catch(console.error);

package/.agent/skills/git-conventions/scripts/validate-commit-msg.sh ADDED Viewed

@@ -0,0 +1,27 @@
+#!/bin/sh
+MESSAGE=$(cat "$1")
+# Check for doctrine tag when needed
+if echo "$MESSAGE" | grep -qiE '(api|chart|data|mobile|backend)'; then
+  if ! echo "$MESSAGE" | grep -q '\[doctrine:'; then
+    echo "ERROR: Changes to api/chart/data/mobile/backend require [doctrine: ...] tag"
+    echo ""
+    echo "Examples:"
+    echo "  [doctrine: Law-2]"
+    echo "  [doctrine: Architecture]"
+    echo "  [doctrine: Performance]"
+    exit 1
+  fi
+fi
+# Check conventional commit format
+if ! echo "$MESSAGE" | grep -qE '^(feat|fix|docs|style|refactor|perf|test|chore|doctrine)(\(.+\))?!?:'; then
+  echo "ERROR: Commit message must follow Conventional Commits format"
+  echo ""
+  echo "Format: <type>[scope]: <description>"
+  echo "Example: feat(api): add caching layer"
+  exit 1
+fi
+exit 0

package/.agent/skills/governance/.skill-source.json ADDED Viewed

@@ -0,0 +1,8 @@
+{
+  "repo": "dataguruin/agent-skills",
+  "skill": "coinpika-doctrine-pack",
+  "ref": null,
+  "checksum": "545e1b627f6efb912cc9095a12bc745d999029ad112d7bcd266dd71e79f9bc3b",
+  "installedAt": "2026-01-24T11:02:40.686Z",
+  "method": "symlink"
+}