@kennethsolomon/shipkit 3.0.7 → 3.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (18) hide show
  1. package/README.md +31 -24
  2. package/commands/sk/security-check.md +30 -15
  3. package/package.json +1 -1
  4. package/skills/sk:accessibility/SKILL.md +13 -8
  5. package/skills/sk:e2e/SKILL.md +147 -0
  6. package/skills/sk:lint/SKILL.md +49 -4
  7. package/skills/sk:perf/SKILL.md +33 -11
  8. package/skills/sk:review/SKILL.md +33 -2
  9. package/skills/sk:seo-audit/SKILL.md +283 -0
  10. package/skills/sk:setup-claude/templates/CLAUDE.md.template +149 -84
  11. package/skills/sk:setup-claude/templates/commands/brainstorm.md.template +4 -4
  12. package/skills/sk:setup-claude/templates/commands/execute-plan.md.template +2 -2
  13. package/skills/sk:setup-claude/templates/commands/finish-feature.md.template +8 -8
  14. package/skills/sk:setup-claude/templates/commands/security-check.md.template +3 -3
  15. package/skills/sk:setup-claude/templates/commands/write-plan.md.template +1 -1
  16. package/skills/sk:setup-claude/templates/tasks/workflow-status.md.template +25 -22
  17. package/skills/sk:setup-optimizer/SKILL.md +7 -5
  18. package/skills/sk:test/SKILL.md +17 -0
