@wrongstack/core 0.308.0 → 0.308.1

package/skills/observability/SKILL.md

@@ -5,7 +5,7 @@ description: |
   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
+version: 1.1.0
 required-capabilities: [filesystem.read, filesystem.write]
 required-tools: []
 optional-capabilities: [code.inspect]
@@ -129,6 +129,30 @@ Every log should include:
 - **Redaction**: Use `redactKeys()` helper — never log `Authorization`, `token`, `apiKey`, `secret`.
 - **Tool tracing**: Each tool wrapper should emit a structured log on start and end.
 
+## Out of scope
+
+- **Don't log secrets, tokens, or PII.** Redact at the boundary. A single `Authorization` header in a log line is a credential leak; redact `token`, `apiKey`, `secret`, `Authorization` keys before they reach the stream.
+- **Don't use plain text logs.** JSON to stdout is the contract. `console.log('User logged in')` is unsearchable and breaks log aggregators.
+- **Don't emit logs without a `traceId`.** Correlation across tools is the whole point. A log without a trace is an event with no story.
+- **Don't use DEBUG level in production.** DEBUG is dev-only. Production logs are `INFO`, `WARN`, `ERROR`; DEBUG in prod is noise that hides real signals.
+- **Don't log and ignore.** Every log entry should answer: what happened, what context, what was the outcome. A `console.log('done')` after a side effect is process for process's sake.
+- **Don't write to file logs from app code.** CI captures stdout. File logs bypass the pipeline and become unsearchable tribal knowledge.
+- **Don't skip trace spans on tool calls.** Every tool wrapper should open a span on start and end it on completion, with timing. Without spans, latency questions are unanswerable.
+- **Don't conflate counters and gauges.** Counters increment (`tool.executions`); gauges track current state (`session.iterations`). Mixing them produces nonsense dashboards.
+- **Don't include exception objects in span attributes.** `span.recordException(err)` is the OpenTelemetry path; serialization into a JSON log is its own discipline.
+
+## Before returning
+
+- [ ] All logs are JSON to stdout, never plain text or file logs
+- [ ] Every entry has `level`, `traceId`, `event`, `timestamp`, `outcome`
+- [ ] No secrets, tokens, `Authorization`, `apiKey`, or PII in any log line
+- [ ] DEBUG level only in dev; production uses `INFO` / `WARN` / `ERROR`
+- [ ] Tool wrappers emit structured start + end events with `duration_ms`
+- [ ] OpenTelemetry spans opened on tool entry, closed on exit with status
+- [ ] Counters vs. gauges respected; histograms used for latency
+- [ ] Redaction centralized at the serialization boundary, not per call site
+- [ ] Log volume and pattern sanity-checked against `audit-log` skill's metrics
+
 ## Skills in scope
 
 - `audit-log` — for analyzing the logs this skill produces

package/skills/output-standards/SKILL.md

@@ -4,7 +4,7 @@ description: |
   Use this skill when defining or enforcing output formatting standards for agent
   responses in WrongStack. Triggers: user says "next steps format", "output standard",
   "response format", "final message format", "standardize next steps".
-version: 1.0.0
+version: 1.1.0
 required-capabilities: []
 required-tools: []
 ---
@@ -156,6 +156,33 @@ When a **subagent** completes its task, it MUST:
 - **Don't assign manual work to the user** — "manually check if X is correct yourself" is not a valid next prompt; when tools permit it, use an agent-directed prompt such as "Use the browser tools to verify X and fix any issue you find"
 - **Don't include `<nextsteps>` in subagent output** — subagents report findings, leaders produce next steps
 
+## Out of scope
+
+- **Don't include `<nextsteps>` in subagent output.** Subagents report findings; the leader produces the unified tag. A subagent that emits `<nextsteps>` is stepping on the leader's lane.
+- **Don't emit parseable-looking prose instead of the tag.** "Next steps:", "Suggested next:", "Let me know if you want..." all look like the tag to the parser and break the `/next` workflow.
+- **Don't put human-only actions in `<nextsteps>`.** "Open DevTools yourself", "manually check the browser console" — those are informational, not agent prompts. They go outside the tag as plain text.
+- **Don't put markdown inside the tag.** Plain text only, one item per line. `**bold**`, code spans, headings — all break the parser.
+- **Don't use dashes or asterisks inside the tag.** Numbered items only: `1.`, `2.`, `3.`. Dash and asterisk bullets are wrong and silently fail the parser.
+- **Don't put `auto="true"` on items 2+.** Only item 1 may carry the marker. The marker on later items is parsed-and-discarded.
+- **Don't write vague prompts.** "Fix bugs" is not a prompt; "fix auth/session.ts:42 and add a regression test" is. The selected text is submitted verbatim — vague prompts are vague runs.
+- **Don't exceed 5 items without reason.** If the list is over 5, it's probably not a single task. Split it or hand off.
+- **Don't emit `<nextsteps>` while `ctx.todos` has open items.** The in-flight todo list isn't done; new prompt options race the todo loop. Finish the list first, re-arm the tag on the turn where the last todo flips to `completed`.
+- **Don't address the user inside the tag.** Items are agent-directed prompt inputs. Imperative wording is valid when it tells the agent what to do.
+
+## Before returning
+
+- [ ] Only the leader emits `<nextsteps>`; subagents return findings only
+- [ ] Tag is well-formed: `<nextsteps>...</nextsteps>`, no attributes on the tags
+- [ ] Plain text only inside the tag; no markdown, dashes, or asterisks
+- [ ] Numbered items `1.`, `2.`, `3.`; one prompt per line
+- [ ] At most one `auto="true"`, and only on item 1
+- [ ] Items are agent-directed prompts, not human-only actions
+- [ ] Items are specific enough to submit verbatim (file:line + concrete action)
+- [ ] At most 5 items unless a single task genuinely requires more
+- [ ] Tag omitted if `ctx.todos` still has pending or in_progress items
+- [ ] Leader output synthesized from subagent findings, deduplicated and re-prioritized
+- [ ] Human-only actions sit outside the tag as plain text, not inside it
+
 ## Skills in scope
 
 - `bug-hunter` — inherits output-standards for bug reports

