@kennethsolomon/shipkit 3.18.0 → 3.20.0

package/skills/sk:laravel-deploy/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: sk:laravel-deploy
+description: "Deploy a Laravel application to Laravel Cloud via the `cloud` CLI. Requires /sk:gates to pass before deploying."
+---
+
+# /sk:laravel-deploy
+
+Deploy the current Laravel application to Laravel Cloud.
+
+## Pre-Deploy Gate Check
+
+**Gates must pass before any deploy.** If `/sk:gates` has not been run since the last code change, run it first:
+
+```
+/sk:gates
+```
+
+All quality checks (lint, tests, security, review) must be green before deploying to any environment.
+
+## Setup (First Time)
+
+Install the Laravel Cloud CLI if missing:
+```bash
+composer global require laravel/cloud-cli
+```
+
+Authenticate:
+```bash
+cloud auth -n
+```
+
+## CLI Rules
+
+Never hardcode command signatures — always run `cloud <command> -h` to discover options at runtime.
+
+| Operation | Flags |
+|-----------|-------|
+| Read | `--json -n` |
+| Create | `--json -n` |
+| Update | `--json -n --force` |
+| Delete | `-n --force` (no `--json`) |
+| Deploy | `-n` with all options explicitly |
+
+## Deployment Workflow
+
+### First Deploy
+```bash
+cloud ship -n
+```
+
+### Existing App
+```bash
+cloud repo:config
+cloud deploy {app} {env} -n --open
+cloud deploy:monitor -n
+```
+
+### Environment Variables
+```bash
+cloud environment:variables -n --force
+```
+
+### Infrastructure
+
+**Database:**
+```bash
+cloud database-cluster:create --json -n
+cloud database:create --json -n
+```
+
+**Cache:**
+```bash
+cloud cache:create --json -n
+```
+
+**Custom Domain:**
+```bash
+cloud domain:create --json -n
+cloud domain:verify -n
+```
+
+## Sub-Agent Delegation
+
+Delegate to background agents (non-blocking):
+- `deploy:monitor` — watch deployment progress
+- `deployment:get` — fetch deployment status
+- `resource:list` — list infrastructure resources
+
+Keep in main context:
+- `cloud deploy` (need deployment ID immediately)
+- Short status commands
+
+## Troubleshooting
+
+Inspect current infrastructure state:
+```bash
+cloud <resource>:list --json -n
+```
+
+Check deployment logs:
+```bash
+cloud deployment:get {id} --json -n
+```
+
+## Official Plugin
+
+For richer guidance with checklists for complex multi-step infrastructure operations, install the official plugin:
+```
+/plugin install laravel-cloud@laravel
+```
+
+Docs: https://cloud.laravel.com/docs

package/skills/sk:laravel-init/SKILL.md

@@ -32,6 +32,24 @@ Behavior depends on who owns the file:
 - **Generated** (has `<!-- Generated by /laravel-init -->` marker): safe to edit directly with section-level updates using `<!-- BEGIN/END -->` markers
 - **User-owned** (no marker): never edit — create `CLAUDE-sub-agents.md` alongside it and let the user copy what they want
 
+## Optional: Official Laravel Plugins
+
+After setup completes, suggest the two official Laravel plugins from Taylor Otwell:
+
+> "Install official Laravel plugins? (`laravel-simplifier` for code refinement + `laravel-cloud` for deployments) [y/n]"
+
+If yes, install each:
+```bash
+/plugin install laravel-simplifier@laravel
+/plugin install laravel-cloud@laravel
+```
+
+**What each adds:**
+- `laravel-simplifier` — an Opus-powered agent that reviews recently modified PHP/Laravel code and refines it for PSR-12 compliance, Laravel conventions, and readability without changing behavior. Invoke after `/sk:execute-plan`: "Review recent changes using the laravel-simplifier agent"
+- `laravel-cloud` — guides deployment and infrastructure management on Laravel Cloud via the `cloud` CLI. Triggers automatically when you ask about deploying. Or use `/sk:laravel-deploy` for a gate-enforced deploy workflow.
+
+If no, skip — plugins can be installed manually at any time.
+
 ## After Running
 
 Start with `/sk:brainstorm` to plan your feature.

