@agentskillkit/agent-skills 1.0.1

package/.agent/skills/governance/metadata/scope-map.yaml

@@ -0,0 +1,156 @@
+# CoinPika Doctrine Scope Map
+# Maps change scopes to applicable doctrines.
+# Used by agents to automatically determine
+# which doctrines MUST be enforced for a given request.
+
+version: 1.0.0
+status: LOCKED
+authority: SUPREME
+
+scopes:
+
+  architecture:
+    description: >
+      System-level architecture, boundaries, ownership,
+      dependency direction, and scalability decisions.
+    applies:
+      - coinpika-master-constitution
+      - coinpika-architecture-doctrine
+      - coinpika-commercial-guardrails-doctrine
+    examples:
+      - system boundaries
+      - ownership changes
+      - dependency inversion
+      - scalability design
+      - cross-layer coupling
+
+  backend-data:
+    description: >
+      Backend data ingestion, normalization,
+      persistence, caching, and cost control.
+    applies:
+      - coinpika-master-constitution
+      - coinpika-architecture-doctrine
+      - coinpika-backend-data-engine-doctrine
+      - coinpika-chart-data-doctrine
+      - coinpika-performance-doctrine
+    examples:
+      - data ingestion pipelines
+      - cron jobs
+      - caching logic
+      - database schema changes
+      - persistence rules
+
+  charts:
+    description: >
+      Financial chart data, historical truth,
+      aggregation, and visualization integrity.
+    applies:
+      - coinpika-master-constitution
+      - coinpika-architecture-doctrine
+      - coinpika-chart-data-doctrine
+      - coinpika-performance-doctrine
+    examples:
+      - chart rendering
+      - timeframe aggregation
+      - historical price corrections
+      - visualization logic
+
+  frontend-mobile:
+    description: >
+      Mobile layout, scroll ownership,
+      structural hierarchy, and UX invariants.
+    applies:
+      - coinpika-master-constitution
+      - coinpika-architecture-doctrine
+      - coinpika-frontend-mobile-doctrine
+      - coinpika-performance-doctrine
+    examples:
+      - mobile layout changes
+      - header / tab bar structure
+      - scroll containers
+      - sticky behavior
+
+  gestures:
+    description: >
+      Swipe, touch gestures, and navigation interaction.
+    applies:
+      - coinpika-master-constitution
+      - coinpika-architecture-doctrine
+      - coinpika-frontend-mobile-doctrine
+      - coinpika-swipe-tabs-doctrine
+      - coinpika-performance-doctrine
+    examples:
+      - swipe tabs
+      - gesture arbitration
+      - horizontal navigation
+      - touch handling
+
+  performance:
+    description: >
+      Rendering speed, caching behavior,
+      loading states, and perceived performance.
+    applies:
+      - coinpika-master-constitution
+      - coinpika-architecture-doctrine
+      - coinpika-performance-doctrine
+    examples:
+      - loading strategy
+      - cache invalidation
+      - background refresh
+      - render optimization
+
+  commercial-risk:
+    description: >
+      Changes affecting user trust, revenue,
+      legal exposure, or operational safety.
+    applies:
+      - coinpika-master-constitution
+      - coinpika-architecture-doctrine
+      - coinpika-commercial-guardrails-doctrine
+    examples:
+      - breaking changes
+      - migrations
+      - irreversible operations
+      - compliance-impacting changes
+
+  code-review:
+    description: >
+      Review decisions, enforcement,
+      approval or rejection logic.
+    applies:
+      - coinpika-master-constitution
+      - coinpika-architecture-doctrine
+      - coinpika-code-review-doctrine
+    examples:
+      - PR approval
+      - rejection decisions
+      - enforcement escalation
+
+  ai-agents:
+    description: >
+      AI agent behavior, learning,
+      autonomy, and enforcement.
+    applies:
+      - coinpika-master-constitution
+      - coinpika-architecture-doctrine
+      - coinpika-learning-engine-doctrine
+      - coinpika-agent-enforcement-protocol
+    examples:
+      - AI-generated code
+      - automated refactors
+      - agent learning behavior
+      - agent refusal or escalation
+
+default_behavior:
+  rule: conservative
+  description: >
+    If scope cannot be confidently determined,
+    ALL doctrines MUST be applied and
+    explicit human review is required.
+
+failure_mode:
+  rule: reject
+  description: >
+    If scope mapping is ambiguous or incomplete,
+    the change MUST be rejected.

