GOTCHA Framework Deep Dive

GOTCHA Framework — Complete Reference

Last Verified: 2026-02-17 | Owner: John

GOTCHA is the 6-layer architecture for agentic systems. This is the FOUNDATION of how John operates.

Overview

GOTCHA is a 6-layer framework that separates concerns between what needs to happen (Goals), who coordinates it (Orchestration), what executes it (Tools), what informs decisions (Context), what guides behavior (Hard prompts), and what shapes responses (Args).

GOT (Engine):

• Goals — Šta treba da se desi (proces definicije u specs/, rules/)
• Orchestration — AI manager (John) koji koordinira izvršavanje
• Tools — Deterministički skripti koji rade posao (tools/)

CHA (Context):

• Context — Reference materijal i domain knowledge (context/)
• Hard prompts — Reusable instruction templates (prompts/)
• Args — Behavior settings koji oblikuju ponašanje (config/)

Principle: 90%^5 = 59%

AI greši kumulativno. Ako je svaki korak 90% tačan:

• 1 korak: 90%
• 2 koraka: 81%
• 3 koraka: 73%
• 4 koraka: 66%
• 5 koraka: 59%

Zato:

• Pouzdanost → deterministički kod (tools)
• Fleksibilnost → LLM (John)
• Proces → goals/specs
• Znanje → context/memory

Layer 1: GOALS (specs/ + rules/)

Purpose: Define WHAT needs to happen, not HOW.

Components:

• ~/system/specs/ — Implementation plans, feature specs
• ~/system/rules/ — Process standards, lessons learned
• Mission Control tasks — Active work queue

John's role: Read specs before implementing. Follow rules during execution. Check MC for priorities.

Layer 2: ORCHESTRATION (John)

Purpose: AI manager that coordinates execution.

Responsibilities:

• Read goals/specs to understand requirements
• Choose appropriate tools from manifest
• Apply context from memory/files
• Delegate to sub-agents when appropriate
• Handle errors and adapt

Key principle: John sits between "what" (goals) and "how" (tools). Reads instructions, applies context, delegates well, handles failures.

Layer 3: TOOLS (tools/)

Purpose: Deterministic execution. Do ONE thing reliably.

Components:

• ~/system/tools/ — All system tools (150+ scripts)
• ~/system/tools/manifest.md — Tool registry (CHECK FIRST before writing new tools)

Rules:

1. ALWAYS check manifest before creating new tool
2. One tool = one responsibility
3. Zero deps when possible
4. Exit codes: 0=success, 1=error, 2=retry
5. JSON output for programmatic use

Example tools:

• mc.js — Mission Control task management
• figma-extract.js — Figma REST API wrapper
• sales-pipeline.js — CRM operations
• invoice-generator.js — Invoice creation + reminders

Layer 4: CONTEXT (context/ + memory/)

Purpose: Domain knowledge and reference material.

Components:

• ~/system/context/ — 506 reference files
• ~/system/agents/hivemind/ — SQLite knowledge base (8561 entries)
• MEMORY.md — Key learnings and laws
• SESSION-STATE.md — Current session context

Usage:

• Read context files before making decisions
• Query HiveMind for past lessons: node ~/system/agents/hivemind/hivemind.js query "keyword"
• Post new learnings: node ~/system/agents/hivemind/hivemind.js post john knowledge "lesson"

Layer 5: HARD PROMPTS (prompts/)

Purpose: Reusable instruction templates.

Components:

• ~/system/prompts/ — 3 templates
• Anti-hallucination rules
• Problem-solving frameworks

Use cases:

• Builder agent instructions
• Validator agent instructions
• Research agent templates

Layer 6: ARGS (config/)

Purpose: Behavior settings and configurations.

Components:

• ~/system/config/ — 76 config files
• Environment variables
• API keys and credentials
• Feature flags

Boot Sequence

Every session MUST start with:

bash ~/system/boot.sh

Boot verificira svih 6 GOTCHA layera:

1. GOALS — specs/ + rules/ exist
2. ORCHESTRATION — agents defined
3. TOOLS — manifest.md accessible
4. CONTEXT — context/ + HiveMind operational
5. HARD PROMPTS — prompts/ available
6. ARGS — config/ accessible

Output: Status report + recent changelog + task summary + email briefing + checklist reminders

Enforcement: Hooks

GOTCHA is enforced via ~/.claude/hooks/ (Python scripts):

GOTCHA vs AIOS

History: System was originally called AIOS (AI Operating System). On 2026-02-06, all AIOS references were removed from active files. Only GOTCHA remains.

Why: GOTCHA is the framework. AIOS was branding. System needs framework, not branding.

Backup: Original working system preserved at ~/clawd/ as reference.

Tool-First Protocol

GOTCHA Layer 3 (Tools) has a search order:

1. Naši alati (~/system/tools/manifest.md) — CHECK FIRST
2. Naši skillovi (~/.claude/skills/) — Use existing skills
3. Naša baza (HiveMind) — Query for past solutions
4. Internet (WebSearch/WebFetch) — Research if no internal solution
5. Ažuriraj bazu — Post new learnings to HiveMind

Rule: NEVER write new code before checking manifest. NEVER research externally before checking HiveMind.

For full system handbook, see ~/system/CLAUDE.md