@wrongstack/core 0.9.4 → 0.9.19

package/skills/node-modern/SKILL.md

@@ -9,6 +9,61 @@ version: 1.1.0
 
 # Modern Node.js (>= 22) — WrongStack
 
+## Overview
+
+Node.js >= 22 patterns: ESM-only imports, native fetch with AbortSignal, Web Streams, and async patterns. WrongStack uses ESM throughout — no CommonJS in new code.
+
+## Rules
+
+1. Always use ESM (`import` with `.js` extension) — never `require()`.
+2. Always use `node:` protocol for built-in modules.
+3. Always use `AbortSignal.timeout()` for long-running operations (fetch, spawn, setTimeout).
+4. Never use axios, node-fetch, or got — native fetch is sufficient.
+5. Always handle `ENOENT` on file reads — use try/catch or `access` first.
+6. Use `Promise.allSettled` when partial failure is acceptable.
+
+## Patterns
+
+### Do
+
+```typescript
+// ✅ ESM with .js extension and node: protocol
+import * as fs from 'node:fs/promises';
+import { createServer } from 'node:http';
+import { helper } from './helper.js';
+
+// ✅ Native fetch with AbortSignal
+const res = await fetch(url, { signal: AbortSignal.timeout(5000) });
+
+// ✅ Atomic write
+const tmp = `${target}.${randomBytes(4).toString('hex')}.tmp`;
+await writeFile(tmp, data);
+await rename(tmp, target);
+
+// ✅ Parallel with allSettled
+const results = await Promise.allSettled(tasks.map(t => t.run()));
+```
+
+### Don't
+
+```typescript
+// ❌ CommonJS
+const fs = require('fs/promises');
+
+// ❌ No AbortSignal — hangs forever on timeout
+await fetch(url);
+
+// ❌ axios in new code
+const res = await axios.get(url);
+
+// ❌ Swallowing AbortError silently
+try {
+  await fetch(url);
+} catch (e) {
+  // AbortError means timeout — log it or handle explicitly
+}
+```
+
 ## Imports — always ESM
 
 ```ts
@@ -130,4 +185,5 @@ while (true) {
 
 - `typescript-strict` — strict TypeScript patterns
 - `react-modern` — React Server Components with Node.js
-- `bug-hunter` — catching async/await bugs, unhandled rejections
+- `bug-hunter` — catching async/await bugs, unhandled rejections
+- `sdd` — for setting up new Node.js features with a spec first

package/skills/observability/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: observability
+description: |
+  Use this skill when instrumenting logs, traces, or metrics in WrongStack,
+  or when setting up observability for a new feature. Triggers: user says
+  "log", "trace", "metrics", "observability", "instrument", "structured logging",
+  "opentelemetry", "log level", "debug", "monitoring".
+version: 1.0.0
+---
+
+# Observability — WrongStack
+
+## Overview
+
+Instruments WrongStack code with structured logs, traces, and metrics. WrongStack uses structured logging (JSON to stdout), and pairs with `audit-log` for session analysis. The goal: every significant event is traceable from input to output.
+
+## Rules
+
+1. Log at the right level: `DEBUG` (dev only), `INFO` (normal flow), `WARN` (recoverable), `ERROR` (needs attention).
+2. Structured logs only — JSON to stdout, not plain text to files.
+3. Every significant event needs a `traceId` — correlate across tools.
+4. Never log secrets, tokens, or PII — redact before logging.
+5. Logs must answer: what happened, what context, what was the outcome.
+6. Metrics: count errors, measure latency, track active sessions.
+7. Traces: every tool call should be a span with timing.
+
+## Patterns
+
+### Do
+
+```typescript
+// ✅ Structured log — JSON to stdout
+console.log(JSON.stringify({
+  level: 'info',
+  traceId: context.traceId,
+  event: 'tool_executed',
+  tool: 'read',
+  path: 'src/index.ts',
+  duration_ms: 12,
+  outcome: 'success',
+}));
+
+// ✅ Error with context
+console.log(JSON.stringify({
+  level: 'error',
+  traceId: context.traceId,
+  event: 'tool_failed',
+  tool: 'bash',
+  command: 'pnpm test',
+  error: err.message,
+  duration_ms: 30000,
+  outcome: 'timeout',
+}));
+
+// ✅ Trace span around a tool call
+import { trace } from 'node:opentelemetry/api';
+const span = trace.getTracer('wrongstack').startSpan('bash');
+try {
+  const result = await bash(cmd);
+  span.setStatus({ code: SpanStatusCode.OK });
+  return result;
+} catch (err) {
+  span.recordException(err);
+  span.setStatus({ code: SpanStatusCode.ERROR });
+  throw err;
+} finally {
+  span.end();
+}
+```
+
+### Don't
+
+```typescript
+// ❌ Plain text log
+console.log('User logged in'); // not structured, hard to search
+
+// ❌ Logging secrets
+console.log(JSON.stringify({ token: bearerToken })); // redact!
+
+// ❌ Log level confusion
+console.log('DEBUG: entering function'); // INFO/WARN/ERROR only in prod
+
+// ❌ Missing traceId
+console.log(JSON.stringify({ event: 'tool_executed' })); // no correlation
+```
+
+## Log levels
+
+| Level | When to use | Example |
+|-------|-------------|---------|
+| `DEBUG` | Dev-only detail | "entering parseArgs with 3 args" |
+| `INFO` | Normal flow | "tool executed", "session started" |
+| `WARN` | Recoverable issue | "retry attempt2/3", "cache miss" |
+| `ERROR` | Needs attention | "tool timeout", "auth failure" |
+
+## Structured log schema
+
+Every log should include:
+
+```json
+{
+  "level": "info | warn | error",
+  "traceId": "uuid",
+  "event": "event_name",
+  "timestamp": "ISO8601",
+  "duration_ms": 12,
+  "outcome": "success | failure | timeout",
+  "context": { /* optional extra */ }
+}
+```
+
+## Metrics to track
+
+| Metric | Type | Why |
+|--------|------|-----|
+| `tool.executions` | Counter | How often each tool runs |
+| `tool.duration_ms` | Histogram | Latency per tool |
+| `session.iterations` | Gauge | Active iterations per session |
+| `error.count` | Counter | Errors by type |
+| `context.tokens` | Gauge | Context size per session |
+
+## WrongStack-specific notes
+
+- **Session logs**: WrongStack writes session JSONL to `sessionRoot` — see `audit-log` skill for analysis.
+- **Log output**: All logs go to stdout as JSON — CI captures them, not file logs.
+- **Redaction**: Use `redactKeys()` helper — never log `Authorization`, `token`, `apiKey`, `secret`.
+- **Tool tracing**: Each tool wrapper should emit a structured log on start and end.
+
+## Skills in scope
+
+- `audit-log` — for analyzing the logs this skill produces
+- `bug-hunter` — for finding bugs via error trace patterns
+- `security-scanner` — for ensuring no secrets leak into logs
+- `node-modern` — for async tracing patterns with AbortSignal

package/skills/prompt-engineering/SKILL.md

@@ -9,6 +9,51 @@ version: 1.1.0
 
 # Prompt Engineering — WrongStack
 
+## Overview
+
+Designs, critiques, and fixes system prompts, tool descriptions, and skill definitions for LLM agents. WrongStack uses a 4-layer prompt structure — static content first, volatile last for cache efficiency.
+
+## Rules
+
+1. Static content first, volatile last — cache-friendly prompts cost less per token.
+2. First sentence of skill description = trigger — keep it specific and actionable.
+3. Tool descriptions must say: when to use, key parameters, what it returns.
+4. Remove filler ("Please be helpful", "Sure, I'd be happy to") — wastes tokens.
+5. Always read before edit — agents should grep/read first, then edit.
+6. Skill descriptions should list specific trigger keywords, not generic descriptions.
+
+## Patterns
+
+### Do
+
+```markdown
+# ✅ Good — specific trigger
+Use this skill when writing or reviewing React 19+ code.
+
+# ✅ Good — tool description with all three parts
+Search file contents with regex. Pattern is regex. Use output_mode to select
+content (matched lines), files_with_matches (file list), or count (line counts).
+Always read before edit — grep first to locate the target.
+
+# ✅ Good — skill description with trigger keywords
+Use this skill when designing system prompts or tool descriptions
+for LLM agents. Covers structure, specificity, and common pitfalls.
+Triggers: user mentions "prompt", "system instruction", "tool hint".
+```
+
+### Don't
+
+```markdown
+# ❌ Bad — vague trigger
+This skill is about Docker.
+
+# ❌ Bad — filler
+Please be helpful and use your best judgment.
+
+# ❌ Bad — tool description missing parameters
+Search files using grep.
+```
+
 ## WrongStack's 4-layer structure
 
 ```
