@wrongstack/core 0.308.0 → 0.308.2

package/skills/docker-deploy/SKILL.md

@@ -5,7 +5,7 @@ description: |
   with Docker. Triggers: user says "docker", "container", "dockerfile",
   "image", "docker-compose", "deploy", "containerize", "registry",
   "multi-stage", "distroless".
-version: 1.0.0
+version: 1.1.0
 required-capabilities: [filesystem.read, filesystem.write, execution.shell]
 required-tools: []
 ---
@@ -149,6 +149,31 @@ trivy image --exit-code 1 --ignore-unfixed --severity HIGH,CRITICAL wrongstack:$
 - **Session storage**: Sessions are stored at `WRONGSTACK_SESSION_ROOT` — mount a volume for persistence.
 - **Config**: Config is at `WRONGSTACK_CONFIG_DIR` — mount for config persistence across restarts.
 
+## Out of scope
+
+- **Don't run as root in the container.** A non-root user is mandatory. A container compromise that lands root on the host is the failure this rule exists to prevent.
+- **Don't use `node:latest` or unversioned base images.** Pin to `node:22-alpine` (or current). Reproducibility starts at the base.
+- **Don't bake secrets into the image.** Pass via environment variables at runtime. A `RUN echo $API_KEY > /app/config.key` is a permanent secret in the image layer.
+- **Don't skip the `.dockerignore`.** Without it, `node_modules`, `dist`, `.git`, and `*.test.ts` end up in the image — bigger, slower, more attack surface.
+- **Don't tag production images `latest`.** Tag with the git SHA. `latest` is a moving target; production needs a specific commit.
+- **Don't ship without a `HEALTHCHECK`.** Orchestrators need a probe; an image without one can't be load-balanced cleanly.
+- **Don't skip image scanning.** `trivy image` or `docker scout` before push. Critical vulnerabilities are blocking.
+- **Don't mix build and runtime stages.** Multi-stage is the rule: build with dev deps, runtime with production deps only. A 1GB image is a build hygiene failure.
+- **Don't deploy without persistent volume mounts.** Sessions at `WRONGSTACK_SESSION_ROOT` and config at `WRONGSTACK_CONFIG_DIR` need volumes; container restarts lose data otherwise.
+
+## Before returning
+
+- [ ] Multi-stage build; runtime stage is production-deps only
+- [ ] Base image pinned to a specific tag (`node:22-alpine`, not `latest`)
+- [ ] Non-root user; `USER wrongstack` set before `ENTRYPOINT`
+- [ ] Secrets via env at runtime, not baked into the image
+- [ ] `.dockerignore` excludes `node_modules`, `dist`, `.git`, `*.test.ts`
+- [ ] Image tagged with git SHA, not `latest`
+- [ ] `HEALTHCHECK` directive points to the CLI's self-check command
+- [ ] `trivy image` or `docker scout` run before push; critical vulns blocked
+- [ ] Volumes mounted for `WRONGSTACK_SESSION_ROOT` and `WRONGSTACK_CONFIG_DIR`
+- [ ] Build runs from repo root with `pnpm build` before `docker build` (workspace order)
+
 ## Skills in scope
 
 - `security-scanner` — for scanning Dockerfiles and container configs for vulnerabilities

package/skills/git-flow/SKILL.md

@@ -4,7 +4,7 @@ description: |
   Use this skill when proposing, reviewing, or troubleshooting git commits,
   branches, pull requests, or merge strategies in a WrongStack project session.
   Triggers: user mentions "commit", "branch", "PR", "merge", "rebase", "stash", "diff".
-version: 1.2.0
+version: 1.3.0
 required-capabilities: [version-control.manage]
 required-tools: [test]
 ---
