CLAUDE.md — STOA Platform

Project

STOA Platform — "The European Agent Gateway"

• API Management AI-Native Open Source (Apache 2.0)
• Kill feature: UAC (Universal API Contract) — "Define Once, Expose Everywhere"
• Legacy-to-MCP Bridge: connect traditional APIs to AI agents

UAC / Agent Contract Doctrine

Canonical rule from ADR-067:

UAC describes.
MCP projects.
Smoke proves.

For any API operation exposed to agents:

• UAC is the primary product contract; MCP tools are projections of UAC operations.
• LLM metadata is endpoint-level, not contract-level.
• V1: missing endpoint.llm metadata is a warning/review note; malformed metadata is an error.
• V2 target: new MCP-exposed endpoints must be LLM-ready before merge.
• side_effects=destructive requires requires_human_approval=true.
• A feature exposed to an agent should not exist only in code; it must be attached to a UAC operation or flow contract.

Load .claude/docs/uac-llm-ready.md when touching UAC schemas, UAC examples, MCP tool generation, smoke tests for MCP projections, or API operations exposed to agents.

Architecture

CONTROL PLANE (Cloud)                    DATA PLANE (On-Premise)
┌────────────────────────────┐           ┌──────────────────────┐
│ Portal  Console  API  Auth │  ←sync→   │ STOA GW webMethods   │
│ (React) (React) (Py) (KC) │           │ (Rust)  Kong/Envoy   │
└────────────────────────────┘           └──────────────────────┘

Components

Gateway: Rust (primary, replaced Python MCP Gateway Feb 2026). 4 modes (ADR-024) — edge-mcp (current), sidecar (Q2), proxy (Q3), shadow (deferred). STOA Go: stoactl CLI + stoa-connect agent (ADR-057). stoactl = GitOps CLI, stoa-connect = VPS agent bridging third-party gateways to Control Plane.

RBAC Roles

• cpi-admin: Full platform (stoa:admin)
• tenant-admin: Own tenant (stoa:write, stoa:read)
• devops: Deploy/promote (stoa:write, stoa:read)
• viewer: Read-only (stoa:read)

Runtime Versions

Historical note: the Python mcp-gateway/ service was retired in Feb 2026 and superseded by stoa-gateway/ (Rust). References below are historical unless tagged otherwise.

Session Workflow

1. 1 thing at a time — never mix feature + refactor + fix
2. Never code without a validated plan
3. Commit often with conventional messages

AI Factory

Subagents (.claude/agents/)

MCP Integrations (Claude.ai Native)

Full reference on-demand: .claude/docs/mcp-integrations.md

Quand lire .claude/docs/

CLAUDE.md (racine + par service) = décisions GO/NOGO auto-chargées. .claude/docs/<topic>.md = protocoles détaillés, exemples, tables de gotchas — jamais auto-chargés.

Lire docs/<topic>.md quand:

• Tu touches un domaine spécifique (ex: modifier le gateway → lire code-style-rust.md + mcp-oauth.md)
• Un CLAUDE.md référence explicitement un fichier docs/
• Tu écris un skill/command qui automatise un protocole (crash-recovery, council-s3, phase-ownership)
• Une règle CLAUDE.md mentionne un seuil sans le détailler

Règle: décisions binaires → CLAUDE.md. Protocoles, exemples, tables → .claude/docs/. Jamais dupliquer.

Skills (.claude/skills/)

• 8 legacy: implement-feature, fix-bug, review-pr, audit-component, create-adr, e2e-test, refactor, update-memory
• 2 modernes: /ci-debug [PR|run-url] (fork), /parallel-review [PR|path] (inline)
• 3 MCP-powered: /council (4-persona validation → Linear), /sync-plan (plan.md ↔ Linear), /decompose (MEGA → component-scoped sub-issues + DAG)
• 5 ops: /analytics (5 data sources, 12 queries), /competitive-watch (veille L1-L3), /ci-fix (auto-fix CI), /carto (platform service catalog + drift detection), /impact (reverse dependency analysis + blast radius)
• 2 sprint: /fill-cycle (capacity gap analysis), /generate-backlog (MEGA backlog generation)
• 1 visibility: /roadmap (strategic progress snapshot — themes, milestones, velocity)

Slash Commands (.claude/commands/)

• /status — quick project snapshot (git, PRs, CI, pods, tokens)
• /deploy-check — post-merge CD verification
• /token-report — 7-day token cost analysis
• /benchmark-competitors — quarterly competitive benchmark (9-dimension matrix)

Agent Teams (experimental)

Prerequis: brew install tmux + export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Parallel Sessions (git worktrees)

Named worktrees in .claude/worktrees/ for concurrent Claude Code sessions:

za   # analysis worktree (read-only exploration)
zf   # feature session (main repo)
zh   # hotfix worktree (ephemeral, from main)

Context Compiler (obligatoire)

CI Automation: none in this tree. Context packs are generated by the manual scripts below. See docs/CONTEXT-COMPILER.md for the full documentation.

CI Integration

No hook runs automatically in CI any more: the post-merge learning workflow was retired (it opened pull requests with GITHUB_TOKEN, which cannot receive the required checks). The scripts under docs/scripts/ remain for manual use.