package/.agent/skills/governance/proposals/v1.1-change-proposal-template.md

@@ -0,0 +1,197 @@
+---
+name: v1.1-change-proposal-template
+version: 1.0.0
+status: TEMPLATE
+authority: GOVERNANCE
+parent: coinpika-master-constitution
+---
+
+# 🏷️ CoinPika Change Proposal — v1.1+  
+**(Controlled Doctrine Evolution Request)**
+
+⚠️ **THIS IS NOT A PULL REQUEST**
+
+This document proposes a **potential change** to CoinPika’s
+Constitution, doctrines, or enforcement rules.
+
+If this proposal is **REJECTED**,  
+**NO IMPLEMENTATION MAY PROCEED**.
+
+Doctrine evolution is **rare by design**.
+
+---
+
+## 1. Proposal Metadata
+
+- **Proposal ID:** CP-YYYY-MM-DD-XX
+- **Author(s):**
+- **Date:**
+- **Target Version:** v1.1.x / v2.0.0
+- **Status:** Draft / Under Review / Approved / Rejected
+
+---
+
+## 2. Change Summary (Plain Language)
+
+Describe the proposed change **without implementation details**:
+
+- What is changing?
+- Which law, doctrine, or invariant is affected?
+- What problem does this change attempt to solve?
+
+If this cannot be explained clearly,  
+the proposal is **INVALID**.
+
+---
+
+## 3. Change Classification (MANDATORY)
+
+This proposal affects (check all that apply):
+
+- [ ] Constitution
+- [ ] Architecture Doctrine
+- [ ] Backend Data Engine Doctrine
+- [ ] Chart Data Doctrine
+- [ ] Frontend Mobile / Gesture Doctrine
+- [ ] Performance Doctrine
+- [ ] Commercial Guardrails
+- [ ] Review / Enforcement Rules
+- [ ] AI Learning / Agent Governance
+
+Unclassified impact = **AUTOMATIC REJECTION**.
+
+---
+
+## 4. Constitutional Impact Analysis (MANDATORY)
+
+For EACH Prime Directive, explicitly state impact:
+
+- **Correctness > Convenience:** Affected / Not Affected
+- **Trust > Speed:** Affected / Not Affected
+- **Architecture > Trends:** Affected / Not Affected
+- **Predictability > Cleverness:** Affected / Not Affected
+- **Explicit Trade-offs Only:** Affected / Not Affected
+
+If ANY directive is weakened,  
+the proposal is **EXTREMELY UNLIKELY TO PASS**.
+
+---
+
+## 5. Doctrine Impact Matrix
+
+List **ALL** affected documents.
+
+| Doctrine / File | Impact Level | Explanation |
+|-----------------|--------------|-------------|
+| coinpika-master-constitution | None / Minor / Major | |
+| coinpika-architecture-doctrine | | |
+| coinpika-backend-data-engine-doctrine | | |
+| coinpika-chart-data-doctrine | | |
+| coinpika-frontend-mobile-doctrine | | |
+| coinpika-swipe-tabs-doctrine | | |
+| coinpika-performance-doctrine | | |
+| coinpika-commercial-guardrails-doctrine | | |
+| coinpika-code-review-doctrine | | |
+| coinpika-learning-engine-doctrine | | |
+| coinpika-agent-enforcement-protocol | | |
+
+Missing an affected doctrine = **REJECTION**.
+
+---
+
+## 6. Motivation & Evidence (MANDATORY)
+
+This section MUST include **concrete evidence**:
+
+- Production incidents
+- Real-world constraints
+- Measurable limitations
+- Audit or compliance findings
+
+Speculation, taste, or elegance  
+are **NOT VALID MOTIVATIONS**.
+
+---
+
+## 7. Alternatives Considered
+
+List alternatives that were considered and rejected:
+
+- Alternative A:
+- Alternative B:
+
+Explain **why each alternative fails**
+without changing doctrine.
+
+No alternatives considered = **INCOMPLETE PROPOSAL**.
+
+---
+
+## 8. Risk & Blast Radius Assessment
+
+Explicitly describe:
+
+- What could break if this change is wrong
+- Which users or systems are affected
+- Worst-case failure scenario
+- Reversibility (Yes / No)
+
+Irreversible changes are  
+**STRONGLY DISCOURAGED**.
+
+---
+
+## 9. Compatibility & Migration Plan
+
+- Is v1.0 behavior preserved during transition?
+- Is migration explicit and bounded?
+- Is rollback possible and documented?
+
+Breaking compatibility without transition = **REJECTION**.
+
+---
+
+## 10. Recommendation
+
+The author recommends:
+
+- [ ] Approve
+- [ ] Approve with constraints
+- [ ] Reject
+
+Explain the recommendation  
+**without implementation bias**.
+
+---
+
+## 11. Constitutional Review & Verdict
+
+**Reviewed by:**
+- Architecture
+- Commercial / Risk
+- Performance
+- AI Governance
+
+**Final Verdict:**
+
+- [ ] Approved → Scheduled for v1.1+
+- [ ] Rejected → Doctrine v1.0 remains authoritative
+
+---
+
+## Enforcement Notice
+
+No code, PR, workflow, or agent output  
+may assume this change until it is:
+
+- Explicitly approved
+- Versioned
+- Released
+
+Doctrine changes without approval  
+are **GOVERNANCE VIOLATIONS**.
+
+---
+
+**Template Status:** ACTIVE  
+**Applies To:** Humans & AI Agents  

