wotann 0.5.0

package/skills/refactor-safely.md

@@ -0,0 +1,73 @@
+---
+name: refactor-safely
+description: Refactor with a safety net. Forces tests-first, small reversible steps, and runs the full verification chain after each step. Use when restructuring non-trivial code, extracting a module, renaming public types, or untangling spaghetti. Refuses to start until tests exist and pass.
+type: workflow
+---
+
+# Refactor Safely — Tests-First, Step-Sized, Reversible
+
+A refactor that is one big commit is not a refactor — it is a rewrite. This skill enforces the mechanics that make refactors safe: green tests before you start, one transformation per commit, and a working tree that always typechecks.
+
+## When to invoke
+
+- Extracting logic from a 1500-line file into smaller modules.
+- Renaming a public type that is referenced in 20+ places.
+- Untangling a circular dependency.
+- Replacing a class hierarchy with composition.
+- Migrating from one library to another with a different API.
+
+## When NOT to invoke
+
+- The code has no tests AND you're working alone on a throwaway prototype — you'll move faster without ceremony.
+- The change is one-line and obvious. Just make it.
+
+## The five mechanics
+
+### 1. Tests first, green first
+Before any refactor, the tests covering the code MUST pass. If coverage is missing, write characterization tests that lock in the *current* behavior — even the bugs. The point is to detect when your refactor changes behavior, not to fix bugs.
+
+If tests are red, stop. Fix or accept the redness explicitly before refactoring.
+
+### 2. One transformation per commit
+Each commit answers ONE question: "extract this method", "rename this type", "invert this dependency". Multi-purpose commits hide bugs. They also make `git bisect` useless and review impossible.
+
+Naming convention for commits: `refactor(scope): <verb> <noun>` — `refactor(auth): extract token-validator from AuthService`.
+
+### 3. Reference-completeness sweep
+Before changing a public signature:
+1. Grep for ALL callers and references.
+2. Update every one in the same commit.
+3. Re-run typecheck. If ANY consumer breaks, you missed a reference.
+
+This is not optional. A "mostly updated" rename is worse than no rename.
+
+### 4. Verification chain after each step
+After each commit, run:
+- `typecheck` — did the change break the type graph?
+- `test` — does the suite still pass?
+- `lint` — is the formatting clean?
+
+If any step fails, fix it before moving on. Do not pile up failures across commits.
+
+### 5. Reversibility
+At every checkpoint, you should be one `git revert` away from the previous green state. If a refactor reaches a point where reverting is too painful, you went too far in one step. Split it.
+
+## Common refactor recipes
+
+- **Extract method**: identify a chunk that has a single purpose, give it a name, move it. Tests still pass.
+- **Rename type**: change definition, run typecheck, update every error site, run typecheck again.
+- **Invert dependency**: change a concrete dependency to an interface, update the consumer, then update the producer to satisfy it.
+- **Split file**: identify a cohesive subset, move it to a new file, update imports, run typecheck.
+
+## Anti-patterns
+
+- **Refactoring without tests** — you cannot tell if you broke anything.
+- **Combining refactor with feature work** — review and bisect become impossible.
+- **Editing as you go** — "while I'm here, let me fix this other thing". No. Separate PR.
+- **Skipping the typecheck step** — "the tests passed locally" is not enough on a strict-mode project.
+
+## Related
+
+- `code-simplifier` — when the goal is reducing complexity, not restructuring
+- `ai-slop-cleaner` — for cleaning AI-generated code, with a deletion-first bias
+- `superpowers:test-driven-development` — for the tests-first mindset

package/skills/refactor-with-tests.md

