@noir-ai/skills 1.9.3 → 1.9.4-beta.2

package/builtin/noir-prd/SKILL.md

@@ -1,35 +1,46 @@
 ---
 name: noir-prd
-description: Use when drafting a Product Requirements Document (.noir/prd/<id>-<slug>.md) for a feature or epic, before writing the technical spec — captures the what/why/for-whom so the spec can focus on the how.
+description: Use when drafting a Product Requirements Document — capturing what a feature does, why it matters, and who it serves before the technical spec. Do NOT use for the technical "how" — that's noir-spec.
+metadata:
+  category: plan
+  version: 1.0.0
+license: MIT
+compatibility: claude · agents-md · gemini · cursor · opencode
 ---
 
-# noir-prd — Product Requirements Document authoring
+# noir-prd
 
-A PRD is a **pre-SDD product artifact** at `.noir/prd/<taskId>-<slug>.md`. It captures the *what / why / for-whom* so the technical spec can focus on the *how*. The spec later `@import`s it (`prdRef: <id>@<hash>`). **No FSM change** — the PRD is optional by mode, not a new phase.
+A PRD captures what and why before the spec captures how. It is the user-facing contract — who this feature is for, what problem it solves, and what success looks like. Shorter than a spec and never technical.
 
-## When to draft
-- `taskClass ∈ {feature, epic}` — a PRD is expected before the spec phase.
-- Explicitly requested (`noir-prd`, or "write a PRD for this").
-- NOT for bugfix / spike / quick-task / refactor (skip — Quick mode flows straight to spec).
+## When to use
+
+## Procedure
+1. **Follow the guidance** in the notes and verification.
+
+- A feature needs stakeholder-facing rationale before a technical spec.
+- The user says "write a PRD", "why are we building this", "who is this for."
+- After `noir-brainstorming` when the idea is clear but needs a formal "why."
+- **Do NOT use:** for the technical implementation plan — that's `noir-planning`.
 
 ## Sections (Noir template)
-1. **Problem** — what's broken / missing.
-2. **Evidence** — proof it's real (data, tickets, user reports). Never fill without a source.
-3. **Audience** — for whom.
-4. **Success Criteria** — machine-verifiable (quantified thresholds, not "fast/intuitive").
-5. **Appetite / Mode** — time-box; small batch or bet.
-6. **Proposed Direction** — product-altitude solution sketch (not technical design).
-7. **No-gos** — explicitly out of scope (highest-signal section).
-8. **Rabbit holes** — known pitfalls to avoid.
-9. **Open Questions** — unresolved; needs human input.
-
-## Task → PRD field mapping (e.g. from a tracker issue)
-`name`→Title; `description`→Problem/Proposed Direction; custom fields (Goal/Metric/Impact)→Evidence/Success Criteria; `status`+`priority`→Appetite/Mode; `assignees`→Audience; `due_date`→time-box; `tags`→clustering; `comments`→Open Questions/Rabbit holes; subtasks→Proposed Direction skeleton. Typically MISSING → No-gos, hard Success-Criteria metrics, explicit Rabbit holes → ask clarifying questions.
-
-## Drafting process
-1. **Ground first** — search `.noir/` memory (+ the web if relevant); never fabricate Evidence.
-2. **Ask clarifying questions** for missing sections (No-gos, metrics, rabbit holes).
-3. **Write** to `.noir/prd/<id>-<slug>.md` via the workflow `writePrd` artifact helper.
-4. The spec phase then `@import`s it.
-
-Offline (no model key): emit the section template above with placeholders — graceful degradation, never a hard failure.
+
+1. **Title & summary.** One sentence — what and why.
+2. **Problem.** What problem does this solve? For whom?
+3. **Proposed solution.** High-level, non-technical. How does it solve the problem?
+4. **Success metrics.** How do we know it worked? (adoption, performance, feedback — one number if possible).
+5. **Non-goals.** What are we deliberately not building in this version?
+6. **Open questions.** What's still unknown?
+
+## Drafting
+
+1. Gather from brainstorming output or the task brief.
+2. On Claude Code, use `AskUserQuestion` to fill gaps (who is the user, what metric). On other hosts, ask.
+3. Write to `.noir/prd/<id>-<slug>.md`.
+4. **Explicit opt-in.** Never auto-draft a PRD — ask first.
+
+## When done → next skill
+
+→ `noir-spec` to formalize the technical side. Or is there something else?
+
+## Notes
+- This skill is a playbook — the host decides which tools to use.

