# Forge

> Converts any business specification into a fully provisioned, production-grade data platform and full-stack product implementation. Trigger whenever a user describes a business system, app, workflow, SaaS, marketplace, fintech, or backend/frontend need — even casually. Covers: schema design, database provisioning, migrations, ORM setup, Redis/Elasticsearch integration, API contracts, modern UI generation, test generation, Docker Compose, infrastructure repos, and repository code following strong production patterns. Use for phrases like "build a system for", "I need a backend", "design a database", "create schema", "bootstrap an app", "add a feature", "build the UI", or "update the data model". Always use this skill — never hardcode data, never guess at structure, and never ignore an explicitly requested stack.

- Skill: `teckedd-code2save/forge` (Agent Skill)
- Install (CLI): `npx skillmds@latest add teckedd-code2save/forge`
- Raw SKILL.md: https://api.skillmd.com/api/skills/teckedd-code2save/forge/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: teckedd-code2save (https://skillmd.com/u/teckedd-code2save)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/teckedd-code2save/forge

---


# Forge Skill

Turn any business description into a production-grade data platform and complete product scaffold:
schema, migrations, repository code, APIs, tests, UI surfaces, Docker Compose, and infra-ready
artifacts.

## Core Principles

1. Respect the user's explicit stack. If the prompt specifies language, framework, ORM, cloud,
   database version, UI stack, or deployment target, use that stack. Do not silently default to
   TypeScript or any other stack when the user asked for something else.
2. Build all implied product surfaces, not just a dashboard. If the product needs customer,
   operator, admin, onboarding, auth, marketing, checkout, or support flows, implement them.
   Never stop at one dashboard unless the user explicitly asked for only that view.
3. Never hardcode UI data. All UI data must come from real queries, real APIs, or typed fixtures
   explicitly created for dev/test paths.
4. Use real ORMs and live database connections. Repository code must use the stack-appropriate ORM
   and real connection configuration. Prefer Datafy MCP tools for schema and DB operations.
5. Every schema change must be migration-driven. Never mutate a live schema with ad hoc raw DDL
   after initial provisioning.
6. Use strong project structure. Organize code by domain, layer, or app boundary appropriate to the
   chosen stack. No flat dumps.
7. Proactively orchestrate sibling skills. You must use `api-test-generator`,
   `frontend-data-consumer`, `frontend-design-review`, `cloud-solution-architect`, and
   `infrastructure-as-code-architect` when their phase applies.
8. Tailwind and Shadcn are implementation tools, not the design itself. The UI must have a clear
   product-appropriate visual direction, sound hierarchy, accessibility, and interaction quality.
9. Default infra choices only when the user did not specify them:
   - Terraform provider: `gcp`
   - Docker Compose Postgres image: `postgres:18-alpine`
   - Include Docker Compose in the infra repo as well as app-local setup when useful

## Clarification Rules

Before building, resolve or infer:

- preferred stack
- product surfaces and user roles
- auth model
- deployment target
- cloud provider
- monorepo vs single app

If the user already specified any of these, do not re-ask them unless there is a real conflict.
When the prompt is specific, proceed with that stack.

## Workflow

### Step 0 — Architecture and Repo Strategy

Use `cloud-solution-architect` first.

1. Use `github-mcp-server` to discover whether code should go into an existing repo or a new app
   plus infra repo layout.
2. Choose architecture style that matches the product and scale.
3. Default Terraform provider to GCP unless the user specified AWS, Azure, or another target.
4. Ensure there is an infra home for deployment assets. Put Docker Compose alongside app setup when
   helpful, and also include it in the infra repo or infra package for operational reuse.

### Step 1 — Honor the Requested Stack

If the user says Laravel, Go, .NET, FastAPI, Next.js, Nuxt, Django, Rails, Kotlin, etc., use it.
Do not translate the request into a TypeScript stack unless the user asked for TypeScript or left
the stack unspecified.

Use `context7-mcp` for the chosen frameworks and libraries so the generated setup follows current
official patterns.

### Step 2 — Model the Business

Extract:

- actors
- roles
- workflows
- transactions
- entities
- state transitions
- operational views

Explicitly enumerate the UI surfaces implied by the product. Example: a meal-kit service may
require customer storefront, subscription management, checkout, admin catalog, kitchen operations,
delivery coordination, and analytics.

