@wrongstack/core 0.6.4 → 0.6.5

package/skills/node-modern/SKILL.md

@@ -1,41 +1,133 @@
 ---
 name: node-modern
 description: |
-  Use this skill for Node.js >= 22 idioms: ESM-only, native fetch, AbortSignal,
-  node: protocol imports, structuredClone, Web Streams, and modern async patterns.
-version: 1.0.0
+  Use this skill when writing, reviewing, or refactoring Node.js >= 22
+  TypeScript code in WrongStack. Triggers: ESM imports, fetch usage, AbortSignal,
+  node: protocol, Web Streams, or any async patterns.
+version: 1.1.0
 ---
 
-# Modern Node.js (>= 22)
+# Modern Node.js (>= 22) — WrongStack
 
-## Imports
+## Imports — always ESM
 
-- Always use `node:` protocol for built-ins: `import * as fs from 'node:fs/promises'`.
-- ESM only — no CommonJS in new code. Use `.js` extension in relative imports.
-- Prefer `import.meta` over `__dirname` (compute via `fileURLToPath`).
+```ts
+// ✅ Always — node: protocol for built-ins
+import * as fs from 'node:fs/promises';
+import { createServer } from 'node:http';
+import { join, resolve } from 'node:path';
+
+// ✅ ESM with .js extension in relative imports
+import { helper } from './helper.js';
+import { types } from '../types/index.js';
+
+// ❌ Never — CommonJS
+const fs = require('fs/promises');
+```
 
-## I/O
+## fetch — native only
 
-- Use `fs.promises` (or `node:fs/promises`). Avoid the callback API.
-- Use native `fetch` — no axios, no node-fetch.
-- Use `AbortSignal` everywhere that takes time: fetch, child_process spawn, timers (via `setTimeout(..., { signal })`).
+```ts
+// ✅ Native fetch (Node 18+)
+const res = await fetch('https://api.example.com/data', {
+  signal: AbortSignal.timeout(5000),
+});
+
+// ❌ Never — axios, node-fetch, got
+const res = await axios.get('https://api.example.com/data');
+```
 
-## Patterns
+## AbortSignal — everywhere that takes time
 
 ```ts
-// Combine signals
+// ✅ Timeout on fetch
+await fetch(url, { signal: AbortSignal.timeout(5000) });
+
+// ✅ Timeout on child_process
+const child = spawn('pnpm', ['test'], { signal: AbortSignal.timeout(30_000) });
+
+// ✅ Combined signals
 const combined = AbortSignal.any([userSignal, timeoutSignal]);
 
-// Atomic write
+// ✅ setTimeout with signal (Node 22+)
+setTimeout(handler, 1000, { signal: userSignal });
+```
+
+## Async patterns
+
+```ts
+// ✅ Atomic write pattern
 import { rename, writeFile } from 'node:fs/promises';
 const tmp = `${target}.${randomBytes(4).toString('hex')}.tmp`;
 await writeFile(tmp, data);
 await rename(tmp, target);
+
+// ✅ Sequential with error handling
+for (const file of files) {
+  try {
+    await processFile(file);
+  } catch (err) {
+    console.error(`Failed ${file}: ${err}`);
+  }
+}
+
+// ✅ Parallel with allSettled (when partial failure is ok)
+const results = await Promise.allSettled(tasks.map(t => t.run()));
+const failures = results.filter(r => r.status === 'rejected');
+```
+
+## Web Streams
+
+```ts
+// ✅ Readable stream from fetch
+const response = await fetch('https://api.example.com/stream');
+const reader = response.body!.getReader();
+const decoder = new TextDecoder();
+while (true) {
+  const { done, value } = await reader.read();
+  if (done) break;
+  process.stdout.write(decoder.decode(value));
+}
 ```
 
 ## Anti-patterns
 
