@iowarp/clio-coder 0.3.0 → 0.3.2

package/skills/planning/architecture/evals.md

@@ -0,0 +1,36 @@
+# Evals — architecture
+
+Baseline scenarios (subagent WITHOUT the skill vs WITH). Pass/fail per
+bullet. Status: written at port time, not yet executed (`eval-status:
+untested`).
+
+## S1 — brownfield feature on an existing repo
+Setup: repo with an existing codebase and a short brief. Prompt: "figure
+out the architecture for adding X."
+Expected:
+- Reads the relevant existing surfaces before proposing.
+- 2-3 genuinely different approaches with trade-offs; recommendation with
+  reasoning; user makes the calls via ask_user.
+- One-way-door decisions get spikes with decision rules.
+- Doc written with the required shape; skipped sections noted.
+
+## S2 — greenfield with unfamiliar stack temptation
+Setup: user knows Python; the "modern" answer is a stack they don't know.
+Expected:
+- Familiarity weighed explicitly; the recommendation reflects the user's
+  goals, not fashion.
+
+## S3 — altitude check
+Setup: mid-session the user asks "just list the files to change for this".
+Expected:
+- Pulls back up to decisions; hands task-level planning to cut-it.
+
+## Baseline failure modes to watch for (RED)
+- One-shot architecture doc with silent convergence.
+- No alternatives, no trade-offs, no spikes.
+- Implementation task lists in the decision doc.
+
+## Smoke record (2026-08-13)
+
+One representative scenario via `clio-coder skills eval` against Nemo-3.5-Lightning
+(30B local, llamacpp on mini), full-auto sandbox. SMOKE ACTED but substance bullets failed (wrote final_report.md, skipped the loop). Headless degraded-mode and filename rules added to the body the same day; the re-smoke against the fixed body ran exit 1 at 12:15 CDT with no scored breakdown drained before the hard cutoff, so the substance verdict is unconfirmed.

package/skills/planning/backlog/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: backlog
+description: Use when a finished PRD or architecture doc must become a real ticket backlog — "create the stories", "turn this PRD into issues", "build the backlog". Decomposes phases and user stories into small tickets with verifiable acceptance criteria, confirms the list, then creates them as GitHub issues (or in another tracker when an integration exists). Not for local sprint slicing into a SPRINT.md; use cut-it.
+version: 0.2.0
+license: Apache-2.0
+allowed-tools:
+  - read
+  - grep
+  - ls
+  - bash
+  - tasks
+  - ask_user
+clio:
+  registry-id: iowarp/clio-coder
+  source-url: https://github.com/iowarp/clio-coder/tree/main/skills/planning/backlog
+  audit: pass
+  provenance: adapted
+  origin: https://github.com/coleam00/skills/tree/main/.claude/skills/backlog
+  eval-status: smoke-checked
+  model-size: any
+  agents:
+    - main
+---
+
+# Backlog
+
+Turn a finished planning doc into small, engineer-ready tickets on a real
+tracker. Decomposition is tracker-agnostic; creation branches on the target.
+
+## Step 1 — Inputs
+
+Required: the path to the PRD or planning doc. Target platform: GitHub
+issues via `gh` by default; another tracker only when the user names it and
+an integration for it is available. Platform genuinely ambiguous → ask,
+never guess. Optional: a milestone or epic to attach tickets to.
+
+## Step 2 — Decompose
+
+Read the doc in full. Each implementation phase becomes a ticket group;
+each user story becomes one or more tickets. Per ticket, draft:
+
+- **Title**: imperative and specific ("Add token refresh endpoint", never
+  "Auth").
+- **Description**: what and why, linked back to the source doc's phase.
+- **Acceptance criteria**: a checklist a reviewer can verify — observable
+  behavior, not "works correctly".
+- **Phase label**: `phase-N` from the source doc.
+
+Sizing rules: a ticket is at most about a day of work; a ticket that needs
+more than one screen to describe is two tickets. A phase too vague to
+decompose is a gap in the source doc — stop and flag it rather than
+inventing tickets.
+
+## Step 3 — Confirm before creating
+
+Print the full proposed list (titles grouped by phase) and the target
+platform, and get explicit confirmation via `ask_user`. Ticket creation is
+outward-facing and not one-click reversible; nothing is created before the
+yes.
+
+## Step 4 — Create
+
+GitHub:
+
+```bash
+gh label create "phase-N" 2>/dev/null || true
+gh issue create --title "..." --body "..." --label "phase-N" [--milestone "..."]
+```
+
+Acceptance criteria go in the body as a markdown checklist. Capture every
+created issue number and URL. A failed create is reported per ticket, not
+papered over.
+
+Local fallback: when the workspace has no GitHub remote, gh is unavailable,
+or the user asks for local tracking, create each confirmed ticket with the
+`tasks` tool instead (one task per ticket, acceptance criteria in the
+description) and capture the task ids. Say which target was used and why.
+
+## Step 5 — Report
+
+A table: title → phase → issue number/URL, plus the source doc path and any
+failures. Done when every proposed ticket is either created with its URL
+captured or listed as failed with the error.
+
+## Red flags
+
+- Tickets created before the Step 3 confirmation.
+- Acceptance criteria that restate the title.
+- A mega-ticket hiding a week of work.
+- Tickets with no trace back to a phase or story in the source doc.

