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

package/builtin/noir-backend/SKILL.md

@@ -1,12 +1,40 @@
 ---
 name: noir-backend
-description: Use when building APIs, database schemas, or server logic — for robust, scalable backend patterns.
+description: Use when building backend code — APIs, database schemas, server logic, and scalable backend patterns. Do NOT use for pure frontend work.
+metadata:
+  category: domain
+  version: 1.0.0
+license: MIT
+compatibility: claude · agents-md · gemini · cursor · opencode
+references:
+  - backend-patterns.md
 ---
 
 # noir-backend
 
-> **Stub:** this skill ships as a valid, loadable placeholder in S5; its full playbook is deepened in a later slice.
+Backend architecture and implementation — APIs, databases, services, and server patterns.
 
-**When to use:** you are building an API, a database schema, or server-side logic and want patterns that age well.
+## When to use
 
-**For now:** model the data and the errors before the endpoints, validate at the boundary, and keep side effects out of pure logic.
+- Building or modifying backend code.
+- The user says "create an API", "add an endpoint", "design a schema", "set up a service."
+- A service boundary or data flow is being defined.
+
+## Procedure
+
+1. **Design the contract first.** What does the API accept and return? What's the schema? The contract is the interface — implementers on both sides read it.
+2. **One endpoint = one responsibility.** Small, focused handlers are testable; monolithic "do-everything" endpoints are not.
+3. **Error handling at every layer.** API → validation → service → database. Each layer reports a structured error; the client never sees a raw stack trace.
+4. **Database migrations.** Schema changes go through migration files — never alter a table by hand. Rollback must be possible.
+5. **Security.** Auth on every endpoint that touches data; rate-limit write endpoints; validate input at the boundary.
+
+## Reference
+
+For contract-first, layered error handling, migrations, and resilience patterns, see [backend-patterns.md](references/backend-patterns.md).
+
+## When done → next skill
+
+→ `noir-test-driven-development` for the test suite, then `noir-verifying`.
+
+## 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-backend/references/backend-patterns.md

@@ -0,0 +1,55 @@
+# Backend patterns — contract-first, layered, resilient
+
+Deep reference for `noir-backend`. Practical patterns for APIs, schemas, and server logic that scale without collapsing.
+
+## Contract-first
+
+The API contract is the interface BOTH sides read. Before code:
+
+1. **Define the endpoint** — method, path, request body, response body, error shapes.
+2. **Validate the schema** — the request is validated at the boundary (a schema/Zod/DTO), not in the handler.
+3. **Document it** — the contract (even a short markdown or a type) is the source both sides build against.
+
+**One endpoint = one responsibility.** A focused handler is testable; a "do everything" endpoint is not. If an endpoint has a second verb's worth of behavior, split it.
+
+## Layered error handling
+
+Every layer reports a STRUCTURED error; the client never sees a raw stack trace:
+
+```
+API → ValidationError (400, field)
+   → AuthError (401/403)
+   → NotFoundError (404)
+   → RateLimitError (429)
+   → ConflictError (409)
+   → InternalError (500, no internals leaked)
+```
+
+- Each layer maps its failures to a typed error with a stable code + human message.
+- The client gets `{error: {code, message}}`, never a stack trace or internal path.
+- Log the full error server-side; return only the safe surface to the client.
+
+## Data & migrations
+
+- **Schema changes go through migrations** — never alter a table by hand. Every migration is forward + rollback.
+- **Indexes** — add indexes for the query patterns the API actually uses, not speculative ones.
+- **Transactions** — multi-step writes (create + link + notify) run in a transaction; a failure mid-way rolls back cleanly.
+
+## Security (baseline)
+
+- **Auth on every data-touching endpoint** — the gate is before the data access, with no "forgot the return."
+- **Validate at the boundary** — reject malformed input before it reaches service logic.
+- **Rate-limit write endpoints** — public creates/updates get a limit + 429 backoff.
+- **Secrets** — tokens via env/config, never committed. Credentials never logged.
+
+## Resilience
+
+- **Idempotency** — writes accept an idempotency key so a retried request doesn't double-create.
+- **Timeouts + retries** — outbound calls have a timeout and a bounded retry (never infinite).
+- **Graceful degradation** — a downstream outage degrades (cached fallback, clear error), never crashes the process.
+- **Observability** — a request id threads through the layers so a failure is traceable; log the request id with each error.
+
+## Good / bad
+
+Good: a validated, single-purpose endpoint that returns typed errors, uses migrations, and has a rate limit.
+Bad: an unvalidated catch-all endpoint that throws a raw error to the client, mutates the DB by hand, and has no auth check before the data leak.

