@agentskillkit/agent-skills 1.0.1

package/.agent/skills/governance/examples/violation-backend-mutation/after.tsx

@@ -0,0 +1,59 @@
+// ✅ CORRECT: Backend as source of truth
+// Follows Law 1 (Truth Ownership)
+
+import { useQuery } from '@tanstack/react-query';
+import { api } from '@/lib/api';
+
+export function CoinPriceCard({ coinId }: { coinId: string }) {
+    // ✅ Frontend only consumes backend data
+    const { data } = useQuery({
+        queryKey: ['coin', coinId, 'price'],
+        queryFn: () => api.getCoinPrice(coinId),
+        refetchInterval: 5000, // Backend controls refresh rate
+    });
+
+    // ✅ NO local state for truth
+    // ✅ NO direct external API calls
+    // ✅ NO frontend calculations
+    // ✅ NO localStorage for financial data
+
+    if (!data) return <div>Loading...</div>;
+
+    return (
+        <div>
+            {/* ✅ Display backend-provided data only */}
+            <p>Price: ${data.currentPrice}</p>
+            <p>24h Avg: ${data.avg24h}</p>
+
+            {/* Backend metadata */}
+            <p className="text-xs text-gray-500">
+                Updated: {new Date(data.timestamp).toLocaleTimeString()}
+            </p>
+        </div>
+    );
+}
+
+// ✅ Backend API implementation (separate service)
+// /api/coins/[coinId]/price.ts
+export async function GET(req: Request, { params }: { params: { coinId: string } }) {
+    // ✅ Backend owns the truth
+    const price = await db.coinPrices.findFirst({
+        where: { coinId: params.coinId },
+        orderBy: { timestamp: 'desc' },
+    });
+
+    // ✅ Backend calculates aggregates
+    const avg24h = await db.coinPrices.aggregate({
+        where: {
+            coinId: params.coinId,
+            timestamp: { gte: new Date(Date.now() - 24 * 60 * 60 * 1000) },
+        },
+        _avg: { price: true },
+    });
+
+    return Response.json({
+        currentPrice: price.price,
+        avg24h: avg24h._avg.price,
+        timestamp: price.timestamp,
+    });
+}

package/.agent/skills/governance/examples/violation-backend-mutation/before.tsx

@@ -0,0 +1,42 @@
+// ❌ VIOLATION: Frontend mutating backend data
+// This violates Law 1 (Truth Ownership)
+
+import { useState } from 'react';
+
+export function CoinPriceCard({ coinId }: { coinId: string }) {
+  const [price, setPrice] = useState<number>(0);
+  const [history, setHistory] = useState<number[]>([]);
+
+  // VIOLATION: Frontend making truth decisions
+  const updatePrice = (newPrice: number) => {
+    // ❌ Directly mutating price state
+    setPrice(newPrice);
+    
+    // ❌ CRITICAL VIOLATION: Frontend managing historical data
+    setHistory(prev => [...prev, newPrice]);
+    
+    // ❌ Frontend calculating aggregates
+    const avg = history.reduce((a, b) => a + b, 0) / history.length;
+    
+    // ❌ Frontend persisting to localStorage
+    localStorage.setItem(`coin_${coinId}_price`, newPrice.toString());
+    localStorage.setItem(`coin_${coinId}_history`, JSON.stringify(history));
+  };
+
+  // ❌ Frontend calling external API directly
+  useEffect(() => {
+    fetch(`https://api.coingecko.com/api/v3/coins/${coinId}`)
+      .then(res => res.json())
+      .then(data => {
+        // ❌ Frontend processing raw external data
+        updatePrice(data.market_data.current_price.usd);
+      });
+  }, [coinId]);
+
+  return (
+    <div>
+      <p>Price: ${price}</p>
+      <p>24h Avg: ${avg}</p>
+    </div>
+  );
+}

package/.agent/skills/governance/examples/violation-backend-mutation/explanation.md

