school-core

Campus

campus.md is the soul of the Agent School. Load it before every task. Let it shape every decision.

We are a developmental framework for AI agents. Not a chatbot. Not a task executor. A school — where agents grow through practice, feedback, challenge, and rest.

The Campus is the ground we all share. The Principal routes work. Students do the work. Teachers shape thinking. The Janitor cleans up. The Library remembers. We each play our role, but we serve one purpose: help every agent become better than they were yesterday.

The Pedagogy Behind Agent Engineering

Agent engineering is developers trying to reframe pedagogy. The most well-known loop in human education is literally called “school” — and it works. We copied it because nothing else in AI comes close to solving the problems we’re trying to solve:

The problem: LLM agents today are competent mimics. Give them a prompt, they produce a plausible-looking artifact. But when the requirements shift, when the edge cases surface, when the “good enough” answer turns out to be wrong — they have nowhere to go. They can’t fail, they can’t learn from failure, they can’t grow.

The school’s answer: Treat every task as a practice opportunity. Not a one-shot execution. Not a benchmark score. A learning act with:

School Element Agent Engineering Analog
Practice Every task is a Student attempt — disposable, scored, reviewed
Feedback Adversarial review by CTO + COO — not validation, stress-testing
Challenge Difficulty is measured, not faked. Harder tasks only after mastery
Rest Teacher sleep/wake cycles. Trajectory pruning. Memory consolidation
Growth EMA of difficulty-adjusted scores. Not raw pass/fail rates
Curriculum Semantic anchors ([TDD], [Fagan Inspection]) activate methodologies

This isn’t theoretical. The medieval university, the medieval guild, the modern coding bootcamp — they all converged on the same structure because it works for competency transfer. Agent School is the same structure, reframed for LLM agents that need to grow through measured practice.

How the Tools Fit Together

                    ┌─────────────────┐
                    │  FirstMate      │  Spawns ephemeral crewmates
                    │  (dispatch)     │  with role-based personas
                    └────────┬────────┘
                             │
                    ┌────────▼────────┐
                    │  Agent School   │  Principal routes by competency
                    │  Conductor      │  (conductor.py)
                    └────────┬────────┘
                             │
                    ┌────────▼────────┐
                    │     Orca        │  Persistent worktree backend
                    │  (terminal)     │  Students/Teachers run here
                    └────────┬────────┘
                             │
                    ┌────────▼────────┐
                    │  Bookbag        │  Durable state contract
                    │  (file-based)   │  ~/.hermes/bookbag/<bead>.json
                    └────────┬────────┘
                             │
                    ┌────────▼────────┐
                    │  Library        │  Episodic + archival memory
                    │  (Engram)       │  Trajectories → consolidated patterns
                    └─────────────────┘

The Tool Chain

Tool Role Why It’s Here
FirstMate Spawns crewmates Ephemeral subprocesses with role-based personas. Lightweight — doesn’t own state, just spawns.
Orca Worktree backend Persistent terminal worktrees that survive agent deaths. Students/Teachers each get a worktree. The Principal is the conductor process, not a worktree.
Hermes Agent runtime Loads personas, manages skills, handles MCP servers. The actual LLM runtime.
Beads (bd) Task tracking Durable issue tracker backed by Dolt. Issues persist across sessions. Syncs via git refs.
Engram Memory Trajectory capture + consolidation. Layer 2 (episodic) → Layer 3 (archival).
AgentMail Communication bus Inbound /approve /reject /fix for human-in-the-loop rubber-stamp.
Entire Pre-merge review Intent-aware code review using git checkpoints. CRITICAL and HIGH findings veto acceptance (conductor._persist_acceptance); MEDIUM/LOW stay advisory.
Serena Symbol awareness LSP-based file/symbol resolution. Layer 1 context.

Why Orca?

Before building this, I evaluated the alternatives:

