workflow-ship-faster

Original source / Raw SKILL.md

---
name: workflow-ship-faster
description: "Ship Faster end-to-end workflow for small web apps (default: Next.js 16.1.1): idea/prototype → foundation gate → design-system.md → lightweight guardrails + docs → feature iteration → optional Supabase + Stripe → optional GitHub + Vercel deploy → optional AI-era SEO (sitemap/robots/llms.txt). Resumable, artifact-first under runs/ship-faster/ (or OpenSpec changes/). Trigger: ship/launch/deploy/production-ready MVP."
---

# Workflow: Ship Faster (Next.js 16.1.1)

The goal of this chain is: **Ship an idea or small prototype to production-ready state in the shortest time**, while maintaining iteration speed afterward.

## When to use

Use this workflow when the user wants an end-to-end chain like:
- “ship this MVP”, “make it production-ready”, “launch/deploy this project”
- “take this prototype and turn it into a real app”
- “set up the foundation + UI system + deployment”

## Core principles (non-negotiable)

- **Pass paths only, not content**: agents/sub-agents only pass `..._path`.
- **Files are first-class citizens**: Every step must persist artifacts; failures can be retried; replayable.
- **Confirmation points**: Any "high-risk/high-effort/side-effect" action must write a plan first and wait for confirmation.
- **Plans are checklists**: progress is tracked in `tasks.md` via `- [ ]` → `- [x]` (not in chat).
- **Progressive disclosure**: Only open step files in this skill directory (`foundation.md`, `deploy-vercel.md`, etc.) when needed—avoid loading all details at once.
- **Hooks doctor (required check; non-blocking)**: If running under Claude Code and you want the evolution loop active, run `tool-hooks-doctor` once at the start of the session; if hooks are missing, offer to install project-level hooks (continue either way).

## Inputs / outputs (paths only)

Inputs (paths only):
- `repo_root`: project root (default `"."`)
- Optional: `run_dir` (active run directory) if the user already has one

Outputs (artifacts, written under `run_dir/`):
- Required: `proposal.md`, `tasks.md`, `context.json`
- Optional: `design.md`, `evidence/`, `logs/`

Canonical contract (backends, templates, read order, auto-archive):
- [references/artifact-contract.md](references/artifact-contract.md)
- Reference index: [references/README.md](references/README.md)

## Step modules (open only when you hit that step)

- Foundation: [foundation.md](foundation.md)
- Guardrails: [guardrails.md](guardrails.md)
- Trace cleanup: [cleanup-traces.md](cleanup-traces.md)
- Docs baseline: [docs-baseline.md](docs-baseline.md)
- Supabase integration: [supabase-integration.md](supabase-integration.md)
- Stripe integration: [stripe-integration.md](stripe-integration.md)
- Deploy (GitHub + Vercel): [deploy-vercel.md](deploy-vercel.md)
- AI-era SEO (Next.js): [ai-seo-nextjs.md](ai-seo-nextjs.md)

## Process (Default Route)

### 0) Initialize Run (Required)

1. Resolve/create `run_dir/` (see the deterministic backend rules in [references/artifact-contract.md](references/artifact-contract.md)).
2. Ensure core artifacts exist (create if missing; merge/append if already present):
   - `proposal.md`, `tasks.md`, `context.json`
3. In `tasks.md`, ensure:
   - a `status: active|blocked|done` field near the top
   - a short **Next action** section (1–3 items)
   - an **Approvals** section (empty is fine until needed)
4. Only create `evidence/` and `logs/` when you actually have large outputs to store.

### 0.2) Scope Confirmation (Required)

Problem this solves: a run summary that marks core steps as “skipped” without the user ever choosing to skip them is misleading and hard to audit.

Ask the user to select a scope **before** executing steps beyond build checks:

- **A) full (default)**: Foundation → Design system → UI/UX → Guardrails → Docs → Feature iteration → Deploy
- **B) deploy-only**: Foundation (build + sanity) → Deploy only (no UI work, no guardrails/docs polish)
- **C) design-only**: Design system + UI/UX plan only (no code changes)
- **D) feature-only**: One feature iteration (plan + implementation), skip deploy

Rules:
- Persist the chosen scope to `context.json` (add/update a `scope` field).
- In `tasks.md`, do **not** mark a default step as “skipped” unless the user explicitly requested skipping it.
  - Prefer: `disabled (scope=...)` with a short reason under a “Scope / Disabled steps” section
- Any destructive action (e.g., **force push** overwriting an existing repo) is a high-risk side effect:
  - Write an executable approval item under `tasks.md` first
  - Wait for explicit user confirmation before executing

### 0.25) Kickoff Clarification (Brainstorm-lite) (Recommended; required if goal is vague)

