This repository has been archived on 2026-10-29. You can view files and clone it, but you cannot make any changes to its state, such as pushing and creating new issues, pull requests or comments.
Epiphany/AGENTS.md
2026-04-24 00:50:48 +01:00

93 lines
4.2 KiB
Markdown

# EpiphanyAgent Instructions
## Project Purpose
This repo explores an Epiphany mode for AI coding agents: external typed state, explicit mental maps, bounded scratch work, verifier evidence, and aggressive anti-churn discipline.
The motivating failure mode is that an agent can make many plausible local edits after global coherence has already failed. The project goal is to test whether explicit map/scratch/evidence channels reduce that drift.
## Canonical State
- Treat `state/map.yaml` as the canonical project map.
- Treat `state/scratch.md` as disposable working memory for one bounded subgoal.
- Treat `state/evidence.jsonl` as the durable log of what was learned, verified, rejected, or accepted.
- Treat `notes/codex-epiphany-mode-plan.md` as the current patch plan for adding Epiphany mode to the vendored Codex repo.
- Update `state/map.yaml` when project understanding changes.
- Append evidence after meaningful research, implementation, verification, or rejected paths.
## Current Status
The old preset-backed TUI experiment is no longer the active path.
What is already landed in vendored Codex:
- Phase 1 durable Epiphany thread state
- Phase 2 prompt integration
- a minimal Phase 3 typed app-server/client read surface via `Thread.epiphanyState`
Current next phase:
- Phase 4 repo-local hybrid retrieval
## Important Paths
- Project root: `E:\Projects\EpiphanyAgent`
- Vendored Codex repo: `E:\Projects\EpiphanyAgent\vendor\codex`
- Patch plan: `E:\Projects\EpiphanyAgent\notes\codex-epiphany-mode-plan.md`
- Handoff summary: `E:\Projects\EpiphanyAgent\notes\fresh-workspace-handoff.md`
- Epiphany delta map: `E:\Projects\EpiphanyAgent\notes\epiphany-current-algorithmic-map.md`
- State CLI: `E:\Projects\EpiphanyAgent\tools\epiphany_state.py`
## Useful Commands
Use the bundled Python runtime if `python` is not on PATH:
```powershell
& 'C:\Users\Meta\.cache\codex-runtimes\codex-primary-runtime\dependencies\python\python.exe' '.\tools\epiphany_state.py' status
& 'C:\Users\Meta\.cache\codex-runtimes\codex-primary-runtime\dependencies\python\python.exe' '.\tools\epiphany_state.py' add-evidence --type research --status ok --note '...'
```
Useful Codex repo searches:
```powershell
rg -n "pub enum ModeKind|TUI_VISIBLE_COLLABORATION_MODES" .\vendor\codex\codex-rs\protocol\src\config_types.rs
rg -n "builtin_collaboration_mode_presets|fn plan_preset|fn default_preset" .\vendor\codex\codex-rs\models-manager\src\collaboration_mode_presets.rs
rg -n "collaboration_mode_label|collaboration_mode_indicator|set_collaboration_mask" .\vendor\codex\codex-rs\tui\src\chatwidget.rs
```
## Session Bootstrap And Re-entry Protocol
On fresh session load, do this before wandering off into implementation:
1. read:
- `state/map.yaml`
- `notes/fresh-workspace-handoff.md`
- `notes/epiphany-current-algorithmic-map.md`
- `notes/codex-epiphany-mode-plan.md`
2. run:
- `& 'C:\Users\Meta\.cache\codex-runtimes\codex-primary-runtime\dependencies\python\python.exe' '.\tools\epiphany_state.py' status`
3. restate the current next action from the persisted state before starting edits
After compaction, resume, or any suspicious loss of continuity:
1. rerun `epiphany_state.py status`
2. reread `state/map.yaml` and `notes/fresh-workspace-handoff.md`
3. treat the persisted next action as authoritative unless fresh evidence in the repo contradicts it
When context pressure is clearly rising:
1. stop broad exploration
2. narrow the active move to a bounded landing zone
3. persist map/evidence/handoff updates before forced compaction hits
Do not wait for the blackout and then act surprised.
## Operating Discipline
- Before substantial edits, restate the current mechanism and intended change.
- Prefer one clear hypothesis per iteration.
- Verify with checks that reflect the real goal, not just proxy success.
- Revert or discard changes that do not clearly improve the target.
- If the diff grows while understanding shrinks, stop implementation and switch to diagnosis.
- Keep maps and prose together; do not replace useful maps with prose-only explanations.
- Before handoff, compaction, or phase boundaries, sync `state/map.yaml`, append `state/evidence.jsonl`, refresh `notes/fresh-workspace-handoff.md`, and make the next action explicit.