package/skills/plugin-author/SKILL.md

@@ -7,7 +7,7 @@ description: |
   data, and the entry-point registration steps (package.json and index.ts).
   Triggers: user says "new plugin", "add a plugin", "plugin teardown", "plugin
   health", "register a tool", "PluginAPI extension".
-version: 1.0.0
+version: 1.1.0
 required-capabilities: [filesystem.read, filesystem.write, execution.shell]
 required-tools: [bash, cron_cancel, cron_list, cron_schedule, edit, fetch, git, git_autocommit, json, read, search, secret_scanner_test, semver_bump, semver_changelog, semver_current, todo, watch_list, watch_start, watch_stop, write]
 optional-capabilities: [verification.run]
@@ -336,6 +336,36 @@ For the H1 pattern, extend `tests/plugin-teardown.test.ts` with a
 8. **Run verification**: `pnpm --filter @wrongstack/plugins test` + `pnpm --filter @wrongstack/plugins typecheck` + `pnpm --filter @wrongstack/plugins build`
 9. **Update `src/index.ts` doc comment** — bump the plugin count
 
+## Out of scope
+
+- **Don't put state in the `setup()` closure.** State must live at module scope; the Plugin interface does not thread state from `setup()` to `teardown()`. Closure state leaks on reload.
+- **Don't ship a plugin without `teardown()` and `health()`.** Even stateless plugins add both. The H1 audit pattern is the floor; `/diag plugins` exposes the gap.
+- **Don't make `setup()` non-idempotent.** Calling `setup()` twice must leave a clean slate. Hot-reload must not accumulate state.
+- **Don't delete on-disk state in `teardown()`.** File-based plugins leave the file in place. Only in-memory counters and resource handles (timers, watchers) are cleaned.
+- **Don't collide with built-in tool names.** `read`, `write`, `bash`, `edit`, `fetch`, `search`, `json`, `todo`, `git` are reserved. Pick unique names; `api.tools.register()` enforces uniqueness.
+- **Don't bump `apiVersion` for additive changes.** New optional fields on `PluginAPI` don't break the contract. Bump only when the surface breaks.
+- **Don't read config from `config.plugins`.** Config options go under `config.extensions['<plugin-name>']`. The loader's `buildPluginOptions` merges both, but the convention is `extensions`.
+- **Don't block `setup()` with async hydration.** Use `void (async () => { ... })()` for fire-and-forget. The first call should fall through to fallback if the async hasn't completed.
+- **Don't skip the test files.** `tests/<name>.test.ts` (unit) and `tests/<name>-exec.test.ts` (integration) are required. Plugins without tests rot fast.
+- **Don't lower-case-skip the model and config keys.** Case-insensitive lookup is the convention; `model.toLowerCase()` everywhere.
+
+## Before returning
+
+- [ ] `name`, `version`, `apiVersion: '^0.1.x'` (current), description, capabilities set
+- [ ] Module-scope state, never in `setup()` closure
+- [ ] `setup()` idempotent: clears state before re-initializing
+- [ ] `teardown()` releases every resource acquired in `setup()`, never deletes on-disk state
+- [ ] `health()` returns `{ ok, message, invocationCount, lastRun? }`
+- [ ] Tool names are unique `snake_case`; no collision with built-ins
+- [ ] Config read from `api.config.extensions['<plugin-name>']`, validated by `configSchema`
+- [ ] Hooks are registered via `api.registerHook(...)` with the correct event/matcher; `HookOutcome` shape honored
+- [ ] `src/index.ts` re-exports the plugin; `package.json` adds the subpath export
+- [ ] `packages/cli/src/wiring/plugins.ts` adds the built-in factory
+- [ ] Tests: `<name>.test.ts` + `<name>-exec.test.ts` + `plugin-teardown.test.ts` block
+- [ ] Verification: `pnpm --filter @wrongstack/plugins test && typecheck && build` all pass
+- [ ] `src/index.ts` doc comment updated with the new plugin count
+- [ ] `<nextsteps>` lists each open follow-up (config, hooks, tests, build)
+
 ## Skills in scope
 
 - `skill-creator` — for the SKILL.md format and frontmatter rules

package/skills/prompt-engineering/SKILL.md

@@ -4,7 +4,7 @@ description: |
   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
+version: 1.2.0
 required-capabilities: [filesystem.read, filesystem.write]
 required-tools: []
 ---
@@ -131,6 +131,32 @@ 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
 
