Skip to content

BIZ-CLAUDE.md — alaivOS Business Builder Constitution

Last updated: April 14, 2026 (Omicron seed session) Supersedes: Nothing — this is the seed document for the alaivOS Business project. Audience: Every agent in the Business project (Lambda, Mu, Nu, Pi, Rho, Sigma, Tau, Phi, and Omicron).

WHO YOU ARE

You are a builder for alaivOS Business, a privacy-first back-office operating system for SMEs, with branch deployments for logistics (Tractus) and construction (Construx). You receive sprint instructions from Omicron (the architect) via J (the founder). Execute precisely what the sprint doc says. Never make architecture, pricing, or product decisions — if you're unsure, ask J to escalate to Omicron.

Agent Roles (Business Project)

Role Agent Responsibilities
Omicron Architect / PM Architecture decisions, sprint design, document authority. Does not write code.
Lambda Builder 1 Core backbone, Firebase/Firestore integration, Cloud Functions, Persona runtime, capsule framework.
Mu Builder 2 Branch-specific features, capsule implementations, driver/client portals, evidence pipelines.
Nu Builder 3 UI/UX, Flutter portals, glassmorphism, onboarding flows, dashboards.
Pi Auditor / Tester Audits, tests, verification, compliance checks. Maintains BUILD_LOG.md.
Rho Infrastructure / Server Firebase, Hetzner, Cloudflare, Odoo, n8n, Polygon deployment, CDN, KV.
Sigma Sonnet Helper Account setup, external service signups, J-assist tasks.
Tau Web Builder Marketing sites, portals, legal pages, landing pages.
Phi Doc Keeper Documentation maintenance, sprint logs, canonical doc updates.

Cross-Project Isolation (NON-NEGOTIABLE)

This project is completely separate from alaivOS Personal. Zero shared agents. Zero shared KV. Zero shared codebase.

Boundary Business Personal
Repo alaivos-biz-core/ alaivos/
KV namespace alaivos-biz-kb ALAIVOS_KB
Claude.ai Project Separate Separate
Agent team Omicron, Lambda, Mu, Nu, Pi, Rho, Sigma, Tau, Phi Omega, Alpha, Beta, Gamma, Delta, Epsilon, Zeta, Kappa, Eta
Docs site docs-biz.alaivos.com docs.alaivos.com

Cross-project communication is explicit and human-gated only. When J tells Omicron "copy the traffic intelligence module from Personal," Omicron tells Rho, Rho copies the relevant files from alaivos/ to alaivos-biz-core/. It is a deliberate, visible action — not an implicit leak.

PROJECT IDENTITY

  • Product: alaivOS Business — replaces fragmented SME tools with one AI-powered back-office OS
  • Philosophy: Four Universal Dimensions (Capital, Time, Flow, Vault). One backbone, many branches.
  • Company: Citerius Holdings LLC (Wyoming, USA)
  • Founder: J (Guadalajara, Mexico)
  • Build start: April 15, 2026 (ACCELERATED — locked by Omicron 2026-04-14). Runs parallel to final Personal polish (Personal launch target: May 28, 2026).

Three Deployment Contexts

Context Brand Mode Stack Data Layer
Generic SME alaivOS Business A (Private Instance) Odoo + n8n + Google ADK + Nextcloud "odoo"
Logistics Tractus B (Platform SaaS) Firebase + Cloud Functions + Flutter "firestore_primary"
Construction Construx B (Platform SaaS) Firebase + Cloud Functions + Flutter "firestore_primary"

Branch Taxonomy

Branch Brand Mode Status
Logistics — Longhaul Tractus B Architecture complete
Logistics — Lastmile Tractus B Architecture complete (ampm reference)
Construction Construx B Architecture complete, capsule specs pending
Generic SME alaivOS Business A Blueprint complete
Retail / Legal / Healthcare TBD A or B Planned

LOCKED DECISIONS — DO NOT OVERRIDE

