// Scaffold a production-ready SaaS project. Checks stack freshness, product brief, design, generates a working hello world, and sets up GitHub CI/CD.
Full quality gate: build, lint, format, typecheck, unit tests, Minter integrity, visual verification, and E2E tests. Run after implementing a feature.
Manage isolated Convex preview environments with per-worktree port assignment. MANDATORY before any Playwright, E2E test, or browser testing.
Multi-pass code review covering Minter spec coverage, code quality, design system compliance, test strategy, and architecture. Use before considering a feature done or creating a PR.
| name | init |
| description | Scaffold a production-ready SaaS project. Checks stack freshness, product brief, design, generates a working hello world, and sets up GitHub CI/CD. |
Read src/stack.yaml (tech stack) and src/harness.yaml (AI workflow) first.
Use npm view <pkg> version for package versions. Use gh api repos/{owner}/{repo}/releases/latest --jq '.tag_name' for GitHub Actions versions. Use Context7 for current API patterns. Never use versions from training data.
Before starting, verify Node.js is on the current LTS or newer (node --version vs web search) and pnpm is on its latest version (pnpm --version vs web search). Any version at or above the current LTS is fine. If below LTS, guide the user to update before proceeding.
Launch sub-agents in parallel — one per leaf technology entry in src/stack.yaml (e.g., TanStack Start, React, Convex, Park UI, Vite+, Playwright, etc.).
Each sub-agent does a web search: is this still the best choice? Actively maintained? Any controversies, deprecations, or clearly better alternatives?
Collect all results. Report findings to the user and wait for feedback before proceeding.
Ask conversationally (3 questions max):
The project name should be kebab-case (e.g., task-flow). Confirm explicitly: "The project will be called {name} — this will also be the repository name. Ok?" This is the last human confirmation needed — from here on, the flow is fully autonomous.
Ask what the user has (Figma, PNG, colors, nothing). Check Park UI docs via Context7 for the available preset color palettes — present only palettes that Park UI actually supports. Propose 2-3 directions if needed. Agree on accent color (must be a Park UI preset palette), gray color, border radius, and a short design direction.
Goal: A WORKING project where every technology is correctly wired together — not packages piled on top of each other. Frontend, backend, UI, testing, and deployment work as one synergistic system.
The concrete result: A single public page (no auth required) with:
Create ../{project-name}/ and immediately run git init inside it (needed by later steps).
Use the structure section in src/stack.yaml for the monorepo layout.
The stack.yaml defines core packages. Wiring them together requires additional dependencies (plugins, adapters, type packages, config tools). Every additional package must be validated by research — never add packages from memory.
Launch sub-agents in parallel to research integration requirements:
npm view + Context7 to find required peer dependencies, plugins, adapters, and configuration packagesCollect results. These packages are added alongside the core stack.yaml packages.
Read all entries in src/stack.yaml that have an install field. For each, check if the CLI tool is already installed. If not, run the install command. Run checks in parallel.
This is the core step — generate all code that achieves the goal described in step 4. Every source file, config file, component, test, backend function, seed script, CI workflow, and deployment config. The result must be a working project where the hello world page renders, the design system is wired, the backend responds, the E2E test passes, and the build succeeds.
Use Context7 for current API patterns and npm view for versions. Make sure imports resolve, types align, and the full stack compiles together.
Critical files to get right:
.gitignore — Copy src/.gitignore.template as the base. Then add any additional entries required by technologies discovered during package research (e.g., framework-specific build caches, generated directories). The template covers the known stack; the AI must think about what else needs ignoring based on the actual packages installed.
Workspace configuration — Set up pnpm workspaces with proper aliases (e.g., @{project}/ui, @{project}/shared). Show the pattern by example in the generated code — import from aliases everywhere so future AI sessions follow the same convention.
Seed script — The Convex seed script MUST be at convex/seed.ts exporting a function named seedData. The /preview skill depends on this exact path: npx convex run seed:seedData. The seed script must be idempotent (upsert, not insert).
Package scripts — Ensure these scripts exist in the root package.json. Map each to the corresponding Vite+ command from src/stack.yaml (toolchain.commands):
dev — Start web + Convex dev servers concurrentlybuild — Production build (vp build)lint — Lint all files (vp lint)format — Format all files (vp fmt . --write)format:check — Check formatting without modifying files (vp fmt --check)test — Unit tests (vp test)test:e2e — E2E tests (Playwright against /preview)check — Full quality gate: vp build && vp check && vp test (build, then lint+format+typecheck, then unit tests)storybook — Start Storybook dev serverstorybook:build — Build Storybook static siteCI workflows — Generate GitHub Actions workflows for the outcomes described in src/stack.yaml (ci.outcomes). Also generate .github/dependabot.yml as described in ci.dependabot.
After generating all files, run pnpm install to install dependencies and verify the lockfile is created.
Generate the CLAUDE.md by reading src/CLAUDE.md.template and replacing all placeholders:
{{PROJECT_NAME}} — project name from product brief{{PROJECT_DESCRIPTION}} — one-sentence description from product brief{{PROJECT_USERS}} — target users from product brief{{PROJECT_DOMAIN}} — industry context from product brief{{DESIGN_DIRECTION}} — agreed design direction (accent color, gray, radius, style){{COMMANDS}} — generate the commands list based on the toolchain in src/stack.yaml and the scripts from 4c (include all scripts with short descriptions){{ARCHITECTURE}} — generate from the structure section in src/stack.yaml, with actual workspace names and descriptionsDo NOT modify the fixed rules (principles, When Stuck, Development Flow).
Copy the entire src/.claude/ directory to the generated project's .claude/. This includes:
settings.json — base permissions for autonomous Claude operationskills/preview/SKILL.md — preview environment managementskills/review/SKILL.md — multi-pass code reviewskills/consistency-check/SKILL.md — full quality gateAdapt every skill to the generated project. The copied skills are starting points — they encode the right structure and workflow, but their details must match what was actually generated. Read each skill file carefully and update it:
{{MAIN_REPO_PATH}} with the absolute path of the generated project. Update the environment variables in the "Set Convex Preview Environment Variables" step to match the actual backend env vars the project uses (only set what exists — remove any that don't apply, add any new ones). Verify the seed function path (seed:seedData) matches the generated seed script. Update the dev server command if the project structure differs.pnpm check command matches the root package.json check script. Update any stack-specific checks or commands.The goal: when a developer runs /preview, /consistency-check, or /review in the generated project, every command, path, and convention the skill references must match what the project actually has. Zero mismatches.
Read src/stack.yaml for all MCP server definitions (check sdd.mcp and the mcps section). Add each MCP server from within the generated project directory using claude mcp add.
Read the setup field from src/stack.yaml commits section and run it inside the generated project directory. This auto-configures Git hooks and Claude Code integration.
Create the agents directory and download the spec agent in one command:
mkdir -p .claude/agents && curl -fSo .claude/agents/spec.md <URL_FROM_STACK_YAML>
Read the agent field from src/stack.yaml sdd section for the URL. Use -fSo (fail on HTTP errors) to avoid silently saving error pages.
The project needs credentials before it can be tested or deployed. Read all sections of src/stack.yaml and collect every entry that has a credentials or setup field — this includes backend, deployment, services, and CI.
For each service: if the user doesn't have an account yet, guide them through creating one (signup URL, what plan to choose). Then tell them exactly where to go (using the setup field), what to click, and what to copy. Verify each credential before moving on.
Write .env.local with all local development values (secrets + non-secrets). This is the only env file with actual values — it is gitignored and never committed. CI/platform credentials (e.g., CLI auth tokens) should be verified by running a quick CLI command to confirm access.
Run /consistency-check with a self-healing loop. The consistency-check skill handles the full quality gate — build, lint, format, types, unit tests, Minter, visual check, and E2E. If any step fails, fix and retry until everything passes.
Note: /preview must be running for the E2E and visual check steps. Start it if not already running.
For a fresh project with no Minter specs yet: minter ci may pass vacuously or report no specs. This is expected — specs are written when building features, not during scaffolding.
git add . && git commit -m "First commit"
(Git was already initialized in step 4.)
Use the project name confirmed during the product brief (step 2). Use the CI platform defined in src/stack.yaml (ci section). Use Context7 and the platform CLI's --help to get current commands and API patterns.
Create a private repository using the project name from the product brief. Push the initial commit. Then configure the repository:
gh api PATCH on the repo with allow_squash_merge=true, allow_merge_commit=false, allow_rebase_merge=false, squash_merge_commit_title=PR_TITLE, squash_merge_commit_message=COMMIT_MESSAGES)Set up the environments defined in src/stack.yaml (ci.environments): preview and production.
Derive the required secrets from src/stack.yaml — read the credentials and setup fields in the sections referenced by each environment's credentials-from. Guide the user through each credential: tell them exactly where to go (using the setup field), what to create, and what to copy. Set each secret on the correct environment using the platform CLI.
Important: Preview and production may need separate credentials (e.g., different deploy keys for different backends). Guide the user through creating credentials for each environment separately.
For services that manage their own environment (like Convex), production env vars (auth keys, email config, etc.) must be set directly on the service dashboard — not via GitHub secrets. Read the note field in ci.environments.production for guidance. Walk the user through setting each required variable on the production backend dashboard.
If the CI platform supports automated dependency updates (e.g., Dependabot, Renovate), verify the config file was generated in step 4c (.github/dependabot.yml). If private registries are used, set the required secrets at the repo level.
Push to main and watch the pipeline. If it fails, diagnose, fix, push, and retry until it passes (checks + production deploy).
Create a test branch with a small change (e.g., update the hello world heading text — also update the E2E test to match). Open a pull request. Watch for checks to pass (preview deploy + E2E verification).
Merge the test PR (squash + delete branch). Pull main. Watch the production pipeline. If it fails, diagnose, fix, push, retry until production deploy succeeds.
Verify the production URL is accessible — the landing page loads.
Report what was created and how to start building features.