Entity, money, identity, records
Business operating system
Formation, banking, collaboration, insurance, meetings, contracts, payments, and financial control before code outruns the company.
Lessons learned from a technically non-technical CEO that has never written a line of code by hand.
A business-school case study, technical field manual, and calm first-week playbook for founders building with Claude Code and Codex.
Read front to back for the complete framework, or use these lenses to enter where your current venture is most fragile.
Entity, money, identity, records
Formation, banking, collaboration, insurance, meetings, contracts, payments, and financial control before code outruns the company.
Architecture, trust, UI, operations
An exact modern baseline, its tradeoffs, and the boundaries that turn one repository into a durable modular monolith.
Law, skills, hooks, proof
How Claude Code, Codex, persistent runtimes, and parallel workers become measurable operating leverage instead of prompt roulette.
So you have an idea that you’ve validated—or you’re working on a new venture that is already proven.
You know the customer, the painful job, and roughly what someone will pay to make that job easier. You can describe the product without hiding behind the words platform, ecosystem, or AI-powered. The next temptation is to open a coding agent, type “build the app,” and watch a surprisingly convincing demo appear.
Do not confuse that moment with having a software company.
A demo proves that a model can produce a plausible interface. A company needs a system that can preserve customer data, collect money, recover from failure, explain itself to the next person, and accept thousands of future changes without becoming a haunted house. Agentic engineering makes that system dramatically faster to create. It does not make the system optional.
This is the useful way to think about the opportunity:
Agents lower the cost of converting clear judgment into working software. They do not eliminate the need for clear judgment.
The founder’s job is no longer to personally manufacture every line. The job is to define reality precisely enough that a machine can help build it, install rails that keep the machine inside that reality, and create feedback loops that make every future session more capable than the last.
This field guide explains how to do that. It covers the business operating system around the code, the exact full-stack technical baseline I would choose today, the repository documents and automated gates that make agents reliable, the difference between a coding assistant and an agent runtime, the most common architectural traps, and a hands-to-keyboard sequence for your first week.
This stack reflects lessons learned while building real products, including Promptable.
It does not mean incurious. It does not mean outsourcing every decision. It means you may not write production code manually, but you learn to reason about systems: state, contracts, failure modes, security boundaries, component ownership, tests, deployment, and customer impact.
You should be able to answer:
Those are engineering questions. None require you to enjoy typing semicolons.
The best founder-agent relationship is not “prompt, pray, and refresh.” It is a loop in which business evidence becomes a narrow product decision, the decision becomes repository truth, the agent implements a thin slice, automated and rendered proof expose the gaps, and customer behavior updates the next decision.
Open the full-size diagram · Speed compounds when customer evidence and implementation proof update the same operating loop.
The speed comes from tightening this loop, not from making the first generation larger.
Technology choices feel permanent when you are new and surprisingly reversible when you understand the boundaries. The dangerous choices are not usually “Postgres versus another competent database.” They are hidden coupling, missing contracts, unowned state, and operational commitments you did not know you were making.
Before comparing tools, write one page that answers:
These constraints select the architecture. The logo on the database comes later.
Score every material choice against six questions:
| Dimension | Ask | Prefer |
|---|---|---|
| Reversibility | Can we replace it behind a local adapter? | Small interfaces and portable data |
| Legibility | Can a new human or agent locate the truth quickly? | Conventional structure and explicit docs |
| Operational weight | What must we monitor, patch, back up, and recover? | Managed infrastructure until scale proves otherwise |
| Security boundary | Does it enforce authorization or merely display it? | Server and database enforcement |
| Feedback speed | How quickly can we prove the change locally and in CI? | Deterministic installs and fast tests |
| Economic fit | Does the cost scale with value or surprise us before revenue? | Transparent usage and exit paths |
No choice wins every column. The point is to make the trade instead of inheriting it accidentally.
Open the full-size diagram · Start with customer and risk constraints; let them select infrastructure instead of beginning with vendor logos.
For a new full-stack SaaS product, my default is one repository, one primary web application, one database, and a separately runnable worker process in the same codebase. This is a modular monolith.
It gives you:
The word modular matters. Route handlers should not contain the whole business. UI components should not call the database. Email jobs should not be hidden inside button-click requests. Modules need explicit responsibilities even when they share a repository.
Start with folders that communicate those responsibilities:
src/
app/ # routes, layouts, server-rendered composition
features/ # product capabilities and their UI composition
components/
ui/ # owned primitives and semantic adapters
system/ # reusable product-level patterns
server/
api/ # request parsing, auth, response mapping
services/ # business operations
repositories/ # persistence boundaries
auth/ # identity and authorization helpers
jobs/ # queue producers and job definitions
workers/ # job consumers
lib/ # narrow cross-cutting utilities
openapi/ # backend-owned API description
supabase/migrations/ # append-only database history
docs/ # durable architecture and product lawMicroservices become appropriate when independently scaling, deploying, securing, or owning a domain creates more value than the coordination cost. “We may be big someday” is not that evidence. A service boundary before a stable domain often gives you distributed confusion.
You will encounter two common codebase archetypes.
The first is operationally mature but structurally weathered. It has customers, migrations, billing webhooks, storage, queues, security patches, and a wide test suite. It also has older framework versions, semver drift, duplicated frontend patterns, handwritten API calls, and documentation that describes a younger system.
The second is structurally modern but operationally incomplete. It has exact dependency pins, a beautiful token system, owned components, excellent agent instructions, browser evidence, and a generated-client direction. It may not yet have real tenancy, durable workers, billing recovery, or years of ugly production edge cases.
Neither is “better.” They have matured along different axes.
| Concern | Operationally mature system | Structurally modern foundation | What to carry forward |
|---|---|---|---|
| Data | Real schema history and tenant policy | Clean but thin contracts | Real authorization patterns, documented cleanly |
| Backend | Services, jobs, retries, webhooks | Better boundary intentions | Proven operations behind explicit interfaces |
| Frontend | Feature-rich, often inconsistent | Governed tokens and owned components | Modern ownership plus real states |
| Tooling | Stable but may be dated | Exact and reproducible | Exact current baseline with upgrade policy |
| Tests | Deep product history | Strong visual and accessibility gates | Both behavioral depth and rendered proof |
| Agents | Instructions may be sparse | Repository law may be excellent | Make operational truth machine-discoverable |
Open the full-size diagram · Production learning and structural clarity are independent forms of maturity; the strongest foundation carries both forward.
The target is not a forced code merge. It is a merger of learned constraints: production-grade backend instincts, disciplined frontend ownership, and repository governance that lets agents see both.
Use exact versions for the core toolchain. A lockfile tells you what resolved on one install; exact package.json versions tell collaborators and agents what you intended to resolve on the next one.
Pin:
Upgrade deliberately, in a dedicated change with release notes, migration notes, and full verification. Do not let a feature branch quietly upgrade the compiler.
At the same time, wrap volatile providers behind small local modules. Your application should call sendTransactionalEmail, not scatter provider-specific SDK calls across route handlers. It should call generateStructuredResult, not bind every feature to one model identifier. Abstraction earns its keep where change is probable and the local contract is clear.
Do not manufacture generic abstractions for stable domain language. WorkspaceInvitationService is legible. UniversalEntityActionManager<TContext> is usually a tax paid to nobody.
An agent can build a checkout page before you have a legal entity, a bank account, an owner for customer support, or a way to reconcile the money. That is not speed. It is deferred coordination.
The business stack should create a clean chain from identity to money to records:
Open the full-size diagram · The company around the code needs the same clear ownership, records, and control boundaries as the application.
Here is a practical founder stack. These are opinions, not universal endorsements.
| Job | Default | Why it earns a place | Important boundary |
|---|---|---|---|
| Formation | Stripe Atlas | Formation workflow, standard documents, EIN and founder-equity mechanics in one place | It is not your lawyer, accountant, or tax adviser |
| Banking and spend | Mercury | Startup-oriented banking interface, cards, transfers, invoices, and spend visibility | Mercury is a fintech company; banking services come from partner banks |
| Identity and collaboration | Google Workspace | Domain email, Calendar, Meet, Drive, Docs, and Sheets under managed accounts | Turn on MFA, recovery controls, groups, and offboarding immediately |
| Insurance | Corgi | A founder-oriented path to understanding and purchasing business coverage | Coverage needs are company-specific; read exclusions and limits |
| Operating model | Claude, Codex, Excel, and Google Sheets | Fast scenario analysis, reconciliations, forecasts, and board-ready models | Models can be wrong; preserve formulas, sources, review, and professional books |
| Payments | Stripe | Deep payment, subscription, tax, invoicing, and webhook infrastructure | Payment state belongs on the server and must reconcile from webhooks |
| Merchant-of-record option | Polar | Worth evaluating when merchant-of-record simplicity fits the business | Compare product fit, geography, tax handling, margins, and exit path |
| Contract review | Crosby | AI-assisted contract workflow can make routine review faster | Material agreements still deserve qualified counsel and human accountability |
| Domains and DNS | Namecheap | Straightforward registration and DNS management | Registrar access is a crown-jewel account; use MFA and renewal protection |
| Meeting memory | Granola | Turns founder calls into searchable notes without converting the meeting into clerical work | Follow consent, confidentiality, retention, and customer-policy requirements |
| Code and change history | GitHub | Code hosting, pull requests, issues, actions, and a durable audit trail | Protect the default branch and treat admin tokens as production secrets |
| Local model ecosystem | Hugging Face | Models, datasets, model cards, and tooling for experiments that can run locally | Inspect licenses, provenance, hardware needs, and data-handling implications |
| Equipment | Apple laptop plus external monitors | Excellent battery life, Unix tooling, local model experimentation, and enough screen space for parallel evidence | Buy for workload and reliability, not as a substitute for good system design |
At the time of writing, the opinionated power-user setup is:
That is $400 per month before API usage. For a founder who uses both as daily production tools, the useful comparison is not another consumer subscription. It is the cost of engineering throughput, research, QA, and cognitive leverage. For an occasional builder, start lower and upgrade only when limits interrupt valuable work.
Subscriptions and API billing are different budgets. A plan may include an interactive coding surface without covering every programmatic model call your product makes. Track:
Customer calls contain product requirements, language for marketing, objections, security concerns, implementation details, and commitments. The mistake is letting all of that remain trapped in memory or a chronological pile of transcripts.
After every important conversation, convert the notes into one or more durable objects:
The meeting tool captures. Your operating system routes.
Claude and Codex are excellent at explaining a workbook, generating formulas, checking reconciliation logic, normalizing transaction exports, building scenarios, and writing the narrative behind a forecast. They are also capable of confidently propagating a false assumption through twenty beautifully formatted tabs.
Use a controlled workflow:
The same pattern applies to contracts, security questionnaires, insurance, and HR: agents prepare, compare, organize, and surface risk. Accountable professionals decide where the law, money, or customer trust requires them.
Your highest-risk accounts are the domain registrar, company email administrator, GitHub organization, cloud host, bank, payment processor, password manager, and production database. Losing any one can stop the company.
Set up:
Do not paste production secrets into chats, issues, screenshots, or repository files. A coding agent should receive credentials through environment or secret-management boundaries, and only the credentials needed for the current scope.
For a greenfield full-stack SaaS application in July 2026, this is a coherent baseline—not a requirement that every package survive forever.
| Layer | Recommended baseline | Why |
|---|---|---|
| Package manager | Bun 1.3.14, exact | Fast installs, scripts, and a single lockfile; pin it in packageManager |
| Production runtime | Node.js 24 LTS | Conservative production runtime with a long support window |
| Web framework | Next.js 16.2.10 App Router | Current stable foundation, server rendering, route handlers, metadata, and improved Turbopack behavior |
| UI runtime | React 19.2.7 | Current stable React line aligned with the framework |
| Language | TypeScript 6.0.3, strict | Modern checking without treating an emerging compiler generation as a casual upgrade |
| CSS | Tailwind CSS 4.3.3 | CSS-first configuration, native custom properties, OKLCH-friendly theming, modern browser primitives |
| Components | shadcn-owned source on Base UI 1.6.0 | Accessible behavior from primitives; visual and compositional ownership in the repository |
| Database and auth | Supabase Postgres + Auth + RLS | Managed relational data, identity, migrations, and database-enforced tenant boundaries |
| API contract | OpenAPI + generated TypeScript client | Backend owns the contract; frontend and agents stop guessing |
| Validation | Zod at request and domain boundaries | Runtime data is not made safe by TypeScript alone |
| Server state | Server Components first; TanStack Query where interactivity needs a cache | Avoid a global client cache until it earns its complexity |
| Local UI state | URL → server → component → context → store | Choose the narrowest durable owner; add a global store last |
| Queue | BullMQ + managed Redis when durable async work appears | Retries, concurrency, scheduling, and job visibility |
| Object storage | Private S3-compatible buckets | Cheap durable objects, presigned access, portable API |
| Billing | Stripe Checkout Sessions + webhooks | Let Stripe own payment UX and authentication where possible |
| Transactional email | Resend behind a local adapter | Simple delivery surface without provider calls throughout the domain |
| AI | A local policy layer over provider SDKs | Centralize model choice, moderation, budgets, logging, and fallbacks |
| Unit/integration tests | Vitest | Fast TypeScript-native behavioral tests |
| Browser tests | Playwright + axe | Rendered behavior, responsive layouts, focus, and accessibility evidence |
| Lint/format | Biome | One fast tool for a broad baseline; supplement with architectural checks |
| Hosting | Vercel for web; managed worker/runtime as needed | Low operating burden at the beginning, with explicit worker boundaries |
Exact versions are a snapshot. The policy is more durable: choose a supported stable line, pin it, write down why, and upgrade intentionally.
A production system already stabilized on Next.js 15 may rationally stay there until an upgrade window. A new system should not inherit that migration merely because the older system is successful.
Next.js 16.2 includes framework and Turbopack improvements that matter to daily agent loops: faster starts, clearer diagnostics, and a current contract for App Router behavior. Next 16 also makes newer conventions the path of least resistance. Starting current means examples, agents, and documentation are less likely to mix old and new behavior.
The tradeoff is change velocity. Current framework lines move. That is why the version is exact, upgrades are isolated, and the project owns browser and build proof. “Latest” is not a strategy; controlled currency is.
TypeScript 6.0 is a deliberate transition release. The rational baseline is the newest version proven compatible with the framework, generated clients, test runner, and editor—not a prerelease chosen to make the version table look ambitious.
Strict mode is non-negotiable. Add narrow lint rules around unsafe assertions, floating promises, and boundary types. Do not turn the codebase into a type puzzle. Types should make illegal product states harder to represent and contracts easier to understand.
Tailwind CSS v4 aligns design tokens with CSS custom properties and modern CSS. Store semantic color roles such as --background, --card, --border, --text-paragraph, and --accent, expressed in OKLCH where practical.
Do not name product tokens after a visual accident like --light-blue-box. Name the job: --status-info-surface, --focus-ring, --interactive-primary. Dark mode is then a remapping of semantic roles, not an inversion filter.
Test at least WCAG 2 AA contrast, visible keyboard focus, forced colors, and reduced motion. Color is never the only status signal.
Open the full-size diagram · One repository can preserve strict internal boundaries while web requests and durable jobs run as separate processes.
The browser never receives a service-role database key. The route layer authenticates, parses, authorizes, and maps errors. Domain services express business operations. Persistence modules contain queries. RLS remains active as a second authorization boundary. Workers consume explicit versioned jobs.
Keep request handlers thin enough to read in one screen:
export const POST = secureHandler( { auth: "required", body: CreateArtifactSchema }, async ({ user, body, requestId }) => { const artifact = await artifactService.create({ actorId: user.id, workspaceId: body.workspaceId, title: body.title, requestId, }); return Response.json({ data: artifact }, { status: 201 }); },);The wrapper is not magic. It is the single place to standardize request IDs, session resolution, schema validation, CSRF policy where needed, rate limits, safe error responses, logging, and timing.
If the product has workspaces, every tenant-owned row should carry a stable tenant key. Every query and mutation should be scoped. Database policies should deny cross-tenant access even when application code makes a mistake.
Open the full-size diagram · Authorization is layered through the request, service, query, and database policy instead of entrusted to the interface.
Write tests with two tenants. Create records for each. Prove a user can read and mutate their own records and cannot read, infer, update, or delete the other tenant’s records. Run those tests against the actual policy path, not only a mocked repository.
Service-role credentials bypass RLS by design. Limit them to controlled server and worker operations, and require explicit tenant scope in those operations. “It only runs on the server” is not an authorization policy.
Use migrations from the first table. Do not edit a migration already applied to a shared environment. Add a new one. Review:
Agents are very good at generating SQL and very bad at feeling the pain of a locked production table. Put migration constraints in repository law and require review for destructive or high-lock changes.
An empty OpenAPI file is intent, not architecture. Build the contract around the first vertical slice.
The backend owns:
Generate the TypeScript client in CI and fail if generation creates an uncommitted diff. UI features import the generated types and client. They do not invent response interfaces that merely resemble the server.
For code that lives entirely inside server-rendered composition, calling a domain service directly can be appropriate. Do not force an HTTP hop inside the same process for ceremony. The contract matters at actual boundaries: browser to server, external clients, separately deployed services, and durable jobs.
Move work out of the request path when it is slow, retryable, scheduled, concurrency-limited, or dependent on an unreliable provider.
Good worker jobs include:
Every job needs an identifier, versioned payload, tenant scope, idempotency strategy, retry policy, timeout, structured logs, and a dead-letter or terminal-failure path. A queue is not a place to hide errors. It is a place to manage them explicitly.
Avoid adding Redis and a worker merely because serious architectures have them. Start synchronous when the work is fast and safe. Extract when customer latency, reliability, or provider behavior supplies the evidence.
If customers upload files:
Object storage paths are not authorization. Signed URLs are bearer credentials until expiry. Treat parsing libraries and converters as part of the attack surface.
A provider SDK call is not an AI architecture. Centralize:
Keep provider-specific objects out of feature components. A feature should request a domain result such as classifyImport or draftFollowUp, not “call model X.” That makes local models, provider changes, and evaluation possible without rewriting the product.
Hugging Face is useful when exploring open models, datasets, embeddings, or local inference. “Local” does not automatically mean private, cheap, or good. Check model licenses, model-card limitations, quantization quality, hardware memory, prompt-data persistence, and whether the local result meets the same evaluation as the hosted one.
For most SaaS starts, use Stripe Checkout Sessions rather than building a custom card form. The payment provider should own sensitive payment entry, authentication flows, and much of the lifecycle UI.
Your server should create sessions from server-owned prices. Never trust a price or entitlement supplied by the browser. Webhook handlers should:
Billing status is not simply isPaid: boolean. Model trialing, active, past due, paused, canceled, and grace behavior in domain language. Decide what access each state grants.
If evaluating Polar or another merchant of record, compare who is the legal seller, tax and invoice responsibilities, supported business models and countries, pricing, payout timing, data portability, customer support boundaries, and how you would migrate. Simplicity is valuable, but know which obligations were removed and which were moved.
shadcn is valuable because it gives you source, not because it gives you a finished visual identity. Base UI provides accessible, unstyled interaction primitives. Your repository owns the adapter, styling, composition, and product contract.
Use three layers:
Feature code should not import Base UI directly. Only owned components/ui adapters may do that. This prevents every feature from inventing focus, portal, animation, and state behavior.
Document each important component family:
Use the narrowest owner that preserves the product behavior:
Avoid duplicating one concept across URL, query cache, and a global store. Derived state should usually be derived, not synchronized through effects.
Self-host WOFF2 fonts with next/font/local, declare weight ranges accurately, and subset only when the license allows it. A distinctive display face can support editorial moments; an exceptionally legible sans should carry long reading and product UI. Use tabular numbers for metrics and financial values.
Choose one primary icon family and own small adapters. Icons inherit currentColor, include predictable sizing, and hide from assistive technology when a text label already communicates the action. Brand icons are different assets, not substitutes from a generic set.
Motion should explain continuity, hierarchy, or causality. Keep it interruptible. Give press feedback immediately. Animate opacity and transforms before layout properties. Preserve focus and semantics throughout exits. Honor prefers-reduced-motion with a complete, calm endpoint—not a broken half-animation.
The difference between “vibe coding” and agentic engineering is not whether an AI generated the code. It is whether the repository makes good decisions repeatable and bad decisions difficult.
Open the full-size diagram · Repository law becomes useful when procedures and automated proof keep it synchronized with implementation truth.
The control plane should answer four things quickly:
Start with a small, accurate set. Empty templates that nobody maintains create false confidence.
README.mdThe two-minute entry point:
AGENTS.mdDurable repository law for Codex and any tool that supports the convention. Keep the root file short enough to remain in working context. Use nested files only where a subtree truly has different rules.
Include:
The official Codex AGENTS.md guidance describes root instructions and more specific nested overrides. Test what the agent actually loaded when rules appear to be ignored.
CLAUDE.mdClaude Code uses CLAUDE.md and supports imports. Keep shared law in one place rather than maintaining two drifting constitutions:
@AGENTS.md# Claude Code notes- Project skills live in `.claude/skills/`.- Use plan mode for high-risk migrations and implementation mode for approved work.- Do not launch a deployment or send external messages without explicit authority.Claude Code’s memory documentation explains the hierarchy and import behavior. If a tool does not read a shared convention directly, bridge it explicitly.
| File | Owns |
|---|---|
docs/ARCHITECTURE.md | runtime topology, module boundaries, sync/async decisions, dependency direction |
docs/BACKEND.md | request pipeline, services, persistence, jobs, idempotency, provider adapters |
docs/DESIGN.md | visual principles, tokens, typography, density, elevation, motion, exceptions |
docs/COMPONENTS.md | owned components, variants, certified usage, gaps, provenance |
docs/SECURITY.md | threat model, tenant model, secrets, uploads, logging, incident paths |
docs/TESTING.md | test layers, required gates, fixture policy, browser matrix |
docs/ACCESSIBILITY.md | keyboard, focus, contrast, semantics, reduced motion, assistive-tech checks |
docs/SEO.md | route classes, canonicals, metadata, structured data, sitemap, measurement |
docs/OPERATIONS.md | environments, deploys, rollbacks, backups, queues, alerts, recovery |
docs/DECISIONS/ | short architecture decision records with context, trade, consequences, review trigger |
Documentation should point to executable truth. If a component ledger claims all popovers share one motion system, an architectural test or demo matrix should make divergence visible.
A repository skill is a focused instruction package for a recurring task: adding a migration, building a UI surface, reviewing auth, creating an API endpoint, running browser verification, preparing a release.
A good skill contains:
Keep the entry file concise and use progressive disclosure for detailed references or scripts. The official Codex skill guide recommends a discoverable description and focused instructions, with supporting resources loaded only when needed.
Do not create one giant “be a great engineer” skill. Broad taste belongs in durable design and architecture law. A skill should make a specific repeated operation safer and faster.
Useful early skills:
bootstrap-featureadd-api-routeadd-database-migrationbuild-owned-componentrender-and-review-uisecurity-reviewrelease-receiptwrite-architecture-decisionA skill is a versioned operating artifact. “This prompt feels better” is not a promotion standard. Keep the current skill and a candidate side by side, run both against the same representative tasks, and promote only when the candidate produces better outcomes without a critical regression.
Use four separate scorecards:
Keep critical requirements non-compensatory. A beautiful result that breaks keyboard access, crosses a tenant boundary, invents an API, or edits a generated file does not pass because its aggregate score is high.
Prevent contamination: the baseline must not inherit the candidate from a global environment, the solver must not see the hidden scoring rubric, and the variants should differ only by the injected skill bundle. Prefer deterministic evidence—contrast calculation, import boundaries, static semantics, browser overflow, test output—before asking another model to judge subjective craft.
Finally, run important skills under both Claude Code and Codex. Their instruction loading differs, so use one canonical skill body with thin tool-specific discovery wrappers. Compare cross-version improvement separately from cross-model parity. Store immutable run artifacts, rubric versions, model snapshots, costs, and critical regressions so the next revision can be compared honestly.
If you repeatedly tell an agent the same thing, decide whether a hook, test, lint rule, or script can enforce it.
Hooks can observe lifecycle events and tool use. Exact configuration and event names differ between Codex and Claude Code, so use each product’s current documentation: Codex hooks and Claude Code hooks.
Good uses:
Bad uses:
Project hooks are code. Review them before trusting the repository.
Model Context Protocol servers let an agent reach systems such as GitHub, databases, design tools, browsers, issue trackers, and documentation. This can be transformative because the agent can inspect evidence and close work without copy-paste. It also expands the blast radius.
For every connector, write down:
Start read-only. Add narrow writes when the workflow is stable. Production database access, payments, email sending, DNS, and deployments deserve explicit approval and stronger isolation.
The most reliable coding prompts have four sections:
## GoalImplement the smallest complete customer outcome.## Context- Read `AGENTS.md`, `docs/ARCHITECTURE.md`, and the linked issue.- The backend contract is `openapi/openapi.yaml`.- Reuse owned components before adding primitives.## Constraints- Preserve tenant isolation and current URL behavior.- Do not add a global store.- Do not deploy, commit, or contact external systems.- Stop if the contract requires a product decision not present in the issue.## Done when- Unit, integration, type, lint, and targeted browser checks pass.- Loading, empty, error, forbidden, and success states are rendered.- Return changed files, commands, results, remaining risks, and screenshots.The prompt names an outcome, supplies local truth, limits authority, and defines proof. “Make it prettier,” “make it scalable,” and “clean this up” force the model to invent the evaluation function.
When you do not know the implementation, say what you can observe:
Good product language is technically useful.
An agent’s final sentence is not evidence. Ask for:
For a UI change, a green typecheck proves only that types compile. For a security change, a unit test around a mocked function does not prove the database policy. Match the proof to the claim.
Open the full-size diagram · The durable output of a painful audit is a better system for the next session, not only a local patch.
When a workflow suddenly feels difficult, resist the urge to add five more sentences of emotional emphasis to the same session. Open a clean session and ask a diagnostic question:
What in this repository makes the requested behavior hard, inconsistent, or easy to implement incorrectly? Investigate without changing files. Map the relevant components, ownership boundaries, existing laws, tests, and current working-tree state. Distinguish root cause from symptoms and return evidence.
Fresh context matters. A long implementation session accumulates assumptions and defensive local decisions. A diagnostic session can inspect the system as evidence.
The usual causes are:
Imagine several toolbar controls that should open with the same spatial continuity. Some feel correct. Two fade in as unrelated floating panels. Another action disappeared during a refactor.
The superficial fix is “make those two animate like the others.” A rigorous audit asks:
The root cause may be that a sophisticated measured morph—geometry, material, interruption, collision behavior, and reduced-motion support—was implemented inside the menu adapter. Rich-content surfaces correctly use a popover for focus and semantics, but the popover only has a basic reveal. The behavior was shared in the design language but not in the architecture.
The correct direction is not to force rich content into menu semantics. It is to extract the visual continuity engine behind owned semantic adapters.
Then the second review should challenge the proposed abstraction:
data-slot contracts are cheaper now than later.This is the deeper lesson:
One implementation per pattern. Semantic adapters may differ; product behavior should have one true owner.
Use this sequence for any painful frontend or backend inconsistency.
Ask for source-only investigation. Record branch, working-tree changes, locks, and overlapping files. Do not debug a moving target by editing it.
Create a matrix of each surface, route, state, semantic primitive, owned adapter, behavior, and exception. Include the “good” reference implementation.
Follow imports from feature to system pattern to primitive to library. Locate where geometry, policy, network access, or state actually lives. Search for parallel implementations and direct primitive imports.
Read docs, ledgers, decision records, stories or demos, unit tests, browser tests, and recent changes. A divergence codified in documentation is more dangerous than an accidental one because future agents will preserve it.
Use primary documentation for the primitive, framework, or API. Confirm semantic responsibilities. A menu is not a popover merely because both float next to a button.
If you cannot, keep investigating. “The animation is inconsistent” is a symptom. “The shared popup behavior is owned by the menu adapter, so correct popover semantics cannot reuse it” is a root cause.
Separate semantic behavior, visual behavior, state, provider integration, and feature composition. Define a replacement API and delete the superseded path in the same migration.
Use a different model or fresh agent to verify load-bearing claims and look for omitted risks: focus, hydration, performance, data loss, migration compatibility, concurrency, and rollback.
First extract with no behavior change. Prove existing tests remain green. Add the new adapter and its edge-case tests. Migrate call sites. Delete old configuration. Update docs and demo evidence together.
Turn the finding into the lightest durable mechanism: an import-boundary test, component ledger row, skill, hook, demo matrix, or CI gate.
Do not ask an agent to “review the whole frontend” as one shapeless task. Build a product-surface inventory, then audit families:
For each family, produce:
This is how design quality becomes infrastructure rather than a cleanup sprint.
The word agent now describes everything from a chat window to a persistent process with payments and a schedule. Use a capability ladder.
Open the full-size diagram · Every increase in autonomy adds leverage and blast radius; observability and permissions must mature at the same pace.
Each step adds leverage and blast radius. Earn the next level with boundaries and observability.
Claude Code and Codex can inspect repositories, edit files, run commands, browse or connect to tools, verify work, and continue across large tasks. Their value comes from different model behaviors and independent perspectives as much as raw generation.
A practical division:
Do not bounce the same vague request between models and call disagreement insight. Give the reviewer the artifact, evidence, constraints, and a specific adversarial brief.
Parallelism helps when tasks are independent and ownership is explicit. It hurts when multiple agents touch the same files, shared state, or unresolved contract.
Good parallel lanes:
Bad parallel lanes:
Use worktrees or isolated sandboxes for separate writers. Assign exact files or directories. Require each agent to report branch, base commit, changed files, verification, and integration assumptions.
You do not need a distributed control plane to supervise several long-running agents. tmux provides durable terminal sessions that survive a closed window or network interruption.
Open the full-size diagram · Durable terminal sessions are enough for serious local orchestration when task ownership and integration remain explicit.
A robust local pattern includes:
tmux solves session durability, not task correctness. Without file ownership and clean handoffs, it merely lets several mistakes run at once.
Coding agents are repository-centered. Persistent agent frameworks add memory, schedules, communication channels, delegated subagents, and longer-running workflows.
Hermes Agent is an open-source personal agent with skills, memory, subagents, scheduled automation, multiple interfaces, and flexible model backends. It is attractive when you want a persistent, self-improving operator you can inspect and customize.
Evaluate its permission model, channel exposure, skill provenance, model costs, update process, and what long-term memory stores. Persistence means old context and credentials become part of the threat model.
OpenClaw is another open personal-agent ecosystem centered on tools, skills, plugins, automation, channels, and subagents. It is useful for understanding what a personal operational agent looks like beyond an IDE session.
Treat community plugins as executable supply-chain dependencies. Start in a constrained environment, review installed skills, and avoid connecting sensitive company systems until logging, confirmation, and revocation are clear.
Vercel Eve approaches agents as deployable TypeScript systems with instructions, skills, tools, durable workflows, sandboxes, schedules, channels, connections, subagents, and evaluations. It is compelling when the agent itself is a product capability you need to develop, deploy, and observe like software.
The tradeoff is platform commitment. Durable workflows and managed primitives reduce infrastructure work, but you should understand runtime limits, portability, data handling, pricing, and how deeply business logic binds to the platform.
Natural is exploring infrastructure for agents to hold identity and use wallets, cards, payments, billing, and related financial rails with auditability. This is the experimental edge of the ladder, and it has only been lightly tested for the purposes of this field guide.
Economic agency should be bounded by:
Do not grant an agent general purchasing authority because a demo transaction worked.
Use Git for code, documentation, prompts, infrastructure definitions, SQL, and other text-based operating artifacts. For binary files such as workbooks and PDFs, Git can still preserve snapshots, although diffs may need companion exports, structured data, or specialized tooling.
The principle is broader than the tool:
The safest high-autonomy environment is isolated, observable, credential-limited, and easy to restore. Full local permissions can be productive for a trusted repository in a disposable environment. They are not a universal default for production systems, personal files, or unknown code.
Write five short artifacts:
The first vertical slice should cross the real system. For a workspace product, that might be:
A signed-in user creates a workspace-owned artifact, sees it in a list after refresh, cannot access another workspace’s artifact, and receives a stable error when validation fails.
That slice proves identity, tenancy, schema, migration, request validation, service boundaries, database policy, server rendering or client fetching, empty/loading/error/success states, and test infrastructure. A dashboard full of static cards proves none of those.
Use a runtime manager and pin versions. Then scaffold:
bunx create-next-app@16.2.10 venture \ --typescript \ --tailwind \ --eslint \ --app \ --src-dir \ --import-alias "@/*"cd venturebun add --exact next@16.2.10 react@19.2.7 react-dom@19.2.7bun add --dev --exact typescript@6.0.3 @types/node@24 @types/react@19.2.17 @types/react-dom@19.2.3If the scaffold’s options or peer requirements have changed, follow current official output rather than forcing this snapshot. Record the final exact versions.
Set:
{ "packageManager": "bun@1.3.14", "engines": { "node": "24.x" }}Add scripts for lint, format:check, typecheck, test, build, test:e2e, and one verify command that runs the required sequence. Commit the untouched scaffold. That commit is your recovery point.
Create:
AGENTS.md
CLAUDE.md
README.md
.env.example
docs/ARCHITECTURE.md
docs/BACKEND.md
docs/DESIGN.md
docs/COMPONENTS.md
docs/SECURITY.md
docs/TESTING.md
docs/ACCESSIBILITY.md
docs/SEO.md
docs/OPERATIONS.md
docs/DECISIONS/0001-modular-monolith.mdKeep every document honest and short. “Not implemented” is useful truth. A fictional architecture is harmful context.
Initialize shadcn for Base UI using the current shadcn documentation. Add only the primitives needed for the walking skeleton. Copying fifty unused components makes ownership less clear.
Define semantic tokens for light and dark themes. Establish:
Build a tiny internal component page that renders every owned primitive in default, hover, focus, disabled, loading, error, and dark-mode states. This is not a public design system. It is an agent-visible proof surface.
Use shadcn Typeset for long-form content instead of hand-styling every Markdown element. Extend it through stable variables and a containing layout; avoid brittle selector overrides that make appended content unpredictable.
Create the Supabase project and local development setup. Add environment validation that distinguishes public browser values from server secrets. Never import server-only configuration through a client module.
Create the first migration:
Write policy tests for two tenants. Add a server-side client scoped to the user session and a separately named administrative client for the rare operations that need it.
Document the tenant invariant in SECURITY.md and the data ownership in BACKEND.md.
Create:
Do not design forty theoretical endpoints. Specify the walking skeleton completely.
Add unit tests for validation and service behavior, integration tests for persistence and RLS, and contract tests for the handler. Make errors actionable for customers and traceable for operators without exposing internals.
Build the real UI with:
Add a Playwright test that creates an artifact, reloads, verifies it remains, attempts cross-tenant access, and captures screenshots at phone and desktop widths. Run axe on the rendered state.
At the end of Day 5, you have a small product system, not a large mockup.
Use customer and runtime evidence to add:
Each capability should arrive as a vertical slice with docs, tests, operations, and rollback—not a package installation followed by TODO comments.
Open the full-size diagram · The first week proves one real vertical slice before adding the operational weight of queues, billing, files, or AI.
Your CI should install from the frozen lockfile and fail in understandable layers:
Open the full-size diagram · CI converts architectural promises into executable gates on every proposed change.
Optimize the fast path so agents run it often. Keep focused commands for a changed package or feature, but require the full gate before integration.
Create separate local, preview, and production environments. Preview is not production and should not expose production data. Production changes require:
Instrument customer outcomes, not only CPU. Measure signup completion, time to first value, job success and latency, payment conversion, retained use, and the failure point in important workflows.
If a customer can discover, understand, or trust the company through a public page, that page deserves the same source-of-truth discipline as application code.
The useful loop is:
Open the full-size diagram · Public discovery compounds when first-hand usefulness, technical accessibility, evidence, and measurement reinforce one another.
Google’s current guidance for generative AI search is refreshingly unmagical: foundational SEO still matters, unique first-hand content matters, pages need to be crawlable and usable, and there is no special schema or llms.txt file that creates ranking advantage in Google Search.
Answer readiness means a page makes it easy for a person or retrieval system to determine:
Do not write robotic fragments for an imagined machine. Write the best answer for a capable human, structure it cleanly, and make the evidence accessible.
Classify every route:
noindex;Only canonical, successful, indexable URLs belong in the sitemap. Preview hosts should be noindex. robots.txt controls crawling behavior; it is not authorization. Private routes need real authentication.
Build canonicals from an allowlisted public origin, never an untrusted request host. Server-render titles, descriptions, main content, and relevant structured data. JSON-LD must describe content visible on the page; it does not grant truth by declaration.
For material public claims, keep a registry:
| Field | Purpose |
|---|---|
| Statement | Exact public claim |
| State | Draft, verified, deprecated, prohibited |
| Evidence | Primary source or internal proof |
| Owner | Person accountable for accuracy |
| Verified at | Last evidence check |
| Review by | Expiry or review date |
| Allowed surfaces | Pages, sales material, support, docs |
| Disallowed wording | Overclaim or legally risky variation |
This prevents agents from copying an expired number or unsupported superlative across the entire site.
A page that cannot be read on a phone, navigated by keyboard, loaded on a mediocre connection, or understood when JavaScript is delayed is less discoverable and less credible.
Make public routes:
h1;Measure Search Console, referrals, qualified conversion, cited pages, customer language, and content decay. Do not optimize for impressions detached from the business.
Use this after the initial repository documents exist:
We are bootstrapping the first walking skeleton for a full-stack SaaS product.## GoalA signed-in member can create one workspace-owned record, see it after refresh,and receive an actionable validation error. A member of another workspace cannotread, infer, update, or delete that record.## Read first- `AGENTS.md` and `CLAUDE.md`- `docs/ARCHITECTURE.md`- `docs/BACKEND.md`- `docs/DESIGN.md`- `docs/SECURITY.md`- `docs/TESTING.md`## Constraints- Preserve the modular-monolith dependency direction.- The backend owns `openapi/openapi.yaml`; generate the browser client from it.- Enforce tenant scope in application code and Postgres RLS.- Use server state first and local UI state only where interaction requires it.- Reuse owned UI components. Do not import Base UI directly from features.- Implement loading, empty, validation, forbidden, request-error, and success states.- Do not add billing, queues, object storage, AI, or a global client store.- Do not deploy, push, or change external systems.- Stop and report if a missing product decision would change the schema or contract.## Workflow1. Audit the current scaffold and report any contradiction with the documents.2. Propose the thinnest vertical implementation and its tests.3. Implement after the plan is internally consistent.4. Run targeted checks, the full verification command, and browser proof at phone and desktop widths in light and dark mode.## Done when- The real database policies pass a two-tenant test.- The generated client has no drift.- Lint, types, tests, production build, and browser checks pass.- Keyboard focus, labels, touch targets, contrast, and reduced motion pass.- Return changed files, commands and results, screenshots, remaining risks, and the next smallest recommended slice.The founders who gain the most from agents will not be the people who memorize the most framework trivia or discover the most theatrical prompt. They will be the people who can define a valuable outcome, make constraints explicit, give capable systems the right context and tools, inspect evidence without ego, and convert every lesson into durable operating leverage.
Your first repository is not merely where the code lives. It is the company’s earliest executable memory. Treat it that way from day one.
AGENTS.mdCLAUDE.md