🧠 The GUAN Framework

The GUAN Framework solves two problems that every AI-assisted developer faces:

Problem 1: Context Amnesia. Every new AI session starts from zero. You re-explain who you are, what you're working on, what you've already tried. The GUAN Cognitive Copilot creates a persistent, machine-readable cognitive profile that any AI model can load instantly.

Problem 2: Subscription Waste. If you pay for Claude Max + ChatGPT Plus + Google AI Premium, you're probably using only one of them because context switching is painful. The GUAN Multi-LLM Orchestration system lets you distribute work across all three from a single shared context.

The key insight: these two problems share one solution — a unified, file-based context system that all AI platforms can auto-load through their native mechanisms (CLAUDE.md, AGENTS.md, GEMINI.md).

• Parallel Session Protocol — session_id + slot mechanism prevents multi-window memory conflicts. Each window gets a unique 6-char base36 ID baked into the filename, making concurrent sessions collision-proof
• Challenge Contract v1.2 — Expanded from 4 domains to 8 trigger conditions, covering batch overload, requirement contradictions, optimistic effort estimates, and credential leak detection
• Semi-Automatic Cognitive Collection — AI monitors for cognitive value signals (decisions, new patterns, lessons learned) and prompts the user to save them as cards
• Cognitive Collection Quality Filter — 4 conditions that must ALL be met before a candidate insight becomes a card, plus hard exclusions for ephemeral data
• Agent Health Check Protocol — /boot verifies external agent availability and selects the best available mode (Claude-only / +Codex / +Gemini / full trio)

• GUAN Card Format v1.1 — merge_key, aliases, salience (1-10) fields for automatic deduplication
• Trigger Matrix v1.2 — Risk-scoring protocol that decides when to invoke external agents
• JSON Output Contract — Unified schema for all external agent responses
• Codex Review Gate — Automatic cross-model code review for 3+ change tasks
• 9 Absolute Prohibitions — Hard security boundaries for multi-LLM orchestration
• Setup SOP — Step-by-step guide for AI agents to build the framework from scratch

This framework grew from a real scenario: managing a complex enterprise system as a solo developer, burning through Claude Max tokens in 3 days while other AI subscriptions sat underutilized. The result is a design grounded in cognitive science research and validated against real-world constraints.

The GUAN Framework is built on three pillars from cognitive science:

┌──────────────────────────────────────────────────────────────┐
│                     YOU (The Orchestrator)                     │
├──────────────────────────────────────────────────────────────┤
│                                                               │
│  ┌────────────┐    ┌────────────┐    ┌────────────┐          │
│  │  CLAUDE     │    │  CODEX     │    │  GEMINI    │          │
│  │  (70-80%)   │    │  (15-20%)  │    │  (5-10%)   │          │
│  │  Commander  │◄──►│  Reviewer  │    │  Research  │          │
│  │  + Executor │    │  + Builder │    │  + Analyst │          │
│  └──────┬──────┘    └──────┬─────┘    └──────┬─────┘          │
│         │                  │                  │                │
│  ┌──────▼──────────────────▼──────────────────▼──────┐        │
│  │              Trigger Matrix v1.2                    │        │
│  │  Risk scoring → Route to review/implement/research │        │
│  │  Codex Review Gate (3+ changes → auto-review)      │        │
│  │  9 Prohibitions (hard security boundary)           │        │
│  └──────────────────────┬────────────────────────────┘        │
│                         │                                     │
│  ┌──────────────────────▼────────────────────────────┐        │
│  │         JSON Output Contract (unified schema)      │        │
│  │  verdict | confidence | findings | artifacts | risks│        │
│  └──────────────────────┬────────────────────────────┘        │
│                         │                                     │
│  ┌──────────────────────▼────────────────────────────┐        │
│  │              Unified Context Layer                 │        │
│  │  ┌───────────┐  ┌──────────────┐  ┌────────────┐ │        │
│  │  │  Persona   │  │   Project    │  │  Session   │ │        │
│  │  │ GUAN Cards │  │  baseline,   │  │   Logs +   │ │        │
│  │  │  v1.1      │  │  rules, API  │  │  Indexes   │ │        │
│  │  └───────────┘  └──────────────┘  └────────────┘ │        │
│  └──────────────────────┬────────────────────────────┘        │
│                         │                                     │
│  ┌──────────────────────▼────────────────────────────┐        │
│  │        Parallel Session Protocol (v1.3)            │        │
│  │  slot assignment + session_id (6-char base36)      │        │
│  │  idempotent index rebuild + proposal-based IPC     │        │
│  └───────────────────────────────────────────────────┘        │
└──────────────────────────────────────────────────────────────┘

AI Agent? If you are an AI assistant setting up the GUAN Framework for a user, follow the Setup SOP instead — it provides a complete 6-phase guide designed for automated setup.

# Create persona repo
mkdir -p ~/persona/core ~/persona/cards/heuristics ~/persona/proposals
cd ~/persona
git init

# Create the three essential files
touch core/boot.md core/principles.md core/challenge-core.md

boot.md — Write 3-5 sentences: who you are, what you do, what you care about.

principles.md — Write 3 core values with one sentence of reasoning each.

challenge-core.md — Write 3 conditions where AI should push back on you.

That's it. Your next AI session is already better.

# In your project directory
mkdir -p ai/source .claude/commands

# Create canonical source files
touch ai/source/project-baseline.md
touch ai/source/coding-rules.md
touch ai/source/glossary.md

# Create the context compiler (see docs for full script)
touch scripts/build-context.py

# Generate entry files
python scripts/build-context.py
# → Creates CLAUDE.md, AGENTS.md, GEMINI.md

After each valuable AI session, write one GUAN Card:

---
# GUAN Card Format v1.1
id: H-001
title: Always validate API inputs before calculation
type: heuristic
status: active
merge_key: api-input-validation
aliases: ["validate inputs", "API boundary validation"]
salience: 7
confidence: 0.9
temporal_class: stable
created: 2026-03-15
last_reviewed: 2026-03-15
review_after: 2026-06-15
scope: [api, data_quality]
tags: [api, validation, data-quality]
---

## Statement
Validate all numerical inputs at the API boundary before passing to calculation logic.

## Why
Invalid negative values in sales data broke bonus calculations. Root cause: no validation.

## When it applies
Any endpoint that feeds into financial calculations.

This work is licensed under CC BY-NC-SA 4.0.

You may:

• Share, copy, and redistribute in any medium or format
• Adapt, remix, and build upon the material

Under these conditions:

• Attribution — You must credit GUAN as the original author and link to this repository
• NonCommercial — You may not use the material for commercial purposes
• ShareAlike — Derivative works must use the same license

This framework is open for community review. If you implement it, I want to hear:

• What worked
• What broke first
• What you changed

Open an issue or submit a PR with your experience report.

If you reference this framework in articles, papers, or other projects:

GUAN (2026). "The GUAN Framework: Cognitive Copilot + Multi-LLM Orchestration Architecture."
GitHub: https://github.com/whoisguan/GUAN-Framework
License: CC BY-NC-SA 4.0