docs: foundational specs (PRD, architecture, design system, database, security, code style, testing) + AGENTS operational rulebook
This commit is contained in:
AHMED
@@ -34,3 +34,56 @@ corporate tone, no AI vocabulary.
|
||||
Clone https://github.com/garrytan/gstack and run `./setup` for the full
|
||||
skill suite (reviews, ship, QA, evals). This digest is generated — edit
|
||||
scripts/gen-agents-digest.ts, not this file.
|
||||
|
||||
---
|
||||
|
||||
# Anwarpy.ai Operational Rulebook (agents)
|
||||
|
||||
Appended 2026-10-11 by owner request. The gstack digest above is untouched and authoritative for behavior; this section is project-specific operations. The specs live beside it: `PRD.md`, `ARCHITECTURE.md`, `DESIGN_SYSTEM.md`, `DATABASE.md`, `SECURITY.md`, `CODE_STYLE.md`, `TESTING.md` — read the relevant one before touching that layer.
|
||||
|
||||
## Always do
|
||||
|
||||
1. **Work in `web/`** for app code; docs/specs at root. Read before writing: the spec for the layer you're touching + existing patterns in sibling files.
|
||||
2. **Verify before claiming**: `cd web && npx tsc --noEmit` and `npm run build` must exit 0 for any TS change. Behavioral changes get exercised (ghost-read for access changes, curl for API changes, screenshot for UI).
|
||||
3. **Ghost-read after touching access logic**: fetch an intended-VIP post logged out and assert what a stranger sees (full body in free early access; preview+paywall when billing is on).
|
||||
4. **Keep contracts verbatim**: the honest-503 Arabic strings, notice-strip copy, and meta lines are product contracts (PRD §3) — copy them exactly.
|
||||
5. **Record evidence**: a claim without command+output is not verification (launch-doc standard). Test rows use `@example.com` and are deleted after; report prod counts post-cleanup.
|
||||
6. **ADR for structural decisions**: anything changing routes, contracts, policy layer, or schema gets `docs/adr/NNNN-*.md` in the same PR.
|
||||
7. **Clean up**: delete throwaway scripts, temp env files, smoke rows, and dev servers (`pkill -f "next dev"`) when done.
|
||||
|
||||
## Allowed without asking
|
||||
|
||||
- Read anything in the repo; read prod **state** via `ssh root@147.79.102.201` (read-only psql selects, `docker compose logs`, `curl` checks).
|
||||
- Create/edit files under `web/src/`, `web/scripts/`, root docs; run `tsc`, `next build`, vitest, `payload generate:types`, local dev server on :3000.
|
||||
- Run the local seed/backfill scripts against the **local** DB.
|
||||
- Commit to a feature branch; open Gitea PRs (merge = **POST** `/repos/ahmed/anwar-pi-website/pulls/{index}/merge` `{"Do":"merge"}`; PUT → 405).
|
||||
|
||||
## Ask the owner before
|
||||
|
||||
- **Deploying**: `rsync` to the VPS or `docker compose up -d --build` (recipe below) — deploy is owner-visible truth.
|
||||
- **Merging to `main`** (except doc/evidence commits recording verified facts).
|
||||
- **Destructive or irreversible**: DB writes on prod (inserts/updates/deletes beyond smoke-row cleanup), `rm` outside your own scaffolds, `git reset --hard`/force-push, rotating credentials.
|
||||
- **Changing contracts**: launch policy values, API status codes/bodies, the access decision, schema fields, or anything marked «verbatim» in the PRD.
|
||||
- **Spending**: new services, paid plans, DNS/Cloudflare console changes, new dependencies (one justification line in the PR).
|
||||
|
||||
## Never
|
||||
|
||||
- Never print, commit, rsync, or video-render secret values (`.env*`, tokens, `DB_PASSWORD`, `AGENT_API_KEY`, `PAYLOAD_SECRET`). Partial leaks → recommend rotation immediately (precedent: 2026-10-10, 8 chars of DB_PASSWORD).
|
||||
- Never rewrite `access` fields to simulate a launch state; the launch state is `LAUNCH_MODE`.
|
||||
- Never edit an applied migration, restore over the live DB, or run pipeline payloads without the secret scan.
|
||||
- Never add CAPTCHA/rate limits beyond the login lockout, a component library, Tailwind, or a global state lib (recorded decisions).
|
||||
- Never let a VIP body reach an anonymous response (JSON route, files, llms-full, or the future chatbot) when billing is on.
|
||||
|
||||
## Deploy recipe (owner-approved only)
|
||||
|
||||
```bash
|
||||
rsync -az web/ root@147.79.102.201:/root/anwarpi/ \
|
||||
--exclude node_modules --exclude .next --exclude .git \
|
||||
--exclude media --exclude files-private \
|
||||
--exclude '.env*' --exclude '*.tsbuildinfo' # NO --delete (protects backups/, media/, files-private/)
|
||||
ssh root@147.79.102.201 'cd /root/anwarpi && docker compose -f docker-compose.vps.yml up -d --build'
|
||||
# migrations apply on boot; LAUNCH_MODE persists in /root/anwarpi/.env.production
|
||||
```
|
||||
|
||||
Prod scripts (no `scripts/` in the standalone image): `ssh -f -N -L 15432:<db-container-ip>:5432 root@…`, then locally `set -a; source <tmp env>; set +a; DATABASE_URI=postgresql://anwarpi:$DB_PASSWORD@127.0.0.1:15432/anwarpi npx tsx scripts/<script>.ts`; delete the temp env file after. Never echo the password.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user