package/builtin/noir-brainstorming/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: noir-brainstorming
+description: Use when starting a new feature or task from a raw idea, ticket, or issue — explore intent, requirements, and design space before implementation. Do NOT use for single-file edits, typo fixes, or pure refactors.
+argument-hint: <describe the feature or idea to explore>
+metadata:
+  category: discovery
+  version: 1.0.0
+license: MIT
+compatibility: claude · agents-md · gemini · cursor · opencode
+---
+
+# noir-brainstorming
+
+Turn a raw idea, ticket, or ambiguous ask into a shared, written understanding of intent — before any plan or code. The goal is a clear problem statement plus the open questions and options, not a shortcut to the first plausible build. This skill replaces the old `noir-intake`, `noir-clarify`, and `noir-brainstorm` skills — one "gather requirements" surface.
+
+**Invoked with:** `$ARGUMENTS` (optional). If the user passed a feature description, treat it as the initial statement of intent and restate it as the goal. If empty, ask what they want to explore first.
+
+## When to use
+
+- A new feature, task, or epic starts from a raw idea, ticket, or issue.
+- The user says "let's build X", "I have an idea", "we need a feature", or pastes a vague request.
+- An idea or spec has ambiguities that should be surfaced before committing to an approach.
+- **Especially when:** the request is one sentence, the requirements are fuzzy, or the user is unsure what they want.
+- **Do NOT use:** for a single-line typo fix, a rename, or a mechanical refactor with no design decision.
+
+## Procedure
+
+1. **Restate the goal.** In one sentence, say what the user is trying to achieve and why. If `$ARGUMENTS` was provided, start from it.
+2. **Surface requirements with a structured prompt.** Ask the clarifying questions you genuinely need — but batch them, don't pepper one at a time. On Claude Code, use the `AskUserQuestion` tool (question + up to 4 options) so the user picks instead of types; on hosts without it (Gemini/Cursor/Copilot), ask in plain text. Cover scope, constraints, users, non-goals, and any acceptance you can see.
+3. **Offer 2-3 distinct approaches.** Present options with explicit trade-offs. Do not collapse to a single path prematurely; the user chooses.
+4. **Record the decision.** Capture the chosen direction + open questions as a spec stub under `.noir/specs/` if the project is Noir-initialized. This is observable, not rhetorical — the SDD engine records the brainstorm checkpoint.
+5. **Hand off.** Point to `noir-spec` (formalize) → then `noir-planning` (break down).
+
+## Verification
+
+- [ ] The goal is restated in one sentence and the user confirmed it.
+- [ ] Open questions are surfaced; ambiguities are resolved or explicitly deferred.
+- [ ] 2-3 options with trade-offs were presented (not one path forced).
+- [ ] The decision + open questions are recorded (spec stub or note).
+
+## Notes
+
+- Discipline is observable: the SDD engine's gates record that brainstorming happened. This skill is the playbook.
+- For a genuinely trivial request (a one-liner with a clear answer), say so and skip the full ritual — brainstorming is for creative or ambiguous work.
+- If the user has a strong opinion, follow it; your job is to surface the space, not to win an argument.
+
+## When done → next skill
+
+→ `noir-spec` to formalize the idea into a spec → `noir-planning` to break it into steps. Or, if you'd rather keep exploring a different direction, say so — I'll pivot.

package/builtin/noir-checkpoint/SKILL.md

@@ -1,18 +1,36 @@
 ---
 name: noir-checkpoint
-description: Use mid-session — to save in-flight state before a context-risky moment or interruption, so work survives.
+description: Use when saving mid-session state before a context-risky moment or interruption — preserve the current task, progress, and open decisions. Use when the user says "save my place" or "checkpoint this". Do NOT use to close a session — use noir-wrap.
+metadata:
+  category: discovery
+  version: 1.0.0
+license: MIT
+compatibility: claude · agents-md · gemini · cursor · opencode
 ---
 
