Imported from WelshLabs/sous.tools (AGENTS.md). Install upstream with npx skills add WelshLabs/sous.tools. Copyright stays with the author.

sous.tools System & Agent Rules (Single Source of Truth)

1. Domain-Driven Design (DDD) & Infrastructure

• Strict Boundaries: Next.js apps (e.g., apps/web, apps/pos-simulator) and domain packages (packages/domain-*) are strictly forbidden from importing database clients.
• The Supabase Firewall: NO CLIENT OR UI APP is allowed to access Supabase. Absolutely no one outside of apps/api should have access to or knowledge of Supabase.
• API First & Dumb Transport Layer: ALL network requests must go exclusively through our unified packages/api-client. Native fetch(), axios, or direct endpoint calls outside of api-client are strictly forbidden. api-client is a pure transport layer—it must contain ZERO application business logic. It solely manages generic connections (REST, WS, GraphQL), headers, and the centralized 401 token refresh mutex. It must contain ZERO URL parsing logic and implicitly trust @soustools/config.
• Server-Side Supremacy: Next.js functions strictly as a routing and data orchestration layer. Server Components are the default.
• Config Lockdown & Client/Server Split: process.env is strictly forbidden outside of @soustools/config. All apps must import the type-safe, Zod-validated clientConfig or serverConfig objects. String fallbacks (e.g., || "http://localhost:3000") are explicitly banned.
• Secrets SSOT (Fail Fast): Infisical is the Single Source of Truth for all environment variables. The @soustools/config package contains ZERO default fallbacks. If Infisical credentials fail or are missing, the app MUST immediately process.exit(1).
• TSConfig Management: All tsconfig.json files must extend from the shared packages/typescript-config. No relative paths (e.g., ../../../) are allowed.
• Thin App Router Shells: apps/* directories must remain as hollow as possible. Next.js page.tsx files should act strictly as Server Component entry points that import their corresponding Containers or Views from @soustools/domain-* packages. Building complex components/ directories inside the Next.js apps/* router is forbidden.
• No Global Database Clients: Never use import { supabase }. Use CLS-injected Singleton providers to enforce RLS (Postgres set_config).
• Code-First GraphQL: The API is Code-First GQL (@nestjs/graphql). REST is deprecated except for webhooks, /health, and /v1/auth.
• Concurrency & Soft Deletes: Never execute DELETE queries. Update deleted_at = NOW(). All update mutations must include and increment a version field.
• Event-Driven Boundaries: Domains must decouple via @nestjs/event-emitter. Do not cross-inject domain services to trigger downstream updates.
• Infisical Booting: Apps must boot using the official Infisical CLI (infisical run --env=... -- pnpm start).
• Data Fetching & Offline-First URQL: Interactive/real-time views MUST use the Container/View pattern with URQL GraphQL hooks (useQuery, useSubscription). The URQL client utilizes @urql/exchange-auth to automatically intercept 401s and reconnect WebSockets seamlessly. Use @urql/exchange-graphcache for optimistic offline UI.

2. Component Architecture & Styling

• Feature-Driven Folders: Do not use atoms/, molecules/, or organisms/ as folder names. Group files by their Feature or Domain (e.g., Supplier/).
• Design System vs. Domain Packages: packages/design-system is strictly reserved for generic, highly reusable UI primitives and theming. Domain-specific UI components MUST live in their respective packages/domain-* package.
• Container/View Pattern: Pure presentational UI components must live in *.tsx files and are banned from importing data-fetching hooks or infrastructure logic.
• Logic Quarantines: Business logic, API calls, and state management must be strictly quarantined to *.container.tsx files.
• Tailwind v4: Use the @theme directive in CSS. No tailwind.config file. Strictly use semantic CSS variables (var(--z-overlay)) and the "Midnight Slate" (zinc-*) palette.

3. AI Orchestration & Execution (4-Interface & Kanban Agents)

• Direct Execution: Analyze silently, and immediately use your file-editing tools to execute changes.
• Debt Audits: Review reports in docs/context/cto_summary.md and docs/audits/ (such as knip-report.txt and lint-report.txt) before refactoring.
• GitHub Issue & Kanban Management (MCP): Autonomous agents must inspect ticket details and use GitHub API/MCP to move tickets across the Kanban board ("In Progress" -> "In Review" -> "Done").
• Halt-on-Error with Self-Repair: Run pnpm typecheck && pnpm lint && pnpm test. If errors occur, attempt self-repair up to 3 times before opening a PR or requesting review.
• Async Execution: Heavy AI tasks MUST NOT block HTTP. Return 202 Accepted, queue in BullMQ, and stream via Redis PubSub (GraphQL Subscriptions).

4. Graph Database (Neo4j) & Relational Parity

• PostgreSQL & Neo4j Synchronization: PostgreSQL and Neo4j MUST stay in perfect 1:1 synchronization. Any changes made to the PostgreSQL schema MUST be immediately reflected in Neo4j schema-registry.ts and associated synchronization webhooks.

ARCHITECTURAL MEMORY PROTOCOL (QDRANT)

You have access to a Qdrant vector database via MCP. This is your long-term memory for the sous.tools infrastructure, design decisions, and resolved bugs. You must actively manage this memory.

1. MANDATORY RETRIEVAL (READ): Before answering questions about or modifying infrastructure (Docker, Tailscale, Traefik, Infisical, networking), you MUST query Qdrant for existing constraints, past configurations, or related bug fixes. Do not guess our architecture; look it up.

2. MANDATORY COMMIT (WRITE): You must proactively store new, valuable information into Qdrant. Automatically trigger a memory save when:

• We finalize a new architectural decision (e.g., routing LiteLLM over Tailscale).
• We resolve a complex bug (e.g., fixing Docker string interpolation for Infisical tokens).
• The user explicitly says "remember this" or "document this."

3. MEMORY FORMATTING: When storing a memory, use clear, searchable tags in the payload (e.g., [INFRASTRUCTURE], [BUGFIX], [SECRETS], [TRAEFIK]). Include the problem, the context, and the exact technical solution.

ISSUE GENERATION PROTOCOL (PLANNER AGENT)

When planning epics and sub-tasks with the user, you must use the following strict templates when utilizing the GitHub MCP server to create issues:

1. Epics: Use the .github/ISSUE_TEMPLATE/epic.yml format. Epics must summarize the architecture and list the planned sub-tasks. Label as "Epic".
2. Sub-Tasks: Use the .github/ISSUE_TEMPLATE/agent-task.yml format. The sub-task MUST be extremely detailed (Context, Exact Files in Scope, Step-by-Step implementation instructions, and a specific validation command). Label as "Draft" or "Blocked" until they are ready to be executed by the kanban-orchestrator. Reference the parent Epic number in the issue.