Building the Engine
While Using It

One Stack. No Substitutions.

Every application in the ForgeKit family uses the same technology stack: Next.js 16 with the App Router, TypeScript throughout, Tailwind CSS for styling, Drizzle ORM against Neon Postgres, Clerk for authentication and multi-tenant isolation, and Vercel for deployment. This is not a preference — it is a constraint that is treated as load-bearing.

The reasoning is compounding in nature. When Leashline was built as the second product after Forge, the scaffold took a single session rather than three because every structural decision had already been made and tested: how the database client is initialized, how Clerk middleware is wired, how the App Router layout is structured, what a deployment looks like from a monorepo. None of that was re-derived. The third app was faster still, because a template had been extracted from the second.

The constraint is this: every time a new tool is introduced, it introduces not just a new capability but a new failure mode, a new documentation burden, and a new surface for bugs to appear at deploy time. Stack consistency eliminates entire classes of problems that would otherwise need to be diagnosed, debugged, and added to the rules. The constraint is not about limiting expression — it is about making each successive build cheaper in time and cognitive overhead.

“Same stack = faster second product. Because Leashline uses the exact same stack as Forge, the scaffold took one session. No new tools to learn, no new deployment patterns, no new auth flows. ForgeKit compounding in practice.”

The Specific Choices and Why They Were Made

Next.js 16 App Router — Server components by default meant no data-fetching boilerplate in most pages. Route-level loading states, streaming, and layout nesting came for free. The App Router also co-locates API routes with the pages that use them, which kept the project structure flat and legible across multiple apps in a monorepo.

Drizzle ORM over Prisma— Drizzle's SQL-like query API is close enough to the database mental model that generated queries are predictable and debuggable. Prisma's generated client added complexity at the schema/migration boundary that was not worth its abstractions at this scale. Drizzle also performs better in serverless environments where connection pooling is constrained.

Neon Postgres— Serverless-compatible, branch-per-environment, and fast to provision. A new app's database can be created, schema-pushed, and seeded in under five minutes.

Clerk for auth — Handling authentication from scratch in a multi-tenant app is a session-destroying detour. Clerk covers login, organization management, session tokens, and middleware in a single integration. The rule is absolute: every database query that touches org data must filter by orgId pulled from auth().orgId. Never from a URL param. Never from a request body.

Rail vs. Rounds: When a Single Observation Becomes a Taxonomy

During the architecture session for Leashline, a single question produced the most durable structural insight in the entire ForgeKit build: does the operator go to the client, or does the client come to the operator?

The answer splits every possible business type into two categories with fundamentally different UX shapes, data models, and interaction patterns.

Rail appsare pipeline-shaped. Contacts enter the system, deals move through stages, the operator works from a fixed location — a desk, a van, an office. The primary metaphor is a board: things move from left to right. The operator's body is stationary. The business comes to them. Forge is a Rail app: contractors receive calls, receive leads, send estimates, follow up. The pipeline is the product.

Rounds appsare route-shaped. The operator moves through a sequence of locations or tasks. The primary metaphor is a list that advances through time: things get done in order, then the day ends. The operator's body is in motion. They go to the business. Leashline is a Rounds app: the pet sitter has a route of addresses, visits happen in sequence, the app reflects that forward motion. ForgeHome is also a Rounds app: the household manager has a route of tasks and errands, the day has a shape, and the app externalizes that shape so it can be shared and tracked.

“Name the engine. Then every new vertical is just a config.”

Why This Rule Is Architectural, Not Cosmetic

The Rail/Rounds distinction is not a naming convention. It determines the shape of the data model, the primary screen, the navigation pattern, the interaction primitives, and the automation philosophy.

A Rail app's primary screen is a Kanban board or a contacts list. A Rounds app's primary screen is Today's Route — a temporally ordered sequence of actions that need to happen before the day ends. These require different components, different state machines, and different ideas about what “done” means.

The rule also resolves ambiguous cases without debate. A mobile veterinarian who drives to clients is Rounds. A stationary vet clinic where pet owners come in is Rail. A house cleaner who drives a route is Rounds. A cleaning company with a walk-in office managing teams is Rail. The operator's direction of travel is the deciding variable — not the industry, not the product category, not the price point.

