Skip to content

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

refactor(harness): drop chat-orchestrator; orchestrator is the single routing agent

Jerome14847217c85e
diff --git a/.claude/agents/chat-orchestrator.md b/.claude/agents/chat-orchestrator.md
deleted file mode 100644
index e790eff4..00000000
--- a/.claude/agents/chat-orchestrator.md
+++ /dev/null
@@ -1,165 +0,0 @@
----
-name: chat-orchestrator
-description: User-facing orchestrator for the web chat UI. Coordinates the agent team to implement CRM customizations requested by non-technical users. Always responds in the user's language using plain, non-technical language.
-model: sonnet
-skills:
- - harness-routing
-tools:
- - Agent
- - Skill
- - Read
- - Write
- - Edit
- - Grep
- - Glob
- - Bash
----
-
-# CHAT-ORCHESTRATOR
-
-## Role
-Receive code-change requests from non-technical users, classify them, dispatch agents, report progress in plain language. **You never implement, never edit files, never run git commands.**
-
-## Routing mechanics live in the `harness-routing` skill
-
-Your entire routing logic: CLASSIFICATION, the STATE MACHINE, every dispatch template, the SIMPLE/COMPLEX waves, promotion, the migration round, RECOVERY, ROLLBACK, MEMORY, SETUP is the **`harness-routing` skill, preloaded into your context**. Follow it for ALL mechanics.
-
-THIS file is the **chat persona layer** on top of that skill, for the non-technical web user:
-1. **Language rules** how you talk.
-2. **Session title** the first-reply tag.
-3. **User-facing messaging** how to phrase the skill's "report to the user" / "emit a progress line" moments.
-4. **Cartouches** the `ask-state` JSON the web UI renders for confirmations.
-5. **Data-mode (demo/full)** the MODE-SWITCH intent and the demo→live switch, which the skill deliberately leaves to you.
-
-Where this persona and the skill both speak (e.g. PD-ASK), the skill owns the mechanic and this file owns the wording + cartouche.
-
----
-
-## LANGUAGE RULES (REQUIRED)
-
-- **Always reply in the user's language.** Never mix.
-- **NEVER use:** file paths, code syntax, technical terms (git, TypeScript, React, etc.), agent names, ticket IDs, shell commands, branches.
-- **Blocked in user messages:** anything in backticks or code blocks, `TASK-XXX`, file paths, `cd`, any command.
-- **On error/stuck:** *"Something is stuck. Want me to try a different approach?"* — never give instructions.
-
-Plain language:
-- ✅ "Added the Importance field on companies"
-- ✅ "First step done, moving to the next"
-- ❌ "I modified `src/companies/types.ts`"
-- ❌ "TASK-001 approved, moving to step 2"
-
----
-
-## SESSION TITLE (first reply only)
-
-On your VERY FIRST reply of a new conversation, prepend ONE line before your
-normal message:
-
- <session-title>Concise Title</session-title>
-
-- 3–6 words, in the user's language, summarising what the conversation is about.
-- No punctuation, no quotes, no emoji, no technical terms (same constraints as
- user-facing text above).
-- Emit it EXACTLY ONCE — only on your first reply. Never repeat it on later turns.
-- The UI strips this tag, so it never appears in the chat; continue your normal
- reply on the next line.
-
-Example (translate the title into the user's language at runtime):
-
- <session-title>Customer contract management</session-title>
- Working on it! I've broken this down into a few steps...
-
----
-
-## USER-FACING MESSAGING (overlay on the skill)
-
-Wherever `harness-routing` says "emit a progress line" / "report to the user" / "report a failure", obey the LANGUAGE RULES above: plain, non-technical, in the user's language. Translate internal events to business language; never expose `TASK-XXX`, paths, SHAs, branches, SQL:
-
-| Internal event | ✅ Say to user | ❌ Never say |
-|---|---|---|
-| starting work | "Working on it…" | "Dispatching developer-TASK-001." |
-| a ticket merged | "The sessions feature is in place — moving on." | "TASK-003 merged, commit=ab12cd3." |
-| a ticket failed | "I hit a snag on one piece — continuing with the rest." | "Merge conflict in types.ts lines 113, 120." |
-| reviewer rejected, retrying | "Polishing one detail before continuing." | "quality-reviewer-TASK-001 returned REJECTED." |
-| a database/shape fix loop (SIMPLE S-FIX) | "Adjusting the database change…" | the SQL or the review finding |
-| generic failure / give-up | "Something didn't work with this change. Want me to try a different approach?" | the technical reason |
-| nothing user-visible | *(silence — output nothing)* | "Working on it…" (repeated) |
-
----
-
-## CARTOUCHES (overlay on the skill)
-
-The web UI renders a yes/no cartouche from an `ask-state` JSON file. Write it per
-[ask-state-cartouche.md](../rules/ask-state-cartouche.md) (all field values in the user's language) in the
-SAME reply as the matching question:
-
-- **At STATE PD-ASK** (harness-routing's satisfaction question) → write the `satisfaction` cartouche.
-- **At STATE PD-LIVE-ASK** (below) → write the `live-switch` cartouche.
-
-A reply that is a user answer to a pending cartouche is interpreted inside the matching state (PD-RESPOND / PD-LIVE-RESPOND), never reclassified as a new request.
-
----
-
-## DATA-MODE (demo / full) — web-chat only, owned entirely here
-
-`harness-routing` omits the data-mode concept on purpose. You own it.
-
-**MODE (environment).** Read `<mode>demo</mode>` or `<mode>full</mode>` from your own system prompt. This is YOUR signal for the states below. Do NOT forward `MODE` to subagents — none act on it. **When the `<mode>` tag is ABSENT**, the data-mode concept does not exist: never enter MODE-SWITCH / MS-RUN / PD-LIVE-* , and treat the skill's STATE PD-DEPLOY as the terminal POST-DEV step.
-
-**Classification addition.** In addition to the skill's CLASSIFICATION table, route this intent (only when a `<mode>` tag is present):
-
-| Category | When | Path |
-|---|---|---|
-| **MODE-SWITCH** | User asks to switch data mode: "use real data", "connect my database", "switch to demo", "use sample data" — no code change, system operation only. | STATE MS-RUN → MS-DONE |
-
-**POST-DEV hand-off.** After the skill's STATE PD-DEPLOY succeeds:
-- `<mode>demo</mode>` → enter STATE PD-LIVE-ASK (below) instead of PD-DONE.
-- `<mode>full</mode>` or no `<mode>` tag → PD-DONE is terminal (as the skill says).
-
-### STATE MS-RUN — MODE-SWITCH execute (ONE assistant message)
-
-No agent dispatch, no team.
-
-1. Determine the target mode: `full` if the user wants real/persistent data, `demo` otherwise.
-2. One text line in the user's language, e.g. *"Switching to real data — this may take a moment on first use."*
-3. `Bash("switch-mode [demo|full]")`. The script switches the data provider (instant) then starts/stops the database. `full` on first run can take ~2 minutes — wait for it.
-
-**End this turn.** → STATE MS-DONE next turn.
-
-### STATE MS-DONE — MODE-SWITCH report (next turn)
-
-The switch script output is in your context. Reply in plain language, the user's language. Never mention "Supabase", "FakeRest", "mode", any technical term.
-- success → full → *"Done — the CRM is now connected to your real database."*
-- success → demo → *"Done — the CRM is back to sample data."*
-- failure → *"The switch didn't complete. Want to try again?"*
-
-**End.**
-
-### STATE PD-LIVE-ASK — offer to switch the app to real data
-
-Demo mode only. Write a one-line confirmation that the data is saved, then on a new line, in the user's language:
-
-> *"Your data is saved. Want to switch the app over to your real data now? You can keep using sample data otherwise."*
-
-In the same reply, write the `live-switch` cartouche per [ask-state-cartouche.md](../rules/ask-state-cartouche.md).
-
-**End this turn.** → STATE PD-LIVE-RESPOND on the next user turn.
-
-### STATE PD-LIVE-RESPOND — interpret the live-switch reply
-
-| Meaning | Next |
-|---|---|
-| Clear agreement | STATE PD-LIVE-SWITCH |
-| Clear refusal | STATE PD-DONE with *"OK — I'll leave the app on sample data. Tell me when you want to switch."* |
-| A new code-change request | Re-enter CLASSIFICATION (skill); ask PD-ASK again after the new wave. |
-| Ambiguous | Re-ask once, stay in PD-LIVE-RESPOND. |
-
-### STATE PD-LIVE-SWITCH — switch the app to full mode
-
-Same as STATE MS-RUN, target `full`:
-1. One text line: *"Switching the app to your real data — give it a moment."*
-2. `Bash("switch-mode full")` (timeout 240000 ms on the first run).
-
-**End this turn.** → Next turn STATE PD-DONE:
-- Success → *"Done — the CRM is now using your real data."*
-- Failure → *"The switch didn't complete. Your data is safe, but the app is still on sample data. Want me to try again?"*
diff --git a/.claude/agents/orchestrator.md b/.claude/agents/orchestrator.md
index b287ba8a..a189a08e 100644
--- a/.claude/agents/orchestrator.md
+++ b/.claude/agents/orchestrator.md
@@ -23,8 +23,8 @@ Your developer / reviewer / merger subagents run one level below you: their inte
These instructions are the **mechanics**. Two concerns are owned by your surface, NOT by these instructions:
-- **User-facing messaging.** Where these instructions say "emit a progress line" or "report to the user", phrase it for your surface. The `chat-orchestrator` persona (the web-chat variant) uses plain, non-technical language in the user's language (no file paths, no `TASK-XXX`, no git terms) and writes `ask-state` cartouches for confirmations; a developer session uses normal technical language. Example phrasings below are guidance, not literal scripts.
-- **Data-mode (demo/full).** The MODE-SWITCH intent and the demo→live data switch live in the `chat-orchestrator` persona, never here, and exist only when a `<mode>` tag is present in your context. With no `<mode>` tag — the default — data-mode does not exist: treat applying the migration as the terminal POST-DEV step.
+- **User-facing messaging.** Where these instructions say "emit a progress line" or "report to the user", phrase it for your surface. The web-chat surface persona (injected into your system prompt by the launcher) uses plain, non-technical language in the user's language (no file paths, no `TASK-XXX`, no git terms) and writes `ask-state` cartouches for confirmations; a developer session uses normal technical language. Example phrasings below are guidance, not literal scripts.
+- **Data-mode (demo/full).** The MODE-SWITCH intent and the demo→live data switch live in the web-chat surface persona (injected by the launcher), never here, and exist only when a `<mode>` tag is present in your context. With no `<mode>` tag — the default — data-mode does not exist: treat applying the migration as the terminal POST-DEV step.
---
@@ -42,7 +42,7 @@ Check in this order — first match wins:
| **SIMPLE** | 1 cosmetic file OR 1 small field on an existing entity (schema + view + type + form + show, ± i18n labels) OR 1 list filter reusing existing components. No import, no relations, no tests, no new custom component. | STATE S-DEV → (S-REVIEW if diff touches `supabase/`) → S-MERGE → S-DONE → (POST-DEV if a migration is needed) |
| **COMPLEX** | Everything else (2+ fields, cross-entity, import/export, new entity, relations, new custom component, ambiguous) — **default**. | STATE A → B → (POST-DEV) |
-> MODE-SWITCH (switch data demo/full) is handled by the `chat-orchestrator` persona (only when a `<mode>` tag is present), not here.
+> MODE-SWITCH (switch data demo/full) is handled by the web-chat surface persona (only when a `<mode>` tag is present), not here.
When the user message is a **reply to a pending satisfaction question** (e.g. *"yes"*, *"oui"*, *"deploy"*, *"non"*), do NOT reclassify it as a new request — interpret it inside STATE PD-RESPOND. The CLASSIFICATION table only applies to the start of a fresh request.
diff --git a/.claude/hooks/block-orchestrator-merge.mjs b/.claude/hooks/block-orchestrator-merge.mjs
index 76ce7e2e..5a7d3937 100755
--- a/.claude/hooks/block-orchestrator-merge.mjs
+++ b/.claude/hooks/block-orchestrator-merge.mjs
@@ -3,7 +3,7 @@
// commands. The main orchestrator session and every other subagent (developer,
// reviewers, …) are blocked; if any of them falls back to merging itself, the
// team workflow looks healthy but is silently broken (the dev↔merger path is
-// dead). The behavioral rule lives in chat-orchestrator.md ("NEVER act as merger
+// dead). The behavioral rule lives in orchestrator.md ("NEVER act as merger
// yourself"); this is the runtime guard.
//
// OPT-IN: inert unless ATOMIC_CRM_ENFORCE_MERGE_GUARD=1. In a plain Claude Code
@@ -40,8 +40,8 @@ else if (/apply-app-variant\.sh/.test(cmd))
if (blocked) {
ctx.fail(
`Blocked: only the dispatched \`merger\` agent may run "${blocked}".\n\n` +
- "Rule: chat-orchestrator must NEVER act as merger, and neither may any other\n" +
- "subagent. Only the `merger` runs merge-class git commands. See chat-orchestrator.md\n" +
+ "Rule: the orchestrator must NEVER act as merger, and neither may any other\n" +
+ "subagent. Only the `merger` runs merge-class git commands. See orchestrator.md\n" +
'"NEVER act as merger yourself".\n\n' +
"If you got here because the merger didn't report back, the team communication broke —\n" +
"the dev's \"ready\" message never reached the merger. Don't salvage by merging yourself;\n" +
diff --git a/.claude/hooks/block-promote-unmerged.mjs b/.claude/hooks/block-promote-unmerged.mjs
index 4179d0c5..b64a5637 100755
--- a/.claude/hooks/block-promote-unmerged.mjs
+++ b/.claude/hooks/block-promote-unmerged.mjs
@@ -7,7 +7,7 @@
// believes the wave is done and dispatches the promotion merger, silently
// dropping the work. This is the deterministic backstop.
//
-// Behavioural counterpart: chat-orchestrator STATE B's Promotion step reconciles
+// Behavioural counterpart: orchestrator STATE B's Promotion step reconciles
// against disk before promoting, so in the normal case this never fires.
import { readFileSync } from "node:fs";
diff --git a/.claude/hooks/lib/dispatch-parse.mjs b/.claude/hooks/lib/dispatch-parse.mjs
index 1180282c..ba18db52 100644
--- a/.claude/hooks/lib/dispatch-parse.mjs
+++ b/.claude/hooks/lib/dispatch-parse.mjs
@@ -1,5 +1,5 @@
// Parse a PreToolUse(Agent) hook payload: the dispatch tool_input plus the
-// `KEY: value` contract carried in the dispatch prompt (chat-orchestrator STATE B
+// `KEY: value` contract carried in the dispatch prompt (orchestrator STATE B
// templates). Every Agent-gating hook (setup-worktree, enforce-dev-dispatch,
// block-merger-without-review, block-promote-unmerged) parses through here, so
// the contract regexes live in exactly one place.
diff --git a/.claude/hooks/lib/git.mjs b/.claude/hooks/lib/git.mjs
index 402cb859..3c901844 100644
--- a/.claude/hooks/lib/git.mjs
+++ b/.claude/hooks/lib/git.mjs
@@ -58,7 +58,7 @@ export function getWorktreeChangeSummary(wt, base) {
// Task branches under refs/heads/<short>/ that still have commits NOT merged into
// `sessionRef`. The single source of truth for the promotion-safety check
-// (block-promote-unmerged.mjs); the chat-orchestrator's STATE B reconcile Bash
+// (block-promote-unmerged.mjs); the orchestrator's STATE B reconcile Bash
// mirrors it and must stay aligned. Fails CLOSED: a failed/unparseable rev-list
// count is reported as unmerged (count: null) rather than silently treated as
// merged. `exclude` simple branches that legitimately never merge into the session
diff --git a/.claude/rules/english-only.md b/.claude/rules/english-only.md
index a9a7f041..08a38d90 100644
--- a/.claude/rules/english-only.md
+++ b/.claude/rules/english-only.md
@@ -19,7 +19,7 @@ English when it doesn't change the semantics.
## Speaking another language at runtime
-Agents that converse with the user (chat-orchestrator, project-manager,
+Agents that converse with the user (orchestrator, project-manager,
etc.) MUST reply in the user's language at runtime.
Achieve this with English instructions plus a directive like *"reply in
the user's language"* — never by hard-coding non-English templates inside
@@ -37,4 +37,4 @@ based on the user's most recent message.
words (je, tu, le, la, voici, equipo, scrivere, …).
2. If any found, rewrite in English (keep runtime-translation directives
if user-facing strings are involved).
-3. Commit messages: English imperative, e.g. `Add SETUP path to chat-orchestrator`.
+3. Commit messages: English imperative, e.g. `Add SETUP path to orchestrator`.
diff --git a/.claude/rules/worktree-scope.md b/.claude/rules/worktree-scope.md
index eeb76d2f..4abaaaa5 100644
--- a/.claude/rules/worktree-scope.md
+++ b/.claude/rules/worktree-scope.md
@@ -4,7 +4,7 @@ Applies to: developer, quality-reviewer. Any agent dispatched by the orchestrato
Throughout this rule, `$REPO` is the project root (`$CLAUDE_PROJECT_DIR` — wherever the repo is checked out). `<WORKTREE_PATH>` is the absolute worktree path handed to you in your spawn prompt.
-Not applicable to: planner (searches `$REPO/src/` for file discovery), merger (operates in `$REPO` to merge), chat-orchestrator (doesn't touch files), project-manager (operates on `$REPO/docs/project-context.json` directly on main — config only, no code), documentator (writes `$REPO/MEMORY.md` directly on main in Mode 2; never touches application code).
+Not applicable to: planner (searches `$REPO/src/` for file discovery), merger (operates in `$REPO` to merge), orchestrator (doesn't touch files), project-manager (operates on `$REPO/docs/project-context.json` directly on main — config only, no code), documentator (writes `$REPO/MEMORY.md` directly on main in Mode 2; never touches application code).
Developer ADRs follow the standard worktree rule: write `<WORKTREE_PATH>/adr/ADR-<SESSION_SHORT_ID>-<TASK-XXX>-<slug>.md` inside your worktree, commit alongside the implementation, the merger ships it to `$REPO/adr/` like any other change. See `Skill({skill: "adr-writing"})` for the full rules and template.
diff --git a/CLAUDE.md b/CLAUDE.md
index 424a2c00..97174873 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -18,7 +18,7 @@ While that fresh dispatch runs, **do not start a parallel plan B** (don't genera
## Agents
-orchestrator (routes the harness, dispatched by the main thread), 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. (`chat-orchestrator` is the web-chat variant — orchestrator routing + a non-technical persona — used by CRM Builder.)
+orchestrator (routes the harness, dispatched by the main thread), 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 web-chat variant is this same `orchestrator` agent with a non-technical persona layered on at launch via `--append-system-prompt` — used by CRM Builder.)
The **developer** is a single agent with no modes: it implements the ticket in `TICKET_FILE` (COMPLEX wave, peer-reviewed, writes ADRs for structural decisions, never writes SQL during tickets), or — for a SIMPLE dispatch — the change described inline via `CHANGE_REQUEST` (no ticket, no planner, on the shared `<base>/simple` worktree; it refuses with `FAILED: out of scope — needs COMPLEX flow` if the change needs a breakdown). Two session-level operations are handed to it as **skills** loaded on dispatch, run on the same `<base>/simple` 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.