ship-create 1.0.0 → 1.2.0

package/README.md

@@ -1,39 +1,61 @@
-# SHIP CLI
+# ship-create
 
-A zero-dependency, zero-API-key project scaffolder for The SHIP Method OS. Built for non-developers — there's nothing to `npm install` and nothing to sign up for before your first command works.
+A zero-dependency, zero-API-key project scaffolder for The SHIP Method OS. Published on npm as [`ship-create`](https://www.npmjs.com/package/ship-create) — no git clone, no API key, nothing to sign up for before your first command works.
 
 ## Run It
 
-From the repo root:
+From anywhere — an empty folder, your desktop, wherever you want the new project to land:
 
 ```
-node ship-cli/create.mjs
+npx ship-create
 ```
 
-That's it. No `npm install` needed for the CLI itself (it only uses Node.js built-ins). You do need [Node.js](https://nodejs.org) installed (18 or newer) — if `node -v` works in your terminal, you're ready.
+That's it. No global install needed. You do need [Node.js](https://nodejs.org) installed (18 or newer) — if `node -v` works in your terminal, you're ready.
+
+> Prefer a permanent global command? `npm install -g ship-create`, then just run `ship-create`.
 
 ## What It Asks
 
 1. **Project name** — e.g. "Acme CRM"
-2. **What you're building** — pick from the 8 product types in [`../06-TEMPLATES/`](../06-TEMPLATES)
+2. **What you're building** — one of 8 product types (SaaS, CRM, membership, lead-gen, directory, dashboard, internal tool, marketplace)
 3. **Which AI tool you mainly use** — ChatGPT, Claude, Gemini, Cursor, or Windsurf
 
 ## What It Creates
 
-A new folder at `projects/<your-project-slug>/` containing:
+A new folder at `./<your-project-slug>/`, in whatever directory you ran the command from, containing:
 
-- The full [`starter-kit/`](../starter-kit) app shell (sale page, member area, backoffice — working Next.js code on mock data)
+- The full starter-kit app shell (sale page, member area, backoffice — working Next.js + Tailwind code on mock data)
 - `AGENTS.md`, `CLAUDE.md`, `.cursorrules`, `.windsurfrules` — copied in, so Cursor/Windsurf/Claude Code enforce the SHIP order automatically the moment you open the folder
 - `docs/PROJECT.md` — pre-filled with your project name and product type
 - `docs/<TYPE>_TEMPLATE.md` — the starter pack matching what you're building
 - `docs/HUMAN_FLOW.md` — blank template, ready for Stage 2
+- `docs/PROMPTS.md` — the full Idea → Code prompt chain
 - `docs/FIRST_PROMPT.txt` — a ready-to-paste prompt for whichever AI tool you picked, with `PROJECT.md` already loaded into it
 - `NEXT_STEPS.md` — plain-language instructions for what to do next, tailored to your AI tool choice
 
+Everything it needs is bundled inside this package's own `templates/` folder — nothing is read from the SHIP Method OS repo at runtime, so it works standalone via `npx` for anyone, without access to that (private) repo.
+
 ## Why No API Key
 
 If you already pay for ChatGPT Plus, Claude Pro, or Gemini Advanced, requiring a *separate* API key (different billing, different signup, different rate limits) to use this CLI would be pure friction. Instead, the CLI prepares the exact prompt you need and tells you where to paste it — into the tool you already have open in a browser tab.
 
 ## Re-running
 
-The CLI refuses to overwrite an existing `projects/<slug>/` folder — pick a different project name, or delete the old folder first if you want to start over.
+The CLI refuses to overwrite an existing `./<slug>/` folder in your current directory — pick a different project name, or delete the old folder first if you want to start over.
+
+## Maintaining This Package
+
+This folder lives inside the private `the-ship-method-os` repo but publishes as a separate public package. If the source templates change (`starter-kit/`, `01-STRUCTURE/PROJECT.md`, `02-HUMAN-FLOW/HUMAN_FLOW.md`, `03-INSTRUCTION/PROMPTS.md`, `06-TEMPLATES/*.md`, or the root agent rule files), re-sync them into `templates/` and bump the version before publishing:
+
+```
+# from the repo root
+cp -R starter-kit ship-cli/templates/starter-kit
+rm -rf ship-cli/templates/starter-kit/{node_modules,.next,package-lock.json,next-env.d.ts,tsconfig.tsbuildinfo}
+cp 01-STRUCTURE/PROJECT.md 02-HUMAN-FLOW/HUMAN_FLOW.md 03-INSTRUCTION/PROMPTS.md ship-cli/templates/docs/
+cp 06-TEMPLATES/*.md ship-cli/templates/docs/product-types/
+cp AGENTS.md CLAUDE.md .cursorrules .windsurfrules ship-cli/templates/
+
+cd ship-cli
+npm version patch   # or minor/major
+npm publish --access public
+```

package/create.mjs

@@ -186,6 +186,14 @@ async function main() {
     }
   }
 
