🤖 Universal AI Principles & Agent Operating System (Portable Kit)

Plug-and-Play AI Assistant Governance, Architecture Principles & Disruption Recovery for Any Software Project.

This kit contains the AI governance system extracted from production development. It ensures that any AI coding assistant follows strict engineering principles, prevents progress loss from unexpected power cuts or crashes, maintains living documentation, and executes automated regression-shielded git workflows.

⚡ 30-Second Cold-Start Quick Reference

Orientation Contract for AI Agents & Developers: Orient yourself in seconds with the verified commands and prerequisites below.

• Runtime Prerequisites: Python 3.10+ (Standard Library only — zero external pip dependencies) and git.
• Canonical Regression Shield Gate:

  python -m unittest discover tests
  

  (100% test pass required before staging or committing changes).

🛠️ Core Operational Command Matrix

Universal CLI contract (PRINCIPLE-011, PRINCIPLE-015). Every CLI: --help / -h prints usage and exits 0, writing nothing; exit 0 = success, 1 = operational failure, 2 = misuse (an unknown flag is refused, never run as the default action); every failure prints What → Why → Fix on stderr, never a traceback. --check is the read-only mode of sync_principles.py and update_knowledge_base.py.

📦 What's Inside

portable_agent_kit/
├── README.md                           <- This Integration & Setup Guide
├── LICENSE                             <- MIT Open Source License
├── aikit.py                            <- Project CLI: new, attach, list, status, check, fix, delegate
├── .gitignore                          <- Credential & local-state baseline (PRINCIPLE-019 R3)
├── AGENTS.md                           <- Generated Tier 1 capsules (auto-loaded by AGENTS.md-convention agents)
├── GUIDELINES.md                       <- Single source of truth: every principle, rule & checklist (Tier 2)
├── GEMINI.md                           <- Google Gemini & Antigravity IDE rules
├── CLAUDE.md                           <- Anthropic Claude Code configuration
├── .cursorrules                        <- Cursor IDE instructions
├── .windsurfrules                      <- Codeium Windsurf IDE instructions
├── .clinerules                         <- Cline / Roo Code IDE instructions
├── .github/
│   ├── copilot-instructions.md         <- GitHub Copilot instructions
│   └── workflows/
│       └── ci.yml                      <- Continuous verification gate (both tiers + freshness)
├── .claude/
│   ├── agents/                         <- Claude sub-agents (generated)
│   ├── settings.json                   <- no agent may edit a task ledger
│   └── skills/
│       └── aikit/
│           └── SKILL.md                <- Claude Code operational runbook (native skill)
├── .agents/
│   ├── rules/
│   │   ├── principles.md               <- Antigravity / Agent IDE workspace rules
│   │   ├── domain.md.template          <- Template for project domain rules (Tier 1B)
│   │   └── readme_quickref.md.template <- Adopter README Quick Reference & tree (PRINCIPLE-005 R6)
│   ├── skills/
│   │   └── aikit/
│   │       └── SKILL.md                <- Antigravity operational runbook & command matrix
│   ├── agents/
│   │   └── opencode_worker.md          <- OpenCode subagent spec for free model delegation
│   └── task_ledger.json                <- Disruption ledger for power-loss resilience (WAL)
├── .opencode/
│   └── agents/                         <- Native OpenCode specialized subagent profiles (architect, coder, etc.)
├── opencode.jsonc                      <- OpenCode v2 provider, model and permissions configuration
├── scripts/
│   ├── sync_principles.py              <- Generates all 8 Tier 1 files from GUIDELINES.md, budget-gated
│   ├── disruption_recovery.py          <- Power-loss audit, atomic checkpointing & ledger CLI
│   ├── update_knowledge_base.py        <- Automatic codebase AST symbol extractor & validator
│   ├── dogfood.py                      <- Operational dogfood runner (sandbox jail + chaos tracks)
│   ├── check_reachability.py           <- Invariant reachability shield (anti-dead-capability)
│   ├── project_registry.py             <- Project discovery, stack detection, .aikit/ memory
│   ├── project_gates.py                <- A project's gates: detection, overrides, runs
│   ├── aikit_cli.py                    <- `aikit.py` commands and error triads
│   ├── subagent_delegate.py            <- `aikit delegate`: bounded OpenCode sub-agent runs
│   ├── project_publish.py              <- Uploads a project to its own GitHub repository
│   └── check_secrets.py                <- Secret & sensitive data scanner (pre-commit gate)

├── tests/
│   ├── test_kit.py                     <- Unit tier: in-process regression shield (strict <1s gate)
│   └── test_integration.py             <- Integration tier: concurrency, CLI contracts & dogfooding
└── knowledge/
    ├── INDEX.md                        <- Knowledge base table of contents & architecture map
    ├── architecture.md                 <- High-level system architecture and component boundaries
    ├── services.md                     <- Core services, API contracts, and business logic
    ├── data_models.md                  <- Data structures, schemas, and persistence models
    ├── state_and_ui.md                 <- Presentation layer, UI state, and event loops
    ├── decisions.md                    <- Architectural Decision Records (ADRs)
    ├── codebase_map.md                 <- Auto-generated AST catalog of classes and functions
    ├── model_benchmarks.md             <- Subagent model benchmark database & selection tree
    ├── host_clients.md                 <- Host client portability & cross-environment parity
    └── principles_audit_ledger.md      <- Snapshot audit at ADR-107 (not kept current)