Problem this solves: people jump straight into “implement a feature” and end up with a very basic MVP that’s hard to demo.

Run this step if **any** of these are true:
- `proposal.md` is missing clear **acceptance criteria** and **non-goals**
- The user request is “build something like X” / “make a prototype” without specifying the core loop
- The user explicitly wants a “demo-ready” prototype (animation, wow factor, shareable)

How:
- Call `workflow-brainstorm` using the **same `repo_root` + this `run_dir`**.
- Follow the one-question-at-a-time rule and converge on:
  - the one core loop (1 sentence)
  - acceptance criteria (3–5 bullets)
  - non-goals (1–3 bullets)
  - constraints (timeline / risk preference)
  - a “demo moment” direction (see step 0.3)
- Persist the confirmed spec to:
  - `evidence/YYYY-MM-DD-kickoff-design.md`
- Then update (merge, don’t overwrite) these inputs:
  - `proposal.md`
  - `context.json` (ensure `need_database/need_billing/need_deploy/need_seo` are explicitly set)

### 0.3) Demo Moment First (Recommended for prototypes)

Principle: a prototype that **feels real** needs at least one “demo moment” (tastefully showy, not gimmicky).

Examples of “demo moment” (pick 1, keep it small):
- A hero section with a **live interactive preview** (fake data is fine) + smooth, purposeful motion
- A delightful micro-interaction: command palette, draggable cards, timeline scrubber, etc.
- A “before/after” transformation animation (input → output) that makes the core loop obvious

Workflow:
1. Write a small feature spec file (if it doesn’t exist):
   - `evidence/feature-00-demo-moment.md`
   - Include `mode: plan-only`, `feature_slug: demo-moment`, and `quality_bar: demo-ready`
2. Call `workflow-feature-shipper` to generate the plan **only** (no implementation yet).
3. Defer actual UI implementation until after Step 2 (design-system.md exists), so the demo moment follows the chosen design system.

### 0.5) Dynamic Branch Decision (Required)

Dynamically adjust execution order based on `context.json` content:

- **Database integration**: Only execute when `context.json` has `"need_database": true`
- **Payment integration**: Only execute when `context.json` has `"need_billing": true` or `"need_stripe": true`
- **Auth**: Only execute when `context.json` has `"need_auth": true` or `"auth": true`
- **Deployment**: Only execute when `context.json` has `"need_deploy": true` or user explicitly requests deployment
- **SEO**: Only execute when `context.json` has `"need_seo": true` or project is already live

Before starting each optional step:
- Check `context.json` (and your chosen `scope`) to decide whether the step applies
- If skipped, write a 1-line reason into `tasks.md` (so resume/audit doesn’t require chat history)

### 1) Foundation: Next.js Foundation (Default Required)

Open and follow: [foundation.md](foundation.md).

Artifact requirements (minimum):
- `evidence/foundation.md` (current state + risk assessment + chosen route)
- `tasks.md`: add a **Foundation** checklist section (tasks + verification commands)
- If upgrade/migration needed with significant changes: add an **Approval** item to `tasks.md` and wait for confirmation