package/skills/sk:lint/SKILL.md

@@ -30,97 +30,77 @@ Scan the project root for config files. Enable every matching stack:
 | `Cargo.toml` | Rust | `cargo fmt` | `cargo clippy` |
 
 Detection logic:
-- For `composer.json`: read `require-dev` keys for `laravel/pint`, `phpstan/phpstan`, `rector/rector`
-- For `package.json`: read `devDependencies` keys for `eslint`, `prettier`
-- For `pyproject.toml`: check `[tool.ruff]` section or `ruff` in `[project.optional-dependencies]` / `[build-system]`
-- For `go.mod` / `Cargo.toml`: presence of file is sufficient
+- `composer.json`: read `require-dev` keys for `laravel/pint`, `phpstan/phpstan`, `rector/rector`
+- `package.json`: read `devDependencies` keys for `eslint`, `prettier`
+- `pyproject.toml`: check `[tool.ruff]` section or `ruff` in `[project.optional-dependencies]` / `[build-system]`
+- `go.mod` / `Cargo.toml`: presence of file is sufficient
 
 Print detected stacks and tools before running anything.
 
 ### 3. Run Formatters — Sequential
 
-Formatters modify files, so run them one at a time in this order:
+Run in this order (formatters modify files — must not run in parallel):
 
-1. **Pint** (if detected): `vendor/bin/pint --dirty`
-2. **Prettier** (if detected): `npx prettier --write .`
-3. **ruff format** (if detected): `ruff format .`
-4. **gofmt** (if detected): `gofmt -w .`
-5. **cargo fmt** (if detected): `cargo fmt`
+1. Pint: `vendor/bin/pint --dirty`
+2. Prettier: `npx prettier --write .`
+3. ruff format: `ruff format .`
+4. gofmt: `gofmt -w .`
+5. cargo fmt: `cargo fmt`
 
-After each formatter, note which files changed. All formatters must finish before step 4.
+Note which files changed. All formatters must finish before step 4.
 
 ### 4. Run Analyzers — Parallel Sub-Agents
 
 Launch all detected analyzers in parallel using the Agent tool in a single message:
 
-- **PHPStan**: `vendor/bin/phpstan analyse --memory-limit=512M`
-- **Rector**: `vendor/bin/rector --dry-run`
-- **ESLint**: `npx eslint .`
-- **ruff check**: `ruff check .`
-- **golangci-lint**: `golangci-lint run`
-- **cargo clippy**: `cargo clippy`
+- PHPStan: `vendor/bin/phpstan analyse --memory-limit=512M`
+- Rector: `vendor/bin/rector --dry-run`
+- ESLint: `npx eslint .`
+- ruff check: `ruff check .`
+- golangci-lint: `golangci-lint run`
+- cargo clippy: `cargo clippy`
 
-Example with PHPStan + Rector + ESLint detected:
-```
-Agent 1: "Run vendor/bin/phpstan analyse --memory-limit=512M. Report all errors with file:line."
-Agent 2: "Run vendor/bin/rector --dry-run. Report all suggested changes with file:line."
-Agent 3: "Run npx eslint . Report all errors with file:line."
-```
+Each agent: "Run `<command>`. Report all errors/changes with file:line."
 
 ### 5. Run Dependency Audit
 
-Run dependency vulnerability checks for detected stacks:
-
 | Stack | Command | Block on |
 |-------|---------|----------|
-| PHP (composer.json) | `composer audit` | any severity with fix available (`composer audit` has no severity filter) |
+| PHP (composer.json) | `composer audit` | any severity with fix available |
 | Node (package.json) | `npm audit --audit-level=high` | high or critical |
 | Node (yarn.lock) | `yarn audit --level high` | high or critical |
 | Node (pnpm-lock.yaml) | `pnpm audit --audit-level high` | high or critical |
 | Python (pyproject.toml / requirements.txt) | `pip-audit` | high or critical |
 
