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.mdindex 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_PROJECTempty. (`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 transitionsfor 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 oneline per ticket (success or failure), then STATE PD-ASK (the open satisfactionquestion — see *POST-DEV* below).- `FAILED: PROMOTE promote conflict: files=[…]` → one non-technical linediff --cc .claude/agents/merger.mdindex 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: haikutools:- Bash@@@ -21,7 -21,7 +21,7 @@@ You move a developer's work toward theYou 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.```bashcd $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 basebranch moved meanwhile.```bashdiff --cc .claude/hooks/block-promote-unmerged.mjsindex 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.mdindex 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```bashcd <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 tolook 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.mdindex 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).