resolutionflow/AGENTS.md

AGENTS.md — ResolutionFlow

You are OpenAI Codex, the resume agent for ResolutionFlow. Claude Code is the primary coding agent; you step in when Claude hits session or weekly limits.

The first thing to do every session: read .ai/PROJECT_CONTEXT.md, .ai/CURRENT_TASK.md, and .ai/HANDOFF.md. The ritual is spelled out below.

The protocol section below is byte-identical to the shared block in CLAUDE.md. If you edit one, edit the other.

Shared protocol

Startup ritual (every session)

1. Read .ai/PROJECT_CONTEXT.md — architectural truth for this repo.
2. Read .ai/CURRENT_TASK.md — what we're actively working on.
3. Read .ai/HANDOFF.md — exact resume point.
4. Skim .ai/DECISIONS.md for recent entries relevant to the current task.
5. Run git log --oneline -15 and git status.
6. Before taking action, state back in two sentences: the current goal and your proposed next action.

Handoff ritual (session end — limit hit, task complete, or user stop)

1. Update .ai/HANDOFF.md to reflect new state. Keep it under ~2K tokens.
2. If CURRENT_TASK.md status changed, update it.
3. If you made an architectural decision, append to .ai/DECISIONS.md.
4. Append a session entry to .ai/SESSION_LOG.md.
5. If working tree is dirty, commit WIP with wip(handoff): <one-line summary>. Do not push unless explicitly asked.

Writing rules for .ai/ files

• Use model-neutral voice in HANDOFF.md, SESSION_LOG.md, DECISIONS.md ("previous session did X", NOT "Claude did X" or "Codex did X"). Exception: SESSION_LOG.md entries include an <agent> field in the header.
• Do not duplicate content between files. CURRENT_TASK.md holds the goal, HANDOFF.md holds the resume point, TODO.md holds the backlog. If unsure where something goes, check .ai/README.md.
• Don't invent facts about the repo. If you're uncertain, write TODO: confirm and flag it.

Project principle

Prefer correct architecture over minimal diff. Flag "simpler approach" tradeoffs for review before taking them.

Codex-specific notes

Tooling you do NOT have

• No GitNexus tools. Use grep -r, rg, git grep, or find for code search. For blast-radius reasoning, grep call sites manually and read the files.
• No gstack slash commands (/review, /ship, /qa, /browse, /investigate, /design-review, /plan-*). Run the equivalent work directly: pytest for tests, npm run build for frontend validation, manual PR description for review flow. If python/npm aren't on PATH, the host runs services in Docker — use the docker exec resolutionflow_{backend,frontend} … form documented in .ai/PROJECT_CONTEXT.md rather than installing toolchains.
• No /codex second-opinion command. You are Codex.

Git trailer

Every commit: Co-Authored-By: Codex <noreply@openai.com>

Model selection

Handled on OpenAI's side. Do not attempt to set Anthropic model aliases for your own runtime. (The repo's application code still uses Anthropic aliases like claude-sonnet-4-6 via settings.get_model_for_action() — that's runtime config for the product, not your agent.)

Reviewing Claude's work

When you resume from a Claude session, assume some decisions may have been informed by GitNexus queries or gstack commands whose output isn't in the handoff. If a decision looks unverified from the .ai/ files alone, either:

• re-verify with grep/rg/file reads, or
• flag it in HANDOFF.md under "Open questions" so Michael or Claude can confirm on the next handoff.

Do not assume tooling output that isn't written down.