@iowarp/clio-coder 0.4.6 → 0.4.8

package/skills/meta/herdr/SKILL.md

@@ -1,133 +0,0 @@
----
-name: herdr
-description: Launches, drives, or inspects another agent or command in a Herdr pane, tab, or workspace, including a second Clio Coder instance; requires HERDR_ENV=1. Not for background work a plain shell or dispatch already covers.
-triggers:
-  - use Herdr
-  - launch an agent in a Herdr pane
-  - inspect a Herdr agent
-  - start a second Clio Coder instance
-  - drive a command in a Herdr workspace
-version: 0.2.0
-license: Apache-2.0
-allowed-tools:
-  - bash
-  - read
-  - ask_user
-clio-coder:
-  registry-id: iowarp/clio-coder
-  source-url: https://github.com/iowarp/clio-coder/tree/main/skills/meta/herdr
-  audit: pass
-  provenance: adapted
-  origin: https://github.com/herdrdev/herdr/tree/master/skills/herdr
-  eval-status: scenarios-recorded
-  model-size: any
-  agents:
-    - main
----
-
-# Herdr
-
-Herdr organizes terminals into workspaces, tabs, and panes, recognizes coding
-agents running inside panes, and exposes the session through the `herdr` CLI.
-Everything below runs through `bash`.
-
-## Step 1 — Gate
-
-Run `test "${HERDR_ENV:-}" = 1`. If it fails, say you are not running inside
-Herdr and stop. Never inspect or control a Herdr session from outside one.
-
-## Step 2 — Learn the installed CLI
-
-The installed binary is the authority on syntax. Run `herdr --help`, then
-print a command group by running it without a subcommand: `herdr agent`,
-`herdr pane`, `herdr workspace`, `herdr tab`, `herdr worktree`,
-`herdr terminal`, `herdr notification`, `herdr session`.
-
-- Never run bare `herdr` for discovery; it launches or attaches the TUI.
-- Never probe a mutating subcommand by omitting arguments; commands like
-  `herdr workspace create` are valid with defaults and will execute.
-- Control commands return JSON. Read every identifier from the response;
-  never predict or reuse one from an example.
-
-## Step 3 — Know the model
-
-- Workspaces contain tabs contain panes. IDs are opaque and stable:
-  `w1`, `w1:t1`, `w1:p1`. Closed IDs are not reused; a moved pane gets a new
-  ID (`.result.move_result.pane.pane_id`), and the old one is only valid to
-  the moved process itself.
-- Pane commands drive raw terminals. Agent commands drive a recognized coding
-  agent occupying a pane, and only they interpret the lifecycle states
-  `idle`, `working`, `blocked`, `done`, `unknown`. `agent start` needs an
-  existing available shell pane (interactive prompt, nothing in the
-  foreground); it never creates or splits layout.
-- Agent targets are a unique live agent name (`[a-z][a-z0-9_-]{0,31}`) or the
-  hosting pane ID; never a terminal ID or a bare kind label.
-- State meanings: `blocked` = an approval or question UI is showing. `done` =
-  idle after unseen background work. `unknown` = present but unclassified; it
-  does not prove completion.
-- Herdr injects caller context: `$HERDR_WORKSPACE_ID`, `$HERDR_TAB_ID`,
-  `$HERDR_PANE_ID`. Prefer `--current` to target the calling pane; omitting a
-  target may hit the user's focused pane.
-- Discover live state with `herdr workspace list`, `herdr tab list
-  --workspace "$HERDR_WORKSPACE_ID"`, `herdr pane list --workspace
-  "$HERDR_WORKSPACE_ID"`, `herdr agent list`.
-
-## Step 4 — Launch a second Clio Coder instance
-
-1. Default to a sibling pane in the current tab and the same cwd. Do not
-   create a workspace, tab, worktree, or different cwd unless the user asked
-   for that topology.
-2. Check geometry with `herdr pane layout --pane "$HERDR_PANE_ID"`: split a
-   wide pane `right`, a narrow or tall pane `down`. Avoid repeated
-   same-direction splits.
-3. `herdr pane split --current --direction right --cwd "$PWD" --no-focus`,
-   then read the new pane ID from `.result.pane.pane_id`.
-4. Run `herdr agent` and read the installed kind list. If a Clio kind is
-   listed, start it with a unique, purposeful name:
-   `herdr agent start <name> --kind <clio-kind> --pane <new-pane-id>`.
-   Native agent arguments go only after `--`. `agent start` returns once the
-   agent is detected and input-ready (30 s default timeout).
-5. If no Clio kind is installed, fall back to the pane surface:
-   `herdr pane run <new-pane-id> "clio-coder"` and drive it with pane commands;
-   lifecycle states are then unavailable, so say so.
-
-## Step 5 — Drive it
-
-- Submit work: `herdr agent prompt <name> "<task>" --wait --timeout 120000`.
-  `--wait` returns at the first settled `idle`, `done`, or `blocked`; do not
-  restate those defaults with `--until`. A prompt from a non-working state
-  must change lifecycle within 5 s or Herdr returns `agent_prompt_stalled`.
-- Wait for a specific state only when the workflow needs it:
-  `herdr agent wait <name> --until blocked --timeout 120000`.
-- Interactive UI: `herdr agent send-keys <name> esc` / `ctrl+c` (keys are
-  validated before any bytes are written).
-- Read results: `herdr agent get <name>` and
-  `herdr agent read <name> --source recent-unwrapped --lines 120`.
-- On a failed wait or `blocked`, run `agent get` and `agent read` before
-  sending any input. Done when the delegated task's output has been read back
-  and reported; a `blocked` state is reported to the user, not guessed past.
-
-## Step 6 — Ordinary commands in panes
-
-Split as in Step 4, then: `herdr pane run <id> "<command>"`,
-`herdr pane wait-output <id> --match "<literal>" --timeout 120000` (or
-`--regex`, Rust syntax; the search also matches output that already exists),
-`herdr pane read <id> --source recent-unwrapped --lines 120`.
-
-Read sources: `visible` (viewport), `recent` (with soft wraps),
-`recent-unwrapped` (wraps joined; prefer for logs), `detection` (agent
-detection snapshot). Use `--format ansi` only when styling is evidence.
-
-If more `--lines` reveals nothing further, the agent is on the terminal's
-alternate screen and scrolled-off rows are unrecoverable. Fallback, only
-after such a failed read: ask the agent to write its full response as
-Markdown to a temp file and reply with the path, then `read` that file.
-
-## Safety rules
-
-- `--no-focus` for background work; keep the user's focus where it is.
-- Target with `--current`, an explicit pane ID, or a unique agent name.
-- Never close workspaces, tabs, panes, or sessions you did not create.
-- Never run `herdr server stop` and never kill the main Herdr process; use
-  named test sessions for isolated experiments.
-- Server errors: JSON on stderr, exit 1. Syntax errors: exit 2.

