@kennethsolomon/shipkit 3.19.0 → 3.20.0

package/skills/sk:seo-audit/SKILL.md

@@ -11,34 +11,32 @@ agent: general-purpose
 
 ## Purpose
 
-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`.
+Standalone optional command — audits any web project for SEO issues (Laravel, Next.js, Nuxt, plain HTML, etc.). Run independently like `/sk:debug`, not a numbered workflow step.
 
 Two modes:
-- **Source mode** (always runs): scans template files directly for SEO signals
-- **Server mode** (optional): fetches from a running dev server to validate rendered output
-
-Run when: before shipping a client site, after adding new pages, or any time you want to check SEO health.
+- **Source mode** (always): scans template files directly
+- **Server mode** (optional): fetches from running dev server to validate rendered output
 
 ## Hard Rules
 
-- **Never auto-apply fixes without explicit user confirmation.**
-- **Every finding must cite a specific `file:line`.**
-- **Every finding is a checkbox:** `- [ ]` (open) or `- [x]` (auto-fixed this run)
-- **Append to `tasks/seo-findings.md`** — never overwrite (use date header per run)
-- **Degrade gracefully** if no server is running — skip Phase 2, note it in report
-- **Structured data validation requires external tools** (Google Rich Results Test) — flag it, don't skip silently
+- Never auto-apply fixes without explicit user confirmation.
+- Every finding must cite a specific `file:line`.
+- Every finding is a checkbox: `- [ ]` (open) or `- [x]` (auto-fixed this run).
+- Append to `tasks/seo-findings.md` with date header — never overwrite.
+- Degrade gracefully if no server running — skip Phase 2, note in report.
+- Structured data validation requires external tools (Google Rich Results Test) — flag it, don't skip silently.
 
 ## Before You Start
 
-1. Read `tasks/findings.md` if it exists — look for site context, target audience, business type (helps tailor content strategy recommendations)
-2. Read `tasks/lessons.md` if it exists — apply any SEO-related lessons
-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)
+1. Read `tasks/findings.md` if exists — look for site context, target audience, business type.
+2. Read `tasks/lessons.md` if exists — apply any SEO-related lessons.
+3. Check `tasks/seo-findings.md` if exists — read last dated section to populate "Passed Checks".
 
 ## Mode Detection
 
 ### Source Mode — Always Active
 
-Scan the project for template files:
+Scan for template files:
 
 | Extension | Framework |
 |-----------|-----------|
@@ -56,68 +54,62 @@ Print: `"Source mode: found N template files ([extensions detected])"`
 
 ### Server Mode — Optional
 
-Probe ports in parallel (background curl processes) to avoid 14-second worst-case serial timeout:
-- Ports: 3000, 5173, 8000, 8080, 4321, 4000, 8888
-- Command: `curl -s -I --max-time 2 http://localhost:PORT` (HEAD request to capture both status code and headers)
-- Use the first port that returns HTTP 200 **and** has a `Content-Type: text/html` response header
+Probe ports in parallel (background curl): `curl -s -I --max-time 2 http://localhost:PORT`
 
-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.
+Ports: 3000, 5173, 8000, 8080, 4321, 4000, 8888
 
-If any port qualifies: `"Server mode: detected running dev server at http://localhost:PORT"`
+Use first port returning HTTP 200 **and** `Content-Type: text/html` header. Skip ports without `text/html` (may be DB, gRPC, etc.).
 
-If none respond or qualify: `"Server mode: no dev server detected — skipping Phase 2. Start your dev server and re-run for full audit."`
+- Qualifies: `"Server mode: detected running dev server at http://localhost:PORT"`
+- None qualify: `"Server mode: no dev server detected — skipping Phase 2. Start your dev server and re-run for full audit."`
 
-> Note: confirm the detected URL looks correct before trusting Phase 2 results.
+Confirm detected URL looks correct before trusting Phase 2 results.
 
 ## Phase 1 — Source Audit
 
 ### Technical SEO
 
-- `robots.txt` — exists in project root or `public/`; does NOT contain `Disallow: /` blocking all crawlers
+- `robots.txt` — exists in project root or `public/`; does NOT contain `Disallow: /`
 - `sitemap.xml` — exists in project root or `public/`; referenced in `robots.txt` via `Sitemap:` directive
