wotann 0.5.0

package/skills/elite-longterm-memory.md

@@ -0,0 +1,144 @@
+---
+name: elite-longterm-memory
+description: Meta-skill for memory governance — what to save, when to forget, how to consolidate. Used by /save-session and autoDream.
+type: cognitive-framework
+source: openclaw
+---
+
+# Elite Long-Term Memory — Governance for Persistent Knowledge
+
+A meta-skill for managing the agent's long-term memory. Memory that grows
+without governance becomes noise; memory that gets pruned blindly loses
+durable context. This skill encodes the policies that keep memory useful
+for years, not days.
+
+Used by the `/save-session` flow at session end, and by the `autoDream`
+nightly extraction process.
+
+## When to invoke
+
+- At session end — decide what to persist from this session
+- During nightly `autoDream` — consolidate the day's observations into durable patterns
+- When a memory query returns 50+ noisy hits — time to prune or consolidate
+- When MEMORY.md crosses 200 lines — forced pruning trigger
+- When a topic_key has 3+ near-duplicate entries — consolidation candidate
+- When introducing a new memory type — decide its retention policy first
+
+## Memory taxonomy (see also: rules/memory-taxonomy.md)
+
+| Block | What it stores | Retention | Hard limit |
+|---|---|---|---|
+| user | Identity, preferences, knowledge level | indefinite | 10 entries |
+| feedback | Confirmed corrections and approaches | indefinite | 15 entries |
+| project | Active project state, decisions, deadlines | 30 days inactive → archive | 10 entries |
+| reference | Pointers to external repos, docs | indefinite | 10 entries |
+| cases | Failure + root cause + fix | indefinite | unlimited |
+| patterns | Reusable techniques that worked | indefinite | unlimited |
+| decisions | Architectural choices with reasoning | indefinite | unlimited |
+| issues | Known bugs with OPEN/SNOOZED/RESOLVED lifecycle | until RESOLVED for 3 sessions | unlimited |
+
+## Process
+
+### Save Decisions (when to write to memory)
+
+Save IMMEDIATELY when:
+- A non-obvious decision is made → block: decisions
+- A failure is fully understood → block: cases
+- A reusable technique works → block: patterns
+- A user correction is given → block: feedback
+- A new known issue is discovered → block: issues
+- A new external resource is bookmarked → block: reference
+
+Do NOT save:
+- Conversational pleasantries
+- Code snippets that already exist in the repo (let the repo be the source of truth)
+- Decisions that are trivially recoverable from the next read of the code
+- Speculation unsupported by evidence
+
+### Forget Decisions (when to prune)
+
+Prune when:
+- A `project` block entry has not been touched in 30 days
+- An `issues` entry has been RESOLVED for 3 consecutive sessions
+- A `feedback` entry has been superseded by a more specific feedback (replace, don't accumulate)
+- An auto-memory file exceeds its hard limit — drop oldest first
+- MEMORY.md exceeds 200 lines — truncate to the highest-value 200
+
+### Consolidate Decisions (when to merge)
+
+Consolidate when:
+- 3+ entries share a `topic_key` and describe the same root concept
+- A pattern has accumulated enough examples to abstract into a rule
+- Multiple cases share a common root cause — promote to a single pattern
+- A decision has been re-confirmed across 3+ sessions — promote to a stable convention
+
+### Topic-key conventions
+
+Use slash-prefixed keys to namespace:
+
+```
+cases/<domain>           — cases/hooks, cases/memory, cases/build
+patterns/<domain>        — patterns/debugging, patterns/testing
+decisions/<feature>      — decisions/auth, decisions/storage
+known-issues/<area>      — known-issues/macos, known-issues/ci
+project/<name>/<topic>   — project/wotann/audit-2026-04
+```
+
+This makes search predictable and consolidation tractable.
+
+## Examples
+
+### Example — saving a debug case
+
+User and agent fixed an EPIPE-on-hook bug. Save:
+
+```python
+mem_save(
+  title="EPIPE in pre-compact hook from undrained stdin",
+  type="bugfix",
+  topic_key="cases/hooks",
+  content="""
+  Trigger: pre-compact.js calling process.exit(0) without reading stdin.
+  Symptom: EPIPE errors in stderr; hook treated as crashed.
+  Root cause: hook STDIN pipe was filled by parent before child read.
+  Fix: read stdin (or destroy() the readable) BEFORE process.exit.
+  Regression test: tests/hooks/epipe.test.ts added.
+  """,
+)
+```
+
+### Example — consolidating duplicates
+
+A search for `topic_key=cases/hooks` returns 4 entries: 3 are about EPIPE,
+1 is about a different bug. Consolidate the 3 EPIPE entries into one
+authoritative case with all reproduction steps + the regression test
+filename. Delete the originals.
+
+### Example — auto-resolving a known issue
+
+A `known-issues/ci` entry has been in RESOLVED state for 3 consecutive
+sessions. The autoDream cycle detects this and:
+1. Moves the entry to `archive/issues/ci/<date>.md`
+2. Removes it from the active issues query results
+3. Leaves a stub: "RESOLVED on <date>; archived to <path>"
+
+## Anti-patterns
+
+- Saving everything "just in case" — noise drowns signal; future searches return junk
+- Pruning by age alone without checking whether the entry is still cited
+- Storing the same fact in 3 different topic_keys — searches return duplicates
+- Using freeform titles instead of structured topic_keys — searches miss matches
+- Treating MEMORY.md as a journal (chronological) instead of a curated knowledge base
+
+## Stopping criteria
+
+- Every save has a topic_key
+- Every block has its retention policy applied
+- MEMORY.md is under 200 lines
+- A 6-month-old entry is still findable through a reasonable query
+
+## Provenance
+
+OpenClaw's elite-longterm-memory skill. Pairs with WOTANN's Engram + claude-mem +
+auto-memory stack. The retention rules are tuned for an agent that runs daily,
+generates 50-200 observations per day, and needs durable knowledge for years.

package/skills/evaluate-prompt.md

@@ -0,0 +1,71 @@
+---
+name: evaluate-prompt
+description: Run a single prompt across N providers with promptfoo-style assertions and produce a JSON report. Use when comparing how providers respond to the same prompt or when validating a prompt against contracts before shipping.
+type: workflow
+status: runtime
+context: fork
+paths:
+  - src/evals/prompt-eval.ts
+  - src/telemetry/eval-observability.ts
+category: testing
+triggers:
+  - evaluate this prompt
+  - test this prompt across providers
+  - check the prompt against assertions
+  - run prompt evals
+  - run an eval matrix
+---
+
+# evaluate-prompt
+
+Run one prompt across multiple providers and check each response
+against a list of assertions. Produces a deterministic JSON report
+suitable for CI gates, golden-file comparisons, or human review.
+
+## When to use
+
+- A prompt is about to ship and you want regression protection.
+- You want to compare provider X vs provider Y for the same task.
+- You need a typed `EvalReport` to feed into the dashboard.
+
+## How it works
+
+1. Caller assembles an `EvalRequest`:
+   ```ts
+   import { runPromptEval } from "wotann/evals/prompt-eval";
+
+   const report = await runPromptEval({
+     prompt: "Summarize this document in one paragraph...",
+     providers: [claudeProvider, gpt5Provider, geminiProvider],
+     assertions: [
+       { type: "contains", value: "summary", caseSensitive: false },
+       { type: "matches", pattern: "^\\w+", flags: "m" },
+       { type: "json-schema", required: ["title", "body"] },
+       { type: "cost-under", maxUsd: 0.01 },
+       { type: "latency-under", maxMs: 5_000 },
+     ],
+   });
+   ```
+2. The harness calls each provider in parallel and grades every
+   response.
+3. The returned `EvalReport` has `passCount`, `ranCount`, and a
+   per-provider breakdown of which assertions passed and why.
+4. Optionally feed each per-provider result into the eval-observability
+   sink (`recordEvalRun(...)`) so the dashboard sees historical trends.
+
+## Assertion taxonomy
+
+- `contains`: substring (case-sensitive flag).
+- `matches`: regex with optional flags.
+- `json-schema`: valid JSON object with required keys.
+- `cost-under`: dollar ceiling.
+- `latency-under`: ms ceiling.
+
+## Tips
+
+- Pair this with the `compare-providers` skill for matrix comparisons.
+- Use `cost-under` + `latency-under` together to encode SLA contracts
+  rather than just correctness.
+- When assertions fail for the right reason (e.g. a model genuinely
+  cannot produce the JSON shape), commit the assertion as the new
+  baseline only after a code-review gate.

package/skills/event-driven.md

@@ -0,0 +1,21 @@
+---
+name: event-driven
+description: Event sourcing, CQRS, message queues, pub/sub
+context: fork
+paths: []
+---
+# Event-Driven Architecture
+## Rules
+- Events are immutable facts about what happened.
+- Consumers are idempotent (safe to replay events).
+- Event schemas are versioned (backward-compatible).
+- Dead letter queues for unprocessable messages.
+## Patterns
+- Event sourcing: rebuild state from event stream.
+- CQRS: separate read/write models for optimal performance.
+- Pub/sub: decouple producers from consumers.
+- Event-driven saga: coordinate distributed workflows.
+## Technologies
+- Kafka for high-throughput event streaming.
+- RabbitMQ for task queues with routing.
+- Redis Streams for lightweight event processing.

package/skills/example-tool-rules.md

@@ -0,0 +1,56 @@
+---
+name: example-tool-rules
+description: Demonstrates the `tool_rules` frontmatter — declarative tool-flow shaping for skills and recipes.
+context: fork
+paths: []
+category: example
+tool_rules:
+  # Init rule: a turn must START with `Read` so the agent gathers
+  # context before acting.
+  - type: init
+    tool: Read
+
+  # Terminal rule: once `complete` is called the turn must end. No
+  # more tool calls allowed after it in the same turn.
+  - type: terminal
+    tool: complete
+
+  # Continue rule (type-shaped): when `Read` is the current tool,
+  # the only valid next tools are Edit/Write/Bash. Anything else
+  # raises an advisory in `result.followUp`.
+  - type: continue
+    after: Read
+    allowed: [Edit, Write, Bash]
+
+  # Child rule: `Write` may only be called AFTER `Edit` has been
+  # called at least once earlier in the turn — encourages
+  # plan-before-create flow.
+  - type: child
+    parent: Edit
+    child: Write
+---
+
+# Example: tool_rules frontmatter
+
+This is a sample skill — it is NOT auto-wired into anything. It exists
+as authoritative documentation of the `tool_rules` schema. Copy the
+frontmatter into a real skill (or a recipe) and the WOTANN runtime
+will register the rules per-session via the `SkillRulesProvider`. The
+`tool-flow-gate` middleware then surfaces violations as advisory
+diagnostics in `result.followUp` — the agent reads the diagnostic on
+its next prompt and corrects course.
+
+## Authoring tip
+
+For `continue` rules you can also use the author-friendly form:
+
+```yaml
+tool_rules:
+  - type: continue
+    tool: Edit         # the tool whose flow you are shaping
+    after: [Read]      # array of parents (single-element only)
+```
+
+This reads as "Edit may run after Read" — closer to how authors
+think about flow than the type-shaped `{after, allowed}` form. Use
+whichever feels clearer; both compile to the same `ToolRule`.

package/skills/express-api.md

@@ -0,0 +1,70 @@
+---
+name: express-api
+description: Express.js REST APIs, middleware, error handling, validation
+context: fork
+paths: ["**/express*", "**/routes/**", "**/middleware/**", "**/server.{js,ts}"]
+requires:
+  bins: ["node"]
+---
+
+# Express API
+
+## When to Use
+- Building or reviewing an Express.js (4 or 5) API.
+- Adding auth, validation, rate limiting, or CORS to an existing API.
+- Migrating from untyped routes to typed (TypeScript + zod / express-validator).
+- Diagnosing slow or leaking endpoints.
+- Structuring a medium-sized Express app before it becomes a mess.
+
+## Rules
+- TypeScript strict mode. `any` in Express handlers is a bug magnet.
+- Validate every input with `zod` / `joi` / `express-validator` — never trust the body.
+- Centralize error handling in a single error middleware; never `res.send(err)` ad hoc.
+- Use `helmet` for security headers and `cors` (configured per env) — not `app.use(cors())`.
+- Wrap async handlers (`asyncHandler(fn)`) — catch rejections into the error middleware.
+- Rate-limit public endpoints at the edge OR in the app (`express-rate-limit`).
+
+## Patterns
+- **Router per domain**: `/users` router, `/orders` router.
+- **Layered architecture**: route → controller → service → repository.
+- **Dependency injection via closures** (or `awilix` / `tsyringe` if you prefer containers).
+- **Structured logging** with `pino` + request ID correlation.
+- **Graceful shutdown**: drain connections on SIGTERM before exit.
+
+## Example
+```ts
+// Typed, validated, error-handled minimal endpoint.
+import { Router, Request, Response, NextFunction } from "express";
+import { z } from "zod";
+
+export const createUserHandler = (users: UserService) => {
+  const router = Router();
+  const schema = z.object({ email: z.string().email(), name: z.string().min(1) });
+
+  router.post("/users", asyncHandler(async (req, res) => {
+    const input = schema.parse(req.body);           // throws → caught by middleware
+    const user = await users.create(input);
+    res.status(201).json(user);
+  }));
+
+  return router;
+};
+
+export function asyncHandler<T extends Request>(fn: (req: T, res: Response, next: NextFunction) => Promise<unknown>) {
+  return (req: T, res: Response, next: NextFunction) => { fn(req, res, next).catch(next); };
+}
+```
+
+## Checklist
+- [ ] TypeScript strict + no-unchecked-indexed-access enabled.
+- [ ] Every route validates its inputs with a schema.
+- [ ] Single central error middleware handles every thrown error.
+- [ ] `helmet` + per-env `cors` applied.
+- [ ] Graceful shutdown hook (`SIGTERM`) closes the HTTP server.
+
+## Common Pitfalls
+- **Missing async error handling** — unhandled rejection crashes the process.
+- **`app.use(cors())`** — wide-open CORS in production.
+- **Leaking stack traces** to clients in error responses.
+- **Long-running handlers** blocking the event loop — offload to worker or queue.
+- **Env config** read ad-hoc instead of validated at startup.

package/skills/fastapi-expert.md

@@ -0,0 +1,76 @@
+---
+name: fastapi-expert
+description: FastAPI, Pydantic V2, async, dependency injection, OpenAPI
+context: fork
+paths: ["**/fastapi*", "**/main.py", "**/*/routers/**"]
+requires:
+  bins: ["python3"]
+---
+
+# FastAPI Expert
+
+## When to Use
+- Building or reviewing a FastAPI service.
+- Converting Pydantic V1 models to V2, or adopting Pydantic V2 validators.
+- Wiring dependency injection for DB sessions, auth, or feature flags.
+- Designing OpenAPI-first APIs with client code generation.
+- Diagnosing slow endpoints or request queuing under load.
+
+## Rules
+- Pydantic V2 models for every request and response — no raw dicts.
+- `async def` for I/O-bound endpoints; sync `def` is fine for pure CPU work.
+- `Depends()` for all cross-cutting concerns: session, auth, pagination, feature flags.
+- `BackgroundTasks` for fire-and-forget work < 1s; Celery / RQ / Arq for anything longer.
+- Use `response_model` on every endpoint — sculpts the OpenAPI schema precisely.
+- Lifespan events (`asynccontextmanager`) for startup + shutdown — not `on_event`.
+
+## Patterns
+- **Router per domain** with its own prefix and tags.
+- **Typed dependency graph**: `db: Session = Depends(get_db)`.
+- **Pagination dependency** returning `limit` / `offset` / `cursor`.
+- **`HTTPException`** plus a global exception handler for uniform error shapes.
+- **OpenAPI tags + descriptions** for every router — generate a useful client.
+
+## Example
+```py
+from fastapi import FastAPI, Depends, HTTPException
+from pydantic import BaseModel, EmailStr
+from contextlib import asynccontextmanager
+
+class UserCreate(BaseModel):
+    email: EmailStr
+    name: str
+
+class UserOut(BaseModel):
+    id: int
+    email: EmailStr
+    name: str
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    await open_db_pool()
+    yield
+    await close_db_pool()
+
+app = FastAPI(lifespan=lifespan)
+
+@app.post("/users", response_model=UserOut, status_code=201)
+async def create_user(payload: UserCreate, users = Depends(get_users_repo)) -> UserOut:
+    if await users.exists(payload.email):
+        raise HTTPException(409, "Email already registered")
+    return await users.create(payload)
+```
+
+## Checklist
+- [ ] Pydantic V2 everywhere; no V1 models left.
+- [ ] Every endpoint has a typed `response_model`.
+- [ ] Lifespan handlers open/close pools cleanly.
+- [ ] Async endpoints used for I/O; sync only for pure CPU.
+- [ ] OpenAPI tags and descriptions land in the spec.
+
+## Common Pitfalls
+- **Sync DB calls in async endpoints** — blocks the event loop.
+- **Missing `response_model`** — OpenAPI spec rots.
+- **`BackgroundTasks` for long jobs** — lost on worker restart.
+- **Using Pydantic V1 API on V2 models** — deprecation warnings become errors in 3.x.
+- **Catch-all `except:`** silencing real bugs.

package/skills/file-based-planning.md

@@ -0,0 +1,49 @@
+---
+name: file-based-planning
+description: Manus-style task_plan.md, findings.md, progress.md
+context: main
+paths: []
+---
+
+# File-Based Planning
+
+## Files
+- **task_plan.md** — The plan. Phases, tasks, acceptance criteria.
+- **findings.md** — Research results, decisions, alternatives considered.
+- **progress.md** — Live progress tracker. Updated after each task.
+
+## Workflow
+1. Create `task_plan.md` with phases and tasks.
+2. For each task, update `progress.md` with status.
+3. Record discoveries in `findings.md`.
+4. Mark tasks complete only when acceptance criteria are met.
+
+## task_plan.md Format
+```markdown
+# Plan: [Feature Name]
+
+## Phase 1: [Name]
+- [ ] Task 1.1: [Description] — AC: [acceptance criteria]
+- [ ] Task 1.2: [Description] — AC: [acceptance criteria]
+
+## Phase 2: [Name]
+- [ ] Task 2.1: [Description] — AC: [acceptance criteria]
+```
+
+## progress.md Format
+```markdown
+# Progress
+
+## Current Phase: 1 (Foundation)
+## Current Task: 1.2
+
+| Task | Status | Notes |
+|------|--------|-------|
+| 1.1  | DONE   | Completed, tests pass |
+| 1.2  | IN PROGRESS | Working on auth flow |
+```
+
+## Rules
+- Plans survive context compaction (they're on disk).
+- Update progress BEFORE moving to the next task.
+- Record WHY decisions were made in findings.md.

package/skills/find-missing-tests.md

@@ -0,0 +1,75 @@
+---
+name: find-missing-tests
+description: Identify untested or under-tested code paths and propose targeted tests. Combines coverage gaps, mutation-style reasoning, and dependency-graph signals to prioritize where to add tests for maximum risk reduction.
+type: workflow
+status: runtime
+context: fork
+paths: []
+category: testing
+triggers:
+  - find missing tests
+  - what's untested
+  - coverage gaps
+  - which functions need tests
+  - prioritize tests
+---
+
+# find-missing-tests
+
+Surface the highest-impact code paths that lack test coverage and
+propose concrete tests for each, ordered by blast radius.
+
+## When to use
+
+- Before a release, to plug coverage gaps in new code.
+- After a bug fix, to confirm a regression test exists for the same
+  failure mode in nearby code.
+- During an audit, to map untested public APIs at the system boundary.
+
+## How it works
+
+1. **Run coverage with `npm run coverage`** — produces a per-file
+   line + branch coverage map.
+2. **Filter out gated paths** that intentionally aren't tested
+   (smoke-only paths, vendor code under `vendor/`, etc.).
+3. **Rank uncovered functions by blast radius**:
+   - public exports (large ripple) before private helpers
+   - functions called from many sites > leaf utilities
+   - error/cleanup paths > happy paths (silent failure is most
+     dangerous)
+4. **For each top candidate, propose a test sketch**:
+   ```
+   File: src/evals/prompt-eval.ts:201
+   Function: runPromptEval
+   Risk: provider rejects request; the fallback path emits
+         passed=false but currently has no assertion coverage.
+   Suggested test:
+     - mock provider that throws Error("rate limit")
+     - assert report.results[0].errorMessage === "rate limit"
+     - assert report.results[0].passed === false
+   ```
+5. **Open the test in TDD mode**: write the failing test, watch it
+   fail, implement / verify the production code path, watch it pass.
+
+## Heuristics
+
+- A function with branches but only line coverage isn't well-tested —
+  prioritize **branch coverage** over **line coverage**.
+- Fixture-only test runs (no actual code path through the SUT) are a
+  red flag — grep for tests that import the module but don't call any
+  exported function.
+- `try { ... } catch` blocks with no assertion covering the catch path
+  are quiet bombs.
+
+## Output
+
+A markdown table:
+```
+| Priority | File | Function | Branches uncovered | Suggested test |
+|----------|------|----------|--------------------|-----------------|
+| 1        | a.ts | doX      | error / retry      | mock throw, assert retry |
+| 2        | b.ts | mapY     | empty input        | pass [], assert []       |
+```
+
+Pair with the **test-engineer** agent to actually write the tests in
+TDD order.

package/skills/flutter-expert.md

@@ -0,0 +1,23 @@
+---
+name: flutter-expert
+description: Flutter 3+, Dart, Riverpod, Bloc, widget composition
+context: fork
+paths: ["**/*.dart", "**/pubspec.yaml"]
+requires:
+  bins: ["flutter", "dart"]
+---
+# Flutter Expert
+## Rules
+- Use Riverpod or Bloc for state management (not setState for complex state).
+- Composition over inheritance for widgets.
+- Use `const` constructors for performance (reduces rebuilds).
+- Extract widgets into separate files when >50 lines.
+## Patterns
+- Repository pattern for data access.
+- GoRouter for declarative navigation.
+- Freezed/json_serializable for immutable models.
+- Platform channels for native code bridging.
+## Testing
+- Widget tests with `testWidgets()`.
+- Unit tests for business logic.
+- Integration tests with `integration_test` package.

package/skills/frontend-design-system.md

@@ -0,0 +1,35 @@
+---
+name: frontend-design-system
+description: DESIGN.md-driven frontend styling workflow with real-site archetypes, component rules, and responsive guardrails
+context: fork
+paths: ["**/*.tsx", "**/*.jsx", "**/*.css", "**/*.scss"]
+not_for: ["**/*.test.*", "**/*.spec.*"]
+category: frontend
+---
+
+# Frontend Design System
+
+## Core Pattern
+- Treat design direction as a written system, not a pile of isolated tweaks.
+- Define the interface in the same order used by DESIGN.md workflows:
+  1. Visual theme and atmosphere
+  2. Color palette and semantic roles
+  3. Typography hierarchy
+  4. Component styling rules
+  5. Layout and spacing principles
+  6. Depth and elevation
+  7. Do and do-not rules
+  8. Responsive behavior
+  9. Agent build prompt
+
+## Style Selection
+- Pick a clear archetype before building: editorial minimalism, terminal-native, cinematic dark, blueprint-technical, premium whitespace, or warm product marketing.
+- Keep the archetype consistent across color, type, spacing, and motion.
+- Use reference-site energy as a direction, not a pixel copy.
+
+## Execution Rules
+- Name color roles semantically; avoid raw hexes scattered through components.
+- Define a deliberate type scale with strong heading/body contrast.
+- Specify component states for buttons, cards, nav, inputs, and empty states.
+- Design mobile collapse behavior up front instead of shrinking desktop layouts.
+- End with a short anti-pattern list so the UI does not drift toward generic SaaS defaults.