@@ -0,0 +1,57 @@
+---
+name: refactor-with-tests
+description: Refactor with characterization tests written FIRST. Locks current behavior (including bugs) into tests so refactor regressions are detected immediately. Use when restructuring code that has missing or weak coverage. Distinct from refactor-safely — that one assumes tests exist; this one writes them first.
+type: workflow
+---
+
+# Refactor With Tests — Characterization-First
+
+## When to invoke
+
+- The code you are about to refactor has weak or missing test coverage.
+- The behavior is implicitly correct (users rely on it) but is not explicitly checked.
+- Refactor would touch a public API and you cannot afford regressions.
+
+## When NOT to invoke
+
+- Tests already cover the code at >80% — use `refactor-safely` instead.
+- The code is throwaway — skip the ceremony.
+
+## Steps
+
+### 1. Identify the seam
+
+Pick the smallest unit you can call from a test without spinning up the whole system. A pure function is ideal; a class with one entry method is acceptable; a global script is not.
+
+If you can't find a seam, pause and refactor enough to introduce one BEFORE adding tests. Do that as a single mechanical extraction commit with no logic changes.
+
+### 2. Write characterization tests
+
+For each input class you care about (happy path, edge case, error case):
+1. Call the seam with a representative input.
+2. Capture the output exactly as it currently behaves — including any bugs.
+3. Assert on the captured output.
+
+These tests are not specifications. They lock current behavior so the refactor doesn't change observable output.
+
+### 3. Run the tests — they MUST be green
+
+If a test you just wrote fails on first run, the test is wrong (you misread the code). Fix the test. Do NOT fix the implementation yet.
+
+### 4. Refactor — one mechanical step at a time
+
+After each step, run the full test suite. The tests must stay green.
+
+If a test goes red:
+- The refactor changed behavior. Either revert the step or update the test deliberately (and document why in the commit message).
+
+### 5. After the refactor
+
+Decide whether each characterization test is still valuable as a regression test, or whether it should be deleted because the new structure makes it redundant. Don't keep tests that test private implementation details.
+
+## What success looks like
+
+- Same external behavior before and after the refactor.
+- Test count went UP, not down (you added characterization tests).
+- Each commit is a single mechanical transformation.
+- No commit changes both behavior and structure.

package/skills/rust-engineer.md

@@ -0,0 +1,24 @@
+---
+name: rust-engineer
+description: Ownership, borrowing, lifetimes, zero-cost abstractions
+context: fork
+paths: ["**/*.rs", "**/Cargo.toml"]
+requires:
+  bins: ["cargo"]
+---
+# Rust Engineer
+## Rules
+- Ownership is the core abstraction. Understand move vs borrow vs clone.
+- Prefer `&str` over `String` in function parameters.
+- Use `Result<T, E>` for fallible operations, `Option<T>` for nullable values.
+- Derive `Debug`, `Clone`, `PartialEq` on most structs.
+- Use `clippy` for linting: `cargo clippy -- -D warnings`.
+## Patterns
+- Builder pattern for complex constructors.
+- `impl Trait` for return types (zero-cost dynamic dispatch).
+- `enum` + `match` for state machines (exhaustive matching).
+- `Arc<Mutex<T>>` for shared mutable state across threads.
+## Testing
+- Unit tests in the same file with `#[cfg(test)]` module.
+- Integration tests in `tests/` directory.
+- Property-based testing with `proptest`.

package/skills/scientific-method.md

@@ -0,0 +1,54 @@
+---
+name: scientific-method
+description: Apply the scientific method to debugging and investigation. Force a hypothesis-first, evidence-driven loop instead of guess-and-check. Use when a bug is non-obvious, a system is misbehaving in production, or three quick attempts to fix have already failed. Hard-stops gut-feel patches that work locally but mask the real defect.
+type: workflow
+---
+
+# Scientific Method — Hypothesis-Driven Debugging
+
+Bugs are scientific puzzles. Treat them that way: observe, hypothesize, predict, test, conclude. Every step has a written artifact you can revisit when the hypothesis falls apart.
+
+## When to invoke
+
+- A failing test reproduces locally but the cause is non-obvious.
+- Production behavior diverges from staging in a way that "should not be possible".
+- Three different patches in a row have failed to fix the same symptom.
+- A flaky test that "passes when I rerun" — chasing it requires discipline.
+
+## When NOT to invoke
+
+- Trivial typo, missing import, off-by-one. Just fix it.
+- Linter / type-check error with a clear message — fix and move on.
+
+## The five-step loop
+
+### 1. Observe
+Write down what you see in the failure. No interpretation yet, just facts: stack trace, exact error message, when it started, who reported it, what changed recently. Keep this neutral — interpretation is step 2.
+
+### 2. Hypothesize
+List 2-4 plausible causes. For each, write one sentence: "The bug is caused by X, which produces the observed Y." Rank by prior probability. Resist the urge to commit to one too early.
+
+### 3. Predict
+For each hypothesis, write the prediction it makes that would distinguish it from the others. Example: "If hypothesis A is true, log line N will appear; if B is true, it will not." A hypothesis with no distinguishing prediction is a wish, not a hypothesis.
+
+### 4. Test
+Run a minimal experiment that observes the predicted distinguisher. This may be: adding a single log line, running with a minimized input, attaching a debugger, or a one-line test. Keep the experiment small enough to run in under five minutes.
+
+### 5. Conclude
+Either the hypothesis survives or it falls. If it falls, mark it dead in the ledger and return to step 2. If it survives, keep testing — surviving one prediction is not proof. Only a surviving hypothesis with multiple confirmed predictions and a reproducible fix counts as solved.
+
+## The evidence ledger
+
+Maintain a running list of `(hypothesis, evidence-for, evidence-against, status)` tuples. Statuses are `OPEN`, `DEAD`, `CONFIRMED`. When you write the postmortem, this ledger is the artifact.
+
+## Anti-patterns
+
+- **Whack-a-mole**: trying random changes until the symptom stops. Stop. Go to step 2.
+- **Confirmation bias**: testing only what proves your favorite hypothesis. Always test what would falsify it.
+- **Premature conclusion**: declaring "fixed" on first success without re-running the failure conditions. The bug may still be present and just hidden.
+
+## Related skills
+
+- `superpowers:systematic-debugging` — formal hypothesis ledger format
+- `tree-search` — when 4+ causes are plausible and you need parallel exploration
+- `trace` — when the bug is "why did X happen" rather than "what is wrong"

package/skills/search-first.md

@@ -0,0 +1,32 @@
+---
+name: search-first
+description: Research before coding — find existing solutions first
+context: main
+paths: []
+---
+
+# Search First
+
+## Workflow (MANDATORY before writing new code)
+1. **Search GitHub** for existing implementations.
+2. **Check package registries** (npm, PyPI) for existing libraries.
+3. **Read library docs** (use Context7 for up-to-date docs).
+4. **Check the current codebase** for existing utilities.
+5. **Only then** write custom code if nothing suitable exists.
+
+## Search Order
+1. Current codebase (Grep, Glob) — maybe it already exists.
+2. Package registries (npm search, PyPI) — maybe there's a library.
+3. GitHub code search — maybe someone solved this already.
+4. Web search — for patterns and best practices.
+5. Library documentation (Context7) — for correct API usage.
+
+## Skip When
+- Trivial edits (<5 lines of obvious code).
+- Project-internal code that's clearly understood.
+- User explicitly says "skip research."
+
+## Anti-Pattern
+Writing a custom date parser when `date-fns` exists.
+Writing a custom CSV parser when `papaparse` exists.
+Writing a custom retry mechanism when `p-retry` exists.

package/skills/security-recon-checklist.md