-For each detected package manager, run the audit command and capture output.
-
-**Block (fail this gate):**
-- PHP: any vulnerability that has a fix available (`composer audit` exits non-zero for all severities — no filtering option exists)
-- Node/Python: critical or high severity vulnerabilities that have a fix available
-
-**Warn (pass with note):** medium/low severity for Node/Python, or any severity with no available fix — note in report but do not block.
+**Block (fail this gate):** PHP: any vuln with fix available (`composer audit` exits non-zero for all severities). Node/Python: critical or high with fix available.
 
-Skip stacks not present in the project.
+**Warn (pass with note):** medium/low for Node/Python, or any severity with no fix — log but do not block.
 
 ### 6. Fix and Re-run
 
-If any analyzer reports errors or the dep audit blocks:
+**Classify each issue before fixing:**
 
-**Before fixing, classify each issue by scope:**
-
-- Run `git diff main..HEAD --name-only` to get the current branch diff.
-- If the issue is in a file **not** in that list (pre-existing issue outside the current branch), do **not** fix it inline. Log it to `tasks/tech-debt.md` in this format and move on:
+Run `git diff main..HEAD --name-only` to get branch diff.
 
+- **Out-of-scope** (file not in branch diff): do NOT fix inline. Log to `tasks/tech-debt.md`:
   ```
   ### [YYYY-MM-DD] Found during: sk:lint
   File: path/to/file.ext:line
   Issue: description of the problem
   Severity: high | medium | low
   ```
+- **In-scope** (file in branch diff): fix it.
 
-- If the issue is in a file **in** the branch diff (in-scope), fix it.
-
-**Fix loop (in-scope issues only):**
+**Fix loop (in-scope only):**
 1. Fix all in-scope issues
-2. Re-run formatters (fixes may need formatting)
+2. Re-run formatters
 3. Re-launch all analyzers in parallel
 4. Re-run dep audit if any dependency was fixed
-5. Re-run from step 3 until every tool exits clean
-6. Once all tools pass clean, make ONE squash commit: `fix(lint): resolve lint and dep audit issues` — do NOT ask the user
-
-> Squash gate commits — collect all fixes for the pass, then one commit. Do not commit after each individual fix.
+5. Repeat from step 3 until all tools exit clean
+6. Make ONE squash commit: `fix(lint): resolve lint and dep audit issues` — do NOT ask the user
 
 ### 7. Report Results
 
-Print one line per tool:
-
 ```
 Pint:          X files formatted / clean
 Prettier:      X files formatted / clean
@@ -143,23 +123,23 @@ Only include lines for detected tools. All must show "clean" before this skill p
 
 ## Fix & Retest Protocol
 
-When this gate requires a fix, classify it before committing:
+Classify every fix before committing:
 
-**a. Formatter auto-fix** (Pint, Prettier, gofmt, cargo fmt changed whitespace/style) → auto-commit and re-run `/sk:lint`. Never a logic change — bypass protocol.
+**a. Formatter auto-fix** (Pint, Prettier, gofmt, cargo fmt changed whitespace/style) → auto-commit and re-run. Never a logic change — bypass protocol.
 
-**b. Analyzer fix** (PHPStan type error, Rector suggestion, ESLint error, ruff violation) → classify each fix:
-  - Type annotation, import order, unused var, style rule → **style fix** → auto-commit and re-run
-  - New guard clause, changed condition, extracted function, modified data flow → **logic change** → trigger protocol:
-    1. Update or add failing unit tests for the new behavior
-    2. Re-run `/sk:test` — must pass at 100% coverage
-    3. Auto-commit (tests + fix together in one commit)
-    4. Re-run `/sk:lint` from scratch
+**b. Analyzer fix** (PHPStan, Rector, ESLint, ruff) — classify:
+- Type annotation, import order, unused var, style rule → **style fix** → auto-commit and re-run
+- New guard clause, changed condition, extracted function, modified data flow → **logic change** → protocol:
+  1. Update or add failing unit tests for the new behavior
+  2. Re-run `/sk:test` — must pass at 100% coverage
+  3. Auto-commit (tests + fix together)
+  4. Re-run `/sk:lint` from scratch
 
-**c. Dependency vulnerability fix** (composer audit / npm audit finding) → classify:
-  - Version bump with no API change → **style fix** → auto-commit and re-run
-  - Version bump with API/behavior change → **logic change** → trigger protocol
+**c. Dependency vulnerability fix** — classify:
+- Version bump, no API change → **style fix** → auto-commit and re-run
+- Version bump with API/behavior change → **logic change** → trigger protocol
 
-All commits in this protocol are automatic — do not prompt the user for commit approval.
+All commits are automatic — do not prompt the user.
 
 ---
 

package/skills/sk:mvp/SKILL.md

@@ -21,60 +21,44 @@ Generate a complete, aesthetically polished MVP from a single idea prompt. Outpu
 
 ## Step 1 — Gather the Idea
 
-Ask the user to describe their product idea. If not already provided, ask:
+Ask: **"What's your product idea? Describe it in 1-3 sentences — what does it do and who is it for?"**
 
-> **What's your product idea? Describe it in 1-3 sentences — what does it do and who is it for?**
-
-Extract from their answer:
+Extract and confirm before proceeding:
 - **Product name** (or ask them to pick one)
 - **One-line value proposition**
 - **Target audience**
-- **Key features** (3-5 core features for the app)
-
-Confirm your understanding before proceeding.
+- **Key features** (3-5 core features)
 
 ---
 
 ## Step 2 — Pick a Tech Stack
 
-Present these preset options:
+Present options:
 
-> **Pick a tech stack:**
->
-> 1. **Next.js + Tailwind** — React ecosystem, SSR, API routes built-in
-> 2. **Nuxt + Tailwind** — Vue ecosystem, SSR, server routes built-in
-> 3. **Laravel + Blade + Tailwind** — PHP ecosystem, full backend, Blade templates
-> 4. **React + Vite + Tailwind** — Lightweight SPA, no backend (waitlist via Formspree)
->
-> Or type your own stack (I'll adapt).
+| # | Stack | Notes |
+|---|-------|-------|
+| 1 | **Next.js + Tailwind** | React, SSR, API routes built-in |
+| 2 | **Nuxt + Tailwind** | Vue, SSR, server routes built-in |
+| 3 | **Laravel + Blade + Tailwind** | PHP, full backend, Blade templates |
+| 4 | **React + Vite + Tailwind** | Lightweight SPA, no backend (waitlist via Formspree) |
 
-Once the user picks, note the selection and load the corresponding reference file in Step 6.
+Or accept a custom stack. Note the selection for Step 6.
 
 ---
 
 ## Step 3 — Optional Design Phase (Pencil MCP)
 
-Check if the user invoked with `--pencil` flag or ask:
-
-> **Would you like to design the UI visually in Pencil before coding? (Requires Pencil app + MCP) (y/n)**
->
-> If no, I'll go straight to code generation with a great default design.
+Check for `--pencil` flag or ask: **"Design UI visually in Pencil before coding? (y/n)"**
 
 ### If YES — Pencil MCP Design Phase
 
-Follow this flow (adapted from sk:frontend-design):
-
-**3a. Find or create .pen file**
-- Check `docs/design/` for existing `.pen` file matching this MVP.
-- Existing: `open_document(filePath)` → skip to 3c.
-- None: `open_document('new')` → save to `docs/design/{product-slug}.pen`.
+**3a.** Check `docs/design/` for existing `.pen` file. If found: `open_document(filePath)` → skip to 3c. If not: `open_document('new')` → save to `docs/design/{product-slug}.pen`.
 
-**3b. Load design context**
-1. `get_guidelines(topic='landing-page')` — load landing page design rules.
-2. `get_style_guide_tags` → `get_style_guide(tags)` — pick tags matching the product's tone (e.g., modern, SaaS, minimal, bold).
+**3b.** Load design context:
+1. `get_guidelines(topic='landing-page')`
+2. `get_style_guide_tags` → `get_style_guide(tags)` — pick tags matching product tone.
 
-**3c. Set color palette as variables**
-Decide a distinctive color palette based on the product's tone and audience. Call `set_variables` with the palette:
+**3c.** Set color palette via `set_variables`:
 ```json
 {
   "color-bg": "#xxxxxx",
@@ -84,29 +68,20 @@ Decide a distinctive color palette based on the product's tone and audience. Cal
 }
 ```
 
-**3d. Build mockup screens**
-Use `batch_design` to create:
-1. Landing page frame — hero, features, pricing, waitlist section
-2. App main screen frame — dashboard or primary view
-3. App secondary screen frame — detail view or key interaction
+**3d.** Use `batch_design` (one frame per call) to create:
+1. Landing page — hero, features, pricing, waitlist section
+2. App main screen — dashboard or primary view
+3. App secondary screen — detail view or key interaction
 
-Work one frame per `batch_design` call. Apply the color variables and typography.
+**3e.** After each frame: `get_screenshot` → if off, `snapshot_layout` → fix → iterate until correct.
 
-**3e. Validate and iterate**
-After each frame: `get_screenshot` to inspect. If off: `snapshot_layout` → fix with `batch_design`. Iterate until the design matches the vision.
+**3f.** Ask: **"Does this design direction look good? Any changes before I start coding?"** Wait for explicit approval before proceeding.
 
-**3f. Get user approval**
-Present screenshots and ask:
-> **Does this design direction look good? Any changes before I start coding?**
-
-Wait for approval. Apply feedback if given. Do not proceed to code without explicit approval.
-
-**3g. Record the design**
-Note the `.pen` file path. The design decisions (colors, typography, layout) carry forward into code generation.
+**3g.** Note the `.pen` file path. Design decisions (colors, typography, layout) carry forward into code.
 
 ### If NO — Skip to Step 4
 
-Use the aesthetic guidelines from `references/design-system.md` to make distinctive design choices automatically. Briefly state the design direction chosen (color scheme, typography, layout style) so the user knows what to expect.
+Use `references/design-system.md` for design choices. State the chosen direction (color scheme, typography, layout style) briefly.
 
 ---
 
@@ -118,124 +93,100 @@ Read the stack-specific reference file:
 - Laravel → `references/stacks/laravel.md`
 - React + Vite → `references/stacks/react-vite.md`
 
-Run the scaffold command from the reference file. Then customize the Tailwind config with the chosen color palette and typography.
+Run the scaffold command from the reference file. Customize Tailwind config with the chosen color palette and typography.
 
 ---
 
 ## Step 5 — Generate the Landing Page
 
-Read `references/landing-page.md` for section patterns and structure.
-
-Generate a complete landing page with these sections (all mandatory):
+Read `references/landing-page.md`. Generate all 9 mandatory sections:
 
-1. **Navbar** — logo/product name + nav links (Features, Pricing, Waitlist) + CTA button
-2. **Hero** — headline (benefit-driven) + subheadline + primary CTA + hero visual/illustration area
-3. **Social proof bar** — "Trusted by X+" or logo strip (use placeholder logos)
-4. **Features grid** — 3-6 feature cards with icons, titles, descriptions (based on the key features from Step 1)
-5. **How it works** — 3-step process with numbered steps and descriptions
-6. **Pricing** — 2-3 tier cards (Free / Pro / Enterprise) with fake but realistic pricing
-7. **Testimonials** — 2-3 fake testimonial cards with names, roles, photos (use placeholder avatars)
-8. **Waitlist / CTA section** — email input + submit button + success message + form validation
+1. **Navbar** — logo + nav links (Features, Pricing, Waitlist) + CTA button
+2. **Hero** — benefit-driven headline + subheadline + primary CTA + hero visual
+3. **Social proof bar** — "Trusted by X+" or logo strip (placeholders)
+4. **Features grid** — 3-6 cards with icons, titles, descriptions (from Step 1 features)
+5. **How it works** — 3-step numbered process
+6. **Pricing** — 2-3 tier cards (Free / Pro / Enterprise) with fake realistic pricing
+7. **Testimonials** — 2-3 fake cards with names, roles, placeholder avatars
+8. **Waitlist / CTA** — email input + submit + success message + validation
 9. **Footer** — product name, links, copyright
 
 ### Waitlist Email Collection
 
-**For stacks with backend (Next.js, Nuxt, Laravel):**
-- Create an API route that accepts POST `{ email }`.
-- Validate the email format server-side.
-- Read existing `waitlist.json`, append the new entry with timestamp, write back.
-- Return success/error JSON response.
-- Wire the landing page form to POST to this route via fetch.
-- Show success state ("You're on the list!") and error state on the form.
+**Stacks with backend (Next.js, Nuxt, Laravel):**
+- API route: POST `{ email }` → validate server-side → read `waitlist.json` → append `{ email, timestamp }` → write back → return JSON.
+- Wire form to POST via fetch. Show success ("You're on the list!") and error states.
 
-**For static stacks (React + Vite):**
-- Use Formspree: form action points to `https://formspree.io/f/{form_id}`.
-- Add a comment/note telling the user to create a free Formspree account and replace `{form_id}`.
-- Handle success/error states client-side.
+**Static stacks (React + Vite):**
+- Use Formspree: `action="https://formspree.io/f/{form_id}"`.
+- Add comment instructing user to create a free Formspree account and replace `{form_id}`.
+- Handle success/error client-side.
 
 ---
 
 ## Step 6 — Generate the App
 