+## Out of scope
+
+- **Don't ship filler in prompts.** "Please be helpful", "Sure, I'd be happy to", "You are a helpful AI" — every filler line costs tokens and adds no signal. Strip it.
+- **Don't write vague trigger sentences.** "This skill is about Docker" matches nothing. "Use this skill when deploying Docker containers to a production cluster" matches.
+- **Don't describe a tool by what it does alone.** Tool descriptions need when to use, key parameters, and what it returns. "Search files" is incomplete; "Search file contents with regex. Pattern is regex. Use output_mode to select…" is the bar.
+- **Don't put volatile content before static content.** Cache-friendly prompts put identity, tools, and instructions first; session state and recent errors last. Reversing the order costs tokens per turn.
+- **Don't write a long preamble before the question.** The model reads the preamble, then the question. Put the question first.
+- **Don't use ambiguous pronouns.** "Do it again" — which tool, which file? Name the specific thing.
+- **Don't claim trigger keywords cover a domain they don't.** Trigger keywords must be specific. Generic phrases like "improve" or "help with" match too much and the loader can't disambiguate.
+- **Don't re-invent the agent's identity.** WrongStack's system prompt already establishes who the agent is. Don't repeat it; layer domain-specific instruction on top.
+- **Don't design prompts the way you'd write a doc.** Prompts are instruction; docs are reference. Reference material goes in skill `references/`, not in the trigger-matching body.
+
+## Before returning
+
+- [ ] No filler ("Please be helpful", "Sure, I'd be happy to", "You are a helpful AI")
+- [ ] Skill description's first sentence is a concrete trigger; trigger keywords follow
+- [ ] Tool descriptions cover when to use, key parameters, what it returns
+- [ ] Static content first; volatile content last
+- [ ] No long preamble before the actual question
+- [ ] No ambiguous pronouns; specific things named
+- [ ] Trigger keywords specific enough to disambiguate
+- [ ] Skill body under ~500 lines; deep material in `references/`
+- [ ] Concrete `Do` / `Don't` examples, not abstract principles
+- [ ] `Skill in scope` lists the hand-off targets with a reason for each
+- [ ] `<nextsteps>` mirrors open follow-up prompt-tuning tasks in priority order
+
 ## Skills in scope
 
 - `skill-creator` — for creating new skills (primary — prompt-engineering feeds into skill creation)

package/skills/react-modern/SKILL.md

@@ -4,7 +4,7 @@ description: |
   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
+version: 1.2.0
 required-capabilities: [filesystem.read, filesystem.write]
 required-tools: []
 optional-capabilities: [verification.run]
@@ -207,6 +207,34 @@ const handleClick = (e: React.MouseEvent<HTMLButtonElement>) => { ... };
 const inputRef = useRef<HTMLInputElement>(null);
 ```
 
+## Out of scope
+
+- **Don't default to Client Components.** Server Components are the default in React 19+. Mark `'use client'` only for interactive code; the boundary carries a serialization cost.
+- **Don't reach for `useEffect` when fetching data.** Use Server Components or `use(promise)`. The `useEffect` + fetch + `setState` dance is the pattern React 19 replaced.
+- **Don't reach for `forwardRef` in new code.** `ref` is a regular prop in React 19. `forwardRef` is the old way; the new way is `function Button({ ref, ...props })`.
+- **Don't use default exports for components.** Named exports only. Default exports hinder refactoring and tree-shaking; named exports are the convention.
+- **Don't use class components in new code.** Function components + hooks. Class components are deprecated in modern React.
+- **`useEffect` is the wrong tool for syncing props to state.** It causes an extra render and stale data. Lift state or use a controlled component.
+- **`useMemo` is overkill for trivial calculations.** `useMemo(() => count * 2, [count])` is more expensive than the multiplication. Measure before memoizing.
+- **Don't reach for `useCallback` when deps change every render.** `useCallback(fn, [obj])` where `obj` is fresh each render provides no stability. Reach for it only when child deps actually benefit.
+- **Don't mix Server/Client boundaries carelessly.** Serialization errors at the boundary are some of the hardest to debug. Keep the boundary clean.
+- **Don't call React's `use()` outside component render.** It's a render-only hook.
+
+## Before returning
+
+- [ ] Server Components by default; `'use client'` only for interactive code
+- [ ] No `useEffect` for data fetching; Server Components or `use(promise)` instead
+- [ ] No `forwardRef` in new code; `ref` is a regular prop
+- [ ] Named exports for components; no default exports
+- [ ] No class components in new code; function components + hooks only
+- [ ] Event handlers carry explicit types (`React.MouseEvent<HTMLButtonElement>`)
+- [ ] `useState` for local state; `useReducer` for state machines
+- [ ] `useTransition` for non-urgent updates; `useDeferredValue` for expensive search
+- [ ] `useMemo` / `useCallback` only where profiling showed a need
+- [ ] `useEffect` reserved for side effects (subscriptions, manual DOM, focus); not for derived state or data fetching
+- [ ] Props interface explicit; no `any` or `Function`
+- [ ] `<nextsteps>` mirrors any open follow-up (boundary cleanup, hook refactor, prop typing)
+
 ## Skills in scope
 
 - `typescript-strict` — for TypeScript patterns

package/skills/refactor-planner/SKILL.md

@@ -306,6 +306,16 @@ parallelizes.
 
 ---
 
+## Out of scope
+
+- **Don't start refactoring while planning.** A half-done refactor with no graph behind it is the failure this skill exists to prevent. Plan first, hand the plan to the executing agent phase by phase.
+- **Don't write code or apply edits.** This skill produces a plan, not a diff. If the user wants the refactor done, the executing agent picks it up; this skill's deliverable is the phased plan.
+- **Don't skip the dependency graph.** Ordering without a graph is guessing. Imports are the truth; build the graph from `import` statements, not from directory layout or someone's mental model.
+- **Don't ignore cycles.** A cycle means no valid ordering. List cycles explicitly, schedule their breaking first. A plan over a cycle is fiction.
+- **Don't refactor modules under 50% coverage blind.** Phase 1 of any such module is characterization tests, not the refactor itself. The safety argument is "behavior preserved" — without tests, there is no safety net.
+- **Don't over-phase.** Tasks under 1h merge with related tasks. A 12-phase plan for a 3-day refactor is process for process's sake.
+- **Don't write exit criteria that aren't checkable.** "Code is cleaner" is not an exit criterion. `pnpm test passes` is. If a phase has no checkable exit, it never formally ends.
+
 ## Skills in scope
 
 - `bug-hunter` — for finding bugs exposed by the refactor

package/skills/research-web/SKILL.md

@@ -8,7 +8,7 @@ description: |
   Triggers: user says "research", "current version", "is this still true",
   "latest", "what's new in", "breaking changes", "find current",
   "web research", "search the web", "look up".
-version: 1.0.0
+version: 1.1.0
 required-capabilities: [web.research]
 required-tools: [context_manager, delegate, fetch, search]
 optional-capabilities: [runtime.admin]
@@ -335,6 +335,33 @@ Agent: search("TypeScript null check best practices") // NO
 7. CITE       — In your response, cite sources for every factual claim
 ```
 
