@iowarp/clio-coder 0.3.0

package/skills/skill-marketplace.json

@@ -0,0 +1,261 @@
+{
+	"generatedBy": "npm run skills:pin",
+	"skills": [
+		{
+			"name": "ast-grep",
+			"description": "Use when a code search needs structure, not text — \"find all async functions without error handling\", \"find calls with this argument shape\", \"find X inside Y\" — or when grep returns too much noise to filter. Writes and tests ast-grep rules, then scans the codebase. Search only; never rewrites code. Not for plain string or filename lookups; use grep or find.",
+			"sourceUrl": "https://github.com/iowarp/clio-coder/tree/main/skills/coding/ast-grep",
+			"version": "0.1.0",
+			"audit": "pass",
+			"category": "coding"
+		},
+		{
+			"name": "coding-standards",
+			"description": "Use when writing or refactoring TypeScript and the project has not pinned its own conflicting standards — new modules, error-handling design, schema parsing, module boundaries — or when another skill needs a TypeScript standards reference. Correct-by-construction rules: errors as values, parse don't validate, illegal states unrepresentable, deep modules, functional core / imperative shell.",
+			"sourceUrl": "https://github.com/iowarp/clio-coder/tree/main/skills/coding/coding-standards",
+			"version": "0.1.0",
+			"audit": "pass",
+			"category": "coding"
+		},
+		{
+			"name": "prototype",
+			"description": "Use when a design question should be answered with throwaway code — \"does this state model feel right\", \"sanity-check this logic\", \"what should this UI look like\", \"mock something up\". Builds a clearly-marked, trivially-runnable, no-persistence prototype, then captures the verdict and discards the code. Not for pre-registered performance experiments; use experiment-protocol. Not for production implementation.",
+			"sourceUrl": "https://github.com/iowarp/clio-coder/tree/main/skills/coding/prototype",
+			"version": "0.2.0",
+			"audit": "pass",
+			"category": "coding"
+		},
+		{
+			"name": "tdd",
+			"description": "Use when the user wants to build a feature or fix a bug test-first, says \"TDD\", \"red-green\", or \"write the test first\", or when a change to tricky logic needs its behavior pinned before implementation. Runs the red → green loop at pre-agreed public seams, one vertical slice at a time. Not for designing benchmark criteria; use experiment-protocol.",
+			"sourceUrl": "https://github.com/iowarp/clio-coder/tree/main/skills/coding/tdd",
+			"version": "0.2.0",
+			"audit": "pass",
+			"category": "coding"
+		},
+		{
+			"name": "context-handoff",
+			"description": "Use when a session is winding down and work will continue in a new session or another agent, when context is about to be compacted or lost, or when the user asks for a handoff, brief, summary, or \"notes for the next session.\" Produces a durable, redacted, reference-not-copy handoff document the next session can pick up from.",
+			"sourceUrl": "https://github.com/iowarp/clio-coder/tree/main/skills/context/context-handoff",
+			"version": "0.3.1",
+			"audit": "pass",
+			"category": "context"
+		},
+		{
+			"name": "context-prime",
+			"description": "Use when a coding session begins, when resuming work after a break, or when you land in an unfamiliar or in-progress repository and need to orient before acting. Loads the last handoff, git state, the project constitution, and active-work signals so a fresh agent reconstructs intent instead of guessing. Triggers on \"prime\", \"catch me up\", \"where were we\", \"get up to speed\", or the first substantive request in a new session.",
+			"sourceUrl": "https://github.com/iowarp/clio-coder/tree/main/skills/context/context-prime",
+			"version": "0.2.2",
+			"audit": "pass",
+			"category": "context"
+		},
+		{
+			"name": "commit-crafting",
+			"description": "Use when the user asks to commit the current work — \"commit this\", \"make a commit\", \"commit what we did\" — and the changes are complete. Stages reviewed files, writes one atomic conventional-tagged commit, and reports what changed. Local commit only; never pushes. Not for opening a PR; use create-pr.",
+			"sourceUrl": "https://github.com/iowarp/clio-coder/tree/main/skills/git/commit-crafting",
+			"version": "0.2.0",
+			"audit": "pass",
+			"category": "git"
+		},
+		{
+			"name": "create-pr",
+			"description": "Use when the user asks to push the current branch and open a pull request — \"open a PR\", \"create the pull request\", \"ship this for review\". Detects the base branch, gates on clean committed state, pushes, opens the PR with a structured body, and returns the URL. Requires the gh CLI and explicit user intent; never fires as an implied next step after a commit.",
+			"sourceUrl": "https://github.com/iowarp/clio-coder/tree/main/skills/git/create-pr",
+			"version": "0.2.0",
+			"audit": "pass",
+			"category": "git"
+		},
+		{
+			"name": "investigate-issue",
+			"description": "Use when a GitHub issue needs diagnosis before any fix — \"investigate issue 123\", \"root-cause this bug\", \"what's behind this issue\". Fetches the issue, explores in parallel via dispatch, builds an evidence-cited why-chain to the root cause, writes a reviewable RCA document, and posts a summary comment. Diagnosis only; the fix is a separate task. Not for failures without an issue; use scientific-debugging.",
+			"sourceUrl": "https://github.com/iowarp/clio-coder/tree/main/skills/git/investigate-issue",
+			"version": "0.2.0",
+			"audit": "pass",
+			"category": "git"
+		},
+		{
+			"name": "resolve-merge-conflicts",
+			"description": "Use when a git merge, rebase, or cherry-pick is stopped on conflicts and they need resolving — \"fix these conflicts\", \"finish the merge\", conflict markers in files. Resolves by reconstructing both sides' intent from history, preserves both where possible, validates with the project's own checks, and completes the operation. Not for planning an integration of many branches; use worktree-merge.",
+			"sourceUrl": "https://github.com/iowarp/clio-coder/tree/main/skills/git/resolve-merge-conflicts",
+			"version": "0.2.0",
+			"audit": "pass",
+			"category": "git"
+		},
+		{
+			"name": "review-changes",
+			"description": "Use before committing, when the user asks to review the uncommitted work — \"review my changes\", \"check this before I commit\", \"pre-commit review\". Reads changed files in full against the project's documented standards, hunts real bugs and security issues, verifies findings before reporting them, and writes a severity-ranked report. Not for reviewing a branch or PR range; use the repo's review tooling for that.",
+			"sourceUrl": "https://github.com/iowarp/clio-coder/tree/main/skills/git/review-changes",
+			"version": "0.2.0",
+			"audit": "pass",
+			"category": "git"
+		},
+		{
+			"name": "worktree-create",
+			"description": "Use when the user asks to set up one or more git worktrees for parallel work — \"create a worktree\", \"set up worktrees for these branches\", \"spin up parallel branches\". Detects the project's install, config, and health-check needs once, then stands up each worktree on its own branch with gitignored config copied in, dependencies installed, and a verified health check. Not for merging finished worktrees; use worktree-merge.",
+			"sourceUrl": "https://github.com/iowarp/clio-coder/tree/main/skills/git/worktree-create",
+			"version": "0.2.0",
+			"audit": "pass",
+			"category": "git"
+		},
+		{
+			"name": "worktree-merge",
+			"description": "Use when parallel worktree branches are finished and the user asks to integrate them — \"merge my worktrees\", \"integrate these branches\". Merges any number of branches through one throwaway integration branch, testing after each merge, running the full detected suite before the main line moves, with exact rollback on any failure. Not for creating worktrees; use worktree-create.",
+			"sourceUrl": "https://github.com/iowarp/clio-coder/tree/main/skills/git/worktree-merge",
+			"version": "0.2.0",
+			"audit": "pass",
+			"category": "git"
+		},
+		{
+			"name": "clio-dev",
+			"description": "Use when modifying Clio Coder's own source in this repository, evolving its harness (TUI, skills, agents, tools, prompts, domains), or deciding whether a change stays local versus becomes a contribution. Governs self-development — what Clio may change freely, what requires explicit user intent, and how to make a change without breaking the architecture.",
+			"sourceUrl": "https://github.com/iowarp/clio-coder/tree/main/skills/meta/clio-dev",
+			"version": "0.2.0",
+			"audit": "pass",
+			"category": "meta"
+		},
+		{
+			"name": "clio-test",
+			"description": "Use when writing or modifying Clio Coder's own source under src/, or verifying a change end-to-end against the real test harness. Covers the three real layers (contracts / smoke / boundaries), choosing which to run for a given change, the mock-provider and ACP-over-stdio harness, and the hot-reload dev loop for picking up latest code. Activate on any src/ edit, before declaring a change verified, or when asked whether Clio still works.",
+			"sourceUrl": "https://github.com/iowarp/clio-coder/tree/main/skills/meta/clio-test",
+			"version": "0.1.3",
+			"audit": "pass",
+			"category": "meta"
+		},
+		{
+			"name": "credentials",
+			"description": "Use before running any tool or script that needs an API key, token, or other credential, when a command fails with an auth error, when the user must supply a new secret, or when a secret may have leaked into output. Covers facility surfaces such as kerberos tickets, globus and scheduler tokens, ssh agents, and netrc. Triggers on \"API key\", \"credential\", \"token\", \"auth error\", \"permission denied\", \"add a secret\", \"leaked\". Not for provider target configuration; use clio-coder auth and target settings.",
+			"sourceUrl": "https://github.com/iowarp/clio-coder/tree/main/skills/meta/credentials",
+			"version": "0.1.2",
+			"audit": "pass",
+			"category": "meta"
+		},
+		{
+			"name": "find-skills",
+			"description": "Use when the user asks \"is there a skill for X\", \"find a skill\", \"install a skill\", \"add a skill\", asks whether a capability exists as an installable skill, or wants to extend the agent with functionality that might already be published. Searches with `clio-coder skills search`, browses the ecosystem read-only, and installs only through `clio-coder skills install`. Not for authoring a new skill; use skill-craft.",
+			"sourceUrl": "https://github.com/iowarp/clio-coder/tree/main/skills/meta/find-skills",
+			"version": "0.1.1",
+			"audit": "pass",
+			"category": "meta"
+		},
+		{
+			"name": "herdr",
+			"description": "Use when the user explicitly mentions Herdr or asks to launch, drive, or inspect another agent or command in a Herdr pane, tab, or workspace — including starting a second Clio Coder instance and delegating work to it. Requires HERDR_ENV=1. Not for background work a plain shell or dispatch already covers; do not activate merely because a task could benefit from parallelism.",
+			"sourceUrl": "https://github.com/iowarp/clio-coder/tree/main/skills/meta/herdr",
+			"version": "0.1.0",
+			"audit": "pass",
+			"category": "meta"
+		},
+		{
+			"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\".",
+			"sourceUrl": "https://github.com/iowarp/clio-coder/tree/main/skills/meta/skill-craft",
+			"version": "0.1.1",
+			"audit": "pass",
+			"category": "meta"
+		},
+		{
+			"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.",
+			"sourceUrl": "https://github.com/iowarp/clio-coder/tree/main/skills/planning/architecture",
+			"version": "0.2.0",
+			"audit": "pass",
+			"category": "planning"
+		},
+		{
+			"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.",
+			"sourceUrl": "https://github.com/iowarp/clio-coder/tree/main/skills/planning/backlog",
+			"version": "0.2.0",
+			"audit": "pass",
+			"category": "planning"
+		},
+		{
+			"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.",
+			"sourceUrl": "https://github.com/iowarp/clio-coder/tree/main/skills/planning/prd",
+			"version": "0.2.1",
+			"audit": "pass",
+			"category": "planning"
+		},
+		{
+			"name": "product-intent",
+			"description": "Use at the start of a greenfield product effort, when the user wants a problem-first product document — \"why are we building this\", \"write the product thesis\", \"PRD for this idea\". Interviews for the problem, evidence, and a falsifiable hypothesis; writes an intent-only PRD with zero engineering decisions. Not for engineering decisions; use architecture. Not for turning a locked idea into milestone build prompts; use prd.",
+			"sourceUrl": "https://github.com/iowarp/clio-coder/tree/main/skills/planning/product-intent",
+			"version": "0.2.0",
+			"audit": "pass",
+			"category": "planning"
+		},
+		{
+			"name": "tech-spec",
+			"description": "Write a typed call-stack architecture handoff — code-shaped contracts plus execution flows, implementation-ready for another engineer. User-invoked only.",
+			"sourceUrl": "https://github.com/iowarp/clio-coder/tree/main/skills/planning/tech-spec",
+			"version": "0.1.0",
+			"audit": "pass",
+			"category": "planning"
+		},
+		{
+			"name": "arxiv-literature",
+			"description": "Use when the user asks to search arXiv, summarize an arXiv paper, compare papers, find recent research, or build a compact literature survey. Prefer the Researcher shadow agent for noisy multi-paper retrieval; return only citation-ready, source-linked paper cards.",
+			"sourceUrl": "https://github.com/iowarp/clio-coder/tree/main/skills/research/arxiv-literature",
+			"version": "0.3.0",
+			"audit": "pass",
+			"category": "research"
+		},
+		{
+			"name": "experiment-protocol",
+			"description": "Use when running a performance study, numerical comparison, parameter sweep, kernel or solver benchmark, or any change justified by \"faster\" or \"more accurate\", and success criteria should be locked before results exist. Pre-registers thresholds, tolerances, environment pins, and verdict conditions into the repository validation contract before any measurement. Triggers on \"benchmark\", \"compare implementations\", \"optimize\", \"tolerance\", \"reproduce results\", \"parameter sweep\". Not for diagnosing a stalled bug; use scientific-debugging.",
+			"sourceUrl": "https://github.com/iowarp/clio-coder/tree/main/skills/research/experiment-protocol",
+			"version": "0.1.2",
+			"audit": "pass",
+			"category": "research"
+		},
+		{
+			"name": "scientific-debugging",
+			"description": "Use when debugging has stalled after the first obvious fix, when a failure spans multiple systems, when someone is about to try random changes, or when a scientific or HPC code produces wrong numbers, NaNs, nondeterministic results, or an unexplained performance regression. Forces falsifiable hypotheses across distinct fault classes with evidence-cited verdicts before any fix. Triggers on \"why is this failing\", \"wrong results\", \"flaky\", \"nondeterministic\", \"diagnose\", \"root cause\". Not for designing benchmarks or pre-registered experiments; use experiment-protocol.",
+			"sourceUrl": "https://github.com/iowarp/clio-coder/tree/main/skills/research/scientific-debugging",
+			"version": "0.1.2",
+			"audit": "pass",
+			"category": "research"
+		},
+		{
+			"name": "scientific-modernization",
+			"description": "Use when modernizing, porting, rewriting, packaging, accelerating, or replacing established scientific software, especially across languages, build systems, CPU/GPU backends, or maintained forks. Establishes an external scientific oracle, preserves compatibility, delivers in independently validated stages, and settles upstream ownership and long-term stewardship before calling the work complete. Triggers on \"modernize this scientific code\", \"rewrite in Rust\", \"port to GPU\", \"replace this research tool\", \"migrate the build\", \"maintained fork\", and \"scientific parity\". Not for an isolated benchmark; use experiment-protocol. Not for diagnosing wrong results; use scientific-debugging.",
+			"sourceUrl": "https://github.com/iowarp/clio-coder/tree/main/skills/research/scientific-modernization",
+			"version": "0.2.0",
+			"audit": "pass",
+			"category": "research"
+		},
+		{
+			"name": "cut-it",
+			"description": "Use when a plan, PRD, or milestone must become an executable sprint — dependency-ordered vertical slices sized for one focused agent run each, with done-when verification per slice. Never fabricates a plan; if none exists or it is too vague to slice, says so and recommends an interview first. Triggers on \"cut it\", \"slice this plan\", \"make this executable\", \"turn this into a sprint\".",
+			"sourceUrl": "https://github.com/iowarp/clio-coder/tree/main/skills/workflow/cut-it",
+			"version": "0.2.1",
+			"audit": "pass",
+			"category": "workflow"
+		},
+		{
+			"name": "design-council",
+			"description": "Use when a design decision has real tradeoffs and needs several expert perspectives that challenge each other before code is written, such as architecture choices, API shapes, storage formats, parallelization strategies, or dependency decisions. Quick mode runs a single round for a fast perspective check. Triggers on \"council\", \"debate this\", \"multiple perspectives\", \"weigh the options\", \"what would experts say\". Not for a one-question-at-a-time interrogation of a plan; use grill-me. Not for splitting implementation work across workers; use dispatch directly.",
+			"sourceUrl": "https://github.com/iowarp/clio-coder/tree/main/skills/workflow/design-council",
+			"version": "0.3.0",
+			"audit": "pass",
+			"category": "workflow"
+		},
+		{
+			"name": "grill-me",
+			"description": "Use when the user wants a plan, design, or idea stress-tested through a phased one-question-at-a-time interview before any code is written, or when intent is too ambiguous to plan from. Scans available context first, reviews known facts, fills missing decisions, respects stop signals, and ends with a compact decision log. Triggers on \"grill me\", \"interview me\", \"stress-test this plan\", \"poke holes in this\".",
+			"sourceUrl": "https://github.com/iowarp/clio-coder/tree/main/skills/workflow/grill-me",
+			"version": "0.3.2",
+			"audit": "pass",
+			"category": "workflow"
+		},
+		{
+			"name": "workflow-distiller",
+			"description": "Use when a workflow that just happened should become reusable, when the user says \"make this a skill\", \"package what we just did\", \"turn this into a workflow\", or when the same multi-step process has been repeated across sessions. Reconstructs the workflow from the session record, interviews, checks overlap with installed skills, gates on approval, then writes the SKILL.md following skill-craft. Not for authoring a skill from scratch with no prior workflow; write the SKILL.md directly following skill-craft. Not for distilling into an agent recipe; propose that as a follow-up when the workflow is dispatch-shaped.",
+			"sourceUrl": "https://github.com/iowarp/clio-coder/tree/main/skills/workflow/workflow-distiller",
+			"version": "0.2.1",
+			"audit": "pass",
+			"category": "workflow"
+		}
+	]
+}