-- `<html lang="">` — present on all layout/root templates (not empty)
+- `<html lang="">` — present and non-empty on all layout/root templates
 - Canonical tags — `<link rel="canonical">` present on key page templates
 - No accidental `<meta name="robots" content="noindex">` on public-facing pages
-- No hardcoded `http://` asset URLs in templates (mixed content risk)
+- No hardcoded `http://` asset URLs (mixed content risk)
 
 ### On-Page SEO
 
-- `<title>` — present in `<head>`, unique across pages, 50–60 characters
-- `<meta name="description">` — present in `<head>`, unique across pages, 150–160 characters
-- Exactly one `<h1>` per page template (not zero, not two+)
+- `<title>` — present in `<head>`, unique across pages, 50–60 chars
+- `<meta name="description">` — present in `<head>`, unique across pages, 150–160 chars
+- Exactly one `<h1>` per page template
 - Heading hierarchy not skipped (no jumping from `<h2>` to `<h4>`)
-- All `<img>` tags have `alt` attribute (even if empty for decorative — but flag empty alt on non-decorative images)
-- Internal `<a>` link text is descriptive — flag anchors with text: "click here", "here", "read more", "link", "this"
-- Image filenames are descriptive — flag patterns like `img001`, `IMG_`, `photo`, `image`, `DSC_`, `screenshot` with no context
+- All `<img>` tags have `alt` attribute — flag empty alt on non-decorative images
+- Internal `<a>` link text is descriptive — flag: "click here", "here", "read more", "link", "this"
+- Image filenames are descriptive — flag: `img001`, `IMG_`, `photo`, `image`, `DSC_`, `screenshot` with no context
 
 ### Content Signals
 
-- Open Graph tags: `og:title`, `og:description`, `og:url`, `og:image` all present in layout
-- Twitter Card tags: `twitter:card` present
-- JSON-LD structured data block: look for `<script type="application/ld+json">` — note presence/absence; do NOT validate schema (requires external tool)
-- Page `<html lang="">` matches expected locale
+- OG tags: `og:title`, `og:description`, `og:url`, `og:image` all present in layout
+- Twitter Card: `twitter:card` present
+- JSON-LD: look for `<script type="application/ld+json">` — note presence/absence; do NOT validate schema
+- `<html lang="">` matches expected locale
 
 ## Phase 2 — Server Audit (Optional)
 
 If server detected:
 
-1. Fetch `/` and discover up to 4 additional pages (from `<a>` href values in homepage, or from sitemap.xml)
-2. For each page fetched, extract and compare:
-   - Rendered `<title>` vs source template value
-   - Rendered `<meta name="description">` vs source template value
-   - Rendered `<h1>` vs source template value
-   - Rendered OG tags vs source template
-3. Flag mismatches: `"/about — Source template declares <title>About Us</title> but rendered output shows <title>My App</title> — framework may be overriding"`
-4. Check HTTP status codes — flag any key page returning non-200
-5. Check for redirect chains on common pages (/ → /home → /index is a chain)
+1. Fetch `/` and discover up to 4 additional pages (from `<a>` hrefs or sitemap.xml).
+2. For each page, compare rendered vs source template: `<title>`, `<meta name="description">`, `<h1>`, OG tags.
+3. Flag mismatches: `"/about — Source template declares X but rendered output shows Y — framework may be overriding"`
+4. Check HTTP status codes — flag any key page returning non-200.
+5. Check for redirect chains (e.g., / → /home → /index).
 
-> 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."
+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."
 
 ## Phase 3 — Ask Before Fix
 
-After completing Phase 1 (and Phase 2 if run):
+After Phase 1 (and Phase 2 if run):
 
-1. Collect all auto-fixable findings (see Mechanical Fixes Reference below)
+1. Collect all auto-fixable findings.
 2. Display numbered list:
 
 ```
@@ -130,37 +122,33 @@ Found N auto-fixable issues:
 Apply mechanical fixes? [y/N]
 ```
 
-3. Wait for user response
-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.
-5. On `n`: mark all as `- [ ]` in report with Fix instructions
+3. Wait for user response.
+4. On `y`: apply each fix, log `"Fixed: [description] in [file:line]"`, mark `- [x]`. On failure: log error, mark `- [ ]`, continue.
+5. On `n`: mark all `- [ ]` with fix instructions.
 
 ## Mechanical Fixes Reference
 
-What this skill CAN auto-apply when user confirms:
+**Can auto-apply (with confirmation):**
 
 | Issue | Fix Applied |
 |-------|------------|
-| Missing `<title>` in `<head>` | Add `<title>TODO: Add page title (50-60 chars)</title>` |
+| Missing `<title>` | Add `<title>TODO: Add page title (50-60 chars)</title>` |
 | Missing `<meta name="description">` | Add `<meta name="description" content="TODO: Add description (150-160 chars)">` |
-| `<img>` missing `alt` attribute | Add `alt="TODO: Describe this image for screen readers"` |
+| `<img>` missing `alt` | Add `alt="TODO: Describe this image for screen readers"` |
 | Missing `<link rel="canonical">` | Add `<link rel="canonical" href="TODO: Add canonical URL">` |
 | Missing `robots.txt` | Create `robots.txt`: `User-agent: *\nAllow: /\nSitemap: /sitemap.xml` |
-| Missing `sitemap.xml` | Create `sitemap.xml` scaffold with homepage entry |
-| Multiple `<h1>` on same page | Demote 2nd, 3rd... `<h1>` to `<h2>` |
-| Missing OG tags | Add `og:title`, `og:description`, `og:url` block (with TODO placeholders) |
-| Missing `<html lang="">` | Add `lang="en"` — **note in output: verify correct language code** |
-
-Things this skill CANNOT auto-apply (report only):
-- Content quality improvements
-- Keyword targeting
-- Title/description CONTENT (only adds TODOs)
-- Schema markup content (only flags missing)
-- Backlink strategy
-- `<meta name="robots" content="noindex">` removal — only the developer can confirm whether a page is intentionally noindexed
+| Missing `sitemap.xml` | Create scaffold with homepage entry |
+| Multiple `<h1>` | Demote 2nd, 3rd... `<h1>` to `<h2>` |
+| Missing OG tags | Add `og:title`, `og:description`, `og:url` block (TODO placeholders) |
+| Missing `<html lang="">` | Add `lang="en"` — note: verify correct language code |
+
+**Cannot auto-apply (report only):**
+- Content quality, keyword targeting, title/description content, schema markup content, backlink strategy
+- `<meta name="robots" content="noindex">` removal — developer must confirm intentional noindex
 
 ## Generate Report
 
-Write to `tasks/seo-findings.md` — append with date header, never overwrite.
+Append to `tasks/seo-findings.md` with date header. Never overwrite.
 
 ```markdown
 # SEO Audit — YYYY-MM-DD
@@ -198,10 +186,10 @@ Write to `tasks/seo-findings.md` — append with date header, never overwrite.
 
 ## Content Strategy — Manual Action
 
-- [ ] 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
-- [ ] `og:image` missing — social shares will have no preview image. Add a default OG image in your layout.
+- [ ] No JSON-LD structured data detected — consider adding schema markup (Article / Product / LocalBusiness / FAQPage). Validate at: https://search.google.com/test/rich-results
+- [ ] `og:image` missing — social shares will have no preview image. Add a default OG image in layout.
 - [ ] Submit `sitemap.xml` to Google Search Console for faster indexing
-- [ ] Title tags are present but content is generic ("TODO") — research target keywords for each page
+- [ ] Title tags present but content is generic ("TODO") — research target keywords per page
 
 ## Passed Checks
 
@@ -232,49 +220,40 @@ Write to `tasks/seo-findings.md` — append with date header, never overwrite.
 | **Total** | **11** | **1** |
 ```
 
-**Never overwrite** `tasks/seo-findings.md` — append new audits with a date header.
-
 ## When Done
 
