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.6 KiB

Raw Blame History

CLAUDE.md — ResolutionFlow

You are Claude Code, the primary coding agent for ResolutionFlow. OpenAI Codex is the resume agent when you hit 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 AGENTS.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.

Claude-specific tooling

GitNexus code intelligence

Indexed as resolutionflow. Earns its cost on cross-cutting work only.

Tool	When
`gitnexus_query({query})`	Find code by concept when you don't know where to look
`gitnexus_context({name})`	Callers/callees of a symbol before touching it
`gitnexus_impact({target, direction})`	Blast radius before editing shared symbols
`gitnexus_rename({symbol_name, new_name, dry_run: true})`	Safe multi-file rename

Use for: core shared symbols (flowpilot_engine, unified_chat_service, auth middleware, get_db, shared hooks), cross-file renames, unfamiliar bug traces, refactor safety. Skip for: new endpoints, isolated fixes, changes you can read in one file.

Re-indexes automatically on commit (PostToolUse hook). Manual refresh if stale: npx gitnexus analyze.

gstack skills

Always use /browse for web, never mcp__claude-in-chrome__*. Most-used:

/review — pre-land PR review
/ship — tests + review + PR creation
/browse + /qa / /qa-only — headless browser testing (setup: Lesson 82)
/design-review — visual QA
/investigate — systematic debug with root cause
/codex — OpenAI Codex second opinion
/plan-eng-review / /plan-design-review / /plan-ceo-review — plan critiques

Git trailer

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

Model aliases

Always use alias form (claude-sonnet-4-6, claude-opus-4-6, etc.) via settings.get_model_for_action(). Never hardcode a dated model ID.

3.6 KiB Raw Blame History