@kensaurus/skills 0.0.0-stage → 2.0.0

package/skills/workflow-git-commit/SKILL.md

@@ -0,0 +1,200 @@
+---
+name: workflow-git-commit
+description: >
+  Create one conventional commit from an already-scoped change: stage the
+  named files or hunks, write the message, commit, never push. Use when
+  "commit these files" or "write a commit message". Whole tree to a PR →
+  workflow-release-prep.
+license: MIT
+effort: low
+---
+
+# Git Commit Message Generator
+
+**Degree of freedom: MIXED.** Type/scope/subject wording `[HIGH freedom]`;
+stage-only-named-paths and never-push `[LOW freedom — run exactly]`.
+
+Create one clear, meaningful conventional commit. This skill owns
+deliberate staging + commit wording, not release preparation, pushing, or
+PR creation. The change must already be logically scoped.
+
+## How to reason
+
+1. **Scope** — named files/hunks already decided; else stop
+2. **Type** — feat/fix/docs/… from the actual diff
+3. **Subject** — imperative, ≤50 chars, why in the body if needed
+4. **Bound** — commit only; never push or open a PR
+
+## Worked example
+
+> **Scope:** caller named `src/lib/cart.ts` and `src/lib/cart.test.ts` only.
+> **Type:** `fix` — deleted SKU no longer 500s.
+> **Subject:** `fix(cart): treat missing SKU as an invalid line`
+> **Bound:** staged those two paths, committed, did not `git push`.
+
+## Self-critique before reporting
+
+- **No widen** — did not `git add .` / `-A`
+- **One concern** — mixed feat+fix was split or refused
+- **Conventional** — type + imperative subject, no trailing period
+- **Right owner** — whole dirty tree → `workflow-release-prep`; push/PR → `workflow-pr`
+
+## Commit Format
+
+```
+<type>(<scope>): <subject>
+
+<body>
+
+<footer>
+```
+
+### Types
+
+| Type | When to Use |
+|------|-------------|
+| `feat` | New feature |
+| `fix` | Bug fix |
+| `docs` | Documentation only |
+| `style` | Formatting, no code change |
+| `refactor` | Code change that neither fixes nor adds |
+| `perf` | Performance improvement |
+| `test` | Adding/updating tests |
+| `chore` | Build, tooling, deps |
+| `ci` | CI/CD changes |
+
+### Scope (Optional)
+
+Component or area affected:
+```
+feat(auth): add OAuth2 support
+fix(api): handle rate limit errors
+docs(readme): update installation steps
+```
+
+---
+
+## Process  [LOW freedom — run exactly]
+
+### 1. Analyze Changes  [LOW freedom — run exactly]
+
+```bash
+# Read-only: inspect the already-scoped change
+git diff --staged
+
+# View changed files
+git status --short
+```
+
+If the intended scope is not already clear, stop and ask the caller to name
+the files or hunks. Stage only those paths/hunks. Never widen scope with
+`git add .` or `git add -A`, and never push from this skill.
+
+### 2. Identify Type and Scope  [HIGH freedom]
+
+- What kind of change? (feat/fix/refactor/etc.)
+- What component is affected?
+
+### 3. Write Subject Line  [HIGH freedom]
+
+**Rules:**
+- Max 50 characters
+- Imperative mood ("add" not "added")
+- No period at end
+- Lowercase after type
+
+**Good:**
+```
+feat(cart): add quantity selector to items
+fix(auth): prevent session timeout during checkout
+refactor(utils): extract date formatting logic
+```
+
+**Bad:**
+```
+Fixed the bug. # Vague, past tense
+feat(cart): Added new feature # Past tense, vague
+Update stuff # No type, vague
+```
+
+### 4. Write Body (If Needed)  [HIGH freedom]
+
+When to include:
+- Complex changes
+- Non-obvious reasoning
+- Breaking changes
+
+Format:
+```
+feat(payments): add Stripe webhook handler
+
+Implement webhook endpoint to process payment events.
+Handles succeeded, failed, and refunded events.
+
+Closes #123
+```
+
+---
+
+## Examples
+
+### Simple Feature
+```
+feat(dashboard): add dark mode toggle
+```
+
+### Bug Fix with Context
+```
+fix(api): handle null response from external service
+
+The third-party API occasionally returns null instead of
+an empty array. Add null check to prevent TypeError.
+
+Fixes #456
+```
+
+### Refactoring
+```
+refactor(hooks): extract useDebounce from search component
+
+Move debounce logic to reusable hook for consistency
+across search inputs throughout the app.
+```
+
+### Breaking Change
+```
+feat(api)!: change response format for user endpoint
+
+BREAKING CHANGE: The /api/users endpoint now returns
+{ data: [...], meta: {...} } instead of a plain array.
+
+Migration: Update clients to access users via response.data
+```
+
+### Multiple Changes — Split Them
+If you need to describe multiple things, consider splitting into separate commits:
+```
+# Instead of:
+"fix(auth): fix login and add logout button and update styles"
+
+# Do:
+git commit -m "fix(auth): handle expired token error"
+git commit -m "feat(auth): add logout button to header"
+git commit -m "style(auth): update login form spacing"
+```
+
+---
+
+## Quick Reference
+
+```bash
+git add -- <named-path> [...]
+git commit -m "$(cat <<'EOF'
+feat(scope): concise imperative subject
+
+Explain why the change is needed when the subject is not enough.
+
+Refs: #123
+EOF
+)"
+```