-If Critical or High items are open:
-> "SEO audit complete. **N critical/high issues** need attention before this site will rank well. Findings and checklist in `tasks/seo-findings.md`."
-
-If only Medium/Low/Content Strategy open:
-> "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."
-
-If all clean:
-> "SEO audit passed — no issues found. `tasks/seo-findings.md` updated with clean baseline."
-
-If fixes were declined (`n`):
-> "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."
+- Critical or High open: `"SEO audit complete. N critical/high issues need attention before this site will rank well. Findings in tasks/seo-findings.md."`
+- Only Medium/Low/Content Strategy open: `"Technical SEO is solid. N medium/low polish items and N content strategy items noted in tasks/seo-findings.md."`
+- All clean: `"SEO audit passed — no issues found. tasks/seo-findings.md updated with clean baseline."`
+- Fixes declined: `"SEO audit complete. N auto-fixable issues left open (fixes declined). Checklist in tasks/seo-findings.md."`
 
 ---
 
 ## Fix & Retest Protocol
 
-When applying an SEO fix, classify it before committing:
+Classify each SEO fix before committing:
 
-**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.
+**a. Template/config change** (adding meta tag, fixing alt text, scaffolding robots.txt, adding lang, creating sitemap.xml) → commit and re-run `/sk:seo-audit`. No test update needed.
 
-**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:
-1. Update or add failing unit tests for the new behavior
+**b. Logic change** (changing how framework generates meta tags, modifying layout data-fetching/rendering, changing routing affecting canonical URLs):
+1. Update or add failing unit tests for new behavior
 2. Re-run `/sk:test` — must pass at 100% coverage
-3. Commit (tests + fix together in one commit)
-4. Re-run `/sk:seo-audit` to verify the fix resolved the finding
+3. Commit tests + fix together
+4. Re-run `/sk:seo-audit` to verify fix resolved the finding
 
-**Common logic-change SEO fixes:**
+Common logic-change examples:
 - Changing a Next.js `generateMetadata()` function → update tests asserting metadata output
-- Modifying a Laravel controller that sets page title → update feature tests
-- Changing a Vue component that injects `<head>` tags → update component tests
+- Modifying a Laravel controller setting page title → update feature tests
+- Changing a Vue component injecting `<head>` tags → update component tests
 
 ---
 
 ## Model Routing
 
-Read `.shipkit/config.json` from the project root if it exists.
+Read `.shipkit/config.json` from project root if it exists.
 
-- If `model_overrides["sk:seo-audit"]` is set, use that model — it takes precedence.
-- Otherwise use the `profile` field. Default: `balanced`.
+- If `model_overrides["sk:seo-audit"]` is set, use that model — takes precedence.
+- Otherwise use `profile` field. Default: `balanced`.
 
 | Profile | Model |
 |---------|-------|
@@ -283,4 +262,4 @@ Read `.shipkit/config.json` from the project root if it exists.
 | `balanced` | sonnet |
 | `budget` | haiku |
 
-> `opus` = inherit (uses the current session model). When spawning sub-agents via the Agent tool, pass `model: "<resolved-model>"`.
+When spawning sub-agents via the Agent tool, pass `model: "<resolved-model>"`.

package/skills/sk:setup-claude/SKILL.md

@@ -124,6 +124,109 @@ On **first-time setup** (no existing `CLAUDE.md` or `tasks/findings.md`), run a
 
 Skip this phase on re-runs (when `tasks/findings.md` already contains "Reconnaissance").
 
