init

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.

/init

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.

---

1. Stack Freshness

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.

2. Product Brief

Ask conversationally (3 questions max):

• "What are you building?" → project name + one-sentence description
• "Who is it for?" → target users
• "What domain?" → industry context

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.

3. Design Direction

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.

4. Create the Project

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:

• A hello world heading using the agreed design direction
• One component from the design system (e.g., a Button) styled with the chosen accent color
• That component also has a Storybook story
• The page has one E2E test (Playwright visits the page, verifies the heading and component render)
• The Convex backend is set up (schema, seed script)
• Everything builds, lints, formats, type-checks as one unit

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.

4a. Package Research (sub-agents)

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:

• One sub-agent per core technology area (frontend framework, backend, UI system, toolchain, testing, deployment)
• Each sub-agent: web search + npm view + Context7 to find required peer dependencies, plugins, adapters, and configuration packages
• Each sub-agent reports: package name, version, why it's needed, which core package requires it

Collect results. These packages are added alongside the core stack.yaml packages.

4b. Install CLI Dependencies

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.

4c. Generate the Full Project

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 concurrently
• build — 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 server
• storybook:build — Build Storybook static site

CI 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.

4d. CLAUDE.md

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 descriptions

Do NOT modify the fixed rules (principles, When Stuck, Development Flow).

4e. Skills and Settings

Copy the entire src/.claude/ directory to the generated project's .claude/. This includes:

• settings.json — base permissions for autonomous Claude operation
• skills/preview/SKILL.md — preview environment management
• skills/review/SKILL.md — multi-pass code review
• skills/consistency-check/SKILL.md — full quality gate

Adapt 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:

• preview: Replace {{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.
• review: Update references to match the actual design system, auth patterns, i18n setup, and conventions used in the generated code. Ensure the file-by-file checks reflect the real stack (e.g., correct auth function names, actual UI package paths).
• consistency-check: Verify the 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.

5. Set Up AI Tooling

MCP Servers

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.

Entire.io (Commit Storytelling)

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.

Minter Agent

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.

6. Set Up Credentials

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.

7. Verify

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.

8. First Commit

git add . && git commit -m "First commit"

(Git was already initialized in step 4.)

9. Repository & CI/CD Setup

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 Repository

Create a private repository using the project name from the product brief. Push the initial commit. Then configure the repository:

• Squash merge only — disable merge commits and rebase merges, keep only squash merge. Set the default squash commit title to PR title and the default commit message to first commit message (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)
• Branch protection on main — require status checks to pass before merging

Create Environments

Set up the environments defined in src/stack.yaml (ci.environments): preview and production.

Set Secrets Per Environment

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.

Set Production Backend Environment Variables

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.

Set Up Dependency Automation

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.

10. Verify CI

Verify Main Pipeline

Push to main and watch the pipeline. If it fails, diagnose, fix, push, and retry until it passes (checks + production deploy).

Verify PR Pipeline

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).

Verify Production Deploy

Merge the test PR (squash + delete branch). Pull main. Watch the production pipeline. If it fails, diagnose, fix, push, retry until production deploy succeeds.

Confirm Production

Verify the production URL is accessible — the landing page loads.

Done

Report what was created and how to start building features.