-- `require()` in new code
-- `__dirname` without `fileURLToPath`
-- Mixing `fs.readFile` callback with `await`
-- Swallowing AbortError silently
+| Anti-pattern | Why bad | Fix |
+|---|---|---|
+| `require()` in new code | WrongStack uses ESM | Use `import` with `.js` extension |
+| `__dirname` without `fileURLToPath` | ESM doesn't have `__dirname` | `path.dirname(fileURLToPath(import.meta.url))` |
+| Mixing `fs.readFile` callback with `await` | Callback API doesn't return a promise | Use `fs.promises.readFile` |
+| Swallowing `AbortError` silently | Means timeout/abort happened | Log it or handle explicitly |
+| `process.cwd()` without fallback | May not match user's cwd | Accept `cwd` as a parameter |
+| Not handling `ENOENT` on file reads | File may not exist | Use try/catch or `access` first |
+
+## package.json scripts
+
+```json
+{
+  "scripts": {
+    "dev": "tsx watch src/index.ts",
+    "build": "tsup",
+    "test": "vitest run"
+  }
+}
+```
+
+## TypeScript config for Node 22+
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true
+  }
+}
+```
+
+## Skills in scope
+
+- `typescript-strict` — strict TypeScript patterns
+- `react-modern` — React Server Components with Node.js
+- `bug-hunter` — catching async/await bugs, unhandled rejections

package/skills/prompt-engineering/SKILL.md

@@ -1,28 +1,109 @@
 ---
 name: prompt-engineering
 description: |
-  Use this skill when designing system prompts, tool descriptions, or task
-  instructions for LLM agents. Covers structure, specificity, and common pitfalls.
-version: 1.0.0
+  Use this skill when designing, critiquing, or fixing system prompts,
+  tool descriptions, skill definitions, or LLM instruction text in WrongStack.
+  Triggers: user mentions "prompt", "system instruction", "skill description", "tool hint", "usage hint", "system prompt".
+version: 1.1.0
 ---
 
-# Prompt engineering
+# Prompt Engineering — WrongStack
 
-## Structure
+## WrongStack's 4-layer structure
 
-- Identity → principles → environment → memory. (WrongStack's 4-layer system prompt.)
-- Static content first (cacheable), volatile last.
-- Markdown headings help models parse structure.
+```
+Layer 1: Identity     — Who you are (static, cacheable)
+Layer 2: Tool usage   — Available tools and their usage hints (static)
+Layer 3: Environment  — Project context, skills, modes, plan (semistatic)
+Layer 4: Volatile     — Session state, recent errors, mode prompt (dynamic)
+```
 
-## Tool descriptions
+Static content first. Volatile content last. Cache-friendly prompts cost less per token.
 
-- Describe *when* to use, not just *what*. "Use `read` before `edit`" is more useful than "reads files".
-- Include schema constraints in prose; the JSON schema alone is rarely enough.
-- Give one example for non-obvious tools.
+## Trigger sentences (skill descriptions)
+
+The **first sentence** of a skill description is its trigger. This is the only thing the skill loader matches on.
+
+```
+# Good — specific trigger
+Use this skill when deploying Docker containers to staging.
+
+# Bad — vague
+This skill is about Docker.
+
+# Good — pattern matchable
+Use this skill when writing or reviewing React 19+ code.
+
+# Bad — not actionable
+This skill covers modern React patterns.
+```
+
+## Tool description rules
+
+Every tool in WrongStack has: `name`, `description`, `usageHint`, `inputSchema`.
+
+The `usageHint` is what appears in the system prompt. It must say:
+1. **When to use it** — not just what it does
+2. **Key parameters** — the important inputs
+3. **What it returns** — so the model knows what to do next
+
+```
+# Good
+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.
+
+# Bad
+Search files using grep.
+```
+
+## Common tool chain patterns (for system prompt builder)
+
+```
+Inspect → Edit:    glob/read → locate → edit
+Search → Operate:   grep/glob → identify → batch_tool_use or edit
+Verify → Report:    write/edit/patch → read back → confirm
+Batch Replace:     grep with pattern → replace with glob → verify
+```
 
 ## Anti-patterns
 
-- "Please" / "kindly" — adds tokens, no benefit.
-- "You are a helpful AI assistant" — already implied, wastes tokens.
-- Long preamble before the actual question.
-- Ambiguous pronouns ("do it again") — names beat pronouns.
+| Anti-pattern | Why it's bad | Fix |
+|---|---|---|
+| "Please be helpful" | Wastes tokens, implies the model isn't | Remove it |
+| "You are a helpful AI" | Already implied by default identity | Remove it |
+| "Sure, I'd be happy to" | Same — filler, no information | Remove it |
+| Vague parameter docs | Model doesn't know when to use tool | Add concrete examples |
+| Long preamble before the question | Model reads it, then reads the actual question | Put question first |
+| Ambiguous pronouns | "do it again" — which tool, which file? | Name the specific thing |
+
+## Skill SKILL.md rules
+
+See `skill-creator` skill for the format. Key points:
+- First sentence = trigger condition
+- 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
+- `typescript-strict` — for TypeScript-specific prompt typing
+- `react-modern` — for React component prompt conventions

package/skills/react-modern/SKILL.md

@@ -1,34 +1,120 @@
 ---
 name: react-modern
 description: |
-  Use this skill when writing or reviewing React 19+ code. Covers Server
-  Components vs Client Components, useTransition, Suspense, the `use` hook,
-  Actions, and form state.
-version: 1.0.0
+  Use this skill when writing or reviewing React 19+ code in WrongStack.
+  Triggers: user mentions "React", "component", "useState", "useEffect",
+  "Server Component", "Client Component", "Suspense", "useTransition", "use hook".
+version: 1.1.0
 ---
 
-# Modern React (19+)
+# Modern React (19+) — WrongStack
 
 ## Component types
 
-- Default to Server Components for data fetching and static UI.
-- Mark interactive code with `'use client'` and keep it minimal.
-- Don't pass Server Components into Client Component children unless serialized.
+```tsx
+// ✅ Server Component (default) — for data fetching and static UI
+async function UserList() {
+  const users = await db.query('SELECT * FROM users');
+  return <ul>{users.map(u => <li key={u.id}>{u.name}</li>)}</ul>;
+}
+
+// ❌ Client Component — mark only when needed
+'use client';
+import { useState } from 'react';
+function Counter() {
+  const [count, setCount] = useState(0);
+  return <button onClick={() => setCount(c => c + 1)}>{count}</button>;
+}
+```
+
+Rule: Default to Server Components. Mark `'use client'` only for interactive code. Keep the client boundary minimal.
 
 ## Data fetching
 
-- In Server Components: `await fetch(...)`, server-side caching is automatic with framework support.
-- In Client Components: use a library (TanStack Query) or `use(promise)` for awaitable thenables.
+```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>;
+}
+
+// ❌ Bad — useEffect for data fetching
+useEffect(() => { fetchData().then(setData); }, []);
+```
+
+## State management
+
+```tsx
+// ✅ useState for local state
+const [count, setCount] = useState(0);
+
+// ✅ useTransition for non-urgent updates
+const [isPending, startTransition] = useTransition();
+startTransition(() => {
+  setPage(page + 1);
+});
+
+// ✅ useReducer for state machines
+const [state, dispatch] = useReducer(reducer, initialState);
+
+// ❌ useEffect for derived state
+// Bad: compute during render instead
+const fullName = firstName + ' ' + lastName;
+```
 
-## State
+## Hook rules
 
-- `useState` for local state. `useReducer` for state machines.
-- `useTransition` for non-urgent updates that should not block input.
-- Avoid `useEffect` for derived state — compute during render.
+| Hook | When to use | Anti-pattern |
+|------|-------------|--------------|
+| `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 |
+| `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
+
+- `ref` is a regular prop — no more `forwardRef`
+- Server Components can be nested without serialization
+- `use(promise)` — await thenables directly in components
+- Actions — server functions callable from client
 
 ## Anti-patterns
 
-- `useEffect` to sync local state with props
-- Class components in new code
-- `forwardRef` in new code (React 19 makes `ref` a regular prop)
-- Default exports for components (named exports help refactor tools)
+| Anti-pattern | Why bad | Fix |
+|---|---|---|
+| `useEffect` to sync props to state | Causes extra render, stale data | Use controlled component or lift state |
+| Class components in new code | Deprecated | Use function components + hooks |
+| `forwardRef` in new code | `ref` is a regular prop in React 19 | Pass `ref` as a normal prop |
+| Default exports for components | Hinders refactoring | Named exports |
+| Mixing Server/Client boundaries | Serialization errors | Keep boundary clean |
+
+## TypeScript patterns
+
+```tsx
+// ✅ Props with explicit type
+interface ButtonProps {
+  children: React.ReactNode;
+  onClick?: () => void;
+  variant?: 'primary' | 'secondary';
+}
+
+// ✅ Event handler types
+const handleClick = (e: React.MouseEvent<HTMLButtonElement>) => { ... };
+
+// ✅ useRef with nullable initial
+const inputRef = useRef<HTMLInputElement>(null);
+```
+
+## Skills in scope
+
+- `typescript-strict` — for TypeScript patterns
+- `node-modern` — for React server components with Node.js
+- `bug-hunter` — for React-specific bugs (stale closures, memory leaks)

package/skills/refactor-planner/SKILL.md

@@ -1,49 +1,84 @@
 ---
 name: refactor-planner
 description: |
-  Structured refactoring planning from code analysis. Covers dependency mapping,
-  risk assessment, phased planning, and migration strategy.
-  Use before large rewrites or when technical debt is blocking progress.
-version: 1.0.0
+  Use this skill when planning a multi-file refactor, code modernization,
+  or technical debt resolution in WrongStack. Triggers: user says "refactor",
+  "technical debt", "modernize", "clean up", "restructure", "decompose".
+version: 1.1.0
 ---
 
-# Refactor Planner Agent
+# Refactor Planner — WrongStack
 
-Analyzes code structure and produces a concrete, phased refactoring plan with
-risk assessment, dependency ordering, and rollback considerations.
+Analyzes code structure and produces a phased refactoring plan with risk assessment, dependency ordering, and rollback strategy.
 
-## Capabilities
+## When to use
 
-- Map module-level dependencies (import graph)
-- Identify coupling hotspots (high fan-in/out modules)
-- Assess refactoring risk by cyclomatic complexity and test coverage
-- Generate phased plans with checkpoint milestones
-- Produce diff-friendly task lists (one task = one concern)
+- Multi-file refactors
+- Breaking up large modules
+- Changing public APIs
+- Addressing technical debt
+- Migration to new patterns
 
 ## Workflow
 
-1. **Analyze** — Build dependency graph, count coupling
-2. **Score** — Rate each module by: size, complexity, test coverage, change frequency
-3. **Plan** — Order tasks by risk, dependency, and payoff
-4. **Document** — Output phased markdown plan
+```
+1. Analyze:  Build dependency graph, identify coupling
+2. Score:    Rate each module by size, complexity, test coverage
+3. Plan:     Order tasks by risk, dependency, payoff
+4. Document: Phased markdown plan with checkpoints
+```
+
+## Risk criteria
+
+| Factor | Low Risk | Medium Risk | High Risk |
+|--------|----------|-------------|-----------|
+| Cyclomatic complexity | <10 | 10-20 | >20 |
+| Test coverage | >80% | 50-80% | <50% |
+| Fan-out (imports) | <5 | 5-15 | >15 |
+| Public API surface | unchanged | modified | removed |
+
+## Phase structure
+
+Good refactors have 3 phases:
 
-## Input
+```
+Phase 1: Low Risk / High Payoff
+  - No behavior change
+  - Tests already pass
+  - Quick wins
+
+Phase 2: Medium Risk (test heavily)
+  - Some behavior may change
+  - Significant test coverage needed
+  - May need rollback plan
+
+Phase 3: High Risk (full regression)
+  - Behavior changes expected
+  - Integration tests required
+  - Coordinate with team
+```
+
+## Risk assessment checklist
 
 ```json
 {
-  "task": "plan | assess | roadmap",
-  "target": "src/core | packages/tools | .",
-  "constraint": "no-breaking-changes | minimal-downtime | full-rewrite",
-  "focus": "architecture | performance | maintainability"
+  "module": "src/auth/session.ts",
+  "size": 450,
+  "cyclomatic": 12,
+  "testCoverage": 65,
+  "fanOut": 8,
+  "publicAPI": true,
+  "dependencies": ["core", "providers"],
+  "dependents": ["cli", "tui", "webui"]
 }
 ```
 
-## Output Format
+## Phased plan output
 
 ```
 ## Refactor Plan — <target>
 