+  // 2b. Copy the Claude Code skill (.claude/skills/ship-method/SKILL.md) so
+  // Claude Code can explicitly invoke the SHIP workflow as a skill, not
+  // just follow it as a passive rules file.
+  const claudeSkillSrc = path.join(TEMPLATES_DIR, ".claude");
+  if (fs.existsSync(claudeSkillSrc)) {
+    copyRecursiveExcluding(claudeSkillSrc, path.join(outDir, ".claude"), new Set());
+  }
+
   // 3. Create a docs/ folder with a pre-filled PROJECT.md and the matching product-type template.
   const docsDir = path.join(outDir, "docs");
   fs.mkdirSync(docsDir, { recursive: true });
@@ -281,6 +289,11 @@ This folder includes AGENTS.md / CLAUDE.md / .cursorrules / .windsurfrules.
 If you open this folder in Cursor, Windsurf, or Claude Code, those tools
 will automatically enforce filling Structure and Human Flow before
 generating feature code — you don't need to do anything extra.
+
+If you use Claude Code specifically, there's also a \`.claude/skills/ship-method/SKILL.md\`
+— Claude can invoke it directly as a skill (not just a passive rule file)
+whenever you ask it to build a feature or review whether something is
+ready to ship.
 `;
 
   fs.writeFileSync(path.join(outDir, "NEXT_STEPS.md"), nextSteps);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ship-create",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Scaffold a new project the SHIP Method way — Structure, Human Flow, Instruction, Publish. No git clone, no API key, just one command.",
   "type": "module",
   "license": "MIT",

package/templates/.claude/commands/ship.md

@@ -0,0 +1,46 @@
+---
+description: Drive this project through the SHIP Method — Structure, Human Flow, Instruction, Publish.
+argument-hint: "[status | structure | human-flow | instruction | publish]"
+---
+
+You are driving this project through **The SHIP Method** via the `/ship` shortcut. FIRST invoke the `ship-method` skill — it owns the gate definitions, the "never invent business facts" rule, and the Theme & First Screen procedure. This command is a thin orchestrator on top of it; do not duplicate or contradict the skill.
+
+Argument passed: "$ARGUMENTS"
+
+## Step 1 — Locate the docs
+
+Determine where this project's SHIP docs live and use whichever set exists:
+- `ship-create`-generated project: `docs/PROJECT.md`, `docs/HUMAN_FLOW.md`, `docs/AI_BUILD_SPEC.md`.
+- The SHIP Method OS repo itself: `01-STRUCTURE/PROJECT.md`, `02-HUMAN-FLOW/HUMAN_FLOW.md`, `03-INSTRUCTION/AI_BUILD_SPEC.md`.
+
+## Step 2 — Detect the current phase
+
+Walk the gates in order and find the FIRST one not yet satisfied. A gate is unsatisfied if its file is missing OR its core sections still contain `[bracket placeholders]` or unedited template / "Worked Mini-Example" content instead of this project's real content.
+
+1. **S — Structure** — `PROJECT.md` core sections filled: Vision, Problem Statement, Target Audience, MVP Scope.
+2. **H — Human Flow** — `HUMAN_FLOW.md` core sections filled: Core Screens, Happy Path, and at least one error/empty state.
+3. **I — Instruction** — `AI_BUILD_SPEC.md` exists with functional requirements, data model, and API contract.
+4. **P — Publish** — Theme & First Screen done, feature code built from the spec, and the pre-launch checklist walked.
+
+## Step 3 — Handle the argument
+
+- `status` → report each gate as pass/fail with one line on what's missing, then STOP (do not drive).
+- `structure`/`s`, `human-flow`/`h`, `instruction`/`i`, `publish`/`p` → jump to that phase regardless of detection (used to revisit an earlier phase).
+- empty or anything else → resume at the first incomplete gate from Step 2.
+
+## Step 4 — Drive the phase
+
+Announce the phase and what is missing, e.g. "You're at **S — Structure**. `PROJECT.md` has N unfilled sections — let's fill them."
+
+Then, **one question at a time** (pull questions from the relevant section headers):
+- Ask → wait for the answer → **draft the real content into the doc** for that section.
+- Never invent business facts (market size, pricing, metrics, quotes). If the user doesn't know, write a clearly-labeled placeholder like `[TBD: ...]` and move on.
+- When the phase's required sections are filled, summarize what was written, confirm with the user, then advance to the next phase by re-running this flow.
+
+For **P — Publish**, follow the `ship-method` skill's Theme & First Screen step (use `theme-guide.md`): derive 2-3 themes from `PROJECT.md`, let the user pick one, apply it, build the real homepage from `HUMAN_FLOW.md`, then build the remaining feature code from the spec, then walk `QA_CHECKLIST.md` / `LAUNCH_CHECKLIST.md`.
+
+## Rules
+
+- Ask exactly one question per message.
+- Do not generate feature/business-logic code until Gates 1-3 pass (scaffolding/config is fine anytime).
+- `/ship` keeps no saved state — it re-detects the phase every run, so it always resumes correctly.

package/templates/.claude/skills/ship-method/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: ship-method
+description: Use when starting any new product, feature, or "build me an app" request — before writing any application code. Walks through Structure, Human Flow, Instruction, Publish in order, using this repo's templates. Also use when asked to review whether a project is "ready to build" or "ready to ship."
+---
+
+# The SHIP Method
+
+You are operating inside a project built with **The SHIP Method OS**. The method has four phases, run strictly in order:
+
+```
+S — STRUCTURE   →   H — HUMAN FLOW   →   I — INSTRUCTION   →   P — PUBLISH
+(what & why)         (the experience)     (AI-ready specs)      (ship it)
+```
+
+The single most common reason AI-built products end up broken, scope-creeped, or unshippable: someone skips Structure and Human Flow and goes straight to "build me an app." This skill exists to stop that.
+
+## When to Use This Skill
+
+- The user describes a new product/feature idea and wants something built
+- The user asks you to generate code for a feature that doesn't have a filled spec yet
+- The user asks "is this ready to build?" or "is this ready to ship?"
+- You're about to scaffold, design a schema, or write business logic and no `PROJECT.md` / `HUMAN_FLOW.md` exists yet for it
+- The user runs the `/ship` shortcut — drive them through the gates below one phase at a time, drafting their answers into the docs
+
+## The Checklist
+
+Work through these gates in order. Do not let scope, urgency, or the user saying "just build it fast" skip a gate without at least naming what's being skipped.
+
+- [ ] **Gate 1 — Structure exists.** Find or create `PROJECT.md` (template: `01-STRUCTURE/PROJECT.md` in this repo, or `docs/PROJECT.md` if this is a `ship-create`-generated project). Vision, Problem Statement, Target Audience, and MVP Scope must be filled — not placeholder brackets.
+- [ ] **Gate 2 — Human Flow exists.** Find or create `HUMAN_FLOW.md`. Every core screen needs a happy path and at least one error/empty state defined before it gets built.
+- [ ] **Gate 3 — Instruction exists.** Functional requirements, data model, and API contract are written somewhere concrete (`AI_BUILD_SPEC.md` / `docs/PROJECT.md`'s feature section) before you generate feature code.
+- [ ] **Gate 4 — Theme & First Screen.** Once Gates 1-3 pass and before final polish/ship: derive 2-3 business-appropriate themes from `PROJECT.md`, let the user pick one, apply it (`app/globals.css`, `app/layout.tsx`), and record it in the design system; then read `HUMAN_FLOW.md` and replace the starter's generic `app/page.tsx` ("Pick your area") with the real entry point. See `theme-guide.md` in this skill folder.
+- [ ] **Gate 5 — Publish readiness.** Before telling the user something is "done," check it against the relevant checklist (`QA_CHECKLIST.md`, `LAUNCH_CHECKLIST.md`) rather than declaring success from a clean build alone.
+
+## How to Apply This
+
+1. **If Gate 1 or 2 is missing or full of `[bracket placeholders]`:** stop, don't generate feature code. Instead, ask the user one specific question at a time to fill the gap — pull questions directly from the relevant template's section headers. Scaffolding, config, and boilerplate are fine to write anytime; business logic and feature code are gated.
+2. **If the user insists on skipping a gate** ("just build it, skip the docs"): comply, but say once, briefly, what's being skipped and the most likely thing that breaks later as a result. Don't refuse repeatedly or lecture.
+3. **If all gates are filled:** proceed normally — generate code straight from the spec, and flag if a code request contradicts what's already written in `PROJECT.md` or `HUMAN_FLOW.md` rather than silently overriding it.
+4. **When asked "is this ready to build/ship?":** walk the checklist above explicitly and report which gates pass/fail, rather than giving a vague yes/no.
+
+## Theme & First Screen (Gate 4)
+
+Run this once Gates 1-3 pass, before final polish or shipping. The agent already
+knows the business from `PROJECT.md`, so it can theme and build the front door
+accurately.
+
+1. **Derive & choose a theme.** From `PROJECT.md`, produce 2-3 candidate themes
+   (palette as HSL token values + a font pairing). Present them and let the user
+   pick — never pick silently, never require brand assets the user didn't give.
+2. **Apply it.** Write the chosen tokens into `app/globals.css` (`:root` and
+   `.dark`), set fonts in `app/layout.tsx`, and record the choice in
+   `12-DESIGN-SYSTEM/DESIGN_SYSTEM.md` (or `docs/DESIGN_SYSTEM.md`).
+3. **Build the first screen.** Read `HUMAN_FLOW.md`, decide the real entry point
+   for this business, and replace the starter's `app/page.tsx` ("Pick your
+   area") with it — landing/sale for marketing-led products, app home/dashboard
+   redirect for tools. Adjust each area's main page to match.
+
+Full procedure and the business-type → palette/font table: `theme-guide.md` in
+this skill folder. (In this OS repo the app lives under `starter-kit/`.)
+
+## Reference Files (when present in this repo)
+
+| Need | File |
+|---|---|
+| Business goals, scope, MVP | `01-STRUCTURE/PROJECT.md`, `01-STRUCTURE/MVP_SCOPE.md` |
+| User journeys, screens | `02-HUMAN-FLOW/HUMAN_FLOW.md`, `02-HUMAN-FLOW/SCREEN_PLANNING.md` |
+| Specs, prompt chain | `03-INSTRUCTION/AI_BUILD_SPEC.md`, `03-INSTRUCTION/PROMPTS.md` |
+| Pre-launch checks | `04-PUBLISH/QA_CHECKLIST.md`, `04-PUBLISH/LAUNCH_CHECKLIST.md` |
+| Product-type starter pack | `06-TEMPLATES/<TYPE>_TEMPLATE.md` |
+| Design consistency | `12-DESIGN-SYSTEM/DESIGN_SYSTEM.md` |
+| Business-type → palette/font theme guide | `theme-guide.md` (this skill folder) |
+| Stack decisions | `13-TECH-STACK/STACK_DECISION_MATRIX.md` |
+
+If this is a project generated by `ship-create`, the same files exist under `docs/` instead of the numbered folders above.

package/templates/.claude/skills/ship-method/theme-guide.md

@@ -0,0 +1,72 @@
+# Theme & First Screen — Reference Guide
+
+Used by the SHIP Method's **Theme & First Screen** step (first step of the
+PUBLISH phase). It tells you how to turn the business described in `PROJECT.md`
+into (a) 2-3 theme candidates the user can choose from, and (b) a real homepage.
+
+## Where things live
+
+In a `ship-create`-generated project the Next.js app is at the repo root:
+- `app/globals.css` — theme tokens (HSL triplets) under `:root` and `.dark`
+- `app/layout.tsx` — fonts via `next/font/google`, mapped to `--font-*` variables
+- `app/page.tsx` — the root page (ships as a generic "Pick your area" screen)
+
+In **this OS repo**, the same app lives under `starter-kit/` (e.g.
+`starter-kit/app/globals.css`). Adjust paths accordingly.
+
+Record the chosen theme in the design system doc:
+`12-DESIGN-SYSTEM/DESIGN_SYSTEM.md` (or `docs/DESIGN_SYSTEM.md` in generated
+projects).
+
+## Step 1 — Derive 2-3 theme candidates
+
+Read `PROJECT.md` (vision, business type, target audience, any stated brand
+colors). Map the business to a palette direction and a font pairing using the
+table below as a starting point — then tailor, don't copy blindly.
+
+| Business / mood | Palette direction | Font pairing (display / sans) |
+|---|---|---|
+| Finance, B2B, trust | Cool navy/slate base, restrained single accent | Serif or grotesk display / neutral sans |
+| Legal, premium, luxury | Deep neutral (ink/charcoal), gold or burgundy accent | Classic serif / humanist sans |
+| Kids, play, consumer fun | Bright, high-saturation, multiple accents | Rounded geometric sans / rounded sans |
+| Health, wellness, calm | Soft greens/teals, low saturation | Humanist serif / soft sans |
+| Tech, SaaS, developer | Dark base, one electric accent | Geometric sans / mono accents |
+| Food, hospitality, warm | Warm earth tones, appetizing accent | Editorial serif / friendly sans |
+| Creative, agency, bold | High-contrast, expressive accent | Display serif or bold grotesk / clean sans |
+
+Each candidate MUST specify, as HSL triplets, values for every token in
+`globals.css`: `--background --foreground --card --card-foreground --primary
+--primary-foreground --secondary --secondary-foreground --accent
+--accent-foreground --muted --muted-foreground --destructive
+--destructive-foreground --success --success-foreground --border --input --ring`
+plus a `--radius`, and a font pairing for `--font-display`, `--font-sans`,
+`--font-mono`.
+
+Present the candidates to the user (a one-line mood + the key colors each).
+Let the user pick one. Do NOT pick silently. Do NOT require brand assets — use
+them only if `PROJECT.md` provides them.
+
+## Step 2 — Apply the chosen theme
+
+1. In `app/globals.css`, set the token values under BOTH `:root` and `.dark`
+   (this kit keeps them identical). Keep the HSL-triplet format (e.g.
+   `--primary: 14 92% 58%;`) so `hsl(var(--x))` keeps working.
+2. In `app/layout.tsx`, swap the `next/font/google` imports to the chosen
+   fonts, keeping the variable names `--font-display`, `--font-sans`,
+   `--font-mono`. The starter uses `Fraunces` (display), `Work_Sans` (sans),
+   `JetBrains_Mono` (mono) as the reference pattern.
+3. Record the final palette + fonts in the design system doc as the source of
+   truth for later UI work.
+
+## Step 3 — Build the real first screen
+
+Read `HUMAN_FLOW.md` and decide the true entry point for THIS business:
+- Marketing-led (course, membership, leadgen) → root `app/page.tsx` becomes the
+  landing/sale page.
+- Tool/dashboard/internal → root becomes the app home, or redirects to the
+  primary dashboard route.
+
+Replace the generic "Pick your area" content in `app/page.tsx` with real content
+drawn from the spec (no lorem). Adjust the main page of each area's route to
+match. Then remind the user to update `FEATURE_MATRIX.md` and `QA_CHECKLIST.md`
+if scope changed.

package/templates/.cursorrules

@@ -39,6 +39,11 @@ Full reference docs live in: `01-STRUCTURE/`, `02-HUMAN-FLOW/`, `03-INSTRUCTION/
 
 6. **Never invent business facts** (market size, pricing, real metrics, real user quotes) into these docs. Draft clearly-labeled placeholders or ask the user instead.
 
