Michael Chihlas
0f00ee5e01
Four items from the design-plan audit, all flagged as locked-design or
Codex corrections, shipped together so the GTM demo path covers them
end-to-end before bug bash.
1. Live AI assessment refresh on the magic-moment screen. Backend already
publishes handoff_assessment_ready when enrich_escalation_async commits;
wire the frontend listener so the senior sees the assessment populate
without a manual reopen. New event type + onAssessmentReady handler on
streamEscalations; AssistantChatPage opens a scoped SSE subscription
whenever it tracks a handoff missing its assessment, refetches on match,
and replaces magicHandoff / overlayHandoff in place. Closes the loop on
the async-assessment commit e8ba74e.
2. Suggested-step chips below the chat input. Locked design from the plan
(Codex correction). Chip strip renders above the composer post-claim
when ai_assessment_data.suggested_steps[] is non-empty. Click prefills
the input and focuses; first send or explicit X hides for the session.
3. Unread 6px dot on EscalationQueue cards. localStorage-persisted seen
set (rf-escalation-seen, capped 200). Dot top-right when not seen.
Cleared on open (card click) or claim (Pick Up) — NOT on hover, per
Codex correction. Pick Up stops propagation so it doesn't double-fire.
4. Race-condition toast on claim conflict. The /claim endpoint previously
silently overwrote claimed_by — both seniors thought they owned the
session. New HandoffAlreadyClaimedError carries the winner's id/name/
timestamp; claim_session rejects different-user re-claims (same-user is
idempotent for double-click safety); endpoint returns 409 with
structured detail. AssistantChatPage.handleStartHere extracts and
surfaces "Already claimed by {name} {time_ago}." via toast, drops
?pickup=true, dismisses magic-moment so the loser flows back to queue.
Tests: 2 new unit tests in test_handoff_manager.py (conflict raises,
same-user idempotent). Full handoff + escalation suite (34 tests) green.
Frontend tsc -b clean.
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.)