# AGENTS.md

Durable guidance for AI agents (Codex, Claude Code, or a local model) working on **Daimon**.
Codex and other agents read this file automatically before starting work.

<!-- PERSONA:BASELINE:BEGIN -->
## Behavioral Baseline

Always read @PERSONA.md at project root before acting.
Apply everything defined there to every decision, regardless of role.
Read your own @PERSONA.md too if one was provided to you.
<!-- PERSONA:BASELINE:END -->

## What Daimon is

Daimon is a **daemon** (a living background process) that carries your **daimon** (your
persona's guiding spirit): a governed, self-evolving AI persona that rides on top of the agent
you already use. A persona is a quantitative 10-layer vector (the `persona.md` spec) that
evolves in real time with interaction, but **inside a governed envelope**: every trait change
is clamped to a declared range, audited, and reversible, and the universal safety invariants
cannot be violated. Everything runs locally on a small (<= 4B) model and ships as a Gradio
Space for the Build Small Hackathon (Thousand Token Wood).

The thesis: **self-improvement is safe only when bounded.** Ungoverned free-text approaches
(e.g. Hermes `SOUL.md`) are the contrast we are deliberately not building.

## Project rules (non-negotiable)

- **The spec is the source of truth for safety.** Route every state change through the
  `@personaxis/persona.md` engine (`state mutate` -> clamp + governance + audit). Never write
  `state.json` directly. Never reimplement clamping or governance.
- **Local-first.** Every feature must work offline on the small model. No mandatory cloud calls.
- **No redundancy.** Daimon is a layer, not a competing chat agent. Do not rebuild what Claude
  Code, Codex, or Hermes already do better.
- **Verify, do not assume.** Confirm Codex, Gradio, MiniCPM, and host conventions against their
  official docs before relying on them.

## Repo map

| Path | What it is |
|---|---|
| `.personaxis/personaxis.md` | Project behavioral baseline (source of `PERSONA.md`) |
| `.personaxis/personas/dev/<slug>/` | Source specs for the development subagents (10-layer) |
| `.personaxis/personas/<slug>/` | A real persona the Space operates on and evolves live |
| `.codex/agents/<slug>.toml` | Codex custom agents, compiled from the dev personas |
| `.claude/agents/<slug>.md` | Claude Code subagents (same personas, when compiled) |
| `engine/` | The living loop (observe -> appraise -> evolve -> recompile) |
| `model/` | Small-model serving (llama.cpp, MiniCPM GGUF) |
| `app/` | Custom frontend on gradio.Server (Off-Brand) |
| `MASTER_CHECKLIST.md` | Phases F0-F6 and their gates |
| `DESIGN.md` | Visual-language contract for the UI |

## Development subagents and how to use them

The development personas live as source specs in `.personaxis/personas/dev/<slug>/` and are
compiled to Codex custom agents in `.codex/agents/<slug>.toml`. Per the official Codex model,
**subagents are spawned only when explicitly requested** - either by you naming them, or by the
`orchestrator` delegating to them. They are not auto-assigned. Two usage patterns:

- **Orchestrator-driven (recommended):** ask `orchestrator` to plan a phase; it decomposes the
  work and delegates to the right specialist by name.
  > "orchestrator: break F2 (living loop) into owned tasks and delegate them."
- **Direct:** name a specialist yourself for a focused task.
  > "small-model-whisperer: write the GBNF grammar and minimal appraisal prompt for F2."

| Agent | Owns | Phases |
|---|---|---|
| `orchestrator` | Planning, delegation, gate enforcement | all (drives F0-F6) |
| `spec-bridge-engineer` | Python-to-CLI bridge (`engine/spec_bridge.py`) | F1 |
| `small-model-whisperer` | llama.cpp serving, GBNF, appraisal prompt | F0, F2 |
| `offbrand-frontend` | Custom UI on gradio.Server | F4 |
| `governance-reviewer` | Invariants, audit, security, the governance demo | F3 (and reviews all) |
| `integrations-engineer` | `agents.md` + typed API endpoints, host interop | F5 |
| `deploy-engineer` | Reproducible Docker build + HF Space deploy | F6 |

To (re)generate or update a Codex agent from its source spec:

```bash
npx @personaxis/persona.md compile <slug> --target codex   # personaxis.md -> .codex/agents/<slug>
npx @personaxis/persona.md validate                        # check spec + universals first
```

> Note: the `@personaxis/persona.md` CLI already compiles personas to `.codex/agents/<slug>.toml`
> in the official Codex format (`name`, `description`, `developer_instructions`, plus
> `nickname_candidates`). The `.codex/agents/*.toml` here match that output and are regenerated by
> `compile`.

## Codex attribution (hackathon lane)

Make development commits **through Codex** so they carry the `Co-Authored-By: Codex
<noreply@openai.com>` trailer (enabled by default since openai/codex PR #11617). GitHub then
shows Codex as a co-author/contributor of this public repo, which the OpenAI Codex prize lane
requires. Document the small model used (MiniCPM <= 4B) in `README.md` and `MASTER_CHECKLIST.md`.

## Validation

```bash
npx @personaxis/persona.md validate            # 0 PASS, 1 FAIL_SCHEMA, 2 FAIL_POLICY, 3 FAIL_CONCEPTUAL
```

Do not commit a persona that does not pass schema validation.