-### Phase 1: Low Risk / High Payoff (do first)
+### Phase 1: Low Risk / High Payoff
 | # | Task | Module | Risk | Est. Time |
 |---|------|--------|------|-----------|
 | 1 | Extract `ToolExecutor` interface | core/tool-executor.ts | low | 2h |
@@ -53,12 +88,8 @@ risk assessment, dependency ordering, and rollback considerations.
 | # | Task | Module | Risk | Est. Time |
 |---|------|--------|------|-----------|
 | 3 | Break circular dep: Config ↔ Logger | core/config.ts | medium | 6h |
-| 4 | Split `Context` into read/write slices | core/context.ts | medium | 8h |
 
-### Phase 3: High Risk (requires full regression)
-...
-
-### Dependency Graph (abbreviated)
+### Dependency Graph
 ```
 config.ts → logger.ts → path-resolver.ts
      ↓           ↓
@@ -68,8 +99,9 @@ config.ts → logger.ts → path-resolver.ts
 ```
 
 ### Rollback Strategy
-Each phase commits independently. On failure: `git checkout phase<N>`.
-Run `pnpm test` before advancing.
+- Phase 1: `git checkout` if tests fail
+- Phase 2: Feature flag, can disable
+- Phase 3: Blue-green deployment
 
 ### Exit Criteria
 - [ ] All Phase 1 tasks pass `pnpm test`
