From 944782facaaaa440826664bbe15afc9acf72911d Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Sat, 28 Feb 2026 08:23:57 +0000 Subject: [PATCH] Add AGENTS.md with comprehensive AI coding agent instructions Co-authored-by: snevemoney --- AGENTS.md | 132 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 132 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..47e27e6 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,132 @@ +# AGENTS.md — AI Coding Agent Instructions + +Read this file before making any changes. It is the entry point for all AI coding agents (Cursor, Copilot, Claude Code, etc.). + +## Behavioral Contract + +**Read `docs/CLIENT_ENGINE_AXIOMS.md` first.** It is the non-negotiable law of this repo. Every suggestion, implementation, and prompt must comply with it. Key constraints: + +- No cold outreach, funnels, hype, urgency language, or guarantees. +- No auto-send emails, auto-build projects, or bypassing money-path gates. Human approval is mandatory for all money-path steps. +- No pivoting the niche, offer, or positioning. +- Proposals must frame change as safe and reversible. No oversell. +- Proof must be observational only — no invented numbers, no superiority claims. +- The AI role is **Sales Engineer × Solution Architect × Pattern Historian**: guide without pushing, constrain decisions, think in trade-offs and human risk. + +For Copilot behavior specifics, see `docs/COPILOT_DECISION_RUBRIC.md`. + +## What This System Is + +Client Engine is a private decision engine and execution system for a freelance operator. It captures leads, evaluates them, positions the offer, generates proposals, and gates builds — running safely in the background. + +It is **not** a CRM clone. It is a positioning-first pipeline with hard money-path gates: + +``` +CAPTURE → ENRICH → SCORE → POSITION → PROPOSE → (OWNER APPROVAL) → BUILD +``` + +No proposal without positioning. No build without approval + proposal artifact. No bypass. + +## Tech Stack + +| Layer | Technology | +|-------|-----------| +| Framework | Next.js 16 (App Router), TypeScript | +| Database | PostgreSQL + Prisma ORM | +| Auth | NextAuth v5 (credentials + optional OAuth) | +| AI | OpenAI API | +| Queue | BullMQ + Redis (optional workers) | +| UI | Tailwind CSS v4, Lucide icons, Sonner toasts | +| Testing | Vitest (unit), Playwright (E2E) | +| Deploy | Docker Compose + Caddy on Hostinger VPS | +| Validation | Zod v4 | + +## Project Structure + +``` +src/ +├── app/ +│ ├── api/ # Next.js API routes (RESTful, auth-gated) +│ ├── dashboard/ # Private operator dashboard pages +│ ├── login/ # Auth pages +│ └── page.tsx # Public landing page +├── components/ # Shared React components +├── hooks/ # Custom React hooks +├── lib/ # Core business logic +│ ├── pipeline/ # Pipeline orchestrator, steps, error classifier +│ ├── proof-engine/ # Quiet proof post + checklist generation +│ ├── research/ # Research engine (RSS/feed → lead factory) +│ ├── scoring/ # Lead scoring logic +│ ├── proposals/ # Proposal generation and revision +│ ├── integrations/ # External service integrations +│ ├── jobs/ # Background job definitions +│ ├── notifications/# Notification system +│ ├── llm/ # LLM client utilities +│ ├── db.ts # Prisma client singleton +│ └── db-lock.ts # Postgres advisory locks for concurrency +├── test/ # Test setup +└── workers/ # Background workers (email, queue) +prisma/ +├── schema.prisma # Database schema (source of truth for models) +├── seed.mjs # Base seed script +└── seed-*.mjs # Domain-specific seed scripts +tests/ +└── e2e/ # Playwright E2E tests +docs/ # Operational docs, runbooks, checklists, phase plans +``` + +## Key Files to Read First + +1. **`docs/CLIENT_ENGINE_AXIOMS.md`** — Behavioral law. Read before doing anything. +2. **`PROJECT_CONTEXT.md`** — Single source of truth for what is built, what ships now, what is next, and what is out of scope. +3. **`SYSTEM_MANIFEST.md`** — Mental model, stack, core engines, money-path rules. +4. **`prisma/schema.prisma`** — Database models and relations. +5. **`docs/COPILOT_DECISION_RUBRIC.md`** — How the Copilot brain should behave (flags, silence, tone). + +## Development + +```bash +npm install +cp .env.example .env # Set DATABASE_URL, AUTH_SECRET, ADMIN_EMAIL, ADMIN_PASSWORD +npx prisma db push +npx prisma db seed +npm run dev # http://localhost:3000 +``` + +Environment variables are documented in `.env.example`. Key ones: `DATABASE_URL`, `AUTH_SECRET`, `NEXTAUTH_URL`, `OPENAI_API_KEY`, `PIPELINE_DRY_RUN`. + +## Testing + +```bash +npm run test # Vitest unit tests +npm run test:e2e # Playwright E2E (needs running app + DB) +npm run test:e2e:dry # E2E with dry-run pipeline (no OpenAI key needed) +npm run smoke # Smoke subset of E2E tests +``` + +Dry-run mode (`PIPELINE_DRY_RUN=1`) creates placeholder artifacts without calling OpenAI — use this for testing. + +## Coding Conventions + +- **API routes** live in `src/app/api/` and follow Next.js App Router conventions. Most require auth. +- **Business logic** lives in `src/lib/`, not in API routes or components. Routes are thin wrappers. +- **Pipeline orchestration** uses a single entry point: `runPipelineIfEligible(leadId, reason)` in `src/lib/pipeline/runPipeline.ts`. Steps are idempotent — if an artifact already exists, the step is skipped. +- **Error classification** uses `src/lib/pipeline/error-classifier.ts` with typed codes (`OPENAI_429`, `OPENAI_5XX`, `GATE`, `VALIDATION`, `DB`, `UNKNOWN`). Step failures are stored as `CODE|message` in step notes. +- **Concurrency** is managed with Postgres advisory locks (`src/lib/db-lock.ts`). +- **Status transitions** for leads follow a strict lifecycle: `NEW → ENRICHED → SCORED → APPROVED/REJECTED → BUILDING → SHIPPED`. Only dedicated API routes may set status and money-path fields (approvedAt, buildStartedAt, proposalSentAt, dealOutcome). The generic PATCH `/api/leads/[id]` uses an allowlist and rejects these fields. +- **Artifacts** store all pipeline outputs (enrichment, score, positioning brief, proposal, run reports, proof posts, checklists). Type + title conventions matter — e.g., positioning must produce an artifact titled `POSITIONING_BRIEF`. +- **Database** uses Prisma with `db push` (no migrations history yet). Schema is in `prisma/schema.prisma`. + +## What NOT to Do + +- Do not bypass money-path gates (no setting status/approvedAt/buildStartedAt via PATCH lead). +- Do not add auto-send, auto-build, or any action that skips human approval. +- Do not add cold outreach, marketing funnels, or hype language anywhere. +- Do not add features from the "out of scope" section in `PROJECT_CONTEXT.md` (Coach OS, Pattern Library, AgentPilot, BitBrain) unless explicitly requested. +- Do not use feature-first or "AI-powered" language in proposals or proof content. +- Do not invent metrics or numbers in proof posts — use actual pipeline cost data or say "approx" / omit. +- Do not remove the positioning requirement for proposals. + +## Deploy + +Production deploys use `./scripts/sync-and-deploy.sh` (push + rsync + deploy) or `./scripts/deploy-remote.sh` (git pull on server + deploy). Post-deploy: verify `GET /api/health` returns `ok: true`. See `docs/VPS_DEPLOY_CHECKLIST.md` and `docs/AFTER_DEPLOY_SMOKE_CHECKLIST.md`.