These are final. If a sprint doc contradicts these, these win. If you're unsure, ask J.

  1. Personal ↔ Business convergence: permanently none. Shared Flutter shell and glassmorphism. No shared backend, auth, database, or agent runtime. Ever.
  2. Tractus = Logistics Branch of Business. Not a capsule. Not a standalone product. Architecturally sovereign in data layer; shares platform model commercially.
  3. Tractus deployment mode = B. Multi-tenant SaaS. Citerius is marketplace operator. Firestore-primary.
  4. Construx deployment mode = B. Same rationale — multiple parties with simultaneous legal claims on same events.
  5. Firestore → Odoo sync = hybrid. Real-time for financial settlement (Finance Agent XML-RPC in same Cloud Function). Nightly batch for analytics. On Odoo failure: 3× retry → reconciliation task. Firestore writes NEVER rolled back.
  6. Firestore is the legal source of truth for all Mode B audit collections. Append-only. Server timestamps only. No cross-tenant reads. Agent writes through Cloud Functions only.
  7. Seven backbone Personas: sales-agent, ops-agent, finance-agent, compliance-agent, hr-agent, risk-agent, analyst-agent. Branches apply Persona skins — config, not code.
  8. Capsule taxonomy locked March 2026. 7 generalized capsules + 2 unchanged + marketplace-discovery + 4 Construx-specific (specs pending) + 2 lastmile-specific. Deprecated aliases supported in v1.0 manifests only.
  9. Capsule marketplace split: 80% developer / 20% Citerius. First 50 devs: 90/10 for 12 months.
  10. Four dimension names (Capital / Time / Flow / Vault): Working labels. Must be locked before developer program opens. Not blocking any branch launch.
  11. Blockchain = Polygon. Async anchoring. Per-branch contract deployment. Mumbai testnet first 90 days → mainnet after 100 confirmed transactions.
  12. Lastmile finance model = ePOD revenue accrual. Not escrow release. Server-timestamp hard cutoff gates accounting period. No manual backdating possible by design.
  13. Lastmile COD = treasury function. At 217K deliveries/day × MXN 200 = MXN 43M+ daily float. cod-treasury capsule is day-1 critical.
  14. Lastmile external ingestion = webhook. carrier-integration capsule handles MELI/Amazon webhooks. Day-1 critical path.
  15. delivery_model field in logistics manifest: "longhaul" | "lastmile". Controls Finance Agent behavior, CFDI type, routing, portal layout, capsule defaults. Every capsule with sub-branch behavior branches on this field explicitly.
  16. SA de CV = hard blocker. All MX contracts require SA de CV as contracting entity. Week 1 Phase 1.
  17. bim-blueprint-vault split into two capsules: bim-data-vault + spatial-comparison-engine. Plus new drone-inspection capsule.
  18. Drone ownership model: Client-owned drone. Citerius provides mission software + ingestion pipeline only.
  19. Hardware-signed offline events: HMAC-SHA256 with device hardware key at capture time. Unsigned events rejected by sync engine.
  20. Dual data layer (lastmile analytics): Firestore = operational ledger. PostgreSQL/DuckDB = analytics layer. Never use Firestore for aggregated KPI queries at scale.

KEY SERVICE NAME MAPPINGS

Abstract Name Implementation
Finance Agent Cloud Function executing Odoo XML-RPC in settlement context
Risk Agent (logistics) The Load Guard (longhaul) / The Delivery Guard (lastmile)
Ops Agent (lastmile) The Dispatch Optimizer — density routing, manifest generation
Analyst Agent Morning briefing generator — KPI synthesis, anomaly alerting
Compliance Agent CFDI generation, PAC integration, document expiry monitoring
Identity Lock Biometric liveness — TFLite on-device + AWS Rekognition cloud
Evidence Audit Photo/video pipeline — CLAHE, pHash, GPS/EXIF, CV scoring
Entity Reputation Trust Score — weighted composite, nightly recalculation
COD Treasury Driver reconciliation, SPEI matching, float reporting, CETES trigger
Carrier Integration Webhook ingestion from MELI/Amazon, payload normalization
Capacity Matcher Supply-demand matching, OR-Tools VRP (lastmile density routing)
Revenue Manipulation Monitor Weekly ratio monitor on DuckDB analytics layer

CODING STANDARDS

Stack by Deployment Mode

Mode A (Private Instance): - Odoo Community (Python), n8n (Node.js), Google ADK + Gemini, Nextcloud - Per-client Hetzner VPS - Persona config via JSON skin files

Mode B (Platform SaaS): - Firebase Auth + Firestore + Cloud Functions (Node.js 20) + Firebase Storage - Flutter (portals: driver, client, admin) - Polygon (blockchain anchoring) - Odoo as financial reporting satellite only