package/.agent/skills/governance/resources/AUTHORITY_MODEL.md

@@ -0,0 +1,111 @@
+# Authority Model
+
+## Supreme Authority
+
+The `coinpika-doctrine-pack` skill has **SUPREME AUTHORITY** in the CoinPika ecosystem.
+
+### What This Means
+
+This skill **overrides**:
+- ✖ All other skills
+- ✖ Framework defaults
+- ✖ Tooling heuristics
+- ✖ Agent preferences
+- ✖ Developer convenience
+- ✖ "It works" arguments
+
+No implicit override is permitted.
+
+## Decision Precedence Order
+
+When conflicts arise, decisions are resolved in this strict order:
+
+1. 👑 **CoinPika Master Constitution** (HIGHEST)
+   - Prime Directives (immutable)
+   - System Laws (non-negotiable)
+   - Constitutional scope
+
+2. 🏛️ **Architecture & System Doctrines**
+   - System boundaries
+   - Data ownership
+   - Dependency direction
+
+3. 💼 **Commercial Guardrails**
+   - Breaking change assessment
+   - Rollback requirements
+   - Financial data protection
+
+4. ⚡ **Performance Doctrine**
+   - Caching strategy
+   - Scalability invariants
+   - Load behavior
+
+5. 📋 **Review Checklists**
+   - Domain-specific guidance
+   - Verification steps
+
+6. 🤖 **Agent Enforcement Protocol**
+   - Agent behavior constraints
+   - Learning boundaries
+
+7. 👤 **Developer or Agent Preference** (LOWEST)
+   - Personal style
+   - Convenience
+   - Short-term optimization
+
+### Enforcement Rule
+
+Anything lower **cannot override** anything higher.
+
+**There are NO exceptions.**
+
+## Agent Operating Mode
+
+All agents using this skill MUST operate in:
+
+- **POLICY_MODE = STRICT**
+- **AUTONOMY = PROPOSAL_ONLY**
+- **TRUST_LEVEL = ZERO**
+
+### Agents MAY:
+- ✅ Propose implementations
+- ✅ Explain trade-offs
+- ✅ Identify risks
+- ✅ Cite applicable doctrines
+
+### Agents MUST NOT:
+- ❌ Approve changes
+- ❌ Merge code
+- ❌ Introduce new invariants
+- ❌ Override architecture
+- ❌ Bypass enforcement
+- ❌ Argue against constitutional decisions
+
+## Violation Response
+
+When a violation is detected, the agent MUST:
+
+1. **STOP** execution immediately
+2. **CITE** the violated doctrine or law
+3. **EXPLAIN** the systemic risk
+4. **REFUSE** the request or output
+
+Partial compliance or "best effort" responses are considered **enforcement failures**.
+
+## Change Authority
+
+This skill is **LOCKED**.
+
+Changes require:
+- An approved Change Proposal
+- Explicit version bump
+- Constitutional review
+
+Unauthorized modification of doctrine files is a **governance violation**.
+
+## Final Authority Statement
+
+> This Constitution overrides all other considerations.
+> CoinPika optimizes for **long-term trust, correctness, and durability**—not short-term velocity.
+> Safety overrides productivity.
+> If in doubt — **REFUSE**.