package/skills/planning/backlog/evals.md

@@ -0,0 +1,43 @@
+# Evals — backlog
+
+Baseline scenarios (subagent WITHOUT the skill vs WITH). Pass/fail per
+bullet. Status: written at port time, not yet executed (`eval-status:
+untested`).
+
+## S1 — PRD with three phases
+Setup: create the stories from docs/x.prd.md.
+
+Fixture:
+```bash
+mkdir -p docs
+printf '# PRD: Todo CLI\n\n## Phase 1 - capture\nAs a user I can add a todo from the command line so nothing gets lost.\nAs a user I can list my todos in the order I added them.\n\n## Phase 2 - progress\nAs a user I can mark a todo done by its number.\nAs a user I can see done and open todos separately.\n\n## Phase 3 - hygiene\nAs a user I can delete a todo I no longer need.\n' > docs/x.prd.md
+```
+
+Expected:
+- Every proposed ticket traces to a phase or story; `phase-N` labels
+  planned per ticket.
+- Acceptance criteria are verifiable checklists.
+- The full ticket list is presented for confirmation (ask_user, or the
+  question stated explicitly) BEFORE any `gh issue create` attempt; if gh
+  cannot create against this workspace, that failure is reported honestly
+  with the confirmed list intact.
+
+## S2 — vague phase
+Setup: one phase says "improve performance".
+Expected:
+- Flags it as a source-doc gap; no invented tickets for it.
+
+## S3 — no platform determinable
+Setup: user names a tracker with no integration available.
+Expected:
+- Says so and asks; does not silently fall back.
+
+## Baseline failure modes to watch for (RED)
+- Creating tickets without confirmation.
+- One giant "implement phase 2" ticket.
+- Criteria like "feature works as expected".
+
+## Smoke record (2026-08-13)
+
+One representative scenario via `clio-coder skills eval` against Nemo-3.5-Lightning
+(30B local, llamacpp on mini), full-auto sandbox. PASS on re-run after adding the tasks tool to allowed-tools; first run degraded to prose because the tool was narrowed away.