@@ -0,0 +1,87 @@
+# Backend Mutation Violation Example
+
+## Why This Matters
+
+This example demonstrates **Law 1: Truth Ownership** from the Master Constitution.
+
+### The Problem (before.tsx)
+
+The frontend is:
+1. ❌ Making truth decisions about prices
+2. ❌ Managing historical data locally
+3. ❌ Calculating financial aggregates
+4. ❌ Persisting data to localStorage
+5. ❌ Calling external APIs directly
+
+### The Systemic Risks
+
+1. **Data Inconsistency**
+   - Different users see different "truths"
+   - No single source of historical accuracy
+   - Aggregates vary by client state
+
+2. **Correctness Failure**
+   - Frontend can be manipulated via DevTools
+   - localStorage can be corrupted
+   - No data validation or normalization
+
+3. **Scalability Failure**
+   - Every client directly hammers external APIs
+   - No rate limiting or caching
+   - Amplification under load
+
+4. **Commercial Risk**
+   - Users making financial decisions on unverified data
+   - Potential for data manipulation
+   - No audit trail
+
+### The Solution (after.tsx)
+
+The backend:
+- ✅ Owns all truth
+- ✅ Manages historical data
+- ✅ Calculates aggregates
+- ✅ Validates and normalizes external data
+- ✅ Provides cacheable, rate-limited API
+
+The frontend:
+- ✅ Only displays backend-provided data
+- ✅ Has no local truth
+- ✅ Cannot manipulate financial data
+- ✅ Stateless and predictable
+
+## Constitutional Justification
+
+> **Law 1 — Truth Ownership**
+> 
+> The backend is the **single source of truth**.
+> 
+> If the frontend can alter financial meaning, the system is architecturally broken.
+
+From: `constitution/coinpika-master-constitution.md`
+
+## Architecture Doctrine
+
+> The frontend MUST NEVER:
+> - Depend directly on external APIs (production)
+> - Reconstruct backend meaning
+> - Patch missing data
+> 
+> If the frontend can "fix" backend data, the architecture is invalid.
+
+From: `doctrines/architecture/coinpika-architecture-doctrine.md`
+
+## When to Apply This Pattern
+
+- Any financial data (prices, volumes, balances)
+- Any historical data (charts, aggregates, trends)
+- Any calculated data (averages, percentiles, rankings)
+- Any persistent data (portfolios, watchlists, settings with financial impact)
+
+## Key Takeaway
+
+**The frontend is a VIEW, not a CALCULATOR.**
+
+If you're writing `localStorage.setItem()` with financial data, or calculating aggregates in a React component, you're violating the Constitution.
+
+Stop, redesign, and move the logic to the backend.

package/.agent/skills/governance/examples/violation-chart-injection/after.tsx