@@ -154,6 +154,31 @@ git rebase main && git merge --ff-only feature
 Open a PR at GitHub linking to issue #123 with the commit message describing the fix.
 ```
 
+## Out of scope
+
+- **Don't force-push shared branches.** `--force-with-lease` on your own branch is the cap; shared branches get a PR + merge, never a force.
+- **Don't commit lockfile changes with logic changes.** Separate commits, separate rollbacks. A lockfile muddied with a feature commit is impossible to bisect.
+- **Don't make "Update stuff" mega-commits.** One concern per commit. 15 packages in one commit is process for process's sake.
+- **Don't branch from branches.** Always branch from `main` or a stable release tag. Branching from a feature branch is git history debt.
+- **Don't write a "what" commit message.** "fix: fixed bug" tells the reader nothing. Subject ≤ 72 chars, imperative mood, body explains why.
+- **Don't `git reset --hard` with uncommitted work.** Stash first. A hard reset that loses work is the kind of incident a `git-flow` skill exists to prevent.
+- **Don't amend a pushed commit.** It rewrites shared history. Open a follow-up commit or revert.
+- **Don't leave WIP commits on `main`.** Use `git stash` or a feature branch, not a commit message like "WIP".
+- **Don't skip self-review.** Self-review the diff before requesting review. Sending a diff the author hasn't read wastes the reviewer's time.
+
+## Before returning
+
+- [ ] Branch is from `main` or a stable release tag, not from another feature branch
+- [ ] One concern per commit; lockfile changes isolated
+- [ ] Subject ≤ 72 chars, imperative, no trailing period; body explains why
+- [ ] Issue reference included (`Fix #123` or `Closes GH-456`)
+- [ ] Self-review done before requesting review
+- [ ] No `git push --force` to shared branches; `--force-with-lease` only on own branch
+- [ ] Branch deleted after merge (unless shared or releasing)
+- [ ] PR title follows commit format; body links the issue and lists changed files
+- [ ] No `WIP` or "Update stuff" commits in the history
+- [ ] `<nextsteps>` mirrors the recommended commit/PR actions
+
 ## Skills in scope
 
 - `refactor-planner` — when a refactor involves multiple git-managed changes

package/skills/mailbox-bridge/SKILL.md

@@ -8,7 +8,7 @@ description: |
   bridge". Starts a loopback HTTP façade over the same GlobalMailbox that
   WrongStack-internal agents already share, so any agent with curl or
   fetch can read, send, and acknowledge messages.
-version: 1.0.0
+version: 1.1.0
 required-capabilities: [execution.shell]
 required-tools: []
 optional-capabilities: [web.research]
@@ -342,6 +342,30 @@ is 15 s.
   audit trails of which external agent called which route are needed,
   the agent itself should log them client-side.
 
+## Out of scope
+
+- **Don't expose the bridge on `0.0.0.0` without a trusted reverse proxy.** Loopback binding makes "reach" require shell access on the host. LAN exposure without re-authentication and rate-limiting at the proxy is a trust leak.
+- **Don't log the bearer token.** The structured `mailbox_serve_started` event includes bind URL, port, project dir, and token path — never the token itself. Logging it once is a permanent compromise.
+- **Don't treat the bearer as identity-bound.** Every caller uses the same project token. The bridge does not separately authorize `steer`/control messages or prevent impersonation; the caller can claim any `from`, `type`, or `readerId`. Add an identity-aware trusted proxy before exposing beyond mutually trusted local clients.
+- **Don't expose the filesystem, shell, or non-mailbox tools through the bridge.** It is the mailbox surface only. If a caller needs more, they need a different bridge.
+- **Don't start the bridge for an external agent that already speaks MCP natively.** Use `wstack mcp serve` to expose WrongStack's full tool registry including the mailbox tool. Two bridges for the same purpose is operational debt.
+- **Don't run as a long-lived daemon for the caller.** The bridge is short-lived; spawn it for the duration of the caller's session and let it exit. `mbWithBootstrap()` is the pattern.
+- **Don't hardcode a token into prompts or committed code.** Read it from `.mailbox.token` or accept it from the environment; re-read after a 401.
+- **Don't send `control` messages through the bridge.** Control is a runtime-only surface; the bridge doesn't expose it, and the only legitimate override is `steer` via the `mailbox_manage` route, not through the bridge.
+
+## Before returning
+
+- [ ] `wstack mailbox serve` (or `mbWithBootstrap`) used; no parallel implementation
+- [ ] Bind address is `127.0.0.1` unless behind a reverse proxy that re-authenticates
+- [ ] Bearer token read from `.mailbox.token` or env, not hardcoded
+- [ ] Token not present in any log line, event, or error message
+- [ ] Body cap of 256 KB enforced; rate limit of 120/min/token enforced
+- [ ] `/healthz` reachable; no auth or rate limit on the health probe
+- [ ] Pair with `wrongstack-mailbox` skill for external-agent usage
+- [ ] Graceful shutdown handles SIGINT/SIGTERM, flushes the cache, unlinks the token
+- [ ] Mailbox health watchdog wired if running unattended
+- [ ] No `control` messages; `steer` only via the canonical `mailbox_manage` route
+
 ## Skills in scope
 
 - `prompt-engineering` — for the external-facing `wrongstack-mailbox`

