Sovereign Governance

"One source of truth. Everything else is a pointer."

Overview

This skill enforces a unified governance model across a multi-repo AI agent ecosystem. It solves the core problem: governance drift — where AGENTS.md files, state files, and skills duplicate across repos, diverge, and cause agents to follow conflicting rules.

The Architecture

/Users/nico/Nico_Archive/AGENTS.md <- THE ONE. Canonical. 5,900+ lines. | |-- repo-1/AGENTS.md <- 36-line pointer |-- repo-2/AGENTS.md <- 36-line pointer |-- repo-3/AGENTS.md <- 36-line pointer |-- repo-N/AGENTS.md <- 36-line pointer '-- [any new repo]/AGENTS.md <- 36-line pointer (auto-generated)

Core Principles

• One canonical AGENTS.md — lives in Nico_Archive (The Source of Truth), above all repos

• Every repo gets a pointer — not a copy, not a subset, not a "local version"

• Documentation stays per-repo — docs/ directories are NOT consolidated. Work happens where the code is.

• Governance crosses boundaries — only AGENTS.md, state file schemas, and skill standards are unified

• Enforcement is automated — shell aliases, git hooks, and validation scripts

When to Use This Skill

ALWAYS invoke this skill when:

Situation Action

Creating a new repo Generate pointer AGENTS.md using the template in this skill

Opening a repo for the first time in a session Verify AGENTS.md is a pointer, not a stale copy

Agent detects AGENTS.md > 50 lines in a non-archive repo Governance violation — flag it, follow canonical

Modifying governance rules Edit ONLY Nico_Archive/AGENTS.md , never repo copies

Adding a new skill Check for duplicates across all 3 skill directories

Creating or modifying state files Follow the .agent_sync_state.json schema

Running a governance audit Use the enforcement script

Onboarding a new agent or tool Point it to Nico_Archive/AGENTS.md

Resolving conflicting instructions between repos Canonical wins. Always.

The Canonical Source

/Users/nico/Nico_Archive/AGENTS.md

This file contains ALL governance:

• Agent role assignments and hierarchy

• Task execution protocols

• Git workflow standards

• Deployment procedures

• Testing requirements

• Security protocols

• Section 31: Sovereign Artifact Governance Stack v3.0

No other file may contain governance rules. If you find governance rules in a repo-level file, it's a violation.

Pointer Template

Every repo MUST have an AGENTS.md at root that looks exactly like this. Fill in the repo-specific fields:

AGENTS.md — POINTER FILE

DO NOT add governance rules to this file. DO NOT duplicate protocol from the canonical source.

Canonical Source

All agent protocol, governance, skills, coordination, and compliance rules live in ONE place:

``` /Users/nico/Nico_Archive/AGENTS.md ```

Location: Nico_Archive (The Source of Truth) Section 31: Sovereign Artifact Governance Stack v3.0 Authority: Nicolae Fratila (Founder/CEO)

This Repo

What To Do

1. Open /Users/nico/Nico_Archive/AGENTS.md
2. Read it. Follow it.
3. If a rule here conflicts with the canonical — canonical wins. Always.

This is a pointer file. The canonical AGENTS.md is in Nico_Archive. Last synced: YYYY-MM-DD

Governance Levels

Level Who Can Modify Examples

SOVEREIGN Founder only apex-os-core

STRATEGIC Founder + Lead Agent apex-os-vibe, APEX-OS-THE-FUTURE, apex-os-clean

TACTICAL Assigned Agent vibe-coder-dashboard, apex-platform, tools

OPERATIONAL Any Agent Archived repos, experimental repos

Artifact Classification

Classification Authority Examples

SOVEREIGN ABSOLUTE — Founder only AGENTS.md (canonical), .env.example , tsconfig.json , vercel.json

STRATEGIC HIGH — Founder + Lead Architecture docs, implementation plans, registries

TACTICAL MEDIUM — Assigned Agent Component specs, API designs, skill files

OPERATIONAL STANDARD — Any Agent .agent_sync_state.json , session logs, status reports

State File Standard

.agent_sync_state.json Schema

Every repo MUST have this file at root. Schema:

{ "$schema": "apex-os-agent-sync-v3", "session": { "id": "unique-session-identifier", "started_at": "ISO 8601", "mode": "NORMAL | EMERGENCY | SAFE_MODE" }, "orchestrator": { "agent": "agent-name", "status": "ACTIVE | STANDBY | OFFLINE", "last_heartbeat": "ISO 8601" }, "current_mission": { "name": "human-readable mission name", "priority": "P0 | P1 | P2 | P3", "target": "what we are achieving", "deadline": "ISO 8601 or null", "progress_pct": 0 }, "agents": { "@agent-name": { "status": "ACTIVE | STANDBY | BLOCKED | OFFLINE", "current_task": "exactly what they are doing NOW", "files_locked": [], "last_update": "ISO 8601", "blockers": [] } }, "file_locks": {}, "phases": {}, "last_updated": "ISO 8601", "next_action": "what happens next" }

State File Rules

Rule Enforcement

Every active repo MUST have .agent_sync_state.json

Agent startup check

Schema MUST match the above Validation on read

last_updated MUST be current Reject if stale (>24h)

File locks auto-expire after 30 minutes Prune on read

Never store secrets in state files Secrets in .env only

Skills Governance

Directory Hierarchy (Authority Order)

1. ~/.config/opencode/skills/ <- User-level (highest priority)
2. [repo]/.agents/skills/ <- Project-level
3. [repo]/.opencode/skills/ <- OpenCode-specific (lowest priority)

Skills Rules

Rule Details

No duplicate skills If a skill exists at user-level, do NOT duplicate at project-level

Every skill MUST have SKILL.md No exceptions

Skills MUST NOT contain secrets No API keys, tokens, credentials

New skills require decision log entry Log in docs/registry/decision-log.md

Skill modifications require Last Updated header Add date to SKILL.md header

Deduplication Check

Before creating or modifying a skill, check all 3 directories:

Check for duplicates

ls ~/.config/opencode/skills/ | sort > /tmp/user_skills ls .agents/skills/ 2>/dev/null | sort > /tmp/project_skills ls .opencode/skills/ 2>/dev/null | sort > /tmp/opencode_skills comm -12 /tmp/user_skills /tmp/project_skills # Shows duplicates

If a duplicate exists, keep the user-level version and remove the project-level one.

Registry Protocol

Decision Log

Location: [primary-repo]/docs/registry/decision-log.md

Type: Append-only. Never delete or edit past entries.

Log a decision when:

• Choosing technology, framework, or service provider

• Changing AI model routing or fallback order

• Modifying sovereign config files

• Adding or removing a repo from the ecosystem

• Changing deployment targets

• Any breaking API/schema change

Format:

YYYY-MM-DD

• [CATEGORY] Decision title
  • Rationale: Why
  • Alternatives: What else was evaluated
  • Reference: Link to artifact/commit
  • Impact: What changes
  • Owner: Who decided

Categories: ARCH | INFRA | MODEL | SECURITY | DEPLOY | DATA | SKILL | PROCESS

Session State Log

Location: [primary-repo]/docs/registry/session-state.md

Type: Append-only.

Entry format:

YYYY-MM-DD

• Session focus: One-line description
• Current phase: Where in the broader plan
• Artifacts referenced: List of artifacts read/modified
• Artifacts created: New artifacts with IDs
• Decisions made: Summary (details in decision-log.md)
• Blockers: Any blockers
• Notes: Free-form

Last updated: ISO 8601

Artifact Registry

Location: [primary-repo]/docs/registry/artifact-registry.md

Naming convention:

Prefix Category

GOV-XXX

Governance & Protocol

ARCH-XXX

Architecture Decisions

EXT-XXX

Extracted Architecture Docs

FUT-XXX

Future Architecture

DB-XXX

Database Schemas

API-XXX

API Specifications

AGENT-XXX

Agent Specifications

INFRA-XXX

Infrastructure Docs

TEST-XXX

Testing Specs

DASH-XXX

Dashboard/UI Specs

INTEG-XXX

Integration Docs

SKILL-XXX

Skill Documentation

Agent Startup Protocol

Every agent MUST follow this sequence on activation:

STEP 1: Read repo's AGENTS.md -> If pointer (< 50 lines, "POINTER FILE"): follow to Nico_Archive -> If full copy (> 50 lines): GOVERNANCE VIOLATION. Follow canonical.

STEP 2: Read canonical AGENTS.md from Nico_Archive

STEP 3: Read .agent_sync_state.json -> Check for active missions, file locks, blockers