+7. **Once the spec is complete, run the "Theme & First Screen" step before polishing or shipping.** When `01-STRUCTURE/PROJECT.md`, `02-HUMAN-FLOW/HUMAN_FLOW.md`, and `03-INSTRUCTION/AI_BUILD_SPEC.md` are filled (no `[bracket placeholders]`), and before calling anything ship-ready:
+   - **Theme:** Derive 2-3 theme candidates (color palette as HSL token values + a font pairing) from the business in `PROJECT.md`, present them, let the user pick one, then apply it to the app's `app/globals.css` and `app/layout.tsx` and record the choice in `12-DESIGN-SYSTEM/DESIGN_SYSTEM.md`.
+   - **Home:** Read `02-HUMAN-FLOW/HUMAN_FLOW.md`, determine the real entry point for this business, and replace the starter kit's generic `app/page.tsx` ("Pick your area") with it.
+   - Don't pick a theme silently and don't require brand assets the user didn't provide. See the `ship-method` skill's `theme-guide.md` for the business-type → palette/font reference. (In `ship-create` projects these docs live under `docs/`; in this OS repo the app lives under `starter-kit/`.)
+
 ## Quick Orientation for a New Agent Session
 
 If you (the AI agent) are opening this repo for the first time in a session:

package/templates/.windsurfrules