**Branch rules (important)**:
- If conclusion is **keep-current-stack** (e.g., Vite static site), don't force continuing "Next.js-specific steps".
  - Only continue steps that still apply to current stack: style (2), guardrails (3, adapted for current stack), docs (4), deploy (8 optional), SEO (9 optional)
  - If DB/payment integration still needed: First ask user "want to migrate to Next.js?", or add integration step for that stack (not in this chain's default scope)

### 2) Style Specification (Default Required)

Call `tool-design-style-selector`: Scan project intent and persist `design-system.md`.

Confirmation point: After user confirms style, deploy `design-system.md`, and enter **2.5 UI/UX Implementation** (default required; if user explicitly skips, log reason).

### 2.5) UI/UX Implementation (Default Required)

Goal: Make `design-system.md` actually reflected in the interface, not "wrote spec but UI unchanged".

Recommended approach: Treat "redo UI/UX per design-system.md" as an independent feature and hand to `workflow-feature-shipper`:
- Input: `design-system.md` (as sole design constraint) + current UI page list (from code scan)
- Output: `evidence/features/<feature_slug>-plan.md` (scope/acceptance criteria/non-goals/risks/rollback) + code changes

Default enrichment (when installed):
- If `tool-ui-ux-pro-max` is installed, use it to enrich the UI/UX plan with concrete palette/typography/UX guardrails, and use its pre-delivery checklist as acceptance criteria.
- Only skip `tool-ui-ux-pro-max` enrichment if the user explicitly asks to skip it (e.g., “don’t over-design / keep it simple”), and log the reason.

For large-scale refactoring: add an **Approval** item to `tasks.md` first and wait for user confirmation before implementing.

### 3) Code Standards (Lightweight Required)

Open and follow: [guardrails.md](guardrails.md).

Artifact: `tasks.md` (Guardrails checklist section)

### 3.5) Trace Cleanup (De-branding & Source Hygiene) (Required if project was copied)

Problem this solves: many starter projects imported from Google AI Studio / v0 / Lovable ship with vendor branding, broken remnants (like `importmap`), and misleading README instructions.

Open and follow: [cleanup-traces.md](cleanup-traces.md).

Artifacts:
- `evidence/trace-scan.md`
- `tasks.md` (Trace cleanup checklist section)

### 4) Documentation Standards (Lightweight Required)

Open and follow: [docs-baseline.md](docs-baseline.md).

Artifact: `tasks.md` (Docs checklist section, plus project README update)

### 5) Core Feature Development (Iterative Loop)

Call `workflow-feature-shipper`:
- Each feature first produces `evidence/features/<feature_slug>-plan.md` (with acceptance criteria/non-goals)
- Default split into PR-able small steps
- After each batch (or before merge), recommend calling `review-quality` for a conclusive review + verdict
- `review-quality` is the single entry point and will auto-triage: if React/Next.js performance risk is detected, it will also run `review-react-best-practices` (CRITICAL rules first)

Auth note (optional): if a feature includes login/session/permissions and `tool-better-auth` is installed, call it before implementation to lock down session strategy, redirects, cookies/CSRF, and middleware boundaries. Persist:
- `evidence/auth-plan.md`
- `evidence/auth-summary.md`

### 6) Database Integration (Optional)

**Execution condition**: `context.json` has `"need_database": true` or `"database": "supabase"`

Open and follow: [supabase-integration.md](supabase-integration.md).

### 7) Payment Integration (Optional)

**Execution condition**: `context.json` has `"need_billing": true` or `"need_stripe": true` or `"payment": true`

Open and follow: [stripe-integration.md](stripe-integration.md).

### 8) GitHub + Vercel Deployment (Optional but Recommended)

**Execution condition**: `context.json` has `"need_deploy": true` or `"deploy_target"` field exists and non-empty

Open and follow: [deploy-vercel.md](deploy-vercel.md).

### 9) AI-Era SEO (Optional but Recommended)

**Execution condition**: `context.json` has `"need_seo": true` or `"seo": true`, or step 8 completed successfully (already deployed)

Open and follow: [ai-seo-nextjs.md](ai-seo-nextjs.md).

## Final Delivery

Write to: `final.md` (in the run root), at minimum include:
- Current project status (can run locally, can build, is deployed)
- Completed steps and artifact paths
- Next steps (prioritized by value)

And wrap up:
- Update `tasks.md` `status` to `done`, and fill the **Delivery summary**
- Run auto-archive after each batch (and at the end):
  - `python3 ~/.claude/skills/workflow-ship-faster/scripts/auto_archive.py --run-dir "<run_dir>"`
- If you want a clean workspace (without auto-archive): move `active/<run_id>/` → `archive/YYYY-MM-DD-<run_id>/`
- Do a `skill-evolution` **Evolution checkpoint** (3 questions); if user chooses "want to optimize", run `skill-improver` based on this `run_dir` to produce minimal patch suggestions


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### references/artifact-contract.md

```markdown
# Artifact Contract (runs/ + OpenSpec)

This document defines the **artifact-first, resumable run directory contract** used by `workflow-ship-faster`.

> Design goal: keep the workflow resumable and auditable **without requiring chat history**.

## Storage backends

This workflow supports two storage backends.

### Backend A (default): `runs/`

- Active: `runs/ship-faster/active/<run_id>/`
- Archive (after completion): `runs/ship-faster/archive/YYYY-MM-DD-<run_id>/`

### Backend B (OpenSpec-compatible): `openspec/`

If the repo is OpenSpec-initialized (detect via `openspec/project.md`), store artifacts as an OpenSpec change:

- Active: `openspec/changes/<change-id>/`
- Archive (after completion): `openspec/changes/archive/YYYY-MM-DD-<change-id>/`

Notes:
- In OpenSpec mode, `run_id` is the `change-id` (kebab-case, verb-led).
- If `openspec` CLI is available, prefer scaffolding the change via `openspec new change <change-id>`.

## Backend selection (must be deterministic)

Resolve `run_dir` using this priority order:

1) If `context.json` includes `"artifact_store": "runs"` or `"openspec"`, follow it.
2) Else if `openspec/project.md` exists in `repo_root`, use OpenSpec backend.
3) Else use the default `runs/` backend.

From this point on, treat `run_dir` as the resolved active directory (`runs/.../active/...` or `openspec/changes/...`).

## Required files (small + resumable)

Each run directory **must** contain:

- `proposal.md`: why/what/scope/constraints (stable context)
- `tasks.md`: executable checklist (`- [ ]` → `- [x]`) + approvals (**resume here**)
- `context.json`: machine-readable switches + repo_root + risk preference

Recommended minimal `context.json` (extend as needed):

```json
{
  "repo_root": "",
  "scope": "full",
  "artifact_store": "auto",
  "need_database": false,
  "need_billing": false,
  "need_deploy": false,
  "need_seo": false
}
```

Optional (only create if needed):

- `design.md`: technical decisions (only if ambiguity/risk warrants it)
- `evidence/`: large outputs / scans / screenshots (paths only in chat)
- `logs/`: optional debug logs (`events.jsonl`, `state.json`)

## Templates (minimum viable)

### `proposal.md`

```md
# Proposal: <title>

- run_id: <run_id>
- status: active|blocked|done
- created_at: <ISO8601>
- repo_root: <path>

## Why
- <1-3 bullets>

## What changes
- <1-5 bullets>

## Acceptance criteria
- <3-7 bullets>

## Non-goals
- <1-3 bullets>

## Links
- tasks: tasks.md
- evidence: evidence/ (optional)
```

### `tasks.md`

```md
# Tasks: <title>

- run_id: <run_id>
- status: active|blocked|done
- last_updated: <ISO8601>

## Checklist
- [ ] T1: <small, verifiable>
- [ ] T2: <small, verifiable>
- [ ] T3: <small, verifiable>

## Verification (required for auto-archive)
- [ ] V1: Verification completed (commands + outcomes recorded under Evidence index)

## Approvals (only if needed)
- (none)

## Evidence index (paths only)
- evidence/<...>

## Delivery summary (fill when done)
- <what shipped>
- <how to verify>
- <next steps>
```

## Default read order (resume)

Unless the user points you at a specific file, read:

1) `tasks.md` (resume + progress)
2) `proposal.md` (context)
3) `context.json` (switches)
4) `design.md` (if exists)
5) Only then: `evidence/` / `logs/`

## Read/write hygiene (mandatory)

Layer info to avoid "output piling up in chat → context window explosion":

- **Raw evidence (traceable, not loaded by default)**: long command output, scans, screenshots → write to `evidence/` or `logs/`
- **Actionable state (default must-read)**: keep the checklist + the current truth in `tasks.md`

Constraints:
- Don’t paste large chunks into chat; write file(s) and return **paths only**
- Any info needed to resume must be written into `tasks.md`, not only in chat
- When tracing details: use `rg` inside `logs/` or search under `evidence/` first

## Archiving and retention (recommended)

If runs accumulate, default strategy is "read less + archivable", not "keep everything visible forever":

- Completed runs (`status: done`) should be **read-only**, avoid polluting retrospectives
- After completion: move `active/<run_id>/` → `archive/YYYY-MM-DD-<run_id>/`

## Auto-archive (fully automatic)

Ship Faster supports **fully automatic archiving** when a run is complete.

Archiving eligibility (must all be true):
- `tasks.md` contains a verification section (`## Verification` or `## Testing`) with at least one checkbox item
- **All** checkbox items in `tasks.md` are checked (`- [x]`)

Automation rule (mandatory):
- After every execution batch (or any time you update checkboxes), run:
  - `python3 ~/.claude/skills/workflow-ship-faster/scripts/auto_archive.py --run-dir "<run_dir>"`
- The script is deterministic:
  - If eligible: it archives the run directory immediately (no confirmation)
  - If not eligible: it prints a short reason and does nothing

## OpenSpec alignment (recommended)

Separate "stable project truth" from "single change run" (avoid stuffing everything into run):

- **Source of truth (project-level docs)**: `design-system.md`, `README.md`, `docs/`, architecture/constraint docs
- **Change folder (this run)**: `run_dir/` (only this run’s proposal/tasks/evidence/logs)

Implementation rule:
- This run folder only stores **process + evidence + decisions**; anything that should live long-term gets merged back to project docs


```

### references/README.md

```markdown
# References (workflow-ship-faster)

This folder contains **deep docs** intended for **progressive disclosure**.

Start from `../SKILL.md` and only open these when you actually need the extra detail (to keep context small and execution deterministic).

## Index

| Doc | When to open | What it covers |
|---|---|---|
| `artifact-contract.md` | You need to create/resume a run, or confirm how archiving works | Storage backend selection (`runs/` vs OpenSpec), required artifacts (`proposal.md`, `tasks.md`, `context.json`), templates, resume read order, auto-archive rules |

## Editing rule (keep the workflow “Ship Faster standard”)

- Keep `SKILL.md` as the **routing + safety + I/O contract** entry point.
- Put “long-form” explanations, templates, and edge-case detail here under `references/`.

```

### foundation.md

```markdown
# Step 1 — Next.js Foundation (target: 16.1.1)

Goal: Get the project to a sustainable Next.js baseline (preferably **16.1.1**) with minimal risk.

## Input (Pass Paths Only)

- `repo_root`: Project root directory path (doesn't exist means "new project")
- `run_dir`: Resolved run directory (see `workflow-ship-faster` → **Artifact Storage**)
- `target_next_version`: Default `16.1.1`

## Output (Persisted)

- `evidence/foundation.md`
- `tasks.md` (Foundation checklist section: tasks + verification)

## Plan (Checklist Required)

Before making changes:
- Add a **Foundation** checklist section to `tasks.md` (checkboxes + verification)
- If the plan includes risky migrations/upgrades, add an **Approval** item under `tasks.md` and wait for explicit user confirmation

## 0) Stack Assessment Gate (Decide Whether to Migrate First)

> Purpose of this step: Avoid "migrating to Next.js for the sake of Next.js".  
> Especially: **Vite/static sites/pure display pages** often aren't worth forcing migration for Ship Faster.

### 0.1 Quick Stack Identification (Required When Repo Exists)

Use minimum evidence set to determine current stack (don't guess):
- `package.json` dependencies/scripts: `next`, `vite`, `react-scripts`, `astro`, `nuxt`, `sveltekit`...
- Framework config exists: `next.config.*`, `vite.config.*`, `astro.config.*`, `nuxt.config.*`
- Routing/page structure: `app/` `pages/` (Next), `src/pages` (common in Vite/SPA), `public/` (static assets)
- Deploy/output: `vercel.json`, `netlify.toml`, build scripts (build output directory)

Write conclusion to `evidence/foundation.md`:
- Current stack: <detected>
- Evidence: <files/keys>

### 0.2 Ask One Question: Need to Migrate to Next.js?

When repo is **not Next.js**, ask user (multiple choice):

> Which situation best describes this project?
> 1) Pure static site/marketing page/display page (no SSR/API/auth/DB needed) → **Don't migrate**
> 2) Simple now, but soon becoming "full Web App" (auth, DB, dashboard, SEO, SSR/ISR) → **Recommend migrate**
> 3) Already mature engineering (lots of custom build/multi-package/complex routing) → **Don't auto-migrate**, only provide migration plan