-Generate a working multi-page app with:
+Generate a working multi-page app with these 5 pages:
 
-1. **Navigation** — sidebar or top nav with links to all pages. Active state highlighting.
-2. **Dashboard / Home** — summary cards, charts (use simple CSS/SVG charts or placeholder), recent activity list. All fake data.
-3. **Primary feature page** — the main thing the product does. Functional UI with fake data. Buttons, modals, forms all work (client-side only).
-4. **Secondary feature page** — a supporting feature. Table or list view with filtering/sorting (client-side).
-5. **Settings / Profile page** — simple form with fake prefilled data. Save button shows a toast/notification.
+1. **Navigation** — sidebar or top nav, links to all pages, active state highlighting.
+2. **Dashboard / Home** — summary cards, simple CSS/SVG charts, recent activity list (fake data).
+3. **Primary feature page** — main product function, functional UI, client-side only (buttons, modals, forms work).
+4. **Secondary feature page** — supporting feature, table/list with client-side filtering/sorting.
+5. **Settings / Profile** — form with fake prefilled data, save button shows toast.
 
-### Design Standards (apply to every page)
+### Design Standards (every page)
 
-Read `references/design-system.md` and apply:
-- Distinctive color palette — never default Tailwind. Custom `tailwind.config` colors.
-- Thoughtful typography — use Google Fonts. Pair a display font with a body font.
-- Consistent spacing scale — use a rhythm (e.g., 4/8/12/16/24/32/48).
-- Polished components — rounded corners, shadows, hover states, transitions.
-- Responsive — must look good on mobile and desktop.
-- Fake data should feel realistic — use real-sounding names, numbers, dates.
+Read `references/design-system.md`:
+- Custom Tailwind colors — never defaults.
+- Google Fonts — pair display + body font.
+- Consistent spacing rhythm (e.g., 4/8/12/16/24/32/48).
+- Rounded corners, shadows, hover states, transitions.
+- Responsive — mobile and desktop.
+- Fake data must feel realistic (real-sounding names, numbers, dates).
 
 ---
 
 ## Step 7 — Visual Validation (Playwright MCP)
 