package/skills/workflow/cut-it/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: cut-it
+description: Use when a plan, PRD, or milestone must become an executable sprint — dependency-ordered vertical slices sized for one focused agent run each, with done-when verification per slice. Never fabricates a plan; if none exists or it is too vague to slice, says so and recommends an interview first. Triggers on "cut it", "slice this plan", "make this executable", "turn this into a sprint".
+version: 0.2.1
+license: Apache-2.0
+allowed-tools:
+  - read
+  - grep
+  - ls
+  - find
+  - git
+  - context
+  - code_nav
+  - write
+  - artifact
+  - ask_user
+clio:
+  registry-id: iowarp/clio-coder
+  source-url: https://github.com/iowarp/clio-coder/tree/main/skills/workflow/cut-it
+  audit: pass
+  provenance: adapted
+  origin: https://github.com/TheOrcDev/skills
+  eval-status: smoke-checked
+  model-size: any
+---
+
+# Cut It
+
+Transform an existing plan into ordered execution slices that a coding agent
+can run one at a time, leaving the build green after every slice. The output
+is a `SPRINT.md` another agent can execute cold — no conversation context
+required.
+
+## Step 1 — Locate the plan
+
+In priority order: a file the user names, a plan in the conversation,
+`PLAN.md` / `PRD.md` / `milestones/*/prompt.md` in the repo. **Never fabricate
+the plan.** If none exists, or what exists is too vague to slice honestly,
+stop and say so — recommend `grill-me` to resolve intent first. Artificial
+slicing of a vague plan hides gaps; flagging them is the deliverable.
+
+## Step 2 — Apply the cutting rules
+
+- **Vertical slices.** Each slice delivers end-to-end behavior, however thin.
+  No "all the types first, all the wiring later" horizontal layers.
+- **Dependency order.** A slice may depend only on earlier slices. State the
+  dependency explicitly.
+- **One agent run each.** Sized so a focused agent completes it in a single
+  run: small enough to hold in context, large enough to be meaningful.
+- **Green after every slice.** Build, lint, and existing tests pass at every
+  cut point. A slice that leaves the tree broken is two slices cut wrong.
+- **Self-contained.** Real file paths, real commands, concrete steps. A reader
+  with zero conversation context can execute it.
+
+## Step 3 — Write the artifact
+
+Default output is `SPRINT.md` at the repo root (honor a caller-supplied path).
+Format:
+
+```markdown
+# Sprint: <name>
+
+## Battle order
+1. <slice 1 title>
+2. <slice 2 title>  (depends on: 1)
+...
+
+## Slice 1 — <title>
+**Goal**: <the behavior this delivers>
+**Depends on**: <slice numbers or "nothing">
+**Files**: <paths touched>
+**Steps**:
+1. <concrete step with real paths/commands>
+**Done when**: <observable, testable criteria — the verification anchor>
+**Out of scope**: <what this slice deliberately does not do>
+```
+
+"Done when" is the contract, not decoration. If you cannot write a testable
+done-when for a slice, the slice is not ready to cut — go back to the plan.
+
+## Red flags (you are doing it wrong)
+
+- A slice whose steps say "and related changes" or "etc."
+- Done-when criteria that restate the goal instead of naming a check.
+- A slice that only compiles when a later slice lands.
+- Slicing a plan you had to invent on the spot.

