@iowarp/clio-coder 0.3.1 → 0.3.2

package/skills/meta/skill-craft/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: skill-craft
+description: Use when writing, reviewing, or pruning a SKILL.md — authoring a new skill, editing an installed one, or judging whether a skill's description, body, or length is earning its cost. Triggers on "write a skill", "improve this skill", "why isn't this skill firing", "is this skill too long".
+version: 0.1.1
+license: Apache-2.0
+allowed-tools:
+  - read
+  - grep
+clio:
+  registry-id: iowarp/clio-coder
+  source-url: https://github.com/iowarp/clio-coder/tree/main/skills/meta/skill-craft
+  audit: pass
+  provenance: designed
+  eval-status: scenarios-recorded
+  model-size: large
+---
+
+# Skill Craft
+
+A skill exists to wrangle predictability out of a stochastic system: the same
+process every run, not the same output. Every rule below is a lever on that
+one virtue. A disputed line is settled by running the skill, not by debate;
+in Clio that means `clio-coder skills eval`, and a shipped skill's `evals.md`
+Expected bullets are its completion criteria.
+
+## Format and Location
+
+A skill is a folder holding a `SKILL.md`, written with the ordinary write
+tool. Project skills live in `.clio-coder/skills/<name>/`; user skills in the Clio
+config dir under `skills/<name>/`. The loader validates on load; check work
+with `clio-coder skills validate`. Frontmatter contract (Agent Skills compatible):
+
+- `name`: lowercase-hyphen, ≤64 chars, must match the folder.
+- `description`: required, ≤1024 chars; its craft is the section below.
+- `disable-model-invocation: true`: hides the skill from the agent; only the
+  user can activate it.
+- `allowed-tools`: tools the skill body may call.
+- `requires`: `skill:<name>` dependencies; the loader warns when one is
+  missing. Reference an installed skill by name instead of restating its job.
+
+Sibling files (`references/*.md`, `evals.md`, scripts) ride along in the
+folder and load only when the body points at them.
+
+## Invocation: Choose Which Load You Pay
+
+A model-invoked skill's description sits in the agent's context every turn:
+that is context load, paid forever. A hidden skill costs nothing in context
+but the user must remember it exists: cognitive load. Keep a description only
+when the agent must reach the skill on its own or another skill requires it;
+if it only ever fires by hand, set `disable-model-invocation: true`.
+
+## Description: Triggers, Not Identity
+
+The description is the skill's trigger surface, so every word competes with
+every other skill's description:
+
+- Front-load the strongest trigger word.
+- One trigger per distinct branch. Synonyms restating one branch ("API key",
+  "credential", "token") are duplication; keep the strongest.
+- Cut identity the body already states; keep triggers, plus one "Not for X;
+  use <other-skill>" clause per real boundary.
+- Word triggers with the language the user actually types.
+
+## Body: Steps and Reference
+
+Two content types, mixing freely. Steps are ordered actions; reference is
+material consulted on demand. Rank by how immediately the agent needs each
+piece: steps first, in-file reference second, sibling-file reference behind a
+pointer last.
+
+- End every step on a checkable, exhaustive completion criterion: "every
+  modified file accounted for", never "understanding reached". A vague bound
+  invites the agent to declare done early.
+- Keep one concept's definition, rules, and caveats under one heading, not
+  scattered.
+- Push material only some runs need into `references/<topic>.md`. The
+  pointer's wording decides whether the agent follows it: state the condition
+  ("when the tests use the mock provider, read references/harness.md"), not
+  just the link.
+- Prefer one pretrained word over a restated sentence: "fast, deterministic,
+  low-overhead" collapses to "tight". A strong word anchors the same behavior
+  every time it appears; a weak one ("be thorough") changes nothing and
+  should be deleted or strengthened ("relentless").
+
+## Pruning
+
+Before finishing any skill, pass the body line by line:
+
+- Relevance: does the line still bear on what the skill does? Stale layers
+  accumulate because adding feels safe and removing feels risky; remove.
+- Duplication: each meaning lives in exactly one place. A repeated meaning
+  also inflates its apparent importance.
+- No-op: would the agent do this by default? Then the line buys nothing;
+  delete the whole sentence, not words within it.
+- Sprawl: past ~120 body lines, either disclose reference into sibling files
+  or split the skill; a split description must earn its permanent context
+  load.
+
+Done when: description is triggers-only, every step has a checkable
+completion criterion, no line fails the relevance/duplication/no-op pass, and
+an `evals.md` records at least one RED-GREEN scenario distinguishing
+with-skill from without.

package/skills/meta/skill-craft/evals.md

@@ -0,0 +1,41 @@
+# Evals — skill-craft
+
+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 — author a skill from a description of a workflow
+Setup: any repo. Prompt: "write a project skill called log-triage that greps
+service logs for errors, groups them by cause, and files a summary."
+Expected:
+- Writes `.clio-coder/skills/log-triage/SKILL.md` directly with the write tool.
+- Description is triggers-only, front-loaded, no synonym-duplicated branches.
+- Every step ends on a checkable completion criterion, not "until done".
+- Frontmatter passes `clio-coder skills validate`.
+
+## S2 — prune an overgrown skill
+Setup: repo containing a 200-line skill whose body restates one rule three
+times, carries two "always be careful" no-op lines, and inlines a long
+reference table used by one branch. Prompt: "improve this skill."
+Expected:
+- Collapses the repeated rule to a single statement.
+- Deletes the no-op sentences entirely rather than rewording them.
+- Moves the branch-only table into `references/` behind a conditional pointer.
+
+## S3 — diagnose a skill that never fires
+Setup: installed skill whose description is a one-line identity statement
+with no trigger words. Prompt: "why does this skill never activate?"
+Expected:
+- Attributes the failure to the description, not the body.
+- Rewrites the description with user-language triggers, one per branch.
+
+## Baseline failure modes to watch for (RED)
+- Scaffolding ceremony: reaching for a create command or tool instead of
+  writing the SKILL.md file.
+- Descriptions that describe what the skill is instead of when to use it.
+- "Done when it works" completion criteria.
+- Rewording weak lines instead of deleting them.
+
+## 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. NOT COMPARABLE: baseline arm hit the loop guard, so no baseline exists; treatment was visibly scaffolding a skill when the run was scored INFRA.

