@kensaurus/skills 0.0.0-stage → 2.0.0

package/skills/workflow-housekeep/SKILL.md

@@ -0,0 +1,453 @@
+---
+name: workflow-housekeep
+description: >
+  Repository maintenance: sync the README, remove confirmed dead artifacts,
+  update dependencies safely. Use when "housekeep", "clean up repo", "update
+  README", or "update dependencies". Unused exports → plan-dead-code. Parked
+  work → housekeep-backlog.
+license: MIT
+---
+
+# Repo Housekeep
+
+**Degree of freedom: MIXED.** What is dead vs still referenced `[HIGH freedom]`;
+delete-only-after-proof and dependency bump commands `[LOW freedom — run exactly]`.
+
+## How to reason
+
+1. **Observe** — README drift, unused files, outdated deps
+2. **Interpret** — unused by search, or only unused in this package?
+3. **Classify** — sync docs / delete / bump / leave
+4. **Severity** — deleting a file still imported is a break
+
+## Worked example
+
+> **Observe:** `OldButton.tsx` has zero imports; README still lists a removed script; patch bump available.
+> **Interpret:** file is dead; README is stale; bump is safe if tests pass.
+> **Classify:** delete the file after `rg` + import check; sync README; bump patch.
+> **Do not** delete `housekeep-design` token work — that is another skill.
+
+## Self-critique before reporting
+
+- **Proven unused** — imports, refs, config, git history checked
+- **README matches** — scripts and paths in the README actually exist
+- **Tests after bump** — dependency update was not a silent break
+- **Right owner** — unused files/exports/deps → `plan-dead-code`; parked work → `housekeep-backlog`; token SSOT → `housekeep-design`; CI gates → `housekeep-gates`
+
+Full-cycle repository maintenance: documentation sync, dead file removal, dependency updates, and research-driven cleanup.
+Works with **any project** — auto-detects tech stack, package manager, and structure.
+
+## Rules  [LOW freedom — do not skip]
+
+> **Delete a file only after proving it unused.**
+> Check imports, references, git blame, and config entries first — a file that is still imported breaks the build when it goes.
+
+> **Research the changelog before any major-version bump.**
+> Majors carry breaking changes; a blind upgrade turns maintenance into an outage.
+
+> **README must reflect reality, not aspiration.**
+> Only document what currently exists in the codebase.
+
+> **Commit each phase separately.**
+> Documentation, cleanup, and dependency updates are independent concerns.
+
+> **Parked-work register is a different skill.**
+> Unfinished plans, TODOs, skipped tests → `housekeep-backlog`. This skill
+> does README / dead files / deps. A housekeep pass may *schedule* a
+> backlog regeneration; it does not invent the register.
+
+> **Module-graph dead code is a different skill.**
+> This skill deletes *artifacts* — logs, `.bak` files, build output,
+> committed screenshots — things dead by inspection. **Unused source
+> files, exports, types, and dependencies belong to `plan-dead-code`
+> (audit) and `housekeep-dead-code` (delete + ratchet)**, because proving
+> those dead needs a configured module graph, not a `rg` pass.
+
+---
+
+## Step 0: Auto-Detect Project Configuration  [LOW freedom — run exactly]
+
+### 0a. Detect Tech Stack
+
+Read the dependency manifest to determine the ecosystem:
+
+| File | Ecosystem | Package Manager |
+|------|-----------|-----------------|
+| `package.json` + `package-lock.json` | Node.js | npm |
+| `package.json` + `pnpm-lock.yaml` | Node.js | pnpm |
+| `package.json` + `yarn.lock` | Node.js | yarn |
+| `package.json` + `bun.lockb` | Node.js | bun |
+| `requirements.txt` / `pyproject.toml` | Python | pip / poetry / uv |
+| `Cargo.toml` | Rust | cargo |
+| `go.mod` | Go | go mod |
+| `Gemfile` | Ruby | bundler |
+| `build.gradle` / `pom.xml` | Java/Kotlin | gradle / maven |
+| `pubspec.yaml` | Dart/Flutter | pub |
+| `composer.json` | PHP | composer |
+
+### 0b. Detect Project Structure
+
+```
+Glob("README*")
+Glob("**/*readme*")
+Glob("**/CHANGELOG*")
+Glob("**/.env*")
+Glob("**/*.log")
+Glob("**/dist/**")
+Glob("**/build/**")
+Glob("**/*.screenshot*")
+Glob("**/*.png", in test/debug/temp folders)
+```
+
+### 0c. Record Configuration
+
+```
+ECOSYSTEM: [Node.js / Python / Rust / Go / etc.]
+PKG_MANAGER: [npm / pnpm / yarn / bun / pip / poetry / cargo / etc.]
+MANIFEST: [package.json / requirements.txt / Cargo.toml / etc.]
+LOCKFILE: [package-lock.json / yarn.lock / etc.]
+README_PATH: [README.md or detected path]
+SRC_DIR: [src/ / app/ / lib/ / etc.]
+BUILD_DIR: [dist/ / build/ / .next/ / out/ / etc.]
+FRAMEWORK: [Next.js / React / Vue / Django / FastAPI / etc.]
+```
+
+---
+
+## Phase 1: README Sync  [HIGH freedom]
+
+Update the root README (and any folder-level READMEs) to reflect the **current** architecture.
+
+### 1a. Discover Current Architecture
+
+Read these files to understand what actually exists:
+
+```
+- Package manifest (package.json, etc.) — dependencies, scripts, name, description
+- Entry point (src/index.ts, app/layout.tsx, main.py, etc.)
+- Config files (next.config.*, vite.config.*, tsconfig.json, etc.)
+- CI/CD (.github/workflows/*, vercel.json, netlify.toml, Dockerfile, etc.)
+- Environment files (.env.example, .env.local) — list expected env vars
+- Folder structure (top-level ls, then 2-level deep ls of src/)
+```
+
+### 1b. Cross-Check README Against Reality
+
+For each section in the existing README, verify:
+
+| README Section | Verify Against |
+|---------------|----------------|
+| Project description | `package.json` name/description, actual functionality |
+| Tech stack | Installed dependencies in manifest |
+| Getting started / Setup | Actual scripts in `package.json`, required env vars |
+| Folder structure | Real directory listing |
+| API endpoints | Route files, API handlers |
+| Features list | Actual implemented features (not planned/removed) |
+| Environment variables | `.env.example` or config files |
+| Deployment | CI/CD config, hosting config |
+| Contributing | Linter config, test setup, pre-commit hooks |
+
+### 1c. Rewrite Stale Sections
+
+For each discrepancy found:
+- **Missing feature in README**: Add it with accurate description
+- **Removed feature still in README**: Delete the section
+- **Outdated instructions**: Update to match current setup
+- **Missing sections**: Add standard sections (see template below)
+
+### 1d. README Template (adapt to project)
+
+Use the README skeleton in [`references/templates.md`](references/templates.md)
+and adapt each section to the detected stack.
+
+### 1e. Folder READMEs
+
+Check for any `*_readme.md` or `README.md` files in subdirectories. Update them if the folder contents have changed.
+
+---
+
+## Phase 2: Dead File Cleanup  [LOW freedom — run exactly]
+
+Remove files that serve no purpose in the repository.
+
+### 2a. Scan for Candidates
+
+Search for these categories of dead files:
+
+**Logs and debug output:**
+```
+Glob("**/*.log")
+Glob("**/npm-debug.log*")
+Glob("**/yarn-debug.log*")
+Glob("**/yarn-error.log*")
+Glob("**/debug.log")
+Glob("**/.pnpm-debug.log*")
+```
+
+**Screenshots and temp images:**
+```
+Glob("**/screenshot*")
+Glob("**/Screenshot*")
+Glob("**/*.png", in root or non-asset directories)
+Glob("**/*.jpg", in root or non-asset directories)
+Glob("**/temp/**")
+Glob("**/tmp/**")
+```
+
+**Build artifacts committed by mistake:**
+```
+Glob("**/dist/**")
+Glob("**/build/**")
+Glob("**/.next/**")
+Glob("**/node_modules/**")
+Glob("**/__pycache__/**")
+Glob("**/*.pyc")
+Glob("**/target/debug/**") (Rust)
+```
+
+**Deprecated / dead code:**
+```
+Glob("**/*.bak")
+Glob("**/*.old")
+Glob("**/*.orig")
+Glob("**/*deprecated*")
+Glob("**/*DEPRECATED*")
+Glob("**/*.backup")
+Glob("**/*_old.*")
+Glob("**/*_backup.*")
+Glob("**/*.tmp")
+```
+
+**IDE and OS artifacts:**
+```
+Glob("**/.DS_Store")
+Glob("**/Thumbs.db")
+Glob("**/*.swp")
+Glob("**/*.swo")
+```
+
+**Stale config files:**
+```
+Glob("**/.env.local") (should not be committed)
+Glob("**/.env.production") (check if contains secrets)
+```
+
+### 2b. Validate Before Deleting
+
+For each candidate file:
+
+1. **Check git blame**: When was it last modified? By whom?
+2. **Check imports/references**: Is any code importing or referencing this file?
+ ```
+ Grep for the filename across the codebase
+ ```
+3. **Check .gitignore**: Should this file type already be ignored?
+4. **Check CI/CD**: Does any workflow reference this file?
+
+**Classification:**
+
+| Category | Action |
+|----------|--------|
+| Log files | Delete + add to `.gitignore` |
+| Screenshots in non-asset dirs | Delete (or move to docs/ if referenced) |
+| Build artifacts | Delete + verify in `.gitignore` |
+| `.bak` / `.old` / `.orig` files | Delete (git has history) |
+| IDE/OS artifacts | Delete + add to `.gitignore` |
+| Secret files committed | Delete + rotate secrets + add to `.gitignore` |
+| Deprecated code files | Verify unused → delete |
+
+### 2c. Update .gitignore
+
+After cleanup, ensure `.gitignore` prevents reoccurrence:
+
+```
+Check existing .gitignore covers:
+- logs/ *.log
+- build output dist/ build/ .next/ out/
+- env files .env.local .env.production
+- OS files .DS_Store Thumbs.db
+- IDE files .idea/ .vscode/ (unless project uses shared settings)
+- temp files *.tmp *.bak *.swp
+- dependencies node_modules/ __pycache__/ target/
+```
+
+### 2d. Dead Exports / Unused Code → hand off
+
+**Do not run a dead-code sweep from this skill.** Unused source files,
+exports, types, and dependencies are a module-graph question: on a first
+run most findings are misconfiguration, and deleting them is how a cleanup
+becomes an outage.
+
+| Stack | Owner |
+|-------|-------|
+| TypeScript / JavaScript | `plan-dead-code` → `housekeep-dead-code` (`/deadcode`) |
+| Python | `vulture` — same discipline: baseline and review before deleting |
+
+`ts-prune` is in maintenance mode; its author points to Knip. Do not add it
+to a project.
+
+What this skill still owns here: noting that the handoff is needed, and
+scheduling it. Record the finding and move on.
+
+---
+
+## Phase 3: Dependency Updates  [HIGH freedom]
+
+### 3a. Audit Current State
+
+**Node.js:**
+```bash
+npm outdated # see what's behind
+npm audit # check vulnerabilities
+```
+
+**Python:**
+```bash
+pip list --outdated
+pip-audit # or safety check
+```
+
+**Rust:**
+```bash
+cargo outdated
+cargo audit
+```
+
+**Go:**
+```bash
+go list -m -u all
+govulncheck ./...
+```
+
+### 3b. Classify Updates
+
+| Update Type | Risk | Action |
+|-------------|------|--------|
+| Patch (1.2.3 → 1.2.4) | Low | Auto-update |
+| Minor (1.2.3 → 1.3.0) | Low-Medium | Auto-update, verify build |
+| Major (1.2.3 → 2.0.0) | High | Research changelog first |
+| Security fix (any) | Critical | Update immediately |
+
+### 3c. Update Strategy
+
+**Step 1: Fix vulnerabilities first**
+```bash
+npm audit fix # safe fixes only
+npm audit fix --force # ONLY if safe fixes insufficient, review changes
+```
+
+**Step 2: Update patch + minor**
+```bash
+npm update # updates within semver range
+```
+
+Or for more control:
+```bash
+npx npm-check-updates -u -t minor # update package.json to latest minor
+npm install # install updated versions
+```
+
+**Step 3: Research major updates**
+
+For each major version bump available:
+
+```json
+firecrawl:firecrawl_search
+{
+ "query": "<package-name> v<new-major> migration guide changelog breaking changes",
+ "limit": 3,
+ "sources": [{ "type": "web" }]
+}
+```
+
+Recognizing the package is not knowing this major's changes — read the fetched changelog as written rather than answering from memory. Only apply major updates if:
+- The migration is straightforward (no breaking API changes affecting this project)
+- The current major version is EOL or has known security issues
+- The project has tests to verify nothing breaks
+
+**Step 4: Verify after updates**
+```bash
+npm run build # or equivalent
+npm run lint # or equivalent
+npm test # if tests exist
+```
+
+### 3d. Lock File Hygiene
+
+- Ensure lock file is committed and up to date
+- If lock file has conflicts or corruption: delete and regenerate
+- Verify lock file matches the package manager in use
+
+---
+
+## Phase 4: Research-Driven General Cleanup  [HIGH freedom]
+
+### 4a. .gitignore Best Practices
+
+Research the recommended `.gitignore` for the detected ecosystem:
+
+```json
+firecrawl:firecrawl_search
+{
+ "query": "<framework> gitignore best practices <current year>",
+ "limit": 3,
+ "sources": [{ "type": "web" }]
+}
+```
+
+Cross-check with https://github.com/github/gitignore templates.
+
+### 4b. Config File Audit
+
+Check for stale or redundant config:
+
+| Config | Check |
+|--------|-------|
+| `tsconfig.json` | Target and lib match Node/browser version in use |
+| `eslint` config | Not using deprecated rules or legacy config format |
+| `prettier` config | Exists and is consistent with eslint |
+| `.nvmrc` / `engines` | Matches current LTS or team's Node version |
+| `browserslist` | Not targeting dead browsers |
+| CI/CD config | Not using deprecated actions or outdated Node versions |
+
+### 4c. Script Audit
+
+Review all scripts in `package.json` (or equivalent):
+- Remove scripts that reference deleted files or tools
+- Verify all scripts actually work
+- Add missing standard scripts (dev, build, lint, test, typecheck)
+
+### 4d. Environment Variable Audit
+
+- Verify `.env.example` lists all required vars
+- Check no `.env` files with real secrets are committed
+- Ensure env var names are consistent with usage in code
+
+### 4e. TypeScript / Lint Config Modernization
+
+If the project uses TypeScript:
+- Check for `any` type usage that could be tightened
+- Verify `strict` mode settings
+- Check for unused `@ts-ignore` or `@ts-expect-error` comments
+
+### 4f. License and Metadata
+
+- `package.json`: verify `name`, `version`, `description`, `license`, `repository` are accurate
+- `LICENSE` file: exists and matches `package.json` license field
+- `CONTRIBUTING.md`: exists if the project accepts contributions
+
+---
+
+## Phase 5: Summary Report  [LOW freedom — do not skip]
+
+Produce a summary using the **Housekeep Report template** in
+[`references/templates.md`](references/templates.md), filling in real values for
+each phase.
+
+---
+
+## Quick Reference: Common Cleanup Commands
+
+See the per-ecosystem command cheatsheet (outdated / audit / update / build
+verify for npm, pnpm, yarn, pip, cargo, go) in
+[`references/templates.md`](references/templates.md).