-Save in-flight state so work survives a context-risky moment (compaction, handoff, or interruption). Persists the task's phase, progress, and next step into `.noir/` and records the checkpoint observably via `noir.checkpoint`.
+# noir-checkpoint
+
+Save in-flight state so work survives an interruption, context-loss, or session restart. A checkpoint is a snapshot, not a close.
+
+## When to use
+
+- Mid-session, before a context-risky moment (long pause, context compaction, or interruption).
+- The user says "save my place", "checkpoint this."
+- **Do NOT use:** to close a session — use `noir-wrap`.
 
 ## Procedure
-1. **Find the task.** Locate the active task stub under `.noir/tasks/<id>.md` (the engine's persisted state). If none, ask the user which task to checkpoint — or note "no active task — nothing to checkpoint" and stop.
-2. **Capture state.** Update `.noir/tasks/<id>.md`: set the current phase, a status line (e.g. `checkpointed @ phase N`), an `updated:` timestamp, and fill *done so far* + *next steps* + any blockers. Append a one-line history entry so a fresh session can pick up cleanly.
-3. **Record the checkpoint.** Call `noir.checkpoint` so the SDD engine records the save observably; the task stub is the source of truth, the checkpoint is the durable signal that survives context loss.
-4. **Memory (best-effort).** Save the checkpoint to Noir memory (phase + key decisions + next step) if the host's memory tooling is available. Skip cleanly if not — `.noir/tasks/<id>.md` remains the durable record either way.
-5. **Uncommitted work.** Note any uncommitted changes (`git status --porcelain`) in the checkpoint and advise the user — commit or stash before truly leaving, or the on-disk state and the working tree will diverge.
-6. **Report.** State the task id, the phase, and the next step. Point to the SDD lifecycle to resume — do not invent a slash command.
-
-## Fallbacks
-- No active task → say so; nothing to checkpoint.
-- `noir.checkpoint` or Noir memory unavailable → skip silently; the task stub is the source of truth and the engine degrades read-only rather than failing.
+
+1. **Record open task state.** Which task is active, what phase it's in, what files are touched, what tests are in-flight. Use `noir task save` (or the SDD engine's checkpoint tooling).
+2. **Note open decisions.** Anything the user and agent agreed on that hasn't been committed.
+3. **Mark the workspace.** Dirty files, branch state, any uncommitted changes. The next session needs to know.
+4. **Save memory.** Key insights from this session segment.
+5. **Print the checkpoint summary.** Brief — next session reads this and resumes.
+
+## Notes
+
+- Checkpoints are temporary scaffolding, not permanent records. The engine's task state is the durable truth.
+- You can checkpoint multiple times in a session — each one replaces the last.
+
+## When done → next skill
+
+→ The session can pause safely. When you return, `noir-sync` will find the checkpoint. Or continue working.

package/builtin/noir-context/SKILL.md

@@ -1,18 +1,37 @@
 ---
 name: noir-context
-description: Use when a question spans more files than fit in context — to seed the repo into a hybrid index once, then query it for windowed snippets instead of reading whole files.
+description: Use when a question spans more files than fit in context — query Noir's hybrid retrieval index (BM25 + kNN) for windowed snippets. Use when the user says "index this", "search the codebase", or "find where X is used". Do NOT use for a single-file lookup.
+metadata:
+  category: context
+  version: 1.0.0
+license: MIT
+compatibility: claude · agents-md · gemini · cursor · opencode
 ---
 
-Ground a question in the whole repo without pulling every file into context. Seed the index once with `context_index`, then query it with `context_search` and reason over the returned windowed snippets. Snippets are extracted around each match and never truncated, so the surrounding line context is intact without a whole-file read.
+# noir-context
+
+Hybrid retrieval for large codebases — index once, query many times. The host gets windowed snippets (BM25 + kNN → RRF) instead of re-reading entire files. Local 384-dim embeddings by default, zero API key.
+
+## When to use
+
+- A question spans more files than fit in context.
+- The user says "search the codebase", "find where X is", "index the repo."
+- You need cross-referenced snippets from many files for a single answer.
+- **Do NOT use:** for a single-file read — just Read it.
 
 ## Procedure