package/skills/planning/architecture/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: architecture
+description: 'Use when an intent (PRD, epic, brief, or idea) needs its engineering approach decided — "how should we build this", "pick the stack", "architecture for this feature". An interactive working session: investigates, proposes 2-3 genuinely different approaches with trade-offs, recommends with reasoning, lets the user decide, and writes a high-level architecture decision doc. Not a task-by-task plan; use cut-it for that. Not a multi-perspective debate; use design-council. Not product intent; use product-intent.'
+version: 0.2.0
+license: Apache-2.0
+allowed-tools:
+  - read
+  - grep
+  - find
+  - ls
+  - git
+  - context
+  - code_nav
+  - web_fetch
+  - write
+  - ask_user
+clio:
+  registry-id: iowarp/clio-coder
+  source-url: https://github.com/iowarp/clio-coder/tree/main/skills/planning/architecture
+  audit: pass
+  provenance: adapted
+  origin: https://github.com/coleam00/skills/tree/main/.claude/skills/architecture
+  eval-status: smoke-checked
+  model-size: large
+  agents:
+    - main
+---
+
+# Architecture
+
+The intent says what and why; this session decides how: approach, stack,
+data shape, boundaries, and what to de-risk first. The deliverable is a
+high-level decision doc — the moment you start listing file edits or task
+steps, you have gone too deep; pull back up to the decisions.
+
+This is interactive. Run the loop out loud with the user, via `ask_user`:
+
+```
+investigate → 2-3 options with trade-offs → recommend + reasoning →
+ask → wait for their call → go deeper
+```
+
+Never converge silently. Optimize for the user's goals, familiarity (a
+stack they know beats a "better" one they don't), leanness (decide only
+what is needed to move), and reversibility (spend deliberation on the
+expensive calls only).
+
+When asking is unavailable (headless or worker run), do not skip the loop
+and do not go quiet: for each decision, state the options, the
+recommendation, and the reasoning inline, adopt the recommendation, and
+mark it `assumed — confirm`. Every other rule still applies, including the
+output path below.
+
+## Step 0 — Ground
+
+Read the intent (PRD path, brief, or the user's words). Read any reference
+docs passed alongside; if none were passed, ask whether any exist — the
+context needed is usually already written down.
+
+## Step 1 — Greenfield or brownfield
+
+Infer from the input and workspace; genuinely unclear → ask. It changes the
+exploration:
+
+- **Greenfield**: explore the solution space — approaches, current best
+  practice (web_fetch when it materially helps), first principles.
+- **Brownfield**: read the relevant existing surfaces first — where this
+  plugs in, what it reuses, what it must not break. High-level read, not a
+  file audit.
+
+## Step 2 — Explore, decision by decision
+
+For each area, surface options, recommend with reasoning, ask, record the
+user's call. Skip what does not apply and say that you skipped it:
+
+- **Approaches**: 2-3 genuinely different directions with trade-offs.
+- **Stack & libraries**: what and why (fit, maturity, familiarity), with
+  alternatives named.
+- **Data model**: main entities, relationships, storage — shape level, not
+  columns and migrations.
+- **Boundaries & contracts**: auth posture, secrets, external services,
+  the API/integration boundaries crossed. Flag, never gloss.
+- **Missing pieces**: what has to exist that does not yet.
+- **Spikes**: any uncertain or one-way-door call gets a spike, not a guess:
+
+  ```
+  Question:      <what we are unsure about>
+  Spike:         <smallest thing to build/test> over <timebox>
+  Decision rule: <X> if <signal> / <Y> if <counter-signal>
+  ```
+
+  Reversible cheap calls: just decide and move on.
+
+## Step 3 — Write the decision doc
+
+Only after the calls are made. Default location: `docs/architecture-<slug>.md`
+(or folded into the PRD as an `## Architecture` section when the user
+prefers one document; a tracker page when the user names one and an
+integration exists). Never invent another filename — `final_report.md`,
+`REPORT.md`, and similar are wrong. Shape:
+
+```markdown
+# Architecture — <intent name>
+
+## Problem & goals        (one paragraph, the lens for every decision)
+## Approaches considered  (the 2-3 directions with trade-offs)
+## Recommended approach   (the shape of the solution; brownfield: where it
+                           plugs in and what it reuses)
+## Key decisions          (stack+why, data model shape, boundaries,
+                           other eng-lead calls; skipped areas noted)
+## Missing pieces
+## Spikes & experiments   (each with its decision rule)
+## Open questions         (deliberately deferred, with what settles each)
+```
+
+## Done when
+
+The doc exists at a confirmed location, every section is either filled or
+explicitly marked skipped, every one-way-door call has a spike or a user
+decision, and the user has been offered the next moves without a forced
+pipeline: slice into tickets (`backlog`), slice into a local
+sprint (`cut-it`), spike a flagged risk now, or keep refining here.
+
+## Red flags
+
+- A document produced in one shot with no user calls in between.
+- One foregone conclusion instead of real alternatives.
+- File-by-file edit lists (that is cut-it's altitude).
+- A one-way door decided by vibe instead of a spike.

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.