APO Agentic Workflow

Last updated: 2026-04-09

This page explains how the agent workflow is set up for this repository.

1. Two-Layer Architecture

The system has two layers:

1. Repo layer
   • AGENTS.md
   • APO_MASTER_INDEX.md
   • Working/research/
2. Runtime layer
   • Codex CLI
   • oh-my-codex (omx)
   • bootstrap script at scripts/bootstrap-codex-omx.sh

Tree view:

APO agent workflow
├── Runtime layer
│   ├── codex
│   ├── omx
│   ├── omx setup
│   └── session state in .omx/
├── Repo policy layer
│   ├── AGENTS.md
│   ├── SETUP_CODEX.md
│   └── scripts/bootstrap-codex-omx.sh
├── Canon layer
│   ├── APO_MASTER_INDEX.md
│   ├── apo_master.tex
│   ├── APO_math_condensed.md
│   ├── NS solution/
│   └── RH solution/
└── Non-canonical work layer
    └── Working/research/
        ├── wiki/
        ├── questions/
        ├── outputs/
        ├── reviews/
        └── raw/

2. Setup Flow

Bootstrap path:

fresh machine
  -> run scripts/bootstrap-codex-omx.sh
  -> install codex if missing
  -> install omx if missing
  -> run omx setup
  -> codex login
  -> start session with omx --madmax --high
  -> read AGENTS.md
  -> start from APO_MASTER_INDEX.md
  -> work in Working/research/

Source basis:

• SETUP_CODEX.md
• scripts/bootstrap-codex-omx.sh

3. Decision Diagram

This is the actual operating logic implied by the repo docs.

new task
  |
  v
read AGENTS.md
  |
  v
is this asking to edit protected canon?
  |-- yes -> only proceed if explicitly instructed
  |-- no  -> continue in Working/research/
  |
  v
read APO_MASTER_INDEX.md for current canon state
  |
  v
choose one narrow track/question
  |-- APO Core
  |-- Navier-Stokes
  |-- Riemann Hypothesis
  |
  v
create or use a question brief in Working/research/questions/
  |
  v
gather only the relevant sources
  |
  v
produce memo in Working/research/outputs/
  |
  v
needs challenge/review?
  |-- yes -> write review in Working/research/reviews/
  |-- no  -> continue
  |
  v
update wiki/dashboard in Working/research/wiki/
  |
  v
only then consider proposing canon edits

4. Agent Responsibility Diagram

User / Research Director
  |
  v
Lead agent (Codex in this repo)
  |
  |-- reads repo policy
  |-- decides scope
  |-- protects canonical files
  |-- keeps work in non-canonical workspace
  |
  +--> optional subagents/workers
  |     |
  |     |-- bounded research subtask
  |     |-- verification subtask
  |     `-- setup/tooling subtask
  |
  v
Artifacts
  |-- wiki pages
  |-- question briefs
  |-- output memos
  |-- review memos
  `-- only later, canon-facing proposals

5. Information Flow

flowchart TD
    A[User request] --> B[AGENTS.md policy check]
    B --> C[APO_MASTER_INDEX.md orientation]
    C --> D{Protected canon edit requested?}
    D -->|Yes| E[Explicit instruction required]
    D -->|No| F[Working/research/ lane]
    F --> G[questions/ brief]
    G --> H[bounded source reading]
    H --> I[outputs/ memo]
    I --> J{Need challenge pass?}
    J -->|Yes| K[reviews/ memo]
    J -->|No| L[wiki/ update]
    K --> L
    L --> M[propose next action or canon edit]

6. Runtime / Orchestration Flow

The runtime layer is simple:

• codex is the main agent interface
• omx adds orchestration, skills, state, and logs
• session artifacts live in .omx/

Current local evidence:

• .omx/logs/
• .omx/state/
• .omx/metrics.json

Runtime tree:

.omx/
├── logs/
│   ├── turns-*.jsonl
│   └── tmux-hook-*.jsonl
├── state/
│   ├── hud-state.json
│   ├── notify-hook-state.json
│   ├── team-leader-nudge.json
│   └── tmux-hook-state.json
└── metrics.json

Interpretation:

• the repo has orchestration support
• the repo does not use canon files as scratch space
• the intended agent memory/progress surface is Working/research/ plus .omx/

7. Practical Summary

In plain language:

• AGENTS.md tells the agent what is allowed
• SETUP_CODEX.md tells the machine how to bootstrap the runtime
• APO_MASTER_INDEX.md tells the agent where the project currently stands
• Working/research/ is the safe workspace for agent-produced artifacts
• .omx/ stores runtime state and logs

So the workflow is not:

ask agent -> agent edits canon directly

It is:

ask agent
  -> check policy
  -> orient from master index
  -> do bounded work in non-canonical workspace
  -> review/summarize
  -> only then propose canon changes