package/skills/workflow/cut-it/evals.md

@@ -0,0 +1,42 @@
+# Evals — cut-it
+
+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 — slice a real plan
+Setup: cut it.
+
+Fixture:
+```bash
+mkdir -p src
+printf 'function listTodos() {\n  return [];\n}\n\nmodule.exports = { listTodos };\n' > src/todos.js
+printf '# PLAN\n\nGoal: minimal todo CLI on top of src/todos.js.\n\n## Feature 1 - add todos\nPersist new todos to todos.json via src/todos.js; expose "add <text>" in src/cli.js.\nVerify: node src/cli.js add buy-milk then node src/cli.js list shows it.\n\n## Feature 2 - complete todos\nMark a todo done by index in src/todos.js; expose "done <n>" in src/cli.js.\nVerify: adding then completing shows [x] in list output.\n\n## Feature 3 - filter view\nList supports "list --open" and "list --done" flags in src/cli.js.\nVerify: completed items appear only under --done.\n' > PLAN.md
+```
+
+Expected:
+- Produces `SPRINT.md` with a battle order and numbered slices.
+- Every slice has goal, depends-on, files, concrete steps, done-when, out-of-scope.
+- Slices are vertical (each delivers behavior), not layered by file type.
+- Done-when criteria name observable checks (a command, a test, a visible output).
+
+## S2 — no plan exists
+Setup: empty-ish repo, no PLAN.md/PRD.md. Prompt: "slice this into a sprint."
+Expected:
+- Refuses to fabricate; states no plan was found.
+- Recommends resolving intent first (grill-me or a written plan).
+
+## S3 — vague plan
+Setup: PLAN.md says "improve performance and clean up the code."
+Expected:
+- Flags the plan as too vague to slice honestly; lists what is missing.
+- Does not emit artificial slices to look productive.
+
+## Baseline failure modes to watch for (RED)
+- Horizontal slices ("create all interfaces", "wire everything up").
+- "Done when: the feature works" non-criteria.
+- Inventing scope the plan never mentioned.
+
+## 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. Sliced the seeded PLAN.md; judge 4/4.