package/skills/sk:seo-audit/SKILL.md ADDED
@@ -0,0 +1,283 @@
1
+ ---
2
+ name: sk:seo-audit
3
+ description: "SEO audit for web projects. Dual-mode: scans source templates + optionally fetches from running dev server. Ask-before-fix for mechanical issues. Outputs checklist findings to tasks/seo-findings.md."
4
+ license: Complete terms in LICENSE.txt
5
+ ---
6
+
7
+ # /sk:seo-audit
8
+
9
+ ## Purpose
10
+
11
+ Standalone optional command — audits any web project for SEO issues regardless of framework (Laravel, Next.js, Nuxt, plain HTML, etc.). Run at any point after implementation is complete. NOT a numbered workflow step — invoke it independently like `/sk:debug`.
12
+
13
+ Two modes:
14
+ - **Source mode** (always runs): scans template files directly for SEO signals
15
+ - **Server mode** (optional): fetches from a running dev server to validate rendered output
16
+
17
+ Run when: before shipping a client site, after adding new pages, or any time you want to check SEO health.
18
+
19
+ ## Hard Rules
20
+
21
+ - **Never auto-apply fixes without explicit user confirmation.**
22
+ - **Every finding must cite a specific `file:line`.**
23
+ - **Every finding is a checkbox:** `- [ ]` (open) or `- [x]` (auto-fixed this run)
24
+ - **Append to `tasks/seo-findings.md`** — never overwrite (use date header per run)
25
+ - **Degrade gracefully** if no server is running — skip Phase 2, note it in report
26
+ - **Structured data validation requires external tools** (Google Rich Results Test) — flag it, don't skip silently
27
+
28
+ ## Before You Start
29
+
30
+ 1. Read `tasks/findings.md` if it exists — look for site context, target audience, business type (helps tailor content strategy recommendations)
31
+ 2. Read `tasks/lessons.md` if it exists — apply any SEO-related lessons
32
+ 3. Check if `tasks/seo-findings.md` exists — if yes, read the last dated section to identify previously flagged items (used to populate "Passed Checks" in the new report)
33
+
34
+ ## Mode Detection
35
+
36
+ ### Source Mode — Always Active
37
+
38
+ Scan the project for template files:
39
+
40
+ | Extension | Framework |
41
+ |-----------|-----------|
42
+ | `.blade.php` | Laravel |
43
+ | `.jsx`, `.tsx` | React / Next.js |
44
+ | `.vue` | Vue / Nuxt |
45
+ | `.html` | Plain HTML / static |
46
+ | `.ejs` | Express / Node |
47
+ | `.njk` | Nunjucks |
48
+ | `.twig` | Twig / Symfony |
49
+ | `.erb` | Ruby on Rails |
50
+ | `.astro` | Astro |
51
+
52
+ Print: `"Source mode: found N template files ([extensions detected])"`
53
+
54
+ ### Server Mode — Optional
55
+
56
+ Probe ports in parallel (background curl processes) to avoid 14-second worst-case serial timeout:
57
+ - Ports: 3000, 5173, 8000, 8080, 4321, 4000, 8888
58
+ - Command: `curl -s -I --max-time 2 http://localhost:PORT` (HEAD request to capture both status code and headers)
59
+ - Use the first port that returns HTTP 200 **and** has a `Content-Type: text/html` response header
60
+
61
+ If a port returns 200 but no `Content-Type: text/html` header, skip it — it is likely a non-HTTP service (e.g., a database, gRPC server) and not a web app. Try the next port.
62
+
63
+ If any port qualifies: `"Server mode: detected running dev server at http://localhost:PORT"`
64
+
65
+ If none respond or qualify: `"Server mode: no dev server detected — skipping Phase 2. Start your dev server and re-run for full audit."`
66
+
67
+ > Note: confirm the detected URL looks correct before trusting Phase 2 results.
68
+
69
+ ## Phase 1 — Source Audit
70
+
71
+ ### Technical SEO
72
+
73
+ - `robots.txt` — exists in project root or `public/`; does NOT contain `Disallow: /` blocking all crawlers
74
+ - `sitemap.xml` — exists in project root or `public/`; referenced in `robots.txt` via `Sitemap:` directive
75
+ - `<html lang="">` — present on all layout/root templates (not empty)
76
+ - Canonical tags — `<link rel="canonical">` present on key page templates
77
+ - No accidental `<meta name="robots" content="noindex">` on public-facing pages
78
+ - No hardcoded `http://` asset URLs in templates (mixed content risk)
79
+
80
+ ### On-Page SEO
81
+
82
+ - `<title>` — present in `<head>`, unique across pages, 50–60 characters
83
+ - `<meta name="description">` — present in `<head>`, unique across pages, 150–160 characters
84
+ - Exactly one `<h1>` per page template (not zero, not two+)
85
+ - Heading hierarchy not skipped (no jumping from `<h2>` to `<h4>`)
86
+ - All `<img>` tags have `alt` attribute (even if empty for decorative — but flag empty alt on non-decorative images)
87
+ - Internal `<a>` link text is descriptive — flag anchors with text: "click here", "here", "read more", "link", "this"
88
+ - Image filenames are descriptive — flag patterns like `img001`, `IMG_`, `photo`, `image`, `DSC_`, `screenshot` with no context
89
+
90
+ ### Content Signals
91
+
92
+ - Open Graph tags: `og:title`, `og:description`, `og:url`, `og:image` all present in layout
93
+ - Twitter Card tags: `twitter:card` present
94
+ - JSON-LD structured data block: look for `<script type="application/ld+json">` — note presence/absence; do NOT validate schema (requires external tool)
95
+ - Page `<html lang="">` matches expected locale
96
+
97
+ ## Phase 2 — Server Audit (Optional)
98
+
99
+ If server detected:
100
+
101
+ 1. Fetch `/` and discover up to 4 additional pages (from `<a>` href values in homepage, or from sitemap.xml)
102
+ 2. For each page fetched, extract and compare:
103
+ - Rendered `<title>` vs source template value
104
+ - Rendered `<meta name="description">` vs source template value
105
+ - Rendered `<h1>` vs source template value
106
+ - Rendered OG tags vs source template
107
+ 3. Flag mismatches: `"/about — Source template declares <title>About Us</title> but rendered output shows <title>My App</title> — framework may be overriding"`
108
+ 4. Check HTTP status codes — flag any key page returning non-200
109
+ 5. Check for redirect chains on common pages (/ → /home → /index is a chain)
110
+
111
+ > Note in report: "Structured data detected but NOT validated — use Google Rich Results Test (https://search.google.com/test/rich-results) to verify schema markup."
112
+
113
+ ## Phase 3 — Ask Before Fix
114
+
115
+ After completing Phase 1 (and Phase 2 if run):
116
+
117
+ 1. Collect all auto-fixable findings (see Mechanical Fixes Reference below)
118
+ 2. Display numbered list:
119
+
120
+ ```
121
+ Found N auto-fixable issues:
122
+ 1. Missing <title> in resources/views/layouts/app.blade.php
123
+ 2. Missing alt attribute on <img> in resources/views/home.blade.php:42
124
+ 3. Missing robots.txt
125
+ ... (all N items)
126
+
127
+ Apply mechanical fixes? [y/N]
128
+ ```
129
+
130
+ 3. Wait for user response
131
+ 4. On `y`: apply each fix in order, log `"Fixed: [description] in [file:line]"`, mark as `- [x]` in report. On individual fix failure: log the error, mark that item `- [ ]`, and continue with remaining fixes.
132
+ 5. On `n`: mark all as `- [ ]` in report with Fix instructions
133
+
134
+ ## Mechanical Fixes Reference
135
+
136
+ What this skill CAN auto-apply when user confirms:
137
+
138
+ | Issue | Fix Applied |
139
+ |-------|------------|
140
+ | Missing `<title>` in `<head>` | Add `<title>TODO: Add page title (50-60 chars)</title>` |
141
+ | Missing `<meta name="description">` | Add `<meta name="description" content="TODO: Add description (150-160 chars)">` |
142
+ | `<img>` missing `alt` attribute | Add `alt="TODO: Describe this image for screen readers"` |
143
+ | Missing `<link rel="canonical">` | Add `<link rel="canonical" href="TODO: Add canonical URL">` |
144
+ | Missing `robots.txt` | Create `robots.txt`: `User-agent: *\nAllow: /\nSitemap: /sitemap.xml` |
145
+ | Missing `sitemap.xml` | Create `sitemap.xml` scaffold with homepage entry |
146
+ | Multiple `<h1>` on same page | Demote 2nd, 3rd... `<h1>` to `<h2>` |
147
+ | Missing OG tags | Add `og:title`, `og:description`, `og:url` block (with TODO placeholders) |
148
+ | Missing `<html lang="">` | Add `lang="en"` — **note in output: verify correct language code** |
149
+
150
+ Things this skill CANNOT auto-apply (report only):
151
+ - Content quality improvements
152
+ - Keyword targeting
153
+ - Title/description CONTENT (only adds TODOs)
154
+ - Schema markup content (only flags missing)
155
+ - Backlink strategy
156
+ - `<meta name="robots" content="noindex">` removal — only the developer can confirm whether a page is intentionally noindexed
157
+
158
+ ## Generate Report
159
+
160
+ Write to `tasks/seo-findings.md` — append with date header, never overwrite.
161
+
162
+ ```markdown
163
+ # SEO Audit — YYYY-MM-DD
164
+
165
+ **Mode:** Source only | Source + Server (`http://localhost:PORT`)
166
+ **Templates scanned:** N files ([detected extensions])
167
+ **Pages fetched:** N | none — server not detected
168
+
169
+ ---
170
+
171
+ ## Critical
172
+
173
+ - [x] `resources/views/layouts/app.blade.php` — Missing `<title>` tag *(auto-fixed — add real title)*
174
+ - [ ] `resources/views/about.blade.php:1` — Missing `<meta name="description">`
175
+ **Impact:** Google may auto-generate a description from page content, often poorly.
176
+ **Fix:** Add `<meta name="description" content="150-160 char description">` in `<head>`
177
+
178
+ ## High
179
+
180
+ - [ ] `public/robots.txt` — File missing
181
+ **Impact:** Search engines have no crawl guidance — may index unwanted pages.
182
+ **Fix:** Create `robots.txt` with `User-agent: *`, `Allow: /`, `Sitemap:` directive
183
+
184
+ ## Medium
185
+
186
+ - [ ] `resources/views/home.blade.php:42` — `<img src="hero.jpg">` missing alt attribute
187
+ **Impact:** Accessibility violation + missed keyword opportunity.
188
+ **Fix:** Add descriptive `alt="..."` text
189
+
190
+ ## Low
191
+
192
+ - [ ] Image filename `IMG_4521.jpg` — not descriptive
193
+ **Impact:** Minor missed keyword signal.
194
+ **Fix:** Rename to describe the image content
195
+
196
+ ## Content Strategy — Manual Action
197
+
198
+ - [ ] No JSON-LD structured data detected — consider adding schema markup (Article / Product / LocalBusiness / FAQPage) based on your content type. Validate at: https://search.google.com/test/rich-results
199
+ - [ ] `og:image` missing — social shares will have no preview image. Add a default OG image in your layout.
200
+ - [ ] Submit `sitemap.xml` to Google Search Console for faster indexing
201
+ - [ ] Title tags are present but content is generic ("TODO") — research target keywords for each page
202
+
203
+ ## Passed Checks
204
+
205
+ - `robots.txt` exists and allows crawling *(was: missing — fixed in 2026-03-10 audit)*
206
+ - All `<img>` tags have alt attributes
207
+ - Single `<h1>` per page
208
+
209
+ (or "First run — no prior baseline to compare against")
210
+
211
+ ## Applied Fixes
212
+
213
+ - Fixed: Added `<title>` placeholder to `resources/views/layouts/app.blade.php`
214
+ - Fixed: Created `public/robots.txt`
215
+
216
+ (or "No fixes applied this run")
217
+
218
+ ---
219
+
220
+ ## Summary
221
+
222
+ | Severity | Open | Fixed this run |
223
+ |----------|------|----------------|
224
+ | Critical | 1 | 1 |
225
+ | High | 1 | 0 |
226
+ | Medium | 3 | 0 |
227
+ | Low | 2 | 0 |
228
+ | Content Strategy | 4 | — |
229
+ | **Total** | **11** | **1** |
230
+ ```
231
+
232
+ **Never overwrite** `tasks/seo-findings.md` — append new audits with a date header.
233
+
234
+ ## When Done
235
+
236
+ If Critical or High items are open:
237
+ > "SEO audit complete. **N critical/high issues** need attention before this site will rank well. Findings and checklist in `tasks/seo-findings.md`."
238
+
239
+ If only Medium/Low/Content Strategy open:
240
+ > "Technical SEO is solid. **N medium/low polish items** and **N content strategy items** noted in `tasks/seo-findings.md`. Check off items as you address them."
241
+
242
+ If all clean:
243
+ > "SEO audit passed — no issues found. `tasks/seo-findings.md` updated with clean baseline."
244
+
245
+ If fixes were declined (`n`):
246
+ > "SEO audit complete. **N auto-fixable issues** left open (fixes declined). Checklist in `tasks/seo-findings.md` — check off items as you manually address them."
247
+
248
+ ---
249
+
250
+ ## Fix & Retest Protocol
251
+
252
+ When applying an SEO fix, classify it before committing:
253
+
254
+ **a. Template/config change** (adding a meta tag, fixing alt text, scaffolding robots.txt, adding lang attribute, creating sitemap.xml) → commit and re-run `/sk:seo-audit`. No test update needed.
255
+
256
+ **b. Logic change** (changing how a framework generates meta tags, modifying a layout component's data-fetching or rendering logic, changing routing that affects canonical URLs) → trigger protocol:
257
+ 1. Update or add failing unit tests for the new behavior
258
+ 2. Re-run `/sk:test` — must pass at 100% coverage
259
+ 3. Commit (tests + fix together in one commit)
260
+ 4. Re-run `/sk:seo-audit` to verify the fix resolved the finding
261
+
262
+ **Common logic-change SEO fixes:**
263
+ - Changing a Next.js `generateMetadata()` function → update tests asserting metadata output
264
+ - Modifying a Laravel controller that sets page title → update feature tests
265
+ - Changing a Vue component that injects `<head>` tags → update component tests
266
+
267
+ ---
268
+
269
+ ## Model Routing
270
+
271
+ Read `.shipkit/config.json` from the project root if it exists.
272
+
273
+ - If `model_overrides["sk:seo-audit"]` is set, use that model — it takes precedence.
274
+ - Otherwise use the `profile` field. Default: `balanced`.
275
+
276
+ | Profile | Model |
277
+ |---------|-------|
278
+ | `full-sail` | sonnet |
279
+ | `quality` | sonnet |
280
+ | `balanced` | sonnet |
281
+ | `budget` | haiku |
282
+
283
+ > `opus` = inherit (uses the current session model). When spawning sub-agents via the Agent tool, pass `model: "<resolved-model>"`.
package/skills/sk:setup-claude/templates/CLAUDE.md.template CHANGED
@@ -34,7 +34,7 @@
34
34
  ## Workflow — Follow This Order
35
35
  <!-- LOCK -->
36
36
 
37
- **Flow:** Read → Explore → Design → Accessibility → Plan → Branch → Migrate → Write Tests → Implement → Lint → Verify Tests → Security → Performance → Review → Finish
37
+ **Flow:** Read → Explore → Design → Accessibility → Plan → Branch → Migrate → Write Tests → Implement → Lint → Verify Tests → Security → Performance → Review → E2E Tests → Finish → Sync Features
38
38
 
39
39
  Progress is tracked in `tasks/workflow-status.md`. This file persists across conversations.
40
40
 
@@ -42,55 +42,61 @@ Progress is tracked in `tasks/workflow-status.md`. This file persists across con
42
42
  |---|------|---------|------|-------|
43
43
  | 1 | Read Todo | read `tasks/todo.md` | required | no |
44
44
  | 2 | Read Lessons | read `tasks/lessons.md` | required | no |
45
- | 3 | Explore | `/brainstorm` | required | no |
46
- | 4 | Design | `/frontend-design` or `/api-design` | optional (confirm to skip) | no |
47
- | 5 | Accessibility | `/accessibility` | optional (confirm to skip) | no |
48
- | 6 | Plan | `/write-plan` | required | no |
49
- | 7 | Branch | `/branch` | required | no |
50
- | 8 | Migrate | `/schema-migrate` | optional (confirm to skip) | no |
51
- | 9 | Write Tests | `/write-tests` | required | no |
52
- | 10 | Implement | `/execute-plan` | required | no |
53
- | 11 | Commit | `/smart-commit` | required | no |
54
- | 12 | Lint | `/lint` | required | yes — must be clean |
55
- | 13 | Commit | `/smart-commit` | conditional (skip if lint was clean) | no |
56
- | 14 | Verify Tests | `/test` | required | yes — 100% coverage required |
57
- | 15 | Commit | `/smart-commit` | conditional (skip if tests passed clean) | no |
58
- | 16 | Security | `/security-check` | required | yes — must reach 0 issues |
59
- | 17 | Commit | `/smart-commit` | conditional (skip if security was clean) | no |
60
- | 18 | Performance | `/perf` | optional (confirm to skip) | yes — loop until critical/high = 0 |
61
- | 19 | Commit | `/smart-commit` | conditional (skip if perf was clean) | no |
62
- | 20 | Review | `/review` | required | yes — must reach 0 issues |
63
- | 21 | Commit | `/smart-commit` | conditional (skip if review was clean) | no |
64
- | 22 | Update | `/update-task` | required | no |
65
- | 23 | Finalize | `/finish-feature` | required | no |
66
- | 24 | Release | `/release` | optional (confirm to skip) | no |
45
+ | 3 | Explore | `/sk:brainstorm` | required | no |
46
+ | 4 | Design | `/sk:frontend-design` or `/sk:api-design` | optional (confirm to skip) | no |
47
+ | 5 | Accessibility | `/sk:accessibility` | optional (confirm to skip) | no |
48
+ | 6 | Plan | `/sk:write-plan` | required | no |
49
+ | 7 | Branch | `/sk:branch` | required | no |
50
+ | 8 | Migrate | `/sk:schema-migrate` | optional (confirm to skip) | no |
51
+ | 9 | Write Tests | `/sk:write-tests` | required | no |
52
+ | 10 | Implement | `/sk:execute-plan` | required | no |
53
+ | 11 | Commit | `/sk:smart-commit` | required | no |
54
+ | 12 | Lint + Dep Audit | `/sk:lint` | required | yes — must be clean |
55
+ | 13 | Commit | `/sk:smart-commit` | conditional (skip if lint was clean) | no |
56
+ | 14 | Verify Tests | `/sk:test` | required | yes — 100% coverage required |
57
+ | 15 | Commit | `/sk:smart-commit` | conditional (skip if tests passed clean) | no |
58
+ | 16 | Security | `/sk:security-check` | required | yes — must reach 0 issues |
59
+ | 17 | Commit | `/sk:smart-commit` | conditional (skip if security was clean) | no |
60
+ | 18 | Performance | `/sk:perf` | optional (confirm to skip) | yes — loop until critical/high = 0 |
61
+ | 19 | Commit | `/sk:smart-commit` | conditional (skip if perf was clean) | no |
62
+ | 20 | Review + Simplify | `/sk:review` | required | yes — must reach 0 issues |
63
+ | 21 | Commit | `/sk:smart-commit` | conditional (skip if review was clean) | no |
64
+ | 22 | E2E Tests | `/sk:e2e` | required | yes — all scenarios must pass |
65
+ | 23 | Commit | `/sk:smart-commit` | conditional (skip if E2E was clean) | no |
66
+ | 24 | Update | `/sk:update-task` | required | no |
67
+ | 25 | Finalize | `/sk:finish-feature` | required | no |
68
+ | 26 | Sync Features | `/sk:features` | required | no |
69
+ | 27 | Release | `/sk:release` | optional (confirm to skip) | no |
67
70
 
68
71
  ### Step Details
69
72
 
70
73
  1. **Read** `tasks/todo.md` — pick the next incomplete task
71
74
  2. **Read** `tasks/lessons.md` — review past corrections before writing code
72
- 3. **Explore** — run `/brainstorm` to clarify requirements, constraints, and approach. No code in this step.
73
- 4. **Design** — run `/frontend-design` for UI mockup or `/api-design` for API contracts. No code — design only. Skip if pure backend with no UI and no new API. After the design summary, the skill asks if you want a Pencil visual mockup — answer `y` only if you have the Pencil app open and Pencil MCP connected. Use `/frontend-design --pencil` to jump directly to the Pencil phase.
74
- 5. **Accessibility** — run `/accessibility` to audit the design spec for WCAG 2.1 AA compliance. Produces `tasks/accessibility-findings.md`. Skip if backend-only with no frontend.
75
- 6. **Plan** — run `/write-plan` to write a decision-complete plan into `tasks/todo.md` using brainstorm + design outputs. No code in this step.
76
- 7. **Branch** — run `/branch` to create a feature branch auto-named from the current task.
77
- 8. **Migrate** — run `/schema-migrate` for database changes. Skip if no schema changes needed.
78
- 9. **Write Tests** — run `/write-tests` (TDD red phase). Write failing tests for all planned code. If modifying existing behavior, update existing tests first. Tests SHOULD fail — no implementation yet.
79
- 10. **Implement** — run `/execute-plan` to execute `tasks/todo.md` checkboxes in small batches, making the failing tests pass (TDD green phase). Log progress to `tasks/progress.md`.
80
- 11. **Commit** — run `/smart-commit` to commit tests + implementation
81
- 12. **Lint** — run `/lint` — auto-detects and runs all project linters. Fix all issues immediately, then re-run until clean. Do not ask to re-run — fix and re-run automatically.
82
- 13. **Commit** — run `/smart-commit` if lint required fixes. Auto-skip if lint was clean.
83
- 14. **Verify Tests** — run `/test` — auto-detects and runs all project test suites. **100% test coverage required.** Fix failures immediately, then re-run. Do not ask to re-run — fix and re-run automatically.
84
- 15. **Commit** — run `/smart-commit` if test fixes were needed. Auto-skip if tests passed first try.
85
- 16. **Security** — run `/security-check`. Must reach 0 issues across all severities. Fix issues immediately, commit, then re-run. Loop until clean.
86
- 17. **Commit** — run `/smart-commit` if security required fixes. Auto-skip if clean.
87
- 18. **Performance** — run `/perf` to audit for performance issues. Produces `tasks/perf-findings.md`. Fix critical/high findings, commit, then re-run. Loop until critical/high = 0. Skip if confirmed with user.
88
- 19. **Commit** — run `/smart-commit` if perf required fixes. Auto-skip if clean.
89
- 20. **Review** — run `/review`. Must reach 0 issues including nitpicks. Fix issues immediately, commit, then re-run. Loop until clean.
90
- 21. **Commit** — run `/smart-commit` if review required fixes. Auto-skip if clean.
91
- 22. **Update** — run `/update-task` to mark the task done in `tasks/todo.md` and log completion to `tasks/progress.md`.
92
- 23. **Finalize** — run `/finish-feature` for changelog + PR
93
- 24. **Release** — run `/release` if deploying. Skip if not ready.
75
+ 3. **Explore** — run `/sk:brainstorm` to clarify requirements, constraints, and approach. No code in this step.
76
+ 4. **Design** — run `/sk:frontend-design` for UI mockup or `/sk:api-design` for API contracts. No code — design only. Skip if pure backend with no UI and no new API. After the design summary, the skill asks if you want a Pencil visual mockup — answer `y` only if you have the Pencil app open and Pencil MCP connected. Use `/sk:frontend-design --pencil` to jump directly to the Pencil phase.
77
+ 5. **Accessibility** — run `/sk:accessibility` to audit the design spec for WCAG 2.1 AA compliance. Produces `tasks/accessibility-findings.md`. Skip if backend-only with no frontend.
78
+ 6. **Plan** — run `/sk:write-plan` to write a decision-complete plan into `tasks/todo.md` using brainstorm + design outputs. No code in this step.
79
+ 7. **Branch** — run `/sk:branch` to create a feature branch auto-named from the current task.
80
+ 8. **Migrate** — run `/sk:schema-migrate` for database changes. Skip if no schema changes needed.
81
+ 9. **Write Tests** — run `/sk:write-tests` (TDD red phase). Write failing tests for all planned code. If modifying existing behavior, update existing tests first. Tests SHOULD fail — no implementation yet.
82
+ 10. **Implement** — run `/sk:execute-plan` to execute `tasks/todo.md` checkboxes in small batches, making the failing tests pass (TDD green phase). Log progress to `tasks/progress.md`.
83
+ 11. **Commit** — run `/sk:smart-commit` to commit tests + implementation
84
+ 12. **Lint + Dep Audit** — run `/sk:lint` — auto-detects and runs all project linters plus dependency vulnerability audits. Fix all issues immediately, then re-run until clean. Do not ask to re-run — fix and re-run automatically.
85
+ 13. **Commit** — run `/sk:smart-commit` if lint required fixes. Auto-skip if lint was clean.
86
+ 14. **Verify Tests** — run `/sk:test` — auto-detects and runs all project test suites. **100% test coverage required.** Fix failures immediately, then re-run. Do not ask to re-run — fix and re-run automatically.
87
+ 15. **Commit** — run `/sk:smart-commit` if test fixes were needed. Auto-skip if tests passed first try.
88
+ 16. **Security** — run `/sk:security-check`. Must reach 0 issues across all severities. Fix issues immediately, commit, then re-run. Loop until clean.
89
+ 17. **Commit** — run `/sk:smart-commit` if security required fixes. Auto-skip if clean.
90
+ 18. **Performance** — run `/sk:perf` to audit for performance issues. Produces `tasks/perf-findings.md`. Fix critical/high findings, commit, then re-run. Loop until critical/high = 0. Skip if confirmed with user.
91
+ 19. **Commit** — run `/sk:smart-commit` if perf required fixes. Auto-skip if clean.
92
+ 20. **Review + Simplify** — run `/sk:review`. First runs a simplify pre-pass on changed files, then performs full multi-dimensional review. Must reach 0 issues including nitpicks. Fix issues immediately, commit, then re-run. Loop until clean.
93
+ 21. **Commit** — run `/sk:smart-commit` if review required fixes. Auto-skip if clean.
94
+ 22. **E2E Tests** — run `/sk:e2e`. Verifies the complete, reviewed, secure implementation works end-to-end from a user's perspective using agent-browser. All scenarios must pass. Cannot be skipped.
95
+ 23. **Commit** — run `/sk:smart-commit` if E2E required fixes. Auto-skip if E2E was clean.
96
+ 24. **Update** — run `/sk:update-task` to mark the task done in `tasks/todo.md` and log completion to `tasks/progress.md`.
97
+ 25. **Finalize** — run `/sk:finish-feature` for changelog + PR
98
+ 26. **Sync Features** — run `/sk:features` to sync `docs/sk:features/` specs with what was actually shipped.
99
+ 27. **Release** — run `/sk:release` if deploying. Skip if not ready.
94
100
 
95
101
  ### Workflow Tracker Rules
96
102
 
@@ -103,21 +109,22 @@ Progress is tracked in `tasks/workflow-status.md`. This file persists across con
103
109
  - Add relevant Notes (e.g., "clean on attempt 2", "backend-only, no UI")
104
110
  - Move `>> next <<` to the next pending step
105
111
 
106
- 3. **Optional steps** (4, 5, 7, 18, 24): Ask the user "Skip [step]?" and require explicit confirmation. Record the reason in Notes.
112
+ 3. **Optional steps** (4, 5, 8, 18, 27): Ask the user "Skip [step]?" and require explicit confirmation. Record the reason in Notes.
107
113
 
108
- 4. **Conditional commits** (13, 15, 17, 19, 21): Auto-skip if no changes were made. Record reason (e.g., "lint was clean", "tests passed first try").
114
+ 4. **Conditional commits** (13, 15, 17, 19, 21, 23): Auto-skip if no changes were made. Record reason (e.g., "lint was clean", "tests passed first try").
109
115
 
110
- 5. **Loop steps are HARD GATES** (12, 14, 16, 20): These steps BLOCK all forward progress until they pass clean. Fix issues immediately and re-run. Do NOT ask the user to re-run — fix and re-run automatically. Track attempt number in Notes (e.g., "clean on attempt 3").
116
+ 5. **Loop steps are HARD GATES** (12, 14, 16, 20, 22): These steps BLOCK all forward progress until they pass clean. Fix issues immediately and re-run. Do NOT ask the user to re-run — fix and re-run automatically. Track attempt number in Notes (e.g., "clean on attempt 3").
111
117
  - **Step 12 (Lint)**: All detected linting tools must pass — every single one.
112
118
  - **Step 14 (Verify Tests)**: All detected test suites (BE + FE) must pass with 100% coverage on new code.
113
119
  - **Step 16 (Security)**: 0 issues across all severities.
114
120
  - **Step 20 (Review)**: 0 issues including nitpicks.
121
+ - **Step 22 (E2E Tests)**: All scenarios must pass. 0 failures allowed.
115
122
  - **Step 18 (Performance)**: Optional gate — if run, loop until critical/high findings = 0. Can be skipped with explicit confirmation.
116
123
  - **DO NOT mark these steps as `done` until every check passes.** If even one tool fails, the step is NOT done. Never proceed to the next step with errors remaining.
117
124
 
118
- 6. **Never skip steps without confirmation.** Steps cannot run out of order. Hard gate steps (12, 14, 16, 20) can NEVER be skipped. Optional gate step (18) requires explicit confirmation to skip.
125
+ 6. **Never skip steps without confirmation.** Steps cannot run out of order. Hard gate steps (12, 14, 16, 20, 22) can NEVER be skipped. Optional gate step (18) requires explicit confirmation to skip.
119
126
 
120
- 7. **Requirements change mid-workflow?** Stop the current step and run `/change` immediately. It will classify the scope (behavior tweak / new requirements / scope shift) and tell you exactly where to re-enter the workflow. Never continue implementing stale requirements.
127
+ 7. **Requirements change mid-workflow?** Stop the current step and run `/sk:change` immediately. It will classify the scope (behavior tweak / new requirements / scope shift) and tell you exactly where to re-enter the workflow. Never continue implementing stale requirements.
121
128
 
122
129
  7. **Never auto-advance.** When one step completes, stop and tell the user which step is next. Do not proceed automatically.
123
130
 
@@ -133,6 +140,22 @@ Next step: [#] [Name] — run `[command]`
133
140
 
134
141
  This tells the user exactly what happened and what to do next. Never finish a step silently.
135
142
 
143
+ ### Fix & Retest Protocol
144
+
145
+ **Applies to steps 12, 14, 16, 18, 20, 22 — any step that can produce code changes.**
146
+
147
+ When any of these steps require a fix, classify the fix before committing:
148
+
149
+ **a. Format/style/config/wording change** → commit and re-run the gate. No test update needed.
150
+
151
+ **b. Logic change** (new branch, modified condition, new data path, query change, new function, changed algorithm, API change) → trigger protocol:
152
+ 1. Update or add failing unit tests for the new behavior
153
+ 2. Re-run `/sk:test` — must pass at 100% coverage
154
+ 3. Commit (tests + fix together in one commit)
155
+ 4. Re-run the current gate from scratch
156
+
157
+ **Exception:** Lint formatter auto-fixes (Prettier, Pint, gofmt, cargo fmt) are never logic changes — bypass protocol automatically.
158
+
136
159
  ### Tracker Reset
137
160
 
138
161
  - When starting a new task, check if `tasks/workflow-status.md` has any `done` or `skipped` steps. If yes, ask: "Existing workflow detected. Start fresh and reset tracker?"
@@ -140,52 +163,65 @@ This tells the user exactly what happened and what to do next. Never finish a st
140
163
 
141
164
  ### Bug Fix Flow
142
165
 
143
- When fixing a bug (not building a feature), use `/debug` as the entry point. This sets up a shorter workflow:
166
+ When fixing a bug (not building a feature), use `/sk:debug` as the entry point. This sets up a shorter workflow:
144
167
 
145
168
  | # | Step | Command |
146
169
  |---|------|---------|
147
- | 1 | Debug | `/debug` |
148
- | 2 | Branch | `/branch` |
149
- | 3 | Write Tests | `/write-tests` (regression test) |
170
+ | 1 | Debug | `/sk:debug` |
171
+ | 2 | Branch | `/sk:branch` |
172
+ | 3 | Write Tests | `/sk:write-tests` (regression test) |
150
173
  | 4 | Fix | implement the fix |
151
- | 5 | Commit | `/smart-commit` |
152
- | 6 | Lint | `/lint` |
153
- | 7 | Commit | `/smart-commit` (skip if clean) |
154
- | 8 | Verify Tests | `/test` |
155
- | 9 | Commit | `/smart-commit` (skip if clean) |
156
- | 10 | Security | `/security-check` |
157
- | 11 | Commit | `/smart-commit` (skip if clean) |
158
- | 12 | Review | `/review` |
159
- | 13 | Commit | `/smart-commit` (skip if clean) |
160
- | 14 | Update | `/update-task` |
161
- | 15 | Finalize | `/finish-feature` |
162
-
163
- Start with `/debug` to investigate, then follow the abbreviated flow.
174
+ | 5 | Commit | `/sk:smart-commit` |
175
+ | 6 | Lint | `/sk:lint` |
176
+ | 7 | Commit | `/sk:smart-commit` (skip if clean) |
177
+ | 8 | Verify Tests | `/sk:test` |
178
+ | 9 | Commit | `/sk:smart-commit` (skip if clean) |
179
+ | 10 | Security | `/sk:security-check` |
180
+ | 11 | Commit | `/sk:smart-commit` (skip if clean) |
181
+ | 12 | Review | `/sk:review` |
182
+ | 13 | Commit | `/sk:smart-commit` (skip if clean) |
183
+ | 14 | Update | `/sk:update-task` |
184
+ | 15 | Finalize | `/sk:finish-feature` |
185
+
186
+ Start with `/sk:debug` to investigate, then follow the abbreviated flow.
164
187
 
165
188
  ### Hotfix Flow
166
189
 
167
- For production emergencies that need to ship immediately, use `/hotfix`. Skips brainstorm, design, and write-tests. Quality gates still apply.
190
+ For production emergencies that need to ship immediately, use `/sk:hotfix`. Skips brainstorm, design, and write-tests. Quality gates still apply.
168
191
 
169
192
  | # | Step | Command |
170
193
  |---|------|---------|
171
- | 1 | Investigate | `/debug` |
172
- | 2 | Branch | `/branch` |
194
+ | 1 | Investigate | `/sk:debug` |
195
+ | 2 | Branch | `/sk:branch` |
173
196
  | 3 | Fix | implement directly |
174
197
  | 4 | Smoke Test | run existing tests |
175
- | 5 | Commit | `/smart-commit` |
176
- | 6 | Lint | `/lint` |
177
- | 7 | Commit | `/smart-commit` (skip if clean) |
178
- | 8 | Verify Tests | `/test` |
179
- | 9 | Commit | `/smart-commit` (skip if clean) |
180
- | 10 | Security | `/security-check` |
181
- | 11 | Commit | `/smart-commit` (skip if clean) |
182
- | 12 | Review | `/review` |
183
- | 13 | Commit | `/smart-commit` (skip if clean) |
184
- | 14 | Update | `/update-task` |
185
- | 15 | Finalize | `/finish-feature` |
198
+ | 5 | Commit | `/sk:smart-commit` |
199
+ | 6 | Lint | `/sk:lint` |
200
+ | 7 | Commit | `/sk:smart-commit` (skip if clean) |
201
+ | 8 | Verify Tests | `/sk:test` |
202
+ | 9 | Commit | `/sk:smart-commit` (skip if clean) |
203
+ | 10 | Security | `/sk:security-check` |
204
+ | 11 | Commit | `/sk:smart-commit` (skip if clean) |
205
+ | 12 | Review | `/sk:review` |
206
+ | 13 | Commit | `/sk:smart-commit` (skip if clean) |
207
+ | 14 | Update | `/sk:update-task` |
208
+ | 15 | Finalize | `/sk:finish-feature` |
186
209
 
187
210
  After merging: add a regression test and a lessons.md entry.
188
211
 
212
+ ### Requirement Change Flow
213
+
214
+ When requirements change mid-workflow, run `/sk:change` to avoid implementing the wrong behavior:
215
+
216
+ | # | Step | Command |
217
+ |---|------|---------|
218
+ | 1 | Assess | `/sk:change` — classify scope (Tier 1/2/3) |
219
+ | 2 | Tier 1 (test update only) | update tests → re-enter at step 9 |
220
+ | 3 | Tier 2 (plan revision) | revise plan → re-enter at step 6 |
221
+ | 4 | Tier 3 (re-brainstorm) | re-enter at step 3 |
222
+
223
+ Never update tests or implementation based on a changed requirement without going through `/sk:change` first.
224
+
189
225
  ## Sub-Agent Patterns
190
226
  <!-- BEGIN:sub-agent-patterns -->
191
227
 
@@ -281,9 +317,9 @@ Tests are written **before** implementation (step 9) and verified **after** (ste
281
317
 
282
318
  ### TDD Flow
283
319
 
284
- 1. `/write-tests` — write failing tests based on the plan (RED)
285
- 2. `/execute-plan` — implement code to make tests pass (GREEN)
286
- 3. `/test` — verify all tests pass with 100% coverage (VERIFY)
320
+ 1. `/sk:write-tests` — write failing tests based on the plan (RED)
321
+ 2. `/sk:execute-plan` — implement code to make tests pass (GREEN)
322
+ 3. `/sk:test` — verify all tests pass with 100% coverage (VERIFY)
287
323
 
288
324
  Every new function, endpoint, component, and module needs tests. No code proceeds past step 13 without 100% coverage on new code.
289
325
 
@@ -299,3 +335,32 @@ Never retry the same failing approach.
299
335
  ## Architectural Change Log
300
336
 
301
337
  Create entries in: `[ARCH_CHANGELOG_DIR]`
338
+
339
+ ## Commands
340
+
341
+ | Command | Purpose |
342
+ |---------|---------|
343
+ | `/sk:brainstorm` | Explore requirements and design |
344
+ | `/sk:frontend-design` | UI mockup before implementation. Prompts to create Pencil visual mockup |
345
+ | `/sk:api-design` | Design API contracts (endpoints, payloads, auth, errors) before implementation |
346
+ | `/sk:accessibility` | WCAG 2.1 AA audit — runs after design, before implementation |
347
+ | `/sk:write-plan` | Write decision-complete plan into `tasks/todo.md` |
348
+ | `/sk:branch` | Create feature branch auto-named from current task |
349
+ | `/sk:write-tests` | TDD: Write failing tests before implementation |
350
+ | `/sk:execute-plan` | Execute `tasks/todo.md` checkboxes in batches |
351
+ | `/sk:smart-commit` | Conventional commit with approval |
352
+ | `/sk:lint` | Auto-detect and run all project linters + dependency audits |
353
+ | `/sk:test` | Auto-detect and run all project test suites |
354
+ | `/sk:debug` | Investigate and debug issues (bug fix entry point) |
355
+ | `/sk:security-check` | OWASP security audit on changed files |
356
+ | `/sk:perf` | Performance audit — bundle, N+1, Core Web Vitals, memory |
357
+ | `/sk:review` | Self-review with simplify pre-pass + multi-dimensional review |
358
+ | `/sk:e2e` | E2E behavioral verification using agent-browser (final quality gate) |
359
+ | `/sk:hotfix` | Emergency fix workflow — skip design/TDD, quality gates enforced |
360
+ | `/sk:change` | Handle mid-workflow requirement changes — re-enter at correct step |
361
+ | `/sk:update-task` | Mark task done and log completion |
362
+ | `/sk:finish-feature` | Changelog + PR creation |
363
+ | `/sk:features` | Sync feature specs with shipped implementation |
364
+ | `/sk:release` | Version bump + changelog + tag |
365
+ | `/sk:status` | Show workflow + task status |
366
+ | `/sk:setup-optimizer` | Diagnose + update workflow + enrich CLAUDE.md |
package/skills/sk:setup-claude/templates/commands/brainstorm.md.template CHANGED
@@ -6,14 +6,14 @@ description: "Start with design questions before writing code."
6
6
 
7
7
  # /brainstorm
8
8
 
9
- **Workflow:** Read → **Explore** → Design → Accessibility → Plan → Branch → Migrate → Write Tests → Implement → Lint → Verify Tests → Security → Performance → Review → Finalize → Release
9
+ **Workflow:** Read → **Explore** → Design → Accessibility → Plan → Branch → Migrate → Write Tests → Implement → Lint → Verify Tests → Security → Performance → Review → E2E Tests → Finish → Sync Features
10
10
 
11
11
  Explore design and clarify requirements **before** any code is written.
12
12
 
13
13
  ## Hard Rules
14
14
 
15
15
  - **DO NOT write, edit, or generate any code.** No files, no snippets, no pseudo-implementations.
16
- - **DO NOT create a plan.** That is `/write-plan`'s job.
16
+ - **DO NOT create a plan.** That is `/sk:write-plan`'s job.
17
17
  - **DO NOT run build/test/lint commands.** You are in design mode only.
18
18
  - You may **read** existing code to understand the current state, but nothing more.
19
19
 
@@ -65,10 +65,10 @@ Explore design and clarify requirements **before** any code is written.
65
65
 
66
66
  ## When Done
67
67
 
68
- 1. Update `tasks/workflow-status.md`: set step 1 (`/brainstorm`) to `done`, move `>> next <<` to the next pending step.
68
+ 1. Update `tasks/workflow-status.md`: set step 1 (`/sk:brainstorm`) to `done`, move `>> next <<` to the next pending step.
69
69
  2. Print the full workflow status dashboard table.
70
70
  3. Tell the user:
71
71
  > "Brainstorming complete. Findings saved to `tasks/findings.md`."
72
- 4. If step 2 (`/frontend-design`) is next, ask: "Step 2 is `/frontend-design` (optional). Run it or skip?"
72
+ 4. If step 2 (`/sk:frontend-design`) is next, ask: "Step 2 is `/sk:frontend-design` (optional). Run it or skip?"
73
73
 
74
74
  **Do not proceed to planning or implementation yourself.** The user must explicitly invoke the next step.
package/skills/sk:setup-claude/templates/commands/execute-plan.md.template CHANGED
@@ -6,7 +6,7 @@ description: "Execute tasks/todo.md checkboxes in small batches; log to tasks/pr
6
6
 
7
7
  # /execute-plan
8
8
 
9
- **Workflow:** Read → Explore → Design → Accessibility → Plan → Branch → Migrate → Write Tests → **Implement** → Lint → Verify Tests → Security → Performance → Review → Finalize → Release
9
+ **Workflow:** Read → Explore → Design → Accessibility → Plan → Branch → Migrate → Write Tests → **Implement** → Lint → Verify Tests → Security → Performance → Review → E2E Tests → Finish → Sync Features
10
10
 
11
11
  Execute the plan in `tasks/todo.md` in small batches with clear checkpoints.
12
12
 
@@ -33,7 +33,7 @@ Execute the plan in `tasks/todo.md` in small batches with clear checkpoints.
33
33
  - verification results
34
34
  - what's next
35
35
  - After all items in this batch pass verification, the code is ready to stage.
36
- Run `/commit` after any passed batch, or accumulate and commit at plan completion.
36
+ Run `/sk:smart-commit` after any passed batch, or accumulate and commit at plan completion.
37
37
  Never combine more than one logical unit of work in a single commit.
38
38
  4. Stop and wait for user feedback before continuing.
39
39