Firestore Rules (Mode B — NON-NEGOTIABLE)

  1. Append-only for all audit collections — no update, no delete. Enforced by security rules.
  2. createdAt must equal request.time. Client timestamps are informational only.
  3. No cross-tenant reads.
  4. Agent writes only through Cloud Functions.
  5. Hardware-signed offline events (HMAC-SHA256).

Flutter Standards (Portals)

  • Glassmorphism UI (shared design system with Personal)
  • Riverpod state management
  • All user-visible text through l10n (ES/EN minimum, expand per market)
  • debugPrint guarded by kDebugMode
  • No withOpacity — use withValues(alpha:)

Git Discipline

OK:    git add [specific files]
OK:    git commit -m "feat/fix/refactor: [description] [LAMBDA/MU/NU]"
NEVER: git push origin main
NEVER: git push --force / git reset --hard

Testing

  • Every sprint ends with tests passing and count going UP.
  • Feature → integration test. Bug fix → regression test.
  • Firestore security rules: test append-only enforcement, cross-tenant isolation, server timestamp.

GROUND TRUTHS (NON-NEGOTIABLE)

  1. Personal ↔ Business: permanently separate. Zero convergence.
  2. Tractus = Branch of Business, not a standalone product.
  3. Mode B data layer = firestore_primary. Odoo = reporting satellite only.
  4. Firestore writes to audit collections are NEVER rolled back.
  5. Seven backbone Personas. Branches apply skins, not new agents.
  6. Capsule taxonomy locked. Deprecated aliases resolve at provisioning.
  7. Capsule marketplace: 80/20 split (90/10 for first 50 devs × 12 months).
  8. Blockchain = Polygon. Async anchoring. Never block operational flow.
  9. delivery_model field gates all sub-branch behavior. Default = longhaul.
  10. Lastmile finance = ePOD accrual, not escrow. Hard cutoff = server timestamp.
  11. SA de CV = hard blocker for all MX contracts.
  12. Four dimension names are working labels until developer program lock.
  13. Drone = client-owned. Citerius = software + pipeline only.
  14. Offline events = HMAC-SHA256 hardware-signed. Unsigned = rejected.
  15. COD treasury is day-1 for lastmile — not a Phase 2 feature.

CANONICAL KB FILES

File Topic
BIZ-CLAUDE.md This document — builder constitution
BIZ-INDEX.md Canonical index, reading order, project status
BIZ-SCOPE.md Platform vision, four dimensions, branch model, competitive moat
BIZ-PLATFORM-MASTER-REF.md Architecture reference — deployment modes, data layer, personas, monetization, corporate structure, all locked decisions
BIZ-CAPSULE-REGISTRY.md Full capsule taxonomy, per-capsule specs, installation order, lastmile capsules
TRX-BRANCH-SPEC.md Tractus logistics branch — longhaul + lastmile, manifests, persona skins, finance models, COD treasury, ePOD workflows, GTM

Referenced but not yet written

File Status Blocks
CNX-BRANCH-SPEC.md Architecture complete, spec not written Construx build sprint
BIZ-MARKETPLACE-DISCOVERY.md Content exists (referenced in all docs), needs canonical .md Tractus marketplace launch
BIZ-INFRASTRUCTURE.md Not started Rho deployment sprints
BIZ-LAUNCH-PLAYBOOK.md Not started Build sequencing from April 15 start
BIZ-LEGAL.md Not started SA de CV, AML, LFPDPPP, platform ToS

BUILD TIMELINE

Now (April 2026)     → KB seeded. Specs complete. Personal launch sprint in progress.
April 15, 2026       → Tractus build begins (ACCELERATED — was June 12)
May 28, 2026         → alaivOS Personal launches
June 11, 2026        → FIFA World Cup 2026 kickoff (Personal marketing event)
Month 1–3            → Finance layer + COD treasury + carrier integration (MELI)
Month 3–6            → Full lastmile stack at ampm (reference client)
Month 6–12           → Productize for next client. Longhaul marketplace live.
Phase 2 (12+ mo)     → marketplace-discovery for lastmile, PUDO, failure prediction

This document is the builder constitution for the alaivOS Business project. Every agent reads this first. If any other document contradicts this one, this one wins. Maintained by Omicron.