Spaces:
Running
Running
| # 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. | |