xeo-forge AGENTS.md

Xeo Forge V3 — Agent & Architecture Rules

Product contract: The Control Plane for Agentic Work. Chat is conversation; Work is governed agency.

This file is the contract for working in this repo. Keep it short, keep it enforced. If a change violates a rule here, the change is wrong — not the rule.

1. What this product is

One governed AI agent with reusable execution context:

1. Chat surface — conversational answers and exploration; it never creates a plan or executes write tools.
2. Work surface — intent-aware agent work. Normal messages stay conversational; explicit planning starts Planning, and direct execution requests pause for an auditable user choice.
3. Planning mode — read-only inspection, produces a structured plan for approval.
4. Build mode — executes an immutable approved plan or an immutable, explicitly accepted execution brief.
5. Context layers — Prompt Studio instructions, approved memories, Agent Profiles, and Agent Skills are compiled into the run context.

The agent:

1. receives a conversation or Work request from a user and classifies intent before selecting planning or execution,
2. loads policy, profile, skill, task context, and approved memories,
3. inspects and analyzes (planning) or executes (build),
4. returns a final result and bounded memory candidates,
5. persists full history and audit events,
6. consumes credits per run.

Plus auth, per-user credits, admin controls, ONE global model configuration, reusable profiles and skills, context management, and an inspectable audit trail.

New capabilities must preserve the approval gate, task-scoped authorization, single source of truth, and end-to-end UI-to-persistence behavior.

2. Hard architecture rules (non-negotiable)

1. Single source of truth. One canonical schema per entity. One writer per resource. No dual persistence. No second copy of the same logical data that can drift.
2. One delivery path for events. Task events are persisted with a monotonic per-task seq. SSE replays from the DB only, tracks maxSeq, then forwards live events with seq > maxSeq. No in-memory replay buffer racing the DB. (This is the V1 duplication bug. Do not reintroduce it.)
3. No silent failures. No catch {} without logging. Every caught error is logged with context. Persistence failures must be visible, never swallowed.
4. End-to-end or not at all. No UI control that points at a route that does not exist. No route that only half-works. Build the full path: input → agent → tools → persistence → UI.
5. One global model. All users share one model config. No per-user model selection. Source of truth: model_settings row id=1, seeded from env. API keys are NEVER returned to any client — always masked.
6. Credits are atomic. Debit via conditional UPDATE ... WHERE balance >= ?. Every balance change writes a credit_ledger row with balance_after. No read-then-write race.
7. Authz on every task-scoped route. Owner-or-admin check, always.
8. No ungoverned feature creep. Do not add subagents, teams, connectors, schedules, marketplaces, plugins, analytics, or permission frameworks without a written V3 design, explicit authorization boundaries, and an end-to-end path.
9. No dead code. Don't scaffold for "future features". Delete what isn't used.
10. Typecheck stays clean. tsc --noEmit has zero errors. Never hide errors behind ignoreBuildErrors.