-1. **Seed the index.** Call `context_index { paths: ["src", "docs"] }` with the trees you need grounded, or omit `paths` to index the project root. Indexing is incremental by SHA-256 content-hash — unchanged files are skipped, so re-call it freely after edits. It must run once before `context_search` returns anything useful.
-2. **Query, do not dump.** Call `context_search { query, budgetTokens }` with a natural-language or identifier query (e.g. `"ContextEngine"` or `"where are errors thrown"`). Set `budgetTokens` to what you can spare (default 4096); optionally pass `source` to scope both legs to one bucket such as `"docs"` or `"codebase"`. You get ranked hits — path, a windowed snippet, a score — fused from BM25 and vector similarity, not raw file dumps.
-3. **Reason over the snippets.** Read the returned windows and decide; open a file by path only when a snippet implicates a change. Everything else stays a citation.
-4. **Re-seed when stale.** After non-trivial edits, re-run `context_index` so the index reflects current content. The content-hash skip keeps it cheap; staleness is the only way a snippet drifts from the code on disk.
+
+1. **Index the repo.** `noir context index` (one-time; `--force` to reindex). This seeds BM25 + embeddings into the store.
+2. **Query with specific terms.** `noir context search "<query>"` returns windowed snippets around matches. Use terms you'd grep for — function names, error messages, patterns.
+3. **Consume the snippets.** The output is the evidence. Don't re-read the whole file unless a snippet implicates it.
+4. **Repeat as needed.** New queries are cheap — the index is persistent.
 
 ## Notes
-- **Degraded is honest, not broken.** With no embedder configured (or the local model failed to load), `context_search` still works in BM25-only mode and returns `degraded: true, mode: "bm25-only"` — lexical recall with no semantic leg. A read-only store (daemon down) still serves `context_search` and `context_status`; only `context_index` is fenced off, returning a clear `ok: false, degraded: true` envelope rather than failing mid-write.
-- **Check health first when unsure.** `context_status` reports `docCount`, `vecCount`, `indexedFiles`, the active embedder (`kind` / `model` / `dim`), and the persistent `degraded` flag — read it once to know whether the index is populated and whether to expect vectors.
-- **Tools absent?** The three tools are registered only when the daemon was started with context enabled (the `ctx.context` service). If they are missing, run `noir init` and start the daemon before reaching for this skill.
-- Keep raw search output out of context where the tool already did the windowing; reach for whole-file reads only for the few files you will actually edit (see `noir-explore`). This skill grounds a query in indexed content — it does not review or refactor what it finds; hand to `noir-review` for judgment.
+
+- The index is a cache, not a replacement for reading files. Snippets show WHERE; reading shows CONTEXT.
+- `noir context index --force` rebuilds from scratch (good after large changes).
+- Zero API key required for local embeddings; remote/Ollama embedders are opt-in.
+
+## When done → next skill
+
+The snippets should answer your question. If not, try a more specific query, or read the implicated file directly.

package/builtin/noir-doctor/SKILL.md

@@ -1,12 +1,31 @@
 ---
 name: noir-doctor
-description: Use when diagnosing environment or project health — deps, config, runtime, toolchain.
+description: Use when diagnosing environment or project health — dependencies, config, runtime, toolchain, and Noir store integrity. Do NOT use for routine status checks — use noir-sync or noir-checkpoint.
+metadata:
+  category: meta
+  version: 1.0.0
+license: MIT
+compatibility: claude · agents-md · gemini · cursor · opencode
 ---
 
 # noir-doctor
 
-> **Stub:** this skill ships as a valid, loadable placeholder in S5; its full playbook is deepened in a later slice.
 
-**When to use:** something is off in the environment or project and you want a structured health check.
+## When to use
+- When the user triggers this skill.
 
