AGENTS.md

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.

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.

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:

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

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.