There is no kill-switch variable any more: nothing runs in CI, so DISABLE_CONTEXT_COMPILER is not read by any workflow.

Manual usage

• docs/scripts/build-context.sh --component X --intent "..." ou --ticket CAB-XXXX
• Lire le context pack dans docs/context-packs/ avant de coder.
• Impact >= HIGH (16+) → Council obligatoire. CRITICAL (31+) → review Christophe.
• Legacy: impact-check.sh, contract-check.sh, dashboard.sh. DB: docs/stoa-impact.db.

Règles

Règles binaires GO/NOGO. Détail on-demand dans .claude/docs/<rule>.md.

Workflow & Sessions

• 1 MEGA par session. /clear entre chaque.
• Jamais coder sans plan validé. "Tant que j'y suis" interdit.
• Session-End State Lint (5 checks) obligatoire avant SESSION-END.
• Context budget: délégation à 60%, /compact à 80%, arrêt à 90%.

Qualité & CI

• CI rouge sur main = P0 absolu. Rien ne merge, rien ne démarre.
• Pre-push hook (Gate 1) obligatoire. --no-verify interdit sauf urgence explicite.
• PR > 300 LOC interdit. Split en micro-PRs.
• fix() sans test de régression = bloqué (regression-guard.yml).
• Test-first par défaut pour feat() et fix(). Tests qui échouent AVANT le code.
• Coverage: cp-api ≥70%. Jamais descendre. (Historical: retired mcp-gateway target was ≥40%; stoa-gateway has its own coverage gate defined in stoa-gateway/CLAUDE.md.)
• Ne jamais mocker la boundary sous test (httpx.MockTransport, MSW, pas AsyncMock).

Rewrite vs Patch (context rot mitigation)

• 2 Edit échecs consécutifs même fichier → Write (rewrite complet) ou subagent. Pas de 3e tentative Edit.
• Diff estimé >30% du fichier → Write direct. Pas de série d'Edit qui dérive.

• 3 itérations de fix sur même fichier dans la même session → /clear ou délégation subagent (contexte frais).

• Skill /rewrite <path> disponible pour forcer rewrite propre quand Edit échoue.
• Détail: .claude/docs/rewrite-vs-patch.md. Hook: post-edit-failure-tracker.sh.

Git & Merge

• Toujours --squash + --delete-branch. Jamais push direct sur main.
• --force, git reset --hard, suppression branche tiers = demander avant.
• Conventional commits obligatoires. Ticket ID sur 1er commit.
• Évidence archive obligatoire après Playwright: docs/audits/<date>-<topic>/.

Council & MEGA

• Impact Score ≥ HIGH (16+) → Council obligatoire avant code.
• Council S1/S2/S3: seuil ≥ 8.0/10. <8 = rework, pas de contournement.
• MEGA jamais marqué Done directement. Toujours /verify-mega (5 gates).
• Sub-ticket Done sans comment "PR #N" = gate 1 échoue.
• Decision Challenge Gate (HLFH-wide) avant exécution d'un plan matchant ≥1 trigger: (a) temps Claude > 5h, (b) impact business direct (GTM/pricing/positioning/contenu stratégique/partenariat/roadmap lourde), (c) irréversible (données/contrats/branding). Rappeler le gate et exiger contre-analyse d'un challenger externe non-aligné (GPT ou autre, PAS Claude). Framework + logs: stoa-docs/HEGEMON/DECISION_GATE.md.
• Plan validation workflow (convention, pas de hook): plan taggé triggers: [...] → fichier canonique dans docs/plans/YYYY-MM-DD-<slug>.md avec frontmatter validation_status: draft|challenged|validated|rejected. Verdict du challenger lié dans docs/decisions/YYYY-MM-DD-<slug>.md (plan_ref + verdict). Pas d'exécution tant que validation_status != validated. Templates: docs/plans/_template.md, docs/decisions/_template-plan-validation.md. Exemple canonique: docs/plans/2026-04-19-dev-tools-gateway.md (rejected, log #7).

Sécurité

• NEVER reset/change/rotate password ou credential. Human-only.
• NEVER terraform destroy, suppression cluster, topic Kafka prod sans confirmation.
• NEVER hardcode secrets. Vault is the source of truth.
• Secrets K8s YAML: REPLACE_FROM_VAULT placeholder, jamais valeur réelle.
• Fichiers interdits en commit: .env*, *.pem, *.key, *.tfvars, *credentials*.

Documentation

• Docs user-facing → stoa-docs. Runbooks/ops-only → stoa/docs/.
• ADR numbers are owned by stoa-docs. Check the ADR index (stoa-docs/docs/architecture/adr/) before creating a new ADR.
• Jamais dupliquer un guide entre stoa et stoa-docs.

Outillage

• stoactl > curl/bash. Lire .claude/context/cli-reference.md avant de scanner src/.
• Linear MCP = state changes. Local files = context. Batch reads, minimize writes.
• Context7 avant de deviner une API de lib.

Phase Ownership (multi-instance)

• Claim via .claude/claims/<ID>.json + mkdir atomic lock.
• End-to-end ownership: qui claim finit la phase.
• Claim stale = 2h sans activité → auto-release.

Repos