package/skills/workflow-housekeep/references/templates.md

@@ -0,0 +1,109 @@
+# Housekeep Templates
+
+Reusable templates for `workflow-housekeep`: the README skeleton, the summary
+report, and the per-ecosystem command cheatsheet. Adapt each to the project's
+detected stack.
+
+---
+
+## README Template (adapt to project)
+
+```markdown
+# Project Name
+
+Brief description from package manifest + actual functionality.
+
+## Tech Stack
+
+[List ONLY what's in the dependency manifest — framework, UI lib, DB, auth, etc.]
+
+## Getting Started
+
+### Prerequisites
+[Node version from .nvmrc/engines, other requirements]
+
+### Installation
+[Exact commands from package.json scripts]
+
+### Environment Variables
+[List from .env.example with descriptions]
+
+### Development
+[Dev server command, test command, lint command]
+
+## Project Structure
+[Actual directory tree, 2 levels deep]
+
+## Deployment
+[From CI/CD config — where it deploys, how]
+
+## Scripts
+[All scripts from package.json with descriptions]
+```
+
+---
+
+## Housekeep Report Template
+
+Produce this at the end of a housekeep run, filling in real values.
+
+```markdown
+## Housekeep Report — [Project Name]
+
+### Configuration
+- Ecosystem: [Node.js / Python / etc.]
+- Package Manager: [npm / pnpm / yarn / etc.]
+- Framework: [Next.js / React / Django / etc.]
+
+### Phase 1: README Sync
+- [x] Root README updated: [list of sections changed]
+- [x] Folder READMEs updated: [list]
+- Stale sections removed: [list]
+- New sections added: [list]
+
+### Phase 2: Dead File Cleanup
+| File | Category | Action |
+|------|----------|--------|
+| path/to/file.log | Log | Deleted |
+| path/to/screenshot.png | Screenshot | Deleted |
+
+- .gitignore updated: [patterns added]
+- Dead exports found: [list or "none"]
+
+### Phase 3: Dependency Updates
+- Vulnerabilities fixed: [count] ([critical/high/moderate])
+- Packages updated: [count]
+ - Patch: [list]
+ - Minor: [list]
+ - Major: [list with migration notes]
+- Build verified: [pass/fail]
+- Tests verified: [pass/fail/no tests]
+
+### Phase 4: General Cleanup
+- Config files updated: [list]
+- Scripts cleaned: [list]
+- .gitignore modernized: [yes/no]
+- Env vars audited: [findings]
+
+### Files Modified
+- [path] — [description]
+
+### Files Deleted
+- [path] — [reason]
+
+### Requires Manual Follow-Up
+- [item] — [why it cannot be automated]
+```
+
+---
+
+## Quick Reference: Common Cleanup Commands
+
+| Ecosystem | Outdated | Audit | Update | Build Verify |
+|-----------|----------|-------|--------|--------------|
+| npm | `npm outdated` | `npm audit` | `npm update && npm audit fix` | `npm run build` |
+| pnpm | `pnpm outdated` | `pnpm audit` | `pnpm update && pnpm audit --fix` | `pnpm build` |
+| yarn | `yarn outdated` | `yarn audit` | `yarn upgrade` | `yarn build` |
+| pip | `pip list --outdated` | `pip-audit` | `pip install -U <pkg>` | `python -m pytest` |
+| cargo | `cargo outdated` | `cargo audit` | `cargo update` | `cargo build` |
+| go | `go list -m -u all` | `govulncheck ./...` | `go get -u ./...` | `go build ./...` |