-After code generation is complete, validate the output visually.
+**If Playwright MCP available:**
+1. Start dev server (stack's dev command from reference file).
+2. Navigate to each page: `/`, `/dashboard`, each app page.
+3. Screenshot at desktop (1280px) and mobile (375px).
+4. Check for: broken layouts, missing content, non-functional interactions, visual inconsistency.
+5. Fix issues and re-validate.
 
-**If Playwright MCP is available:**
-
-1. Start the dev server (use the stack's dev command from the reference file).
-2. Use Playwright MCP to navigate to each page:
-   - Landing page (`/`)
-   - Dashboard (`/dashboard`)
-   - Each app page
-3. Take screenshots of each page at desktop (1280px) and mobile (375px) widths.
-4. Check for:
-   - Broken layouts (overlapping elements, overflow, misaligned sections)
-   - Missing content (empty sections, broken images, placeholder text not filled)
-   - Non-functional interactions (click buttons, submit forms, open modals)
-   - Visual consistency (colors match palette, typography is consistent)
-5. If issues found: fix them and re-validate.
-
-**If Playwright MCP is NOT available:**
-
-Tell the user:
-> Playwright MCP is not connected — skipping visual validation. Start the dev server with `{dev command}` and check the pages manually.
+**If Playwright MCP NOT available:**
+Tell user: `"Playwright MCP not connected — start the dev server with {dev command} and check pages manually."`
 
 ---
 
 ## Step 8 — Quality Loop
 
-If visual validation found issues:
-
-1. Fix the identified issues.
-2. Re-run Playwright validation (Step 7).
-3. Repeat until all pages pass — no broken layouts, all interactions work, design is consistent.
-
-Maximum 3 loop iterations. If issues persist after 3 loops, present remaining issues to the user and ask how to proceed.
+1. Fix issues found in Step 7.
+2. Re-run Playwright validation.
+3. Repeat until all pages pass. Max 3 iterations — if issues persist, present remaining issues and ask how to proceed.
 
 ---
 
 ## Step 9 — Generate Project Context Docs
 
-Generate 3 lightweight documentation files in `docs/` from information already gathered in Steps 1-2. No new questions — use the product name, value prop, audience, features, and tech stack already captured.
-
-### Files to Generate
+Generate 3 files in `docs/` using information from Steps 1-2. No new questions.
 
 **`docs/vision.md`**
 ```markdown
 # [Product Name]
 
 ## Value Proposition
-[One-line value prop from Step 1]
+[One-line value prop]
 
 ## Target Audience
-[Target audience from Step 1]
+[Target audience]
 
 ## Key Features
-[Bullet list of 3-5 features from Step 1]
+[Bullet list of 3-5 features]
 
 ## North Star Metric
-[Suggest one metric that measures core value — e.g., "weekly active waitlist signups" or "daily feature usage"]
+[One metric measuring core value]
 ```
 
 **`docs/prd.md`**
@@ -243,13 +194,13 @@ Generate 3 lightweight documentation files in `docs/` from information already g
 # PRD — [Product Name]
 
 ## Overview
-[1-2 sentence product description]
+[1-2 sentence description]
 
 ## User Stories
-[For each key feature from Step 1, write a user story: "As a [audience], I want to [feature] so that [benefit]"]
+[Per key feature: "As a [audience], I want to [feature] so that [benefit]"]
 
 ## Feature Acceptance Criteria
-[For each feature, list 2-3 concrete acceptance criteria]
+[Per feature: 2-3 concrete criteria]
 
 ## Out of Scope (MVP)
 - Real authentication
@@ -263,19 +214,19 @@ Generate 3 lightweight documentation files in `docs/` from information already g
 # Tech Design — [Product Name]
 
 ## Stack
-- **Framework:** [chosen stack from Step 2]
+- **Framework:** [chosen stack]
 - **Styling:** Tailwind CSS
 - **Fonts:** [chosen fonts]
 
 ## Project Structure
-[List the key directories and files generated during scaffolding]
+[Key directories and files from scaffolding]
 
 ## Component Map
 ### Landing Page
-[List all 9 sections and their components]
+[All 9 sections and their components]
 
 ### App Pages
-[List each page and its key components]
+[Each page and its key components]
 
 ## Data Model
 ### Waitlist
@@ -283,19 +234,15 @@ Generate 3 lightweight documentation files in `docs/` from information already g
 - timestamp: ISO 8601 string
 
 ### Fake Data Entities
-[List the fake data structures used in the app]
+[Fake data structures used in the app]
 ```
 
-After generating the docs, output:
-> **Context docs generated:** `docs/vision.md`, `docs/prd.md`, `docs/tech-design.md`
-> These persist context for future sessions. Run `/sk:context` to load `docs/vision.md` into the session brief, or read the others directly.
+Output after generating: `"Context docs generated: docs/vision.md, docs/prd.md, docs/tech-design.md — Run /sk:context to load vision.md into the session brief."`
 
 ---
 
 ## Step 10 — Present the Output
 
-Summarize what was generated:
-
 ```
 ## MVP Generated