# AGENTS.md

This file provides guidance to Codex (Codex.ai/code) when working with this repository.

## Purpose and status

This repository is the Python-first AI Platform workspace. Lead Scoring is the first service; related systems are `DotB-Omni`, `lead-scoring-agent`, and `aihub` under `/home/hung/code/dotb_workspace/`.

The repository contains specifications, project documentation, and the initialized baseline for the Lead Scoring service (`src/lead_scoring/`).

Before implementing or changing Lead Scoring Customer Pilot behavior, read:

- `docs/specs/lead-scoring-customer-pilot.md`: authoritative product behavior, scope, invariants, acceptance boundaries, and cross-service ownership.
- `stack.md`: technology decisions, candidates, evidence, and unresolved stack questions. It does not override the approved specification.

The DotB Vault RFC, initial brief, Grill Brief, legacy reports, drafts, and agent messages are historical/supporting context rather than implementation authority. Exact wire formats become authoritative through released Pydantic models, generated OpenAPI/JSON Schemas, and shared fixtures.

## Communication

- Keep responses short, specific, and decision-oriented.
- Put the decision or conclusion first, followed by only the evidence and next action needed.
- Keep the main context high-signal. Put raw logs, scratch data, and long intermediate reports in `/tmp/` or the appropriate durable document.
- Use lists and compact structure when they make the result easier to scan.
- State assumptions, unresolved decisions, and verification status explicitly.

## Writing

- Write directly and precisely. Avoid buzzwords, filler, and repeated explanations.
- Comments explain intent, invariants, trade-offs, or non-obvious constraints, not syntax or line-by-line behavior.
- Do not add speculative documentation, abstractions, or metadata that the repository does not need.
- Do not use emoji or em dashes in new prose, comments, or reports. Preserve emoji and punctuation that are part of existing paths or quoted source text.

## Delegation

- Prioritize standard subagents over teammates to minimize token overhead. Spawn multiple subagents when parallel execution is genuinely needed.
- Pick the agent type matching the task from available configured agents (e.g., `explorer`, `implementer`, `tester`, `researcher`, `adversarial-reviewer`, `general`, `codebase-memory`).
- Delegate context-heavy or tool-heavy work with a clear scope, completion criteria, and evidence requirements.
- Require condensed handoffs containing conclusions, changed paths, verification, and uncertainty. Do not paste raw logs into the main context.
- The main context retains final decisions and integration responsibility. Agent messages are evidence, not user approval.

## Agent skills

### Issue tracker

Local Markdown issues are stored under `.scratch/<feature-slug>/`. See `docs/agents/issue-tracker.md`.

### Domain docs

The repository uses a single-context domain layout. See `docs/agents/domain.md`.

## Project knowledge

- `AGENTS.md` is the project map for conventions, verified commands, boundaries, and gotchas.
- `docs/specs/lead-scoring-customer-pilot.md` is the approved source of truth for Lead Scoring Customer Pilot product behavior and build boundaries.
- `stack.md` is the primary record for technology decisions and unresolved stack questions; it cannot override the approved spec.
- `docs/` contains shared project knowledge intended for version control.
- `/tmp/` is for scratch data, raw logs, and temporary handoffs.
- Released Pydantic models, generated OpenAPI/JSON Schemas, tests, and shared fixtures become the exact executable contract when they exist.

## Documentation

- Put temporary reports, raw logs, and scratch material in `/tmp/`.
- Put durable team knowledge in `docs/` and include it in version control.
- Use `vault/` only for durable project-local knowledge that must not be committed.
- New durable Markdown documents under `docs/` or `vault/` use minimal YAML frontmatter:

```yaml
---
title: Document title
description: A short description of what the document contains and when it is useful.
status: draft
tags: []
---
```

- `title` and `description` are required. For governed specs, `status` may be `draft`, `review_ready`, `approved`, or `deprecated`; other existing document schemas keep their established status vocabulary. `tags` is optional.
- Do not add metadata that Git, the filesystem, or existing tooling can derive.
- Preserve the format and metadata schema of existing documents. Do not add frontmatter, reformat, move, or normalize existing files unless the task explicitly requests migration.
- `AGENTS.md`, README files, and files with an existing schema keep their established format.

## Repository structure

- `src/lead_scoring/`: Lead Scoring production service package and CLI tools.
- `alembic/`: database migrations for PostgreSQL.
- `tests/`: test suite including health check, OpenAPI CLI, and migration lifecycle.
- `docs/specs/lead-scoring-customer-pilot.md`: approved Lead Scoring Customer Pilot specification.
- `docs/`: durable shared project documentation.
- `.scratch/`: local untracked draft specs and issue tickets used by agent skills.
- `stack.md`: technology decisions and unresolved stack questions.
- `.codex/settings.json`: project hook configuration.
- `.codex/hooks/post-edit-check.py`: Python-only PostToolUse feedback hook.

## Product and frontend boundary

The frontend boundary is approved for Customer Pilot: DotB-Omni owns all customer-facing Lead Scoring configuration and HITL UI. AI Platform may provide only an internal Dev Console for fixtures, contract testing, failure testing, and allowlisted integration verification; it must not duplicate Omni business UI.

