resolutionflow/CLAUDE.md

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)

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.

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__*.

Available commands:

• Planning & review: /autoplan, /plan-eng-review, /plan-design-review, /plan-ceo-review, /plan-devex-review, /devex-review, /review, /cso, /office-hours
• Design: /design-consultation, /design-shotgun, /design-html, /design-review
• Browser & QA: /browse, /connect-chrome, /qa, /qa-only, /setup-browser-cookies
• Ship & deploy: /ship, /land-and-deploy, /canary, /benchmark, /setup-deploy, /document-release
• Debug & investigate: /investigate, /careful, /freeze, /guard, /unfreeze
• Other: /codex (OpenAI second opinion), /setup-gbrain, /retro, /learn, /gstack-upgrade

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.