ForgeKit

ForgeKit is an installable Codex toolkit that turns Codex into a production-safe SaaS builder.

Codex is the AI brain. ForgeKit is the deterministic local toolbelt: scaffold, configure, verify, test, secure, and prepare SaaS apps using standard providers while keeping code ownership with the developer.

ForgeKit is not a hosted no-code app builder, chatbot, proprietary app host, or prompt wrapper. It creates real code in a real repo and uses explicit checks before dangerous actions.

v0.4 Scope

• Framework-aware app scaffolding for Next.js, Astro, Vite React, and SvelteKit
• Forge project state under .forge/
• Spec-first docs
• Blueprint-backed vertical app factory for local business sites, agency portals, and subscription SaaS products
• Capability-aware provider adapters for GitHub, Vercel, Cloudflare, Supabase, Stripe, Resend, Sentry, and OpenTool
• Deterministic env, security, readiness, and changeset commands
• Real provider status checks where official APIs are available
• GitHub repo creation/push, Vercel and Cloudflare preview deploy paths, Supabase project linking/status, and Stripe account/product/price checks
• Operation receipts under .forge/operations/
• Policy gates under .forge/policy.json
• Deterministic plan/task workflow with .forge/tasks.json
• Blueprint-aware plan/task workflows with concrete file targets, modules, checks, and acceptance criteria
• Context, setup, fix-guide, preview, DB safety, and template quality commands
• MCP server at forge-mcp
• Codex skill at skills/forge-saas-builder/SKILL.md

Install

npm install
npm run build
npm link
forge doctor

Without npm link, run the CLI through npm:

npm run forge -- doctor

Quick Start

forge doctor
forge blueprint list
forge create demo --blueprint agency-portal
cd demo
forge spec init
forge spec validate
forge providers list
forge providers status --json
forge context
forge plan "Build a client portal with Stripe payments" --blueprint agency-portal
forge task next
forge env check
forge security scan
forge readiness score
forge changeset --goal "Initial app scaffold"

Provider commands do not fake success. If credentials are unavailable or a live adapter is not implemented, ForgeKit reports configured/unconfigured/connected status and explains what happened.

CLI Commands

forge init <project-name> --template <template> --framework <nextjs|astro|vite-react|sveltekit>
forge create <project-name> --blueprint <blueprint> --framework <framework>
forge doctor
forge blueprint list
forge blueprint show <name>
forge blueprint test <name>
forge providers list
forge providers connect <provider>
forge providers status
forge providers status --json
forge providers login <provider>
forge setup
forge context
forge plan "<app idea>" --blueprint <blueprint>
forge task list
forge task next
forge task show <id>
forge task done <id>
forge task status
forge spec init
forge spec validate
forge add <feature>
forge env check
forge env sync --target preview --yes
forge fix --issue <id>
forge fix --list
forge db inspect
forge db migration check
forge security scan
forge readiness score
forge changeset
forge test
forge watch --security-only
forge github create-repo --name <repo> --public --yes
forge vercel link --project <project> --yes
forge cloudflare status
forge cloudflare pages link --project <project> --yes
forge cloudflare dns list --zone <zone>
forge cloudflare cache purge --zone <zone> --yes
forge supabase link --project-ref <ref> --yes
forge supabase status
forge stripe status
forge stripe products
forge stripe prices --product <id>
forge stripe webhook-verify
forge preview create --yes
forge preview validate <url>
forge deploy preview --provider vercel --yes
forge deploy preview --provider cloudflare --yes
forge deploy production --provider cloudflare --confirm
forge operations list
forge operations show <id>
forge rollback list
forge rollback --id <operation-id> --yes
forge issues sync --yes
forge issues pull
forge policy show
forge policy init
forge policy check --provider vercel --action deploy-preview --risk high
forge template test saas-starter
forge template test --all

High-risk provider actions require --yes. Critical actions, including production deployment, remain blocked unless explicit approval and readiness gates are satisfied.

Templates

• templates/nextjs/saas-starter
• templates/nextjs/client-portal
• templates/nextjs/admin-dashboard
• templates/astro/local-business-site
• templates/vite-react/admin-dashboard

Flat template names are still accepted for backward compatibility where a matching framework template exists.

Blueprints

• local-business-site: Astro-preferred pages, lead forms, Resend notifications, SEO metadata, and optional Cloudflare Pages preview.
• agency-portal: Next.js-preferred client login, project dashboard, invoices/payments, messages, admin, and email.
• subscription-saas: Next.js-preferred onboarding, teams, billing, account settings, admin, and lifecycle emails.

MCP Server

npm run build
FORGE_PROJECT_ROOT=/path/to/app npm run mcp

See MCP server for Claude Code configuration and the full tool list.

Feature Scaffolds

forge add auth
forge add billing
forge add email
forge add admin
forge add file-upload
forge add teams
forge add audit-log
forge add lead-form
forge add messaging
forge add seo
forge add onboarding
forge add client-projects
forge add invoices

Each scaffold updates .forge/project.json, adds feature docs, adds env requirements when needed, and creates a test checklist.

How Codex Should Use ForgeKit

1. Start with forge doctor.
2. For new apps, choose a blueprint with forge blueprint list, then run forge create <name> --blueprint <blueprint>.
3. Run forge setup or forge providers status --json.
4. Run forge context.
5. Use forge spec validate; if specs/tasks are missing, run forge plan "<app idea>" --blueprint <blueprint>.
6. Run forge task next and implement one task at a time.
7. After meaningful changes, run forge security scan and forge readiness score.
8. Generate forge changeset before the final response.
9. Never claim a provider is connected unless forge providers status --json verifies it.
10. Never claim preview deployment unless ForgeKit returns a real URL.
11. Never deploy production without explicit user approval.

Example Codex Prompt

Use ForgeKit to build a client portal SaaS.
Start with forge doctor, choose the agency-portal blueprint, create the app, create the spec docs, then implement auth and billing.
Work through forge context and forge task next.
Do not deploy production. After implementation, run forge security scan, forge readiness score, and forge changeset.

Docs

• Architecture
• Provider adapters
• MCP server
• OpenTool integration
• Security model
• Roadmap
• Prompt library: prompts/