When the internal Dev Console is implemented:

- Use Svelte 5 and TypeScript with Bun, Vite, and Vitest. Add SvelteKit only when routing, SSR, or deployment requires it.
- Generate types from backend OpenAPI and consume them through `openapi-fetch`.
- Keep shared transport concerns such as authentication and error handling outside generated code.
- Use the official Svelte tooling, including `@sveltejs/mcp` autofixer feedback and `svelte-check`.
- Use Playwright only for important end-to-end user flows.

TypeScript 7 native compiler and language server are pilot candidates, not the adopted project default. Test them project-locally before changing global runtimes or the shared `mcpls` configuration.

## Engineering principles

- Follow YAGNI. Implement only what the current requirement needs; do not add speculative abstractions, extension points, compatibility layers, or infrastructure.
- Prefer the simplest design that preserves clear boundaries and can be changed safely.
- Reuse the standard library and established, actively maintained packages when they reduce code and operational burden. Avoid dependencies for trivial behavior.
- Keep code explicit. Use precise names, short control flow, and direct data transformations. Avoid cleverness, hidden side effects, global mutable state, and premature optimization.
- Prefer composition over inheritance and functions over classes. Introduce a class only when state, lifecycle, or a framework contract genuinely requires one.
- Keep a functional core with side effects at the boundaries. Isolate I/O, persistence, network calls, clocks, and environment access.
- Organize modules by capability or domain responsibility, not by arbitrary technical layers.
- Avoid wrappers that only rename another API. Every abstraction must remove meaningful complexity or enforce a real boundary.
- Preserve one clear source of truth for contracts, configuration, and domain rules.

## AI-native code

Write code that humans and coding agents can understand with minimal hidden context:

- Make dependencies, inputs, outputs, errors, and side effects explicit.
- Use typed, stable contracts at module and service boundaries.
- Keep related implementation and tests easy to locate.
- Prefer deterministic behavior and small composable functions.
- Document decisions and non-obvious constraints, not syntax or line-by-line behavior.
- Match existing conventions before introducing a new pattern.
- Make the smallest coherent change and remove superseded code instead of leaving parallel implementations.

## Verified commands

- `uv sync`: sync workspace dependencies and environment.
- `uv run pytest`: run pytest test suite against Python 3.13.
- `uv run ruff check src tests`: run lint checks across source and tests.
- `uv run ruff format --check src tests`: check code formatting.
- `uv run pyright`: run Pyright static type checker.
- `uv run ty check`: run project-local ty type checker.
- `uv run generate-openapi`: deterministically generate root `openapi.json`.
- `uv run generate-openapi --check`: verify that `openapi.json` is present and matches the current backend contract.
- `uv run generate-webhook-contract`: deterministically generate terminal webhook contract pack.
- `uv run generate-webhook-contract --check`: verify that webhook contract pack is present and matches current models.
- `uv run generate-polling-contract`: deterministically generate scoring run polling contract pack.
- `uv run generate-polling-contract --check`: verify that polling contract pack is present and matches current models.
- `uv run generate-contract-pack`: deterministically generate the versioned shared Contract Pack.
- `uv run generate-contract-pack --validate-fixtures`: validate provider and consumer fixture expectations.
- `uv run generate-contract-pack --check`: verify the versioned Contract Pack and checksums are present and current.
- `uv run alembic upgrade head`: apply database migrations up to head.
- `uv run alembic downgrade base`: revert all database migrations.

## Deterministic generation

- When a verified project generator exists, use it instead of manually editing derived files.
- Treat OpenAPI output and generated frontend types as derived artifacts. Regenerate them from the backend contract and require the authoritative verification command to detect drift.
- Do not edit generated files manually unless the project workflow explicitly requires it.

## Safety and scope

- Inspect a path before overwriting or deleting it. Preserve existing configuration, documentation, code, and data unless the task explicitly authorizes removal or migration.
- Do not expose secrets in logs, reports, handoffs, or generated artifacts.
- Do not install packages, modify system configuration, or create permissions and background services without explicit approval.
- Bootstrap production code only after the relevant product and implementation decision. Customer-facing Lead Scoring UI remains owned by DotB-Omni.

## Tooling and verification gotchas

- Root `openapi.json` and frontend build output remain covered by the ignore policy; the versioned Contract Pack OpenAPI artifact is generated and committed, and must not be edited manually.
- The project PostToolUse hook is configured in `.codex/settings.json` for `Write` and `Edit`. It handles Python files via `ruff` (safe fix and format). Full type-checking (`pyright`, `ty`) and test suites belong to explicit verification steps. Preserve the working-tree modification to `.codex/hooks/post-edit-check.py` unless explicitly asked to change or reset it.
- Do not modify `/etc`, package-manager state, system services, drivers, kernel settings, global Node/TypeScript versions, or the shared `mcpls` configuration as part of repository work unless explicitly approved.

## Quality of life

Pyright LSP is available for semantic navigation. Use it for definitions, references, hover types, document and workspace symbols, and call hierarchy; then read the relevant implementation to understand business rules and side effects.