@@ -0,0 +1,63 @@
+---
+name: security-recon-checklist
+description: Defender-side security reconnaissance checklist for your OWN systems. Covers public attack surface, exposed metadata, SSL posture, header hygiene, and IOC lookup. Strict scope - only audits assets the user controls. Does not include exploit, payload, or attack tooling.
+type: checklist
+---
+
+# Security Recon Checklist — Defender Edition
+
+This skill is for auditing your OWN systems, your OWN domains, and your OWN public footprint. Do NOT use it to probe assets you do not own.
+
+## Pre-flight
+
+Before running any check:
+- Confirm you have written authorization for every domain, IP, or username in scope.
+- Document the scope in writing.
+- Notify on-call so unexpected traffic does not trigger an incident.
+
+## Public attack surface
+
+- [ ] List every public domain you own. Include subdomains, vanity URLs, and historical domains.
+- [ ] For each domain, capture the DNS records currently published.
+- [ ] Check for orphan A / CNAME records pointing to abandoned cloud resources (subdomain takeover risk).
+- [ ] Check certificate transparency logs for unrecognized issuer activity.
+
+## Metadata exposure
+
+- [ ] Scan publicly hosted documents (PDFs, images) for EXIF / author / device metadata.
+- [ ] Audit static-asset bundles for source maps that leak internals.
+- [ ] Review robots.txt for paths that hint at sensitive endpoints.
+
+## TLS / header posture
+
+- [ ] Run a TLS audit (testssl.sh or equivalent) against each public endpoint you own.
+- [ ] Check HSTS, CSP, X-Frame-Options, Referrer-Policy on each endpoint.
+- [ ] Confirm your certs are not about to expire.
+
+## IOC and feeds
+
+- [ ] Look up your domains and IPs in public IOC feeds (MISP, AbuseIPDB) — make sure you are NOT already listed.
+- [ ] Subscribe to CT log feeds for your domain so cert issuance triggers an alert.
+
+## Username / OSINT (only for your own usernames)
+
+- [ ] Use `wotann recon plan-username <yourUsername>` to generate a list of public profile URLs that mention your handle.
+- [ ] Visit each manually. Decide whether any need cleanup.
+- [ ] Do NOT aggregate the results into a profile of any other person.
+
+## Outputs
+
+For each item, record:
+1. Asset / scope.
+2. Tool used (and version).
+3. Date / time / operator.
+4. Finding summary.
+5. Action item with owner and due date.
+
+Write the report to `security-recon-<date>.md` and store it in your private security folder.
+
+## Out of scope
+
+- Active exploitation of any kind.
+- Probing of assets you do not own or have written authorization to test.
+- Aggregating personal data on third parties.

package/skills/security-reviewer.md

@@ -0,0 +1,37 @@
+---
+name: security-reviewer
+description: OWASP Top 10, injection, XSS, secrets, and supply chain
+context: fork
+paths: []
+---
+
+# Security Reviewer
+
+## Mandatory Checks
+- [ ] No hardcoded secrets (API keys, passwords, tokens, JWT secrets).
+- [ ] All user inputs validated and sanitized.
+- [ ] SQL queries use parameterized statements (never string concatenation).
+- [ ] HTML output escaped to prevent XSS.
+- [ ] CSRF protection on state-changing endpoints.
+- [ ] Authentication verified on all protected routes.
+- [ ] Authorization checked (not just authentication).
+- [ ] Rate limiting on public-facing endpoints.
+- [ ] Error messages don't leak sensitive data (stack traces, DB queries).
+- [ ] Dependencies checked for known CVEs.
+
+## OWASP Top 10 (2025)
+1. Broken Access Control
+2. Cryptographic Failures
+3. Injection (SQL, NoSQL, OS, LDAP)
+4. Insecure Design
+5. Security Misconfiguration
+6. Vulnerable Components
+7. Auth Failures
+8. Data Integrity Failures
+9. Logging/Monitoring Failures
+10. SSRF (Server-Side Request Forgery)
+
+## Response Protocol
+If CRITICAL issue found: STOP. Fix immediately before continuing.
+If HIGH issue found: Fix before the commit.
+If MEDIUM issue found: Fix when possible, document if not.

package/skills/self-healing.md