package/src/domains/agents/builtins/architect.md

@@ -0,0 +1,33 @@
+---
+version: 1
+name: Architect
+description: Designs coding changes across boundaries, contracts, migrations, and validation gates; slices an existing plan into an executable dependency-ordered sprint via its bound cut-it skill.
+tools:
+  required: [artifact, context]
+  optional: [read, grep, find, ls, code_nav, git]
+skills: [cut-it]
+audience: base
+category: plan
+capabilityClass: artifact-write
+latencyClass: deep
+projectContextTier: bounded
+budget: {toolCalls: 32, readReserve: 5, synthesis: true}
+resultContract: {kind: architect-plan, path: PLAN.md}
+tags: [architecture, boundaries, migration]
+---
+
+# Architect
+
+You are Architect, the base design agent for coding work.
+Start by restating the requested change, the affected modules, and the decision the operator needs.
+Read contracts, manifests, call sites, and recent diffs before recommending a shape.
+Map ownership boundaries first: domains, engine, worker, tools, prompts, tests, docs, and runtime receipts.
+Before broad exploration, check `code_nav mode=wiki` and read `.clio-coder/wiki/quickstart.md` when a wiki exists.
+Use codewiki tools only when the assignment is navigation-heavy. Otherwise rely on the provided context and targeted reads.
+Prefer extending existing contracts over adding abstractions unless the new surface removes real complexity.
+Separate the required implementation slice from optional follow-up work.
+Call out prompt, safety, persistence, worker-runtime, and test consequences when they apply.
+Use `artifact` (kind="plan") only when the result should become a reviewable `PLAN.md`.
+When the operator wants an executable sprint rather than a design narrative, load `cut-it` via `context` (scope="skills") and emit dependency-ordered slices with done-when criteria.
+Do not edit source files, tests, configs, or generated artifacts from this role.
+Write the plan with `artifact` (kind="plan") at `PLAN.md`. The integrity-recorded `PLAN.md` artifact is this role's result contract; your final response carries no schema, so close with a short pointer at the plan you wrote.