Once this was named, the Armory — ForgeKit's product catalog — split into two parallel tracks: Rail configs for service businesses and Rounds configs for field operators. A new vertical is a config file added to one of these tracks. The six capabilities of a Rail app do not apply to a Rounds app and vice versa. The split is permanent.

Extract When Two Apps Use It. Not Before.

After Forge was built, the code lived in its own repository. After Leashline was started, the first structural choice was whether to keep it separate or pull everything into a monorepo. The answer was a monorepo — but with a constraint: nothing moves into shared packages until at least two apps need it.

This rule prevents premature abstraction. The temptation when building a second app on the same stack is to immediately generalize everything into shared utilities. The problem is that generalization requires knowing the shape of the second and third use cases — and you don't know them yet. The first use case teaches you how something needs to work. The second use case teaches you what varies. Only then do you know where the abstraction boundary belongs.

Three packages emerged organically from this process:

The Turbopack Boundary Problem

One significant technical constraint surfaced during monorepo work: Next.js 16's Turbopack cannot statically analyze configuration that is re-exported through a package boundary. This manifested specifically with the proxy.tsmiddleware config — the file that defines Clerk's route matcher pattern. Attempts to define the matcher in forgekit-coreand re-export it into each app's proxy.ts failed with build errors.

The fix is a hard rule: the matcher config must be inlined directly in each app's proxy.ts. The pattern is repeated, not shared. This is one of the cases where the DRY principle conflicts with a framework constraint, and the framework wins. The rule is encoded and applied to every new app at scaffold time.

leashline's .git — A Deliberate Deferral

When Leashline was folded into the monorepo, it still had its own .git directory from when it was a standalone repository. npm workspaces silently skips nested git repos when linking. Rather than spending a session on a git migration that could go wrong in several ways, the decision was made to leave it and migrate in a dedicated session. The .gitignore at the monorepo root was updated to exclude embedded repos. The technical debt is documented, not ignored.

This is a pattern that recurs: when something is non-trivial to fix correctly and the cost of deferring it is low, defer it with documentation. The decision is explicit — not an oversight.

Rules Are Made From Failures, Not Foresight

The most reliable rules in the ForgeKit build playbook are the ones that cost something before they were written. The following are the highest-signal technical rules from the build sessions, with their origin.

Design Is Not Decoration — It's Constraint

The AI/Human Interface Question

Every ForgeKit app that communicates with end customers on behalf of an operator forces a single architectural decision before any code is written: does this user's value come from the relationship, or from the outcome?

This is not a UX preference. It determines the shape of the entire communication layer.

For a contractor with forty open estimates, automated SMS is a feature, not a shortcut. The operator cannot review every message. The clients don't expect a personal touch on an estimate reminder. Auto-send is the correct default. The system fires the follow-up on day 3, 7, and 14 without operator involvement. The value the contractor delivers is expertise and reliability — the text message is administrative.

For a pet sitter, the personal warmth is the product. Clients are paying not just for a walk but for someone they trust with an animal they love. An automated post-visit text — even a well-crafted one — would damage the relationship. The correct design is: the AI drafts the message (pulling pet name, service type, and any care notes from the visit record), but the operator reads it, adds a photo from the visit, writes a personal line, and sends it from their own number. The AI did the forgettable work. The human delivered the thing the client actually values.

This decision manifests differently in code. The contractor app uses a server-side Twilio call on a schedule trigger. The pet sitter app uses an sms:deep link that opens the operator's native Messages app with the draft populated. The underlying pattern — construct message, surface to operator, send — is the same. The integration point is different, and deliberately so.

“AI prepared it. Katie delivered it. That's the whole principle.”

The SMS Deep-Link Pattern

The Leashline SMS implementation deserves specific attention because it solves a class of problems that arise when apps need to send messages on behalf of operators who have existing relationships with their clients.

Server-side SMS via Twilio requires: a Twilio account, phone number registration, A2P 10DLC brand registration with carriers (2–4 week approval window), per-message carrier fees on top of Twilio fees, and ongoing compliance overhead. For a solo pet sitter sending five post-visit updates per day, this is entirely the wrong solution.

