@iowarp/clio-coder 0.4.6 → 0.4.8

package/library/skills/meta/herdr/SKILL.md

@@ -0,0 +1,133 @@
+---
+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/library/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/library/skills/meta/herdr/evals.md

@@ -0,0 +1,38 @@
+# 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 eval skill` 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/library/skills/meta/herdr/plugin.json

@@ -0,0 +1,23 @@
+{
+	"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+	"name": "herdr",
+	"version": "0.2.0",
+	"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.",
+	"license": "Apache-2.0",
+	"extensions": {
+		"ai.iowarp.clio": {
+			"manifestVersion": 1,
+			"kind": "skill",
+			"resources": {
+				"skills": "."
+			},
+			"components": [
+				{
+					"kind": "skill",
+					"id": "herdr",
+					"path": "SKILL.md"
+				}
+			]
+		}
+	}
+}

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

@@ -0,0 +1,139 @@
+---
+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.1
+license: Apache-2.0
+allowed-tools:
+  - read
+  - grep
+  - write
+  - edit
+  - bash
+clio-coder:
+  registry-id: iowarp/clio-coder
+  source-url: https://github.com/iowarp/clio-coder/tree/main/library/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 eval skill`, 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`. Author with ordinary write/edit tools
+in a draft directory such as `draft-skills/<name>/`, outside active skill and
+installed package roots. In this repository, curated sources live under
+`library/skills/<category>/<name>/`. Validate a draft with
+`clio-coder library validate draft-skills/<name>/SKILL.md`.
+
+For distribution, use the portable envelope in
+`library/_authoring/templates/skill/` and validate the complete package root.
+The operator installs it through the Library into the user or project package
+store (`<configDir>/plugins/` or `.clio-coder/plugins/`). Loose skills under
+`.clio-coder/skills/` and `<configDir>/skills/` are also operator-managed; Clio's
+model tools cannot author directly in those protected roots. Other hosts may
+consume the same `SKILL.md` through their own installation routes.
+
+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 library/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 (library/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/library/skills/meta/skill-craft/evals.md

@@ -0,0 +1,49 @@
+# 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 `draft-skills/log-triage/SKILL.md` outside protected active roots.
+- Supplies a portable package envelope and operator installation guidance when
+  distribution is requested; authoring does not silently activate the skill.
+- 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 library validate draft-skills/log-triage/SKILL.md`.
+
+## 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.
+
+## Instruction correction (2026-09-10)
+
+Version 0.3.1 corrects draft authoring and operator installation paths and admits
+the ordinary write/edit/bash tools the existing author/validate procedure needs.
+Scenarios recorded; no new model eval is claimed.
+
+## 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. 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/library/skills/meta/skill-craft/plugin.json

@@ -0,0 +1,23 @@
+{
+	"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+	"name": "skill-craft",
+	"version": "0.3.1",
+	"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.",
+	"license": "Apache-2.0",
+	"extensions": {
+		"ai.iowarp.clio": {
+			"manifestVersion": 1,
+			"kind": "skill",
+			"resources": {
+				"skills": "."
+			},
+			"components": [
+				{
+					"kind": "skill",
+					"id": "skill-craft",
+					"path": "SKILL.md"
+				}
+			]
+		}
+	}
+}

package/library/skills/planning/archify/SKILL.md

@@ -0,0 +1,196 @@
+---
+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/library/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. This library package contains Clio instructions; the renderer is
+an independently installed upstream Archify v2.16.0 package. Before authoring,
+locate its directory containing `bin/archify.mjs`, `schemas/` and `examples/`.
+If unavailable, ask the operator to prepare that upstream renderer; do not claim
+that installing this instruction package installed it. Below, `<renderer>` is
+that verified directory, and renderer-relative schema/example paths refer to it.
+The renderer needs Node 18 or later; ordinary rendering then needs no network.
+
+## Fast authoring path
+
+1. Choose `architecture`, `workflow`, `sequence`, `dataflow`, or `lifecycle`
+   from the question. When ambiguous, run
+   `node <renderer>/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 <renderer>/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 <renderer>/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 <renderer>/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 <renderer>/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.

package/library/skills/planning/archify/plugin.json

@@ -0,0 +1,23 @@
+{
+	"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+	"name": "archify",
+	"version": "0.1.0",
+	"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.",
+	"license": "MIT",
+	"extensions": {
+		"ai.iowarp.clio": {
+			"manifestVersion": 1,
+			"kind": "skill",
+			"resources": {
+				"skills": "."
+			},
+			"components": [
+				{
+					"kind": "skill",
+					"id": "archify",
+					"path": "SKILL.md"
+				}
+			]
+		}
+	}
+}