ship-create 1.1.0 → 1.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ship-create",
-  "version": "1.1.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

@@ -20,6 +20,7 @@ The single most common reason AI-built products end up broken, scope-creeped, or
 - 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
 
@@ -28,7 +29,8 @@ Work through these gates in order. Do not let scope, urgency, or the user saying
 - [ ] **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 — 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.
+- [ ] **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
 
@@ -37,6 +39,26 @@ Work through these gates in order. Do not let scope, urgency, or the user saying
 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 |
@@ -47,6 +69,7 @@ Work through these gates in order. Do not let scope, urgency, or the user saying
 | 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: