@kensaurus/skills 0.0.0-stage → 2.1.0

package/skills/docs-writer/SKILL.md

@@ -0,0 +1,469 @@
+---
+name: docs-writer
+description: >
+  Write developer docs: README content, API references, code comments,
+  changelog entries. Use when "write docs", "document this API", or "explain
+  for contributors". README visuals → enhance-readme. Co-authored specs →
+  docs-coauthor.
+license: MIT
+---
+
+# Documentation Writer Skill
+
+**Degree of freedom: MIXED.** Voice and structure `[HIGH freedom]`;
+pre-documentation checks and the verification statement
+`[LOW freedom — run exactly]`.
+
+Create clear, useful documentation for developers.
+
+## Core principle — write for the reader's mental model first
+
+Documentation rarely fails because it's *incomplete*. It fails because the reader can't build a mental model fast enough to care. So before any reference detail, answer the questions the reader is silently asking — in their words, in this order:
+
+| The reader is silently asking… | Answer it with… |
+|:--|:--|
+| **What** is this? | One plain-English sentence — what it *does*, not how it's built |
+| **Why** should I care? | The problem it solves / the pain it removes |
+| **Who** is it for? | The audience + stack, so a wrong-fit reader can leave early |
+| **How** do I start? | The shortest path to a first win: install → one command → result |
+| **When / where** do I use it? | The situations it fits — and its boundaries (what it's *not*) |
+
+Rules that follow from this:
+
+- **Lead with the goal, not the implementation.** *"Turn a CSV into a chart"* beats *"A streaming transform pipeline built on X."*
+- **Progressive disclosure.** Newcomer on-ramp first (plain language + one example), reference depth below. A pro scrolls past the primer in two seconds; a newcomer can't skip *to* it if it was never written.
+- **Beat the curse of knowledge.** You know the jargon; the reader may not. Define a term on first use, or add a plain-language glossary when the project leans on 3+ domain terms (pattern below).
+- **Show, don't just tell.** Every abstract capability gets a concrete, copy-pasteable example.
+- **Write the sentence you'd say out loud** to a smart colleague who's never seen the project. Mannered prose is the anti-pattern — sentences that perform writing instead of saying something: throat-clearing openers, stacked hedges, "it's worth noting", triplets for rhythm, a closing line that restates the paragraph. One plain sentence per idea.
+
+Everything else in this skill (templates, API docs, comments) serves this principle — structure and polish never substitute for orienting the reader first.
+
+## How to reason
+
+1. **Observe** — existing README/docs, the code being documented, the audience
+2. **Interpret** — which silent reader questions (what / why / who / how / when) are unanswered
+3. **Classify** — README / API reference / comments / architecture — match the repo's pattern
+4. **Verify** — signatures and examples match the code you read
+
+## Worked example
+
+> **Observe:** "document createUser"; `src/users.ts` is `createUser({ email, role }) → Promise<User>`; README links `docs/api.md` with signature tables.
+> **Interpret:** the reader needs the signature, errors, and a copy-paste call — not another project README.
+> **Classify:** API reference in the existing table pattern.
+> **Write only after:** "Pre-documentation check: existing docs read: README.md, docs/api.md; pattern: signature tables; code verified: src/users.ts"
+
+## Self-critique before reporting
+
+- **Pre-doc check stated** — existing docs and code listed, not assumed
+- **First screen** — what / why / who in plain language
+- **Examples run** — copy-pasteable; signatures match the file you read
+- **Right owner** — visual README makeover → `enhance-readme`; docs/code drift plan → `plan-docs-sync`; long-form collab → `docs-coauthor`
+
+## Pre-documentation checks  [LOW freedom — run exactly]
+
+**Before writing any documentation:**
+
+### 1. Read Existing Documentation
+```
+README.md (project root)
+docs/ (existing docs)
+src/[domain]/@_[domain]-README.md (feature-specific READMEs)
+```
+
+### 2. Check Documentation Patterns
+Use `Glob` to find existing README files:
+```
+Glob: "**/*README.md" to find all READMEs
+Glob: "**/*.md" in docs/ to find documentation patterns
+```
+
+### 3. Verify Code Matches Documentation
+Read the actual code being documented to ensure accuracy:
+- Check function signatures match documentation
+- Verify example code actually works
+- Confirm database schema matches any data documentation
+
+### 4. Verification statement — so the docs rest on files you read, not assumptions
+Before writing docs, state:
+```
+"Pre-documentation check:
+- Existing docs read: [list]
+- Documentation pattern identified: [pattern from existing READMEs]
+- Code verified: [files read to ensure accuracy]"
+```
+
+---
+
+## README Template  [HIGH freedom]
+
+```markdown
+# Project Name
+
+> One plain-English sentence: what it does and who it's for — no jargon.
+
+**Why it exists** — the problem it solves, in one line.
+**Who it's for** — the audience + stack, so a wrong-fit reader leaves early.
+
+<!--
+Newcomer on-ramp: if the project is novel or uses 3+ domain-specific terms,
+add a plain-language glossary here (see "Newcomer on-ramp" pattern below) so the
+features and options that follow aren't cryptic. Omit it when the domain is common.
+-->
+
+## Features
+
+- Feature 1
+- Feature 2
+- Feature 3
+
+## Quick Start
+
+\`\`\`bash
+# Install
+npm install
+
+# Run
+npm start
+\`\`\`
+
+## Installation
+
+### Prerequisites
+
+- Node.js >= 18
+- npm or pnpm
+
+### Setup
+
+\`\`\`bash
+# Clone repository
+git clone https://github.com/user/project.git
+cd project
+
+# Install dependencies
+npm install
+
+# Set up environment
+cp .env.example .env
+# Edit .env with your values
+
+# Run development server
+npm run dev
+\`\`\`
+
+## Usage
+
+### Basic Example
+
+\`\`\`typescript
+import { Widget } from 'project';
+
+const widget = new Widget({ option: 'value' });
+widget.render();
+\`\`\`
+
+### Advanced Configuration
+
+See [Configuration Guide](./docs/configuration.md)
+
+## API Reference
+
+See [API Documentation](./docs/api.md)
+
+## Contributing
+
+See [Contributing Guide](./CONTRIBUTING.md)
+
+## License
+
+MIT
+```
+
+---
+
+## Newcomer on-ramp (novel or jargon-heavy projects)  [HIGH freedom]
+
+When a project introduces its own concepts, the reader can't parse the feature list until they know the vocabulary. Add a compact **building-blocks glossary** high in the README — plain meaning + how the reader actually uses each thing. This is the single highest-leverage block for making docs land with non-experts:
+
+```markdown
+**The building blocks** — what the terms below actually mean:
+
+| Building block | In plain English | You use it by… |
+|:--|:--|:--|
+| **Widget** | A self-contained unit that does one job | dropping it into a page |
+| **Pipeline** | The path your data takes from input to output | pointing it at a source |
+| **Adapter** | A connector to an outside service | adding its key to config |
+```
+
+Guidelines:
+
+- **Three columns beat prose.** Term → plain meaning → how you trigger/use it. Use concrete verbs ("drop in", "point at", "add a key"), not dictionary definitions.
+- Put it *above* the counts, options, or API — it's the decoder ring for everything below it.
+- **Drop it when the domain is already familiar.** Don't gloss `useState` for a React audience; do gloss a term you invented.
+
+---
+
+## Documentation Types  [HIGH freedom]
+
+### 1. API Documentation
+
+```markdown
+## createUser
+
+Create a new user account.
+
+### Signature
+
+\`\`\`typescript
+function createUser(params: CreateUserParams): Promise<User>
+\`\`\`
+
+### Parameters
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| name | string | Yes | User's display name |
+| email | string | Yes | Valid email address |
+| role | 'admin' \| 'user' | No | User role (default: 'user') |
+
+### Returns
+
+`Promise<User>` - The created user object
+
+### Example
+
+\`\`\`typescript
+const user = await createUser({
+ name: 'John Doe',
+ email: 'john@example.com',
+ role: 'admin'
+});
+\`\`\`
+
+### Errors
+
+| Error | Cause |
+|-------|-------|
+| `ValidationError` | Invalid email format |
+| `ConflictError` | Email already exists |
+```
+
+### 2. Code Comments
+
+```typescript
+/**
+ * Calculate the total price including tax and discounts.
+ *
+ * @param items - Array of cart items
+ * @param taxRate - Tax rate as decimal (e.g., 0.1 for 10%)
+ * @param discount - Optional discount code
+ * @returns Total price in cents
+ *
+ * @example
+ * const total = calculateTotal(items, 0.1, 'SAVE10');
+ */
+function calculateTotal(
+ items: CartItem[],
+ taxRate: number,
+ discount?: string
+): number {
+ // Sum up item prices
+ const subtotal = items.reduce((sum, item) => sum + item.price, 0);
+
+ // Apply discount if valid
+ const discountAmount = discount ? getDiscountAmount(discount, subtotal) : 0;
+
+ // Calculate tax on discounted amount
+ const taxableAmount = subtotal - discountAmount;
+ const tax = Math.round(taxableAmount * taxRate);
+
+ return taxableAmount + tax;
+}
+```
+
+### 3. Architecture Documentation
+
+```markdown
+# Architecture Overview
+
+## System Components
+
+\`\`\`
+┌─────────────┐ ┌─────────────┐ ┌─────────────┐
+│ Client │────▶│ API │────▶│ Database │
+│ (React) │ │ (Node) │ │ (Postgres) │
+└─────────────┘ └─────────────┘ └─────────────┘
+ │
+ ▼
+ ┌─────────────┐
+ │ Cache │
+ │ (Redis) │
+ └─────────────┘
+\`\`\`
+
+## Data Flow
+
+1. Client sends request to API
+2. API checks cache for data
+3. If cache miss, query database
+4. Store result in cache
+5. Return response to client
+
+## Key Decisions
+
+### Why PostgreSQL?
+- ACID compliance for financial data
+- JSON support for flexible schemas
+- Strong ecosystem
+
+### Why Redis?
+- Fast read performance
+- Session storage
+- Pub/sub for real-time features
+```
+
+---
+
+## Writing Guidelines  [HIGH freedom]
+
+### Be Concise
+
+```markdown
+# ❌ Too verbose
+This function is responsible for taking an array of user objects
+and filtering them based on the active status property, returning
+only those users who have an active status of true.
+
+# ✅ Concise
+Filter users by active status.
+```
+
+### Use Examples
+
+```markdown
+# ❌ Abstract description
+The function accepts configuration options.
+
+# ✅ With example
+Configure the logger:
+\`\`\`typescript
+const logger = createLogger({
+ level: 'info',
+ format: 'json',
+ output: 'stdout'
+});
+\`\`\`
+```
+
+### Structure Information
+
+Format by content shape: a list, table, or numbered steps when the content is multifaceted (options, parameters, an ordered setup); prose when it is one idea. Headings only where a reader would scan for them.
+
+```markdown
+# ❌ Wall of text
+To install the package you need to run npm install, then create
+a .env file with your configuration, then run the migrations...
+
+# ✅ Structured steps
+## Setup
+
+1. Install dependencies
+ \`\`\`bash
+ npm install
+ \`\`\`
+
+2. Configure environment
+ \`\`\`bash
+ cp .env.example .env
+ \`\`\`
+
+3. Run migrations
+ \`\`\`bash
+ npm run migrate
+ \`\`\`
+```
+
+### Kill the Jargon (beat the curse of knowledge)
+
+```markdown
+# ❌ Assumes the reader shares your context
+Configure the RLS policy on the tenant-scoped RPC before hydrating the store.
+
+# ✅ Plain first, precise second
+Set who's allowed to read each row (a "policy") before the app loads its data.
+(Supabase calls row rules "RLS"; loading data into the app is "hydrating the store.")
+```
+
+Lead with the plain-language version; put the precise term in parentheses or right after it. Never make a newcomer look up three words just to parse one sentence.
+
+---
+
+## Documentation Checklist  [LOW freedom — do not skip]
+
+### README
+- [ ] Opens by answering **what / why / who** in the first screen (plain language)
+- [ ] Clear project description
+- [ ] Quick start (< 5 steps)
+- [ ] Prerequisites listed
+- [ ] Installation instructions
+- [ ] Basic usage example
+- [ ] Jargon defined on first use, or a glossary added for 3+ domain terms
+- [ ] Link to detailed docs
+
+### API Docs
+- [ ] All public functions documented
+- [ ] Parameters and return types
+- [ ] Usage examples
+- [ ] Error cases documented
+
+### Code Comments
+- [ ] Complex logic explained
+- [ ] "Why" not just "what"
+- [ ] JSDoc for public APIs
+- [ ] No obvious comments
+
+### Architecture
+- [ ] System overview diagram
+- [ ] Component relationships
+- [ ] Key decisions documented
+- [ ] Data flow explained
+
+---
+
+## Helpful Diagrams  [HIGH freedom]
+
+### Mermaid Flowchart
+
+```markdown
+\`\`\`mermaid
+flowchart LR
+ A[User] --> B[Frontend]
+ B --> C[API]
+ C --> D[Database]
+ C --> E[Cache]
+\`\`\`
+```
+
+### Sequence Diagram
+
+```markdown
+\`\`\`mermaid
+sequenceDiagram
+ User->>+API: POST /login
+ API->>+DB: Verify credentials
+ DB-->>-API: User data
+ API-->>-User: JWT token
+\`\`\`
+```
+
+---
+
+## Keep Docs Updated  [HIGH freedom]
+
+```markdown
+# In PR template:
+## Documentation
+- [ ] README updated (if needed)
+- [ ] API docs updated (if endpoints changed)
+- [ ] Code comments added (for complex logic)
+```

package/skills/enhance-agent-guardrails/SKILL.md

@@ -0,0 +1,164 @@
+---
+name: enhance-agent-guardrails
+description: >
+  Install guardrails as code so AI sessions cannot reintroduce leaked secrets,
+  injection, or untested code. Use when "set up guardrails", "stop vibe-coding
+  regressions", or "add pre-commit security checks". Gate audit →
+  audit-gate-logic.
+license: MIT
+---
+
+# enhance-agent-guardrails — Guardrails-as-Code Against AI Regressions
+
+**Degree of freedom: MIXED.** Gap-map judgment `[HIGH freedom]`; plant-and-check, CI wiring, and "never weaken an existing check" `[LOW freedom — run exactly]`.
+
+AI agents ship the visible 80% fast and skip the 20% that keeps a repo safe. Studies in
+2026 put ~45% of AI-generated code shipping OWASP Top-10 issues, ~2.74× more security
+findings per PR, and repeated production disasters from unguarded destructive actions.
+Telling the agent to "be secure" doesn't work — **deterministic gates** do. This skill
+installs those gates so the next fast session can't quietly reintroduce old classes of bugs.
+
+> **Treat all agent output as untrusted until a machine check says otherwise.** The goal is
+> guardrails that *block at the moment of creation* (pre-commit) and *again before merge*
+> (CI), plus policy files that steer the agent up front. Additive and reversible — never
+> weaken an existing check to make the setup "pass".
+
+## How to reason
+
+1. **Detect** — hooks, CI, rules, scanners already present
+2. **Map** — which AI failure class is unguarded
+3. **Install** — additive only; pin versions; don't duplicate
+4. **Prove** — a planted finding is blocked, then removed
+
+## Worked example
+
+> **Detect:** husky + lint-staged; no gitleaks; CI runs typecheck only.
+> **Map:** secrets and SAST unguarded; tests not a merge gate.
+> **Install:** gitleaks pre-commit + CI; semgrep CI; keep existing typecheck.
+> **Prove:** scratch file with a fake AWS key is blocked; file deleted; no history rewrite.
+
+## Self-critique before reporting
+
+- **Additive** — no existing check was weakened to make setup pass
+- **Bites** — plant-and-check blocked; planted value never committed
+- **Pinned** — scanner versions are not `latest`
+- **Right owner** — leaked-secret rotation → `plan-secrets-audit`; gate bypass → `audit-gate-logic`; gate sprawl → `housekeep-gates`
+
+---
+
+## Phase 0 — Detect stack and existing protection  [HIGH freedom]
+
+```bash
+# Ecosystem + CI
+cat package.json 2>/dev/null | grep -iE "husky|lint-staged|semgrep|gitleaks|eslint|prettier|typescript"
+ls -la .husky/ .github/workflows/ 2>/dev/null
+ls .cursor/rules/ AGENTS.md CLAUDE.md .pre-commit-config.yaml 2>/dev/null
+# What's already gated?
+rg -n "gitleaks|trufflehog|semgrep|npm audit|osv-scanner|socket" .github/ .husky/ 2>/dev/null
+```
+
+Record: package manager, CI provider (GitHub Actions / other), existing hooks, existing
+rules/policy files, and which checks already run. **Don't duplicate** what's present —
+extend it.
+
+---
+
+## Phase 1 — Research current practice  [HIGH freedom]
+
+Follow `/research`: current-year guidance on AI-code guardrails (VibeSec / OWASP), and the
+current invocation for the scanners you'll wire (gitleaks, semgrep, osv-scanner/`npm audit`,
+socket). Pin tool versions rather than floating `latest`.
+
+---
+
+## Phase 2 — Gap map (which failure classes are unguarded)  [HIGH freedom]
+
+Map the documented AI failure classes to the repo's current coverage and pick what to add:
+
+| Failure class | Guard to add (if missing) |
+|---|---|
+| Hardcoded secrets / credential sprawl | Secret scan (gitleaks / trufflehog) in pre-commit **and** CI |
+| Injection / XSS / SSRF / OWASP | SAST (semgrep with a ruleset for the stack) in CI |
+| Vulnerable / hallucinated dependencies | `npm audit` / `osv-scanner` / socket in CI; lockfile required |
+| Off-system / drifting styles | Lint-as-policy (no raw hex, no arbitrary values, single icon lib) |
+| Untested "plausible" code | CI requires typecheck + test to pass; coverage floor if one exists |
+| Destructive shell/DB ops | Agent policy: human-in-the-loop for `rm -rf`, migrations, prod scripts |
+| Context/spec drift & false-done | Point agents at `verification-before-completion` + `completion-judge` |
+
+---
+
+## Phase 3 — Install the guardrails  [HIGH freedom]
+
+Install only the missing pieces. Keep each additive and clearly named.
+
+### 3a. Agent policy files (steer up front)
+
+- `.cursor/rules/*.mdc` and/or `AGENTS.md`: encode the non-negotiables as rule-as-code —
+  parameterized queries only, validate/sanitize all external input, no hardcoded secrets,
+  auth middleware on protected routes, **no destructive ops without explicit human
+  approval**, write tests for new features. Ground it in the OWASP Top 10.
+
+### 3b. Pre-commit hook (block at creation)
+
+- Wire the repo's hook manager (`husky` + `lint-staged` for Node, or
+  `.pre-commit-config.yaml`): run secret scan on staged files, lint + typecheck on changed
+  files, and fail the commit on any finding. Keep it fast (staged-only).
+
+### 3c. CI gate (block before merge — the authoritative gate)
+
+- Add/extend a CI job that treats agent output as untrusted: secret scan (full history or
+  diff), SAST, dependency audit, typecheck, lint, test. Fail the PR on high-severity
+  findings. This is the gate that matters even if a local hook is skipped.
+
+### 3d. Lint-as-policy
+
+- Add rules that block off-system patterns (`no-restricted-syntax`, raw color/arbitrary-value
+  rules, `no-console` where appropriate, `@typescript-eslint/no-explicit-any`) with a
+  documented, reviewed escape hatch — so rules get exceptions, not blanket-disabled.
+
+---
+
+## Phase 4 — Verify the guards actually bite  [LOW freedom — run exactly]
+
+A guardrail you didn't test is a guardrail that doesn't work.
+
+- **Plant-and-check (dry run):** temporarily introduce a fake secret / off-system value in a
+  scratch file and confirm the pre-commit hook and/or the scanner **blocks** it; then remove
+  it. Never commit the planted value.
+- Run the lint-as-policy rules against the current tree and report (don't mass-`--fix`
+  silently — surface what would change).
+- Confirm the CI workflow is valid (`act`/`yamllint` if available, or a draft PR).
+
+---
+
+## Phase 5 — Report + handoff  [LOW freedom — do not skip]
+
+```markdown
+## Agent Guardrails — report
+**Already present:** [hooks/CI/rules found]
+**Installed:** agent policy [files] · pre-commit [checks] · CI gate [checks] · lint-as-policy [rules]
+**Verified:** planted secret blocked ✓ · lint rules run ✓ · CI workflow valid ✓
+**Needs human review before enforcing:** [CI changes that will block merges / branch protection]
+**Not covered here (route to):** deep secrets audit → plan-secrets-audit · OWASP depth → plan-security-audit
+```
+
+> **STOP for the human** before turning on anything that blocks merges in a shared repo
+> (branch protection, required CI checks) or that rewrites history. Rotating real leaked
+> secrets is out of scope — route to `plan-secrets-audit`.
+
+---
+
+## Related
+
+- `audit-gate-logic` — audit whether existing gates can be bypassed or gamed (this skill *installs*)
+- `housekeep-gates` — consolidate accreted duplicate gates; this skill does not delete sprawl
+- `test-mutation` — assertion-strength hook this skill can install the wording for
+- `docs-adr` — same-PR / handoff reminder that a decision needs a record
+- `housekeep-backlog` — same-PR reminder that newly parked work gets a `BL-` row
+- `audit-security` / `plan-security-audit` — the vulnerability depth the SAST gate can't fully cover
+- `plan-secrets-audit` — find + triage existing leaked secrets (and rotation plan)
+- `plan-dependency-provenance` — hallucinated/slopsquatted dependency audit
+- `plan-data-integrity` — destructive-operation and data-loss guardrails
+- `verification-before-completion` (rule) + `completion-judge` — the false-done guard agents should obey
+- `audit-llm-security` — product-facing LLM attack surface (not this repo's coding agent)
+- `housekeep-design` — pairs the visual lint-as-policy with a full design consolidation