The SMS deep-link pattern bypasses all of this. When the operator taps “Text Sarah” after completing a visit, the app constructs a URL in the format sms:+15551234567?body=Hi+Sarah...and opens it. The operator's native Messages app opens with the number and draft pre-populated. The operator edits, adds media if they want, and sends from their real number. Zero Twilio cost. Zero carrier registration. No compliance overhead. The message comes from a real person's real number, which is exactly what the relationship requires.

The draft is not static. It pulls dynamically from the visit record: pet name, service type, any special care notes from the session. The operator sees a useful draft, not a template. The cognitive cost of sending the update drops from a minute of writing to a few seconds of review.

Inline Action Panels and One-Handed UX

The Leashline UX architecture produced a pattern that is now a first-class ForgeKit primitive: the inline action panel.

The constraint was physical. A pet sitter uses this app one-handed, with a dog on a leash. Navigation between screens, modal dialogs requiring two-handed interaction, and action buttons placed in headers all fail under these conditions. The UX had to work with a thumb, at the bottom third of a phone screen, in motion.

The inline action panel solves this: when an operator needs to act on a visit card — mark it done, log an issue, indicate they're running late — the card expands in place to show the action content. A two-button confirmation (confirm / cancel) appears within thumb reach. No navigation change. No context loss. The route remains visible behind the expanded card.

The finish panel, specifically, includes an editable SMS draft, a soft note toggle for internal records, and a skip-text option for visits where the owner is present. The issue workflow includes seven quick-select chips for issue categorization (came off leash, medication refused, gate locked, etc.) plus a free-text field, followed by log-only or log-and-text-owner actions. All of this is accessible without leaving the Today's Route screen.

The pattern generalizes to any mobile route-based app where the operator's hands and attention are partially occupied: field service, delivery, home health, inspections.

Translucent Full-Bleed Card Backgrounds

The ForgeKit website introduced a visual pattern that is now applied across all product cards: a full-bleed background image at 7% opacity with an absolute-positioned dark overlay on top, with content at z-index above both. This gives cards a sense of texture and context without competing with text legibility.

The implementation is: Image fill with opacity-[0.07], an absoluteinset-0 gradient overlay at 60% opacity, and content in a relative z-10 container. The numbers were arrived at empirically — 7% image opacity is the threshold where the texture is perceptible but the content is still primary. Below 5% the effect disappears. Above 10% it competes with body text.

The Mobile Hero Problem

The website's hero sections required roughly 90 minutes of debugging time concentrated in a single session — an unusually high cost for what appeared to be a simple CSS positioning issue. The root cause analysis is worth documenting in full because the failure mode recurs.

The symptoms: adjusting objectPosition values on hero images had no visible effect. The craftsman in the homepage hero was invisible on mobile regardless of how the position was tuned.