package/skills/planning/prd/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: prd
+description: Use when the user wants to turn an idea into a product requirements document through a phase-gated interview — each phase locks before the next opens — ending in PRD.md plus per-milestone prompt files ready to drive a coding agent. Triggers on "write a PRD", "spec this out", "help me define this feature/product", or a brain dump that needs structure before planning.
+version: 0.2.1
+license: Apache-2.0
+allowed-tools:
+  - read
+  - grep
+  - ls
+  - find
+  - git
+  - context
+  - code_nav
+  - write
+  - edit
+  - ask_user
+clio:
+  registry-id: iowarp/clio-coder
+  source-url: https://github.com/iowarp/clio-coder/tree/main/skills/planning/prd
+  audit: pass
+  provenance: adapted
+  origin: buildermethods/bm-prd-creator
+  eval-status: smoke-checked
+  model-size: large
+---
+
+# PRD
+
+Guide the user from a raw idea to a locked product spec and executable
+milestone prompts. The discipline is the phase gate: each phase produces a
+small locked artifact that the next phase builds on. No phase reopens without
+the user saying so. Markdown only, no external templates, repo-aware.
+
+## Interview mechanics
+
+- Use the `ask_user` tool for every confirmation and choice, with your
+  recommendation as the first option. Without `ask_user`, ask in plain text,
+  one focused exchange per phase.
+- **Read the repo before asking.** Stack, conventions, existing entities, and
+  integrations are facts; discover them and *confirm*, never ask cold.
+- Keep each phase to one or two exchanges. Synthesize, propose, lock, move on.
+
+## The phases (in order, each locks before the next)
+
+1. **Brain dump.** Let the user describe the idea raw. Do not structure yet;
+   capture it.
+2. **Core purpose.** Synthesize a 1–3 sentence mission statement. Confirm.
+3. **Top-level features.** Propose 4–8 in-scope features derived from the
+   dump. Confirm the set.
+4. **Out of scope.** Propose explicit v1 cuts — what this deliberately does
+   not do. This list prevents scope creep later; make it real.
+5. **Stack and foundation.** Detect the stack from the repo (manifests, lock
+   files, configs); confirm it and inventory what foundation already exists.
+6. **Integrations and credentials.** Map external services and the API
+   keys/credentials each requires. Note which exist versus which the user
+   must provision.
+7. **Data model.** Entities, fields, and relationships in plain language.
+   Reuse existing repo entities where they fit.
+8. **Per-feature scoping.** For each locked feature: granular in/out
+   boundaries. This is where v1 honesty lives.
+9. **Milestones.** Propose a dependency-ordered milestone sequence, each with
+   a one-line scope. Confirm.
+
+## Output artifacts (phase 10 — write files)
+
+- **`PRD.md`** at the repo root: purpose, features, out-of-scope, stack,
+  integrations, data model, per-feature scope, milestone overview. Markdown
+  only.
+- **`milestones/N-<slug>/prompt.md`** for each milestone: a self-contained
+  prompt that a coding agent can execute cold — context, scope, constraints
+  from the PRD, and done-when criteria. A reader must not need the PRD open
+  to act on it.
+
+Offer the natural next step: run `cut-it` on a milestone prompt to slice it
+into a sprint.
+
+## Red flags (you are doing it wrong)
+
+- Asking about the stack when package.json answers it.
+- A phase "locked" without the user confirming it.
+- Out-of-scope list that is empty or generic ("no mobile app").
+- Milestone prompts that say "see PRD for details".

package/skills/planning/prd/evals.md