@@ -39,6 +39,11 @@ Full reference docs live in: `01-STRUCTURE/`, `02-HUMAN-FLOW/`, `03-INSTRUCTION/
 
 6. **Never invent business facts** (market size, pricing, real metrics, real user quotes) into these docs. Draft clearly-labeled placeholders or ask the user instead.
 
+7. **Once the spec is complete, run the "Theme & First Screen" step before polishing or shipping.** When `01-STRUCTURE/PROJECT.md`, `02-HUMAN-FLOW/HUMAN_FLOW.md`, and `03-INSTRUCTION/AI_BUILD_SPEC.md` are filled (no `[bracket placeholders]`), and before calling anything ship-ready:
+   - **Theme:** Derive 2-3 theme candidates (color palette as HSL token values + a font pairing) from the business in `PROJECT.md`, present them, let the user pick one, then apply it to the app's `app/globals.css` and `app/layout.tsx` and record the choice in `12-DESIGN-SYSTEM/DESIGN_SYSTEM.md`.
+   - **Home:** Read `02-HUMAN-FLOW/HUMAN_FLOW.md`, determine the real entry point for this business, and replace the starter kit's generic `app/page.tsx` ("Pick your area") with it.
+   - Don't pick a theme silently and don't require brand assets the user didn't provide. See the `ship-method` skill's `theme-guide.md` for the business-type → palette/font reference. (In `ship-create` projects these docs live under `docs/`; in this OS repo the app lives under `starter-kit/`.)
+
 ## Quick Orientation for a New Agent Session
 
 If you (the AI agent) are opening this repo for the first time in a session:

package/templates/AGENTS.md

@@ -39,6 +39,11 @@ Full reference docs live in: `01-STRUCTURE/`, `02-HUMAN-FLOW/`, `03-INSTRUCTION/
 
 6. **Never invent business facts** (market size, pricing, real metrics, real user quotes) into these docs. Draft clearly-labeled placeholders or ask the user instead.
 