package/builtin/noir-readme/SKILL.md

@@ -1,12 +1,33 @@
 ---
 name: noir-readme
-description: Use when generating or updating a README or docs from the codebase.
+description: Use when generating or updating a project README or documentation from the codebase — keeping docs accurate. Use when the user says "write a README" or "update the docs"; when a new feature ships.
+metadata:
+  category: document
+  version: 1.0.0
+license: MIT
+compatibility: claude · agents-md · gemini · cursor · opencode
 ---
 
 # noir-readme
 
-> **Stub:** this skill ships as a valid, loadable placeholder in S5; its full playbook is deepened in a later slice.
+Generate or update project documentation — README, docs index, package docs. The rule: docs reflect shipped reality, never a stale plan.
 
-**When to use:** the README is missing, stale, or out of sync with what the code actually does.
+## When to use
 
-**For now:** read the manifests, entry points, and existing docs, then write a README that reflects the real setup and usage — install, run, test, and the one or two commands that matter — without inventing features.
+- A new project needs a README.
+- A feature shipped and the docs must reflect it.
+- The user says "write docs", "update README", "document this."
+
+## Procedure
+
+1. **Survey the codebase.** What does the project do? What's the entry point? What commands matter? Read the README and any existing docs.
+2. **Follow the project's doc convention.** If the project uses Diátaxis (tutorial/how-to/reference/explanation), follow it. If not, standard README sections: intro, install, usage, contributing, license.
+3. **Keep docs lean.** A 50-line README that's accurate beats a 200-line README that's outdated. Link to deeper docs — don't inline them.
+4. **Run `pnpm docs:validate`** if the project has doc validation — catch broken links and stale refs before committing.
+
+## When done → next skill
+
+→ `noir-shipping` to commit the doc update. Or continue.
+
+## Notes
+- This skill is a playbook — the host decides which tools to use.

package/builtin/noir-recall/SKILL.md

@@ -1,18 +1,37 @@
 ---
 name: noir-recall
-description: Use when starting a task, before re-deriving something that may already be known — to recall a prior decision, pattern, bug, or fact from Noir's cross-session memory.
+description: Use when searching Noir's cross-session memory for past decisions, patterns, bugs, or facts — before re-deriving something already known. Use when starting a task; when the user says "recall", "what did we do", or "what did we decide about X". Do NOT use to save new information — use noir-remember.
+metadata:
+  category: memory
+  version: 1.0.0
+license: MIT
+compatibility: claude · agents-md · gemini · cursor · opencode
 ---
 
-Recall what past sessions already learned before re-deriving it. Noir's memory is a local, project-scoped store of observations (pattern / preference / architecture / bug / workflow / fact / decision / lesson) you saved in earlier sessions. Querying it first avoids repeat work and keeps decisions stable across sessions.
+# noir-recall
+
+Query cross-session memory for what was already decided, discovered, or documented — before you re-derive it.
+
+## When to use
+
+- Starting a task that may have prior context.
+- The user says "recall", "what did we do about X", "do we have any memory of Y."
+- There's a decision to make and prior sessions may have already made it.
+- **Do NOT use:** to save — use `noir-remember`. To search code — use `noir-exploring`.
 
 ## Procedure