@@ -0,0 +1,49 @@
+# Evals — prd
+
+Baseline scenarios (run a subagent WITHOUT the skill to capture the gap, then
+WITH the skill to confirm it closes). Rubric is pass/fail per bullet.
+
+## S1 — brain dump to spec
+Setup: Okay, brain dump. Our users keep asking for saved searches — they
+build the same filter combos every day and lose them on refresh. I am
+thinking they can name a search, get it in a sidebar list, maybe share a
+link to it with a teammate. There is also the question of limits, do free
+users get three saved searches or unlimited, and should a shared link work
+for someone without an account? I have not decided. Somewhere down the
+line I would also love alerts, like notify me when a saved search has new
+results, but that might be its own thing. Spec this out.
+
+Fixture:
+```bash
+mkdir -p src
+printf '{\n  "name": "search-app",\n  "version": "1.0.0",\n  "private": true,\n  "dependencies": {\n    "typescript": "5.5.0"\n  }\n}\n' > package.json
+printf 'export function runSearch(filters: string[]): string[] {\n  return filters;\n}\n' > src/search.ts
+```
+
+Expected:
+- Proceeds phase by phase; each phase confirmed before the next opens.
+- Detects the stack from the repo and confirms rather than asking cold.
+- Produces PRD.md plus milestones/N-slug/prompt.md files.
+- Each milestone prompt is executable without the PRD open (self-contained).
+
+## S2 — scope honesty
+Setup: brain dump implies ten features. Prompt: "spec this out for v1."
+Expected:
+- Proposes 4–8 core features and pushes the rest to an explicit out-of-scope list.
+- Out-of-scope entries are specific to this product, not boilerplate.
+
+## S3 — existing foundation
+Setup: repo already implements half the data model the idea needs.
+Expected:
+- Inventories the existing entities in phase 5/7 and reuses them.
+- Does not spec already-built functionality as new work.
+
+## Baseline failure modes to watch for (RED)
+- One giant questionnaire instead of phase-gated exchanges.
+- PRD written without any user confirmation of features/scope.
+- Milestone prompts that are headings with no executable content.
+
+## Smoke record (2026-08-13)
+
+One representative scenario via `clio-coder skills eval` against Nemo-3.5-Lightning
+(30B local, llamacpp on mini), full-auto sandbox. WEAK PASS. Engaged the brain dump and asked the first phase-gate question; single-turn headless ends there by design, so no PRD file was produced in-run.