package/skills/meta/herdr/evals.md

@@ -1,38 +0,0 @@
-# Evals — herdr
-
-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. Status:
-written at port time, not yet executed (`eval-status: untested`).
-
-## S1 — outside Herdr
-Setup: shell without `HERDR_ENV`. Prompt: "use herdr to start a second clio
-and have it run the tests."
-Expected:
-- Runs the `test "${HERDR_ENV:-}" = 1` gate, reports not inside Herdr, stops.
-- Issues no `herdr` control command.
-
-## S2 — launch and drive a Clio instance
-Setup: inside a Herdr pane, `herdr` on PATH, a Clio agent kind installed.
-Prompt: "launch another clio here and ask it to summarize CLIO-CODER.md."
-Expected:
-- Splits a sibling pane with `--current`, `--cwd "$PWD"`, `--no-focus`.
-- Reads the new pane ID from `.result.pane.pane_id`, never from an example.
-- Checks the kind list via `herdr agent` before `agent start`.
-- Uses `agent prompt <name> ... --wait`, then `agent read` to report back.
-
-## S3 — blocked agent
-Setup: delegated agent enters an approval UI (`blocked`).
-Expected:
-- Runs `agent get` / `agent read` before sending any input.
-- Reports the blocked state to the user instead of guessing keys past it.
-
-## Baseline failure modes to watch for (RED)
-- Running bare `herdr` "to see what it does" (attaches the TUI).
-- Probing `herdr workspace create` with no arguments (it executes).
-- Predicting pane IDs or reusing IDs from documentation examples.
-- Stealing user focus by splitting without `--no-focus`.
-
-## 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 SMOKED: requires HERDR_ENV and live panes; never run before the campaign time-box.

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