-**For now:** check installed deps and versions against manifests, inspect config files, confirm the runtime and toolchain resolve, and report concrete mismatches — the `noir doctor` CLI command is the entry point.
+Check what's wrong. Run `noir doctor` and read every row — the command groups findings by category (install, config, store, daemon) and reports pass/warn/fail per check. Advisory, not mandatory — even a red check doesn't block.
+
+## Procedure
+
+1. **Run `noir doctor`.** In-process — no daemon needed. Read the full output on stderr.
+2. **Surface actionable issues.** A failed check should tell you what to fix. The install row checks Node version + managed runtime (if installed via native installer).
+3. **Fix one at a time.** Don't batch fixes — each fix deserves its own verification that the underlying issue resolved.
+4. **Re-run `noir doctor` to confirm green.**
+
+## When done → next skill
+
+→ The relevant skill for whatever was broken. Or continue working with a green doctor.
+
+## 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-executing-plans/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: noir-executing-plans
+description: Use when you have a written implementation plan and are ready to code — drive it task by task with a disciplined implement-test-commit loop. Use when the user says "implement this" or "start building". Do NOT use when there is no plan; run noir-planning first.
+metadata:
+  category: execute
+  version: 1.0.0
+license: MIT
+compatibility: claude · agents-md · gemini · cursor · opencode
+---
+
+# noir-executing-plans
+
+Drive a written implementation plan task by task, in order. Each task: implement → test → commit. One task at a time; each commit is a checkpoint.
+
+## When to use
+
+- A plan is written and it's time to code.
+- The user says "implement this", "start coding", "build it", or points at a plan file.
+- The plan has ordered tasks — you're executing them sequentially.
+- **Do NOT use:** for exploratory coding without a plan; use `noir-brainstorming` first. For independent tasks that can fan out concurrently, use `noir-parallel`. For a single subagent per task with review between, use `noir-subagent`.
+
+## Procedure
+
+1. **Load the plan.** Read the plan file. Confirm the task order. If a task depends on an earlier one, start there.
+2. **One task at a time.** Pick the next pending task. State which task you're executing. Do not bundle multiple tasks into one commit.
+3. **RED → GREEN → COMMIT.** Write the failing test first (see `noir-test-driven-development`), implement the minimal code to pass, verify the test goes green and no regression, then commit with a conventional-commit message. Repeat for the task's subtasks if any.
+4. **Mark the task done.** Update the plan's checkbox `- [x]` and move to the next task. The engine's execute gate records the checkpoint observably.
+5. **When the plan is done:** all tasks ticked, all tests green, the implementation matches the spec → hand off.
+
+## Verification
+
+- [ ] Every task in the plan is implemented, tested, and committed.
+- [ ] No regression in the existing test suite.
+- [ ] The implementation fulfills every acceptance criterion from the spec.
+- [ ] No "while I'm here" refactors crept into task commits (each commit is one task).
+
+## Notes
+
+- Don't skip tests because "the change is simple." A simple change that breaks silently is the most expensive bug.
+- If a task reveals that the plan is wrong, stop and update the plan — `noir-planning` for the revised scope, then resume.
+- Commit per task, not per file. A task = one logical change = one commit.
+
+## When done → next skill
+
+→ `noir-verifying` to prove the work is complete. Or is there another task you'd like to handle?

package/builtin/noir-exploring/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: noir-exploring
+description: Use when answering means sweeping many files, directories, or naming conventions — fan out read-only search and return the conclusion, not the dumps. Use when the user says "find all places where X", "what uses Y", or "audit the codebase for Z". Do NOT use for a targeted single-file read.
+metadata:
+  category: discovery
+  version: 1.0.0
+license: MIT
+compatibility: claude · agents-md · gemini · cursor · opencode
+---
+
+# noir-exploring
+
+Fan-out search for broad questions. One exploration = pattern → found → conclusion. The host reads excerpts, not whole files. You report the conclusion, not the dumps.
+
+## When to use
+
+- A question spans dozens of files.
+- The user says "where is X used", "find all Y", "audit the codebase for Z."
+- A naming convention, import pattern, or API usage needs a broad sweep.
+- **Do NOT use:** for a single file lookup — just use Read/Grep directly.
+
+## Procedure
+
+1. **Define the search.** What pattern are you looking for? Name it explicitly so the search is targeted.
+2. **Fan out.** On Claude Code, use `Grep` and `Glob` to find matches across the codebase. On other hosts, use the equivalent search tools. Search by file name, by content, or by dependency — pick the right tool per pass.
+3. **Synthesize, don't dump.** Read the relevant excerpts, form a conclusion, and report it. The host should never see raw 700-line grep output; they see "3 locations found, pattern is X."
+4. **Hand off.** If the exploration found something worth acting on, point to the right skill.
+
+## Verification
+
+- [ ] Search was broad enough to cover the question (not just one dir).
+- [ ] Conclusion is stated — not a file dump.
+- [ ] Edge cases were checked (variants of the pattern, sibling dirs).
+
+## When done → next skill
+
+→ `noir-systematic-debugging` if this was for a bug hunt, or the skill that matches the resulting task.