STEP 4: Read docs/registry/session-state.md -> Understand previous session context

STEP 5: Read docs/registry/decision-log.md -> Know recent decisions

STEP 6: Update .agent_sync_state.json -> Register self as active agent

STEP 7: Begin work

Compliance Violations

Violation Severity Response

AGENTS.md > 50 lines in non-archive repo CRITICAL Replace with pointer. Log violation.

Working in wrong directory CRITICAL STOP. Navigate to correct directory.

Modifying sovereign file without approval CRITICAL Revert. Escalate to Founder.

State file missing or corrupt HIGH Recreate from schema template. Log.

Skill duplicated across directories MEDIUM Remove lower-priority duplicate.

Decision not logged MEDIUM Add entry retroactively.

Session not handed off LOW Update session-state.md next session.

Stale state file (>24h) LOW Update timestamp, prune offline agents.

Escalation Path

Agent detects issue | v Classify severity | +-- LOW: Log it. Fix inline. Continue. +-- MEDIUM: Log it. Fix inline. Flag in session-state.md. +-- HIGH: Log it. Fix immediately. Flag in decision-log.md. +-- CRITICAL: STOP ALL WORK. Log. Escalate to Founder. Do not continue.

Enforcement

Shell Aliases

Add to ~/.zshrc or ~/.bashrc :

APEX OS Governance

alias enforce='/Users/nico/Nico_Archive/enforce-agents-governance.sh' alias enforce-fix='/Users/nico/Nico_Archive/enforce-agents-governance.sh --fix'

Git Pre-Commit Hook

Install globally so it fires in every repo:

mkdir -p ~/.config/git/hooks git config --global core.hooksPath ~/.config/git/hooks

The hook checks AGENTS.md on every commit. If it's stale (not a pointer), the commit is blocked.

Hook location: ~/.config/git/hooks/pre-commit

Enforcement Script

Location: /Users/nico/Nico_Archive/enforce-agents-governance.sh

Audit mode (report violations)

enforce

Fix mode (replace all stale copies with pointers)

enforce-fix

The script:

• Verifies canonical AGENTS.md exists in Nico_Archive

• Scans ALL repos (maxdepth 2 from home directory)

• Classifies each AGENTS.md as COMPLIANT or STALE

• In --fix mode: replaces stale copies with properly classified pointers

• Reports compliance percentage

Cross-Repo Documentation Policy

Governance is centralized. Documentation is NOT.

What Where Consolidated?

AGENTS.md Nico_Archive (ONE copy) YES — centralized

State file schema Defined in canonical AGENTS.md §31 YES — one schema

Skills standards Defined in canonical AGENTS.md §31 YES — one standard

Architecture docs Per-repo docs/

NO — stays where work happens

Session logs Per-repo docs/registry/

NO — per-repo

Decision logs Per-repo docs/registry/

NO — per-repo

README.md Per-repo NO — repo-specific

Source code Per-repo NO — obviously

New Repo Checklist

When creating ANY new repo in the APEX OS ecosystem:

[ ] 1. Create repo [ ] 2. Add AGENTS.md using pointer template (see above) [ ] 3. Add README.md with repo purpose [ ] 4. Add .gitignore (exclude .env, node_modules, .next, dist) [ ] 5. Add .env.example if repo has environment variables [ ] 6. Add .agent_sync_state.json following schema [ ] 7. Add docs/registry/ directory if this is a primary repo [ ] 8. Run enforce to verify compliance [ ] 9. Initial commit and push

Quick Reference

+---------------------------------------------------------------+ | SOVEREIGN GOVERNANCE — QUICK REFERENCE | +---------------------------------------------------------------+ | | | CANONICAL: /Users/nico/Nico_Archive/AGENTS.md | | | | AUDIT: enforce | | FIX: enforce-fix | | | | NEW REPO: Copy pointer template -> fill in fields -> done | | | | VIOLATION: AGENTS.md > 50 lines in any repo = STALE | | RESPONSE: Replace with pointer. Log it. Move on. | | | | DOCS: Stay per-repo. Never consolidate. | | GOVERNANCE: One file. Nico_Archive. That's it. | | | | STATE FILE: .agent_sync_state.json — one schema everywhere | | SKILLS: User-level wins over project-level | | | +---------------------------------------------------------------+

Sovereign Governance Skill v1.0 "One source of truth. Everything else is a pointer."