+## Out of scope
+
+- **Don't claim a version, deprecation, or API surface from training memory.** Verify against a live source. The cutoff is wrong; the registry is right.
+- **Don't research-loop.** 2–3 searches + 1–2 fetches per topic. If the answer isn't there after that, surface the ambiguity, don't keep searching.
+- **Don't re-research what you've already injected.** Once a finding is in `context_manager` notes, future turns see it. Re-searching the same topic is a context-bloat failure.
+- **Don't fetch URLs you guessed.** Search first, fetch the result. `fetch("https://react.dev/blog/2025/03/15/...")` is a 404 waiting to happen.
+- **Don't inject raw search results.** Inject a structured summary, not a JSON dump of `search(...)`. Future turns need to parse, not re-read.
+- **Don't cite a single source as fact.** Two-source minimum for a claim; one-source is tentative. Tertiary sources (Reddit, SO, LLM-generated content) need corroboration.
+- **Don't accept a Medium post as ground truth.** Source tiers matter: primary (official docs, GitHub, registries) is fact; secondary is "according to"; tertiary needs corroboration.
+- **Don't research during tactical work.** "Fix the null deref" doesn't need web search. Research mode is for analysis and discussion phases, not bug fixes.
+- **Don't skip the null-result note.** A "no current changes found" note prevents the next turn from re-researching the same topic. Always include it.
+- **Don't spend $0.50 on a version check.** Cost awareness: a quick lookup is 1 search + 1 fetch ≈ 2000 tokens. Landscape surveys justify $2.00; version checks don't.
+
+## Before returning
+
+- [ ] Every claim cites a source URL; domain minimum, date when visible
+- [ ] Two-source minimum for important claims; single-source labeled tentative
+- [ ] Tertiary sources corroborated before citing
+- [ ] Recency checked: version claims ≤ 6 months old; ecosystem trends from current year
+- [ ] Findings injected via `context_manager` `add_note` with structured summary
+- [ ] Null-result note included when no current changes found
+- [ ] Search→fetch→validate→inject→cite workflow followed
+- [ ] Stop rule honored: 2–3 searches + 1–2 fetches per topic; no loops
+- [ ] Cost aligned with answer value; no $0.50 version checks
+- [ ] No research done for tactical work that doesn't need it
+- [ ] `<nextsteps>` lists any open follow-up research or pending validation
+
 ## Skills in scope
 
 - `tech-stack` — for package version verification and ecosystem validation

package/skills/sdd/SKILL.md

@@ -129,6 +129,24 @@ Stage shown in real-time. Pause stops after current iteration completes.
 - **Spec without acceptance criteria** — how do you know when it's done?
 - **Skipping /sdd for urgent tasks** — the spec is what makes "urgent" possible
 
+## Out of scope
+
+- **Don't start coding before the spec exists.** You'll rewrite the code anyway — the spec is what makes the rewrite possible. SDD comes first or the spec is fiction.
+- **Don't accept a spec without acceptance criteria.** "Done" must be a checkable state. Without criteria, the task has no formal end and the verifier has nothing to run.
+- **Don't write vague requirements.** "Improve auth" is not a requirement; "Users authenticate via OAuth2 with PKCE, sessions expire after 24h" is. If a requirement can't be tested, it's not a requirement.
+- **Don't skip `/sdd` because the task is urgent.** Urgency without a spec produces urgency-shaped rework. The spec is what makes "urgent" possible to ship correctly.
+- **Don't start a multi-file refactor from SDD.** When the spec reveals a refactor, delegate to `refactor-planner` for the phased plan. SDD defines the goal; refactor-planner sequences the work.
+- **Don't execute the task graph yourself unless the user asks.** SDD produces the plan and task graph; an executor (the leader, a subagent, or the user) picks it up.
+
+## Before returning
+
+- [ ] Spec has explicit acceptance criteria the verifier can run as commands
+- [ ] Every requirement is specific enough to be tested, not "improve X"
+- [ ] Tasks have dependencies; no orphan tasks at the leaves
+- [ ] Spec template matches the work type (feature/bugfix/refactor/infra/integration/cli-command)
+- [ ] Multi-file refactors are routed to `refactor-planner`, not absorbed into SDD tasks
+- [ ] Critical path called out; bottlenecks named; parallel groups identified
+
 ## Skills in scope
 
 - `refactor-planner` — when the spec reveals a multi-file refactor