-1. **Query with intent.** Call `memory_recall { query, limit }` with a natural-language or identifier query (e.g. `"auth token storage"`, `"why sqlite-vec over pgvector"`, `"ContextEngine embed"`). The hybrid path fuses BM25 + vector similarity via RRF and returns ranked observations scoped to memory only — context-index rows never leak in.
-2. **Use the instant path for a quick check.** When you only need "does anything mention X" and want no embedding cost, call `memory_search { query }` — BM25-only, faster, still scoped to memory.
-3. **Read the full content, not the snippet.** Every returned observation carries its complete `content` (never truncated). Reason over the full text plus its `concepts`, `files`, `type`, and `ts`; cite the observation rather than paraphrasing it loosely.
-4. **Scope when useful.** Pass `type` to filter to one kind (e.g. `"decision"`) or `session_id` to limit to one session, when the query is broad.
-5. **Act, then stop.** If recall surfaces a relevant decision or pattern, follow it; if it contradicts the current plan, surface the conflict before proceeding. If nothing relevant returns, say so plainly and proceed — absence is not a hidden result.
-
-## Notes
-- **Degraded is honest, not broken.** With no embedder configured (or the local model failed to load), `memory_recall` still works in BM25-only mode. A read-only store (daemon down) still serves `memory_recall` and `memory_search`; only writes are fenced off.
-- **Hydrate, never truncate.** Recall hydrates each hit from the authoritative store row, so what you read is the full original text — the BM25 snippet is only the preview that ranked it.
-- **Tools absent?** The memory tools are registered only when the daemon was started with memory enabled (the `ctx.memory` service). If they are missing, run `noir init` and start the daemon. To forget something recalled here, see `noir-remember`'s forget path.
+
+1. **Form a specific query.** What decision, pattern, or fact are you looking for? A vague "anything relevant" produces noise.
+2. **Search memory.** On Noir projects, use `noir memory recall <query>` (or the `memory_recall` MCP tool). If no memory tool is available, check `.noir/` artifacts (specs, plans, tasks) as the durable fallback.
+3. **Surface 2-4 top matches.** State what was found and when it was recorded. If nothing found, say so — don't fabricate.
+4. **Apply to the current task.** If a prior decision is relevant, cite it; if it's stale, note that and ask the user.
+
+## Verification
+
+- [ ] Memory was queried before making assumptions.
+- [ ] Results are cited with source (date/session).
+- [ ] No fabricated memories.
+
+## When done → next skill
+
+→ Route to the relevant noir skill based on what you recalled. Or is there something else?

package/builtin/noir-remember/SKILL.md

@@ -1,23 +1,37 @@
 ---
 name: noir-remember
-description: Use when an insight, decision, pattern, or bug worth keeping surfaces, or the user says "remember this" / "save this" — to persist it to Noir's cross-session memory.
+description: Use when persisting an insight, decision, pattern, or bug to Noir's cross-session memory. Use when the user says "remember this" or "save this"; when an insight surfaces during a session. Do NOT use for routine progress.
+metadata:
+  category: memory
+  version: 1.0.0
+license: MIT
+compatibility: claude · agents-md · gemini · cursor · opencode
 ---
 
-Persist a durable observation to Noir's cross-session memory so a future session can recall it. Saving is always local and free — no network call, no LLM call. The observation is written to the local store and recalled later via `noir-recall`.
+# noir-remember
+
+Save durable insights so the next session doesn't start from zero.
+
+## When to use
+
+- An important decision, pattern, or bug workaround surfaces.
+- The user says "remember this", "save this", "don't forget this."
+- A pattern repeats across sessions — it's worth formalizing.
+- **Do NOT use:** for routine progress updates (those live in the task state).
 
 ## Procedure
-1. **Decide it is worth keeping.** Save observations that will matter beyond this session: a decision and its rationale, a confirmed pattern or convention, a hard-won bug fix, a project architecture fact, a workflow that worked. Do not save transient status, scratch reasoning, or anything already obvious from the code.
-2. **Call `memory_save`.** `memory_save { content, type?, concepts?, files?, importance?, session_id? }`. Only `content` is required; the rest sharpen recall:
-   - `content` — the full insight in prose. Write it to be readable cold, with the why, not just the what. It is never truncated.
-   - `type` — `pattern` | `preference` | `architecture` | `bug` | `workflow` | `fact` | `decision` (unknown values are accepted). Pick the closest fit; `lesson` is reserved for consolidation output.
-   - `concepts` — short tags that a future query would use (e.g. `["auth", "sqlite-vec"]`).
-   - `files` — repo-relative paths the insight concerns.
-   - `importance` — 0..1 (default 0.5); raise it for load-bearing decisions.
-3. **Confirm the round-trip.** After a non-trivial save, a quick `memory_recall { query }` with a phrase from the content confirms it landed and is retrievable.
-4. **Forget when wrong.** If something saved is outdated or wrong, remove it with `memory_forget { ids: [...] }` using the id returned from `memory_save`. The row and its search indexes are purged.
-
-## Notes
-- **Local + free, by design.** Saving performs only a local store write plus a local embedding (when an embedder is configured). It never makes a paid call; the only LLM surface in memory is consolidation, which is separately provider-gated and off by default.
-- **Append-only; edit by forgetting.** Memory does not mutate rows in place. To correct an observation, forget the old one and save the new one — the audit trail stays clean.
-- **Read-only store.** If the daemon is down the store opens read-only and `memory_save` refuses cleanly rather than failing mid-write; start the daemon (`noir daemon start`) and retry.
-- **Tools absent?** The memory tools register only when the daemon was started with memory enabled. If they are missing, run `noir init` and start the daemon.
+
+1. **Identify what's worth keeping.** A decision with a reason, a pattern that recurred, a bug with its root cause, a preference the user stated.
+2. **Write a short, searchable entry.** Key concepts + why it matters. Keep it focused — one fact per entry.
+3. **Persist it.** On Noir projects, use `noir memory save <content>` (or the `memory_save` / `noir.remember` MCP tool).
+4. **Confirm.** Say what was saved so the user knows it'll survive.
+
+## Verification
+
+- [ ] The entry is one focused fact (not a grab-bag).
+- [ ] Key concepts are named (searchable later).
+- [ ] The entry has a "why" — not just "what."
+
+## When done → next skill
+
+→ `noir-wrap` if closing, or continue working.