+7. **Once the spec is complete, run the "Theme & First Screen" step before polishing or shipping.** When `01-STRUCTURE/PROJECT.md`, `02-HUMAN-FLOW/HUMAN_FLOW.md`, and `03-INSTRUCTION/AI_BUILD_SPEC.md` are filled (no `[bracket placeholders]`), and before calling anything ship-ready:
+   - **Theme:** Derive 2-3 theme candidates (color palette as HSL token values + a font pairing) from the business in `PROJECT.md`, present them, let the user pick one, then apply it to the app's `app/globals.css` and `app/layout.tsx` and record the choice in `12-DESIGN-SYSTEM/DESIGN_SYSTEM.md`.
+   - **Home:** Read `02-HUMAN-FLOW/HUMAN_FLOW.md`, determine the real entry point for this business, and replace the starter kit's generic `app/page.tsx` ("Pick your area") with it.
+   - Don't pick a theme silently and don't require brand assets the user didn't provide. See the `ship-method` skill's `theme-guide.md` for the business-type → palette/font reference. (In `ship-create` projects these docs live under `docs/`; in this OS repo the app lives under `starter-kit/`.)
+
 ## Quick Orientation for a New Agent Session
 
 If you (the AI agent) are opening this repo for the first time in a session:

package/templates/CLAUDE.md