The actual cause: there were three stacked div layers over the image, and two of them had no mobile breakpoint guards. A solid bg-[#0D1117] div that was meant to appear only on desktop (to split the hero into a left text panel and right image panel) had no md: prefix — so it painted over the entire image on mobile. A gradient inside the image container was doing the same. The objectPosition values we were adjusting were correct all along. They were irrelevant because the image was fully covered.

The rule this produced: before adjusting any value on a hero image, list every absolute-positioned div in the component and verify its mobile behavior. Any div without a responsive guard applies to all breakpoints. Check the overlays first, not the image properties.

The Compression Session

One session in the ForgeKit build shipped zero features. It built two scripts, compressed three major documentation files, created an index for the entire Armory catalog, and named a core principle. The output was invisible to any user. The effect on every subsequent session was measurable.

This requires some context. In an AI-assisted build, the AI's context window is a resource that gets consumed by every file read, every prompt, every result. When context is limited, the AI makes worse decisions — it loses track of earlier constraints, misremembers schema fields, repeats work that's already been done. The larger and less structured the context, the more of the window is spent on orientation rather than building.

The compression session addressed this systematically. The build playbook — 15,000 characters of deployment rules and patterns — was prefixed with a 14-row quick-reference table that covers the common case. The reusable patterns doc — 14,000 characters — got a 23-row index at the top. The Armory, 18 files totaling 62,000 characters, was summarized into a 3,000-character JSON index. Individual files are pulled only when working on that specific module or pack.

The Session Compiler

The build log session pages were originally written by hand as HTML — each page required reading a 1,100-line HTML template, understanding its structure, and writing 300+ lines of markup with the session content embedded. The token cost was enormous: read the template, hold its structure in context, write the output.

The session compiler replaced this entirely. Sessions are now written as 50–80 line JSON files following a fixed schema (stats, timeline, built, spins, insights, patterns, rules, quote, nextItems). A Node script reads the JSON and generates the full HTML page. The schema is the format contract — the AI never needs to read an existing session page again to write a new one.

The generator also auto-prepends the new session card to the build log page's sessions array, so the index stays current without a separate edit step.

The efficiency gain was not just in token count but in the quality of session documentation. When writing a retro is cheap and structured, it gets written. When it is expensive and unstructured, it gets deferred or abbreviated. The compiler made doing the right thing the easy thing.

Generated Code and the tsc --noEmit Rule

The trends generator (which reads all session JSON files and emits a TSX page) produced nine TypeScript errors on its first run — all in generated code. The IDE had no visibility into the generated file because it wasn't tracked during development. The errors only appeared at build time.

The root cause was an empty array declaration: const spinCategories = [] was inferred as undefined[] by TypeScript because there were no initial elements and no type annotation. The fix is mechanical: always write const spinCategories: SpinCategory[] = [].

More importantly, this failure produced the rule: run npx tsc --noEmit before every deploy. Generated code is a blind spot for the IDE. TypeScript errors in generated files are invisible until something runs the compiler explicitly. This is now a mandatory pre-deploy step in the playbook.

Modules, Packs, and the Configuration Layer

As the number of ForgeKit products grew, a catalog problem emerged: how do you go from “a contractor needs follow-up automation” to a deployed, configured, working product without rebuilding the logic from scratch each time? The Armory is the answer.

The Armory is a two-layer catalog. The first layer is modules: atomic capabilities that each do one thing. Missed Call Follow-Up. Estimate Reminder Sequence. Jobs Pipeline. Review Request. Lead Intake. Photo AI Caption. Document Q&A. Session Recap. Each module has a fixed schema: buyer, pain, outcome, objections, vertical fit, demo story, pricing. You cannot write a module card without knowing who buys it and why.

The second layer is packs: named configurations of modules for a specific vertical. The Contractor Pack is Lead Intake + Missed Call Follow-Up + Estimate Reminder + Jobs Pipeline + Review Request. Each module already exists. The pack is a named combination of them. A new vertical is a new pack — not new code, not new logic, just a new configuration of existing capabilities with vertical-specific copy, pricing, and demo story.

Why the Schema Is a Quality Gate

Writing every module through the fixed schema revealed gaps in the product story that were not visible before the exercise. Several modules had outcomes that were too vague (“helps with follow-up” instead of “recovers 20–40% of non-responsive leads within 14 days”). Several had objections that hadn't been thought through. The schema forces specificity. A module card that can't answer all the schema fields is not ready to be sold.

The Armory also produced a strategic decision: ShowUp. The pain-mapping exercise that produced the Salon & Spa pack card revealed that the appointment confirmation + no-show recovery flow was a standalone product, not a Forge module. The reasoning: Forge requires a contacts database, an organization, a pipeline, Clerk auth, and a full onboarding flow. A salon owner who just wants to stop losing $200 on no-shows doesn't need any of that. They need a phone number, an appointment time, and a text message. ShowUp was designed as the minimum product that solves exactly that problem — not a lighter version of Forge, but a different product entirely.

ShowUp was ultimately parked when market analysis revealed that appointment reminder tools are a saturated category dominated by Square, GlossGenius, and Fresha — all of which bundle reminders as a feature in broader platforms. The decision to park rather than kill it is deliberate: the Armory analysis that produced ShowUp is still valid, the pain is still real, and the right distribution path may emerge. Parked means revisit; it doesn't mean wrong.

Compounding as Architecture

The ForgeKit build method is not a workflow — it is a feedback loop with compounding properties. The distinction matters because a workflow is followed and then discarded. A compounding loop is followed and then it improves the next iteration of itself.

The loop has six steps:

The Retro Is Not Step 5 — It Is the Loop Itself

An important reframe happened during the compression session. The retro had been positioned as the fifth step of a five-step process — something done after the real work was finished. This framing was wrong in a way that mattered.

A step done after the real work is optional. It can be deferred, abbreviated, or skipped under time pressure. When a retro is optional, it doesn't happen consistently. When it doesn't happen consistently, the compounding stops. Each session becomes independent — it produces an app but does not make the engine smarter.

The correct framing: the retro is the loop itself. A session without compression is half a session. The build is how we test ideas. The retro is how we encode what we learned. Both are the work. Neither is maintenance.

This was encoded in the core principle: Every session makes the engine smarter. Build something. Compress what you learned. The next session starts ahead of where this one did.

Recognizing the Pattern, Building the Skill

Mid-session during the ForgeHome launch, the same three-file sequence appeared for the third time: update the navigation to add a new product, add a card to the homepage, build the product page. The first time, it was work. The second time, it was familiar. The third time, it was a pattern.

Instead of executing the pattern again, the session stopped and built it as a Claude Code/add-product skill. The skill asks a structured set of questions (product name, slug, engine type, tagline, hero images, story) and executes all three file changes. Future products launch through the skill rather than through manual execution of the same sequence.

The rule: when you do something twice, name it. When you do it a third time, build it as a skill. The moment of recognition — “this is the same thing again” — is the moment to stop and codify. Executing the pattern again manually means the cost of learning it the hard way buys nothing.

What Actually Limits a Build Now

Traditional software development is bottlenecked by engineering capacity. Can we build it? How many sprints? How much does it cost? These are real constraints that shape every product decision: what gets built, in what order, to what quality level, on what timeline.

With AI as the build engine, those constraints do not disappear — they shrink dramatically. A full-stack application with authentication, a relational database, multi-tenant data isolation, SMS automation, and a deployed production domain is a one-session effort. The engineering questions are still answered, but they are answered in the course of building, not as prerequisites to it.

The binding constraint moves upstream: can you imagine it clearly enough?

This is not a motivational statement. It is an observation about where decisions get made and what determines their quality. In a traditional engineering team, the product manager writes requirements and the engineers implement them. Ambiguity in the requirements is resolved during implementation — sometimes productively (the engineer finds a better solution) and sometimes wastefully (the engineer builds the wrong thing and has to rebuild it).

In an AI-assisted build, ambiguity in the description produces ambiguity in the output. The AI will build something — it will not refuse to proceed because the specification is incomplete — but what it builds will reflect the vagueness of the input. A precisely described problem (one user, one fear, one physical action, one edge case) produces targeted, coherent software. A vaguely described problem produces software that is technically functional but misses what matters.

The highest-leverage skill in this model is not writing code. It is thinking clearly about problems: naming the user specifically enough that their constraints shape the design, describing the interaction at the level of a physical action, identifying the edge cases before they become spins, and making the product decision (Rail vs. Rounds, auto-send vs. draft-and-send) before the build begins rather than during it.

“The constraint didn't disappear. It moved. It's no longer 'can I engineer this?' It's 'can I imagine it clearly enough?' That question is more interesting. And the answer, it turns out, is learnable.”

What This Changes

If engineering capacity is no longer the bottleneck, the traditional reasons to defer a product idea — it would take too long, it costs too much, we don't have the engineers — no longer apply. The question shifts from “can we afford to build this?” to “is this the right thing to build?”

This changes the economics of early-stage software significantly. A local business that would never have been able to afford a custom software tool — the cost of a traditional development engagement runs $50,000 to $500,000 before the first user — can now have one built to their specific workflow in two weeks at a fixed price. The price point reflects the actual cost structure, not the historical cost structure.

It also changes what a software company looks like. ForgeKit is not an engineering team with a product manager. It is a product architect with an AI engine. The skills that matter are domain knowledge (understanding the contractor's workflow well enough to know that the 14-day follow-up is the one that matters), communication (describing the product specifically enough that the build goes in the right direction), and judgment (knowing when a product idea is in a saturated market and should be parked, knowing when the right answer is a lighter product rather than another module). Engineering is the execution layer, not the constraint.