Ensure core artifacts exist (create if missing; merge/append if already present):
proposal.md
,
tasks.md
,
context.json
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)
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:
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
Call
workflow-feature-shipper
to generate the plan
only
(no implementation yet).
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
.
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/-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
.
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
.
Artifacts:
evidence/trace-scan.md
tasks.md
(Trace cleanup checklist section)
4) Documentation Standards (Lightweight Required)
Open and follow:
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/-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
.
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
.
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
.
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
.
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 ""
If you want a clean workspace (without auto-archive): move
active//
→
archive/YYYY-MM-DD-/
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