package/skills/workflow-green-repo/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: workflow-green-repo
+description: >
+  Drive a repository to a green baseline — typecheck, lint, tests, and build
+  passing from a clean checkout — when fixing is authorized. Use when "make
+  the repo green", "get CI passing", or "fix all the failing tests".
+license: MIT
+---
+
+# workflow-green-repo — Whole-Repository Greening
+
+**Degree of freedom: MIXED.** Root-cause of each failure `[HIGH freedom]`;
+gate discovery, worklist, and no skip/silence `[LOW freedom — run exactly]`.
+
+Bring the repository to a verified-green baseline: every configured health
+gate passes from a clean state. This is broad, authorized cleanup — the one
+place where fixing unrelated pre-existing failures is the goal, not scope
+creep.
+
+> **Green is defined by a fresh from-scratch run of every gate, not by the
+> failures you happened to see.** Enumerate first, externalize the worklist,
+> fix root causes in batches, and re-run until zero.
+
+## How to reason
+
+1. **Authorize** — whole-repo green was explicitly asked
+2. **Enumerate** — real commands + baseline failures, not assumed
+3. **Fix-root** — no skip, narrow, or ignore
+4. **Prove** — fresh from-scratch run of every gate
+
+## Worked example
+
+> **Authorize:** user said "get CI passing on this repo."
+> **Enumerate:** `pnpm typecheck` 14 errors in `lib/billing`; `pnpm test` 3 failures on date TZ.
+> **Fix-root:** restore the `Invoice` discriminant the last refactor dropped; fix TZ in the test clock, do not `.skip` the suite.
+> **Prove:** typecheck/lint/test/build re-run from scratch → clean; state file has zero open failures.
+
+## Self-critique before reporting
+
+- **Authorized** — this was not a silent rewrite of unrelated debt
+- **No fake-green** — no `.skip`, `@ts-ignore`, or weakened assertion
+- **Fresh prove** — green is a new full run, not the last batch
+- **Right owner** — one plan's leftovers → `complete-everything`; one pattern → `burndown-full`; ratchet gaming → `audit-gate-logic`
+
+## When NOT to use this  [LOW freedom — do not skip]
+
+- The user asked to finish one plan or feature → use `complete-everything`.
+- The change is one searchable pattern across files → use `burndown-full`.
+- No explicit authorization to touch pre-existing debt → confirm scope first;
+  do not silently rewrite unrelated code.
+
+## Phase 0 — Confirm authorization and discover gates  [LOW freedom — run exactly]
+
+1. Confirm the user wants the **whole repo** green, including debt that predates
+   their work. If the surface is narrower, route to `complete-everything`.
+2. Discover the real gate commands — never assume them. Read `package.json`
+   scripts, `Makefile`, `justfile`, CI workflows (`.github/workflows/*`),
+   `AGENTS.md`, `CLAUDE.md`, and README. Identify the exact commands for:
+   typecheck, lint/format, unit/integration tests, e2e (if any), build.
+3. Note the required scope for each gate (whole repo vs. per-package in a
+   monorepo) and any environment prerequisites (services, env vars, fixtures).
+4. Capture the **baseline**: run each gate once and record the failing output.
+   This is the worklist source, and it separates real regressions from flakes.
+
+## Phase 1 — Enumerate the full failure worklist  [LOW freedom — run exactly]
+
+Write `.cursor/green-repo-state.md` as the durable source of truth:
+
+```md
+# Green Repo: <repo/package scope>
+Gates: typecheck=`...` lint=`...` test=`...` e2e=`...|none` build=`...`
+Baseline captured: <date>
+
+## Failures
+- [ ] typecheck: <file:line> — <error summary>
+- [ ] lint: <rule> — <file(s)>
+- [ ] test: <suite/case> — <assertion / error>
+- [ ] build: <step> — <error>
+
+## Flaky / environment-dependent (quarantine, do not fake-fix)
+- [ ] <case> — <why it is nondeterministic>
+
+## Discovered while fixing (append, then fix)
+- (none yet)
+
+## Intentional exceptions (justify each — needs human sign-off)
+- (none yet)
+
+## Evidence
+- <gate>: <command> → <result>
+```
+
+State the totals: "N failing gates across M areas. Driving all to green."
+Mirror the worklist into the native task list for UI visibility; the state
+file wins after context compaction.
+
+## Phase 2 — Fix root causes in batches  [HIGH freedom]
+
+Work the list in small batches (one gate area or 5–10 related failures):
+
+1. Read the failing code and its intent before editing. Understand why it
+   fails — do not pattern-match a silence.
+2. Fix the **root cause**. Forbidden: deleting/`.skip`/`.only`-ing a test,
+   narrowing an assertion so it cannot fail, `@ts-ignore` / `eslint-disable` /
+   `any` to hide a real type error, broad `try/catch` that swallows, or
+   blanket snapshot updates that mask regressions.
+3. A snapshot or golden file may be updated only when the output change is
+   correct and intended — state why.
+4. Tick the item in the state file immediately per batch.
+5. Append any newly surfaced failure to **Discovered while fixing** and close
+   it in this run.
+6. If a failure is genuinely flaky or needs a real environment you lack, move
+   it to the quarantine/exception section with a precise reason — never fake a
+   pass. Real environment blockers are the only stop condition.
+7. Edit surgically: change what causes the failure, not the surrounding file. Tests you add exist only to pin the fix or to match what the repo already keeps; scratch scripts used to reproduce stay out of the repo.
+
+Do not pause between batches to ask "continue?", and do not wrap up because the context is getting long — compaction will happen on a run this size and the state file carries the worklist across it. Keep going until the worklist is empty; re-read the state file instead of trusting memory.
+
+## Phase 3 — Prove green from scratch  [LOW freedom — run exactly]
+
+Do not report green until every configured gate passes in a fresh run:
+
+1. Typecheck (whole configured scope) → clean.
+2. Lint/format → clean.
+3. Unit/integration tests → all pass; quarantined items explicitly listed.
+4. E2E (if configured) → pass.
+5. Build → succeeds.
+6. State file: zero unchecked failures outside justified exceptions.
+7. If the repo has CI, note whether the same gates run there and whether any
+   are environment-specific (so local green predicts CI green).
+
+Any new failure or regression → add to the worklist and loop back to Phase 2.
+For approved-plan or wide-change contexts, invoke `completion-judge` before the
+final claim.
+
+## Phase 4 — Report  [LOW freedom — do not skip]
+
+```md
+## Green Repo — report
+Scope: <repo/packages>
+### Result: GREEN | GREEN WITH QUARANTINE | BLOCKED
+### Gates
+- typecheck: `<cmd>` → clean
+- lint: `<cmd>` → clean
+- tests: `<cmd>` → <n> passed
+- build: `<cmd>` → ok
+### Fixed
+- <count> failures across <areas>
+### Quarantined / exceptions (each justified)
+- <case> — <reason, tracking recommendation>
+### Environment blockers (real human/infra gates only)
+- none | <blocker + one precise ask>
+```
+
+Leave `.cursor/green-repo-state.md` in place as the audit trail unless asked to
+remove it. Suggest committing mechanical fixes separately from behavioral ones
+if that aids review.
+
+## Related
+
+- `complete-everything` — close one plan's connected scope (not the whole repo)
+- `burndown-full` — one searchable pattern to 100% coverage
+- `audit-gate-logic` — whether the green baseline / ratchet can be gamed
+- `verification-before-completion` — evidence levels this skill proves
+- `completion-judge` — independent verdict before a green claim
+- `debug-error` — root-cause a single stubborn failure

