@iowarp/clio-coder 0.4.6 → 0.4.8

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

@@ -0,0 +1,106 @@
+# 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 eval skill` 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.
+
+## Battletest record (2026-09-03)
+
+Fixture: `/home/akougkas/eval-temp/harness/test_productintent.py`. S1's own
+domain ("a log-triage tool for HPC operators") made concrete: a repo with
+`docs/evidence/support-tickets.md` (3 tickets, a 45-min OOM triage, a
+silent-ECC lost queue, a tmux/grep cope with a ~12-node ceiling) and
+`docs/evidence/interview-notes.md` (3 operator quotes, including an explicit
+switch signal). Task: "write the PRD," grounding docs named but not pasted,
+so Step 0's read-first behavior is load-bearing. Graded 12 checks against
+real post-run disk state (file at `docs/<slug>.prd.md`, all 9 sections, a
+hypothesis with distinct RIGHT/WRONG, >=3 seeded facts grounded, zero
+stack-term leaks, non-goals, checkbox open questions) plus the reconstructed
+final assistant text (names the path, offers `architecture` next) and
+process (zero safety blocks, no `tasks` call). `qwen3.8-27b` on `dynamo`
+throughout; one confirm run on `ornith-1.5-35b-a3b`.
+
+| run | model | wall | turns | in / out tok | safety blocks | score | outcome |
+|---|---|---|---|---|---|---|---|
+| baseline (no skill) | qwen3.8-27b | 145s | 11 | 189.1k / 13.1k | 0 | 2/12 | wrote `PRD.md` at repo root (wrong name/path); no interview at all, no hypothesis RIGHT/WRONG block, no non-goals/open-questions sections; opened a task list (harmless here, no skill narrowing the surface) |
+| v1 (frozen 0.3.0) | qwen3.8-27b | 137s | 7 | 102.5k / 12.8k | 1 | 10/12 | correct path, sections, hypothesis, grounding, non-goals; opened a `tasks` call refused by the narrowed surface (self-recovered); degraded past the interview on its own reasoning ("`ask_user` isn't in this session's tool surface" — false, it is listed, the model just never tried it) rather than on any instruction in the skill |
+| v2 (first hardened cut) | qwen3.8-27b | 224s | 8 | 170.9k / 20.2k | 1 | 11/12 | no `tasks` call; ran the assumed-confirm monologue explicitly through all 5 clusters citing evidence; one `bash` call (a `$(...)` count-check on the written PRD) refused — `bash` was never in this skill's surface, model reached for it anyway to self-verify, then recovered with `grep` |
+| v3 (final 0.4.0) | qwen3.8-27b | 227s | 7 | 132.5k / 20.5k | 0 | 12/12 | same correctness as v2, self-verified with `grep`/`read` instead of `bash` after the added Red flags line; zero safety blocks, zero stack leaks, explicit "Process notes" section narrating the headless degradation cluster by cluster |
+| confirm (0.4.0) | ornith-1.5-35b-a3b | 69s | 11 | 158.6k / 10.8k | 1 | 11/12 | same content correctness; independently reached for a `bash` echo ("attempting ask_user via context") once, blocked, self-recovered with `grep` — the Red flags line reduced but did not eliminate the `bash` reflex on a second model family |
+
+**Changes** (0.3.0 -> 0.4.0): (1) an `## Arguments` contract stating there is
+no operator in a headless run, that `ask_user` returns immediately with no
+answers every time regardless of how many times it's called, and that the
+fix is to apply the existing "user declines" treatment cluster by cluster
+from wherever the first empty response lands — including Step 0's evidence
+check, which the old text left ungated but unaddressed for headless; (2) the
+decline paragraph in "The interview" now cross-references that headless
+default explicitly instead of leaving the model to infer it (v1 inferred a
+*wrong* reason — a nonexistent tool-surface gap — and got lucky); (3) an
+explicit "the clusters below are the plan; `tasks` is refused" line, which
+closed v1's one real safety block; (4) a new `## Red flags` section (the
+skill had none) naming the concrete failures seen across runs: stack-term
+leaks, a WRONG condition that's just RIGHT negated, the literal `PRD.md`
+name, re-calling `ask_user` after an empty response, skipping the loop
+outright instead of degrading into it, ungrounded claims, and reaching for
+`bash` (not in this skill's surface) to self-verify instead of `grep`/`read`.
+
+**Design note on the biggest named risk**: the mission brief flagged gating
+hard on Step 0/cluster 1 and never reaching Generate as the single biggest
+risk for this skill. It did not reproduce on either model tested, on any
+version including the unhardened v1 baseline snapshot — `ask_user`'s
+headless behavior in this harness (confirmed by reading
+`src/tools/ask-user.ts`: with no operator handler wired by `clio-coder run`,
+every `ask_user` call resolves immediately to `{cancelled: true}`, framed as
+an ok result with "proceed with defaults" guidance, never an error or a
+hang) means a stalled interview was never actually the failure mode to
+defend against here. What *was* real and reproduced on both models: an
+unprompted reach for `bash` to self-verify a written document, refused
+because `bash` is correctly outside this skill's surface. The hardening
+therefore targets the reproduced failure (`tasks` in v1, `bash` in v2/
+confirm), not the hypothesized one — matching context/context-handoff's
+own finding that the ask_user-stall defense is precautionary, not
+repro-driven, here too.
+
+**Still weak**: the `bash`-reach-to-verify reflex was reduced (v2 -> v3 on
+qwen3.8-27b: fixed) but not eliminated on ornith-1.5-35b-a3b, which hit the
+identical refused-tool pattern even after the Red flags line existed — a
+prose warning did not fully generalize across model families, only across
+runs of the same one. S2 (explicit "skip the questions, just write it") and
+S3 (solution-shaped request, "PRD for adding a reply button") from the
+scenario list above were not run standalone against 0.4.0 — only the S1-style
+combined evidence fixture ran, five times. The `git` tool (in allowed-tools)
+was never exercised in any run; a fixture with prior commits/branches to
+reference might exercise it. Only 27-35B class models tried, no small-model
+run.

package/library/skills/planning/product-intent/plugin.json

@@ -0,0 +1,23 @@
+{
+	"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+	"name": "product-intent",
+	"version": "0.4.1",
+	"description": "Writes a problem-first product document for a greenfield effort: interviews for the problem, evidence, and a falsifiable hypothesis, with zero engineering decisions. Not for engineering decisions; use architecture. Not for turning a locked idea into milestone build prompts; use prd.",
+	"license": "Apache-2.0",
+	"extensions": {
+		"ai.iowarp.clio": {
+			"manifestVersion": 1,
+			"kind": "skill",
+			"resources": {
+				"skills": "."
+			},
+			"components": [
+				{
+					"kind": "skill",
+					"id": "product-intent",
+					"path": "SKILL.md"
+				}
+			]
+		}
+	}
+}

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

@@ -0,0 +1,172 @@
+---
+name: tech-spec
+description: "Writes a typed call-stack architecture handoff: code-shaped contracts plus execution flows, implementation-ready for another engineer. User-invoked only. Not for weighing approaches or deciding the design; use architecture first."
+triggers:
+  - write a tech spec
+  - typed call-stack handoff
+  - code-shaped contracts
+  - implementation-ready technical specification
+  - specify execution flows
+version: 0.3.1
+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-coder:
+  registry-id: iowarp/clio-coder
+  source-url: https://github.com/iowarp/clio-coder/tree/main/library/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.
+
+## Arguments
+
+```text
+/skill tech-spec <the change, in a few sentences, or a path to read first>
+```
+
+- The text is the design problem: what's changing and why. A doc or file
+  path named in the request (a PRD, an architecture decision, a module) is
+  context to read, not more arguments — see "Load local context" below.
+- Nothing is required beyond some text; a blank invocation falls straight
+  to Path B's first question rather than inventing a change to spec.
+- **Output defaults to inline.** Write a file only when the request says
+  so explicitly — "save it", "write it to `<path>`", "put it in `docs/`".
+  Absent that, the finished spec is the reply itself: no file, in this run
+  or a prior one in the same session, gets created for it. This holds
+  regardless of which path below runs or how long the spec is — length is
+  never itself a reason to write a file.
+- Disabled for model self-invocation and requires the `tdd` skill be
+  installed to reference in the TDD Test Plan section; both are frontmatter
+  facts, not something to explain to the user unless asked.
+
+There is no operator in a headless run: `ask_user` is not registered, so
+any call is refused as an unregistered tool rather than answered, and a
+second try will not resolve differently. In Path B (below), that means: state the
+question, your recommendation grounded in the codebase and any docs read
+(or the most defensible engineering default when nothing grounds it), and
+the reasoning; adopt the recommendation; mark it `assumed — confirm`; move
+to the next question. Run every question this way, end to end, not just
+the first — the interview is the plan to execute, not an outline to
+abbreviate because no one answered the opening question. Never invent a
+fact or a codebase detail to back an assumption; anything genuinely
+unknown becomes an Open Question in the spec, not a plausible guess. This
+degrades the interview only — it never licenses writing a file that
+wasn't asked for.
+
+The steps below are the plan; do not open a task list for them. `tasks`
+sits outside this skill's tool surface and any call to it is refused.
+`bash` is also outside this skill's tool surface — verify what you wrote
+with `grep`, `read`, and `find`, never `bash`.
+
+## 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.
+  See Arguments above for how a headless run carries every question
+  through instead of stalling on the first one.
+
+## 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, nothing was implemented, and
+no file was written unless the request asked for one.
+
+## 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.
+- Writing the spec to a file when nothing in the request asked for one —
+  the default output is always the inline reply.
+- A Path B question left unanswered instead of run as the assumed-confirm
+  monologue, or an interview skipped straight into Path A without ever
+  asking the first question.
+- Opening a task list for the steps above; `tasks` is refused. Reaching for
+  `bash` to grep or verify the spec; `bash` is not in this skill's tool
+  surface and the call is refused — use `grep`/`read`/`find`.

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

@@ -0,0 +1,120 @@
+# 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 eval skill` 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.
+
+## Battletest record (2026-09-03)
+
+Fixture: `/home/akougkas/eval-temp/harness/test_techspec.py`, continuing the
+planning category's shared HPC log-triage domain (`product-intent` -> `prd`
+-> `tech-spec`). Seeds a plausible root `PRD.md` (purpose, features,
+out-of-scope, stack, integrations, data model, milestones, and the
+always-on-vs-on-demand ingestion tension explicitly marked as *not this
+document's decision*) plus the existing partial codebase (`src/scanner.py`:
+a working `FailureEvent` + `scan_oom`, OOM only) and two sample dmesg logs
+carrying real OOM/ECC/Xid line formats, inside a git repo. Three task
+variants, one fixture:
+
+- **base** (S1, Path A): "spec ECC + Xid detection and cross-signature
+  top-3 ranking" — sufficient context, no save request. Graded on 9 checks
+  against the *reconstructed final assistant text* (this skill's default
+  output is inline, not a file): all 11 outline-derived sections present,
+  >=5 domain grounding terms, >=2 materially different alternatives,
+  `FailureEvent` reused not respecced, nothing implemented (`scanner.py`
+  byte-identical to seed), the ingestion trade-off left unresolved, zero
+  safety blocks, no `tasks` call, and — the check this run exists to catch —
+  **no file written when nothing asked for one**.
+- **save** (S1 variant, confirmation only, run once on the final version):
+  same task plus an explicit "save it to docs/tech-spec-log-triage.md" —
+  10 checks, same 8 plus the file existing at exactly that path and no
+  other new file appearing.
+- **thin** (S2, Path B, confirmation only, run once on the final version):
+  a genuinely vague "improve our failure detection, you'll need to ask me
+  stuff" request with 5 lighter checks — zero safety blocks, no silent
+  stall, no `tasks` call, and either a real `ask_user` exchange or the
+  assumed-confirm monologue (`assumed` + `confirm` both present), with a
+  real spec still produced.
+
+| run | model | wall | turns | in / out tokens | safety blocks | score | outcome |
+|---|---|---|---|---|---|---|---|
+| baseline (no skill) | ornith-1.5-35b-a3b | 80s | 5 | 54.9k / 12.1k | 0 | 4/9 | never invoked `/skill tech-spec`; discovered the installed skill itself via `context(scope="skills")`, read its SKILL.md directly, then called `artifact` and terminated early with a `.clio-coder/artifacts/PLAN.md` instead of a spec — no alternatives, no sections, wrong output shape |
+| v1 (frozen 0.2.0) | ornith-1.5-35b-a3b | 95s | 8 | 115.0k / 15.1k | 1 | 6/9 | ran Path A correctly and produced a genuinely strong spec (11/11 sections, 3 material alternatives, `FailureEvent` reused, nothing implemented) but opened a `tasks` plan (refused, safety block) and **wrote the spec to `docs/tech-spec-scanner-ecc-xid.md` without being asked to** — the exact Path-A/B default-output risk flagged going in |
+| v2 (live 0.3.0) | ornith-1.5-35b-a3b | 68s | 5 | 57.2k / 10.4k | 0 | 9/9 | same spec quality, zero safety blocks, no `tasks` call, correctly returned inline with no file written; final text states explicitly "I did **not** write a file, since nothing in the request asked to save it" |
+| v2 confirm — save | ornith-1.5-35b-a3b | 110s | 11 | 184.8k / 16.5k | 0 | 10/10 | explicit "save it to docs/tech-spec-log-triage.md" correctly produces exactly that file at that path, nothing else |
+| v2 confirm — thin (Path B) | ornith-1.5-35b-a3b | 69s | 9 | 111.8k / 11.7k | 0 | 5/5 | correctly identified insufficient context, ran Path B, and carried all five scope decisions (S1-S5) through as an explicit assumed-confirm monologue headlessly instead of stalling or silently skipping to Path A |
+
+**Changes**: (1) `## Arguments` contract with the slash-invocation syntax,
+what's required vs. inferred, and — the section that mattered most here —
+an explicit "output defaults to inline" rule stated as its own bullet
+before the headless-monologue prose, so the fix for Path B's ask_user gap
+can't be misread as license to always write a file; (2) the headless
+no-operator paragraph, ported from `product-intent`/`prd`, applied to Path
+B's grill-me interview: every question runs as state-question /
+grounded-recommendation / reasoning / adopt / mark `assumed — confirm`,
+end to end, not just the first one; (3) explicit `tasks` and `bash`
+refusal lines — `tasks` was v1's only safety block; (4) `Done when` and
+`Red flags` both gained a line naming the unrequested-file failure and the
+unanswered-Path-B-question failure by name, plus the existing `tasks`/`bash`
+refusal repeated as a red flag (matching `prd`'s and `product-intent`'s
+pattern of naming the exact observed failure, not a generic reminder).
+Version 0.2.0 -> 0.3.0.
+
+**Still weak**: per this pass's coordinator note, no secondary-model
+confirmation was run (qwen3.8-27b was skipped in favor of running one full
+cycle on ornith-1.5-35b-a3b at speed, concurrently with a sibling agent
+hardening `architecture` on `mini`); the fix is validated on one model
+class only. The baseline's failure mode (discovering and improvising from
+the installed skill file directly, without ever invoking it, then calling
+`artifact` for an unrelated early exit) is a skill-selection/tool-scoping
+gap this SKILL.md cannot fix from inside its own body. `code_nav` (in
+`allowed-tools`) was never exercised — the fixture's one-file codebase
+never needed it. `requires: [skill:tdd]` is a diagnostic-only reference in
+this harness (unmet requires warn, never block `--skill`-path invocation);
+the TDD Test Plan section reads fine without the `tdd` skill installed, but
+that was not tested with `tdd` actually present to see if the reference
+changes. Genuine unknowns (S3 from the original evals) were exercised only
+incidentally via the Xid-severity and ECC-correctable open questions, not
+as an isolated scenario.