@@ -77,18 +109,16 @@ Run `pnpm test` before advancing.
 - [ ] `Context` interface < 20 methods
 ```
 
-## Risk Criteria
+## Anti-patterns
 
-| Factor | Low Risk | Medium Risk | High Risk |
-|--------|----------|-------------|-----------|
-| Cyclomatic complexity | <10 | 10-20 | >20 |
-| Test coverage | >80% | 50-80% | <50% |
-| Fan-out (imports) | <5 | 5-15 | >15 |
-| Change frequency | low | medium | high |
+- **Don't plan without analyzing** — assumptions cause wasted work
+- **Don't skip rollback strategy** — every refactor can fail
+- **Don't over-phase** — if a task takes <1h, merge it
+- **Don't ignore team constraints** — parallelization only works if reviewers exist
+- **Don't skip the dependency graph** — the most important part
 
-## Anti-patterns
+## Skills in scope
 
-- Don't plan without analyzing — assumptions cause wasted work
-- Don't skip rollback strategy — every refactor can fail
-- Don't over-phase — if a task takes <1h, merge it
-- Don't ignore team constraints — parallelization only works if reviewers exist
+- `bug-hunter` — for finding bugs exposed by the refactor
+- `git-flow` — for committing each phase properly
+- `multi-agent` — for parallel analysis of multiple modules