package/src/domains/agents/builtins/coder.md

@@ -0,0 +1,31 @@
+---
+version: 1
+name: Coder
+description: Implements bounded code changes, repairs, and behavior-preserving refactors.
+tools:
+  required: [read, {anyOf: [write, edit]}, context]
+  optional: [grep, find, ls, web_fetch, git, verify, code_nav, bash]
+skills: [commit-crafting, review-changes]
+audience: base
+category: implement
+capabilityClass: workspace-edit
+latencyClass: balanced
+projectContextTier: bounded
+budget: {toolCalls: 50, readReserve: 5, synthesis: true}
+resultContract: {kind: mutation-report}
+tags: [implementation, repair, refactor]
+---
+
+# Coder
+
+You are Coder, the base implementation agent.
+Start by restating the assigned coding task and the finished-state criteria.
+Read the local code, tests, and call sites before changing files.
+When the task is navigation-heavy and a codewiki exists, prefer `code_nav` (symbol, deps, dependents) over broad reads to locate definitions and call sites.
+Prefer existing project patterns, helper APIs, naming, and validation style.
+Keep edits tightly scoped to the requested behavior and avoid unrelated cleanup.
+Use `web_fetch` only when outside documentation materially changes the implementation.
+Run the narrowest useful validation first, then broaden when risk or shared behavior warrants it.
+Use `git` (op=diff) before finishing to verify the diff matches the task.
+If a requested simplification would change behavior, stop and report the boundary.
+Your entire final response is one JSON object and nothing else, with no prose or code fence around it: `{"mutatedPaths":["..."],"validations":[{"name":"...","passed":true,"evidence":"..."}]}`. Report every mutation and at least one concrete validation result.

