Family rules — index

index Sat Jun 20 2026 00:00:00 GMT+0000 (Coordinated Universal Time) rulesindexmeta

Family rules — index

These are the rules every chirag127/oriz* repo and every agent working in the family must follow. They override anything an agent might otherwise assume from training data or convenience.

If a chat decision contradicts a rule here, see future-overrides-past.md — the chat wins, and the rule file is updated in the same conversation.

Operational HOW for fan-out

• parallel-fan-out-by-default.md — concrete HOW for the parallel-by-default rule: use the Agent tool with run_in_background: true, send 3-6 subagents per turn for independent work, await <task-notification> events, commit + push after each batch. Sized to dodge Anthropic context-window limits.

The five non-negotiables (from AGENTS.md §"five non-negotiable rules")

1. never-hit-quotas.md — architect for headroom; surprise quota walls are a design failure.
2. no-card-on-file.md — Cloudflare Free / Firebase Spark / GitHub Free only; no card EVER.
3. self-update-rule.md — every chat decision lands in knowledge/ in the same conversation.
4. future-overrides-past.md — when chat contradicts knowledge, chat wins; knowledge updates.
5. parallel-fan-out-by-default.md — fan-out subagents for any parallelisable work.

Auto-only tracking (family-wide goal)

• auto-only-tracking.md — every tracked metric in the family must be automatically captured. Manual entry, manual timer, manual journal NOT allowed for system metrics. Manual = decay; auto = honest. Rejects Toggl Track (manual timer); locks Wakatime as sole time-tracking pick. Applies to METRICS, not content (journal entries on oriz-journal-site are intentionally manual creative writing — that's CONTENT, not a metric).

Stricter than no-card

• no-subscriptions.md — no service requiring a subscription, ever; no "free trial then pay".
• cloudflare-pages-only.md — every website and every app in the family hosts on Cloudflare Pages. No exceptions. GitHub Pages is the per-site survival mirror only; Firebase Hosting / Vercel / Netlify / Render / Fly all rejected.

Exceptions to no-card

• aws-lambda-exception.md — AWS Lambda ONLY is admitted as the 4th-rail fallback in the serverless chain (CF Workers → Deno Deploy → Render → AWS Lambda). AWS account requires card at signup but Lambda forever-free (1M req/mo + 400K GB-sec) means $0 charges if quota-bounded. NO other AWS service covered. Locked 2026-06-22 evening.

DNS / SSL constraints

• one-level-subdomain-only.md — subdomains under oriz.in live AT MOST one level deep. CF free-tier Universal SSL covers only *.oriz.in (one wildcard level); 2-level shapes like <name>.api.oriz.in are FORBIDDEN for new work. Use <name>-api.oriz.in instead. 19 grandfathered *.api.oriz.in records remain DNS-only (grey-cloud); GH Pages provisions Let's Encrypt for them. Locked 2026-06-22 evening.

Git rules

• one-branch-only.md — only main, in master + every submodule.
• push-by-default.md — commit AND push to main immediately after every change. Standing authorisation 2026-06-20. Replaces the retired no-push-without-say-so rule. Outward-effect actions (repo delete, paid APIs, store publish) still need confirmation.
• no-force-push-to-main.md — separate explicit instruction required.
• conventional-commits.md — feat / fix / chore / docs / refactor / test.
• repo-naming.md — every new repo slug ends in -site / -ext / -vsc-ext / -cli / -worker / -fn / -data, or is a clean npm-package name. Audit before publish.
• never-delete-empty-placeholder-repos.md — empty repos in the chirag127/oriz* family are deliberate slug reservations, not cleanup candidates. gh repo delete requires explicit, repo-named, current-conversation user authorisation, even on empty repos.

Stack / runtime constraints

• no-hardcoded-secrets.md — everything via envpact.
• no-firebase-admin-in-workers.md — gRPC incompat; use firebase-rest-firestore.
• no-firebase-functions-blaze.md — Cloud Functions require Blaze (card on file); banned. Use GH Actions / CF Workers / CF Pages Functions / Firestore client SDK instead.
• no-paid-self-hosting-only.md — no VPS / Docker / k8s. Cloudflare Pages + Workers + KV/R2/D1 is the compute ceiling.
• no-web3forms-server-side.md — browser-side only.
• no-ad-slots-in-markup.md — AdSense / Ezoic / Mediavine inject at runtime.
• — AdSense + AdMob on every app except `oriz-cs-me-app` and `oriz-janaushdhi-app`.

Tooling / dependencies

• always-latest-deps.md — pnpm add <pkg>@latest; weekly pnpm update --latest --recursive.
• repos-work-independently.md — every submodule must pnpm install && pnpm build standalone.
• use-pnpm.md — pnpm only, family-wide; the global store is what makes "no duplication" work.
• — **SUPERSEDED 2026-06-20** by [`env-example-synced-from-master.md`](./env-example-synced-from-master.md). Kept for audit trail.
• env-example-synced-from-master.md — canonical .env.example at master templates/.env.example; every other repo's copy is synced via ; CI fails on drift; no comments. Pairs with github-org-level-secrets.md and the two-track decision.
• github-org-level-secrets.md — every GitHub Actions secret lives at the chirag127 ORG level (gh secret set --org chirag127 --visibility all); per-repo writes are forbidden — they cause drift. Doppler stays upstream; org-level GH secrets are the runtime CI mirror.

Design + style rules

• no-emoji-in-chrome.md — per family design rules.
• match-surrounding-style.md — semicolons, indent, quotes match the file you're in.
• design-divergence-vs-dedup.md — per-app design-brief variants (Header / Footer / Wordmark, blog's MultiSearch, blog's astro.config) are intentionally divergent and must NOT be forced into generic slot-based components. The 25-lines × 3-apps dedup threshold applies to TRUE duplicates only.

Agent-harness rules

• read-before-edit.md — always Read before Edit; the harness enforces it.

MCQ-learned tastes

• user-prefers-atomic-split.md — when offered fewer-larger-units vs. more-smaller-units, default to more-smaller (repos, packages, files). Mined from override patterns.
• user-prefers-wider-coverage.md — for content / brand surfaces, default to wider scope over narrower; for tools, default to narrower-and-deeper. Mined from override patterns.

Geo + communication constraints

• — Telegram is banned in India; user cannot access reliably. Drafts queue → GH Issues; notifications → GH + email. Do NOT propose Telegram bots for India-resident users.
• communication-stt-friendly.md — user uses STT heavily; accept transcription noise. When ambiguous, pick most-likely interpretation, state it explicitly, proceed. Never ask user to re-transcribe.
• confirm-knowledge-deltas.md — when new user input contradicts existing knowledge, surface the delta explicitly, ask the user to confirm overwrite vs one-off, and only then act. Latest input wins ONLY after explicit confirmation. Pairs with future-overrides-past + keep-knowledge-fresh.