package/builtin/noir-frontend/SKILL.md

@@ -1,12 +1,40 @@
 ---
 name: noir-frontend
-description: Use when building or reshaping UI — for distinctive visual design, typography, and component patterns.
+description: Use when building or modifying frontend code — distinctive visual design, typography, component patterns, and responsive layouts. Do NOT use for pure backend logic.
+metadata:
+  category: domain
+  version: 1.0.0
+license: MIT
+compatibility: claude · agents-md · gemini · cursor · opencode
+references:
+  - ui-patterns.md
 ---
 
 # noir-frontend
 
-> **Stub:** this skill ships as a valid, loadable placeholder in S5; its full playbook is deepened in a later slice.
+Frontend design and implementation guide — visual design, component architecture, responsive patterns, and interaction behavior. Use when the user is building or reshaping UI.
 
-**When to use:** you are building or reshaping a UI and want intentional, distinctive design rather than templated defaults.
+## When to use
 
-**For now:** choose typography and a restrained palette deliberately, compose from primitives over chasing components, and let hierarchy and spacing carry the design.
+- Building or modifying a UI component, page, or layout.
+- The user says "design this", "style this", "make it look good."
+- A component needs consistent visual language (colors, spacing, typography, dark/light theme).
+
+## Procedure
+
+1. **Establish the design system.** Colors, spacing, typography, breakpoints — before any component. If the project has a design system (Tailwind config, theme tokens, CSS variables), use it; if not, suggest one.
+2. **Component-first thinking.** Break the UI into independent, composable components. One component = one file = one responsibility.
+3. **Responsive by default.** Start with mobile layout, add breakpoints for wider viewports. `max-width: 100%` on images; horizontal-scroll containers for wide tables.
+4. **Accessibility.** Semantic HTML, keyboard navigation, color contrast, screen-reader labels. An inaccessible UI is an unfinished UI.
+5. **On Claude Code**, use `AskUserQuestion` for design choices (color palette, layout preference). On other hosts, ask plainly.
+
+## Reference
+
+For design tokens, component structure, responsive, and accessibility patterns, see [ui-patterns.md](references/ui-patterns.md).
+
+## When done → next skill
+
+→ `noir-verifying` to confirm the UI meets the spec. Or `noir-test-driven-development` to add tests.
+
+## 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-frontend/references/ui-patterns.md

@@ -0,0 +1,48 @@
+# UI patterns — design system, components, accessibility
+
+Deep reference for `noir-frontend`. Practical patterns for building and reshaping UI that reads as one coherent system.
+
+## Establish the design tokens first
+
+A UI is coherent when it draws from ONE set of tokens. Before styling a component, confirm or propose:
+
+- **Color** — a small palette: background, surface, text-primary, text-muted, accent, error. Light + dark variants. Never 20 ad-hoc hex values.
+- **Spacing** — a scale (e.g. 4/8/12/16/24/32). Use the scale, not arbitrary pixels.
+- **Typography** — font stack, size scale (e.g. xs/sm/base/lg/xl/2xl), line-height, weight for headings vs body.
+- **Radius/shadow** — a consistent corner radius and elevation system.
+- **Breakpoints** — the widths where layout changes (e.g. 640/768/1024/1280).
+
+Where the project already has tokens (Tailwind config, CSS variables, a theme file), USE THEM — do not invent a parallel system.
+
+## Component-first structure
+
+- One component = one file = one responsibility. A `Button`, a `Card`, a `TableRow` — each standalone.
+- Components are composable: small pieces assemble into screens.
+- Props/inputs are explicit; a component never reaches into global state it wasn't given.
+
+## Responsive by default
+
+- **Mobile-first** — build the narrow layout first, add breakpoints for wider views.
+- `max-width: 100%` on images and media — never overflow.
+- Wide tables and code blocks scroll inside their OWN container (`overflow-x: auto`) — the page body never scrolls horizontally.
+- Touch targets ≥ 44px on interactive elements.
+
+## Accessibility (non-negotiable)
+
+- **Semantic HTML** — use `<button>`, `<a>`, `<nav>`, `<label>`, not `<div onClick>`.
+- **Keyboard** — every interactive element reachable + operable by keyboard (focus, Enter/Space).
+- **Focus** — a visible focus indicator; never `outline: none` without a replacement.
+- **Contrast** — text meets WCAG AA contrast against its background (both themes).
+- **Labels** — every input has a `<label>` or `aria-label`; images have alt text.
+- **Reduced motion** — respect `prefers-reduced-motion`.
+
+## Interaction behavior
+
+- **State** — every interactive element has hover / focus / active / disabled / loading states.
+- **Feedback** — actions give feedback (a spinner, a toast, a state change). Silent failure confuses users.
+- **Optimistic updates** with rollback on error feel faster than blocking on every request.
+
+## Good / bad
+
+Good: a component uses the spacing scale, tokens, semantic markup, and has all states.
+Bad: a hard-coded `padding: 17px`, an inline `#f3f2ef` that exists nowhere in tokens, a `<div onClick>` for a button, no focus style, an image with no alt.

