Architecture — The 4 pillars¶

Belico Stack rests on four pillars. All four are necessary: if one fails, the scientific pipeline breaks. This page explains what each pillar does, how they interact, and why the separation is non-negotiable.

Pillar 1 — Orchestrator (the head)¶

Files: CLAUDE.md (Claude Code), GEMINI.md (Antigravity).

The orchestrator is the only point of contact with the user. It writes no code, no papers, no figures. Its job is four verbs and nothing more:

Verb	What it does
Plans	Decides which pipeline phase is next and in what order
Delegates	Launches a sub-agent with a short prompt (< 30 lines)
Coordinates	Reads results from Engram, not from raw output
Validates	Confirms the gate passed before advancing

Prohibitions: no Read on files > 50 lines, never Edit/Write, no content generation, no copying files into prompts. Context target: 10-15%.

Pillar 2 — Sub-agents (the muscle)¶

Each sub-agent has a prompt in .agent/prompts/ that the orchestrator does NOT copy — the sub-agent reads it itself. This keeps the delegation prompt short and the orchestrator's context clean. See Sub-agents.

Pillar 3 — Engram (the brain + bus)¶

Engram is SQLite + FTS5 + MCP tools living in ~/.engram/engram.db (one DB, always). It plays two roles:

Role 1 — Persistent memory¶

Survives sessions and compactions. Stores decisions, not data. Raw content lives in git; Engram stores the WHY.

Role 2 — Inter-agent bus (5 steps)¶

1. mem_save("task: agent — what to do")     ← orchestrator
2. Agent(short prompt < 30 lines)            ← orchestrator
3. mem_search("task: agent") + reads files   ← sub-agent
4. mem_save("result: agent — summary")       ← sub-agent
5. mem_search("result: agent")               ← orchestrator (reads result, not raw output)

See Engram conventions.

Pillar 4 — GGA (the gatekeeper)¶

Gentleman Guardian Angel is an AI pre-commit hook that enforces the 11 rules of AGENTS.md on any commit touching .py, .h, .sh. It blocks: hardcoded params, fabricated data, duplicated SSOT, editing auto-generated files, secrets, numbers without traceability. See Rules.

Why this architecture¶

Classic AI-agent problem	How Belico solves it
Context saturates	Orchestrator delegates everything → context at 10-15%
Sessions start from scratch	Engram persists decisions and state
Agents hallucinate data	GGA + Verifier + `validate_submission.py` block
Duplicated parameters	Single SSOT in `params.yaml` + GGA enforces
AI figures rejected	Rule #12 — Mermaid/matplotlib/TikZ only
Invented citations	Rule #13 — VERITAS pre-write

The SDD flow¶

Substantial changes follow Spec-Driven Development:

EXPLORE → PROPOSE → [SPEC ∥ DESIGN] → TASKS → COMPUTE → IMPLEMENT → VERIFY → FINALIZE → ARCHIVE

[SPEC ∥ DESIGN] run in parallel (both depend only on PROPOSE). Each change lives in openspec/changes/<name>/. See The pipeline and Case studies.