mcpforwork AGENTS.md

AGENTS.md — source of truth for all agents and contributors

Everything here binds every coding agent (Claude Code, Codex, Cursor) and every human contributor. CLAUDE.md only adds Claude-Code-specific notes; on conflict, this file wins. All prose, code, comments, and docs are English-only.

The full product specification lives in docs/PRODUCT_PLAN.md. Section references such as "§Architecture spec" point there.

---

1. Product invariants (never violate)

1. The LLM is the client. No server-side LLM calls, ever. No openai/anthropic SDK importable from domain/, services/, ports/, or packs/ — enforced by import-linter in CI.
2. Graduated autonomy, consent-based. Never submit without a recorded consent check: request_submit is the only place a submit directive can be issued, and consent artifacts (L1 approval, L2 policy) are written exclusively by the human-session HTTP API — never by an MCP tool (ADR 0005). Supervised (L0) is the default.
3. Open-core. Every feature works self-hosted on SQLite with no account. Hosted-only concerns (Postgres/RLS, Stripe, mailer) live behind ports.
4. Never fabricate. Every generation brief includes a facts inventory; drafts may only claim what the profile proves. Gaps are acknowledged, never stuffed.
5. Sector/country logic is data, not code. Site knowledge ships as versioned packs in packs/, updatable independently of releases.
6. User owns their data. Export/delete paths are mandatory for any new personal-data table; EEO data is optional and privacy-gated.

2. Architecture (pragmatic hexagonal)

src/mcpforwork/
  domain/       # PURE logic, no I/O; imports nothing from any other layer
  services/     # use cases; signatures (uow, user_id, ...); caller commits;
                # consent + caps + dedup gates live here
  ports/        # typing.Protocol seams ONLY: Database/UoW, Mailer, Billing,
                # FileStore, Clock
  adapters/     # driven implementations: db/{sqlite,postgres}, billing, mail, files
  entrypoints/  # driving, all thin (auth + serialization only): mcp, api, cli
  packs/        # DATA not code: country/sector source packs + schema validator