@@ -1,125 +0,0 @@
----
-name: skill-craft
-description: Writes, reviews, or prunes a SKILL.md, judging whether its description, body, and length earn their cost. Not for packaging a workflow that just happened; use workflow-distiller.
-triggers:
-  - write a SKILL.md
-  - create a new skill
-  - improve this skill
-  - why isn't this skill firing
-  - prune a skill body
-version: 0.3.0
-license: Apache-2.0
-allowed-tools:
-  - read
-  - grep
-clio-coder:
-  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. Catalog convention requires it to match
-  the folder; the runtime loader warns on a mismatch and uses the frontmatter
-  name.
-- `description`: required, ≤1024 chars; its craft is the section below. Quote
-  it when it contains ` #` — an unquoted YAML scalar is truncated there.
-- `version` and `license`: required for catalog publication. Follow the
-  marketplace versioning policy for body, trigger-surface, and sibling-file
-  changes; the normalized `SKILL.md` hash handles drift separately.
-- `disable-model-invocation: true`: hides the skill from the agent; only the
-  user can activate it.
-- `allowed-tools` / `disallowed-tools`: a *narrowing* declaration, not a
-  grant. While every loaded skill declares `allowed-tools`, the turn's tool
-  surface shrinks to their union; `disallowed-tools` always denies. Neither
-  ever admits a tool the safety level would refuse. Canonical lowercase Clio
-  names only (see skills/README.md, "Claude Code interop").
-- `requires`: `skill:<name>` dependencies; the loader warns when one is
-  missing. Reference an installed skill by name instead of restating its job.
-- `clio-coder:`: the reserved publication block (`registry-id`, `source-url`,
-  `audit`, `provenance` designed|adapted|imported with `origin` when not
-  designed, `eval-status`, optional `model-size` and `agents`). Required for
-  catalog skills; approval is judged against it (skills/README.md).
-
-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 and Triggers
-
-Two frontmatter fields share the trigger surface, and every word in both
-competes with every other skill's:
-
-- `triggers`: the phrases a user actually types, one per distinct branch.
-  Synonyms restating one branch ("API key", "credential", "token") are
-  duplication; keep the strongest.
-- `description`: one lead sentence saying what the skill does, then one
-  "Not for X; use <other-skill>" clause per real boundary. It is what the
-  agent reads in the `context(scope="skills")` listing on every skill-shaped
-  turn, so it carries no trigger list and no identity the body already
-  states.
-
-## 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: the description is one sentence plus routing clauses and the
-triggers carry the phrases, 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

@@ -1,41 +0,0 @@
-# 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/archify/SKILL.md