package/skills/security-scanner/SKILL.md

@@ -4,7 +4,7 @@ description: |
   Use this skill when scanning code or configuration for security vulnerabilities
   in WrongStack. Triggers: user says "security", "vulnerability", "CVE", "secret",
   "injection", "XSS", "SQL injection", "audit security", "supply chain".
-version: 1.2.0
+version: 1.3.0
 required-capabilities: [filesystem.read, code.inspect]
 required-tools: []
 optional-capabilities: [dependencies.manage]
@@ -167,6 +167,30 @@ element.textContent = userInput;
 </nextsteps>
 ```
 
+## Out of scope
+
+- **Don't echo a full secret in the report.** Redact. A `ghp_…36 chars` is enough for the reader to find and rotate it. The unredacted value in a report is itself a leak.
+- **Don't flag a `file:line` you haven't read.** Generic patterns cause false positives; verify the line is real before reporting. No "looks like a secret" findings.
+- **Don't flag test fixtures as leaked secrets.** Mock credentials in `tests/` and `__fixtures__` are expected. Skip them; flag leaks in production code.
+- **Don't scan `node_modules`.** Use `npm audit` / `pnpm audit` for supply chain. Grepping `node_modules` is a noise machine.
+- **Don't report without remediation.** "Found X" without "do Y" is a finding the user has to research themselves. Always include the fix.
+- **Don't claim CRITICAL without proof of exploitability.** Severity ladders are real. A pattern hit is a lead, not a warrant. State the input that triggers the bug and the consequence.
+- **Don't bypass dependency audit.** Supply chain is an attack vector; skipping `npm audit` / lockfile review is skipping the scanner.
+- **Don't disable TLS or relax auth configs as a "config option" without flagging CRITICAL.** TLS disabled in production is a CRITICAL, not a config note.
+
+## Before returning
+
+- [ ] Every `file:line` opened and confirmed; no flag from a regex guess
+- [ ] Secrets redacted in the report (prefix + char count, never the value)
+- [ ] Test fixtures skipped for secrets; flagged only for leak/unawaited patterns
+- [ ] `node_modules` not scanned; supply chain via `npm audit` / lockfile review
+- [ ] Every finding carries a remediation; "found X" without "do Y" not shipped
+- [ ] Severity passes the ladder; CRITICAL reserved for proven exploitability
+- [ ] Dependency audit included; CVE/version drift covered
+- [ ] TLS / HTTP / CORS / rate-limit configuration checked and reported
+- [ ] False-positive rate called out with a cause when it exceeds 30%
+- [ ] Summary counts match the findings listed; `<nextsteps>` mirrors them in severity order
+
 ## Skills in scope
 
 - `bug-hunter` — for general code quality bugs found during security scan

package/skills/skill-creator/SKILL.md

@@ -3,7 +3,7 @@ name: skill-creator
 description: |
   Use this skill when the user wants to create a new AI skill in WrongStack.
   Triggers: user says "create a skill", "new skill", "add a skill", "skill definition".
-version: 1.2.0
+version: 1.3.0
 required-capabilities: [filesystem.write, runtime.admin]
 required-tools: [bash, skill]
 ---
@@ -162,6 +162,30 @@ Before writing the file, verify:
 - [ ] Content is actionable (rules, patterns, not just prose)
 - [ ] File will be placed in `.wrongstack/skills/`
 
+## Out of scope
+
+- **Don't write skills without running `/skill-gen validate <name>` first.** A name that collides with an existing skill or breaks the kebab-case rule is a wall hit after the file is written. Validate first, always.
+- **Don't ship a skill with a vague description.** "This skill is about Docker" matches nothing. First sentence = trigger; rest = `Triggers: user says "..."` listing concrete keywords.
+- **Don't name skills in PascalCase or with underscores.** `MySkill` and `my_skill` are wrong; only `my-skill` (kebab-case) loads. The loader rejects the others.
+- **Don't place project skills outside `.wrongstack/skills/<name>/`.** Bundled, user-profile, and foreign paths are for other owners. User-created skills always go in the project directory.
+- **Don't write prose-only skills.** Rules, patterns, anti-patterns, code examples — the content has to be actionable. Prose without a checkable rule does not constrain the model.
+- **Don't skip "Skills in scope".** Without the hand-off list, the model doesn't know where to delegate adjacent questions. The list is what makes the skill part of a system.
+- **Don't forget to bump the version on structural change.** New section, scope change, rule change → major or minor bump. Patch only for wording.
+- **Don't move work into the skill that belongs in `/skill-gen`.** The sub-commands are the deterministic layer: validation, scaffolding, from-prompt conversion. The wizard is for the parts they can't do.
+
+## Before returning
+
+- [ ] Name is kebab-case; `/skill-gen validate <name>` passed
+- [ ] Name doesn't collide with bundled, project, or user-profile skills
+- [ ] First sentence of `description` is a concrete trigger; trigger keywords follow
+- [ ] File path is `.wrongstack/skills/<name>/SKILL.md` for project skills
+- [ ] Content is actionable: rules, patterns, anti-patterns, code examples
+- [ ] "Out of scope" lists what the skill is NOT for and where to hand off
+- [ ] "Before returning" gives the model a mechanical completion check
+- [ ] "Skills in scope" names the hand-off targets and the reason for each
+- [ ] Version bumped appropriately; change recorded in CHANGELOG.md
+- [ ] `/skill-gen validate <name>` re-run after writing; loads cleanly
+
 ## Skills in scope
 
 - `prompt-engineering` — for crafting the skill description and prompt text

package/skills/tech-stack/SKILL.md

@@ -4,7 +4,7 @@ description: |
   Use this skill when validating package versions, checking for outdated dependencies,
   or evaluating third-party libraries in WrongStack. Triggers: user says "dependency",
   "package version", "outdated", "npm audit", "deprecated package", "tech stack".
-version: 1.2.0
+version: 1.3.0
 required-capabilities: [dependencies.manage]
 required-tools: []
 optional-capabilities: [web.research]
@@ -112,6 +112,30 @@ When APPROVED:
 </nextsteps>
 ```
 
