scaffold-factory

scaffold-factory

Create a ready-to-build KMP or Next.js project in under 2 minutes — with your package name, auth provider, and theme wired in, from a pinned starter tag your AI agent can't rewrite.

Built for developers who live inside agent-native workflows (Claude Code, OpenClaw, Hermes) and who start the same kinds of projects repeatedly. The LLM never generates project structure; it routes a small deterministic script that copies from canonical starter repos and applies find-and-replace.

---

What it does

$ scaffold.py create kmp PlateTracker --dest ./PlateTracker --package-prefix com.rzv --room

60 seconds later you have a working Kotlin Multiplatform app at ./PlateTracker:

• Compose Multiplatform UI across Android / iOS / Desktop
• Package namespace rewritten from com.example.kmp_starter_project → com.rzv.platetracker everywhere (source, manifests, Xcode config, 50+ files)
• Optional packs you asked for are kept (kmp/room_data/ in this run), ones you didn't are deleted along with their settings.gradle.kts include(...) line
• local.properties pointing at your detected Android SDK
• ./gradlew build already passed — the scaffold fails if the project doesn't compile

Note (v0.4.0): the KMP optional packs (kmp/auth, kmp/room_data, kmp/ui_theme) ship as reference modules, not wired dependencies. The generated project includes them but composeApp/shared do not import from them by default. See the starter's AGENTS.md for how to wire them manually. Full cross-target wiring is planned for v0.5.0. The scaffold's "Next steps" output prints the same note explicitly.

Same flow for Next.js 16:

$ scaffold.py create nextjs MyApp --dest ./MyApp \
    --auth-provider clerk \
    --clerk-publishable-key pk_test_... \
    --clerk-secret-key sk_test_...

Generates a minimal .env.local with the provider selection + any keys you passed, then runs pnpm install && pnpm build && pnpm start and curls every route (/, /sign-in, /sign-up, /dashboard) to prove runtime works, not just build. If you skip the keys, the app still boots — the starter's auth providers no-op gracefully and show a "configure " notice on the sign-in page until you fill .env.local.

Same works for Supabase via --supabase-url / --supabase-anon-key.

Why this exists

An LLM asked to "scaffold a KMP project" will re-invent the project structure every time. It burns tokens, produces non-deterministic output, and can't build-verify because it doesn't know what "correct" looks like.

scaffold-factory flips that: the LLM routes, a Python script executes. The starter repos are the single source of truth, pinned by tag. The agent's job is to pick the right flags and confirm with you before running. The output is reproducible across machines and time.

• No LLM in the hot path. Every file operation is deterministic copy + substring replace.
• Pinned sources. v0.1.0 of a starter today is v0.1.0 next year.
• Build-gated by default. A scaffold isn't done until ./gradlew build or pnpm build passes.
• Self-describing starters. Each starter declares its own placeholders and packs via .scaffold.json — swap in your own starter without touching scaffold-factory.
• Portable. Install as a Claude Code plugin (/plugin install scaffold-factory) with automatic updates; or clone into any skills directory as a fallback.

Who this is for

• Agent-native developers (Claude Code, OpenClaw, Hermes) who want deterministic scaffolding instead of asking an LLM to type boilerplate
• Teams with opinionated internal starters who want every new app to start from the same base
• Solo devs who start several projects a week and are tired of create-next-app → 20 minutes of cleanup → wire auth → set up the theme tokens → fix the placeholder app name

If you start one Next.js app a year, create-next-app is fine. If you start five, this saves you an afternoon per project.

Install

Recommended — Claude Code plugin

Run these from your shell (or use the /plugin ... equivalents inside a Claude Code session — same commands, different entry point):

claude plugin marketplace add mahdirzv/scaffold-factory
claude plugin install scaffold-factory

Verify:

claude plugin list | grep scaffold-factory
# → scaffold-factory@mahdirzv  Version: 0.4.0

Updating