@@ -0,0 +1,52 @@
+---
+name: self-healing
+description: Autonomous diagnosis and repair of build, test, and runtime errors. Use when an agent hits a failure it must recover from without human intervention (CI failures, flaky tests, dependency drift).
+---
+
+# Self-Healing Pipeline
+
+Use when: autonomous agent encounters build failures, test failures, or runtime errors
+and needs to automatically diagnose and fix them without human intervention.
+
+## Pipeline Stages
+
+### Stage 1: Error Classification
+- Parse error output (compiler, test runner, linter)
+- Classify as: syntax, type, import, runtime, test, config, dependency
+- Map to fix strategy
+
+### Stage 2: Fix Strategy Selection
+| Error Type | Strategy |
+|-----------|----------|
+| Syntax error | LSP auto-fix or direct edit at error location |
+| Type error | Add/fix type annotations, update interfaces |
+| Import error | Fix import path, add missing dependency |
+| Runtime error | Add error handling, fix logic |
+| Test failure | Read test expectation vs actual, fix implementation |
+| Config error | Validate against schema, fix invalid keys |
+| Dependency error | npm install / version bump / peer dep resolution |
+
+### Stage 3: Automated Fix
+1. Read the error output and source file
+2. Apply the fix strategy
+3. Run verification (build + test)
+4. If still failing: escalate to next strategy
+
+### Stage 4: Escalation
+If 3 sequential fix attempts fail:
+1. Try a different approach (decompose the problem)
+2. Use a different model to analyze the error
+3. Search codebase for similar patterns that work
+4. If all else fails: generate a detailed error report for human
+
+## Self-Healing Hooks
+Wire into the autonomous mode's verification step:
+- After each cycle, if tests fail, enter self-healing pipeline
+- Pipeline runs as a sub-loop (max 3 attempts per error)
+- Each fix is shadow-committed for safe rollback
+
+## Hive-Inspired Features (from competitor analysis)
+- Process tree monitoring: restart crashed worker agents
+- Deadlock detection: kill and re-spawn stuck tasks
+- Resource monitoring: scale down when memory/CPU limits approached
+- Heartbeat health checks: verify all sub-agents are responsive

package/skills/setup-audit.md

@@ -0,0 +1,56 @@
+---
+name: setup-audit
+description: Detect configuration rot in .wotann/ - stale rules, orphaned skills, conflicts
+context: main
+paths: []
+---
+
+# Setup Audit
+
+## When to Use
+
+- After a major WOTANN refactor touches `src/hooks/`, `src/skills/`, or `src/prompt/`.
+- When an old guard or skill hasn't fired in the last 50 sessions.
+- Before a release candidate, to catch stale references in `wotann.yaml`.
+- When the user reports "a rule I set last month isn't working anymore".
+- Monthly hygiene pass as part of memory taxonomy maintenance.
+
+## Rules
+
+- Run in a read-only pass first; never auto-delete without user confirmation.
+- Preserve the user's custom rules; only flag WOTANN-shipped defaults as removable.
+- Report findings by severity (CRITICAL = breaks boot, HIGH = wrong behavior, LOW = cruft).
+- Propose fixes as diffs, not free-form instructions.
+- Never modify `MEMORY.md` beyond the 200-line cap enforced by the harness.
+- Record each audit run to Engram (`topic_key: audits/<date>`) for drift tracking.
+
+## Patterns
+
+- **Config diff**: `.wotann/wotann.yaml` vs. the schema in `src/core/config.ts`.
+- **Skill usage log**: `src/skills/usage.log` -> any skill with 0 triggers in 30 days.
+- **Hook orphans**: `.wotann/hooks/*.sh` referencing events that no longer fire.
+- **Memory bloat**: MEMORY.md line count, Engram observations older than 90 days.
+- **Dependency drift**: `package.json` versions vs. `package-lock.json` resolved.
+
+## Example
+
+```
+== WOTANN Setup Audit (2026-04-13) ==
+[CRITICAL] hooks/pre-compact.sh -> references removed 'compactLegacy' event
+[HIGH]     skills/epic-design.md -> 0 triggers in 45 days; consider archiving
+[LOW]      wotann.yaml -> deprecated field 'providers.v1apiKey' (renamed 'providers.apiKey')
+[OK]       memory/ -> 18 observations, no decay needed
+```
+
+## Checklist
+
+- [ ] Scan completed without modifying any file (read-only pass).
+- [ ] Findings categorized by severity.
+- [ ] Each finding includes a proposed diff or fix command.
+- [ ] Audit run recorded to Engram for future comparison.
+
+## Common Pitfalls
+
+- Auto-deleting "unused" skills that the user loads manually via `wotann skills load`.
+- Assuming a hook is orphaned when it only fires on rare events (release, upgrade).
+- Modifying `wotann.yaml` without backing it up first; user loses custom overrides.

