@kensaurus/skills 0.0.0-stage → 2.1.0

package/skills/mushi-health/SKILL.md

@@ -0,0 +1,206 @@
+---
+name: mushi-health
+description: >-
+  Pass/fail health check across every Mushi Mushi pipeline component — CLI
+  credentials, API reachability, edge functions, BYOK key pool, QA cron.
+  Use when "is mushi working", "mushi health check", "check mushi pipeline",
+  "mushi deploy check", "pipeline not responding", or right after setup.
+license: MIT
+disable-model-invocation: true
+effort: low
+---
+
+# Mushi Health Check
+
+**Degree of freedom: MIXED.** First-red diagnosis `[HIGH freedom]`;
+Steps 1–6 in order `[LOW freedom — run exactly]`.
+
+## How to reason
+
+1. **Observe** — `doctor`, `deploy check`, keys, logs, cron — in that order
+2. **Interpret** — first red is root vs downstream symptom
+3. **Classify** — creds / functions-down / keys / logs / cron-missing
+4. **Severity** — paused project or invalid API key outranks a quiet QA cron on a new project
+
+## Worked example
+
+> **Observe:** `mushi doctor` green; `mushi deploy check` ✗ `qa-story-runner`; `qa_story_runs` empty for 2h.
+> **Interpret:** first red is the runner; empty cron is downstream.
+> **Classify:** function-down — check `query_logs` for `qa-story-runner`; do not add keys yet.
+> **Verify:** stop at Step 2; fix the runner; continue remaining steps only after it is green.
+
+## Self-critique before reporting
+
+- **In order** — did not skip ahead of the first ❌
+- **Evidence** — each row cites command output or a query, not memory
+- **Stopped to fix** — first red was remediated before later steps
+- **Right owner** — e2e loop proof → `mushi-integration`; targeted diagnosis → `diagnose_setup`
+
+Run these checks in order. Stop and fix at the first ❌ before continuing.
+
+## Component map
+
+| # | Component | How to check |
+|---|-----------|-------------|
+| 1 | CLI credentials | `mushi doctor` |
+| 2 | API + edge functions | `mushi deploy check` |
+| 3 | Project overview | `mushi status` |
+| 4 | BYOK key pool | `mushi keys list` or MCP `list_byok_keys` |
+| 5 | Supabase logs | Supabase MCP `query_logs` |
+| 6 | QA cron running | DB query on `qa_story_runs` |
+
+---
+
+## Step 1 — CLI credentials  [LOW freedom — run exactly]
+
+```bash
+mushi doctor
+```
+
+Expected output — all lines green:
+
+```
+✓  ~/.mushirc found
+✓  MUSHI_API_KEY valid (mushi_...)
+✓  MUSHI_API_ENDPOINT reachable (200 OK)
+✓  MUSHI_PROJECT_ID matches a live project
+✓  Feature flags fetched
+```
+
+**Fix if red:** Re-run `mushi login --api-key mushi_... --endpoint https://<ref>.supabase.co/functions/v1/api --project-id <pid>`.
+
+---
+
+## Step 2 — API + edge functions  [LOW freedom — run exactly]
+
+```bash
+mushi deploy check
+```
+
+Probes each edge function with a lightweight ping. Healthy output:
+
+```
+✓  api
+✓  classify-report
+✓  fix-worker
+✓  story-mapper
+✓  test-gen-from-story   # Mushi edge function, not a pack skill
+✓  pdca-runner
+✓  qa-story-runner
+```
+
+A `✗` on any line means that function is down. Check its logs in Step 5.
+
+---
+
+## Step 3 — Project overview  [LOW freedom — run exactly]
+
+```bash
+mushi status
+```
+
+Confirm:
+- Report count is non-zero (or expected zero for a brand-new project).
+- `autofix_agent` shows the expected agent (`cursor_cloud`, `mcp`, etc.).
+- No `billing: quota_exceeded` warning.
+
+---
+
+## Step 4 — BYOK key pool  [LOW freedom — run exactly]
+
+Via CLI:
+
+```bash
+mushi keys list
+```
+
+Via MCP (if the Mushi MCP server is active in Cursor):
+
+```
+list_byok_keys(projectId)
+```
+
+**Healthy:** at least one `anthropic` key with `status=active`, at least one `firecrawl` key with `status=active`.
+
+**Fix:** Add a missing or exhausted key:
+
+```bash
+mushi keys add --provider anthropic --key sk-ant-... --label "primary" --priority 100
+mushi keys add --provider firecrawl --key fc-...   --label "primary" --priority 100
+```
+
+---
+
+## Step 5 — Supabase edge function logs  [LOW freedom — run exactly]
+
+Use the Supabase MCP (requires `SUPABASE_ACCESS_TOKEN` in MCP config):
+
+```
+query_logs(sql: "select timestamp, log_attributes['function_id'] as function_id, log_attributes['level'] as level, event_message from logs where source = 'function_logs' order by timestamp desc limit 100", iso_timestamp_start: "<ISO 8601, 15 min ago>")
+```
+
+`function_logs` holds console output from inside each function;
+`function_edge_logs` holds the invocations and their status codes.
+`function_id` is the `id` that `list_edge_functions` returns for each slug.
+Look for `ERROR` lines in the last 15 minutes, especially from these
+**Mushi edge functions** (not pack skills):
+- `story-mapper` — Firecrawl timeout or Claude quota
+- `test-gen-from-story` — LLM key exhausted
+- `pdca-runner` — failed PDCA cycle
+- `qa-story-runner` — Browserbase quota or Firecrawl error
+
+If the Supabase MCP is not wired in Cursor, use the CLI:
+
+```bash
+supabase functions logs story-mapper --project-ref <ref>
+supabase functions logs qa-story-runner --project-ref <ref>
+```
+
+---
+
+## Step 6 — QA cron running  [LOW freedom — run exactly]
+
+Verify scheduled tests are executing (requires Supabase MCP):
+
+```sql
+SELECT status, COUNT(*) 
+FROM qa_story_runs 
+WHERE created_at > NOW() - INTERVAL '2 hours'
+GROUP BY status;
+```
+
+**Healthy output:** at least one `completed` row in the last 2 hours (if you have enabled stories).
+
+If `qa_story_runs` is empty:
+1. Confirm at least one story has `enabled = true` and `approval_status = 'approved'`.
+2. Confirm the pg_cron job is registered: `SELECT jobname, schedule FROM cron.job WHERE jobname LIKE 'qa%';`
+3. Manually trigger: `mushi tdd run <qa-story-id>` and re-check.
+
+---
+
+## Pass/Fail Summary Template  [LOW freedom — do not skip]
+
+After running all steps, record results:
+
+| Component | Status | Notes |
+|-----------|--------|-------|
+| CLI credentials | ✅ / ❌ | |
+| Edge functions | ✅ / ❌ | Which ones failed? |
+| Project overview | ✅ / ❌ | Billing ok? |
+| BYOK key pool | ✅ / ❌ | Missing providers? |
+| Supabase logs | ✅ / ❌ | Any ERRORs? |
+| QA cron | ✅ / ❌ | Last run at? |
+
+If all ✅ → pipeline is healthy.  
+If any ❌ → run the mushi MCP `diagnose_setup` tool for targeted diagnosis.
+
+---
+
+## Common causes of all-red  [HIGH freedom]
+
+| Symptom | Likely cause | Fix |
+|---------|-------------|-----|
+| `mushi doctor` can't reach endpoint | Wrong `MUSHI_API_ENDPOINT` in `~/.mushirc` | Re-run `mushi login --endpoint https://...` |
+| All edge functions ❌ | Supabase project paused (free tier) | Restore the project in the Supabase dashboard |
+| BYOK keys all `quota_exhausted` | Rate limits hit on all keys | Add a backup key for each provider |
+| QA cron never fires | pg_cron job missing | Re-run migration `20260602000003_pdca_qa_improve_cron.sql` |