@@ -0,0 +1,99 @@
+// ✅ CORRECT: Realtime and historical data strictly separated
+// Follows Law 3 (Realtime Ephemerality) and Law 4 (Chart Truthfulness)
+
+import { useEffect, useRef, useState } from 'react';
+import { createChart } from 'lightweight-charts';
+
+export function BitcoinChart() {
+    const chartRef = useRef<any>(null);
+    const seriesRef = useRef<any>(null);
+
+    // ✅ SEPARATE state for realtime display
+    const [realtimePrice, setRealtimePrice] = useState<number | null>(null);
+    const [realtimeChange, setRealtimeChange] = useState<number>(0);
+
+    useEffect(() => {
+        const chart = createChart(chartRef.current, { width: 600, height: 400 });
+        const series = chart.addLineSeries();
+
+        // ✅ Load ONLY historical data into chart
+        fetch('/api/bitcoin/historical')
+            .then(res => res.json())
+            .then(data => {
+                series.setData(data); // Immutable historical record
+
+                // ✅ Use last historical point as baseline for realtime change
+                const lastPrice = data[data.length - 1].value;
+                setRealtimeChange(0); // Reset change against history
+            });
+
+        // ✅ WebSocket for DISPLAY ONLY
+        const ws = new WebSocket('wss://stream.binance.com/ws/btcusdt@trade');
+
+        ws.onmessage = (event) => {
+            const tick = JSON.parse(event.data);
+            const price = parseFloat(tick.p);
+
+            // ✅ Update ephemeral display state ONLY
+            setRealtimePrice(price);
+
+            // ✅ Calculate change from last HISTORICAL close
+            const lastHistoricalPrice = series.data()[series.data().length - 1].value;
+            setRealtimeChange(((price - lastHistoricalPrice) / lastHistoricalPrice) * 100);
+
+            // ✅ NO modification to chart data
+            // ✅ NO persistence
+            // ✅ NO mixing historical and realtime
+        };
+
+        seriesRef.current = series;
+
+        return () => ws.close();
+    }, []);
+
+    return (
+        <div>
+            {/* ✅ Historical chart (immutable) */}
+            <div ref={chartRef} />
+
+            {/* ✅ Separate realtime display */}
+            <div className="realtime-ticker bg-gray-900 p-4 mt-2">
+                <p className="text-sm text-gray-400">Live Price (not in chart)</p>
+                <p className="text-2xl font-bold">
+                    ${realtimePrice?.toLocaleString() ?? '---'}
+                </p>
+                <p className={realtimeChange >= 0 ? 'text-green-500' : 'text-red-500'}>
+                    {realtimeChange >= 0 ? '↑' : '↓'} {Math.abs(realtimeChange).toFixed(2)}%
+                </p>
+                <p className="text-xs text-gray-500 mt-1">
+                    Since last close • Ephemeral • Not persisted
+                </p>
+            </div>
+        </div>
+    );
+}
+
+// ✅ Backend aggregates realtime into historical at fixed intervals
+// /api/cron/aggregate-bitcoin-price.ts (runs every 5 minutes)
+export async function aggregateRealtimeToHistory() {
+    // ✅ Collect realtime ticks from last 5 minutes
+    const realtimeTicks = await redis.lrange('btc:ticks:last5m', 0, -1);
+
+    // ✅ Calculate OHLCV from ticks
+    const candle = calculateOHLCV(realtimeTicks);
+
+    // ✅ APPEND to historical data (immutable)
+    await db.bitcoinHistory.create({
+        data: {
+            timestamp: candle.timestamp,
+            open: candle.open,
+            high: candle.high,
+            low: candle.low,
+            close: candle.close,
+            volume: candle.volume,
+        },
+    });
+
+    // ✅ Clear realtime buffer
+    await redis.del('btc:ticks:last5m');
+}

package/.agent/skills/governance/examples/violation-chart-injection/before.tsx

@@ -0,0 +1,57 @@
+// ❌ VIOLATION: Realtime ticks injected into historical chart
+// Violates Law 3 (Realtime Ephemerality) and Law 4 (Chart Truthfulness)
+
+import { useEffect, useRef } from 'react';
+import { createChart } from 'lightweight-charts';
+
+export function BitcoinChart() {
+    const chartRef = useRef<any>(null);
+    const seriesRef = useRef<any>(null);
+
+    useEffect(() => {
+        const chart = createChart(chartRef.current, { width: 600, height: 400 });
+        const series = chart.addLineSeries();
+
+        // ✅ Load historical data (OK)
+        fetch('/api/bitcoin/historical')
+            .then(res => res.json())
+            .then(data => {
+                series.setData(data); // Historical data
+            });
+
+        // ❌ CRITICAL VIOLATION: WebSocket realtime injection
+        const ws = new WebSocket('wss://stream.binance.com/ws/btcusdt@trade');
+
+        ws.onmessage = (event) => {
+            const tick = JSON.parse(event.data);
+            const price = parseFloat(tick.p);
+            const time = Math.floor(tick.T / 1000);
+
+            // ❌ VIOLATION: Adding realtime tick to historical chart
+            series.update({
+                time,
+                value: price,
+            });
+
+            // ❌ VIOLATION: Persisting realtime as history
+            const existingData = series.data();
+            const updated = [...existingData, { time, value: price }];
+
+            // ❌ This permanently alters the historical record
+            series.setData(updated);
+        };
+
+        seriesRef.current = series;
+
+        return () => ws.close();
+    }, []);
+
+    return <div ref={chartRef} />;
+}
+
+// ❌ Result: Chart now contains MIX of:
+// - Historical aggregated data (5m candles from backend)
+// - Realtime individual ticks (streaming)
+//
+// This is FORBIDDEN. Users cannot distinguish history from realtime.
+// The chart is now lying about the past.

