Fork Build Deploy

The top-level skill for the actual purpose of this repo: fork the template, build the app, deploy the app. Use this first when the user wants to create or ship a new product from Seed — it coordinates the lower-level skills.

Default stance

Keep the workflow simple. Use high-level instructions first. Add scripts only where failure is expensive or easy to miss. Product-building decisions are agentic — the model and the user shape them in conversation. Hard-fail only the few paths that can silently break hosted environments (db push, missing env, stale CLI artifact during smoke).

This repo is not the idea engine and not the GTM engine. It exists to help agents fork, build, and deploy. Anything outside that loop usually lives elsewhere.

Use this skill when

Forking Seed for a new product, deciding the sequence between data model/API/MCP/CLI/skills/docs work, picking which lower-level skill to invoke, or coordinating a full build → deploy cycle.

Skill web

This skill decides the sequence. Drop into the lower-level skills when you're working that layer:

setup-product — product identity, fork shaping, initial bootstrap orientation
run-quality-gates — local validation before push or promotion
db-health — migration discipline, Neon branch safety, preview branch DB workflow
promote-deployment — preview/staging/production release flow, env parity, deploy smoke
add-api-endpoint — when the product needs new public API surface
webhooks-and-events / sandboxed-tasks — when the product needs reactive or agent-execution surfaces
release-cli / release-sdk — when forks need their own CLI/SDK shipped
organization-best-practices / better-auth-best-practices — multi-tenant or auth changes

Canonical workflow

For the short root-level operator version, read WORKFLOW.md first. The steps below explain the same sequence with skill routing.

Fork or branch from Seed.
Bootstrap product identity — lib/brand.ts, env, initial config.
Build the product contract — schema strategy → product-specific data model → OpenAPI/REST → MCP tools → CLI verbs → installable product skills. See references/factory-release-standard.md.
Use the product rails for mechanical surfaces when the product can be expressed as product/<slug>/product.json, schema.json, openapi.yaml, and skills/*/SKILL.md: bun run product:generate, then bun run product:check.
Generate and commit migrations locally — never db:push.
Run quality gates locally — ./scripts/gates.sh.
Push the branch.
Wait for the Vercel preview deployment to exist before debugging anything branch-specific.
Validate the live preview URL first — that's the strongest signal short of staging.
If direct DB access is still needed: vercel env pull to discover branch wiring, then neonctl for the access path.
Provision live rails — bun run product:provision wires GitHub, Vercel, Neon, Vercel env, Porkbun/Vercel domain, Svix, and Stripe from .env.seed.
Deploy and smoke — bun run product:deploy, then bun run product:smoke, then bun run product:ship-report.
Verify the release surface — /skills install page, /docs generated from public product skills, llms.txt, CLI binary name, MCP tools, Svix smoke, billing smoke when applicable, and Union Street design compliance.
Promote through staging and then main via ./scripts/promote.sh.
Run deploy smoke against hosted environments before calling the app shipped.

Hard rules

bun run db:push is banned. No exceptions for hosted preview, staging, or main.
Never apply hosted migrations manually. Let the Vercel build step do it via DATABASE_URL_UNPOOLED.
Live preview validation > local-only DB validation. The hosted environment is the truth.
Treat env parity failures, deploy smoke failures, and stale CLI artifact failures as hard blockers.
A launch product must satisfy the factory release standard before it is called shipped: schema strategy, product data model, OpenAPI/REST, MCP, CLI, skills, docs, llms.txt, headless smoke, and design checks all need a real product-specific pass.
If the product allows user or agent schema customization, flexible schema discovery and mutation must be exposed through REST/OpenAPI, MCP, CLI, skills, and docs. Anonymous JSONB blobs without definitions are not enough.
Product rails are preferred for repetitive plumbing. The agent should edit the product contract, run product:generate, run product:check, and only hand-edit generated surfaces for gaps the rails cannot express.
Headless products stay headless. Do not add GUI surfaces unless the user explicitly requires them; docs and install flows are still required.
Product docs must not expose Seed factory internals, factory instructions, or repo playbooks.

Hidden trap: the Neon staging-as-default quirk

We set staging as Neon's default branch so previews fork from staging data. This means the Neon-Vercel integration tries to set Production DATABASE_URL to the staging endpoint. Production DATABASE_URL must be set manually, and the integration's Production toggle disabled, or the integration will overwrite it on its next sync. See db-health and CLAUDE.md.

Repo identity

This repo helps agents:

fork the template
build the product
deploy the product

The factory thesis is volume — many forks per month. Optimize for the loop, not for any one product.

Where things live

File	Purpose
`lib/brand.ts`	Product identity (name, CLI name, URL fragments)
`fork-manifest.json`	Product contract, including schema strategy and release surface
`product/<slug>/`	Agent-authored rail input: product metadata, schema contract, OpenAPI, and skills
`scripts/product-rails.mjs`	Contract-driven generator/checker for repeatable product plumbing
`scripts/product-live.mjs`	Live provision/deploy/smoke rail for Vercel, Neon, Porkbun, Svix, Stripe, and GitHub
`scripts/promote.sh`	Stage promotion
`scripts/gates.sh`	Quality gates
`scripts/factory-check.sh`	Fork readiness inspection
`scripts/factory-cold-start-dry-run.sh`	Simulates a fresh fork from cold start
`CLAUDE.md`	Project instructions, env matrix, Neon quirks
`docs/release-flow.md`	Full delivery checklist
`UnionStreetAI/skills/<product>/skills/*`	Public product skills that drive install/docs surfaces
`/skills`	Product skill installation page
`/docs`	Product documentation derived from public skills
`llms.txt`	LLM-facing product surface index

Auxiliary content

references/original-guide.md — full canonical guide with skill-web routing and repo identity statement
references/graph.md — explicit handoff boundaries to lower-level skills
references/factory-release-standard.md — required launch surface for product forks
scripts/inspect-fork-readiness.sh — checks a fork against the readiness contract; run before first deploy of a new product
assets/fork-manifest.schema.json — JSON Schema for the fork manifest declarative config
assets/example-fork-manifest.json — concrete example for a new product
assets/fork-readiness-checklist.md — human-review checklist before declaring a fork ready
assets/evals/basic.json — eval cases for skill regression