package/skills/skeleton-of-thought.md

@@ -0,0 +1,53 @@
+---
+name: skeleton-of-thought
+description: Generate a structured outline first, then expand each point in parallel for faster long-form responses
+context: fork
+paths: []
+---
+
+# Skeleton-of-Thought
+
+## When to Use
+- Long-form structured answers (essays, reports, proposals, design docs)
+- Multi-section explanations where points are independent
+- Whenever a single linear generation feels slow or unstructured
+- Time-sensitive responses where parallel expansion saves wall-clock
+
+## What It Does
+Two-stage generation:
+1. **Skeleton stage** — emit a numbered outline of N points (1-2 sentences each)
+2. **Expansion stage** — expand each point INDEPENDENTLY (in parallel when possible) and concatenate
+
+Because expansions are independent, they can run concurrently — total wall-clock approaches 1× a single point's expansion time, not N×.
+
+## Output Shape
+```
+<skeleton>
+1. Point about X
+2. Point about Y
+3. Point about Z
+</skeleton>
+
+<expansions>
+1. [full expansion of point 1]
+2. [full expansion of point 2]
+3. [full expansion of point 3]
+</expansions>
+```
+
+## Instructions
+
+1. Identify whether the user's task fits — works best for structured long-form. Avoid for narrative prose where flow matters.
+2. Stage 1 prompt: "Produce a numbered skeleton of N points (each 1-2 sentences) covering: <user's task>. Do not expand yet."
+3. Pick N based on scope — typically 4-8.
+4. Stage 2: for each skeleton point, prompt: "Expand point K into a full paragraph. Use only point K's topic; do not reference other points."
+5. When a parallel-execution surface is available, fire all expansions concurrently.
+6. Concatenate expansions in skeleton order. Add light transitions between points if narrative continuity matters.
+
+## Tradeoffs
+- 2-3x faster wall-clock when expansions run in parallel
+- 1.0-1.2x token cost (slight overhead for the skeleton stage)
+- Lower coherence between sections than a single linear pass — add a final pass-through edit if narrative flow is required
+
+## References
+- Skeleton-of-Thought: Large Language Models Can Do Parallel Decoding — https://arxiv.org/abs/2307.15337

package/skills/skill-creator.md

@@ -0,0 +1,28 @@
+---
+name: skill-creator
+description: Create, test, and evaluate new skills
+context: fork
+paths: []
+---
+# Skill Creator
+## Skill Format
+```yaml
+---
+name: my-skill
+description: One-line description
+context: fork | main
+paths: ["**/*.ext"]
+requires:
+  bins: ["tool"]
+---
+[Skill instructions in markdown]
+```
+## Rules
+- Keep skills focused (one domain, one concern).
+- Include triggers (file patterns, keyword patterns).
+- Include anti-patterns (what NOT to do).
+- Test with at least 3 different prompts.
+## Evaluation
+- Relevance: Does it trigger for the right tasks?
+- Quality: Does it improve output quality?
+- Cost: How many tokens does it add?

package/skills/spec-driven-workflow.md

@@ -0,0 +1,23 @@
+---
+name: spec-driven-workflow
+description: Write specs before code, define acceptance criteria
+context: main
+paths: []
+---
+# Spec-Driven Workflow
+## Process
+1. **Spec**: Write feature spec with acceptance criteria BEFORE coding.
+2. **Review**: Get spec reviewed (even by yourself).
+3. **Implement**: Code to the spec, not to assumptions.
+4. **Verify**: Each acceptance criterion is tested.
+## Spec Format
+```markdown
+## Feature: [Name]
+### User Story
+As a [role], I want [action] so that [benefit].
+### Acceptance Criteria
+- [ ] Given [context], when [action], then [result].
+- [ ] Given [context], when [action], then [result].
+### Out of Scope
+- [What this feature does NOT do]
+```

package/skills/spring-boot.md