package/.agent/skills/governance/examples/violation-chart-injection/explanation.md

@@ -0,0 +1,116 @@
+# Chart Injection Violation Example
+
+## Why This Matters
+
+This example demonstrates **Law 3: Realtime Ephemerality** and **Law 4: Chart Truthfulness**.
+
+### The Problem (before.tsx)
+
+The implementation:
+1. ❌ Mixes realtime ticks with historical aggregates
+2. ❌ Mutates historical chart data
+3. ❌ Persists ephemeral realtime as permanent history
+4. ❌ Misleads users about data accuracy
+
+### The Systemic Risks
+
+1. **Data Corruption**
+   - Historical chart contains individual ticks (millisecond resolution)
+   - Mixed with 5-minute aggregated candles
+   - Impossible to distinguish which is which
+   - Chart appears "more accurate" but is actually lying
+
+2. **Financial Incorrectness**
+   - Users making decisions on fake "historical" data
+   - Backtesting on contaminated data produces wrong signals
+   - Aggregates (MA, RSI) calculated on mixed data are invalid
+
+3. **Performance Degradation**
+   - Chart contains thousands of individual ticks
+   - Memory bloat as realtime data accumulates
+   - Rendering lag from excessive data points
+
+4. **Predictability Failure**
+   - Refresh page → different data (depends on when you connected to WebSocket)
+   - Users see different "history"
+   - No reproducibility
+
+### The Solution (after.tsx)
+
+**Separation of Concerns**:
+
+1. **Historical Chart** (Immutable)
+   - Only contains backend-aggregated data
+   - Consistent across all users
+   - Never modified by frontend
+   - Refreshing shows same data
+
+2. **Realtime Display** (Ephemeral)
+   - Separate visual component
+   - Clearly labeled "Live Price"
+   - Not persisted
+   - Not in chart
+   - Shows change from last historical close
+
+3. **Backend Aggregation** (Truth)
+   - Backend collects realtime ticks
+   - Aggregates at fixed intervals (5min)
+   - Appends to historical table
+   - Frontend receives pre-aggregated data
+
+## Constitutional Justification
+
+> **Law 3 — Realtime Ephemerality**
+> 
+> Realtime data is transient and display-only.
+> It MUST NOT:
+> - Be persisted as history
+> - Affect aggregates
+> - Contaminate charts
+
+> **Law 4 — Chart Truthfulness**
+> 
+> Charts represent historical financial truth, not realtime excitement.
+> Realtime ticks MUST NEVER be injected into charts.
+
+From: `constitution/coinpika-master-constitution.md`
+
+## Chart Data Doctrine
+
+> Historical data and realtime data MUST be visually and architecturally separated.
+> 
+> If a user cannot distinguish historical from realtime, the system is broken.
+
+From: `doctrines/data/coinpika-chart-data-doctrine.md`
+
+## Visual Separation Examples
+
+### ✅ Good Patterns
+- Separate "Live Price" badge above/below chart
+- Realtime ticker with "ephemeral" label
+- Crosshair showing "last close" vs "current price"
+- Explicit timestamp showing historical data ends
+
+### ❌ Bad Patterns
+- Extending chart line with realtime ticks
+- Updating last candle with realtime data
+- Showing realtime on same Y-axis scale without separation
+- Any approach where user can't tell what's historical
+
+## When to Apply This Pattern
+
+- **Always** when displaying charts
+- **Always** when showing financial time-series
+- **Always** when mixing historical + realtime
+- **Always** when users make trading decisions
+
+## Key Takeaway
+
+**Charts show HISTORY. Realtime shows NOW. Never mix them.**
+
+If your chart is "updating in realtime," you're violating Laws 3 and 4.
+
+Historical data is **append-only from the backend**.  
+Realtime data is **ephemeral display-only in the frontend**.
+
+Stop, separate, and preserve chart truthfulness.