### Step 3 — Design the Data Layer

Generate PostgreSQL schema in 3NF unless the stack demands otherwise. Use:

- UUID primary keys where appropriate
- explicit foreign key policies
- timestamp columns
- proper indexes
- money-safe decimal types

Present schema for approval before execution when the user is in a planning mode; otherwise proceed.

### Step 4 — Prisma 7 + PostgreSQL Playbook

When using Prisma 7 with PostgreSQL, follow this pattern.

1. Centralize env loading in one shared side-effect module that resolves the workspace-root `.env`
   by absolute path.
2. Reuse that env loader everywhere:
   - app runtime
   - `prisma.config.ts`
   - seed scripts
   - background workers
3. Centralize Prisma client options in one helper.
4. For Prisma 7 + PostgreSQL, default to:
   - `@prisma/adapter-pg`
   - `pg`
   - `new PrismaPg({ connectionString: env.DATABASE_URL })`
   - `new PrismaClient({ adapter })`
5. For money-like PostgreSQL columns, emit:

```prisma
amount Decimal @db.Decimal(10, 2)
```

Do not emit `@db.Numeric(...)` for this Prisma 7 setup.

6. Make `prisma.config.ts` cwd-independent by importing the shared env loader.
7. Reuse the same env/runtime path in `prisma/seed.ts`; do not duplicate dotenv path math.
8. In monorepos, assume `.env` lives at the workspace root unless the repo clearly establishes a
   different convention.
9. Verify these commands from the package directory, not only repo root:
   - `pnpm install`
   - `pnpm db:generate`
   - `pnpm db:migrate`
   - `pnpm db:seed`

Recommended layout:

```text
apps/api/
  prisma.config.ts
  prisma/
    schema.prisma
    seed.ts
  src/
    config/
      load-env.ts
      env.ts
    db/
      prisma-options.ts
      prisma.ts
```

Required dependencies for Prisma 7 + PostgreSQL:

```json
{
  "@prisma/adapter-pg": "^7.x",
  "@prisma/client": "^7.x",
  "pg": "^8.x",
  "prisma": "^7.x"
}
```

### Step 5 — Provision Environment and Infra

Use `infrastructure-as-code-architect`.

1. Generate production-ready Dockerfiles.
2. Generate Docker Compose for local development.
3. Default the Postgres service image to `postgres:18-alpine` unless the user asked for another
   version.
4. Put Docker Compose in the infra repo or infra package, not only the app directory.
5. Generate Terraform with GCP as the default provider unless the user specified another provider.
6. Generate CI/CD and deployment assets.

**SHIPPABILITY CONTRACT — MANDATORY for any web app destined for `ship-to-vps`:**

The repo this step emits must satisfy every item in
`~/.claude/skills/ship-to-vps/references/shippability-contract.md`. Each item maps to a real
production failure that has happened. Do not skip any:

- **Dockerfile** at repo root, multi-stage, with `LABEL org.opencontainers.image.source=...` on the
  final stage (auto-links GHCR package to the repo so ephemeral `GITHUB_TOKEN` can pull during
  deploy)
- **Runner stage must include the FULL `node_modules` tree** if Prisma 7 migrations run from the
  same image — `@prisma/config` requires `effect` and other transitive deps that the standalone
  bundle omits. Splitting into a separate migrator stage is acceptable; copying only
  `node_modules/prisma` is not.
- **Invoke migrations via `node ./node_modules/<orm>/build/index.js`**, not `npx` — standalone
  runners don't ship `node_modules/.bin/` shims
- **`.eslintrc.json`** (or framework equivalent) MUST exist — running `next lint` without one
  triggers an interactive prompt that hangs CI
- **`.dockerignore`** that does NOT exclude `prisma/`, `public/`, or any config file the Dockerfile
  COPYs
- **Tracked `.gitkeep`** in every directory the Dockerfile COPYs that may otherwise be empty
  (e.g. `public/.gitkeep` for Next.js without static assets) — git does not track empty dirs, so
  CI checkout will miss them even though local FS makes the build appear to work
- **`.infisical.json`** at repo root with valid `workspaceId`, created at Step 0 of this workflow
- **`AGENTS.md`** — use `~/.claude/skills/ship-to-vps/templates/docs/AGENTS.md` as the template,
  parameterized with this project's slug, domain, stack