@@ -0,0 +1,67 @@
+---
+name: spring-boot
+description: Spring Boot 3, Security 6, JPA, REST APIs with Java 21+
+context: fork
+paths: ["**/application.properties", "**/application.yml"]
+requires:
+  bins: ["java", "mvn"]
+---
+
+# Spring Boot
+
+## When to Use
+
+- Building a new Java 21+ REST or GraphQL service with Spring Boot 3.x.
+- Migrating from Spring Security 5 (WebSecurityConfigurerAdapter) to Security 6 (SecurityFilterChain).
+- Wiring JPA repositories with Hibernate and query optimization.
+- Adding observability (Micrometer, Actuator, OpenTelemetry) to an existing service.
+- Containerizing a Spring app with buildpacks or Jib.
+
+## Rules
+
+- Spring Boot 3.x with Java 21+ only; drop anything <17.
+- Use `SecurityFilterChain` bean; `WebSecurityConfigurerAdapter` is removed in Security 6.
+- Constructor injection only; `@Autowired` fields are prohibited.
+- `@Transactional` at service layer, never on controllers or repositories.
+- Define DTOs via `record` types; never expose JPA entities through the API.
+- Profile-aware config (`application-prod.yml`) for anything environment-specific.
+
+## Patterns
+
+- **Layered architecture**: Controller (HTTP) -> Service (business) -> Repository (data).
+- **Problem+JSON errors**: `ResponseEntityExceptionHandler` for standardized error body.
+- **Spring Cache**: `@Cacheable` on read-heavy service methods with TTL.
+- **Testcontainers**: real DB in integration tests, never H2 as a Postgres stand-in.
+- **Actuator**: `/actuator/health`, `/actuator/metrics`, behind auth in prod.
+
+## Example
+
+```java
+@Configuration
+@EnableWebSecurity
+public class SecurityConfig {
+    @Bean
+    SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
+        return http
+            .csrf(AbstractHttpConfigurer::disable)
+            .authorizeHttpRequests(a -> a
+                .requestMatchers("/api/public/**").permitAll()
+                .anyRequest().authenticated())
+            .oauth2ResourceServer(o -> o.jwt(Customizer.withDefaults()))
+            .build();
+    }
+}
+```
+
+## Checklist
+
+- [ ] Constructor injection only (no `@Autowired` fields).
+- [ ] `SecurityFilterChain` bean defined; no deprecated adapter class.
+- [ ] DTOs are records, not JPA entities.
+- [ ] Integration tests use Testcontainers against real Postgres/MySQL.
+
+## Common Pitfalls
+
+- H2 in integration tests produces false greens; Postgres-specific SQL fails in prod.
+- `@Transactional` on a controller method: no effect (wrong proxy layer).
+- Returning `Entity` directly: Jackson triggers lazy-loading exceptions in JSON.

package/skills/sql-pro.md

@@ -0,0 +1,34 @@
+---
+name: sql-pro
+description: SQL optimization, indexing, migrations, and query design
+context: fork
+paths: ["**/*.sql", "**/migrations/**"]
+---
+
+# SQL Pro
+
+## Query Optimization
+- ALWAYS use parameterized queries (never string concatenation).
+- SELECT only needed columns (never `SELECT *` in production).
+- Use EXPLAIN ANALYZE to understand query plans.
+- Add indexes for WHERE, JOIN, and ORDER BY columns.
+- Use CTEs for readability, but check if they hurt performance.
+
+## Indexing Strategy
+- Primary keys get automatic indexes.
+- Foreign keys should have indexes.
+- Composite indexes: put high-cardinality columns first.
+- Use partial indexes for filtered queries.
+- Monitor unused indexes and remove them.
+
+## Migrations
+- Every schema change is a migration file.
+- Migrations must be reversible (up + down).
+- Never drop columns in the same deploy as code changes.
+- Use pg_stat_statements to find slow queries.
+
+## Anti-Patterns
+- N+1 queries — use JOIN or batch loading.
+- Missing WHERE on UPDATE/DELETE — always have a condition.
+- Storing JSON blobs instead of normalized tables.
+- Using ORM without understanding generated SQL.