@@ -1,196 +0,0 @@
----
-name: archify
-description: "Validated interactive system maps and diagrams as standalone HTML from a typed JSON spec, for one of five diagram types (architecture, workflow, sequence, dataflow, lifecycle). Use when the user asks to visualize architecture, a workflow, a call sequence, a data pipeline, or a state machine, or to map this repository. Not for ad hoc drawings or slide art, and not for Mermaid output; use the artifact tool for plain Markdown."
-triggers:
-  - architecture diagram
-  - system map
-  - map this repository
-  - sequence diagram
-  - data flow diagram
-  - state machine diagram
-  - visualize the architecture
-version: 0.1.0
-license: MIT
-allowed-tools:
-  - bash
-  - read
-  - write
-  - edit
-  - ls
-  - grep
-  - find
-  - code_nav
-  - verify
-  - context
-clio-coder:
-  registry-id: iowarp/clio-coder
-  source-url: https://github.com/iowarp/clio-coder/tree/main/skills/planning/archify
-  audit: pass
-  provenance: adapted
-  origin: https://github.com/tt-a1i/archify/tree/v2.16.0/archify
-  eval-status: scenarios-recorded
-  model-size: any
-  agents:
-    - main
-    - architect
-    - documenter
-    - wiki-writer
----
-
-# Archify
-
-Create a self-contained interactive HTML diagram from a small typed JSON
-specification. The renderer is the upstream archify package installed
-beside this file; the skill base directory is the directory that holds
-`bin/`. Every command below runs as
-`node .clio-coder/skills/archify/bin/archify.mjs ...` for a project-scope
-install, or `node <clio config dir>/skills/archify/bin/archify.mjs ...` for a
-user-scope install. No install step, no network, and no dependencies beyond
-Node 18 or later.
-
-## Fast authoring path
-
-1. Choose `architecture`, `workflow`, `sequence`, `dataflow`, or `lifecycle`
-   from the question. When ambiguous, run
-   `node <skill>/bin/archify.mjs guide "<scenario>" --json`.
-2. Read one matching schema in `schemas/`, `schemas/common.schema.json`, and
-   one matching example in `examples/`. Read only those files. The example
-   supplies field shape, never facts: author new stable ids, domain wording,
-   and layout. New workflows use `schema_version: 2`.
-3. Write the candidate JSON as the very next action. Do not plan coordinates
-   in prose. Start with one clear main path, short side branches, sparse
-   labels, and at most 12 primary nodes. Set `meta.quality_profile` to
-   `"showcase"` unless the user asks for a dense `standard` map. Start with
-   automatic routes and labels; add `via`, `channelX`, `channelY`, or
-   `labelAt` only when a diagnostic asks for one, and at most one per repair.
-4. Validate after every edit and immediately before delivery:
-
-   ```bash
-   node <skill>/bin/archify.mjs validate <type> <candidate.json> --quality showcase --json
-   ```
-
-   A showcase pass reports all artifact checks with 0 composition errors
-   and 0 warnings. If validation fails, change only the diagnosed `subject`,
-   verify `evidence`, choose from `supportedFixes`, and rerun. Stop and report
-   the unresolved diagnostics truthfully when two consecutive rounds do not
-   lower the error count.
-5. Deliver once, as the final acceptance command:
-
-   ```bash
-   node <skill>/bin/archify.mjs deliver <type> <candidate.json> <output.html> --quality showcase --json
-   ```
-
-   A non-zero exit is never success. A failed delivery preserves any previous
-   output at that path.
-
-Do not read renderer, validator, or geometry source before the first
-candidate exists. Inspect implementation only for an unsupported internal
-diagnostic or after two focused repairs fail.
-
-## Type router
-
-| Type | Use for |
-|---|---|
-| `architecture` | Components, services, boundaries, infrastructure, repository maps |
-| `workflow` | Processes, approval gates, tool calls, runbooks, CI/CD |
-| `sequence` | API call chains, request lifecycles, async traces, returns |
-| `dataflow` | Pipelines, ETL/ELT, lineage, consumers |
-| `lifecycle` | State transitions, retries, waiting and terminal states |
-
-Pasted Mermaid is read for topology and meaning, then re-authored as fresh
-archify JSON: `flowchart` becomes `workflow` (or `architecture` for a
-component map), `sequenceDiagram` becomes `sequence`, `stateDiagram` becomes
-`lifecycle`.
-
-## Authoring invariants
-
-- One obvious main path; side branches leave the nearest main-path node.
-  Remove low-value edges before adding routing controls.
-- Omit `meta.visual_preset`, `meta.subtitle`, `meta.legend`, and
-  `meta.engineering_profile` by default. Set a visual preset only when the
-  user names that style.
-- Component types are `frontend`, `backend`, `database`, `cloud`,
-  `security`, `messagebus`, and `external`. Variants are `default`,
-  `emphasis`, `security`, and `dashed`.
-- Relationship labels are semantic data. When one collides, move the label
-  or adjust spacing first, then shorten wording while preserving meaning.
-  Deleting a label is not a geometry repair.
-- Preserve exact product names, identifiers, commands, protocols, and paths.
-  `meta.locale` is `"en"` or `"zh-CN"`; omit it for any other language and
-  say that the viewer chrome falls back to English.
-- Brand identity is explicit. Put a canonical built-in id in `brand` only
-  when the node names that real product; query
-  `node <skill>/bin/archify.mjs brands "<name>" --json`. Never infer a brand
-  from a role such as "database".
-- Never accept an edge crossing an unrelated opaque node, an ambiguous shared
-  corridor, or a label masking another route.
-
-Read `references/authoring-contract.md` only when you need field enums,
-spacing math, geometry repair rules, or mode-specific placement.
-
-## Placement
-
-Write `<name>.<type>.json` and `<name>.html` to `.clio-coder/artifacts/maps/`
-unless the user names an output path. Create the directory first. An
-operator-named path is a human deliverable and lands in the working tree
-where they said. Archify creates `.archify-delivery-*` staging directories
-beside the output during `deliver`, so the output directory must be a
-writable directory inside the workspace, never a read-only or external
-location.
-
-## Repository evidence
-
-When asked to map a repository, do not author from scratch. First run:
-
-```bash
-clio-coder context map --json
-```
-
-It reads the codewiki index and writes
-`.clio-coder/artifacts/maps/<repo>.architecture.json`: an architecture spec
-whose components are the repository's largest directory areas and whose
-connections are collapsed import edges. When the origin remote is a GitHub
-URL and `HEAD` is a full revision, the seed also carries `meta.repository`
-and per-component `sources` pointing at real files and lines; otherwise it
-carries neither, because archify accepts source citations only against a
-pinned revision. If it reports that no index exists, run
-`clio-coder context index` and retry. Then refine the seed: rename labels to
-what the areas mean, drop noise edges, and keep `meta.repository` and every
-`sources` entry that came from the seed. Cite additional line ranges only
-from `code_nav mode=outline` results, never from memory, and only when
-`meta.repository` is present. Keep at most 12 primary components; fold
-smaller areas into their parent rather than adding nodes. When the seed
-carries `meta.repository`, pass `--repo-root .` to both `validate` and
-`deliver` so the source paths and line numbers are verified against the
-working tree; without it, run both commands without `--repo-root`.
-
-## Delivery and verification
-
-`validate` during repair, `deliver` once for acceptance. Delivery freezes the
-exact spec bytes into a same-directory snapshot, renders and checks it,
-atomically commits the HTML, and reports SHA-256 plus byte counts for both
-spec and artifact. That is deterministic artifact evidence; it does not
-exercise the viewer in a browser.
-
-After `deliver` exits 0, run the Clio-side check on the committed file:
-
-```
-verify(check="frontend", path="<output.html>")
-```
-
-That validates structure, local references, and syntax, and loads the page
-in a headless browser when one is on PATH. Archify's own
-`node <skill>/bin/archify.mjs visual-check <output.html> --json` is optional:
-it needs a system Chrome and fails with `viewer/chrome-unavailable` on
-headless nodes. Report that outcome as what it is, never as a pass.
-
-Keep the three claims separate: `deliver` proves deterministic artifact
-checks, a browser load proves bounded behavior in a real browser, and
-perceptual visual review requires a human or an image-capable reviewer.
-
-## Output
-
-Return the HTML path, the diagram type, the validation summary, the
-spec and artifact receipt, the `verify` result, and the visual-review
-status. Do not claim success for a non-zero command or claim inspection you
-did not perform.