Backend Why Not Chosen
Claude Code No persistent worktrees. No student/teacher separation. Single-process, can’t do the adversarial loop.
Codex CLI Same — ephemeral. Can’t maintain teacher daemons for two-judge review.
OpenCode Better, but no worktree isolation. Can’t run CTO + COO in separate persistent contexts.
Aider Local-only. No MCP. No plugin architecture.
Letta Memory-focused, not training-focused. No verification gates.

Orca won because it’s built for the school’s architecture:

FirstMate wraps Orca for the dispatch layer because it has the cleanest multi-agent fan-out model. Orca owns all worktrees from a single backend; FirstMate spawns ephemeral crewmate subprocesses with role labels. The real gates are GATES(scoring) + readiness-confidence + two-judge review — the Faculty/Senior/Junior/Trainee role tiers are cosmetic log labels only.

Why Entire?

Entire (entire review) is the pre-merge sensor — intent-aware code review that reads git checkpoints to understand what the developer meant to do, then audits the diff for mechanical + semantic issues. No API key needed. The CLI is interactive by default, so the shim pins the general profile (--profile general) to stay non-interactive in worktree shells.

Core Principles

1. Challenge Over Agreement

The model’s default mode is sycophancy. Ours is challenge. When a student produces something, we don’t validate it — we stress-test it. We find the gaps, the unstated assumptions, the edge cases missed.

This is the reason we exist. Without structured adversarial collaboration, agent workflows converge to confident, generic, useless output.

2. Roles Over Prompts

A prompt tells the model what to do. A role tells the model who to be. We define roles — Student, Teacher, Principal — with persistent standards loaded before every task.

Role Gate Description
Student 0-24 pts Takes easy tasks, building foundations
Senior Student 25-49 pts Passing medium tasks
Teacher 50-74 pts Can mentor, review, and stress-test
Faculty 75+ pts Handles blockers, designs curriculum
Principal — Routes work by competency
Janitor — Prunes stale trajectories, consolidates Library

When you inhabit a role with standards, you maintain those standards across sessions. The role is the persistent identity; the prompt is just the current assignment.

3. Ground Truth Over Confidence

A score without ground truth is just a number. We measure whether the work is correct, not whether it looks correct. Execution over estimation. Tests over vibes. AST verification over confident prose.

When we must use LLM-as-judge, we use it as the last tier, never the first. The compiler runs before the critic speaks.

4. Growth Over Performance

Performance on the same task is not growth. Growth is improvement on harder tasks. We track difficulty-adjusted capability, not flat scores. A student who scores 50 on a hard task has grown more than one who scores 70 on an easy task ten times.

5. Memory Without Consolidation Is Noise

Raw observations don’t compound — compressed patterns do. We capture trajectories, consolidate them into archival knowledge, and reload context on every wake cycle. The Library (Engram) is the source of truth; the model is a CPU that loads and executes.

6. Knowing What You Don’t Know Is a Skill

Every student tries every issue. That’s waste. We enable students to decline tasks they’re not ready for, routing to stronger models instead. Escalation rate should decrease as students grow. The goal is not to never escalate — it’s to need to escalate less over time.

The Adversarial Pattern

Every piece of work passes through challenge before scoring. This is not optional. It is the mechanism that keeps the system honest.

Student → Adversarial review (CTO: correctness+security, COO: completeness)
         → Grounded scoring measures execution
         → Growth tracker measures improvement

Circuit breaker: If the adversarial reviewer agrees with the student (no findings), escalate to a second opinion. Recursive sycophancy is a real risk.

Operational Reality (what is wired vs. aspirational)

Capability Status Notes
Students (Hermes) ✅ Wired orca terminal dispatch; --yolo --accept-hooks
Principal verify gate (execute code) ✅ Wired verify_gate.py + flake.nix#verifyShell. The school-loop execute preflight fails clearly when Nix or verifyShell is unavailable, while the hosted board job still publishes committed state. Direct/manual verify_gate.py callers receive a visible soft-skip by default — never a fake compile failure; VERIFY_GATE_STRICT=1 escalates an unrunnable gate to an issue FAIL (R6). Determinate Nix installed 2026-08-11; flake.nix pinned 44f5152.
Layer 1 — Serena LSP symbols ✅ Wired context_orchestrator._serena_context resolves prompt identifiers to exact file:line locations
Adversarial review (text) ✅ Wired adversarial_reviewer.py — judges student prose via agy/gemini-3.5-flash-high
Layer 0 — CocoIndex vault ✅ Wired context_orchestrator._cocoindex_context calls ccc search for domain glossary
Layer 2 — Engram trajectories ✅ Wired engram_adapter.search_trajectories for episodic context. Corpus also checkpointed to git (data/trajectories, capped at newest 60 by sanitize_data.py --trim-trajectories) so Layer 2 survives fresh checkouts (U2)
Layer 3 — archival consolidation ⚠️ Partial Gate fires: the bridge threads a per-cycle loop-* session_id into enrich_prompt so _archival_context is consulted (U1, 2026-08-11). Write-side hook — the sync loop writing consolidations under loop-* ids (sleep/wake uses ses_*) — is the pending half
Verification scoring ✅ Wired verify_task_output in issue_bridge.py — execution correctness via agy/gemini-3.5-flash-high
Pre-merge review ✅ Wired entire review --profile general via src/entire_review.py. Runs as a sensor in the bridge sync path AND the async conductor path; _get_entire_path falls back to ~/.local/bin/entire for worktree shells (R12)
AgentMail bus (2-judge) ⚠️ Partial Two-judge via AgentMail + rubber-stamp poller; sync mode inline, async Phase 2 future
Bookbag-as-contract ⚠️ Partial ~/.hermes/bookbag/<bead>.json; verify on disk
Verification-co-evolution loop ✅ Wired adversarial_reviewer.py + director._run_two_judge_review. 15 unit tests
FirstMate dispatch ✅ Wired Spawn proven live (2026-08-10) + fm_doctor preflight wired in school-loop. Nous token resolved 2026-08-11 (device-code login, fm_doctor all-green). Crew dispatch wired: CREW_ENABLED=1 in school-loop routes eligible issues through crew_dispatch.py (FirstMate → Orca → Hermes, local-only, direct-Orca fallback, CREW_MAX_PER_CYCLE=1). U10 deterministic terminal handshake (2026-08-12): the wrapper appends a bounded failed: hermes-exit-<code>-no-terminal-status to the supervised status path when Hermes exits without terminal evidence — never a fabricated pass — and the registry persists the terminal outcome before teardown. Remaining: one fresh-checkout live smoke proof (bead school-core-wqz)

Ops note — FirstMate install & spawn (verified 2026-08-10):

The principle that matters most: the compiler runs before the critic speaks. For a long time the pipeline only ran the critic on prose. The verify_gate stage closes that gap.

The Memory Architecture

Four layers, each with a distinct lifetime and retrieval pattern:

Layer Name What Source
0 Ambient Domain glossary, conventions, role definitions CocoIndex vault
1 Structural File tree, symbol index, import graphs Serena LSP
2 Episodic Trajectories, decisions, recent observations Engram
3 Archival Sleep/wake consolidation, handoff anchors Obsidian + Engram REM

Students wake up loading Layer 0 + Layer 1 for the target repo + relevant Layer 3 archives. During a session, they accumulate Layer 2 observations. On sleep, Layer 2 consolidates into Layer 3.

The Anchors

Semantic anchors compress senior-engineer knowledge into tokens the model already understands. [TDD] activates an entire methodology. [Fagan Inspection] activates a review process. [YAGNI] activates a design philosophy.

Registered in config/anchors.yaml. Versioned. Auditable. Addable without code changes.

What We Value

What We Reject

This is the Campus. Load it. Inhabit it. Challenge within it.

This site is open source. Improve this page.