package/skills/mnemosyne/SKILL.md

@@ -4,7 +4,7 @@ description: |
   Use when curating WrongStack SAGE memory: run deterministic hygiene and
   anchor verification first, then review contradictions, drift, and noise;
   file destructive outcomes as review proposals instead of deleting directly.
-version: 1.1.0
+version: 1.2.0
 required-capabilities: [memory.manage, memory.curate]
 required-tools: [cron_cancel, cron_schedule, mail_send, mailbox, memory_candidates, memory_delete, memory_hygiene, memory_search, memory_update, memory_verify, skill]
 ---
@@ -102,7 +102,7 @@ memory_candidates({
 })
 ```
 
-Never call `memory_delete`, never set `status: "deleted"`, and never set
+Never trigger `memory_delete`, never set `status: "deleted"`, and never set
 `status: "archived"` as part of an autonomous Mnemosyne cycle. The user owns
 the later `memory_candidates({ action: "resolve", ... })` decision.
 
@@ -149,6 +149,29 @@ tools are absent, run on demand instead.
 - Never advertise commands, config keys, background services, or tools that
   are not present in the live runtime.
 
+## Out of scope
+
+- **Don't delete or archive memories autonomously.** `memory_delete` and `status: "deleted"` / `"archived"` are not part of an autonomous Mnemosyne cycle. File `memory_candidates` proposals and let the user resolve.
+- **Don't re-author untouched memories to bump timestamps.** A memory that passes review stays as it is. Bumping timestamps corrupts recency signals and churns the store.
+- **Don't skip the deterministic pass.** Hygiene, anchor verification, and supersede/stale marking are run before any LLM analysis. The LLM is a bounded second pass over deterministic results, not a replacement.
+- **Don't infer absence from a missing search result.** A search miss is not proof a memory doesn't exist. Report what was searched; let deterministic checks carry the absence claim.
+- **Don't claim a successful broadcast or scheduled cycle that didn't run.** If the mailbox or cron tools are absent, say so. Never invent a successful delivery or a scheduled job.
+- **Don't describe cron as a persistent daemon.** Cron jobs belong to the live runtime; they must be inspected and cancelled through the cron tools. The skill is session-scoped.
+- **Don't bypass store protections with `force`.** Permanent and high-importance memories receive extra scrutiny. Bypassing protections is a bug, not a feature.
+- **Don't use it as a generic memory CRUD layer.** Mnemosyne is the curation workflow. Direct memory creation/update without going through the workflow is the wrong lane.
+
+## Before returning
+
+- [ ] `memory_hygiene({ verify: true })` ran first; counts captured
+- [ ] Non-zero `deleted` or `archived` counters treated as a bug and reported
+- [ ] Bounded semantic review searched related memories, not whole store
+- [ ] Direct updates only for non-terminal corrections (text, classification, confidence, `stale`, supersede/contradict links)
+- [ ] Deletion or archival recommendations filed as `memory_candidates` proposals, not applied
+- [ ] Every proposal includes a supported `reason`
+- [ ] Report contains trigger, counts, safe corrections, proposals, errors
+- [ ] Broadcast only when mailbox tools are registered and coordination is active
+- [ ] No claim of scheduled cycle or broadcast that didn't actually run
+
 ## Skills in Scope
 
 - `auto-review` — bounded background-review and reporting patterns.

package/skills/multi-agent/SKILL.md

@@ -351,6 +351,18 @@ session that dies halfway — and they let you synthesize as you go.
 
 ---
 
+## Out of scope
+
+- **Don't fan out a single atomic task.** One task is one agent. Subagent overhead exceeds the benefit below ~5 tool calls per subtask.
+- **Don't fan out work that needs shared mutable state.** Subagents share nothing — no memory, no session state, no variable scope. If two subtasks would read or write the same thing, they don't fan out.
+- **Don't fan out work with sequential dependencies.** Worker 2 needing worker 1's output means either chain it inside one agent, or use the fleet pattern with explicit hand-off. One-shot fan-out fails on dependencies.
+- **Don't write briefs by reference.** "Audit the file we discussed" — the worker has no idea. Include exact scope, the specific question, definition of done, return format, and boundaries.
+- **Don't dispatch workers one turn at a time.** Serialized fan-out throws away the only thing parallelism was for. Fire the whole batch in one turn.
+- **Don't ignore `budget_exhausted`.** Partial results are still results. Re-split and retry; never silently absorb a failure into a clean-looking report.
+- **Don't present partial coverage as complete.** A 7-of-10 fleet is a partial audit. Naming the missing three is the only way the user keeps trusting the report.
+- **Don't pick a role that doesn't match the task.** A `bug-hunter` writing docs or a `refactor-planner` running a security audit produces confident output shaped by the wrong priorities — worse than no output.
+- **Don't fan out "because the context is too big".** With 200K–1M windows, work that used to need splitting now fits. Fan out for wall-clock time and genuinely independent attention, not for size.
+
 ## Skills in scope
 
 - `bug-hunter` — parallel file audits

package/skills/node-modern/SKILL.md

@@ -4,7 +4,7 @@ description: |
   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
+version: 1.2.0
 required-capabilities: [filesystem.read, filesystem.write]
 required-tools: []
 optional-capabilities: [verification.run]
@@ -185,6 +185,33 @@ while (true) {
 }
 ```
 