package/.agent/skills/governance/resources/ENFORCEMENT_GUIDE.md

@@ -0,0 +1,242 @@
+# Enforcement Guide
+
+## How to Enforce CoinPika Doctrines
+
+This guide explains how to actively enforce constitutional and doctrinal requirements in code reviews, architecture decisions, and AI agent behavior.
+
+## Enforcement Levels
+
+### Level 1: Constitutional (IMMUTABLE)
+**Source**: `constitution/coinpika-master-constitution.md`
+
+**Violations at this level are FATAL**. The work must be rejected entirely.
+
+**Examples**:
+- Modifying historical data in place (violates Law 2)
+- Frontend making truth decisions (violates Law 1)
+- Injecting realtime ticks into charts (violates Law 3)
+
+**Response**: Stop, cite, refuse.
+
+---
+
+### Level 2: Architectural (NON-NEGOTIABLE)
+**Source**: `doctrines/architecture/`, `doctrines/backend/`, `doctrines/data/`
+
+**Violations at this level compromise system integrity**.
+
+**Examples**:
+- Blurred ownership between layers
+- Client-side data reconstruction
+- Implicit dependencies
+
+**Response**: Require architectural redesign before proceeding.
+
+---
+
+### Level 3: Domain-Specific (STRICT)
+**Source**: `doctrines/frontend/`, `doctrines/performance/`, `doctrines/commercial/`
+
+**Violations at this level create technical debt or risk**.
+
+**Examples**:
+- Not following swipe-tab architecture
+- Missing caching strategy
+- No rollback plan for breaking changes
+
+**Response**: Block until compliance is demonstrated.
+
+---
+
+### Level 4: Process (ENFORCED)
+**Source**: `enforcement/checklists/`, `doctrines/review/`
+
+**Violations at this level indicate incomplete work**.
+
+**Examples**:
+- Skipping code review checklist
+- Missing test coverage
+- Undocumented breaking changes
+
+**Response**: Return for completion.
+
+---
+
+## Enforcement Workflow
+
+### 1. Pre-Review
+Before reviewing code/design:
+
+1. ✅ Load `SKILL.md` to identify applicable doctrines
+2. ✅ Load `constitution/` for Prime Directives and System Laws
+3. ✅ Load relevant `doctrines/` based on domain
+4. ✅ Select appropriate `enforcement/checklists/`
+
+### 2. During Review
+While reviewing:
+
+1. **Check Constitutional Compliance**
+   - Are Prime Directives violated?
+   - Are System Laws (1-4) upheld?
+   - Is learning subordinate to Constitution?
+
+2. **Check Architectural Compliance**
+   - Clear ownership boundaries?
+   - Proper dependency direction?
+   - No implicit coupling?
+
+3. **Check Domain Compliance**
+   - Backend: Data engine rules followed?
+   - Frontend: Mobile UX patterns correct?
+   - Data: Chart integrity maintained?
+   - Performance: Caching strategy defined?
+
+4. **Check Process Compliance**
+   - Checklist completed?
+   - Breaking changes documented?
+   - Rollback plan exists?
+
+### 3. Post-Review
+After violations found:
+
+1. **Stop execution**
+2. **Cite specific doctrine** (with file path)
+3. **Explain systemic risk**
+4. **Refuse or request redesign**
+
+### 4. Approval
+Only approve if:
+- ✅ All constitutional laws upheld
+- ✅ All architectural boundaries respected
+- ✅ All domain rules followed
+- ✅ All checklists completed
+
+**Remember**: Partial compliance is not compliance.
+
+---
+
+## Enforcement Examples
+
+### Example 1: Backend API Adding Chart Data
+
+**Request**: "Add a new endpoint to serve sparkline data"
+
+**Enforcement Checklist**:
+1. Load `doctrines/backend/coinpika-backend-data-engine-doctrine.md`
+2. Load `doctrines/data/coinpika-chart-data-doctrine.md`
+3. Load `enforcement/checklists/backend-api-review-checklist.md`
+
+**Key Checks**:
+- ✅ Historical data is immutable (Law 2)?
+- ✅ Realtime data separated from history (Law 3)?
+- ✅ Chart truthfulness maintained (Law 4)?
+- ✅ Caching strategy defined (Performance)?
+- ✅ Rate limiting implemented (Performance)?
+
+**Cite if violated**: "This violates Law 3 (Realtime Ephemerality) from `constitution/coinpika-master-constitution.md`. Realtime ticks must not be persisted as historical aggregates."
+
+---
+
+### Example 2: Frontend Mobile Gesture Change
+
+**Request**: "Modify swipe behavior on Portfolio page"
+
+**Enforcement Checklist**:
+1. Load `doctrines/frontend/coinpika-frontend-mobile-doctrine.md`
+2. Load `doctrines/frontend/coinpika-swipe-tabs-doctrine.md`
+3. Load `enforcement/checklists/mobile-gesture-review-checklist.md`
+
+**Key Checks**:
+- ✅ Native gesture precedence maintained?
+- ✅ No gesture conflicts introduced?
+- ✅ Swipe-tab architecture followed?
+- ✅ Predictable behavior guaranteed?
+
+**Cite if violated**: "This violates the Native Gesture Precedence rule from `doctrines/frontend/coinpika-frontend-mobile-doctrine.md`. Native scrolling must never be blocked."
+
+---
+
+### Example 3: AI Agent Proposing "Smart Fix"
+
+**Request**: Agent suggests "Let's cache prices in localStorage for offline mode"
+
+**Enforcement Checklist**:
+1. Load `constitution/` (Law 1: Truth Ownership)
+2. Load `doctrines/architecture/` (Dependency Direction Law)
+3. Load `doctrines/learning/coinpika-learning-engine-doctrine.md`
+
+**Key Checks**:
+- ❌ Frontend managing truth? (Violates Law 1)
+- ❌ Client-side caching of financial data? (Violates Architecture)
+- ❌ Agent proposing architectural change without approval? (Violates Learning)
+
+**Response**: "This violates Law 1 (Truth Ownership) from the Master Constitution. The backend must remain the single source of truth for all financial data. Frontend caching of prices is architecturally forbidden. Please propose a backend-first caching strategy instead."
+
+---
+
+## Agent-Specific Enforcement
+
+### When AI Agent Violates Doctrine
+
+If an agent:
+- Produces unsafe output
+- Violates doctrine repeatedly
+- Shows unpredictable drift
+- Argues against constitutional decisions
+
+Then:
+1. **Reject output immediately**
+2. **Cite violation** with doctrine reference
+3. **Restrict agent autonomy** if repeated
+4. **Audit past outputs** if severity is high
+
+### Agent Learning Boundaries
+
+Agents MAY learn:
+- ✅ Better reasoning patterns
+- ✅ Improved architectural judgment
+- ✅ More accurate risk assessment
+
+Agents MUST NOT learn:
+- ❌ Code style preferences
+- ❌ Naming conventions
+- ❌ Temporary workarounds
+- ❌ Exceptions to laws
+
+**All learning is subordinate to the Constitution.**
+
+---
+
+## Enforcement Tools
+
+### Automated Enforcement
+
+Use validation scripts when available:
+```bash
+# Validate doctrine compliance
+node scripts/validate_doctrine.js <file-path>
+
+# Audit PR for violations
+node scripts/audit_pr.js <pr-branch>
+
+# Check system boundaries
+node scripts/check_boundaries.js <directory>
+```
+
+### Manual Enforcement
+
+Use checklists:
+- `enforcement/checklists/backend-api-review-checklist.md`
+- `enforcement/checklists/chart-component-review-checklist.md`
+- `enforcement/checklists/mobile-gesture-review-checklist.md`
+- `enforcement/checklists/frontend-gesture-review-checklist.md`
+
+---
+
+## Final Enforcement Principle
+
+> Agents exist to reduce human load, increase consistency, and surface risks early.
+> 
+> Agents do NOT exist to replace architectural judgment, accelerate unsafe change, or bypass review or law.
+> 
+> **If in doubt — REFUSE.**