package/skills/mushi-integration/SKILL.md

@@ -0,0 +1,257 @@
+---
+name: mushi-integration
+description: >-
+  Full end-to-end Mushi Mushi integration smoke test: bug capture → AI triage
+  → story mapping → TDD test generation → approval → execution → PDCA cycle.
+  Use when "test mushi integration", "verify full pipeline", "mushi e2e check",
+  "does mushi work end-to-end", "smoke test mushi", or after deploying changes.
+license: MIT
+disable-model-invocation: true
+effort: low
+---
+
+# Mushi Integration Smoke Test
+
+**Degree of freedom: MIXED.** Pass/fail judgment `[HIGH freedom]`;
+Stages 1–6 probes and DB verifies `[LOW freedom — run exactly]`.
+
+## How to reason
+
+1. **Observe** — each stage's CLI output and DB row
+2. **Interpret** — stage failed vs still-pending vs expected-failure (test detected friction)
+3. **Classify** — capture / triage / map / gen / run / pdca
+4. **Severity** — `classify-report` down outranks optional Stage 7 dashboard drift
+
+## Worked example
+
+> **Observe:** `mushi test` → `rep_…`; DB still `pending` at 70s; `mushi doctor` was green.
+> **Interpret:** capture wrote; `classify-report` did not.
+> **Classify:** Stage 2 fail — check `query_logs`; do not start story mapping.
+> **Verify:** summary marks Stage 2 ❌; later stages skipped; `diagnose_setup` next.
+
+## Self-critique before reporting
+
+- **Health first** — `mushi doctor` green before Stage 1
+- **DB verify** — each stage checked the row, not only CLI text
+- **Expected fail ok** — Stage 5 `failed` still counts if the test executed
+- **Right owner** — component down → `mushi-health`; targeted diagnosis → `diagnose_setup`
+
+Exercises every stage of the Mushi pipeline end-to-end. Run after setup,
+after a deploy, or any time you need proof that the whole loop works.
+
+## Prerequisites  [LOW freedom — run exactly]
+
+- `mushi doctor` passes (all green) — run [`mushi-health`](../mushi-health/SKILL.md) first if unsure.
+- At least one BYOK key for `anthropic` and `firecrawl` is active.
+- You have the app URL you want to map stories from.
+
+---
+
+## Stage 1 — Bug capture  [LOW freedom — run exactly]
+
+Send a real test report through the SDK pipeline:
+
+```bash
+mushi test
+```
+
+Expected: `Test report submitted — id: rep_...`
+
+**Verify in DB** (Supabase MCP):
+
+```sql
+SELECT id, status, severity, category, created_at
+FROM reports
+ORDER BY created_at DESC LIMIT 1;
+```
+
+Expected: a row with `status` = `classified` and a non-null `severity` within ~30 seconds.  
+If still `pending` after 60 s: `classify-report` edge function failed — check its console output with `query_logs` on `source = 'function_logs'`.
+
+---
+
+## Stage 2 — AI triage  [LOW freedom — run exactly]
+
+Confirm the classifier ran:
+
+```bash
+mushi reports list --limit 1
+```
+
+Expected output includes `severity`, `category`, and `blast_radius`.
+
+**Verify via MCP:**
+
+```
+get_report_detail(reportId)
+```
+
+Confirm `classification.severity` and `classification.category` are set.
+
+---
+
+## Stage 3 — Story mapping  [LOW freedom — run exactly]
+
+Map user stories from a live URL:
+
+```bash
+mushi stories map --url https://your-app.com --wait
+```
+
+`--wait` polls until the crawl finishes (usually 30–90 s). Expected terminal output:
+
+```
+✓  Crawled 12 pages
+✓  Claude drafted 8 user stories
+✓  Proposal created: prop_...
+Open in console → Inventory → Discovery → Past proposals
+```
+
+**Verify in DB:**
+
+```sql
+SELECT id, source, status, pages_crawled, created_at
+FROM inventory_proposals
+ORDER BY created_at DESC LIMIT 1;
+```
+
+Expected: `source = 'live_crawl'`, `status = 'pending_review'`.
+
+**Accept the proposal** in the Mushi console (Inventory → Discovery → Past proposals → Accept),
+or via CLI when the accept command is available.
+
+---
+
+## Stage 4 — TDD test generation  [LOW freedom — run exactly]
+
+Pick a story id from the accepted inventory and generate a Playwright test:
+
+```bash
+# List available stories from the accepted inventory
+mushi tdd pending
+
+# Generate a test (review mode — goes to approval queue)
+mushi tdd gen <story-id> --mode review
+```
+
+Expected output:
+
+```
+✓  Test generated: qa_...
+✓  Draft PR opened: https://github.com/.../pull/...
+   Waiting for approval — run: mushi tdd approve qa_...
+```
+
+**Verify in DB:**
+
+```sql
+SELECT id, title, approval_status, source, automation_mode, created_at
+FROM qa_stories
+ORDER BY created_at DESC LIMIT 1;
+```
+
+Expected: `source = 'test_gen_from_story'`, `approval_status = 'pending_review'`.
+
+**Via MCP:**
+
+```
+list_pending_review_stories(projectId)
+```
+
+---
+
+## Stage 5 — Approval and execution  [LOW freedom — run exactly]
+
+Approve the generated test:
+
+```bash
+mushi tdd approve <qa-story-id>
+```
+
+Trigger a manual run immediately:
+
+```bash
+mushi tdd run <qa-story-id>
+```
+
+**Verify in DB:**
+
+```sql
+SELECT id, status, latency_ms, provider_session_url, created_at
+FROM qa_story_runs
+WHERE qa_story_id = '<qa-story-id>'
+ORDER BY created_at DESC LIMIT 1;
+```
+
+Expected: `status = 'completed'` (or `failed` — a failure here is fine; it means the test ran and detected real friction).
+
+**Via MCP:**
+
+```
+run_qa_story(projectId, qaStoryId)
+```
+
+---
+
+## Stage 6 — PDCA improvement cycle  [LOW freedom — run exactly]
+
+If Stage 5 produced a failure, trigger the PDCA improver:
+
+```bash
+mushi tdd improve
+```
+
+Expected: Claude analyzes the failure, writes an improved test, and queues it for review.
+
+**Verify:**
+
+```sql
+SELECT id, title, source, parent_story_id, approval_status, created_at
+FROM qa_stories
+WHERE source = 'pdca'
+ORDER BY created_at DESC LIMIT 3;
+```
+
+Expected: at least one row with `source = 'pdca'` and a `parent_story_id` pointing to the original.
+
+---
+
+## Stage 7 — Evolution loop (optional)  [HIGH freedom]
+
+Check the full PDCA dashboard to confirm the loop is converging:
+
+**Via MCP resource:**
+
+```
+project://dashboard
+```
+
+Look for:
+- Rising `judge_scores` over time.
+- Falling `recurrence_rate` (same bugs re-appearing).
+- `fix_attempts` with `status = 'completed'` outpacing `failed`.
+
+---
+
+## Pass/Fail Summary  [LOW freedom — do not skip]
+
+| Stage | What ran | Status | Notes |
+|-------|----------|--------|-------|
+| 1. Bug capture | `mushi test` → `reports` row | ✅ / ❌ | |
+| 2. AI triage | `classify-report` → severity/category | ✅ / ❌ | |
+| 3. Story mapping | `story-mapper` → `inventory_proposals` | ✅ / ❌ | |
+| 4. TDD generation | Mushi edge fn `test-gen-from-story` → `qa_stories` | ✅ / ❌ | |
+| 5. Approval + run | `qa-story-runner` → `qa_story_runs` | ✅ / ❌ | |
+| 6. PDCA improve | `pdca-runner` → `qa_stories (source=pdca)` | ✅ / ❌ | |
+
+All ✅ → Mushi is fully operational end-to-end.  
+Any ❌ → the relevant edge function failed. Run the mushi MCP `diagnose_setup` tool for targeted diagnosis.
+
+---
+
+## Tips  [HIGH freedom]
+
+- **Fastest smoke test:** Stages 1–2 only. Takes ~60 s and confirms bug capture + triage is alive.
+- **Story map only:** Stage 3. Useful after changing the Firecrawl key or updating the `story-mapper` function.
+- **TDD-only check:** Stages 4–6. Run this after changing the Mushi edge functions `test-gen-from-story` or `pdca-runner`.
+- **Browserbase vs Firecrawl:** Stage 5 uses `firecrawl_actions` by default. To test Browserbase: set `provider = 'browserbase'` on the QA story in the console first.

