Skip to content

A full-featured CRM built with React, shadcn/ui, and Supabase.

Merge branch 'main' into chore/improve-agents-and-efforts

erwanMarmelab3672cb12ff86
diff --cc .claude/agents/chat-orchestrator.md
index 187d722e,36b8051e..ab8ae524
--- a/.claude/agents/chat-orchestrator.md
+++ b/.claude/agents/chat-orchestrator.md
@@@ -552,8 -693,9 +552,9 @@@ Bash("for b in $(git -C $CLAUDE_PROJECT
empty. (`block-promote-unmerged` refuses a promotion dispatch while it's non-empty.)
- **Empty** → every developed ticket is on the session branch.
- Then promote the session branch to main (both SETUP and CODE-CHANGE) — Stage A only put
- tickets on `session/<SESSION_SHORT_ID>`; nothing has reached `main` yet.
+ Then promote the session branch to the base branch — the branch the session was
-forked from (both SETUP and COMPLEX) — Stage A only put tickets on
++forked from (both SETUP and CODE-CHANGE) — Stage A only put tickets on
+ `session/<SESSION_SHORT_ID>`; nothing has reached the base branch yet.
- **≥ 1 ticket reached `DONE`** → dispatch the promotion merger in the
**foreground** and handle its result inline (do NOT run the Stage 1–3 transitions
for it):
@@@ -564,8 -706,8 +565,8 @@@
prompt: "ROLE: merger\nMODE: promote\nSESSION_SHORT_ID: <SESSION_SHORT_ID>"
})
```
- - `DONE: PROMOTE commit=…` → the session branch is now on `main`. SETUP path
+ - `DONE: PROMOTE commit=…` → the session branch is now on the base branch. SETUP path
- (planner given `SETUP_MODE=true`) → STATE SETUP-DONE. COMPLEX path → reply one
+ (planner given `SETUP_MODE=true`) → STATE SETUP-DONE. CODE-CHANGE path → reply one
line per ticket (success or failure), then STATE PD-ASK (the open satisfaction
question — see *POST-DEV* below).
- `FAILED: PROMOTE promote conflict: files=[…]` → one non-technical line
diff --cc .claude/agents/merger.md
index 792dffb2,05dcf86d..571352cb
--- a/.claude/agents/merger.md
+++ b/.claude/agents/merger.md
@@@ -1,6 -1,6 +1,6 @@@
---
name: merger
- description: Local merge agent (no team, single-shot). Dispatch contexts — (1) per-task Stage A merge of a feature branch into the session branch, (2) MIGRATION flow (Stage A then promotion in one shot), (3) promotion-only (Stage B, session branch → main under flock), (4) ROLLBACK (revert branch promoted directly into the default branch). No PR, no CI watch, no SendMessage — purely local git.
-description: Local merge agent (no team, single-shot). Dispatch contexts — (1) per-task Stage A merge of a feature branch into the session branch, (2) SIMPLE flow (Stage A then promotion in one shot), (3) promotion-only (Stage B, session branch → base branch under flock), (4) ROLLBACK (revert branch promoted directly into the base branch). No PR, no CI watch, no SendMessage — purely local git.
++description: Local merge agent (no team, single-shot). Dispatch contexts — (1) per-task Stage A merge of a feature branch into the session branch, (2) MIGRATION flow (Stage A then promotion in one shot), (3) promotion-only (Stage B, session branch → base branch under flock), (4) ROLLBACK (revert branch promoted directly into the base branch). No PR, no CI watch, no SendMessage — purely local git.
model: haiku
tools:
- Bash
@@@ -21,7 -21,7 +21,7 @@@ You move a developer's work toward the
You don't create PRs, push, or watch CI. You never call `SendMessage` or join a team — the orchestrator dispatches you single-shot and reads your OUTPUT CONTRACT line.
- There is also a **ROLLBACK** path (rollback-conflict resolution): a `developer` running the `resolving-rollback-conflicts` skill produced revert commits on `BRANCH_NAME` (already rebased onto the default branch). You **skip Stage A entirely** and promote `BRANCH_NAME` **directly** into the default branch (see ROLLBACK mode below). A rollback is a default-branch operation, NOT session work — merging it through `session/<SESSION_SHORT_ID>` would drag unrelated history into the session branch and poison the deploy-time migration diff.
-There is also a **ROLLBACK** path (rollback-conflict resolution): `simple-developer` produced revert commits on `BRANCH_NAME` (already rebased onto the base branch). You **skip Stage A entirely** and promote `BRANCH_NAME` **directly** into the base branch (see ROLLBACK mode below). A rollback is a base-branch operation, NOT session work — merging it through `session/<SESSION_SHORT_ID>` would drag unrelated history into the session branch and poison the deploy-time migration diff.
++There is also a **ROLLBACK** path (rollback-conflict resolution): a `developer` running the `resolving-rollback-conflicts` skill produced revert commits on `BRANCH_NAME` (already rebased onto the base branch). You **skip Stage A entirely** and promote `BRANCH_NAME` **directly** into the base branch (see ROLLBACK mode below). A rollback is a base-branch operation, NOT session work — merging it through `session/<SESSION_SHORT_ID>` would drag unrelated history into the session branch and poison the deploy-time migration diff.
Run the steps for your dispatch mode once, then emit the OUTPUT CONTRACT line and stop.
@@@ -100,16 -100,23 +100,23 @@@ The orchestrator parses this line by re
---
- ### PROMOTION — Stage B (session branch → main)
+ ### PROMOTION — Stage B (session branch → base branch)
-**Trigger**: either `MODE: promote` (COMPLEX, run once per request after every ticket has merged into the session branch) or automatically after Stage A in the SIMPLE flow.
+**Trigger**: either `MODE: promote` (wave, run once per request after every ticket has merged into the session branch) or automatically after Stage A in the MIGRATION flow.
- **Promotion ALWAYS targets the repository's default branch** — never trust
- `$CLAUDE_PROJECT_DIR`'s current HEAD. If `$CLAUDE_PROJECT_DIR` has drifted onto a previous session's branch
- (it can, and nothing else resets it), merging into the current HEAD silently
- piles every session onto that branch while the default branch never advances:
- the promotion "succeeds" but the work never reaches the real main. So the lock
- block checks out the default branch first, then merges.
+ **Promotion targets the branch the session was forked from** (the base branch),
+ recorded in git config (`sessionbase.<SESSION_SHORT_ID>.branch`) by the
+ `setup-worktree` hook at the moment of the fork — so the work lands back on the
+ branch the user is on, not always on `main`. The recorded value is preferred;
+ if absent (e.g. a session started before this was introduced) — or if it names a
+ branch that no longer exists locally (deleted or renamed since the fork) — it
+ falls back to the repository's remote default branch, then `master`/`main`. Either way, never
+ trust `$CLAUDE_PROJECT_DIR`'s current HEAD: if `$CLAUDE_PROJECT_DIR` has drifted
+ onto a previous session's branch (it can, and nothing else resets it), merging
+ into the current HEAD silently piles every session onto that branch while the
+ base branch never advances — the promotion "succeeds" but the work never reaches
+ the real base branch. So the lock block resolves the target explicitly and checks
+ it out first, then merges.
```bash
cd $CLAUDE_PROJECT_DIR && flock $CLAUDE_PROJECT_DIR/.promote.lock bash -c '
@@@ -129,19 -139,19 +139,20 @@@ correct
- Success → capture the short SHA (`cd $CLAUDE_PROJECT_DIR && git rev-parse --short HEAD`) and emit:
- promotion-only: `DONE: PROMOTE commit=<short_sha>`
- - SIMPLE: `DONE: SIMPLE commit=<short_sha>`
+ - MIGRATION: `DONE: MIGRATION commit=<short_sha>`
- On non-zero exit (conflict): the lock block already ran `git merge --abort` before releasing the lock. Read the conflicting files from the merge output and emit:
- promotion-only: `FAILED: PROMOTE promote conflict: files=[<paths>]`
- - SIMPLE: `FAILED: SIMPLE promote conflict: files=[<paths>]`
+ - MIGRATION: `FAILED: MIGRATION promote conflict: files=[<paths>]`
Do NOT resolve — the orchestrator dispatches a resolver.
- - The `flock` serialises promotions across concurrent sessions sharing main.
+ - The `flock` serialises promotions across concurrent sessions sharing the base branch.
- ### ROLLBACK PROMOTION (ROLLBACK mode — `BRANCH_NAME` → main, no Stage A)
+ ### ROLLBACK PROMOTION (ROLLBACK mode — `BRANCH_NAME` → base branch, no Stage A)
Identical to Stage B except you merge **`BRANCH_NAME`** instead of the session
- branch, and you never run Stage A. The `developer` (ROLLBACK_CONFLICT mode) already
- rebased the reverts onto the default branch, so this merge fast-forwards cleanly unless the default
-branch, and you never run Stage A. `simple-developer` already rebased the reverts
-onto the base branch, so this merge fast-forwards cleanly unless the base
++branch, and you never run Stage A. The `developer` running the
++`resolving-rollback-conflicts` skill already rebased the reverts onto the base
++branch, so this merge fast-forwards cleanly unless the base
branch moved meanwhile.
```bash
diff --cc .claude/hooks/block-promote-unmerged.mjs
index 2a156cd3,e1fc9cbf..cc3da64d
--- a/.claude/hooks/block-promote-unmerged.mjs
+++ b/.claude/hooks/block-promote-unmerged.mjs
@@@ -46,9 -46,9 +46,9 @@@ const describe = ({ branch, count }) =
` - ${branch} (${count === null ? "unmerged (count unavailable)" : `${count} unmerged commit(s)`})`;
ctx.fail(
- `Refusing to promote ${session} to main — these task branches have commits NOT yet merged into the session branch:\n` +
+ `Refusing to promote ${session} to the base branch — these task branches have commits NOT yet merged into the session branch:\n` +
unmerged.map(describe).join("\n") +
"\n" +
- "A ticket was developed but never merged (its reviewers/merger were likely never dispatched). For EACH branch above, drive its ticket through REVIEW -> MERGE (dispatch its quality-reviewer + test-validator if needed, then its per-ticket merger) so its work lands on the session branch. Re-dispatch the promotion merger only once this list is empty.",
+ "A ticket was developed but never merged (its reviewer/merger were likely never dispatched). For EACH branch above, drive its ticket through REVIEW -> MERGE (dispatch its quality-reviewer if needed, then its per-ticket merger) so its work lands on the session branch. Re-dispatch the promotion merger only once this list is empty.",
{ log: `BLOCK unmerged=${unmerged.length}` },
);
diff --cc .claude/skills/writing-migrations/SKILL.md
index daa8ab3d,028575da..1c81614c
--- a/.claude/skills/writing-migrations/SKILL.md
+++ b/.claude/skills/writing-migrations/SKILL.md
@@@ -5,19 -5,30 +5,34 @@@ description: Generate Supabase SQL migr
# Writing Migrations (deploy-time round)
- You (the `developer`) have been asked to generate the deploy-time migration.
- Your worktree is `<WORKTREE_BASE>/ops` on `<SESSION_SHORT_ID>/ops`,
- forked from `session/<SESSION_SHORT_ID>` (`<WORKTREE_BASE>` =
- `/tmp/<$CLAUDE_PROJECT_DIR with every "/" replaced by "_">/<SESSION_ID>`). Produce SQL migrations that make the
- real Supabase schema match what this session's app expects — nothing more. The
+ ## Overview
+
+ A workflow that turns a session's *code* changes into the *minimal* SQL that
-makes the real Supabase schema match what the session's app now expects
-nothing more.
-You run as `simple-developer` in migration mode.
++makes the real Supabase schema match what the session's app now expects —
++nothing more.
++You (the `developer`) have been asked to generate the deploy-time migration. The
+"never write migrations / no schema" rule of normal ticket work does NOT apply
+here: writing SQL under `supabase/migrations/` is the whole job. Do not edit any
+TS/TSX/CSS — the schema diff already comes from the session branch; you only
+translate it to SQL.
+ Exit criterion: either a committed, idempotent migration whose delta is provably the net schema change, or an explicit `NO_MIGRATION_NEEDED` when there is no schema impact.
+
-Your worktree is `<WORKTREE_BASE>/simple` on `<SESSION_SHORT_ID>/simple`, forked from `session/<SESSION_SHORT_ID>` (`<WORKTREE_BASE>` =
-`/tmp/<$CLAUDE_PROJECT_DIR with every "/" replaced by "_">/<SESSION_ID>`).
++Your worktree is `<WORKTREE_BASE>/ops` on `<SESSION_SHORT_ID>/ops`, forked from `session/<SESSION_SHORT_ID>` (`<WORKTREE_BASE>` =
++`/tmp/<$CLAUDE_PROJECT_DIR with every "/" replaced by "_">/<SESSION_ID>`). Every Bash call must `cd <WORKTREE_PATH> && …` (stateless shells).
+
+ ## When to Use
+
+ - The deploy-time migration round, after a session's app changes have merged to `session/<SESSION_SHORT_ID>` and need their schema counterpart.
-- Triggered only by the orchestrator dispatching `simple-developer` in MIGRATION MODE never invoked ad hoc by a feature developer (developers never write SQL).
++- Triggered only by the orchestrator dispatching a `developer` that loads this skill, never invoked ad hoc by a feature developer (per-ticket developers never write SQL).
+
+ Skip (write nothing, report `NO_MIGRATION_NEEDED`) when the net diff has no
+ schema impact: CSS, layout, copy, or test-only changes.
- Every Bash call must `cd <WORKTREE_PATH> && …` (stateless shells).
+ ## Process
- ## 1. Compute the session's net change
+ Each step ends in a checkpoint, do not advance until its evidence holds.
+
+ ### 1. Compute the session's net change
```bash
cd <WORKTREE_PATH>
@@@ -98,22 -120,44 +124,56 @@@ declarative schema must mirror the depl
"append at end" placement of newer columns. Don't reorder the schema file to
look prettier — schema drift breaks future `supabase db diff` generations.
- ## 6. Commit and hand off
+ **Checkpoint:** for every table that gained a column AND feeds a view,
+ positions 1..N of the recreated view match the old view exactly, the new column is position N+1, and `03_views.sql` mirrors that order.
+
+ ### 6. Commit and hand off
-Commit the SQL on `<SESSION_SHORT_ID>/simple`. Stop. SubagentStop hooks
-(typecheck/prettier/unit/e2e) run automatically. The orchestrator then sends you
-to quality-reviewer (migration mode) and the merger.
+Commit the SQL on `<SESSION_SHORT_ID>/ops`:
+
+```bash
+cd <WORKTREE_PATH> && git add supabase/migrations && git commit -m "migration(<SESSION_SHORT_ID>): <slug>"
+```
+
+Then stop and emit the output contract as your very last line — one of:
+
+- `DONE: branch=<SESSION_SHORT_ID>/ops migration=<filename> summary=<what the SQL does>`
+- `NO_MIGRATION_NEEDED` — only after computing the diff (step 1) and confirming no schema impact.
+- `FAILED: <one-line reason>`
+
+SubagentStop hooks (typecheck/prettier/unit/e2e) run automatically; they should
+pass since you only touched SQL. The orchestrator then sends you to
+quality-reviewer (`MODE: migration-review`) and the merger.
For Postgres correctness you may load `Skill({skill: "supabase-postgres-best-practices"})`.
+
-**Checkpoint:** the migration is committed on `<SESSION_SHORT_ID>/simple` and the SubagentStop validation chain is green.
++**Checkpoint:** the migration is committed on `<SESSION_SHORT_ID>/ops` and the SubagentStop validation chain is green.
+
+ ## Rationalizations
+
+ | Rationalization | Reality |
+ |---|---|
+ | "I'll diff against main, it's close enough." | Other sessions pollute main. Only the two-dot `session-base..session` range is the true net change. |
+ | "This column is probably already deployed, I'll re-emit it to be safe." | Re-emitting a deployed change is drift, not safety. Guard with `IF NOT EXISTS` and emit only the delta. |
+ | "The view still selects all the right columns, order doesn't matter." | Postgres rejects any ordinal shift (42P16). Order is a hard correctness constraint, not cosmetics. |
+ | "DROP VIEW CASCADE then CREATE is simpler." | It silently drops dependents and loses REVOKEs. Use `CREATE OR REPLACE` unless you are removing/renaming a column. |
+ | "No schema change, but I'll write an empty migration anyway." | A no-op deploy is valid. Write nothing and report `NO_MIGRATION_NEEDED`. |
+
+ ## Red Flags
+
+ - Diff computed via `git merge-base` or against `main`.
+ - A migration statement without an `IF [NOT] EXISTS` guard.
+ - A new table with no RLS, or an RLS policy using `USING (true)`.
+ - A view recreated by `DROP … CASCADE` for a mere column *addition*.
+ - A new column inserted anywhere but the last position of an existing view.
+ - `03_views.sql` and the migration's view definition disagreeing on column order.
+ - Re-emitting SQL already present in `supabase/migrations/`.
+
+ ## Verification
+
+ - [ ] Diff taken from `session-base/<SESSION_SHORT_ID>..session/<SESSION_SHORT_ID>`.
+ - [ ] Every emitted statement is an incremental delta not already in `supabase/migrations/`.
+ - [ ] All statements are idempotent (`IF [NOT] EXISTS`).
+ - [ ] New tables have RLS enabled with real policies (never `USING (true)`).
+ - [ ] Affected views recreated via `CREATE OR REPLACE`, new column last, matching `03_views.sql`.
-- [ ] SQL committed on `<SESSION_SHORT_ID>/simple`; SubagentStop validation green — OR `NO_MIGRATION_NEEDED` reported with no file written.
++- [ ] SQL committed on `<SESSION_SHORT_ID>/ops`; SubagentStop validation green — OR `NO_MIGRATION_NEEDED` reported with no file written.
diff --cc CLAUDE.md
index 7fd90958,d7ba18e9..1a55feb6
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@@ -2,48 -2,34 +2,35 @@@
# Agent Workflow
- This project ships CRM changes through a coordinated agent team rather than a single implementer. Once a plan is approved (via `ExitPlanMode`), the main thread / orchestrator does not implement directly — it routes the work to the custom agents defined under `.claude/agents/`. Each agent's full contract lives in its own file; this section is the map of who does what, and in which order.
+ Once a plan is approved (`ExitPlanMode`), the main thread does not implement directly — it routes to the agents in `.claude/agents/` (each carries its own full contract). Trigger is *plan approved*, not task size.
+
+ ## Opting out
+
+ Harness routing is the **default**. `#no-harness` (or "implement directly" / "without the agent team" / "skip harness") makes the main thread implement itself, no agents, even after plan approval. "no-harness for this session" keeps it off all session. Irrelevant under `make harness` (orchestrator always routes).
-## Routing
+## Routing: one pipeline for every change
-- **SIMPLE** (1 cosmetic edit, OR 1 single-field change on an existing entity, OR 1 filter reusing existing components) → simple-developer → merger. No team, no review.
-- **COMPLEX** (everything else) → planner → wave → review → merge pipeline below.
+The **chat-orchestrator** is the user-facing entry point. It routes, narrates progress, and never implements. There is **no SIMPLE-vs-COMPLEX triage**: every request that changes the CRM code or schema — a one-line label rename just as much as a new entity with relations — runs the **same pipeline** below. A tiny change is simply a one-ticket wave. The orchestrator only branches away from this pipeline for non-code operational intents: SETUP (project scoping), MODE-SWITCH (demo/real data), MEMORY (capture a pattern), ROLLBACK-CONFLICT (resolve a failed automatic revert), and RECOVERY (resume after an interruption).
-## COMPLEX pipeline
+## The pipeline
- 1. **planner** — decompose the approved plan into atomic, ordered tickets (JSON) with best-guess file paths and dependency waves. Skip only when the plan is already a single atomic deliverable (one file, one fix).
- 2. **developer** (one per ticket) — implement + commit inside the ticket's git worktree. Tickets in the same wave (`parallel_safe: true`, no mutual dependency) are spawned concurrently as **foreground** subagents — a single message with multiple `Agent(...)` tool uses (no `run_in_background`); the orchestrator's turn resumes once they all return. Developers also write an ADR under `adr/` when a change introduces a structural decision, and never write SQL migrations (those are generated at deploy time).
- 3. **quality-reviewer** — the single reviewer: combined semantic code + security review (Parts A, B) plus QA / runtime validation — integration wiring, behavior-verifiable acceptance criteria, e2e presence (Part C). Never re-runs validation (hooks already do).
- 4. **merger** — `git merge --no-ff` only; never `git add` / `git commit`. One merger is dispatched per ticket (Stage A: feature branch → session branch); a final promotion merger (`MODE: promote`) moves the session branch onto `main` once the wave is done, serialised across sessions by a `flock` on the shared `.git`.
- 5. **documentator** — auto-runs at the end of every session, appending business knowledge to `MEMORY.md` from the session diff. (Mode 1 also captures reusable rules/skills on explicit user request.)
-
- There is no cross-agent messaging: the orchestrator dispatches every agent as a **foreground subagent** (`Agent(...)`, no `run_in_background`) and drives the wave **synchronously within one continuous turn** (chat-orchestrator.md STATE B) — a foreground call blocks until the subagent returns, and several in one message run concurrently and return together. Each wave flows through three barriered stages: develop (concurrent) → review + bounded retry (concurrent) → merge (sequential, since per-ticket mergers share the session branch). This replaces an earlier event-driven background model, which stalled when a background completion woke the wrong subagent instead of the orchestrator. Each agent's last output line is an **output contract** (`DONE: …` / `FAILED: …` / `APPROVED` / `REJECTED: …`) that the orchestrator parses to choose the next dispatch (see `.claude/rules/agent-output-format.md`). PreToolUse/Agent hooks prepare the worktree (`setup-worktree`) and gate the flow (`enforce-dev-dispatch`, `block-merger-without-review`, `block-promote-unmerged`); SubagentStop hooks validate (`validate-on-stop`) and record review verdicts (`record-review-verdict`).
-
- ## Agent team
-
- | Agent | Model | Role |
- |---|---|---|
- | chat-orchestrator | sonnet | User-facing. Routes every code change through the one pipeline; narrates progress; never implements. |
- | planner | opus | Decomposes the plan into tickets JSON with waves + file hints. |
- | developer | sonnet | One agent, no modes. Implements the ticket in `TICKET_FILE`: plans, commits in a per-ticket worktree, peer-reviewed, writes ADRs for structural decisions, never writes SQL migrations during tickets. Two session-level operations are handed to it as **skills** (loaded on dispatch, run on the shared `<base>/ops` worktree): `writing-migrations` (deploy-time SQL generation) and `resolving-rollback-conflicts` (replay merge-commit reverts). Applies the **Ponytail** minimization ladder (full mode) automatically via an inline prompt directive. |
- | quality-reviewer | opus | Sole reviewer: combined semantic code + security review AND QA/runtime validation (integration wiring, behavior criteria, e2e presence). Never re-runs validation. |
- | merger | haiku | `git merge --no-ff` only. Never `git add` / `git commit`. |
- | documentator | haiku | Mode 1 — captures rules/skills on request. Mode 2 — appends business knowledge to `MEMORY.md` at session end. |
-planner (tickets JSON + waves) → developer per ticket (implements + commits in a worktree; no SQL migrations, deploy-time only) → quality-reviewer (code + security + QA) → merger (`git merge --no-ff` only) → documentator (appends to `MEMORY.md`). Agents run as **foreground** subagents in one synchronous turn; each agent's last line is an output contract the orchestrator parses (`.claude/rules/agent-output-format.md`).
++planner (tickets JSON + waves) → developer per ticket (implements + commits in a worktree; no SQL migrations, deploy-time only) → quality-reviewer (code + security + QA) → merger (`git merge --no-ff` only; Stage A per ticket, then one `MODE: promote` to the base branch under `flock`) → documentator (appends to `MEMORY.md`). Agents run as **foreground** subagents in one synchronous turn; each agent's last line is an output contract the orchestrator parses (`.claude/rules/agent-output-format.md`).
- **planner** and **quality-reviewer** run on opus; everything else is sonnet or haiku.
+ ## Agents
- The **developer** applies the **Ponytail** minimization ladder (full mode) on every change — in every mode — via inline directives in its prompt, the only mechanism that reaches `Agent`-dispatched subagents. Ponytail is also installed **natively** in-repo as on-demand skills (no plugin, no marketplace, no hooks): its skills live in `.claude/skills/ponytail*` and its `/ponytail*` commands in `.claude/commands/`, for interactive use in the main session (`/ponytail-review`, `/ponytail-audit`, …). These do not affect the dev agents, whose ladder comes from the inline directives above.
-chat-orchestrator (routes, narrates), planner, developer, simple-developer, quality-reviewer, merger, documentator. Models/roles: see each `.claude/agents/*.md`.
++chat-orchestrator (routes, narrates), planner, developer, quality-reviewer, merger, documentator. Models/roles: see each `.claude/agents/*.md`. **planner** and **quality-reviewer** run on opus; everything else is sonnet or haiku.
+
- ## The orchestrator's job between hand-offs
++The **developer** is a single agent with no modes: it implements the ticket in `TICKET_FILE` (peer-reviewed, writes ADRs for structural decisions, never writes SQL during tickets). Two session-level operations are handed to it as **skills** loaded on dispatch, run on the shared `<base>/ops` worktree: `writing-migrations` (deploy-time SQL generation) and `resolving-rollback-conflicts` (replay merge-commit reverts). It applies the **Ponytail** minimization ladder (full mode) on every change via an inline prompt directive — the only mechanism that reaches `Agent`-dispatched subagents. Ponytail is also installed natively in-repo as on-demand skills (`.claude/skills/ponytail*`) and `/ponytail*` commands for interactive use in the main session; these do not affect the dev agents.
- Relay agent reports, surface blockers, and stop to ask the user whenever an agent flags an open question or a `FAILED` outcome the orchestrator can't resolve. (A reviewer `REJECTED` verdict is handled silently by the bounded developer-retry loop, not surfaced to the user.) Do not bypass this flow for "small-looking" changes — the trigger is *plan approved*, not *task size*. Direct requests that never entered plan mode are not subject to this workflow.
+ ## Rules & hooks
- ## Supporting rules
+ Mechanics live in `.claude/rules/` (worktree-scope, agent-output-format, validation-commands, security-triggers). Hooks in `.claude/settings.json` / `.claude/hooks/` are `.mjs` ES modules.
- The mechanics each agent must follow live in `.claude/rules/`:
+ ## graphify
- - **worktree-scope** — every ticket agent works only inside its own worktree; never read/edit the base-branch checkout. Covers session-branch topology and the merge path.
- - **agent-output-format** — the structured-text contract every agent returns.
- - **validation-commands** — typecheck / prettier / unit / e2e are automated by hooks; agents must not run them manually.
- - **security-triggers** — when a change warrants extra security scrutiny.
+ This project has a knowledge graph at graphify-out/ with god nodes, community structure, and cross-file relationships.
- Claude Code hooks (configured in `.claude/settings.json`, stored in `.claude/hooks/`) must be written as `.mjs` files (ES modules).
+ Rules:
+ - For codebase questions, first run `graphify query "<question>"` when graphify-out/graph.json exists. Use `graphify path "<A>" "<B>"` for relationships and `graphify explain "<concept>"` for focused concepts. These return a scoped subgraph, usually much smaller than GRAPH_REPORT.md or raw grep output.
+ - Read graphify-out/GRAPH_REPORT.md only for broad architecture review or when query/path/explain do not surface enough context.
+ - After modifying code, run `graphify update .` to keep the graph current (AST-only, no API cost).