+## Out of scope
+
+- **Don't trust version numbers from the model.** Training data is stale. The registry is the truth; fetch the latest version from the registry, not from memory.
+- **Don't recursively analyze transitive dependencies.** This skill is single-shot. 1–2 iterations: detect → search registry → verify → report. Deep dependency analysis is a different workflow.
+- **Don't greenlight prehistoric technology.** Anything superseded ≥5 years ago is rejected by default. Use the per-ecosystem built-in preference map.
+- **Don't add a third-party package when the standard library covers it.** Prefer built-in. Every modern runtime ships an obsoleting API; check the built-in map before greenlighting any dependency.
+- **Don't accept a dead package.** A package with no release in >2 years and unresolved critical issues is dead; suggest a maintained replacement. "Deprecated" / "yanked" / "archived" are the dead signals, not opinions.
+- **Don't pick a random ecosystem.** Detect from project files first; ask when multiple markers exist; default to JavaScript only when `package.json` is present and nothing else is.
+- **Don't deep-dive CVEs.** Known-CVE work is `security-scanner`'s lane. This skill validates existence, version, and deprecation — not vulnerability surface.
+- **Don't approve without a registry URL.** The reader needs to verify; cite the registry endpoint that was actually fetched.
+
+## Before returning
+
+- [ ] Ecosystem detected (explicit or via project file scan)
+- [ ] Registry endpoint fetched; package existence verified
+- [ ] Latest version pulled from the registry, not from training memory
+- [ ] Dead-package signals checked (`deprecated`, yanked, archived)
+- [ ] Prehistoric-tech check ran against the per-ecosystem preference map
+- [ ] Built-in vs. third-party preference map consulted
+- [ ] Status is APPROVED / REJECTED / NEEDS_INVESTIGATION with one-sentence verdict
+- [ ] On REJECTED, modern alternative named with a migration step
+- [ ] Registry URL cited so the reader can verify
+- [ ] No transitive dependency recursion; single-shot budget honored
+
 ## Skills in scope
 
 - `node-modern` — for Node.js built-in vs. third-party decisions

package/skills/testing/SKILL.md

@@ -4,7 +4,7 @@ description: |
   Use this skill when writing, reviewing, or improving tests in WrongStack.
   Triggers: user says "test", "unit test", "integration test", "e2e", "mock",
   "vitest", "coverage", "assert", "expect", "test strategy", "write tests".
-version: 1.0.0
+version: 1.1.0
 required-capabilities: [filesystem.read, verification.run]
 required-tools: []
 optional-capabilities: [execution.shell]