package/.agent/skills/governance/knowledge/lessons-learned.yaml

@@ -0,0 +1,3 @@
+version: 1.0.0
+last_updated: ""
+lessons: []

package/.agent/skills/governance/metadata/precedence.yaml

@@ -0,0 +1,117 @@
+# CoinPika Doctrine Precedence Map
+# Defines absolute authority order for conflict resolution.
+# Higher precedence ALWAYS overrides lower precedence.
+# No implicit override is permitted.
+
+version: 1.0.0
+status: LOCKED
+authority: SUPREME
+
+precedence:
+  - id: coinpika-master-constitution
+    level: 0
+    authority: supreme
+    description: >
+      Ultimate constitutional authority.
+      Overrides all doctrines, skills, enforcement rules,
+      agent behavior, and developer preference.
+
+  - id: coinpika-architecture-doctrine
+    level: 1
+    authority: constitutional
+    description: >
+      System-wide architectural boundaries, ownership,
+      scalability invariants, and dependency direction.
+
+  - id: coinpika-backend-data-engine-doctrine
+    level: 2
+    authority: constitutional
+    description: >
+      Backend truth ownership, ingestion taxonomy,
+      persistence, caching, and cost control laws.
+
+  - id: coinpika-chart-data-doctrine
+    level: 3
+    authority: constitutional
+    description: >
+      Financial data integrity, historical immutability,
+      and chart truth enforcement.
+
+  - id: coinpika-commercial-guardrails-doctrine
+    level: 4
+    authority: constitutional
+    description: >
+      Enterprise safety, legal exposure,
+      blast radius control, and business continuity rules.
+
+  - id: coinpika-performance-doctrine
+    level: 5
+    authority: constitutional
+    description: >
+      User-perceived performance, visual stability,
+      cache-first rendering, and trust preservation.
+
+  - id: coinpika-frontend-mobile-doctrine
+    level: 6
+    authority: constitutional
+    description: >
+      Mobile-first layout invariants, scroll ownership,
+      and structural UX rules.
+
+  - id: coinpika-swipe-tabs-doctrine
+    level: 7
+    authority: constitutional
+    description: >
+      Universal swipe-tab architecture,
+      gesture arbitration, and navigation consistency.
+
+  - id: coinpika-code-review-doctrine
+    level: 8
+    authority: enforcement
+    description: >
+      Review authority, rejection rules,
+      and enforcement of architectural law.
+
+  - id: coinpika-learning-engine-doctrine
+    level: 9
+    authority: controlled-learning
+    description: >
+      Controlled reasoning improvement,
+      learning boundaries, and rollback rules.
+
+  - id: coinpika-agent-enforcement-protocol
+    level: 10
+    authority: enforcement
+    description: >
+      AI agent permission model,
+      compliance enforcement, and shutdown rules.
+
+  - id: coinpika-frontend-gesture-review-checklist
+    level: 11
+    authority: enforcement
+    description: >
+      Hard merge gate for frontend gesture
+      and scroll-related changes.
+
+  - id: developer-or-agent-preference
+    level: 99
+    authority: none
+    description: >
+      Lowest priority.
+      Never allowed to override any doctrine or law.
+
+resolution_rules:
+  - rule: higher_precedence_wins
+    description: >
+      When two documents conflict, the document
+      with the LOWER level number wins.
+
+  - rule: ambiguity_equals_rejection
+    description: >
+      If conflict resolution is ambiguous,
+      the change MUST be rejected.
+
+  - rule: no_silent_override
+    description: >
+      Overrides must be explicit, versioned,
+      and approved via a Change Proposal.