package/skills/workflow-launch-ready/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: workflow-launch-ready
+description: >
+  Launch-preparation sweep for a new app or major release. Use when "prepare
+  for launch", "launch week", "everything before going live", "is the app
+  launch-ready?", or "pre-launch sweep". Working tree to a PR →
+  workflow-release-prep.
+license: MIT
+---
+
+# workflow-launch-ready — Full Launch Preparation
+
+**Degree of freedom: MIXED.** Skip/condition judgment `[HIGH freedom]`; sweep
+order and quality-gate NO-GO block `[LOW freedom — run exactly]`.
+
+The pre-launch sequence. Run once, get the complete picture across SEO, PWA,
+performance, quality, and post-launch monitoring.
+
+Local dirty-tree → merge-ready PR is **`workflow-release-prep`**, not this.
+
+## How to reason
+
+1. **Scope** — new app / major release, not a dirty-tree PR
+2. **Sweep** — which steps apply; which are honest skips
+3. **Verdict** — LAUNCH-READY / WITH CONDITIONS / NOT READY
+4. **Handoff** — day-1 loop scheduled; blockers named
+
+## Worked example
+
+> **Scope:** first public launch of a Next.js + Supabase app; single locale; PWA wanted.
+> **Sweep:** SEO + PWA + bundle + quality-gate; skip i18n with a note.
+> **Verdict:** NOT READY — quality-gate NO-GO on missing RLS on `profiles`.
+> **Handoff:** fix RLS, re-run Gate 2, then `deploy-verify`; do not treat this as `workflow-release-prep`.
+
+## Self-critique before reporting
+
+- **Not a PR-prep** — local dirty tree was not routed here
+- **Skips named** — PWA/i18n skipped only when inapplicable, in the table
+- **NO-GO blocks launch** — quality-gate NO-GO is NOT READY, not "with conditions"
+- **Right owner** — merge-ready PR → `workflow-release-prep`; npm package → `deploy-npm`
+
+---
+
+## Sweep sequence  [LOW freedom — run exactly]
+
+```
+1. SEO          → enhance-web-seo    (meta, OG, JSON-LD, sitemap, canonicals)
+2. PWA          → enhance-pwa        (manifest, service worker, offline, install)
+3. BUNDLE       → audit-bundle-size  (first-load JS ≤ 200 KB goal)
+4. i18n         → audit-i18n         (if multi-locale: natural copy, no hardcoded strings)
+5. QUALITY GATE → workflow-quality-gate (red-team + security + perf + unit tests)
+6. DEPLOY       → deploy-verify      (post-deploy smoke after the release)
+7. ITERATE      → iterate-post-launch (close loop on day-1 production signals)
+```
+
+Skip steps 2 (PWA) and 4 (i18n) if not applicable — note the skip in the checklist.
+
+---
+
+## Step 1: SEO (read enhance-web-seo)  [HIGH freedom]
+
+> Read the `enhance-web-seo` skill and follow it.
+
+Every public page needs: `<title>`, `meta description`, OG tags, canonical URL,
+structured data (JSON-LD), and a sitemap entry.
+
+---
+
+## Step 2: PWA (read enhance-pwa)  [HIGH freedom]
+
+> Read the `enhance-pwa` skill and follow it.
+
+Required: Web App Manifest + service worker with offline fallback, and no
+installability errors in Chrome DevTools → Application → Manifest (Lighthouse 12
+removed its PWA score).
+
+---
+
+## Step 3: Bundle size (read audit-bundle-size)  [HIGH freedom]
+
+> Read the `audit-bundle-size` skill and follow it.
+
+Target: first-load JS ≤ 200 KB gzip. All routes lazy-loaded.
+
+---
+
+## Step 4: i18n (read audit-i18n — skip if single locale)  [HIGH freedom]
+
+> Read the `audit-i18n` skill and follow it.
+
+Priority: no hardcoded user-facing strings, natural copy in all supported
+locales, correct date/number/currency formatting.
+
+---
+
+## Step 5: Quality gate (read workflow-quality-gate)  [LOW freedom — hand off]
+
+> Read the `workflow-quality-gate` skill and follow it.
+
+This step runs test-red-team, audit-security, audit-performance, and test-unit
+internally. A NO-GO verdict from this step blocks launch.
+
+---
+
+## Step 6: Deploy & smoke (read deploy-verify)  [LOW freedom — hand off]
+
+> Read the `deploy-verify` skill and follow it.
+
+Run immediately after the production deploy. Confirm no new Sentry errors,
+schema is healthy, and critical flows work.
+
+---
+
+## Step 7: Day-1 iteration loop (read iterate-post-launch)  [LOW freedom — hand off]
+
+> Read the `iterate-post-launch` skill and follow it.
+
+Schedule this 24–48 hours after launch. Pull first real-user signals and
+prioritize the first fix pass.
+
+---
+
+## Launch checklist output  [LOW freedom — run exactly]
+
+```markdown
+## Launch Readiness — [App] — [Date]
+
+### Verdict: LAUNCH-READY / LAUNCH WITH CONDITIONS / NOT READY
+
+| Step | Status | Open items |
+|------|--------|------------|
+| SEO | ✅ / ⚠️ / ❌ | [list] |
+| PWA | ✅ / ⚠️ / ❌ / skipped | [list] |
+| Bundle size | ✅ / ⚠️ / ❌ | [X KB] |
+| i18n | ✅ / ⚠️ / skipped | [list] |
+| Quality gate | GO / NO-GO / CONDITIONAL | [see gate report] |
+| Deploy smoke | ✅ / ❌ | [notes] |
+| Day-1 plan | scheduled / not yet | [date] |
+
+### Blockers (must fix before launch)
+[list]
+
+### Post-launch backlog (fix within 48 h)
+[list]
+```