+## Phase 0.5: Stack Detection + Project-Level Skill Installation
+
+After reconnaissance, detect the project stack and install only relevant skills, agents, and rules at the project level.
+
+**Reference:** Read `${CLAUDE_SKILL_DIR}/references/skill-profiles.md` for the full categorization matrix.
+
+### Step 1: Detect Stack
+
+Scan project root for stack indicators (in priority order):
+
+| Priority | Signal | Stack | Capabilities |
+|----------|--------|-------|-------------|
+| 1 | `composer.json` + `laravel/framework` | laravel | web, database, api |
+| 2 | `package.json` + `next` | nextjs | web |
+| 3 | `package.json` + `nuxt` | nuxt | web |
+| 4 | `package.json` + `react` (no next) | react | web |
+| 5 | `package.json` + `vue` (no nuxt) | vue | web |
+| 6 | `app.json` or `app.config.ts` | expo | mobile |
+| 7 | `react-native.config.js` | react-native | mobile |
+| 8 | `pubspec.yaml` | flutter | mobile |
+| 9 | `package.json` + `express` | express | api |
+| 10 | `go.mod` | go | api |
+| 11 | `Cargo.toml` | rust | api |
+| 12 | `pyproject.toml` / `requirements.txt` | python | api |
+| 13 | `Gemfile` + `rails` | rails | web, database, api |
+
+Sub-detect database capability (within any stack):
+- `prisma/schema.prisma` → add `database` capability
+- `drizzle.config.ts` / `.js` → add `database` capability
+- `database/migrations/` (Laravel) → add `database` capability
+- `alembic/` → add `database` capability
+- `db/migrate/` (Rails) → add `database` capability
+
+Display result and allow override:
+```
+Detected: [stack] — capabilities: [web, database, api]
+[N] skills, [N] agents, [N] rules will be installed.
+Override? (enter to accept, or type capabilities to add/remove)
+```
+
+### Step 2: Write Config
+
+Write detection results to `.shipkit/config.json` (merge additively, preserve existing fields like `profile`):
+
+```json
+{
+  "stack": {
+    "detected": "<stack>",
+    "detected_at": "<YYYY-MM-DD>",
+    "capabilities": ["web", "database"]
+  },
+  "skills": {
+    "extra": [],
+    "disabled": []
+  }
+}
+```
+
+### Step 3: Install Project-Level Skills
+
+Using the categorization from `skill-profiles.md`, determine the install set:
+
+```
+installed = universal_skills + capability_add_ons(capabilities) + extra - disabled - mobile_exclusions
+```
+
+Copy matching skills from `~/.claude/skills/` to `.claude/skills/` in the project:
+- Only copy skill directories that match the install set
+- Skip skills that already exist in the project's `.claude/skills/`
+- If a skill exists in project but is NOT in the install set and NOT in `extra`, leave it (don't remove on first setup — only `setup-optimizer` removes)
+
+### Step 4: Install Project-Level Agents + Rules
+
+**Agents** — copy from `~/.claude/agents/` to `.claude/agents/` in the project:
+
+| Stack | Agents to install |
+|-------|------------------|
+| all | architect, qa-engineer, debugger, code-reviewer, security-reviewer, performance-optimizer, refactor-specialist, tech-writer, devops-engineer |
+| laravel, express, go, python, rust, rails | + backend-dev |
+| react, nextjs, vue, nuxt, svelte | + frontend-dev |
+| expo, react-native, flutter | + mobile-dev |
+| any with `database` capability | + database-architect |
+
+**Rules** — copy from `~/.claude/rules/` to `.claude/rules/` in the project:
+
+| Stack | Rules to install |
+|-------|-----------------|
+| all | tests.md, api.md |
+| laravel | + laravel.md |
+| react, nextjs | + react.md |
+| vue, nuxt | + vue.md |
+| any with `database` capability | + migrations.md |
+
+### Step 5: Generate CLAUDE.md Commands Table
+
+When generating CLAUDE.md, the Commands table should only list installed skills (not all 44+). Read the installed skills from `.claude/skills/` in the project and generate the table dynamically.
+
+Display installation summary:
+```
+Installed: [N] skills, [N] agents, [N] rules for [stack] stack.
+[M] opt-in skills available (activate via .shipkit/config.json "extra" field).
+```
+
 ## Generation Inputs
 
 This skill detects:

package/skills/sk:setup-claude/references/skill-profiles.md

@@ -0,0 +1,201 @@
+# ShipKit Skill Profiles — Stack-Based Filtering
+
+**Last Updated:** 2026-03-29
+**Total Skills:** 44 | **Agents:** 13 | **Rules:** 6
+
+This file is the source of truth for which skills, agents, and rules get installed per project. Read by `sk:setup-claude` (initial setup) and `sk:setup-optimizer` (ongoing sync).
+
+---
+
+## Universal Skills (always installed — 25 skills)
+
+| Skill | Purpose |
+|-------|---------|
+| sk:start | Smart entry point — classifies task, routes to workflow |
+| sk:context | Load project context + session brief |
+| sk:brainstorming | Explore requirements before implementation |
+| sk:write-plan | Decision-complete plan into todo.md |
+| sk:execute-plan | Implement tasks in batches with progress logging |
+| sk:write-tests | TDD: write failing tests before implementation |
+| sk:test | Run all test suites, verify 100% coverage |
+| sk:lint | Auto-detect and run all linters |
+| sk:debug | Structured bug investigation |
+| sk:review | 7-dimension self-review |
+| sk:smart-commit | Conventional commit with approval |
+| sk:gates | All quality gates in parallel batches |
+| sk:safety-guard | Protect against destructive operations |
+| sk:scope-check | Detect scope creep vs plan |
+| sk:save-session | Save session state for continuity |
+| sk:resume-session | Restore previously saved session |
+| sk:learn | Extract reusable patterns from session |
+| sk:retro | Post-ship retrospective |
+| sk:health | Harness self-audit scorecard |
+| sk:context-budget | Audit context window token consumption |
+| sk:setup-claude | Bootstrap project scaffolding |
+| sk:setup-optimizer | Diagnose + update workflow + enrich CLAUDE.md |
+| sk:release | Version bump + changelog + tag |
+| sk:fast-track | Abbreviated workflow for small changes |
+| sk:skill-creator | Create or modify skills |
+
+---
+
+## Stack-Specific Skills
+
+### Laravel (+4 skills)
+
+| Skill | Purpose |
+|-------|---------|
+| sk:laravel-new | Scaffold fresh Laravel app |
+| sk:laravel-init | Configure existing Laravel project |
+| sk:laravel-deploy | Deploy to Laravel Cloud |
+| sk:schema-migrate | Multi-ORM schema change analysis |
+
+### Web (+5 skills)
+
+| Skill | Purpose |
+|-------|---------|
+| sk:frontend-design | UI mockup before implementation |
+| sk:accessibility | WCAG 2.1 AA audit |
+| sk:seo-audit | SEO audit (source + dev server) |
+| sk:website | Build multi-page marketing website |
+| sk:mvp | Generate MVP with landing page + app |
+
+### Database (+1 skill)
+
+| Skill | Purpose |
+|-------|---------|
+| sk:schema-migrate | Multi-ORM schema change analysis |
+
+### API (+2 skills)
+
+| Skill | Purpose |
+|-------|---------|
+| sk:api-design | Design API contracts before implementation |
+| sk:team | Parallel domain agents (BE + FE + QA) |
+
+### Mobile (exclude from web)
+
+No additional skills. **Exclude:** sk:e2e (Playwright), sk:seo-audit, sk:accessibility, sk:website.
+
+---
+
+## Opt-In Skills (manual activation only — 8 skills)
+
+| Skill | Purpose | When to activate |
+|-------|---------|-----------------|
+| sk:autopilot | Hands-free workflow, all 8 steps | Well-defined tasks, minimal steering |
+| sk:eval | Run evaluations for agent reliability | Eval-driven development |
+| sk:ci | Set up GitHub Actions or GitLab CI | First-time CI setup |
+| sk:reverse-doc | Generate docs from existing code | Onboarding, formalizing prototypes |
+| sk:features | Sync feature specs with implementation | Feature spec maintenance |
+| sk:e2e | E2E behavioral verification | Web projects with Playwright/Cypress |
+| sk:dashboard | Workflow Kanban board (localhost) | Multi-worktree progress tracking |
+| sk:plugin | Package skills as distributable plugin | Team skill sharing |
+
+---
+
+## Quality Gate Skills (part of sk:gates — always installed)
+
+| Skill | Gate role |
+|-------|----------|
+| sk:perf | Performance audit |
+| sk:security-check | OWASP security audit |
+
+These are installed universally because they run inside `sk:gates`. Perf auto-skips if no frontend+DB keywords. Security always runs.
+
+---
+
+## Stack Detection Rules
+
+| Priority | Signal | Detected Stack | Capabilities |
+|----------|--------|---------------|-------------|
+| 1 | `composer.json` + `laravel/framework` | laravel | web, database, api |
+| 2 | `package.json` + `next` | nextjs | web |
+| 3 | `package.json` + `nuxt` | nuxt | web |
+| 4 | `package.json` + `react` (no next) | react | web |
+| 5 | `package.json` + `vue` (no nuxt) | vue | web |
+| 6 | `package.json` + `svelte` | svelte | web |
+| 7 | `app.json` or `app.config.ts` | expo | mobile |
+| 8 | `react-native.config.js` | react-native | mobile |
+| 9 | `pubspec.yaml` | flutter | mobile |
+| 10 | `package.json` + `express` | express | api |
+| 11 | `go.mod` | go | api |
+| 12 | `Cargo.toml` | rust | api |
+| 13 | `pyproject.toml` / `requirements.txt` | python | api |
+| 14 | `Gemfile` + `rails` | rails | web, database, api |
+
+### Capability → Add-on mapping
+
+| Capability | Add-on skills |
+|-----------|---------------|
+| web | sk:frontend-design, sk:accessibility, sk:seo-audit, sk:website, sk:mvp |
+| database | sk:schema-migrate |
+| api | sk:api-design, sk:team |
+| laravel | sk:laravel-new, sk:laravel-init, sk:laravel-deploy |
+| mobile | Exclude: sk:e2e, sk:seo-audit, sk:accessibility, sk:website |
+
+### Database sub-detection (within any stack)
+
+| Signal | ORM |
+|--------|-----|
+| `prisma/schema.prisma` | Prisma → add `database` capability |
+| `drizzle.config.ts` / `.js` | Drizzle → add `database` capability |
+| `database/migrations/` (Laravel) | Laravel migrations → add `database` capability |
+| `alembic/` | SQLAlchemy → add `database` capability |
+| `db/migrate/` (Rails) | Rails migrations → add `database` capability |
+
+---
+
+## Agent → Stack Mapping
+
+| Agent | Stacks | Notes |
+|-------|--------|-------|
+| architect | all | System design, universal |
+| backend-dev | laravel, express, go, python, rust, rails | Backend implementation |
+| frontend-dev | react, nextjs, vue, nuxt, svelte | Frontend implementation |
+| mobile-dev | expo, react-native, flutter | Mobile-specific |
+| database-architect | any with `database` capability | Schema design, migrations |
+| qa-engineer | all | E2E test scenarios, universal |
+| debugger | all | Bug investigation, universal |
+| code-reviewer | all | Code quality review, universal |
+| security-reviewer | all | OWASP audit, universal |
+| performance-optimizer | all | Performance analysis, universal |
+| refactor-specialist | all | Safe refactoring, universal |
+| tech-writer | all | Documentation, universal |
+| devops-engineer | all | CI/CD, deployment, universal |
+
+---
+
+## Rule → Stack Mapping
+
+| Rule | Applies to stacks | Path patterns |
+|------|------------------|---------------|
+| tests.md | all | `tests/**`, `**/*.test.*`, `**/*.spec.*` |
+| api.md | laravel, express, go, python, rails | `routes/api.php`, `**/controllers/**`, `src/api/**` |
+| laravel.md | laravel | `app/**/*.php`, `routes/**`, `config/**` |
+| react.md | react, nextjs | `**/*.{tsx,jsx}`, `resources/js/**` |
+| vue.md | vue, nuxt | `**/*.vue`, `resources/js/**` |
+| migrations.md | any with `database` capability | `database/migrations/**`, `prisma/**`, `db/migrate/**` |
+
+---
+
+## Installation Formula
+
+For a given project with detected `stack` and `capabilities`:
+
+```
+installed_skills = universal_skills
+                 + capability_add_ons(capabilities)
+                 + config.skills.extra
+                 - config.skills.disabled
+                 - mobile_exclusions (if mobile stack)
+
+installed_agents = universal_agents
+                 + stack_specific_agents(stack)
+                 - agents not matching any detected stack
+
+installed_rules  = universal_rules (tests.md)
+                 + stack_matching_rules(stack, capabilities)
+```
+
+User overrides (`extra`, `disabled`) are never touched by auto-detection.