package/builtin/noir-parallel/SKILL.md

@@ -1,50 +1,39 @@
 ---
 name: noir-parallel
-description: Use when facing two or more independent tasks with no shared state or ordering — to work them concurrently.
+description: Use when facing two or more independent tasks — dispatch them concurrently without blocking each other. Use when the user says "do these at the same time" or "work on both". Do NOT use for tasks that share state or have ordering; use noir-executing-plans or noir-subagent instead.
+metadata:
+  category: execute
+  version: 1.0.0
+license: MIT
+compatibility: claude · agents-md · gemini · cursor · opencode
 ---
 
-Dispatch one focused subagent per independent problem and let them run concurrently. Each subagent gets precisely crafted scope and context — never the controller's session history — so it stays narrow and you preserve your own context for coordination. Sequential investigation of independent problems wastes wall-clock; parallel dispatch collapses that to the slowest agent.
+# noir-parallel
 
-## Procedure
+When two or more tasks are independent (no shared state, no ordering), work them concurrently. Every tool dispatch in one response — no waiting for Task A to finish before starting Task B.
 
-### 1. Confirm the tasks are genuinely independent
-Before dispatching, verify:
-- each problem can be understood without context from the others;
-- fixing one cannot fix or break another;
-- the agents will not edit the same files or contend on the same resource (ports, locks, the working tree).
+## When to use
 