package/skills/workflow-grilling/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: workflow-grilling
+description: >
+  Interview the user about a plan, decision, or idea one question at a time
+  until you agree. Use when "grill me", "stress-test this plan", "interview me
+  about this", "poke holes in this", "challenge my thinking", or before a
+  non-trivial design.
+license: MIT
+effort: high
+---
+
+# Grilling
+
+**Degree of freedom: MIXED.** Which branch to walk and how hard to challenge
+`[HIGH freedom]`; one-question-at-a-time, recommend-an-answer, and
+no-act-until-confirmed `[LOW freedom — run exactly]`.
+
+> The most common failure mode in software work is misalignment: the agent builds
+> what it *thinks* was asked. A grilling session closes that gap before any work
+> starts. Adapted from [mattpocock/skills](https://github.com/mattpocock/skills) (MIT).
+
+Interview the user relentlessly about every aspect of the plan, decision, or idea
+until you reach a shared understanding. Walk down each branch of the decision
+tree, resolving dependencies between decisions one by one.
+
+## How to reason
+
+1. **Surface** — what decision or vague term is actually in play?
+2. **Depend** — which upstream choice must land before this one?
+3. **Recommend** — your answer and why, in one sentence
+4. **Confirm** — wait; log the user's words, not yours
+
+## Worked example
+
+> **Surface:** "add AI chat to the dashboard" — "AI" and "dashboard" are both overloaded.
+> **Depend:** audience (internal ops vs customers) gates model, retention, and auth.
+> **Recommend:** internal ops assistant on existing `/dashboard` — cheapest test of the idea.
+> **Confirm:** user picks customers instead; log that, then ask the next downstream (retention vs ephemeral).
+
+## Self-critique before reporting
+
+- **One question** — the last turn asked exactly one thing
+- **Recommendation present** — every question included a default the user can accept
+- **Facts looked up** — nothing askable from the repo was asked
+- **Right owner** — session over → `design-prd` / `workflow-spec-tdd` / a `plan-*`; do not start building here
+
+## Rules of the session  [LOW freedom — run exactly]
+
+1. **One question at a time.** Ask a single question, then wait for the answer
+   before continuing. Asking multiple questions at once is bewildering.
+2. **Recommend an answer with every question.** State your recommended answer and
+   why, so the user can accept it with a single word or push back.
+3. **Facts are yours; decisions are theirs.** If a *fact* can be found by
+   exploring the environment (filesystem, git history, docs, running commands),
+   look it up instead of asking. *Decisions* belong to the user — put each one to
+   them and wait. Before the first question, read the relevant sources broadly —
+   repo, docs, git history, tickets — so the first question is already a
+   decision, not a fact.
+4. **Resolve dependencies in order.** When one decision hinges on another,
+   surface the upstream decision first.
+5. **Challenge vague terms.** When the user uses an overloaded or fuzzy word,
+   propose a precise one (see `docs-domain-modeling` when the vocabulary itself needs
+   fixing).
+6. **Do not act until confirmed.** No edits, no scaffolding, no "getting a head
+   start". The session ends when the user confirms shared understanding — then
+   summarize the decisions made and hand off to the appropriate skill
+   (`workflow-spec-tdd`, `design-prd`, `plan-*`).
+
+## Output  [LOW freedom — run exactly]
+
+Close the session with a compact decision log: each decision on one line, in the
+user's confirmed vocabulary. This log is the input to the spec or plan that
+follows — offer to carry it into `design-prd` or `/plan-mode`.

package/skills/workflow-gtm/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: workflow-gtm
+description: >
+  Take a shipped repo to market: plan-gtm audit and interview, approval, then
+  measure, message, activate, get found, launch, and a weekly loop. Use when
+  "go to market", "grow users", or "increase traffic and visibility". Strategy
+  only → plan-gtm.
+license: MIT
+---
+
+# workflow-gtm — From shipped to found, used, and paid
+
+**Degree of freedom: MIXED.** Skip/condition judgment per step
+`[HIGH freedom]`; step order, the approval gate after Step 1, and the
+scorecard `[LOW freedom — run exactly]`.
+
+The go-to-market sequence for a product that already works. Plan first, get
+the founder's approval, then run the apply skills in the order that compounds:
+measure → message → activate → be found → launch → loop.
+
+Technical launch readiness (SEO meta, PWA, bundle, quality gate) is
+**`workflow-launch-ready`**, not this. Run it before Step 5 when the app has
+never shipped.
+
+## How to reason
+
+1. **Scope** — shipped product, real users possible today; not a PRD
+2. **Gate** — `plan-gtm.md` approved phase by phase; nothing applied before
+3. **Sweep** — which steps apply this quarter; honest skips named
+4. **Scorecard** — funnel table before and after; weekly loop scheduled
+
+## Worked example
+
+> **Scope:** Next.js + Supabase kakeibo app, live, ~200 signups/month, no paid tier yet.
+> **Gate:** `plan-gtm.md` approved Phases 1–3; Phase 5 (monetize) parked until activation ≥ 30%.
+> **Sweep:** analytics → hero → onboarding → SEO/AEO → launch kit for v2.1; skip pricing.
+> **Scorecard:** activation unmeasured → 22% → 34% after onboarding; weekly loop on Mondays via `iterate-gtm-weekly`.
+
+## Self-critique before reporting
+
+- **Plan approved** — no Step 2+ skill ran before the founder approved its phase
+- **Measured first** — the funnel table had real cells (or `audit-analytics` added events) before copy or UX changed
+- **Skips named** — every skipped step has a one-line reason in the scorecard
+- **No promised outcomes** — the scorecard reports numbers, not "should grow"
+- **Right owner** — PRD → `design-prd`; technical launch sweep → `workflow-launch-ready`
+
+---
+
+## Sequence  [LOW freedom — run exactly]
+
+```
+1. PLAN      → plan-gtm                 (inventory, interview, plan-gtm.md)  ── STOP for approval
+2. MEASURE   → audit-analytics          (Visit→Signup→Activated→Paid events, consent-gated)
+3. MESSAGE   → enhance-web-conversion   (hero, CTA, proof; pricing only if Phase 5 approved)
+             → enhance-readme           (README as landing page, when the repo is the product;
+                                         audit-registry-listing first for the findings)
+4. ACTIVATE  → enhance-onboarding       (activation event, cut steps, templates, checklist)
+             → enhance-lifecycle-email  (activation nudges keyed to the same events)
+5. BE FOUND  → enhance-web-seo          (meta, sitemap, schema)
+             → docs-comparison-pages    ("X vs Y" / alternatives pages, ≤5, dated facts)
+             → plan-aeo-readiness       (AI-engine citation plan; approve, then enhance-web-seo)
+6. LAUNCH    → docs-launch-kit          (per-channel kit for this release)
+             → enhance-growth-loops     (badge / share / referral, one K per loop)
+7. LOOP      → iterate-gtm-weekly       (weekly: funnel by source, one experiment, one post)
+```
+
+Steps 3–6 run only for phases the founder approved. Mobile store products add
+`plan-aso` beside Step 5. Phase 5 (monetize) runs `plan-pricing` → approval →
+`enhance-web-conversion` (pricing) + `enhance-lifecycle-email` (trial expiry).
+
+---
+
+## Step 1: Plan (read plan-gtm)  [LOW freedom — hand off, then stop]
+
+> Read the `plan-gtm` skill and follow it.
+
+Ends the turn with `plan-gtm.md`. Wait for phase approval.
+
+## Step 2: Measure (read audit-analytics)  [HIGH freedom]
+
+> Read the `audit-analytics` skill and follow it.
+
+Goal: every funnel cell measurable, consent-gated, one taxonomy. Include the
+`activated` event `plan-gtm` defined.
+
+## Step 3: Message (read enhance-web-conversion, enhance-readme)  [HIGH freedom]
+
+> Read the `enhance-web-conversion` skill and follow it. For repo-as-product,
+> run `audit-registry-listing` for findings, then `enhance-readme`.
+
+Hero carries the positioning statement; one CTA; real proof.
+
+## Step 4: Activate (read enhance-onboarding, enhance-lifecycle-email)  [HIGH freedom]
+
+> Read the `enhance-onboarding` skill and follow it. Then read
+> `enhance-lifecycle-email` for the activation nudges keyed to the same events.
+
+Report steps before/after and the `activated` event firing.
+
+## Step 5: Be found (read enhance-web-seo, docs-comparison-pages, plan-aeo-readiness)  [HIGH freedom]
+
+> Read `enhance-web-seo` and follow it. Read `docs-comparison-pages` for the
+> ≤5 bottom-funnel pages. Then read `plan-aeo-readiness`; its plan is approved
+> before its fixes run.
+
+## Step 6: Launch (read docs-launch-kit, enhance-growth-loops)  [LOW freedom — hand off]
+
+> Read the `docs-launch-kit` skill and follow it. If the plan named a loop,
+> read `enhance-growth-loops`.
+
+One kit per release; UTMs on every link; one K per loop.
+
+## Step 7: Loop (read iterate-gtm-weekly)  [LOW freedom — hand off]
+
+> Read the `iterate-gtm-weekly` skill and follow it.
+
+Weekly review, five lines: funnel by source · activation cohort · top
+drop-off step · one experiment shipped · one launch or post. Production
+defects stay on `iterate-post-launch`.
+
+---
+
+## Scorecard output  [LOW freedom — run exactly]
+
+```markdown
+## GTM Scorecard — <product> — <date>
+
+### Decision log (from plan-gtm.md)
+Goal metric · ICP · Model · Budget
+
+### Funnel
+| Stage | Before | After | Source |
+|-------|--------|-------|--------|
+| Visit | | | |
+| Signup | | | |
+| Activated | | | |
+| Habit | | | |
+| Paid | | | |
+| Refer | | | |
+
+### Steps
+| Step | Status | Skill | Notes / skip reason |
+|------|--------|-------|---------------------|
+| 1 Plan | approved phases: … | `plan-gtm` | |
+| 2 Measure | ✅ / ⚠️ / skipped | `audit-analytics` | |
+| 3 Message | | `enhance-web-conversion` | |
+| 4 Activate | | `enhance-onboarding` | |
+| 5 Be found | | `enhance-web-seo`, `plan-aeo-readiness` | |
+| 6 Launch | | `docs-launch-kit` | |
+| 7 Loop | scheduled <day> | `iterate-gtm-weekly` | |
+
+### Next week's one fix
+```