commit 8af9e92fe093209cb557dab8bf4799a1e1664586
Author: Stéphane Tailland <stephane.tailland@gmail.com>
Date:   Wed Aug 26 15:14:41 2026 +0200

    Add implementation instructions
    
    Design agreed in discussion, nothing built yet. Records the agent's role, its
    scopes and MCP servers, its A2A surface, and the framework choice with its
    reason — so the next session starts from the decisions rather than re-deriving
    them.
    
    Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..5fdc90c
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,50 @@
+# Assistant — orchestrating agent
+
+**Framework:** LangGraph · **Mode:** conversational · **Client id:** `classic-models-agent-assistant`
+
+The single entry point for users. Understands the request, delegates to
+specialists over A2A, composes the answer.
+
+## Scopes
+
+**None.** This agent has no MCP server and no domain scope, by design. It is the
+component that sees raw user text, therefore the prompt-injection target, and it
+must be structurally incapable of exfiltrating data. If you find yourself
+wanting to give it a domain scope, the work belongs in a specialist instead.
+
+## What it calls
+
+Every other agent, over A2A: Ventes, Catalogue, Support, Approvisionnement,
+Recouvrement. It calls them in parallel when the request allows.
+
+Example: *"can we ship order 10248?"* → Ventes (order contents) and
+Approvisionnement (stock) concurrently, then compose.
+
+## Why LangGraph here
+
+The orchestrator is where the routing logic is worth making explicit. A graph
+states which specialist is consulted when, and where the composition happens —
+useful when a request fans out and the answers must be reconciled.
+
+## Watch out
+
+LangGraph's `MultiServerMCPClient` fixes its headers at construction and
+rebuilding it loses in-memory checkpoints (langchain-mcp-adapters #172, #194,
+#235). This agent has no MCP servers, so it is not affected — but do not copy an
+MCP pattern from here into a specialist.
+
+## Before writing code
+
+Read `classic-models-agent-platform/CLAUDE.md` first. It holds the identity
+model, the MCP and LLM endpoints, the token-exchange recipe and the known
+blockers. This file only covers what is specific to this agent.
+
+## Non-negotiables
+
+- **Inference goes through the Kong AI gateway**, `https://llm-dev.sttlab.local/llm/v1/chat/completions`.
+  Calling a provider directly bypasses the rate limits and prompt guards.
+- **One MCP client per conversation turn**, built with freshly exchanged tokens.
+  Do not hold a long-lived MCP connection with a fixed token.
+- **A2A calls return answers, not data.** Expose narrow decision-shaped skills,
+  never a generic `query`.
+- Deliverables in English.