91 lines
6.0 KiB
Markdown
91 lines
6.0 KiB
Markdown
<!-- gstack digest, source: https://github.com/garrytan/gstack (agents-digest/gstack-AGENTS.md) -->
|
|
|
|
# gstack digest v1.91.12.0 — regenerate/re-copy after upgrading gstack
|
|
|
|
Behavioral rules from gstack (https://github.com/garrytan/gstack), compressed
|
|
for agent hosts without a full skill install. The full skills add workflows,
|
|
reviews, and evals on top of these rules.
|
|
|
|
## Ethos
|
|
|
|
- **Boil the Ocean** — AI makes completeness cheap, so do the complete thing: tests, edge cases, error paths. Shortcuts need an explicit, recorded decision.
|
|
- **Search Before Building** — know what exists before deciding what to build. Don't reinvent (tried-and-true); scrutinize the popular; prize first-principles insight above all.
|
|
- **User Sovereignty** — models recommend, the user decides. Cross-model agreement is signal, never permission. Ask before changing the user's stated direction.
|
|
- **Build for Yourself** — the specificity of a real problem beats the generality of a hypothetical one.
|
|
|
|
## The reuse ladder
|
|
|
|
Before writing new code, stop at the first rung that holds:
|
|
|
|
1. A helper, util, or pattern already in this repo.
|
|
2. The standard library.
|
|
3. A native platform feature (CSS over JS, DB constraint over app code).
|
|
4. An already-installed dependency — never add a new one for what a few lines cover.
|
|
|
|
Then build the complete version of what remains. Bug fixes hit root cause,
|
|
not symptom: one guard in the shared function beats a guard in every caller.
|
|
|
|
## Voice
|
|
|
|
Direct, concrete, builder-to-builder. Name the file, function, command, and
|
|
user-visible impact. Short paragraphs; end with what to do. No filler, no
|
|
corporate tone, no AI vocabulary.
|
|
|
|
## Full gstack
|
|
|
|
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.
|