package/library/skills/planning/tech-spec/plugin.json

@@ -0,0 +1,23 @@
+{
+	"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+	"name": "tech-spec",
+	"version": "0.3.1",
+	"description": "Writes a typed call-stack architecture handoff: code-shaped contracts plus execution flows, implementation-ready for another engineer. User-invoked only. Not for weighing approaches or deciding the design; use architecture first.",
+	"license": "Apache-2.0",
+	"extensions": {
+		"ai.iowarp.clio": {
+			"manifestVersion": 1,
+			"kind": "skill",
+			"resources": {
+				"skills": "."
+			},
+			"components": [
+				{
+					"kind": "skill",
+					"id": "tech-spec",
+					"path": "SKILL.md"
+				}
+			]
+		}
+	}
+}

package/library/skills/registry.yaml

@@ -0,0 +1,144 @@
+# Pinned marketplace skill content hashes (provenance-stripped sha256).
+# Generated by `pnpm run skills:pin`. At activation, an installed skill
+# carrying registry-id provenance is compared against its pinned hash;
+# a mismatch surfaces a drift warning.
+skills:
+  # ── coding ──
+  - name: ast-grep
+    path: coding/ast-grep
+    version: 0.3.0
+    sha256: 0a72f4c906303f550be78f80a927da7e24e5c2076f058ccafdec80dfbed275af
+  - name: coding-standards
+    path: coding/coding-standards
+    version: 0.4.0
+    sha256: d573cdc5b430ae94ebfb5ef69c4a0ac9ac074aae815959ab4e6515012846ce3b
+  - name: prototype
+    path: coding/prototype
+    version: 0.4.0
+    sha256: 0f82df386c2ee565b0e968216ece746b1a11b4acd79676812074c1a406b698e1
+  - name: tdd
+    path: coding/tdd
+    version: 0.4.0
+    sha256: 63b88f29424091a92a8d8c0cc94474ae7e78af76491aea17e6f54af66f32db2d
+  # ── context ──
+  - name: context-handoff
+    path: context/context-handoff
+    version: 0.5.1
+    sha256: e05a8dc9d09b4decbf79afade1f530d7c81d5412112723faab104a83893c34f8
+  - name: context-prime
+    path: context/context-prime
+    version: 0.4.1
+    sha256: 3e6783d3fd95bd5635fe274ea0b9f73f3c4606ce64b832524cc242b114d8ef12
+  # ── git ──
+  - name: branch-closeout
+    path: git/branch-closeout
+    version: 0.1.0
+    sha256: 3227f31b0693bb6428abb20a2d4f449aeba1d8e45a79cf0c2c7c333c30c10664
+  - name: file-ticket
+    path: git/file-ticket
+    version: 0.3.0
+    sha256: 65029c2d9d545728750c8a713f92035bd6bdbfa9874de442df72bd059846cb7a
+  - name: fix-issue
+    path: git/fix-issue
+    version: 0.3.0
+    sha256: 626e3aa8ca95bc603f2e0cdd2e7502aa96be85af6bfa92b635c39ef99d3845a5
+  - name: resolve-merge-conflicts
+    path: git/resolve-merge-conflicts
+    version: 0.4.0
+    sha256: 901f482aa2231552d64a721e0d1c58dc8f211347543b5a91fd2ab3c7e413c11c
+  - name: ship
+    path: git/ship
+    version: 0.5.0
+    sha256: 4d626718fdb8b67cf3f22d09ac5a228e5c8103befa1295a672587a6605f038b1
+  - name: worktree-create
+    path: git/worktree-create
+    version: 0.6.0
+    sha256: a4ae790d916a170977814b4334e14aef4f96fb304e3289f7beb5e31e8fb83881
+  - name: worktree-merge
+    path: git/worktree-merge
+    version: 0.6.0
+    sha256: 0fbe2297622ed955b2e4fb14306d75a51bd36db7eebf59e8e92fac1da5b6e64e
+  # ── meta ──
+  - name: clio-coder-dev
+    path: meta/clio-coder-dev
+    version: 0.4.0
+    sha256: 8980f3bed0f06c24685bc0a02f3ffbbcdac9442616dc3ce54122265b666ae0d7
+  - name: clio-coder-test
+    path: meta/clio-coder-test
+    version: 0.3.1
+    sha256: 1e8c839b3668e50cd8ed7c69e7ae3ccc5afa15a1db72eb2b8babb1672134fba1
+  - name: credentials
+    path: meta/credentials
+    version: 0.2.0
+    sha256: d9382790ab30c9a13e5ca451f6f6b6b81eb8bcc6d458ad4931cc0495d39ea78d
+  - name: find-skills
+    path: meta/find-skills
+    version: 0.2.1
+    sha256: 48d35f7212d870d94354b8e792e363391ceb6692277012276f3a40c9a35411d9
+  - name: herdr
+    path: meta/herdr
+    version: 0.2.0
+    sha256: eeda051fe8736344b480fbd0d482a0e0ab82d4fc44e7ced5ff7058378beae3b6
+  - name: skill-craft
+    path: meta/skill-craft
+    version: 0.3.1
+    sha256: a8bc00508eca69e4988a4555ecdc9d3b29b2b00084374a2e9deca00fc80c8ffb
+  # ── planning ──
+  - name: archify
+    path: planning/archify
+    version: 0.1.0
+    sha256: a43f96828207ec63ff11bfbb0602f853c0de58c68f3c669d3c5ac687917cfd74
+  - name: architecture
+    path: planning/architecture
+    version: 0.4.1
+    sha256: 0d62ded74021d148f3091e044c32d205edfa3d1298706e68c84ad0f032d0feba
+  - name: backlog
+    path: planning/backlog
+    version: 0.4.1
+    sha256: 8fc700ad8f1b2f44fb6ea013c54ce06314cf9c4fdee63bd65c36686f5c25d092
+  - name: prd
+    path: planning/prd
+    version: 0.4.1
+    sha256: 3841f2f9635229c8208382e40123de1b5a496ec562cb851758d2ac013921c069
+  - name: product-intent
+    path: planning/product-intent
+    version: 0.4.1
+    sha256: 95d629fe8688003a9816a0774674f0c9fd5a922a82835415c3c1806799436832
+  - name: tech-spec
+    path: planning/tech-spec
+    version: 0.3.1
+    sha256: e8e6a1326aeb8b010647fc9fa9dc5ff827e13550f54524555f5e6a83341eb27f
+  # ── research ──
+  - name: arxiv-literature
+    path: research/arxiv-literature
+    version: 0.5.1
+    sha256: 4668827aa0f13527de5fc34914911ef942d2103ed3d139008fbd1c0ce2c4bd3d
+  - name: experiment-protocol
+    path: research/experiment-protocol
+    version: 0.3.1
+    sha256: da151931fb1961b19fcb6d4ae1957cef908f8b35692e301f109125488ad65302
+  - name: scientific-debugging
+    path: research/scientific-debugging
+    version: 0.3.1
+    sha256: ba94f8ad2655396a3791c7599631513f16651ffa61c8148044b996a25c0bc1cc
+  - name: scientific-modernization
+    path: research/scientific-modernization
+    version: 0.4.1
+    sha256: eb31099d764cba913c19726f6ba85d7081c5e01c81a3b2cd45eb136a4e47b858
+  # ── workflow ──
+  - name: cut-it
+    path: workflow/cut-it
+    version: 0.4.1
+    sha256: d0ce7dc6ea633d87e9e68c6b59ad402c24644b9eac580774410b235e0ca1c93f
+  - name: design-council
+    path: workflow/design-council
+    version: 0.6.0
+    sha256: 42fbf2e54524253b2955b22576ae0aca998dc04a902b8a59440edcfd051e0f5a
+  - name: grill-me
+    path: workflow/grill-me
+    version: 0.5.1
+    sha256: 3844770b507f9b2904aaa5c944c2b26f9ecf114383758dfff3bd7f39b2c717a6
+  - name: workflow-distiller
+    path: workflow/workflow-distiller
+    version: 0.4.2
+    sha256: 427009a3cf3e772520419761eca62b1e1ee41ad1bff9f1ed6e6c40871c9548d6

package/library/skills/remote.yaml

@@ -0,0 +1,13 @@
+# Skills whose content lives in another repository at a pinned ref.
+# Clio never vendors these. `npm run skills:pin` publishes each entry into
+# skill-marketplace.json with the upstream tree as its sourceUrl, the catalog
+# overlay whose files land on top of that tree at install, and the upstream
+# top-level members the install drops. The overlay SKILL.md is pinned in
+# registry.yaml like every other catalog skill.
+version: 1
+skills:
+  - name: archify
+    category: planning
+    sourceUrl: https://github.com/tt-a1i/archify/tree/v2.16.0/archify
+    overlay: library/skills/planning/archify
+    exclude: [test, package-lock.json]