{"id":48959138,"url":"https://github.com/mahdirzv/scaffold-factory","last_synced_at":"2026-04-18T01:01:15.883Z","repository":{"id":351815630,"uuid":"1212622800","full_name":"mahdirzv/scaffold-factory","owner":"mahdirzv","description":"Deterministic project scaffolding for AI agents — create ready-to-build KMP or Next.js apps from pinned GitHub starters in under 2 minutes. Never rewrites project structure with an LLM.","archived":false,"fork":false,"pushed_at":"2026-04-17T12:13:15.000Z","size":232,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-17T12:14:18.237Z","etag":null,"topics":["ai-agents","claude-code","code-generation","kmp","kotlin-multiplatform","nextjs","project-template","scaffolding","starter-template"],"latest_commit_sha":null,"homepage":"https://github.com/mahdirzv/scaffold-factory","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mahdirzv.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-16T15:04:25.000Z","updated_at":"2026-04-17T12:11:06.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/mahdirzv/scaffold-factory","commit_stats":null,"previous_names":["mahdirzv/hermes-skill-scaffold","mahdirzv/scaffold-factory"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/mahdirzv/scaffold-factory","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mahdirzv%2Fscaffold-factory","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mahdirzv%2Fscaffold-factory/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mahdirzv%2Fscaffold-factory/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mahdirzv%2Fscaffold-factory/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mahdirzv","download_url":"https://codeload.github.com/mahdirzv/scaffold-factory/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mahdirzv%2Fscaffold-factory/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31952206,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-18T00:39:45.007Z","status":"ssl_error","status_checked_at":"2026-04-18T00:39:20.671Z","response_time":62,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","claude-code","code-generation","kmp","kotlin-multiplatform","nextjs","project-template","scaffolding","starter-template"],"created_at":"2026-04-18T01:01:09.744Z","updated_at":"2026-04-18T01:01:15.866Z","avatar_url":"https://github.com/mahdirzv.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# scaffold-factory\n\n[![smoke](https://github.com/mahdirzv/scaffold-factory/actions/workflows/smoke.yml/badge.svg)](https://github.com/mahdirzv/scaffold-factory/actions/workflows/smoke.yml)\n[![release](https://img.shields.io/github/v/tag/mahdirzv/scaffold-factory?label=release\u0026color=blue)](https://github.com/mahdirzv/scaffold-factory/releases)\n[![license](https://img.shields.io/github/license/mahdirzv/scaffold-factory)](LICENSE)\n\n**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.**\n\nBuilt 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.\n\n---\n\n## What it does\n\n```bash\n$ scaffold.py create kmp PlateTracker --dest ./PlateTracker --package-prefix com.rzv --room\n```\n\n60 seconds later you have a working Kotlin Multiplatform app at `./PlateTracker`:\n\n- Compose Multiplatform UI across Android / iOS / Desktop\n- Package namespace rewritten from `com.example.kmp_starter_project` → `com.rzv.platetracker` everywhere (source, manifests, Xcode config, 50+ files)\n- 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\n- `local.properties` pointing at your detected Android SDK\n- `./gradlew build` already passed — the scaffold fails if the project doesn't compile\n\n\u003e **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](https://github.com/mahdirzv/kmp-starter-project/blob/main/AGENTS.md#optional-packs--reference-modules-not-wired-dependencies) 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.\n\nSame flow for Next.js 16:\n\n```bash\n$ scaffold.py create nextjs MyApp --dest ./MyApp \\\n    --auth-provider clerk \\\n    --clerk-publishable-key pk_test_... \\\n    --clerk-secret-key sk_test_...\n```\n\nGenerates a minimal `.env.local` with the provider selection + any keys you passed, then runs `pnpm install \u0026\u0026 pnpm build \u0026\u0026 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 \u003cprovider\u003e\" notice on the sign-in page until you fill `.env.local`.\n\nSame works for Supabase via `--supabase-url` / `--supabase-anon-key`.\n\n## Why this exists\n\nAn 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.\n\nscaffold-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.\n\n- **No LLM in the hot path.** Every file operation is deterministic copy + substring replace.\n- **Pinned sources.** `v0.1.0` of a starter today is `v0.1.0` next year.\n- **Build-gated by default.** A scaffold isn't done until `./gradlew build` or `pnpm build` passes.\n- **Self-describing starters.** Each starter declares its own placeholders and packs via `.scaffold.json` — swap in your own starter without touching scaffold-factory.\n- **Portable.** Install as a Claude Code plugin (`/plugin install scaffold-factory`) with automatic updates; or clone into any skills directory as a fallback.\n\n## Who this is for\n\n- **Agent-native developers** (Claude Code, OpenClaw, Hermes) who want deterministic scaffolding instead of asking an LLM to type boilerplate\n- **Teams with opinionated internal starters** who want every new app to start from the same base\n- **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\n\nIf you start one Next.js app a year, `create-next-app` is fine. If you start five, this saves you an afternoon per project.\n\n## Install\n\n### Recommended — Claude Code plugin\n\nRun these from your shell (or use the `/plugin ...` equivalents inside a Claude Code session — same commands, different entry point):\n\n```bash\nclaude plugin marketplace add mahdirzv/scaffold-factory\nclaude plugin install scaffold-factory\n```\n\nVerify:\n\n```bash\nclaude plugin list | grep scaffold-factory\n# → scaffold-factory@mahdirzv  Version: 0.4.0\n```\n\n### Updating\n\nWhen a new release lands (e.g. `v0.5.0`):\n\n```bash\nclaude plugin marketplace update mahdirzv           # refresh the marketplace.json cache\nclaude plugin update scaffold-factory@mahdirzv      # bump the installed plugin\n```\n\n\u003e **Two gotchas worth knowing:**\n\u003e\n\u003e - `claude plugin update scaffold-factory` (unqualified) fails with `Plugin \"scaffold-factory\" not found`. Always pass the fully-qualified name `scaffold-factory@mahdirzv`.\n\u003e - If the marketplace cache is stale, `plugin update` says \"already up to date\" even when a new version is published upstream. Run `claude plugin marketplace update mahdirzv` first.\n\n### Using it\n\nOnce installed, trigger by asking the agent:\n\n\u003e *\"scaffold a KMP project called PlateTracker, package prefix com.rzv, with Room\"*\n\u003e\n\u003e *\"create a Next.js starter named MyApp with Clerk auth\"*\n\nOr use the slash command directly:\n\n```\n/scaffold nextjs MyApp --auth-provider clerk --clerk-publishable-key pk_test_... --clerk-secret-key sk_test_...\n```\n\nThe agent confirms your package prefix, pack selection, destination, and API keys before running (see [`SKILL.md`](SKILL.md) — it's instructed not to silently default).\n\n### Fallback — manual git clone (no auto-updates)\n\n```bash\ngit clone https://github.com/mahdirzv/scaffold-factory ~/.claude/skills/scaffold-factory\n```\n\nUse this only if you can't use Claude Code's plugin system. You'll `git pull` manually to get new releases; `/plugin update` does not apply.\n\n\u003e **Already have a git-clone install?** Remove it before installing the plugin — running both at once creates a duplicate skill and routing may pick the wrong copy:\n\u003e\n\u003e ```bash\n\u003e rm -rf ~/.claude/skills/scaffold-factory\n\u003e claude plugin install scaffold-factory\n\u003e ```\n\n## Requirements\n\n- **Python 3.10+** (modern type syntax; 3.9 and older are rejected at startup with a clear message)\n- **git** on PATH (for lazy-cloning starters)\n- **Per stack:**\n  - KMP → JDK 17+, Android SDK (auto-detected via `ANDROID_HOME` / `ANDROID_SDK_ROOT` or common paths)\n  - Next.js → Node.js 20+ and pnpm (`npm i -g pnpm` or `corepack enable`)\n\nMissing executables are reported with an actionable hint (\"install pnpm with `npm i -g pnpm`\") instead of a Python traceback.\n\n## Commands\n\n```bash\nscaffold.py resolve \u003cstack\u003e \u003cname\u003e [flags]       # print the JSON plan\nscaffold.py create  \u003cstack\u003e \u003cname\u003e --dest PATH   # resolve + apply + verify\nscaffold.py apply   --plan plan.json --dest PATH # apply a saved plan\n```\n\nSee [`references/command-grammar.md`](references/command-grammar.md) for the full flag set and [`references/registry-schema.md`](references/registry-schema.md) for how the registry and `.scaffold.json` manifests work.\n\n## Architecture\n\n| Layer | File | Role |\n|---|---|---|\n| Router | [`SKILL.md`](SKILL.md) | Policy + decision rules (loaded by the agent) |\n| Registry | [`references/registry.json`](references/registry.json) | Pinned starter tags + pack ids |\n| Script | [`scripts/scaffold.py`](scripts/scaffold.py) | Deterministic file operations |\n| Starter (KMP) | [mahdirzv/kmp-starter-project](https://github.com/mahdirzv/kmp-starter-project) | Canonical Compose Multiplatform base + packs |\n| Starter (Next.js) | [mahdirzv/base-next-starter](https://github.com/mahdirzv/base-next-starter) | Canonical Next.js 16 base |\n\nEach starter owns its own `.scaffold.json` declaring its placeholders and packs. The skill is generic; the starter is authoritative. **Bring your own starter** by adding a `.scaffold.json` to your repo and pointing `registry.json` at it — see [`references/design-rationale.md`](references/design-rationale.md).\n\n## Releases\n\nSee [CHANGELOG.md](CHANGELOG.md) for the version history.\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmahdirzv%2Fscaffold-factory","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmahdirzv%2Fscaffold-factory","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmahdirzv%2Fscaffold-factory/lists"}