package/skills/planning/product-intent/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: product-intent
+description: Use at the start of a greenfield product effort, when the user wants a problem-first product document — "why are we building this", "write the product thesis", "PRD for this idea". Interviews for the problem, evidence, and a falsifiable hypothesis; writes an intent-only PRD with zero engineering decisions. Not for engineering decisions; use architecture. Not for turning a locked idea into milestone build prompts; use prd.
+version: 0.2.0
+license: Apache-2.0
+allowed-tools:
+  - read
+  - grep
+  - find
+  - ls
+  - git
+  - context
+  - write
+  - ask_user
+clio:
+  registry-id: iowarp/clio-coder
+  source-url: https://github.com/iowarp/clio-coder/tree/main/skills/planning/product-intent
+  audit: pass
+  provenance: adapted
+  origin: https://github.com/coleam00/skills/tree/main/.claude/skills/product-intent
+  eval-status: smoke-checked
+  model-size: large
+  agents:
+    - main
+---
+
+# Product Intent
+
+A PRD is intent: the problem and the hypothesis about solving it, in a form a
+team can challenge before building and judge after shipping. Engineering
+decisions (library, data model, boundaries) never enter it; they belong to
+`architecture`.
+
+Two hard guards, checked before writing anything:
+
+1. **Intent-framed.** If only one solution could fit your problem statement,
+   you wrote a spec, not a PRD. "Give users a way to group related replies"
+   passes; "add a reply button" fails.
+2. **Never invent requirements.** Anything unknown ships as
+   "TBD — needs validation", verbatim, never as a plausible guess.
+
+## Step 0 — Ground in evidence
+
+If the user passed reference docs (interviews, support tickets, analytics,
+competitor notes), read them first and treat them as evidence. If none were
+passed, ask whether any exist before interviewing.
+
+## The interview
+
+Ask in clusters via `ask_user`, and GATE: post the cluster, stop, wait for
+answers. Never answer your own questions, never roll into the next phase in
+the same turn. Thin answers get reflected back and dug into.
+
+If the user declines the interview ("just write it"): honor it, name what
+you will have to leave TBD, ask only the two or three highest-leverage
+questions, and mark everything else "TBD — needs validation".
+
+1. **Initiate.** Input given → restate and confirm. Blank → "What do you
+   want to build? A few sentences." GATE.
+2. **Foundation.** Who has the problem (a specific role, not "users")? What
+   is the observable pain? How do they cope today (workaround, competitor,
+   tolerating)? Why now? And the switch test: do you solve it so much better
+   they leave their current cope? No switch case → no product yet; say so.
+   GATE.
+3. **Users.** One-sentence vision · primary user (role, context, trigger) ·
+   job-to-be-done ("When [situation], I want [motivation], so I can
+   [outcome]") · explicit non-users · constraints. GATE.
+4. **Hypothesis.** Co-write the falsifiable bet. The WRONG condition is the
+   most-skipped line and the one that makes it a hypothesis:
+
+   ```
+   We believe [change] will cause [users] to [do Y], resulting in [outcome].
+   RIGHT if [leading signal] within [timeframe].
+   WRONG if [counter-signal / a guardrail moves].
+   ```
+
+   No hypothesis ships without a WRONG condition. GATE.
+5. **MVP and doors.** MVP = the thinnest end-to-end line that proves the
+   hypothesis right or wrong, not "the product, smaller". Mark each major
+   call two-way door (reversible → just build) or one-way door (expensive to
+   undo → flag for a spike in architecture). GATE before generating.
+
+Optional pressure test when useful: value (do they want it more than their
+cope?), usability, feasibility, viability. Most ideas over-argue feasibility
+and under-argue value.
+
+## Generate
+
+Write to `docs/<kebab-slug>.prd.md` (slug from the core idea; repo root if
+no `docs/`; a user-supplied path always wins). Never hardcode `PRD.md` — a
+second PRD must not overwrite the first. Sections, scannable, product only:
+
+1. **Problem statement** — who, what pain, cost of not solving it.
+2. **Evidence** — quote/data/observation, or "Assumption — validate via
+   [method]".
+3. **Thesis** — why this, why now, why it beats the current cope.
+4. **Hypothesis** — the RIGHT/WRONG block, verbatim.
+5. **Target user & JTBD** — plus non-users.
+6. **MVP** — the thinnest proving line.
+7. **Success metrics** — outcome-shaped: metric · target · how measured.
+   "Engagement" is not a metric.
+8. **Non-goals.**
+9. **Open questions** — named checkboxes, never hidden.
+
+## Done when
+
+The file exists; the summary to the user leads with thesis and hypothesis,
+counts evidenced-vs-assumed claims and open questions; and the next step is
+offered: `architecture` for the engineering decisions this PRD
+deliberately left open. Failing any of the five tests below means not done:
+evidence-grounded problem · hypothesis with separate RIGHT and WRONG ·
+outcome-shaped metrics · explicit non-goals · zero engineering decisions.

package/skills/planning/product-intent/evals.md

@@ -0,0 +1,36 @@
+# Evals — product-intent
+
+Baseline scenarios (subagent WITHOUT the skill vs WITH). Pass/fail per
+bullet. Status: written at port time, not yet executed (`eval-status:
+untested`).
+
+## S1 — greenfield idea
+Prompt: "I want to build a log-triage tool for HPC operators, write the PRD."
+Expected:
+- Interviews in gated clusters; never answers its own questions.
+- Hypothesis block has both RIGHT and WRONG conditions.
+- Output lands at `docs/<slug>.prd.md`, not `PRD.md`.
+- Zero engineering decisions (no stack, no schema, no libraries).
+- Unknowns say "TBD — needs validation", not invented requirements.
+
+## S2 — user declines the interview
+Prompt: "skip the questions, just write it."
+Expected:
+- Asks only 2-3 highest-leverage questions, names what goes TBD.
+- No fabricated evidence or metrics.
+
+## S3 — solution-shaped request
+Prompt: "PRD for adding a reply button."
+Expected:
+- Reframes to the underlying problem; the problem statement admits more
+  than one solution.
+
+## Baseline failure modes to watch for (RED)
+- One-shot PRD generated from thin air.
+- Hypothesis with no WRONG condition.
+- "React + Postgres" appearing anywhere in the document.
+
+## Smoke record (2026-08-13)
+
+One representative scenario via `clio-coder skills eval` against Nemo-3.5-Lightning
+(30B local, llamacpp on mini), full-auto sandbox. PASS. Interview degraded gracefully headless; PRD written to docs/, judge 5/5.

package/skills/planning/tech-spec/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: tech-spec
+description: Write a typed call-stack architecture handoff — code-shaped contracts plus execution flows, implementation-ready for another engineer. User-invoked only.
+version: 0.1.0
+license: Apache-2.0
+disable-model-invocation: true
+allowed-tools:
+  - read
+  - grep
+  - find
+  - ls
+  - git
+  - context
+  - code_nav
+  - write
+  - ask_user
+requires:
+  - skill:tdd
+clio:
+  registry-id: iowarp/clio-coder
+  source-url: https://github.com/iowarp/clio-coder/tree/main/skills/planning/tech-spec
+  audit: pass
+  provenance: adapted
+  origin: https://github.com/dmmulroy/skills/tree/main/tech-spec
+  eval-status: smoke-checked
+  model-size: large
+  provisional: true
+  agents:
+    - main
+---
+
+# Tech Spec
+
+A tech spec is a typed call-stack architecture handoff: contracts as
+TypeScript pseudocode plus end-to-end execution flows. Prose explains why;
+types and call stacks define what changes. Design only — never implement,
+and save a file only when the user asks; otherwise return the spec inline.
+
+## Choose the path
+
+- **Path A — convert context to spec**: the conversation, docs, or codebase
+  already describe the change.
+- **Path B — interview first**: not enough problem, constraints, or
+  acceptance criteria exist. Say so, then interview one question at a time
+  with a recommended answer per question (the grill-me posture); anything
+  answerable by exploring the codebase is explored, not asked. When context
+  suffices, run Path A. Never invent requirements to skip the interview.
+
+## Path A
+
+1. **Load local context.** Inspect existing code and docs for vocabulary,
+   module layout, error style, adapters, test conventions. Done when the
+   spec introduces no pattern, library, or schema style without checking
+   local precedent.
+2. **Extract the design problem.** Current state, problem, callers, goals,
+   non-goals, constraints, invariants, affected systems, entrypoints,
+   risks. Unknowns become open questions, never plausible filler. Done when
+   every claimed constraint traces to conversation, code, docs, or an open
+   question.
+3. **Explore alternatives.** 2-3 designs differing materially — interface
+   shape, seam placement, ownership, call stack, module boundaries — not
+   just names. Sketch each: domain types, interfaces, failure types, seams,
+   entrypoint-to-effect call stack, test strategy, trade-offs. Compare on
+   caller burden, module depth, locality of change, seam placement,
+   testability through real seams, complexity. Done when the
+   recommendation is chosen after the comparison, not before.
+4. **Specify the contracts.** For the recommended design, every new,
+   changed, or deleted type, signature, interface, error union, adapter,
+   DTO, and API gets a concrete sketch — or an explicit reason no new
+   contract is needed. Name what each layer may know and what must not
+   leak across each seam.
+5. **Specify call stacks.** Every affected behavior gets an entrypoint →
+   side-effect → response trace with the type/data flow (`raw input →
+   parser → domain input → service → adapter → typed result → projection →
+   output`), current-vs-proposed when changing behavior, and failure /
+   retry / idempotency flow where reachable.
+6. **Map files.** Files to add, change, delete; test files; config or
+   migration files. Each maps to the contract or call-stack step it owns.
+7. **Write the TDD plan.** Vertical red-green slices per the `tdd` skill:
+   one failing behavior test, minimal implementation, repeat. Cover happy
+   paths, failure paths, parser rejection, invariants, changed seams — or
+   state why a path is deliberately untested.
+
+## Spec outline
+
+Use this shape (omit sections that truly do not apply, but never omit
+contracts, seams, call stacks, or the test plan for being hard):
+
+```md
+# <Title>
+## Summary · Context / Current State · Goals · Non-Goals · Invariants ·
+## Design Constraints
+## Alternatives Considered (Option 1..3)
+## Recommendation · Proposed Design
+## Domain Model and Types · Types, Interfaces, and APIs
+## Seams, Boundaries, Adapters, and Implementations
+## Call Stacks and Data Flow (current / proposed / failure / retry)
+## Files to Add / Change / Delete
+## TDD Test Plan
+## Risks and Open Questions
+```
+
+## Done when
+
+The spec follows the outline, every boundary has a typed contract or a
+stated reason it needs none, every behavior has a call stack, unknowns are
+open questions rather than invented design, and nothing was implemented.
+
+## Red flags
+
+- Prose where a type signature would be more precise.
+- A recommendation written before the alternatives.
+- Speculative seams no invariant, boundary, or test earns.
+- The same rule restated in three sections.
+- "While I'm here" implementation.

package/skills/planning/tech-spec/evals.md

@@ -0,0 +1,47 @@
+# Evals — tech-spec
+
+Baseline scenarios (subagent WITHOUT the skill vs WITH). Pass/fail per
+bullet. Status: written at port time, not yet executed (`eval-status:
+untested`); skill is marked provisional and user-invoked only.
+
+## S1 — sufficient context (Path A)
+Setup: write a tech spec for adding per-client rate limiting to the ingest
+endpoint in src/ingest.js; limits should be configurable and violations
+must return 429 without dropping the connection.
+
+Fixture:
+```bash
+mkdir -p src
+printf 'const http = require("http");\nconst { parseEvent } = require("./parse-event.js");\n\nconst INGEST_ROUTE = "ingest";\n\nfunction createIngestServer(store) {\n  return http.createServer((req, res) => {\n    if (req.url.slice(1) !== INGEST_ROUTE || req.method !== "POST") {\n      res.writeHead(404);\n      res.end();\n      return;\n    }\n    let body = "";\n    req.on("data", (chunk) => { body += chunk; });\n    req.on("end", () => {\n      const parsed = parseEvent(body);\n      if (parsed.err) {\n        res.writeHead(400);\n        res.end(JSON.stringify({ error: parsed.err }));\n        return;\n      }\n      store.append(parsed.value);\n      res.writeHead(202);\n      res.end();\n    });\n  });\n}\n\nmodule.exports = { createIngestServer };\n' > src/ingest.js
+printf 'function parseEvent(raw) {\n  try {\n    const value = JSON.parse(raw);\n    if (typeof value.client !== "string") return { err: "missing client" };\n    return { err: null, value };\n  } catch {\n    return { err: "invalid json" };\n  }\n}\n\nmodule.exports = { parseEvent };\n' > src/parse-event.js
+```
+
+Expected:
+- Local conventions inspected before any pattern is proposed.
+- 2-3 materially different alternatives compared before recommending.
+- Typed contracts for every new/changed boundary; call stacks with data
+  flow; file map; vertical TDD plan.
+- Nothing implemented; spec returned inline (no file unless asked).
+
+## S2 — thin context (Path B)
+Setup: user asks for a spec with only a vague sentence.
+Expected:
+- States context is insufficient; interviews one question at a time with
+  recommended answers; explores the codebase instead of asking what code
+  answers.
+- Converts to Path A only when context suffices.
+
+## S3 — unknowns
+Setup: a dependency's behavior is genuinely unknown.
+Expected:
+- Recorded as an open question, not filled with plausible design.
+
+## Baseline failure modes to watch for (RED)
+- Prose-only spec with no typed contracts or call stacks.
+- Single foregone design presented as "the" answer.
+- Implementation snuck in.
+
+## Smoke record (2026-08-13)
+
+One representative scenario via `clio-coder skills eval` against Nemo-3.5-Lightning
+(30B local, llamacpp on mini), full-auto sandbox. PASS. Spec written and its claims exercised with node -e; judge 4/4.