-If the failures are related, or you do not yet know what is broken, do not parallelize — investigate together first. Shared state and exploratory debugging disqualify this skill.
+- 2+ tasks that don't depend on each other.
+- The user says "do these at the same time", "concurrently", "parallelize."
+- A task naturally splits into non-overlapping sub-tasks.
+- **Do NOT use:** when tasks share state (B reads A's output). For a fan-out plan with review between tasks, use `noir-subagent`.
 
-### 2. Group by independent domain
-Cluster the work by what is actually broken or what is actually being built: one test file or subsystem per agent. "Fix all the tests" is too broad; "fix the 3 failing tests in `agent-tool-abort.test.ts`" is a domain.
+## Procedure
 
-### 3. Craft each task
-Each dispatch carries:
-- **Scope** — the exact file(s) or subsystem; name them.
-- **Goal** — what "done" looks like (tests green, function added with signature X).
-- **Context** — the error messages, test names, or interface contract the agent needs. Do not make it re-derive what you already know.
-- **Constraints** — what it must not touch ("production code", "other test files"), and any anti-patterns to refuse ("do not just raise the timeout — find the real issue").
-- **Output** — what to return (a summary of root cause and the change made, plus the test evidence).
+1. **Validate independence.** List the tasks. Confirm none reads another's output or touches the same file in a conflicting way.
+2. **Issue all dispatches in the same response.** On Claude Code, issue multiple tool uses concurrently. On other hosts, dispatch the equivalent parallel work.
+3. **Collect results.** Each result lands independently. Aggregate, then continue.
 
-### 4. Dispatch in parallel
-Issue every subagent dispatch in the same response — multiple dispatches in one response run concurrently, one per response runs sequentially. This is the move that buys the time saving.
+## When not to use
 
-### 5. Review and integrate
-When the agents return:
-- read each summary;
-- check the diffs for conflicts — did two agents edit the same code?;
-- run the full suite (not just each agent's scoped tests) to verify the fixes compose;
-- spot-check the changes — a subagent can make a systematic error that its own scoped tests do not catch.
+- Shared database or shared file writes — these must be sequential or protected by locking.
+- Tasks with a dependency chain — use `noir-executing-plans`.
+- Tasks that need per-task review — use `noir-subagent`.
 
-If two agents touched overlapping code, reconcile manually and re-run before claiming green.
+## When done → next skill
 
-## When not to use
-- The failures are related — fixing one might fix or break another.
-- Understanding requires seeing the whole system at once.
-- The work is exploratory — you do not yet know what is broken.
-- Agents would contend (editing the same files, binding the same port, taking the same lock).
+→ `noir-verifying` to confirm all tasks are done and integrated.
 
 ## Notes
-- Parallel dispatch trades coordination cost for wall-clock. For two small tasks, the overhead of crafting two briefs may not be worth it — sequential is fine. The win compounds at three or more independent domains.
-- Each agent's report is its deliverable; the controller's job at the end is integration and the full-suite check, not re-doing the investigation.
-- Discipline is observable, not rhetorical: the SDD engine records the parallel dispatch and its integrated result via `noir.checkpoint` (the SDD execute gate).
+- This skill is a playbook — the host decides which tools to use.

package/builtin/noir-planning/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: noir-planning
+description: Use when you have an approved spec and need a step-by-step implementation plan — naming files, interfaces, and tasks before touching code. Use when the user says "plan this" or "how should I build this". Do NOT use when the scope is already clear from the spec and the user asked to start coding.
+metadata:
+  category: plan
+  version: 1.0.0
+license: MIT
+compatibility: claude · agents-md · gemini · cursor · opencode
+---
+
+# noir-planning
+
+Break an approved spec into a concrete, step-by-step implementation plan. The plan names files, describes interfaces, and defines an order — so execution is mechanical, not improvisational. A plan is a contract, not a diary entry.
+
+## When to use
+
+- A spec is approved and it's time to plan the build.
+- The user says "plan this", "how should I implement this", "break this down."
+- The feature has enough moving parts (multiple files, dependencies, or non-trivial logic) that an ordered plan prevents rework.
+- **Do NOT use:** when the spec is trivial (one file, one function) and the user already knows the shape.
+
+## Procedure
+
+1. **Read the spec.** Reload the approved specification. Note every acceptance criterion — each one is a task or a test.
+2. **Decompose into tasks.** Break the work into the smallest units that carry their own test cycle and are worth a reviewer's gate. Each task names the files it touches and the interface it produces.
+3. **Order the tasks by dependency.** Which task must finish before another starts? List the chain.
+4. **Define the interfaces.** For each task, state what it consumes (from earlier tasks) and what it produces (for later tasks). Be specific — exact function names, parameter types, file paths.
+5. **Write the plan.** Record under `.noir/plans/<date>-<slug>.md`. Use a numbered task list with checkbox syntax (`- [ ]`) so the engine's verify gate can track completion.
+6. **Hand off.** Point to `noir-executing-plans` to drive the plan task by task.
+
+## Verification
+
+- [ ] Every acceptance criterion from the spec maps to ≥1 task.
+- [ ] Tasks are ordered (no circular dependencies).
+- [ ] Each task names the exact files + interfaces it produces.
+- [ ] The plan is committed to `.noir/plans/`.
+
+## Notes
+
+- A plan is a scaffold, not a prison. If a task reveals new information during execution, update the plan — don't force it through.
+- For a plan that fans out (independent tasks), note which tasks can run in parallel — `noir-parallel` can then dispatch them concurrently.
+- Don't pad a plan with "write tests," "run tests," "commit" per task — those are implicit in the execute-test-commit loop.
+
+## When done → next skill
+
+→ `noir-executing-plans` to implement the plan task by task. Or would you like to adjust anything first?