| name | from-scratch |
| description | Use when starting a new project from scratch. Establishes contracts, design system, and architecture skeleton before any feature code. Enforces phase gates to prevent incoherence and bugs. |
| allowed-tools | Read, Grep, Glob, Bash, Edit, Write |
| when_to_use | Use when user says "new project", "start from scratch", "build X from zero", or when no existing codebase is present. |
| argument-hint | [project name] [archetype] [tech stack] |
| context | fork |
| agent | senior-engineer |
from-scratch
Three laws: (1) contracts before components — define routes/types/APIs first, (2) tokens before components — write globals.css CSS vars first, (3) phase gates — lint + tsc must pass before advancing. See agent_docs/from-scratch-guide.md for templates, framework init commands, and the self-review checklist.
- Seed the project
CLAUDE.md from the kit's matching stack preset (presets/<category>/<stack>/CLAUDE.md under KIT ROOT; multiple stacks → concatenate their compact.mds per presets/README.md; no matching preset → generic/fallback).
- Write
PROJECT-CONTRACTS.md (routes, types, API endpoints, shared components, nav items). Determine archetype: SaaS | Marketing | DevTool | Ecommerce | Mobile | API | Internal | Creative, then select stack per archetype.
- Collect the brief, then pick the design direction with the user (
agent_docs/design-directions.md — brief intake first, then three far-apart options in one question; bespoke when none of the eight fits). Write DESIGN-SPEC.md (axes as real numbers + brief constraints + the one signature moment) + globals.css from those values. Gate 1: lint + tsc = 0 errors.
- Write
types/index.ts from contracts. Build layout shell (AppShell, Sidebar, TopBar, PageHeader, EmptyState, SkeletonCard). Gate 2: lint + tsc + build = 0 errors.
- Build first feature page — all 4 states: loading skeleton + populated + empty + error. Gate 3: lint + tsc + build = 0 errors.
- Self-review: design tokens, the spec's spacing scale, component completeness, structural coherence — then run
/design-check for the rest (direction actually visible, tells, monotony, signature).
Output
PROJECT INITIALIZED: [name] | Archetype: [type] | Stack: [list]
Contracts: ✓ | Design: ✓ | CSS tokens: ✓ | Types: ✓ | Shell: ✓ | First page: ✓
Phase gates: Gate 1: ✓ | Gate 2: ✓ | Gate 3: ✓
Next: /new-page [route] for additional pages.
