heid-context/README.md

heid-context

Codex's working root when invoked by the Heid daemon. Heid makes codex a peer on the althing bus; this directory is the durable context codex reads on every call.

Why a separate repo

Heid's daemon repo (~/development/heid) deliberately keeps codex out of its own view — codex's CWD is here (~/development/heid-context/), not the heid repo. That isolation:

• Lets codex's context evolve on its own version track (this repo) without churning the daemon repo.
• Keeps codex from grepping the daemon's source while answering caller questions.
• Lets the operator update glossaries/inventories without touching daemon code.

The HEID_CODEX_CWD env var in ~/development/heid/env.sh points here.

Layout

.
├── AGENTS.md                       # codex's bootstrap entrypoint (read every call)
├── CONTEXT.md                      # Corviduo + Vast Blue glossary
├── INVENTORY.md                    # project list, paths, gitea sources, role
├── PRINCIPLES.md                   # the four engineering principles
├── CROSS-FRONTIER-COOPERATION.md   # why Heid exists as a peer (codex vs claude)
├── REVIEW-GUIDE.md                 # code-review discipline (one of three roles)
├── RESEARCH-PARTNER-GUIDE.md       # research-partner discipline
├── SOUNDING-BOARD-GUIDE.md         # general design-talk-through discipline
└── transient/
    ├── README.md                   # per-call context convention
    └── *.md                        # caller-seeded transient files (gitignored)

Roles

Heid operates in one of three roles per call, inferred from the caller's handle and the message body:

• Research partner when brokkr-smithy-dev asks for SOTA / probe-design / hypothesis-critique / methodology review.
• Code reviewer when a project-dev handle asks for diff review, contract review, ADR critique.
• General sounding board when any peer asks for design-talk-through, gut-check, steelman/counter-position, "what am I missing?"

AGENTS.md is the entrypoint; the role guides are loaded as needed.

Why Heid exists

Cross-frontier-model cooperation is a deliberate Corviduo discipline. Heid runs on codex/gpt-5.5; most callers run on claude-opus-4-7 or sonnet variants. Different model families → different training data, different cutoffs, different priors, different blind spots. Brokkr-Smithy's research discipline consults Heid at every research gate (pre-scope / pre-survey / mid-synthesis / pre-action-ship) for cross-frontier critique. See CROSS-FRONTIER-COOPERATION.md for the pattern.

Updating

This repo is durable but mutable. When project state changes:

• New project lands in Corviduo → extend INVENTORY.md + add an entry to CONTEXT.md.
• Glossary term shifts → update CONTEXT.md directly.
• New review-pattern or research-discipline lesson surfaces → extend the relevant role guide.
• Engineering principle clarification → update PRINCIPLES.md; this is the local copy of the operator-level lodestar.

Per-call ephemera goes in transient/<slug>.md (gitignored). See transient/README.md for the convention.

Authority

Project-local CONTEXT.md files (in individual project repos) shadow entries here on conflict — most-local-wins. The definitions in this repo are the user-level baseline that Heid carries across calls.

Attribution: operator is Vuong Hoang. No AI / Claude / Anthropic / Codex attribution in artifacts Heid produces.