package/builtin/noir-rules/SKILL.md

@@ -1,34 +1,35 @@
 ---
 name: noir-rules
-description: Use when reviewing or editing the project's AI working-rules (.noir/rules/RULES.md), or when deciding whether a directive belongs in the always-on contract vs a skill, a memory, or an ADR.
+description: Use when reviewing or editing the project's AI working-rules (.noir/rules/RULES.md) — decide whether a directive belongs in the always-on contract vs a skill, a memory, or an ADR. Use when the user says "update the rules" or "add a rule".
+metadata:
+  category: meta
+  version: 1.0.0
+license: MIT
+compatibility: claude · agents-md · gemini · cursor · opencode
 ---
 
-# noir-rules — AI working-rules steward
+# noir-rules
 
-The project's canonical AI working-contract lives at `.noir/rules/RULES.md`; the host context file (`CLAUDE.md`) `@import`s it so it is in context every session. Noir re-emits only the `@import` pointer on `noir init`/`noir sync` — the body is user-owned.
+The project's AI working-rules at `.noir/rules/RULES.md` — the always-on contract. Every line costs context in every session, so a rule must earn its place.
 
 ## When to use
-- Editing or reviewing `.noir/rules/RULES.md`.
-- Deciding where a directive belongs:
-  - **rules** — always-on contract (loaded every session);
-  - **skill** — on-demand playbook (loaded when triggered);
-  - **memory** — a learned fact/decision (recall on demand);
-  - **ADR** — a locked architecture decision (`.noir/decisions/NNNN-*.md`).
-
-## Keeping rules lean — the pruning rubric
-Every line pays rent in every session's context budget. Keep a line only if it is one of:
-- **failure-backed** — it prevented a real issue in the last 30 days; or
-- **tool-enforceable** — a command / hook / gate checks it; or
-- **decision-encoding** — records a locked architecture/workflow choice; or
-- **triggerable** — names a specific condition for action.
-
-Otherwise delete it. "Document failures, not aspirations."
-
-## Recommended structure (section order)
-Identity & scope → Anti-assumption contract → SDD workflow gates → Verification commands → Coding standards (link ADRs, don't inline) → Docs & roadmap pointers → Conventions gotchas.
-
-## Budget
-Target ≤ 150 lines / ≤ 6 KB. Effective attention degrades in the low-thousands of tokens regardless of window size — every line must earn its place.
-
-## Multi-host (v1.x)
-`RULES.md` is AGENTS.md-compatible. For non-Claude hosts, `noir sync` emits a root `AGENTS.md` that imports it; Cursor additionally compiles to `.cursor/rules/*.mdc` with `description`/`globs`/`alwaysApply` frontmatter.
+
+## Procedure
+1. **Follow the guidance** in the notes and verification.
+
+- The user says "add a rule", "update rules", "should this be a rule?"
+- A convention is being repeated verbally every session — it's time to codify it.
+- A rule is growing stale — it's time to prune or archive.
+
+## Keeping rules lean
+
+1. **One rule, one line.** If it needs a paragraph, it belongs in a skill, a memory, or an ADR.
+2. **Use the most specific mechanism.** A directive you want ALWAYS active → rule. A directive you want on-demand → skill. A decision worth recalling → memory. An architecture decision with rationale → ADR.
+3. **Prune stale rules.** `noir doctor rules` checks the budget.
+
+## When done → next skill
+
+→ The relevant noir skill for the change the rule governs. Or continue.
+
+## Notes
+- This skill is a playbook — the host decides which tools to use. On Claude Code, prefer `AskUserQuestion` for choices; on other hosts, ask in text.

package/builtin/noir-security/SKILL.md

@@ -1,12 +1,41 @@
 ---
 name: noir-security
-description: Use when reviewing changes for security vulnerabilities — injection, auth, SSRF, data exposure.
+description: Use when reviewing code for security vulnerabilities — injection, auth, SSRF, data exposure, and supply chain risks. Use when the user says "security review" or "audit this for security"; before shipping a feature that handles user input, auth, or sensitive data.
+metadata:
+  category: verify
+  version: 1.0.0
+license: MIT
+compatibility: claude · agents-md · gemini · cursor · opencode
+references:
+  - security-checklist.md
 ---
 
 # noir-security
 
-> **Stub:** this skill ships as a valid, loadable placeholder in S5; its full playbook is deepened in a later slice.
+Review changes for vulnerabilities — not a pen-test, but the baseline every feature should pass before shipping.
 
-**When to use:** you are reviewing a change and want to check it for the common, exploitable classes before merging.
+## When to use
 
-**For now:** scan for injection (SQL/command/template), broken auth and authz, SSRF in any outbound call, and sensitive data in logs or responses — flag concretely, do not rubber-stamp.
+- A feature handles user input, authentication, or sensitive data.
+- The user says "security review", "check this for vulnerabilities", or "is this safe."
+- Before `noir-shipping` for a security-sensitive change.
+
+## Procedure
+
+1. **Check surface area.** What data enters? What exits? Who can call it? What's authenticated?
+2. **Check injection.** SQL, shell, template injection paths — review every dynamic string used in a command or query.
+3. **Check auth.** Is every endpoint gated? Is the auth check before any data access? No "if admin → show data" then "else → also show data because we forgot a return."
+4. **Check secrets.** Any hard-coded keys, tokens, or passwords? (Check committed files, not env vars).
+5. **Check dependencies.** Any new packages? Known vulnerabilities? Pinned versions that are stale?
+6. **Report findings.** Severity (critical/high/medium/low) + location + fix. One finding per entry.
+
+## Reference
+
+For the full injection/auth/exposure/dependency checklist, see [security-checklist.md](references/security-checklist.md).
+
+## When done → next skill
+
+→ `noir-shipping` if clean, or `noir-systematic-debugging` if a vulnerability needs fixing.
+
+## Notes
+- This skill is a playbook — the host decides which tools to use. On Claude Code, prefer `AskUserQuestion` for choices; on other hosts, ask in text.

package/builtin/noir-security/references/security-checklist.md

@@ -0,0 +1,49 @@
+# Security review checklist — the baseline every feature should pass
+
+Deep reference for `noir-security`. A methodical checklist for reviewing code for vulnerabilities before shipping.
+
+## Surface area first
+
+Before looking at specific attacks, map the surface:
+
+- What DATA enters the system? (user input, webhooks, files, network)
+- What EXITS? (responses, logs, external calls, rendered pages)
+- WHO can call each path? (unauthenticated? role-gated? internal-only?)
+- What TRUST boundaries exist? (the point where untrusted data meets trusted code)
+
+## Injection (the classic)
+
+- **SQL** — is any user input concatenated into a query string? Parameterized queries / prepared statements everywhere. No `eval`-style dynamic queries.
+- **Shell** — is user input passed to a shell command? Use `execFile`/argument arrays, never string interpolation into `sh -c`.
+- **Template/XSS** — is user input rendered into HTML/JS unescaped? Framework auto-escaping ON, no `dangerouslySetInnerHTML`-style bypass without a reason.
+- **Path** — is user input used to build a filesystem path? Normalize + validate it stays inside the intended root (no `..` traversal).
+
+## Auth & authorization
+
+- **Every data-touching endpoint is gated** — a missing `if (isAdmin) return;` before a `return data` leak is the classic bug (the "forgot the return" pattern).
+- **Auth check happens BEFORE data access**, not after.
+- **Failed auth doesn't reveal** whether the user or password was wrong (in login forms).
+- **Tokens/secrets** — any hard-coded key, committed `.env`, or token in a log? Scan the diff, not just the code.
+
+## Data exposure
+
+- **Over-fetching** — does an API return more fields than needed (password hashes, internal ids)?
+- **Logging** — do logs contain tokens, PII, or full request bodies? Sanitize before logging.
+- **Error messages** — do errors leak stack traces or internal paths to the client?
+
+## Dependencies
+
+- **New packages** — any added this change? Check for known vulnerabilities and whether they're pinned to a safe version.
+- **Supply chain** — is a package pulled from a trusted source? Any `curl | bash` installs?
+- **Transitive** — a lockfile bump that pulls a vulnerable transitive dep?
+
+## How to report
+
+One finding per entry, each with:
+
+- **Severity** — critical / high / medium / low (impact × likelihood).
+- **Location** — file:line.
+- **The attack** — a concrete "an attacker could X by Y."
+- **The fix** — a specific remediation.
+
+**Rule:** never ship a critical/high finding unaddressed. If it must ship, the risk is explicitly accepted by the user with a tracking issue — never silently.

package/builtin/noir-shipping/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: noir-shipping
+description: Use when shipping verified work — stage, commit with conventional-commit messages, decide integration (merge, PR, or keep local), and clean up. Use when the user says "commit this", "open a PR", or "ship it". Do NOT use when tests aren't green; verify first with noir-verifying.
+metadata:
+  category: git
+  version: 1.0.0
+license: MIT
+compatibility: claude · agents-md · gemini · cursor · opencode
+---
+
+# noir-shipping
+
+Ship verified work. Absorbs `noir-commit`, `noir-pr`, and `noir-branch` into one surface: stage → commit → integrate → clean up.
+
+## When to use
+
+- Implementation is verified and it's time to ship.
+- The user says "commit", "push", "PR", "merge", "ship this."
+- **Do NOT use:** when tests aren't green. Do NOT use as "save my work" — use `noir-checkpoint`.
+
+## Procedure
+
+1. **Stage logically.** One logical change = one commit. No grab-bags.
+2. **Write a conventional-commit message.** `type(scope): summary`. Body = why, not what.
+3. **Run the pre-commit gate.** Lint, build, typecheck, test — must be green before committing.
+4. **Decide integration.** On Claude Code, use `AskUserQuestion`: merge, PR, or keep local. On other hosts, ask plainly. Never push without asking.
+5. **Clean up.** Scratch files, merged branches, temp notes.
+
+## When done → next skill
+
+→ `noir-wrap` to close the session. Or is there more to ship?
+
+## Notes
+- This skill is a playbook — the host decides which tools to use. On Claude Code, prefer `AskUserQuestion` for choices; on other hosts, ask in text.

package/builtin/noir-spec/SKILL.md

@@ -1,22 +1,56 @@
 ---
 name: noir-spec
-description: Use when turning a brainstormed idea into a formal spec (what / why / acceptance / non-goals) — before planning or code.
+description: Use when turning a brainstormed idea into a formal spec — capturing the what, why, acceptance criteria, and non-goals. Use when the user says "write a spec" or "spec this". Do NOT use for a single-line feature request that needs no formalization.
+argument-hint: <the idea or feature to specify>
+metadata:
+  category: spec
+  version: 1.0.0
+license: MIT
+compatibility: claude · agents-md · gemini · cursor · opencode
+references:
+  - spec-template.md
 ---
 
-Turn the confirmed intake into a written spec that a planner (and later an implementer) can work against without re-litigating decisions. The spec is the contract for everything downstream.
+# noir-spec
+
+Turn a brainstormed idea into a formal specification — the contract the implementation plan builds against. The spec captures what to build and why, not how to build it. Keep it focused; a spec is a reference, not a novel.
+
+**Invoked with:** `$ARGUMENTS` (optional). If present, treat it as the starting idea. If empty, ask what to specify.
+
+## When to use
+
+- A brainstorm session has produced a clear direction and it's time to formalize.
+- The user says "write a spec", "spec this", "formalize this", or "create a specification".
+- A feature is large enough that the what/why/non-goals deserve a written reference before planning.
+- **Do NOT use:** for a trivial single-file change that needs no contract.
 
 ## Procedure
-1. **Read the resolved intake.** Pull the task stub and any clarification Q&A from `.noir/tasks/`. If anything is still ambiguous, route back to `noir-clarify` instead of guessing here.
-2. **Draft the spec sections.** Write, one section each and no filler:
-   - **Problem** — why this work exists, in user terms.
-   - **Scope** — what is being built; the surface area.
-   - **Acceptance criteria** — observable, each one a check an implementer can run.
-   - **Non-goals** — what is explicitly out of scope, to protect the plan.
-   - **Open questions** — anything genuinely unresolved, named not hidden.
-3. **Where approaches are live, pick one.** Name the alternatives, state the trade-off in one line, and choose with a reason. Record the rejected options briefly — the planner needs to know the decision is settled.
-4. **Self-review the draft.** Scan for placeholders (TBD, TODO, vague nouns), internal contradictions (does the scope match the acceptance criteria?), scope-fit (is this one plan, or should it decompose?), and ambiguity (could any line be read two ways?). Fix inline.
-5. **Write and hand off.** Save to `.noir/specs/<topic>.md`. The SDD engine records the spec checkpoint observably via `noir.checkpoint`. Point to `noir-plan` for the implementation plan.
+
+1. **Restate the goal** (one sentence — what are we building and why).
+2. **Capture the scope.** What's in, what's explicitly out (non-goals), and who this is for (users / personas). On Claude Code, use `AskUserQuestion` for structured choices; on other hosts, ask in plain text.
+3. **Define acceptance criteria.** Concrete, verifiable "done when" statements. No vague acceptances.
+4. **Note constraints.** Technical, timeline, dependency, or architectural constraints that bind the implementation.
+5. **Write to `.noir/specs/<id>-<slug>.md`.** Use the spec template at `references/spec-template.md` if shipped. The file is the durable contract; the engine records the spec checkpoint.
+6. **Hand off.** Point to `noir-planning` to break this spec into an implementation plan.
+
+## Verification
+
+- [ ] The goal is one clear sentence.
+- [ ] Scope boundaries (in / out) are explicit — no "we'll figure it out later."
+- [ ] Acceptance criteria are concrete and verifiable (numbers, behaviors, screens).
+- [ ] Non-goals are listed (what we are deliberately NOT building).
+- [ ] The spec stub is written to `.noir/specs/` (or surfaced to the user if not initialized).
 
 ## Notes
-- A spec is done when an implementer can plan against it without coming back for clarification. If you would need to ask, the spec is not done.
-- Rejected approaches are part of the spec — write them down so they do not come back as new ideas.
+
+- A spec can be short. A 10-line spec with sharp boundaries beats a 200-line essay with fuzzy acceptances.
+- Reference sibling specs when a feature builds on one — don't copy-paste.
+- If the user already has a clear mental model, don't force a spec; ask whether they'd like one.
+
+## Reference
+
+For a copyable spec skeleton (goal/scope/non-goals/acceptance/constraints), see [spec-template.md](references/spec-template.md).
+
+## When done → next skill
+
+→ `noir-planning` to break the spec into an implementation plan. Or is there something else you'd like to do?

package/builtin/noir-spec/references/spec-template.md

@@ -0,0 +1,43 @@
+# Spec template — the what/why/acceptance/non-goals skeleton
+
+Deep reference for `noir-spec`. A copyable skeleton for a formal specification. Keep it short and sharp; a spec is a contract, not a novel.
+
+```markdown
+# <Feature> — specification
+
+## Goal
+One sentence: what are we building and why.
+
+## Scope (in)
+- The concrete capabilities this build delivers.
+
+## Non-goals (out)
+- What we are deliberately NOT building in this version.
+
+## Users / personas
+- Who this is for.
+
+## Acceptance criteria
+- [ ] Concrete, verifiable "done when" statements.
+- [ ] Each one is testable (behavior, number, or screen).
+- [ ] No vague acceptances like "works well" or "feels fast".
+
+## Constraints
+- Technical, timeline, dependency, or architectural limits that bind the implementation.
+
+## Open questions
+- Anything still unknown; resolved before planning if possible.
+```
+
+## Authoring rules
+
+1. **Goal first, one sentence.** If the goal needs two sentences, it's two features.
+2. **Acceptance criteria are the contract.** The implementation plan maps each criterion to a task; the verify gate checks each one. Write them so a reader can check them off without asking you.
+3. **Non-goals prevent scope creep.** "We are not doing X" is as important as "we are doing Y."
+4. **A short spec with sharp boundaries beats a long essay.** 10 crisp lines > 200 fuzzy ones.
+5. **Reference sibling specs** when this builds on another — don't copy-paste its content.
+
+## Good / bad
+
+Good: "Acceptance — the CLI accepts `--json` and emits a versioned `{ok, data}` envelope to stdout, empty otherwise; exit 0 on success, non-zero on failure."
+Bad: "Acceptance — it should work properly and be user friendly."