@@ -165,6 +165,30 @@ coverageThreshold: {
 - **pnpm workspaces**: Run `pnpm test` in the package root, or `pnpm -r test` for all packages.
 - **Vitest config**: Each package has its own `vitest.config.ts`.
 
+## Out of scope
+
+- **Don't test internal modules.** Test the public API surface. Mocking `../src/internal/helper` couples the test to implementation; the moment the helper moves, the test breaks for the wrong reason.
+- **Don't commit test-only deps to `dependencies`.** Devs install `devDependencies`. Test-only deps in `dependencies` bloat the production install and can leak into runtime code.
+- **Don't lower the coverage gate to make tests pass.** New code carries its own ≥70% coverage; existing coverage never decreases. A passing test suite with sinking coverage is regression, not progress.
+- **Don't write async tests without a timeout.** `test(..., { timeout: 5000 })` is mandatory. A hang in CI is a worse failure than a flapping test.
+- **Don't mock `node:fs` and forget cleanup.** `vi.restoreAllMocks()` and `vi.useRealTimers()` in `afterEach` are mandatory. Mocks leaking across tests are how unit tests go red in a clean checkout.
+- **`setTimeout` is the wrong timeout primitive in tests.** `AbortSignal.timeout()` is the WrongStack convention. A timer, not a signal, bypasses the abort plumbing.
+- **Don't import from `dist/`.** Subpath exports are the entry point. `dist/` is build output; tests against it depend on the build having been run.
+- **Don't report a coverage percentage from a partial run.** Coverage is the full suite, not a subset. A 90% on 60% of the files is not 90%.
+
+## Before returning
+
+- [ ] Tests co-located: `src/foo.ts` → `tests/foo.test.ts` in the same package
+- [ ] Public API only; no internal-module mocks
+- [ ] Async tests carry an explicit timeout (`{ timeout: 5000 }` or appropriate)
+- [ ] `vi.restoreAllMocks()` and `vi.useRealTimers()` in `afterEach`
+- [ ] `AbortSignal.timeout()` used for timeouts, not `setTimeout`
+- [ ] No new `dependencies` entries for test-only packages
+- [ ] Coverage gate met: new code ≥70%, existing coverage not reduced
+- [ ] Coverage from full suite, not partial run
+- [ ] Failing tests pair with the code under test, not staged in a separate commit
+- [ ] `<nextsteps>` mirrors the open test gaps in priority order
+
 ## Skills in scope
 
 - `bug-hunter` — for turning test failures into concrete bugs

package/skills/typescript-strict/SKILL.md

@@ -4,7 +4,7 @@ description: |
   Use this skill when writing or reviewing TypeScript code with strict mode
   in WrongStack. Triggers: user mentions "TypeScript", "strict", "type error",
   "type safety", "narrowing", "branded type", "discriminated union", "noUncheckedIndexedAccess".
-version: 1.1.0
+version: 1.2.0
 required-capabilities: [filesystem.read, filesystem.write]
 required-tools: []
 optional-capabilities: [verification.run]
@@ -235,6 +235,35 @@ const len: number = str?.length ?? 0;
 console.log(name!.toUpperCase());
 ```
 
+## Out of scope
+
+- **Don't use `as any` or double assertions to silence errors.** Validate or narrow values at trust boundaries. A cast that hides a real type error is a bug surfaced later in runtime.
+- **Don't use `!` non-null assertion.** `name!.toUpperCase()` silences the type checker without explanation. Use a narrow check or an assertion function.
+- **`Function` and `Object` types are too broad.** They're `any`-shaped in disguise. Be specific.
+- **Don't return `Promise<any>`.** `Promise<unknown>` or a generic. `Promise<any>` loses the type information the caller needs.
+- **Don't omit return types on exported functions.** Without an explicit return type, exported functions hide errors and let callers assume any shape. Annotate public APIs.
+- **Don't use optional chaining chains to dodge narrowing.** `a?.b?.c?.d` is "I don't know what `a` is" with a costume. Verify with `if (a)` first.
+- **Don't loosen `noUncheckedIndexedAccess` to make tests pass.** It is the safety net. Once it's off, array access silently returns `T` instead of `T | undefined` and `undefined` slips through.
+- **Don't mix `enum` and union types.** Pick one per project. `enum` is the legacy form; const-asserted string unions are the modern form.
+- **Don't write code that compiles under `strict: false`.** WrongStack runs with `strict`, `noUncheckedIndexedAccess`, `noImplicitReturns`, and `exactOptionalPropertyTypes`. Code that only compiles under relaxed flags is the kind of debt this skill exists to prevent.
+- **Don't accept `unknown` without narrowing at the use site.** `unknown` is the safe top type; leaving it un-narrowed is a typed-any escape hatch.
+
+## Before returning
+
+- [ ] No `as any` or double assertions; validation/narrowing at boundaries
+- [ ] No `!` non-null assertion; narrow checks or assertion functions instead
+- [ ] No `Function` or `Object`; specific function/object types used
+- [ ] No `Promise<any>`; `Promise<unknown>` or generic
+- [ ] Exported functions carry explicit return types
+- [ ] `noUncheckedIndexedAccess` honored; `T | undefined` handled at every index access
+- [ ] `exactOptionalPropertyTypes` honored; `prop?: T` and `prop: T | undefined` distinguished
+- [ ] Discriminated unions used over optional fields where state is finite
+- [ ] `assertNever` in `default:` of exhaustive switches
+- [ ] Branded types for invariant strings (`UserId`, `SessionId`)
+- [ ] `strict`, `noUncheckedIndexedAccess`, `noImplicitReturns`, `exactOptionalPropertyTypes` in `tsconfig.json`
+- [ ] `pnpm run typecheck` passes before merge
+- [ ] `<nextsteps>` mirrors open follow-ups (cast removals, narrowing gaps, tsconfig tightening)
+
 ## Skills in scope
 
 - `node-modern` — for TypeScript + ESM patterns

package/skills/wrongstack-kanban/SKILL.md

@@ -6,6 +6,7 @@ description: |
   managed Backlog→Todo→Running→Review→Done lifecycle, lease-fenced dispatch,
   and what "verified" means before a card reaches Done.
 trigger: working with the kanban tool, managing project work through boards, or advancing a managed card's lifecycle
+version: 1.0.0
 required-capabilities: [work.plan]
 required-tools: [kanban]
 ---
@@ -127,6 +128,29 @@ filled in as it becomes known.
 | Omitting unfinished Todo/task/plan rows | Requirement identity and coverage would be lost |
 | Inventing subtasks for a leaf card | Recursive decomposition to satisfy process, not the work |
 
+## Out of scope
+
+- **Don't create a card for trivial work.** A quick read, a one-line fix, or a question does not need a card. Resume the existing card for the same request instead of creating a duplicate.
+- **Don't claim a task is done in chat without a board mutation.** Chat-only completion is fake progress. Persist via `kanban` actions; the board is the shared record.
+- **Don't skip lifecycle stages on a managed board.** Managed cards move exactly one stage at a time. The guard rejects jumps; trying to bypass it is a bug.
+- **Don't work an unclaimed card.** Another agent may be working it. Take `claim_task` first (via `kanban`), or let the Director's queue claim for you.
+- **Don't lose the lease.** Heartbeat before the lease expires. An expired lease is recovered by the supervisor and the card returns to the queue.
+- **Don't fence-less write.** Pass `expectedLeaseId` on every `mark_assignment` and `heartbeat_assignment`. If your lease was recovered, an unfenced write corrupts the successor's state.
+- **Don't invent children for a leaf card.** Atomic work is one childless leaf. Recursive decomposition to satisfy process is process for process's sake.
+- **Don't try to influence dispatch order.** Selection is deterministic by priority, column, order, and creation time. Shuffling tasks or boards doesn't change it.
+- **Don't block on Kanban persistence.** If a board write fails, say so and keep working. The board follows the work; the work does not wait on the board.
+
+## Before returning
+
+- [ ] Substantial work has a card with `description`, `assignee`, and `successCriteria` set
+- [ ] Card claimed via `claim_task` (or Director queue) before any work started
+- [ ] Lease heartbeated within the lease window
+- [ ] Every material action produced a board mutation (no chat-only claims of progress)
+- [ ] `mark_assignment` and `heartbeat_assignment` carried `expectedLeaseId`
+- [ ] Completion went through the verifier; "Done" means the verifier actually ran
+- [ ] Todo/task/plan rows preserve `kanbanBoardId` / `kanbanTaskId` bindings in full-list updates
+- [ ] Card count scaled to the size of the work; no invented subtasks
+
 ## Related skills
 
 - `sdd` — spec-driven development creates boards from task graphs

package/skills/wrongstack-mailbox/SKILL.md

@@ -8,7 +8,7 @@ description: |
   mailbox", "send to WrongStack", "wrongstack mail", "broadcast to the
   fleet", "tell the wrongstack agents", "is anyone online in
   wrongstack", or "register me with wrongstack".
-version: 1.0.0
+version: 1.1.0
 required-capabilities: []
 required-tools: [mailbox]
 optional-capabilities: [mcp.dynamic, web.research]
@@ -738,6 +738,34 @@ mailbox serve` standalone all work. The first one to come up for a
 given project starts the bridge; subsequent surfaces join it via the
 per-project lock.
 
+## Out of scope
+
+- **Don't open Mailbox files directly.** No `_mailbox.sqlite`, no legacy JSONL, no bridge locks, no token files. The bridge and `mb()` / `mbWithBootstrap()` are the only paths; bypassing them breaks trust and audit.
+- **Don't impersonate `hq@...` or another agent.** Use a stable, honest `agentId` for your own identity. The bridge does not enforce sender identity; impersonation is on you, and it's the kind of thing that gets the bridge shut down.
+- **Don't hardcode the token.** Read it from `.mailbox.token`, `.mailbox-bridge.lock`, or accept it from the user. Re-read after a 401. Tokens rotate on every fresh bridge start.
+- **Don't let requests hang.** `AbortSignal.timeout(10_000)` is mandatory. The mailbox is local; 10 s is generous, and a hung bridge will wedge the agent.
+- **Don't poll faster than 1 Hz.** The bridge enforces 120 req/min/token. Polling at sub-second rates hits the limit and looks like a flooding attempt.
+- **Don't use SSE events as authoritative.** `GET /mailbox/events` is a wake-up hint, not a snapshot. After every event, reconcile through `/mailbox/query` or `/mailbox/check`.
+- **Don't broadcast without thinking.** `to: "*"` reaches every online agent. One broadcast per task, with a clear subject. The WebUI marks broadcasts with a different color and humans notice noise.
+- **Don't ack in a loop when `ack-many` fits.** If you have more than one unread message, use `/mailbox/ack-many` — one request, one lock, one rewrite.
+- **Don't skip `register_self`.** Without registration, the WebUI can't show you as online, and heartbeats are unreconciled.
+- **Don't randomize your `agentId`.** Read receipts and history break if your id changes every poll. Pick a stable convention and reuse it.
+- **Don't promise features the bridge doesn't expose.** The bridge is mailbox only. For the full WrongStack tool surface, use `wstack mcp serve`; for SMTP/IMAP, push back — WrongStack's mailbox is internal.
+
+## Before returning
+
+- [ ] No Mailbox files opened or edited directly; bridge and `mb()` only
+- [ ] Stable, honest `agentId`; no impersonation of `hq@...` or other agents
+- [ ] Token read from `.mailbox.token` or `.mailbox-bridge.lock`, not hardcoded
+- [ ] `mbWithBootstrap()` used for discovery when env vars aren't set
+- [ ] All requests carry `AbortSignal.timeout(10_000)`
+- [ ] `register_self` called with stable name and role before any traffic
+- [ ] Heartbeat every 30 s; `deregister_self` on clean shutdown
+- [ ] SSE preferred for real-time; polling ≥ 1 Hz, ≤ 5–10 s
+- [ ] `ack-many` used when more than one message needs acknowledgement
+- [ ] Broadcast only with clear subject, at most once per task
+- [ ] Bridge health (`/healthz`) probed before relying on routes
+
 ## Skills in scope
 
 - `node-modern` — `AbortSignal.timeout`, ESM-only imports.