Files

Michael Chihlas bee8690056 chore(ai): migrate to dual-agent handoff system

Split the monolithic CLAUDE.md into a durable handoff system:

- .ai/PROJECT_CONTEXT.md  — stable architectural truth (stack, structure,
  SaaS shape, ConnectWise, coding standards, frontend patterns, critical
  lessons). Ported verbatim from the previous CLAUDE.md.
- .ai/CURRENT_TASK.md     — single active task with DoD + out-of-scope.
- .ai/HANDOFF.md          — resume point, kept under ~2K tokens.
- .ai/TODO.md             — backlog, read only when CURRENT_TASK complete.
- .ai/DECISIONS.md        — append-only architectural decision log.
- .ai/SESSION_LOG.md      — append-only chronological history.
- .ai/README.md           — human-facing explanation of the system.

Root agent files share a byte-identical protocol block (verified via diff):

- CLAUDE.md — primary agent, with GitNexus + gstack tooling and the
  Claude Opus 4.7 co-author trailer.
- AGENTS.md — OpenAI Codex resume agent, with grep/rg fallbacks and the
  Codex co-author trailer. Steps in when Claude hits session/weekly
  limits.

Legacy root-level SESSION-HANDOFF.md deleted — superseded by .ai/HANDOFF.md.
It was a self-describing one-off from the Design System v4 migration and
had no external references.

Supersedes previous CLAUDE.md. Old version recoverable via
`git show pre-ai-handoff:CLAUDE.md` (tag points at commit e110fed).

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

2026-04-24 14:50:41 -04:00

3.4 KiB

Raw Blame History

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)

Read .ai/PROJECT_CONTEXT.md — architectural truth for this repo.
Read .ai/CURRENT_TASK.md — what we're actively working on.
Read .ai/HANDOFF.md — exact resume point.
Skim .ai/DECISIONS.md for recent entries relevant to the current task.
Run git log --oneline -15 and git status.
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)

Update .ai/HANDOFF.md to reflect new state. Keep it under ~2K tokens.
If CURRENT_TASK.md status changed, update it.
If you made an architectural decision, append to .ai/DECISIONS.md.
Append a session entry to .ai/SESSION_LOG.md.
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.
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.

3.4 KiB Raw Blame History