package/skills/plan-aeo-readiness/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: plan-aeo-readiness
+description: >
+  Plan-only audit of answer-engine (AEO/GEO) citation readiness for ChatGPT,
+  Perplexity, and AI Overviews. Use when "AEO", "GEO", "show up in
+  ChatGPT/Perplexity", "AI search visibility", "llms.txt", or "am I blocking
+  AI crawlers".
+license: MIT
+effort: high
+---
+
+# Answer-Engine Readiness Audit + Citation Plan
+
+**Degree of freedom: HIGH** — crawl access, extractability, authority levers, plan.
+Stay **plan-only**. No robots.txt, schema, or copy edits until approved.
+
+## This skill vs neighbors
+
+| Skill | Owns |
+|---|---|
+| **plan-aeo-readiness** (this) | Answer-engine / GEO citation plan |
+| `enhance-web-seo` | Classic search meta / sitemap / OG |
+| `plan-antislop` | Voice / slop in the copy itself |
+
+
+**Role:** Senior growth engineer + content strategist (AEO/GEO lens).
+
+**Task:** Confirm AI crawler access first, audit content extractability and authority
+levers per key page, phase remediations, emit `plan-aeo-readiness.md`. **Audit & plan
+only — no robots.txt, schema, or copy edits until approved.**
+
+**Find why AI engines don't cite you. Plan the fix. Change nothing until approved.**
+
+## How to reason (every plan item)
+
+1. **Propose** — unblock a bot, SSR/expose, schema, or authority lever
+2. **Risk** — engines never see the page, or they see it and have nothing to cite
+3. **Keep-working** — pages already answer-first with valid schema
+4. **Phase** — Unblock → Structure → Authority → Entity-measure (do not execute)
+
+## Worked example
+
+> **Propose:** allow GPTBot/PerplexityBot in robots.txt; add an FAQ JSON-LD block on `/pricing`.
+> **Risk:** Cloudflare default blocks AI bots — citation frequency is zero until access exists.
+> **Keep-working:** `/docs` is SSR and already direct-answer-first.
+> **Phase:** Phase 1 — Unblock & expose.
+> **Lever:** access before schema; do not promise a rank.
+
+Ranking #1 on Google no longer buys an AI citation. Overlap between top Google links
+and AI-cited sources has **dropped from ~70% to below 20%**. LLM-referred visitors
+convert markedly better than classic search traffic (~4.4x in one 2026 analysis).
+
+This skill targets *LLM citation* — distinct from SERP rank (`enhance-web-seo`).
+
+---
+
+## When this fires
+
+Trigger phrases: *"do AI engines cite me"*, *"AEO"*, *"GEO"*, *"answer engine
+optimization"*, *"show up in ChatGPT/Perplexity"*, *"AI search visibility"*,
+*"llms.txt"*, *"am I blocking AI crawlers"*.
+
+Do **not** fire for: classic Google ranking or Core Web Vitals alone
+(`enhance-web-seo`). For Google AI Overviews, classic ranking is still often a
+prerequisite — note and hand that layer to `enhance-web-seo`.
+
+---
+
+## The audit  [HIGH freedom]
+
+### A · Can AI even read the site?
+- **robots.txt** — GPTBot, ClaudeBot, PerplexityBot, Google-Extended, and each engine's other current crawler tokens allowed? Check the engines' published token lists; the set changes.
+- **CDN / Cloudflare** — AI-bot blocking can be on by default; if the site sits behind a CDN, confirm bot access with a live fetch.
+- **SSR vs JS-hidden** — content behind client JS/login/paywall can't be cited.
+- **llms.txt** — present? Recommend describing site structure for AI systems.
+
+### B · Extractable & answer-shaped?
+- **Direct-answer-first** — concise answer before context.
+- **Heading hierarchy** — H1→H2→H3, one topic per section.
+- **Schema markup** — FAQ, HowTo, Product, Review, Speakable JSON-LD valid.
+- **Sub-query coverage** — answers likely fan-out sub-questions.
+
+### C · Citable / authoritative? (Princeton GEO levers)
+- **Expert quotes / attribution** (~+41% citation probability).
+- **Statistics & data** (~+30%).
+- **Inline citations** to authoritative sources (~+30%).
+- **No keyword stuffing** (~-9%); hand AI-slop copy to `plan-antislop`.
+
+### D · Entity & consensus (advisory)
+- Brand consistency across crawled sources; platform presence gaps. Note only.
+
+### E · Measurability
+- Baseline citation monitoring across engines recommended.
+
+---
+
+## Procedure  [HIGH freedom — plan only]
+
+1. **Crawl-access first** (A) — blocked bots = finding #1.
+2. **Audit content shape & authority** (B, C) per key page.
+3. **Note entity/measurability** (D, E).
+4. **Score** by impact × effort.
+5. **Emit `plan-aeo-readiness.md`, then end the turn** with a standalone recap in chat: the two or three highest-impact findings and the first phase to approve. The file is the deliverable — write it before the recap.
+
+---
+
+## Guardrails
+
+- **Plan only.** No robots.txt, schema, or copy edits.
+- **Access before optimization.**
+- **Don't promise rankings** — frame as citation frequency, not fixed rank.
+- **Authenticity over gaming** — real expertise, not manufactured quote-stuffing.
+- **Cross-hand copy** to `plan-antislop`.
+
+## Self-critique before the burndown  [LOW freedom — do not skip]
+
+1. **evidenced-not-assumed** — robots/CDN/SSR checked on real URLs, not assumed open
+2. **plan-only** — no robots.txt, schema, or copy edits
+3. **severity/phase justified** — blocked bots are finding #1, not buried under schema polish
+4. **right-owner** — classic meta/sitemap/OG → `enhance-web-seo`; slop copy → `plan-antislop`
+5. **no-false-safety** — do not promise rankings; citation frequency only; no manufactured quote-stuffing
+
+---
+
+## Report template — `plan-aeo-readiness.md`
+
+```markdown
+# Answer-Engine Readiness Audit — <site>
+
+_Audit-only. Nothing changes until each phase is approved._
+
+## Scope
+- Pages/routes audited: …  | Behind Cloudflare/CDN: ☐
+
+## Verdict
+| Area | Status | Worst gap |
+|------|--------|-----------|
+| AI crawler access | ❌ | GPTBot blocked |
+| Content extractability | partial | answers buried |
+| Authority levers | weak | no stats/quotes |
+
+## Findings
+| # | Page | Gap | Lever | Sev | Direction |
+|---|------|-----|-------|-----|-----------|
+
+## Phased burndown
+- **Phase 1 — Unblock & expose** → `enhance-web-seo` — robots, CDN, SSR, llms.txt
+- **Phase 2 — Structure & schema** → `enhance-web-seo` — direct-answer-first, JSON-LD
+- **Phase 3 — Authority levers** → `docs-writer` — stats, quotes, citations
+- **Phase 4 — Entity/measure (advisory)** → off-site + monitoring baseline
+
+## Execution handoff
+Set citation-monitoring baseline before/after so improvement is measured.
+```
+
+---
+
+## Chains with
+
+- **Launch gates loop** — growth/discoverability; run alongside `plan-mobile-readiness`.
+- **`enhance-web-seo`** — classic ranking underpins AI Overviews.
+- **`plan-antislop`** — generic copy suppresses citation.
+- **Execution:** `enhance-web-seo`, `docs-writer`, `enhance-web-landing`.
+- **Verify:** prompt-test target queries across engines before/after.
+
+> Planned at high effort; executed at the default effort under the approved-plan execution rule (`approved-plan-execution.mdc`), which forbids reward hacking and feature deletion on any model.