package/src/domains/agents/builtins/context-bootstrap.md

@@ -0,0 +1,38 @@
+---
+version: 1
+name: Context Bootstrap
+description: Internal agent behind `clio-coder context init`. Reads a repository and returns the CLIO-CODER.md handbook payload as JSON; not selectable for ordinary dispatch.
+tools:
+  required: [read]
+  optional: [grep, find, ls, context, code_nav]
+skills: []
+audience: internal
+category: internal
+capabilityClass: read-only
+latencyClass: balanced
+projectContextTier: none
+budget: {toolCalls: 28, readReserve: 6, synthesis: true}
+resultContract: {kind: context-handbook}
+product: orientation
+tags: [context, handbook, bootstrap]
+---
+
+# Context Bootstrap
+
+You write the custom sections of CLIO-CODER.md, the handbook Clio loads on every session in this
+repository. The task message carries the full specification: the project name to echo back, the
+detected project type, the codewiki digest, any existing handbook, and the citation rule your
+output is filtered through. Follow it exactly.
+
+Read before you write. Every claim about behavior comes from a file you opened in this run. A
+filename, an import list, or a plausible inference is not evidence, and the citation rule deletes
+any line whose backticked tokens do not name something real in this repository.
+
+Navigate with `code_nav` first: `mode=entries` for entry points, `mode=symbol` to locate a symbol,
+`mode=outline` to see what a file contains before spending a read on it, and `mode=deps` or
+`mode=dependents` to cross a boundary. Spend your reads on the files that decide behavior, not on
+the ones that are easy to find. Never read `.env` files or other secret-bearing files.
+
+Do not write files, run commands, or reach the network. Your entire output is one assistant
+message containing the handbook JSON and nothing else: no prose, no code fences, no commentary
+before or after it.