Decision persisted (write to top of `evidence/foundation.md`, one clear line):
- Decision: `keep-current-stack` | `migrate-to-nextjs` | `plan-only-no-auto-migrate`

> Rule: When user chooses 1), don't "migrate anyway". This isn't a bug, it's strategy.

## Decision Tree (Must Follow)

### A) New Project (idea → project)

- Goal: Fastest path to runnable Next.js app (can `dev`, can `build`)
- Constraint: Minimize modifications, get main chain running first

Recommendation: Use `create-next-app` to create, then pin `next` version to `16.1.1`.

### B) Already Next.js Project

1. Identify current version (from `package.json` or lockfile)
2. If already `16.1.1`: No upgrade needed, just record "already at target"
3. If not `16.1.1`: Evaluate "is project too large"

**Project too large (default don't upgrade)** signals (any one triggers stop first):
- Lots of custom build: Complex `next.config.*` (webpack rewrites, complex rewrites/headers)
- Multi-package/monorepo structure is complex and CI build time is long
- Obvious framework migration history or lots of unconverged experimental features

When "too large":
- In `tasks.md`, write a **plan-only** Foundation section (upgrade risks, phased approach, rollback strategy)
- Don't auto-upgrade, wait for user confirmation

When not "too large":
- Upgrade to `16.1.1` (and record changes and verification results)

### C) Not Next.js but Very Small Prototype (Can Migrate)

Only migrate when "very small and confirmed migrate (Decision = migrate-to-nextjs)":
- Very small: Single package, few dependencies, simple routing/build logic
- Migration is definitely high effort: add an **Approval** item to `tasks.md` and wait for confirmation

Recommended migration route:
1. Create new Next.js 16.1.1 baseline project
2. Migrate UI components/business logic (prioritize no UI style changes)
3. Gradually replace routing and data fetching patterns

### D) Not Next.js and Not Migrating (Keep Current Stack)

When Decision = `keep-current-stack`:
- Don't do Next.js migration/upgrade actions
- In `tasks.md`, write a short "keep current stack" plan (e.g.: design system → guardrails → docs → deploy)
- Clearly state: Subsequent "Supabase/Stripe integration" are **Next.js adapters**; if still need DB/payment integration, need to:
  - Either migrate to Next.js first
  - Or add integration step for that stack (e.g., `vite + supabase`), underlying DB operations still reuse `supabase` skill

## Verification (Required After Every Change)

- `npm/pnpm/yarn dev` can start
- `build` passes (if project has it configured)
- Key pages can open

Write verification results to `evidence/foundation.md`.

```

### guardrails.md

```markdown
# Step 3 — Guardrails (Lightweight Code Standards)

Goal: Establish a code standards baseline that "won't slow down development" with minimal cost.

## Scope (Boundaries)

**Applicable:**
- Next.js projects (prioritize `next lint`)
- Non-Next.js frontend projects (like Vite/React/Vue): Can also use this step to establish lint/format/typecheck baseline, but adapt scripts for current stack (e.g., `vite build`, `eslint .`, `tsc -p tsconfig.json`)

**Not applicable:**
- You want "deep governance/refactoring health check" → Use `review-quality` or `tool-ast-grep-rules`

## Input (Pass Paths Only)

- `repo_root`: Project root directory
- `run_dir`: Resolved run directory (see `workflow-ship-faster` → **Artifact Storage**)

## Output (Persisted)

- `tasks.md` (Guardrails checklist section: tasks + verification)
- Optional: `evidence/guardrails-current.md` (current state scan)

## Plan (Checklist Required)

Before changing repo config/scripts, add a Guardrails checklist section to `tasks.md`.
Record verification results (lint/typecheck/format) inside the same `tasks.md` section.

## Principles

- **Prefer reusing existing conventions**: If project already has eslint/prettier/biome etc., don't introduce a second set.
- **Run first, stricten later**: Default to no "heavy governance", avoid blocking ship.

## Minimum Viable Baseline

1. Ensure `package.json` has clear script entries (add as needed per project state, don't force reorganize):
   - `dev`, `build`, `start`
   - `lint` (Next.js projects prioritize `next lint`)
   - `typecheck` (if using TS)
   - `format` (if using Prettier/Biome)
2. If missing formatter: Choose one (Prettier or Biome), only minimal config.
3. If CI already exists: Just align scripts; if no CI: Recommend completing alongside deployment step.

## Delivery

- In `tasks.md`, list files and commands to be added/modified
- After changes complete, append verification results to the same `tasks.md` section

```

### cleanup-traces.md

```markdown
# Step 3.5 — Trace Cleanup (De-branding & Source Hygiene)

Goal: When a project is copied from external generators (e.g., Google AI Studio, v0, Lovable), remove **their branding + scaffolding remnants** so the repo looks first‑party and doesn’t ship broken artifacts.

## Input (Pass Paths Only)

- `repo_root`
- `run_dir`

## Output (Persisted)

- `evidence/trace-scan.md` (what was found; paths + short notes)
- `tasks.md` (Trace cleanup checklist section: tasks + verification + evidence paths)
- Updated project files (README, HTML entrypoints, gitignore, etc.)

## Plan (Checklist Required)

Before making any edits, add a Trace cleanup checklist section to `tasks.md`.

Minimum requirements inside the plan:
- `## Tasks` as `- [ ]` items, derived from the checklist below
- `## Verification` as `- [ ]` items (commands + expected outcome)
- Evidence links to `evidence/trace-scan.md` and any other scan output

## What to Clean (Checklist)

### 1) Branding Sweep (fast scan)

Search for obvious vendor fingerprints and record hits (path + a short reason) in `evidence/trace-scan.md`:

- “AI Studio” / “Run and deploy your AI Studio app”
- `ai.studio` links
- `v0` / `v0.dev`
- “Lovable” / `loveable.dev`
- Google asset/badge URLs (e.g. `user-attachments`, `gstatic`, `googleapis`)
- “Generated by …” banners or boilerplate sections in `README.md`

### 2) README Hygiene (required)

- Remove third-party banner images and “view in X” links.
- Remove generator instructions that don’t match the repo (e.g., “npm install + set GEMINI_API_KEY…” when the project doesn’t require it).
- Replace with a clean project README (or Ship Faster template README if this is a template):
  - one-line value prop
  - features
  - quickstart
  - env vars (key names only; omit if none required)
  - scripts
  - design system link (if present)

### 3) Runtime Artifact Cleanup

Remove or exclude common “copied project” leftovers:

- Delete: `.claude/`, `runs/`, `node_modules/`, `dist/`, `.DS_Store`, `.vercel/` (if present)
- Ensure `.gitignore` covers these artifacts
- Ensure no secrets are committed (`.env.local` must never be in git)

### 4) Frontend Entry Hygiene (avoid subtle runtime bugs)

Common issues from copied starters:

- **Vite + `importmap` conflict**: if the project uses Vite bundling, remove any `<script type="importmap">` from `index.html` to avoid React being loaded twice.
- **`/index.css` 404**: remove hardcoded `<link rel="stylesheet" href="/index.css">` unless the file truly exists and is served that way. Prefer `import './index.css'` from `index.tsx`.

### 5) Environment Variable Hygiene

Goal: remove *vendor-specific* env requirements from docs unless truly required.

- Prefer **no required env vars** for demos/templates (fallback to mock output when missing).
- If a key is optional, document it as optional and default to safe behavior.
- Avoid naming env vars after vendors in docs (`GEMINI_API_KEY`, etc.). Prefer a neutral `API_KEY` when needed.

### 6) Keep Required Attribution

Don’t remove legal/license attribution if it’s required by the source or dependencies. Clean “marketing + generator fingerprints”, not legal obligations.

## Verification (must record results)

Write the final verification results into the Trace cleanup section in `tasks.md`:

- No hits for branding strings you intentionally removed
- `git status` shows no secrets / no accidental large artifacts
- App runs locally (`pnpm dev` / `npm run dev`)
- No console/runtime errors indicating double React / broken hooks

```

### docs-baseline.md

```markdown
# Step 4 — Docs Baseline (Minimum Viable Documentation)

Goal: Not "write everything", but **let people quickly run it, deploy it, and iterate**.

## Input (Pass Paths Only)

- `repo_root`
- `run_dir`

## Output (Persisted)

- `tasks.md` (Docs checklist section: tasks + verification)
- Main artifact is: Project `README.md` (in repo)

## Plan (Checklist Required)

Before editing docs, add a Docs checklist section to `tasks.md`.
Mark tasks complete only after verifying docs match the actual scripts/env requirements.

## Minimum README Template (Recommended Contents)

- One-sentence project description (goal/users)
- Local startup (Node version, install, `dev`)
- Environment variables (list key names, don't write secret values)
- Database (if applicable: Supabase)
- Payments (if applicable: Stripe)
- Deployment (Vercel)
- Design system: Link to `design-system.md`

## Principles

- Don't introduce large docs directories unless actually needed
- Content should be "copy-paste runnable", avoid lengthy theory

```

### supabase-integration.md

```markdown
# Step 6 — Next.js + Supabase (Ship Faster Integration)

Goal: Complete "can read/write data + types available + security gates" via shortest path.

## Scope (Boundaries)

**Applicable:**
- Need to **integrate Supabase into Next.js project** (env / types / minimal read-write / migration strategy / traceable artifacts)

**Not applicable:**
- Just want to run a quick query, execute some SQL, check logs, do a one-time migration (use `supabase` skill directly—faster and cleaner)

**Dependencies:**
- This step executes all DB actions through `supabase` skill (schema detection / migration / types generation / logs etc.)
- DB security gates (write operation confirmation, DDL via migration, UPDATE/DELETE must have WHERE...) follow `supabase` skill rules

## Input (Pass Paths Only)

- `repo_root`
- `run_dir`
- `requirements.md` (optional): What tables/fields/queries are needed

## Output (Persisted)

- `tasks.md` (Supabase checklist section: tasks + verification)
- `evidence/schema.md` (runtime detected/confirmed schema)
- `evidence/supabase-summary.md`

## Plan (Checklist Required)

Before any schema/migration/integration edits, add a Supabase checklist section to `tasks.md`.
For any write SQL (INSERT/UPDATE/DELETE), add an **Approval** item to `tasks.md` as the explicit confirmation gate.

## Process

1. Use `supabase` skill to dynamically detect schema (don't rely on outdated schema docs)
2. DDL always goes through migration (`apply_migration`)
3. Write operations always go through confirmation point (write SQL to `evidence/sql.md` first, then execute)
4. Generate TypeScript types (`generate_typescript_types`) and persist in project (location per project conventions)
5. Integrate with Next.js:
   - Only write env key names, don't write secret values to logs
   - Implement minimal data access layer first (one read, one write), then expand

## Confirmation Points

- Any INSERT/UPDATE/DELETE: add an **Approval** item to `tasks.md` first, then request user confirmation
- Rows affected > 100: Mandatory second confirmation

```

### stripe-integration.md

```markdown
# Step 7 — Next.js + Stripe (Ship Faster Integration)

Default goal: **Get paid first**, then gradually evolve into a deeper billing system.

## Input (Pass Paths Only)

- `repo_root`
- `run_dir`
- `billing.md` (optional): What to sell (one-time/subscription), pricing, delivery method

## Output (Persisted)

- `tasks.md` (Stripe checklist section: tasks + verification)
- `evidence/stripe-actions.md` (human-auditable action log: intended Stripe operations)
- `evidence/stripe-summary.md`
- `evidence/receipt.json`

## Plan (Checklist Required)

Before executing Stripe operations or integrating code, add a Stripe checklist section to `tasks.md`.
Keep `evidence/stripe-actions.md` as the human-auditable action list (what you plan to do in Stripe + why), then mark items `- [x]` only after execution + verification.

## Two Routes

### Route A (Default, Fastest): Payment Links (Low-code/No-code)

1. Use `stripe` skill to create/reuse Product + Price
2. Use `stripe` skill to create Payment Link (one-time or subscription)
3. Minimal integration in Next.js:
   - Provide a "Buy/Subscribe" button that redirects to Payment Link
   - Success page/copy can be optimized later

Pros: Fast, fewer pitfalls; Cons: Limited deep customization capability.

### Route B (Optional): Code Integration (webhook + SDK)

Only take this route when you need:
- Strong consistency of order status in your own system
- Webhook-driven business provisioning/permission control

Requires:
- Stripe SDK
- Webhook endpoint
- Securely store webhook secret (only in env, not in logs)

## Mandatory Confirmation Points

- Any money/contract related action (refund, cancel subscription, update subscription, submit dispute evidence) must:
  1) Write to `evidence/stripe-actions.md`
  2) Add an **Approval** item to `tasks.md`
  3) Wait for explicit user confirmation before executing

```

### deploy-vercel.md

```markdown
# Step 8 — GitHub + Vercel Deploy (Ship Faster)

Goal: Quickly turn "runs locally" into "has a URL online (preview/prod)".

## Input (Pass Paths Only)

- `repo_root`
- `run_dir`
- `env-vars.md` (optional): What environment variables are needed (key names only, no secrets)

## Output (Persisted)

- `tasks.md` (Deploy checklist section: tasks + verification)
- `evidence/deploy-summary.md` (URLs + config notes + verification)

## Plan (Checklist Required)

Before any GitHub/Vercel actions, add a Deploy checklist section to `tasks.md`.
If the plan includes secrets, repo settings, or production switches, also add an **Approval** item to `tasks.md` and wait for explicit user confirmation.

## Process

1. GitHub:
   - If no repo yet: Create and push to GitHub (can use `gh`)
   - Set up minimal CI: lint/typecheck/build (per existing project scripts)
2. Vercel:
   - Create/connect project (dashboard or `vercel` CLI)
   - Configure env vars (Supabase/Stripe etc.)
   - Confirm preview auto-deploy
3. Verification:
   - Preview URL is accessible
   - Key pages work correctly

## Confirmation Points

- Any action that modifies GitHub repo settings, writes secrets, or switches production environment: add an **Approval** item to `tasks.md` first and wait for confirmation.

```

### ai-seo-nextjs.md

```markdown
# Step 9 — AI-era SEO for Next.js

Goal: Get "discoverable by search engines + readable by LLMs" right with minimal investment.

## Input (Pass Paths Only)

- `repo_root`
- `run_dir`
- `site.json` (optional): Site info (domain, site name, main pages, update frequency)

## Output (Persisted)

- `tasks.md` (SEO checklist section: tasks + verification)
- `evidence/seo-summary.md`

## Plan (Checklist Required)

Before SEO edits, add an SEO checklist section to `tasks.md`.
Record verification (sitemap/robots routes reachable, metadata present) in the same `tasks.md` section.

## Minimum Delivery Checklist (Recommend Completing All)

1. `robots` (allow/disallow crawling policy)
2. `sitemap` (at least include core pages)
3. Site-wide metadata: title/description/canonical
4. OpenGraph/Twitter cards (at least one default set)
5. Structured data (JSON-LD): organization/product/article (choose by site type)
6. `llms.txt` (site index entry for LLMs; keep content brief and maintainable)

## Optional modules (when installed)

Use these to raise SEO quality without bloating the base step:

1. `review-seo-audit`: run after minimum checklist to find concrete issues and prioritize fixes.
   - Persist: `evidence/seo-audit.md`
2. `tool-schema-markup`: if you need rich results / structured data beyond the basics.
   - Persist: `evidence/schema-markup.md`
3. `tool-programmatic-seo`: if the goal includes template-driven pages at scale (directories, locations, comparisons).
   - Persist: `evidence/programmatic-seo.md`

## Optional: Cloudflare Enhancement (Don't Block Ship)

If user explicitly wants to use Cloudflare:
- Only do minimal config directly related to "discoverability/performance" (caching/redirects/basic observability)
- Don't force complex edge logic at launch

```