Michael Chihlas
9c8ba296a8
Codex review of the dual-agent handoff migration flagged factual errors carried over verbatim from the pre-migration CLAUDE.md. All claims verified against the live code before correction. PROJECT_CONTEXT.md — SaaS shape: - Role hierarchy was `super_admin > team_admin > engineer > viewer`, but `backend/app/core/permissions.py:4` and `frontend/src/hooks/usePermissions.ts:4` both define it as `super_admin > owner > engineer > viewer`. The `team_admin` concept exists separately as an orthogonal team-scoped gate (`require_team_admin`, `is_team_admin=True` + valid `team_id`), not a level in the primary hierarchy. - Dep list was missing `require_account_owner` and `require_team_admin`, both present in `backend/app/api/deps.py`. PROJECT_CONTEXT.md — directory tree: - `api/endpoints/` comment listed 11 routers; `api/router.py` actually registers 50+. Replaced with a summary that points at `router.py` as the source of truth instead of trying to maintain a freezing list. - `services/psa/` comment omitted `exceptions.py` and `ticket_context.py`, both present in the directory. CURRENT_TASK.md + TODO.md: - Replaced `<!-- EXAMPLE -->` placeholders with clearer empty-state sentinels so a resume agent sees "no real task yet" at a glance rather than placeholder acceptance criteria that look unresolved. SESSION_LOG.md updated with a follow-up bullet documenting this pass. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
.ai/ — dual-agent handoff system
ResolutionFlow uses two coding agents: Claude Code (primary) and OpenAI Codex (resume when Claude hits session or weekly limits). This directory holds the shared state that lets either agent start a session with full context.
Files
| File | Holds | Written when | Read when |
|---|---|---|---|
| PROJECT_CONTEXT.md | Stable repo truth: stack, structure, SaaS shape, ConnectWise, coding standards, frontend patterns, critical lessons | Only when the repo's shape changes | Every session start |
| CURRENT_TASK.md | The single active task: goal, DoD, assumptions, out-of-scope | On task start; status updates during work | Every session start |
| HANDOFF.md | Exact resume point: branch, where you left off, next steps, blockers | On session end / context-window limit | Every session start (most important) |
| TODO.md | Backlog of work NOT currently active | When deferring or queueing work | Only when CURRENT_TASK.md is complete |
| DECISIONS.md | Append-only architectural decision log | When an architectural choice is made | Skim top entries each session |
| SESSION_LOG.md | Append-only chronological history | On session end | Only when broader context is needed |
Agent-specific tooling lives at the repo root:
- ../CLAUDE.md — Claude Code's tooling (GitNexus, gstack slash commands, Claude trailer)
- ../AGENTS.md — OpenAI Codex's tooling (grep/rg fallbacks, Codex trailer)
Both root files contain an identical shared-protocol block. If you edit one, edit the other.
The handoff ritual
At session end (limit hit, task complete, or user stop): update HANDOFF.md to reflect the new resume point, update CURRENT_TASK.md status if it changed, append to DECISIONS.md if you made an architectural call, append a session entry to SESSION_LOG.md, and WIP-commit any dirty working tree with wip(handoff): <one-line> unless told otherwise. Don't push.
How to invoke a resume
Tell the agent:
Read CLAUDE.md (or AGENTS.md) and follow its instructions.
The agent will read its root file, which directs it to .ai/PROJECT_CONTEXT.md, .ai/CURRENT_TASK.md, and .ai/HANDOFF.md before doing anything else.
Recovery
The previous monolithic CLAUDE.md is recoverable via:
git show pre-ai-handoff:CLAUDE.md
(Tag pre-ai-handoff on commit e110fed — the snapshot taken before this migration.)