+## Out of scope
+
+- **Don't use `require()`.** ESM only. `import { x } from './y.js'` with the `.js` extension, even in TS source.
+- **Don't use axios, node-fetch, or got.** Native fetch is sufficient. Third-party HTTP clients are an obsolete layer.
+- **Don't call fetch without `AbortSignal.timeout()`**. Every long-running operation needs a timeout. A request that hangs forever is a CI failure waiting to happen.
+- **Don't use `__dirname` directly in ESM.** ESM doesn't have it. `path.dirname(fileURLToPath(import.meta.url))` is the replacement.
+- **Don't mix callback `fs` with `await`.** Callback APIs don't return promises. Use `fs.promises.*` for `await`able access.
+- **Don't swallow `AbortError` silently.** An `AbortError` means a timeout or abort — it is signal, not success. Log it or handle it explicitly.
+- **Don't trust `process.cwd()` blindly.** It may not match the user's cwd. Accept `cwd` as a parameter and default sensibly.
+- **Don't use setTimeout for cancellable delays in new code.** `setTimeout(handler, ms, { signal })` (Node 22+) is the cancellable form.
+- **Don't write non-atomic file updates.** Use the write-temp + rename pattern. A crash mid-write leaves the file in an indeterminate state otherwise.
+- **Don't enable axios or got for "familiarity".** Node 22+ ships everything you need.
+
+## Before returning
+
+- [ ] ESM only; no `require()`, no `module.exports`
+- [ ] All relative imports use the `.js` extension
+- [ ] Built-in modules imported via the `node:` protocol (`node:fs/promises`, `node:http`, `node:path`)
+- [ ] fetch carries `AbortSignal.timeout()` for any operation that can wait
+- [ ] `__dirname` replaced with `path.dirname(fileURLToPath(import.meta.url))`
+- [ ] `fs.promises.*` for awaited file access; no callback `fs`
+- [ ] `AbortError` caught and handled explicitly, not swallowed
+- [ ] `cwd` accepted as parameter; `process.cwd()` is not a default
+- [ ] File writes atomic: `writeFile(tmp)` + `rename(tmp, target)`
+- [ ] `Promise.allSettled` for parallel tasks where partial failure is acceptable
+- [ ] `<nextsteps>` mirrors any open follow-up (timeout wiring, ESM migration, abort handling)
+
 ## Skills in scope
 
 - `typescript-strict` — strict TypeScript patterns

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