🚀 Start a Project

Open this folder in any AI host and describe what to build. Each project gets its own folder under projects/ (ignored by AIKit's git) and its own git repository; AIKit's gates, map and ledger never read it.

python aikit.py new my-app          # projects/my-app/: new git repo + .aikit/ memory
python aikit.py attach ../existing  # register a folder elsewhere; adds only .aikit/ and .gitignore lines
python aikit.py list                # every project, its stack and test command
python aikit.py status my-app       # its task, open changes, last decision
python aikit.py check my-app        # its tests and configured checks, AIKit's guidelines, secret scan
python aikit.py fix my-app          # restore memory/README, refresh map, then check
python aikit.py guideline my-app "money is integer cents" --source user  # project rule
python aikit.py publish my-app      # own private GitHub repo, scanned first

A project's memory is its .aikit/ folder (record, ledger, decisions, guidelines: its own rules, ranked below the principles), committed in its repository; ledger commands take --workspace projects/<name>. The stack and test command are detected from its files on every call (Python, Node, Rust, Go, Java, .NET); --test "<cmd>" overrides.

📥 Alternative: Copy AIKit Into an Existing Project

Step 1: Copy Governance Assets

• Copy only the source of truth and tooling; the Tier 1 files are generated in Step 3, never copied:

  cd portable_agent_kit
  mkdir -p /path/to/target/.agents
  cp -r GUIDELINES.md scripts knowledge /path/to/target/
  cp -r .agents/rules .agents/skills /path/to/target/.agents/
  

  Do not copy tests/, .github/ or .agents/task_ledger.json (they are AIKit's own). Enforcement travels as the CLI gates in the command matrix above. Replace copied knowledge/ documents with your project's. Copy .agents/rules/readme_quickref.md.template into your README.md and replace <FILL placeholders.

Step 2: Move Your Own Agent Instructions into Tier 1B

If the target already has its own instruction files, move project-specific rules into .agents/rules/domain.md (max 1,200 chars), then delete the originals. Sync injects that block into every generated file. It never overwrites hand-authored files without a generated header ([PROTECTED]).

Step 3: Run Principle Synchronization

Generate every Tier 1 file from GUIDELINES.md:

python scripts/sync_principles.py

This writes all 8 Tier 1 files (AGENTS.md, CLAUDE.md, GEMINI.md, .cursorrules, .github/copilot-instructions.md, .windsurfrules, .clinerules, .agents/rules/principles.md), each <=1,600 tokens including Tier 1B.

Step 4: Generate Your Knowledge Base

Run the knowledge base AST scanner to automatically index your project's classes and functions:

python scripts/update_knowledge_base.py

This generates knowledge/codebase_map.md with every exported class, method, argument, and docstring.

🏛️ The 20 Core Principles (Lifecycle-Ordered)

The principles are strictly organized across 5 chronological execution phases:

🏛️ Phase 1: Meta-Governance & Attentional Grounding

🧭 Phase 2: Pre-Flight Orientation & Planning

🏗️ Phase 3: Architecture & Lean Implementation

🛡️ Phase 4: Operational Verification & Resilience

🚀 Phase 5: Living Synchronization & Delivery

⚡ Disruption Recovery & Power-Loss Protection

If electricity cuts out, battery dies, or the computer crashes mid-task:

1. Pre-flight Audit: On a cold start, run this one command first (PRINCIPLE-004 R2):

   python scripts/disruption_recovery.py --resume
   

   It prints every --audit finding, then the interrupted task, its plan and the phase to resume at. With no interrupted task it says "Ready" only when no uncommitted files exist.
2. Everything else (--audit, --checkpoint, --complete, --reset, --clean) is in the command matrix above; a task's first plan checkpoint must carry --why --benefits --risks --mitigation.
3. Atomic File Safety: state files are written to a temp file, fsynced and renamed (PRINCIPLE-013); a corrupt ledger is moved to *.corrupt_* and restored from its .bak.

🛠️ Adding New Principles to Your Project

1. Add ### PRINCIPLE-0XX: [Title] (the next free ID) to GUIDELINES.md only, with Problem, Concept, Invariant and numbered Rules, under the right lifecycle heading.
2. Raise MIN_PRINCIPLES in scripts/sync_principles.py and EXPECTED_PRINCIPLE_COUNT in tests/test_kit.py; add the ID to this README and both checklists.
3. Run python scripts/sync_principles.py. On [TOKEN EXCEEDED] or [TIER 1B HEADROOM], pay for the new capsule by condensing existing capsule narrative (PRINCIPLE-001 R9).
4. All 8 generated Tier 1 files then carry the new capsule.