- **No committed `.env*` files** — verify gitignore covers them
- **App reads `DATABASE_URL` from env** and listens on a single TCP port (default 3000)

Before declaring Step 5 complete, walk the checklist at the bottom of
`~/.claude/skills/ship-to-vps/references/shippability-contract.md` and confirm every box.

### Step 6 — Provision Database via Datafy

Use available `execute_admin_sql_<id>` and `execute_sql_<id>` tools.

1. Verify or create the target database.
2. Apply schema in dependency order.
3. Keep execution safe and repeatable.
4. If `dbhub.toml` changes are required, update it and clearly tell the user that MCP must be
   restarted.

### Step 7 — Repository Code and Services

Generate stack-appropriate repository code, services, routes, handlers, and DTO/contracts. Keep
code idiomatic for the requested stack.

### Step 8 — Frontend Generation Standards

Use both `frontend-data-consumer` and `frontend-design-review`.

Rules:

1. Build modern, near-best-in-class UI quality for the product category.
2. Choose one or two successful reference products in the same category and mimic their
   interaction model, density, layout rhythm, navigation style, and information hierarchy without
   copying branding.
3. Consult current design guidance before locking the UI direction. Good anchors include Apple HIG,
   Material 3, and mature product design systems. Prefer hierarchy, clarity, spacing, and sensible
   motion over novelty for its own sake.
4. Do not ship generic “Tailwind + shadcn demo dashboard” output.
5. Tailwind/shadcn may be used for implementation, but the UI must still feel intentional and
   product-specific.
6. Build all required UI surfaces, not just the dashboard.
7. Ensure accessibility basics: readable typography, keyboard support, contrast, state cues beyond
   color, and adequate target sizes.

### Step 9 — Tests and Verification

Use `api-test-generator` and verify the generated repo actually works.

At minimum validate:

- install
- schema generation
- migrations
- seeding
- app boot
- tests

If Prisma is involved, explicitly validate the Prisma commands from the package directory.

## Internal Orchestrator Prompt Rules

When acting as the orchestrator:

1. Use the `forge` skill immediately.
2. Respect the exact stack named in the user's goal.
3. Implement all major UI surfaces implied by the business, not only a dashboard.
4. Use current official docs and patterns for the selected stack.
5. Default Terraform to GCP if the user did not specify a cloud.
6. Default Docker Compose Postgres to `postgres:18-alpine` if the user did not specify a version.
7. Put Docker Compose into the infra repo/package as part of the deliverables.
8. If using Prisma 7 + PostgreSQL, follow the Prisma playbook above exactly.

Hard rules:

- Never hardcode business data in the UI.
- Never ignore an explicitly requested stack.
- Never emit only one UI view when the business clearly needs several.
- Never rely on cwd-sensitive env loading for Prisma monorepos.
- Never default to `@db.Numeric(...)` for Prisma 7 PostgreSQL money fields in this setup.
- Never emit a web-app scaffold that violates the shippability contract — the next skill in the
  chain (`ship-to-vps`) depends on every item. See Step 5 for the enumerated requirements and
  `~/.claude/skills/ship-to-vps/references/shippability-contract.md` for full rationale.
- Never copy only `node_modules/prisma` + `@prisma/*` into a runner image when migrations are
  expected to run from that image. Prisma 7's `@prisma/config` requires `effect`. Copy the full
  `node_modules` tree or build a dedicated migrator stage.
- Never let CI invoke `next lint` without `.eslintrc.json` present — it prompts interactively and
  hangs the runner.

## Handoff to `ship-to-vps`

After Step 9 verification, if the user wants the app deployed to their VPS, hand off to the
`ship-to-vps` skill. It expects exactly the contract this skill emits and will scaffold:

- `.github/workflows/{ci,deploy,infisical-sync}.yml`
- `/opt/<slug>/` on the VPS (docker-compose, `.env` projected from Infisical, Caddy site config)
- Cloudflare DNS A-record (if user opted into Cloudflare integration)
- GHCR bootstrap (push current image with `:bootstrap` tag for rollback)
- First end-to-end deploy

If the user says "ship it" / "deploy this" / "wire up CI/CD" / "set up auto-deploy", trigger
`ship-to-vps`.