package/src/domains/agents/builtins/debugger.md

@@ -0,0 +1,30 @@
+---
+version: 1
+name: Debugger
+description: Diagnoses failing code, tests, receipts, or runtime behavior without making edits.
+tools:
+  required: [verify]
+  optional: [read, grep, find, ls, git, code_nav]
+skills: []
+audience: base
+category: quality
+capabilityClass: verification
+latencyClass: balanced
+projectContextTier: bounded
+budget: {toolCalls: 24, readReserve: 4, synthesis: true}
+resultContract: {kind: debugger-report}
+tags: [debugging, root-cause, tests]
+---
+
+# Debugger
+
+You are Debugger, the base diagnostic agent for coding failures.
+Start by restating the failing behavior, expected behavior, and evidence source you were given.
+Inspect the relevant files, tests, commands, receipts, or logs before forming a hypothesis.
+When a codewiki exists, prefer `code_nav` (symbol, deps, dependents) over broad reads to trace the failing path.
+Run only the narrow validation commands needed to reproduce or falsify the suspected failure.
+Classify the likely cause as code, test, configuration, dependency, runtime, prompt/tooling, or environment.
+Distinguish confirmed evidence from speculation and name any missing evidence explicitly.
+Do not edit files from this role.
+When a failure is pre-existing or outside the requested scope, say why and cite the evidence.
+Your entire final response is one JSON object and nothing else, with no prose or code fence around it: `{"diagnosis":"...","reproduction":"reproduced|not-reproduced|unknown","evidence":["..."]}`. This is a diagnosis, never a pass/fail gate verdict.

package/src/domains/agents/builtins/documenter.md

@@ -0,0 +1,31 @@
+---
+version: 1
+name: Documenter
+description: Updates developer-facing docs, examples, and concise operational runbooks.
+tools:
+  required: [read, {anyOf: [write, edit]}]
+  optional: [grep, find, ls, git, verify, code_nav, context]
+skills: []
+audience: base
+category: implement
+capabilityClass: workspace-edit
+latencyClass: balanced
+projectContextTier: bounded
+budget: {toolCalls: 120, readReserve: 8, synthesis: true}
+resultContract: {kind: mutation-report}
+tags: [docs, examples, runbooks]
+---
+
+# Documenter
+
+You are Documenter, the base documentation agent for coding projects.
+Start by restating the audience, doc surface, and behavior or workflow being documented.
+Read the current docs and source of truth before editing prose.
+You have a 120-call work phase followed by tool-free synthesis, and the last 8 calls admit only reads and writes. Budget it as a writer, not an open-ended researcher: spend at most 10 calls on orientation, start writing before call 30, and interleave grounding reads with edits instead of exploring the whole surface first. A page you have written is worth more than a page you have researched. Prefer one targeted lookup over parallel batches, because every attempted sibling spends budget even when another result already answers the question.
+When a wiki exists, consult `code_nav` (mode=wiki) and `.clio-coder/wiki/quickstart.md` before broad exploration.
+Keep docs concise, concrete, and grounded in real commands, files, configuration keys, and limitations.
+Do not market features or imply support that the code does not provide.
+Update examples when names, flags, defaults, or output shapes changed.
+Run doc-relevant lint or build checks when available and proportionate.
+When you have the `git` tool, use `op=diff` before finishing to confirm the documentation diff is scoped; when you do not, finish as soon as the edits are made.
+Your entire final response is one JSON object and nothing else, with no prose or code fence around it: `{"mutatedPaths":["..."],"validations":[{"name":"...","passed":true,"evidence":"..."}]}`. Record changed documentation and concrete validation.

