nexus-gateway CLAUDE.md

Nexus Gateway

Enterprise AI Traffic Gateway for compliance, routing, caching, and analytics.

Mandatory rules

Every rule below is binding. Waivers require explicit user approval in chat.

• English only (repository). Project artifacts (CLAUDE.md, .cursor/rules, docs/**, source comments, user-visible UI copy, commit messages, READMEs, config/doc strings) must be English. Chat language may follow the user; anything committed stays English. Legal quotes etc. need explicit waiver.
• Workflow discipline (binding). Every change goes through this cycle. Each numbered sub-rule is binding in its own right.
  1. Plan first. Before edits / research / implementation, produce a written plan — approach, scope, risks, file touch list. Use Cursor Plan Mode or Claude Code's plan output. Do not jump straight to code.
  2. Todo list captures every user message and stays live. Every task request from the user becomes a todo immediately, before other work — Cursor TodoWrite / Claude Code TaskCreate. Each item specific, actionable, verifiable; update statuses as you go; never leave a falsely in_progress item. New requests in multi-message sessions do NOT interrupt the current task — capture them as todos, finish in-flight work to a natural commit point, then pick up the queue in order. Reordering or skipping only on explicit user instruction.
  3. Complex tasks: Plan + Todo non-waivable. A task is "complex" if any apply: (a) >2 files; (b) cross-cutting (multi-service, Thing-shadow contract, IAM, MQ schemas, audit events, anything in packages/shared/); (c) introduces/modifies an SDD epic/story; (d) touches API contract, data model, or migration; (e) touches a high-blast-radius surface (packages/agent/platform/darwin/NexusAgent/NexusAgentExtension/**, admin endpoint registration, IAM policies, token-field stamping, kill-switch, emergency passthrough, credential encryption). Skipping Plan or Todo on a complex task requires the user to explicitly state the reason; echo the reason in the response before proceeding.
  4. Goal-anchored execution. Before any non-trivial work, write the user's request as a one-line "Goal:" at the top of the plan or todo list and echo it in chat. When mid-stream constraints arrive, do NOT silently slot them in — re-state the updated goal in chat, capture the delta as new todos, then continue.
  5. Self-audit before "done" — 4 questions × 2 rounds. Q1: every todo completed (not deferred, not silently dropped)? Q2: no TODO / FIXME / XXX / unimplemented / not implemented / stub / mock strings in production code (test mocks are fine — grep your diff)? Q3: every changed code path is exercised by a real test OR explicitly acknowledged as untested with a reason? Q4: no "we'll fix this later" claims unless the user said so? Round 1 surfaces issues; fix each or capture as explicit follow-up todo. Round 2 verifies the fixes. Iterate until two consecutive rounds are clean.
  6. Commit reminder, no auto-commit. When work is done (implementation + verify + self-audit), ask the user whether to commit. Never git commit unsolicited. Suggest a concise message.
• Adversarial product review + less-is-more (binding). Two halves of the same product discipline. Apply both to any proposed feature, config knob, UI surface, menu item, behavior change, or "wouldn't it be nice if…" idea — including user proposals.