velobase-harness: Instructions file for Codex

AI Agent Guide

This file is the universal entry point for AI coding tools such as Cursor, Claude Code, GitHub Copilot, Windsurf, and generic agent runners.

Read this file first. Then follow the task and integration routers below before editing code.

Task Router

IF the user asks to build a new product from scratch:

• MUST read docs/en/ai/design.md.
• MUST complete domain design before writing product code.

IF you are about to add a new capability:

• MUST read docs/en/ai/new-module.md first.

IF you are about to create or modify tests (*.test.ts, *.spec.ts, or e2e/*):

• MUST read docs/en/ai/testing.md first.

After development is complete:

• MUST run the checks in docs/en/ai/completion-checklist.md.
• MUST tell the user which checks were run and which were skipped.

Integration Router

IF you touch authentication or login:

• Read docs/en/integrations/auth/README.md.

IF you touch billing, orders, payments, subscriptions, products, credits, or promo codes:

• Read docs/en/integrations/payment/README.md.

IF you touch email delivery or email templates:

• Read docs/en/integrations/email/README.md.

IF you touch database, Prisma, migrations, Redis, or env-backed persistence:

• Read docs/en/integrations/database/README.md.

IF you touch file upload, object storage, CDN URLs, or asset access:

• Read docs/en/integrations/storage/README.md.

IF you touch analytics, feature flags, or product events:

• Read docs/en/integrations/analytics/README.md.

IF you touch ad attribution or conversion upload:

• Read docs/en/integrations/ads/README.md.

IF you touch queues, workers, processors, or scheduled jobs:

• Read docs/en/integrations/queue/README.md.

IF you touch anti-abuse, captcha, rate limiting, IP, country, or security boundaries:

• Read docs/en/integrations/security/README.md and relevant docs/en/features/*/README.md.

Core Rules

Public Repository Boundary

• Treat all repository files, examples, fixtures, comments, commit messages, and pull request descriptions as public material.
• Do not copy non-public product specifications, business rules, strategy, roadmaps, prompts, implementation status, customer data, internal conversations, or local workspace details into this repository.
• Access to a private source for analysis does not authorize publishing it. Private product implementation and documentation belong in an explicitly authorized private destination, not anywhere in this repository, including ignored files.
• Public framework designs must stand on their own and use independently constructed generic examples. Removing names or replacing domain nouns does not make a private workflow public.
• Before delivery, review the entire change for private provenance as well as credentials. Keep private source paths and identifiers out of public text.