@@ -39,6 +39,11 @@ Full reference docs live in: `01-STRUCTURE/`, `02-HUMAN-FLOW/`, `03-INSTRUCTION/
 
 6. **Never invent business facts** (market size, pricing, real metrics, real user quotes) into these docs. Draft clearly-labeled placeholders or ask the user instead.
 
+7. **Once the spec is complete, run the "Theme & First Screen" step before polishing or shipping.** When `01-STRUCTURE/PROJECT.md`, `02-HUMAN-FLOW/HUMAN_FLOW.md`, and `03-INSTRUCTION/AI_BUILD_SPEC.md` are filled (no `[bracket placeholders]`), and before calling anything ship-ready:
+   - **Theme:** Derive 2-3 theme candidates (color palette as HSL token values + a font pairing) from the business in `PROJECT.md`, present them, let the user pick one, then apply it to the app's `app/globals.css` and `app/layout.tsx` and record the choice in `12-DESIGN-SYSTEM/DESIGN_SYSTEM.md`.
+   - **Home:** Read `02-HUMAN-FLOW/HUMAN_FLOW.md`, determine the real entry point for this business, and replace the starter kit's generic `app/page.tsx` ("Pick your area") with it.
+   - Don't pick a theme silently and don't require brand assets the user didn't provide. See the `ship-method` skill's `theme-guide.md` for the business-type → palette/font reference. (In `ship-create` projects these docs live under `docs/`; in this OS repo the app lives under `starter-kit/`.)
+
 ## Quick Orientation for a New Agent Session
 
 If you (the AI agent) are opening this repo for the first time in a session: