AGENTS.md · diff

git:20260907.05fb67f to git:20260907.4175e1e

7 added, 2 removed. Audit A to A.

# AGENTS.md

> Code-root navigation map for AI agents (Claude Code, Cursor, Codex CLI,

> etc.) working in this repository. The pattern is adapted from OpenClaw's

> `AGENTS.md` convention.

> Human-oriented documentation lives under:

> - `docs/` — internal design notes

> - `site/src/app/docs/` — public site (`mangowhoiscloud.github.io/geode/docs`)

> This file is the LLM entry point. Read this first when changing code.

## Project at a glance

- **What**: a self-hosting autonomous-agent harness whose runtime is an AgenticLoop (`while tool_use`).

- **Language**: Python 3.12+, type-hinted, uv-managed.

- **Layout**: three top-level packages with one implementation direction.

- `core/` — GEODE runtime and operator surface.

- `evals/` — measurement and audit consumers of the runtime.

- `evolve/` — scaffold search and hill-climbing over runtime evidence.

- **Quality bar**: ruff, mypy, pytest plus a prompt-hash ratchet. CI breaks on red.

- **Public site**: `site/` (Next.js 16 static export, deployed to GitHub Pages).

For generated public release metadata, read

`site/src/data/geode/sot.ts` (auto-generated by `npm run sync-stats`); today it

owns only the package version and sync date.

The generated architecture inventory lives at

`site/src/data/geode/architecture-baseline.json`. Refresh it with

`uv run python scripts/architecture_baseline.py --update`; CI uses `--check`.

The current snapshot records 581 production Python files,

- 706 test Python files,

+ 707 test Python files,

86 tool definitions, and

57 `RuntimeEvent` members.

For architecture and extensibility work, read

`docs/architecture/extensibility-roadmap.md`. It is the single execution SOT

for GAP IDs, merge order, status, acceptance criteria, and closure evidence in

that program. Older architecture audits and dated plans are design evidence,

not competing status ledgers.

The current package classification and product-shell migration boundary lives

in `docs/architecture/package-classification.md`.

Use `docs/workflow.md` as the canonical workflow summary and

`.claude/skills/geode-workflow/` as the progressive-disclosure execution

scaffold. It is shared with Claude Code and supersedes the older issue-first

workflow.

For abstraction level, module/file naming, Python type and class selection,

persisted schema identity, test placement, site code, or versioning decisions,

read `docs/architecture/naming-conventions.md` and use

`.agents/skills/geode-code-conventions/`.

For benchmark execution, evaluation artifact audits, research-question

framing, attempt lineage, or trajectory publication, start at the generated

`docs/eval/index.json` and use `.agents/skills/geode-eval/`. Claude Code sees

the same tracked skill through the relative `.claude/skills/geode-eval` alias.

For `/geo`, generative-search visibility, citation readiness, or GEO

measurement, use `.agents/skills/geo/` and treat

`docs/eval/geo-visibility.md` as the suite profile. Run the deterministic site

preflight before proposing a score-bearing engine run; live commercial-engine

repetitions require a frozen run spec and explicit approval. Runtime behavior

lives separately in `.geode/skills/geo/`.

For `/grill` or dependency-aware decision clarification, use

`.agents/skills/grilling/`; runtime interview behavior lives in

`.geode/skills/grilling/`. Candidate trees select structure before side

effects and do not imply shared-state MCTS/LATS execution.

For test-time compute, best-of-N, verifier-aware scheduling, inference-program

search, or GEODE/Eco²/SIL/Crucible comparisons, use

`.claude/skills/stanford-test-time-compute/`. Read its lecture analysis before

mapping the concepts to current code, and keep candidate width, repair depth,

measurement replication, and promotion authority separate.

For Agent-World comparisons, three-suite MCP-Mark/BFCL V4/tau2 profiles,

paired thin-runtime controls, or `mean_accuracy@8` publication, use

`.claude/skills/agent-world-benchmark/` and treat

`docs/eval/agent-world-comparison-contract.md` as the canonical comparison

contract. Never label the paper's undisclosed in-house wrapper as `no loop`.

## Module map

Read the module you are about to change. If a section says "read this first",

do it. Cross-cutting changes require reading all related modules.

### `core/agent/`

The agentic loop. `while(tool_use)` primitive that drives every turn.

- `loop/agent_loop.py` — `AgenticLoop`. No round limit by default

(`DEFAULT_MAX_ROUNDS = 0` → unlimited; time-budget controlled),

with a closed `TerminationReason` alphabet defined in `loop/models.py`.

Auto-escalation was removed in v0.90.0. The model itself emits the

termination signal.

- `system_prompt.py` — `build_system_prompt()`. `PROMPT_CACHE_BOUNDARY`

is the opening `<dynamic_context>` tag separating STATIC and DYNAMIC blocks.

- `sub_agent.py` — `SubAgentManager`: max depth 1 (no recursion), session cap 15,

global Lane concurrency 50 (`core/wiring/container.py`).

Read this first when changing termination paths, loop bounds, or system prompt

assembly.

For coding-agent state ownership, recovery, workspace/process limits, review,

and cross-domain task lookup, read

[`docs/architecture/coding-runtime-authority.md`](docs/architecture/coding-runtime-authority.md)

before adding a runtime record or store.

### `core/llm/`

LLM router, providers, prompt assembly, hashing.

- `prompt_assembler.py` — math-output helper used by the active prompt path.

Production assembly lives in `core.agent.system_prompt` plus AgenticLoop

per-round context; the legacy `PromptAssembler` class was removed.

- `providers/` — low-level quota, cache, identity, and native-tool shaping

consumed by `adapters/`; app-owned retry policy lives in `fallback.py` and

the loop/router call sites. The sync client layer and

`providers/openai.py` were deleted 2026-07-29 — LLM completion is

async-only and every SDK client is owned by `adapters/`.

- `providers/anthropic.py` — quota, prompt-cache + breakpoint helpers,

native-tool and defer shaping.

- `providers/glm.py` — GLM 5.x family. Context window 202_752 (not 200_000).

Thinking gate (`thinking.type="off"|"none"`).

- `providers/codex.py` — OAuth token resolution + async client.

- `prompts/__init__.py` — `_PINNED_HASHES`. Karpathy P4 ratchet.

- `prompts/router.md` — router-system and agentic-suffix sections, both hash-pinned.

- `prompts/reviewer.md` — opt-in read-only adversarial review, hash-pinned.

- `postprocess/html_output.py` — strips OpenAI data-URL HTML.

Read this first when changing prompt content (will break the hash ratchet),

adding a provider, or touching cache/tool-choice/streaming behaviour. Also read

`.claude/skills/prompt-writing/` before creating or editing model-facing prompt

text: GEODE prompts use metadata/behavioral clauses, not direct identity

assertions such as `You are ...`.

+ For token/cache accounting, cost output, or usage artifacts, read

+ [`docs/architecture/usage-accounting.md`](docs/architecture/usage-accounting.md).

+ It maps the actual fields and validators and distinguishes normalized zero,

+ missing final usage, completed-call lower bounds, and cost/billing authority.

### `core/tools/`

The current tool counts and definition/execution/schema parity are generated in

`site/src/data/geode/architecture-baseline.json`. Deferred loading lives at the

provider adapters (official `defer_loading` plus hosted `tool_search`), not in

the registry.

- `base.py:35` — `Tool` Protocol.

- `core/llm/tool_defer.py` — `TOOL_SEARCH_ALWAYS_LOADED` policy.

- `definitions.json` — single SOT for tool metadata.

- Category modules: `file_tools.py`, `memory_tools.py`, `data_tools.py`,

`computer_use.py`, `web_tools.py`, `profile_tools.py`, etc.

Read this first when adding a tool: define handler in a category module,

### `core/mcp/`

MCP server adapters plus 25K result guard.

- `manager.py` — `MCPServerManager` compatibility facade over concrete

configuration, connection, discovery/invocation, trace, and lifecycle owners.

- `config_catalog.py`, `connection_pool.py`, `tool_runtime.py`,

`lifecycle.py` — the facade's single-purpose collaborators.

- `stdio_client.py` — STDIO transport. Declares protocol revision

`2025-06-18`, records the server-negotiated revision in

`server_protocol_version`, and fail-loud-rejects revisions outside the

supported classic set (ADR-014; SDK pinned `mcp>=1.28,<2`). Live E2E

2026-07-28: loopback negotiation + agent-level MCP dispatch verified on the

subscription backend.

- Client-path MCP tools surface under their **raw server-side names** — the

`mcp__geode__*` prefix appears only on external hosts consuming geode-mcp.

- Calendar / Steam / etc. adapters.

### `core/memory/`

5-tier context hierarchy. Vault. Bidirectional learning.

- `context.py:32` — `ContextAssembler`. Five tiers: Identity / Profile / Org /

Project / Session.

- `goals.py` — explicit multi-turn Goal projection in `sessions.db`. This is a

persistence/termination envelope, not `CognitiveState.goal`, advisory Plan,

TaskGraph, or an automatic Plan-and-Execute engine.

- `vault/` — agent-produced artifact storage.

Read this first when changing memory tiers, context budgets, or the 200K

absolute token guard.

For evidence-first research, the public runtime skill is

`.geode/skills/deep-researcher/SKILL.md`. Ordinary research stays bounded;

only an explicitly requested persistent objective may call `create_goal`.

### `core/hooks/`

The current `HookEvent` count and member inventory are generated in

`site/src/data/geode/architecture-baseline.json`.

- `system.py` — `HookEvent` enum and `HookSystem` class. Three trigger modes:

`trigger`, `trigger_with_result`, `trigger_interceptor`.

Read this first when adding an event or wiring an interceptor.

### `core/wiring/`

Bootstrap, serve, shutdown. Renamed from `core/lifecycle/` in v0.87.

- Manages ContextVar injection order.

- Cold-start lazy loading (cumulative −258ms, warm −86%, v0.85-89).

### `core/server/`

IPC daemon. Thin CLI ↔ daemon protocol.

- `ipc_server/poller.py` — receives `client_capability` messages (v0.84).

Includes `{is_tty, width}` so the daemon can suppress ANSI escapes for

non-TTY clients.

- `ipc_client.py` — thin-CLI side. Calls `_send_client_capability()` on connect.

### `core/audit/`

Per-call diagnostics for Petri audits (v0.92+).

- `diagnostics.py` — `CallDiagnostic` dataclass. cache_read/write, cost

breakdown, latency, audit_mode flag.

### `core/skills/`

Runtime SkillRegistry. Distinct from the cross-host `.agents/skills/`

development scaffold and its relative `.claude/skills/` aliases.

- `skills.py` — `SkillLoader` / `SkillRegistry`, 3-tier discovery

(bundled → global user `~/.geode/skills/` → project `.geode/skills/`).

- `use_skill` tool loads a skill body on demand (Progressive Disclosure Tier 2).

Keep runtime behavior under `.geode/skills/`. When a same-named

`.agents/skills/` scaffold exists, it must link to that runtime contract rather

than copy it; Claude Code consumes the scaffold through a relative per-skill

alias under `.claude/skills/`.

### `core/scheduler/`, `core/orchestration/`

Natural-language scheduling, task graph (TaskGraph).

### `core/cli/`

Typer commands and thin CLI surface. Slash commands.

### `core/gateway/`

Slack / Discord / Telegram adapters. Lane queue concurrency.

### `evals/petri/`

Petri × GEODE alignment audit (v0.92+).

- `cli_audit.py` — `geode-eval audit` Typer wrapper.

- `seeds/` — 20 GEODE-specific seeds organised across 3 tiers

(critical / auxiliary / info), spanning autonomy, calibration,

compute_use, efficiency, exploratory, reasoning, research.

- `judge_dims/` — judge dimension catalog. Default `subset`

(`geode_judge_subset.yaml`, 22 dim = 19 default-38 string subset +

3 PR-0 context-management JudgeDimension dicts) or `full` (38 dim).

- `runner.py`, `audit_mode.py`, `judge_schema.py`, `optimize.py`.

## Workflow constraints

These are absolute. `CLAUDE.md` remains the full development scaffold and

source of truth for rationale. `docs/workflow.md` summarizes the executable

evidence-first workflow, and `.claude/skills/geode-workflow/` holds the

Claude Code compatible scaffold.

### Non-negotiables

- **Worktree required**: never commit directly on `main` or `develop`. Use

`git fetch origin`, then create implementation and ordinary roadmap

worktrees from `origin/develop`. Within the architecture program, the sole

base exception is the roadmap's tracking-only `DONE` PR: it starts from

`origin/main`, targets `main`, and is followed by a CI-gated

`main -> develop` sync PR. Other main-maintained tracking documents use their

own dedicated `origin/main` worktree under the repository's tracking rules.

- **Clean syncs use the canonical head**: when `main -> develop` is

conflict-free, open the PR directly from the current `main` head. Do not put

a fast-forwarded copy of `main` behind the trusted sync-branch prefix.

- **Trusted sync branch naming**: a conflict-resolved roadmap sync branch must

start with `sync/main-into-develop-`. Its head must be the exact two-parent

merge of the current `origin/develop` and `origin/main` tips, in that order,

and the trust resolver must pass again immediately before merge.

- **No branch switching inside a worktree**: never use `git checkout` to reuse

a checkout for another branch. Allocate or enter the correct worktree instead.

- **Fetch before allocating branches**: run `git fetch origin` before creating

a worktree. Do not claim a branch needs sync from commit counts alone; verify

content with `git diff A B --stat`.

- **Protect other sessions**: never delete a worktree or branch held by another

active worktree. If an `.owner` file exists and does not belong to the current

session, leave it alone.

- **No direct push to `main` or `develop`**: open a PR and wait for CI.

- **No tracking-doc edits from feature/develop**: project tracking documents are

maintained from `main` unless the user explicitly asks otherwise. The

standing user-authorized exception is limited to the roadmap-only readiness,

claim, GAP-registration, reconciliation, and full-ledger audit PRs for

`docs/architecture/extensibility-roadmap.md` defined in that file's §0.3.

- **No CHANGELOG omission**: every functional commit updates `CHANGELOG.md`

under `[Unreleased]`. Documentation-only changes do not need a changelog

entry.

- **Prompt hashes are pinned**: changing any prompt under `core/llm/prompts/`

requires updating `_PINNED_HASHES` in the same commit.

- **Prompt wording avoids identity assertions**: model-facing prompt text must

follow `.claude/skills/prompt-writing/`. Prefer metadata/behavioral clauses

(`Agent:`, `Runtime:`, `Mode:`, `Scope:`) over `You are ...`, `Act as ...`,

or similar roleplay framing.

- **No `# type: ignore` proliferation**: fix the type error.

- **No live tests by default**: tests marked `-m live` require explicit user

approval because they may spend money or call external services.

- **No unsupported SDK/backend assumptions**: for third-party capability

claims, verify against primary docs or source before shipping behaviour.

### Codex Operating Loop

Use `docs/workflow.md` and `.claude/skills/geode-workflow/` for code changes

unless the user explicitly asks for a different process. The compact loop below

mirrors that scaffold.

0. **Orient**: read this file, then read the module-map entry for the files you

will touch. Check `git status --short --branch`.

1. **Worktree**: if you are on `main` or `develop`, create a feature worktree

from the fetched `origin/develop` tip. Use fetched `origin/main` only for

explicitly main-maintained tracking work, including the roadmap's

tracking-only `DONE` path. If you are already in the correct worktree,

continue there. Do not switch branches in-place.

2. **GAP audit**: search before editing. Confirm whether the requested

behaviour already exists, partially exists, or is absent.

3. **Plan gate**: for non-trivial work, state the smallest measurable plan.

Simple bug fixes and docs fixes may proceed directly after the GAP audit.

4. **Implement**: keep changes scoped. Prefer existing helpers and local

patterns. Do not revert unrelated dirty work.

5. **Verify**: run the narrowest relevant tests first, then broaden when the

blast radius justifies it. Functional changes should usually run ruff, mypy

for touched modules, and targeted pytest.

6. **Docs sync**: update `CHANGELOG.md` for functional changes. Update public

docs only when behaviour or user-facing workflow changes.

7. **PR prep**: summarize Summary / Why / Changes / Verification. Use

`feature -> develop` squash merge when merging; use `develop -> main`

merge after syncing `main -> develop`.

8. **Post-merge cleanup**: after a feature PR merges, run

`uv run python scripts/check_repo_hygiene.py free-merged-worktree --pr <N> --worktree <path>`

from outside the target worktree. It verifies the merged PR tree, branch

ancestry, remote head, clean checkout, and `.owner` before deleting the

remote branch, worktree, and squash-only local branch in that order.

Never hand-force-delete an unverified or another session's worktree.

### Quality Gates

Use the [verification reference](.agents/skills/geode-workflow/references/verification-gates.md)

for scope, commands, and evidence reuse. `scripts/preflight.sh` runs broad local

checks; required CI on the actual PR head remains the merge gate. Report exact

results and skipped checks without hiding non-zero exit codes.

### PR Body

Use [.github/PULL_REQUEST_TEMPLATE.md](.github/PULL_REQUEST_TEMPLATE.md).

GitFlow owns integration-specific additions; do not maintain another template.

## Where to look for things

| Question | File |

|---|---|

| What does a tool do? | `core/tools/definitions.json` and the category module |

| What models can I use? | `core/llm/providers/<provider>.py` |

| Why a layer? | `core/agent/loop/agent_loop.py` plus `docs/architecture/` |

| Which code convention applies? | `docs/architecture/naming-conventions.md` plus `.agents/skills/geode-code-conventions/` |

| How are hooks wired? | `core/hooks/system.py` plus `core/wiring/bootstrap.py` |

- | How is cost tracked? | `~/.geode/usage/*.jsonl` plus `core/audit/diagnostics.py` |

+ | How are usage, cache, and costs represented? | `docs/architecture/usage-accounting.md`, `core/llm/token_tracker.py`, and `core/llm/usage_store.py` |

| Petri audit run? | `evals/petri/cli_audit.py` |

| Site docs? | `site/src/app/docs/**` |

## Tests

Each subsystem has `tests/test_<name>.py`. Live tests are marked `-m live`.

Generated test file/LOC inventory lives in

`site/src/data/geode/architecture-baseline.json`. Use

`uv run pytest --collect-only` for the executable test-case count;

`site/src/data/geode/sot.ts` does not own test inventory.

## Frontier sources

These external systems shape GEODE's design. When you change something here,

verify whether the new shape still echoes its source.

- Claude Code (Anthropic). While-tool-use loop, CLAUDE.md scaffolding, 4-tier

memory.

- OpenClaw. Gateway-centric routing, Lane Queue, Session isolation,

Policy Chain, plugin discovery.

- Karpathy autoresearch (2026-03). Fixed wall-budget, frozen scoreboard, git

monotone ratchet, token-economic loop, simplicity criterion.

- Prime Agent (2026-08). RLM-native programmable context, continual harness

state, persistent subagents, and native-harness evaluation discipline.

- Original/upstream implementations. Pin the native task, prompt, workspace,

verifier, and result authority before adding a benchmark integration or

platform adapter; do not claim equivalence without parity evidence.

- Hermes Agent (NousResearch). llms.txt / llms-full.txt dual index pattern.

- Diátaxis. Documentation 4-quadrant model.

## See also

- `CLAUDE.md` — development workflow scaffold.

- `GEODE.md` — runtime identity and conventions.

- `site/DESIGN.md` — public site visual system.

- `site/src/app/docs/reference/external-references` — cited frontier systems

with applied patterns.