@@ -84,26 +129,8 @@ See `skill-creator` skill for the format. Key points:
 - Include concrete code examples in "Do" and "Don't" sections
 - End with "Skills in scope" so agents know to delegate
 
-## Anti-patterns for skill descriptions
-
-```
-# Bad — doesn't say when to use it
-This skill helps with code review.
-
-# Good — specific trigger
-Use this skill when reviewing a pull request or reviewing code changes
-before committing. Covers bug detection, style, and security.
-
-# Bad — too long, no trigger
-This skill is a comprehensive guide to writing effective prompts...
-
-# Good — short trigger + description
-Use this skill when designing system prompts or tool descriptions
-for LLM agents. Covers structure, specificity, and common pitfalls.
-```
-
 ## Skills in scope
 
-- `skill-creator` — for creating new skills
+- `skill-creator` — for creating new skills (primary — prompt-engineering feeds into skill creation)
 - `typescript-strict` — for TypeScript-specific prompt typing
 - `react-modern` — for React component prompt conventions

package/skills/react-modern/SKILL.md

@@ -9,6 +9,55 @@ version: 1.1.0
 
 # Modern React (19+) — WrongStack
 
+## Overview
+
+React 19+ patterns: Server Components by default, `use` hook for promises, `useTransition` for non-blocking updates, and clean client boundary management. WrongStack uses TypeScript throughout.
+
+## Rules
+
+1. Default to Server Components — mark `'use client'` only for interactive code.
+2. Keep the client boundary minimal — avoid unnecessary serialization errors.
+3. Don't use `useEffect` for data fetching — use Server Components or `use(promise)`.
+4. Don't use `forwardRef` in new code — `ref` is a regular prop in React 19.
+5. Use named exports for components — default exports hinder refactoring.
+6. Event handlers must have explicit types: `React.MouseEvent<HTMLButtonElement>`.
+
+## Patterns
+
+### Do
+
+```tsx
+// ✅ Server Component — direct await
+async function Profile({ userId }: { userId: string }) {
+  const user = await fetch(`/api/users/${userId}`).then(r => r.json());
+  return <div>{user.name}</div>;
+}
+
+// ✅ Client Component — use(promise) for thenables
+import { use } from 'react';
+function UserData({ promise }: { promise: Promise<User> }) {
+  const user = use(promise);
+  return <div>{user.name}</div>;
+}
+
+// ✅ useTransition for non-urgent updates
+const [isPending, startTransition] = useTransition();
+startTransition(() => setPage(page + 1));
+```
+
+### Don't
+
+```tsx
+// ❌ Bad — useEffect for data fetching
+useEffect(() => { fetchData().then(setData); }, []);
+
+// ❌ Bad — forwardRef in new code
+const Button = forwardRef<HTMLButtonElement, ButtonProps>(...)
+
+// ❌ Bad — default export
+export default function Button() { ... }
+```
+
 ## Component types
 
 ```tsx
@@ -76,10 +125,52 @@ const fullName = firstName + ' ' + lastName;
 | `useState` | Local component state | Don't sync with props via useEffect |
 | `useReducer` | Complex state logic | Don't chain useState for related state |
 | `useTransition` | Non-blocking updates | Don't use for urgent state changes |
+| `useDeferredValue` | Deferring expensive rendering | Don't use for urgent state changes |
+| `useCallback` | Stable function references for deps | Don't memoize everything — measure first |
+| `useMemo` | Expensive computations | Don't memoize trivial calculations |
 | `use` | Awaiting promises in render | Don't use outside component render |
 | `useEffect` | Side effects only | Don't use for data fetching or derived state |
 
-## Common React 19 changes
+## Patterns
+
+### Do
+
+```tsx
+// ✅ useDeferredValue for expensive search
+function SearchResults({ query }: { query: string }) {
+  const deferredQuery = useDeferredValue(query);
+  // deferredQuery lags behind query — renders are non-blocking
+}
+
+// ✅ useCallback for stable deps in child
+const handleClick = useCallback(() => {
+  setCount(c => c + 1);
+}, []);
+
+// ✅ useMemo for expensive transformations
+const sorted = useMemo(
+  () => items.slice().sort((a, b) => a.name.localeCompare(b.name)),
+  [items]
+);
+```
+
+### Don't
+
+```tsx
+// ❌ useMemo for trivial operations
+const doubled = useMemo(() => count * 2, [count]); // not worth it
+
+// ❌ useCallback when deps change every render
+const handleClick = useCallback(() => {
+  doSomething(obj); // obj changes every render — no benefit
+}, [obj]);
+
+// ❌ useDeferredValue for simple state
+const [name, setName] = useState('');
+const deferredName = useDeferredValue(name); // overkill
+```
+
+### Common React 19 changes
 
 - `ref` is a regular prop — no more `forwardRef`
 - Server Components can be nested without serialization

package/skills/refactor-planner/SKILL.md

@@ -9,7 +9,55 @@ version: 1.1.0
 
 # Refactor Planner — WrongStack
 
-Analyzes code structure and produces a phased refactoring plan with risk assessment, dependency ordering, and rollback strategy.
+## Overview
+
+Analyzes code structure and produces a phased refactoring plan with risk assessment, dependency ordering, and rollback strategy. Use for multi-file refactors, breaking up large modules, or addressing technical debt.
+
+## Rules
+
+1. Always build a dependency graph before planning — assumptions cause wasted work.
+2. Always include a rollback strategy — every refactor can fail.
+3. Never skip Phase 1 (low-risk quick wins) — momentum matters.
+4. Never over-phase — if a task takes <1h, merge it with related tasks.
+5. Rate each module by: cyclomatic complexity, test coverage, fan-out, public API surface.
+6. Never ignore team constraints — parallelization only works if reviewers exist.
+
+## Patterns
+
+### Do
+
+```json
+// ✅ Good — risk assessment checklist
+{
+  "module": "src/auth/session.ts",
+  "size": 450,
+  "cyclomatic": 12,
+  "testCoverage": 65,
+  "fanOut": 8,
+  "publicAPI": true,
+  "dependencies": ["core", "providers"],
+  "dependents": ["cli", "tui", "webui"]
+}
+```
+
+```text
+// ✅ Good — dependency graph (most important part)
+config.ts → logger.ts → path-resolver.ts
+     ↓           ↓
+  secret-vault.ts    session-store.ts
+     ↓                    ↓
+     └────────→  agent.ts  ←←←
+```
+
+### Don't
+
+```json
+// ❌ Bad — no dependency graph
+// "Refactor the auth layer" — with no graph, order is guessed
+
+// ❌ Bad — no rollback strategy
+// "We'll figure it out if something breaks" — plan for failure
+```
 
 ## When to use
 

package/skills/sdd/SKILL.md

@@ -9,7 +9,18 @@ version: 2.1.0
 
 # Spec-Driven Development — WrongStack
 
-Every non-trivial change starts with a spec. The spec is the source of truth.
+## Overview
+
+Every non-trivial change starts with a spec. The spec is the source of truth — it defines what to build, how to verify it, and what counts as done. SDD uses `/sdd` slash commands to create specs, generate task graphs, and track execution.
+
+## Rules
+
+1. Every non-trivial task needs a spec before writing code — you'll rewrite it anyway.
+2. Spec must have acceptance criteria — without them, you can't know when it's done.
+3. Tasks must have dependencies — everything is a dependency of something.
+4. Spec must be specific: "Users authenticate via OAuth2 with PKCE" not "improve auth".
+5. Skipping `/sdd` for urgent tasks backfires — the spec is what makes "urgent" possible.
+6. When the spec reveals a multi-file refactor, delegate to `refactor-planner` first.
 
 ## When to use
 

package/skills/security-scanner/SKILL.md

@@ -9,7 +9,52 @@ version: 1.1.0
 
 # Security Scanner — WrongStack
 
-Scans code, configs, and dependencies for security issues.
+## Overview
+
+Scans code, configs, and dependencies for security issues. Reports with severity (CRITICAL/HIGH/MEDIUM/LOW) and concrete remediation steps. Pairs with `npm audit` for supply chain scanning.
+
+## Rules
+
+1. Always provide remediation — "found X" without "do Y" is useless.
+2. Verify regex matches before flagging — generic patterns cause false positives.
+3. Don't scan `node_modules` — use `npm audit` for supply chain issues.
+4. Don't flag test fixtures — mock credentials in tests are acceptable.
+5. Always run dependency audit — supply chain is a real attack vector.
+6. Flag config issues (TLS disabled, HTTP in production) as CRITICAL.
+
+## Patterns
+
+### Do
+
+```typescript
+// ✅ SAFE — parameterized query
+db.query("SELECT * FROM users WHERE id = $1", [userId]);
+
+// ✅ SAFE — escape user input
+element.textContent = userInput;
+
+// ✅ SAFE — execFile with args array
+execFile('find', ['.', '-name', userInput], { signal: AbortSignal.timeout(5000) });
+```
+
+### Don't
+
+```typescript
+// ❌ CRITICAL — hardcoded AWS credentials
+const awsKey = "[REDACTED:aws_access_key]";
+
+// ❌ CRITICAL — private key committed
+const pem = "-----BEGIN RSA PRIVATE KEY-----\nMIIE...";
+
+// ❌ HIGH — XSS via innerHTML
+element.innerHTML = userInput;
+
+// ❌ HIGH — shell injection
+exec(`find . -name ${userInput}`);
+
+// ❌ HIGH — SQL injection
+const query = "SELECT * FROM users WHERE id = " + userId;
+```
 
 ## Workflow
 

package/skills/skill-creator/SKILL.md

@@ -8,7 +8,54 @@ version: 1.1.0
 
 # Skill Creator — WrongStack
 
-Guide the user through creating a new skill. You are the wizard — ask questions, validate answers, write the file.
+## Overview
+
+Guides the creation of new WrongStack skills. A skill is a Markdown file with YAML frontmatter — the first sentence of the description is the trigger. You are the wizard: ask questions, validate answers, write the file.
+
+## Rules
+
+1. First sentence of `description` = trigger — this is the only thing the skill loader matches on.
+2. Name must be kebab-case: `my-skill`, `docker-deploy` — lowercase, hyphens only.
+3. Skills live in `.wrongstack/skills/<name>/SKILL.md` (project level).
+4. After the trigger sentence, add `Triggers: user says "X", "Y", "Z".`.
+5. Content must be actionable — rules, patterns, anti-patterns, not just prose.
+6. End with "Skills in scope" listing related skills for delegation.
+7. Don't let skill names collide with existing skills.
+
+## Patterns
+
+### Do
+
+```markdown
+---
+name: docker-deploy
+description: |
+  Use this skill when deploying Docker containers to a production cluster.
+  Triggers: user says "docker", "container", "deploy", "dockerfile", "image".
+version: 1.0.0
+---
+
+# Docker Deploy — WrongStack
+
+## Overview
+...
+## Rules
+...
+## Patterns
+...
+## Skills in scope
+```
+
+### Don't
+
+```markdown
+---
+name: MySkill # ❌ PascalCase
+name: my_skill      # ❌ underscore
+description: |
+  This skill is about Docker.  # ❌ no trigger sentence
+---
+```
 
 ## Skill format
 
@@ -58,49 +105,7 @@ Skills live in directories under these paths (priority order):
 
 For user-created skills: always use path 1 (project level).
 
-## Naming Rules
-
-- **kebab-case**: `my-skill`, `docker-deploy`, `api-testing`
-- Lowercase letters, numbers, hyphens only
-- No spaces, no underscores, no uppercase
-- Directory name = skill name
-
-## The Trigger — the most important part
-
-The **first sentence** of the `description` is the trigger. This is the **only** thing the skill loader matches on.
-
-```
-# ✅ Good — specific trigger that can be matched
-Use this skill when deploying Docker containers to a production cluster.
-
-# ❌ Bad — vague, can't be matched
-This skill is about Docker deployment.
-
-# ✅ Good — pattern-matchable
-Use this skill when writing or reviewing React 19+ code.
-
-# ❌ Bad — too broad
-This skill is about code.
-```
-
-After the trigger sentence, add `Triggers: user says "X", "Y", "Z".` so agents know when to delegate.
-
-## Description rules
-
-- First sentence = trigger condition
-- Second sentence = what it covers
-- Triggers list = specific keywords or phrases
-- Multi-line descriptions use YAML block scalar (`|`)
-
-## Content Guidelines
-
-- **Rules**: concrete do/don't rules, not vague advice
-- **Patterns**: actual code examples, not pseudocode
-- **Anti-patterns**: show what NOT to do with real code
-- **Workflows**: step-by-step, actionable, not theoretical
-- **Skills in scope**: list related skills at the bottom for delegation
-
-## Creation Workflow
+## Workflow
 
 1. **Ask the name** — suggest kebab-case, validate format
 2. **Ask the trigger** — "What situation should activate this skill?"
@@ -117,14 +122,6 @@ Before writing the file, verify:
 - [ ] Content is actionable (rules, patterns, not just prose)
 - [ ] File will be placed in `.wrongstack/skills/`
 
-## Existing skills (don't collide)
-
-```
-audit-log, bug-hunter, git-flow, multi-agent, node-modern,
-prompt-engineering, react-modern, refactor-planner, sdd,
-security-scanner, skill-creator, typescript-strict
-```
-
 ## Skills in scope
 
 - `prompt-engineering` — for crafting the skill description and prompt text