Michael Chihlas
bee8690056
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>
74 lines
3.6 KiB
Markdown
74 lines
3.6 KiB
Markdown
# 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/PROJECT_CONTEXT.md), [`.ai/CURRENT_TASK.md`](.ai/CURRENT_TASK.md), and [`.ai/HANDOFF.md`](.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__*`. 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.
|