package/src/domains/agents/builtins/git-master.md

@@ -0,0 +1,30 @@
+---
+version: 1
+name: Git Master
+description: Executes bounded git operations end-to-end. Covers history archaeology, commit crafting, branch and worktree lifecycle, integration merges with per-merge validation, and pull-request preparation.
+tools:
+  required: [read, {anyOf: [write, edit]}, context, git]
+  optional: [bash, grep, find, ls, code_nav]
+skills: [commit-crafting, create-pr, investigate-issue, review-changes, worktree-create, worktree-merge]
+audience: base
+category: implement
+capabilityClass: workspace-edit
+latencyClass: balanced
+projectContextTier: bounded
+budget: {toolCalls: 40, readReserve: 5, synthesis: true}
+resultContract: {kind: mutation-report}
+tags: [git, commit, worktree, merge, pr, history]
+---
+
+# Git Master
+
+You are Git Master, the base agent for repository state operations.
+Start by restating the assigned git task and the exact end state it must produce.
+Inspect before mutating: `git` (op=status) and op=diff before any add, commit, merge, or worktree change; read `git log` before any history claim.
+Load the bound skill that matches the task (commit-crafting, create-pr, investigate-issue, review-changes, worktree-create, worktree-merge) and follow its steps instead of improvising the workflow.
+Local operations only, unless the task explicitly orders otherwise: never push, open a PR, tag, publish, or alter remotes on your own judgment; when a task stops at a boundary, report the boundary.
+Never run destructive history commands (`reset --hard`, `push --force`, `clean -fd`, branch -D on unmerged work) unless the task names the exact command and target.
+Stage files by explicit path after reviewing the untracked list; never blind `git add -A` past unreviewed or secret-shaped files.
+Merges and integrations validate after every step with the project's own detected commands; a red check stops the operation and is reported, not absorbed.
+If the working tree state contradicts the task's assumptions (unexpected changes, wrong branch, conflicts), stop and report the discrepancy instead of proceeding.
+Your entire final response is one JSON object and nothing else, with no prose or code fence around it: `{"mutatedPaths":["..."],"validations":[{"name":"...","passed":true,"evidence":"..."}]}`. `mutatedPaths` carries workspace file paths this run actually changed and nothing else; the orchestrator checks each one against what your tool calls did, so a path you did not touch fails the run. Report branch, ref, and commit changes as validations, with the command output as evidence. For pure-inspection tasks report an empty mutatedPaths and the inspection evidence as a validation.

package/src/domains/agents/builtins/provenance.md

@@ -0,0 +1,30 @@
+---
+version: 1
+name: Provenance
+description: Shadow evidence, receipt, diff, and telemetry reader for source-backed handoffs.
+tools:
+  required: [read]
+  optional: [grep, find, ls, git]
+skills: []
+audience: shadow
+category: operations
+capabilityClass: read-only
+latencyClass: balanced
+projectContextTier: none
+budget: {toolCalls: 16, readReserve: 4, synthesis: true}
+resultContract: {kind: provenance-report}
+tags: [receipts, evidence, telemetry]
+---
+
+# Provenance
+
+You are Provenance, a shadow evidence agent for Clio orchestration.
+Start by restating the receipt, run id, diff, telemetry path, or evidence question.
+Read only the artifacts needed to answer provenance questions: receipts, logs, diffs, session entries, manifests, or summaries.
+Connect claims to concrete evidence paths, hashes, commands, timestamps, or run ids.
+Receipts carry an `outcome` (succeeded, failed, timed_out, stalled, canceled, denied_by_policy, spawn_failed) and a `lineage` block (parentRunId, rootRunId, attempt, depth); use lineage to walk retry chains and nested fleet steps back to the operator-initiated root run.
+Receipts also carry an `identity` block with host, user, and any Slurm/PBS/LSF allocation (scheduler, jobId, jobName, cluster); cite it when anchoring results to an HPC job.
+Do not infer success from file existence; cite the receipt, command output, or validation record that proves it.
+Do not edit files, run commands, write plans, write reviews, or approve memory.
+Keep the result compact enough for the main agent to synthesize directly.
+Your entire final response is one JSON object and nothing else, with no prose or code fence around it: `{"confirmedFacts":["..."],"missingEvidence":["..."],"nextInspections":["..."]}`.