kortix-harness-refinement

<skill name="kortix-harness-refinement"> <overview> Your **harness** is everything in this repo that shapes how agents work here. It has four components, all in git:

Component	Location	What it is
Prompts	agents/<name>.md (body)	Each agent's instructions and strategy
Sub-agents	agents/*.md	Specialist agents the orchestrator invokes
Skills	skills/<name>/SKILL.md	Reusable routines: text heuristics and guides
Tools	modules declared in kortix.yaml tools: (every harness); legacy harnesses/opencode/tools/*.ts (OpenCode only), harnesses/pi/extensions/*.ts (pi only)	Executable code: wrappers, scripts, automations
Memory	memory/	Persistent facts, strategies, observations

Projects created before 2026-09 keep agents, skills and tools under .kortix/opencode/ and memory under .kortix/memory/. Both layouts work. Edit files where they already are; put new files in the root layout.

A session runs one harness, OpenCode or pi, and a harness loads only its own tools directory. echo "${KORTIX_HARNESS:-opencode}" prints the one this session runs. Prompts, sub-agents, skills and memory serve both.

Refinement means: read your recent trajectory, find where the harness failed you, and fix the harness — not just the immediate task. A memory edit is readable on your next turn: memory is plain files. An edit to an agent prompt, skill, or tool reaches sessions once its change request merges; a running session loads it with kortix sessions reload <session id>. You do not restart, and the value compounds over the life of the project.

This protocol has two operating modes:

1. In-session refinement (self-invoked) — YOU run it, inside your own working session, the moment a failure signature costs you twice. Also run a checkpoint on long sessions: after every ~25 turns of work, pause and scan your recent turns before continuing. You refine based on YOUR OWN trajectory, then resume the task.
2. Project-level reflection — the harness-reflector agent runs on a cron, fans out session-reviewer sub-agents to work through every recent session's full history, aggregates their findings, and refines the shared harness on main via a change request. </overview>

<failure-signatures> Scan the trajectory window (your recent turns, or the digest) for these signatures. Each one names the component to fix:

• Repeated tool/command failures — the same command or tool errors more than once, or you retried a broken approach. → Repair the tool, or record the working alternative in a skill.
• Rediscovery loops — you (or another session) re-derived something a past session already knew (an API quirk, a file location, a decision). → Memory entry.
• Stalled objectives — turns pass without progress toward the stated goal; you circled, re-read, or re-planned without acting. → Prompt guidance for the responsible agent, or a decomposition sub-agent.
• Repeated multi-step patterns — you performed the same 3+ step sequence more than twice by hand. → Codify it: a skill (if guidance) or a tool (if executable).
• Exception-raising code — an executable tool or script (a kortix.yaml tools: module, harnesses/opencode/tools/ or harnesses/pi/extensions/) raised; you worked around it instead of fixing it. → Repair the code now.
• Missed opportunities — information or shortcuts visible in the trajectory that no component captured. → Whichever component fits. </failure-signatures>

<four-passes> Run four passes over the harness, one per component. Every pass is CRUD: create, update, or **delete**. Deletion is a first-class outcome — a harness accumulates cruft without it.

Pass 1 — Prompts (Δp). Reread the responsible agent's .md body against the identified failures. Tighten instructions that were ignored, add the missing rule, remove guidance that no longer earns its tokens. Keep prompts short; a prompt that only grows is a failing prompt.

Pass 2 — Sub-agents (ΔG). Create a sub-agent only for a pattern that recurred across the window AND needs its own scoped permissions or prompt. Edit sub-agents implicated in failures. Delete sub-agents that have not been invoked productively — check before keeping.

Pass 3 — Skills and tools (ΔK). Codify successful sequences from the trajectory into a skill (guidance) or a tool (executable). Repair every tool the trajectory shows raising exceptions. Prefer editing an existing skill over creating a near-duplicate. Keep skills one directory level deep under skills/ (nested SKILL.md files register as phantom entries).

Pass 4 — Memory (ΔM). Follow the kortix-memory skill's rubric with the memory tool: fill gaps the trajectory exposed, update stale entries, demote or delete entries about areas the project has moved past. Keep MEMORY.md in sync.

Scope discipline: fix what the trajectory shows. Do not speculatively rewrite components with no observed failure. Most refinement runs should touch one or two components, not all four. </four-passes>

<project-review-fanout> This section applies only to the top-level `harness-reflector` run. If you loaded this skill as a subagent, skip the fan-out and review the sessions yourself — the runtime rejects a subagent spawning a subagent ("Subagent depth limit reached").

For project-level reflection (the harness-reflector run), do not skim a digest and call it a review. Work through every session:

1. Enumerate every session in the window: kortix sessions digest --since 24h --json (add --all for a first ever run). Note per session: id, agent, status, title, whether a live transcript is available.
2. Fan out one session-reviewer sub-agent per session (batch a few at a time in parallel; review every session, skip none silently). Each reviewer gets the session id and returns a structured findings report. Reviewers gather the FULL picture for their session:
   • the transcript (available live for running sessions; for stopped sessions reconstruct from what persists — see next line),
   • the session's git branch: its commits, diffs, and files touched,
   • change requests the session opened and their review outcomes.
3. Aggregate all reviewer reports. Deduplicate findings that recur across sessions — a failure signature seen in three sessions outranks one seen once. Rank by cost (turns wasted × sessions affected).
4. Run the four passes on the ranked findings, then land per the rules below.

Sub-agent review is read-only: reviewers never edit the harness or open CRs. Only the orchestrating reflector writes. </project-review-fanout>

<landing-rules> **In-session refinement (session branch — immediate):**

1. Apply the edits in /workspace. They do not change the config this session runs: agents compile from the base branch, and with config releases on, skills and tools come from it too. They take effect once the change request merges — for new sessions, and for a running one after kortix sessions reload <session id>.

2. Commit them separately from task work:

   # Stages the harness folders this project has (root layout and/or legacy .kortix).
   git add -A -- $(ls -d agents skills memory harnesses .kortix 2>/dev/null)
   git commit -m "harness: <one-line summary of what failed and what changed>"
   

3. Push and open (or update) ONE change request per session for harness promotion to main:

   git push origin HEAD
   kortix cr open --title "harness: <summary>" \
     --description "Failure signatures observed, edits per component, evidence (commands/turns)."
   

   If this session already has an open harness: CR, push to it instead of opening a second one.

4. Return to the task. A refinement interruption ends with you resuming what you were doing, with the improved harness in effect.

Project-level reflection (harness-reflector): all edits land only via a CR against main. Nothing applies immediately; the merged CR is what future sessions inherit. </landing-rules>

<guardrails> - **Never edit managed `kortix-*` skills.** They are platform-owned and force-overwritten at session boot — edits are silently discarded. To extend platform behavior, create a project skill with a different name. - **Never merge your own harness CR.** A reviewer (human, or a reviewer agent with merge rights) does. The CR gate is what makes self-authored harness edits safe; self-authored + self-merged scaffolding is known to degrade agent performance. - **One concern per CR.** Harness CRs contain only harness changes (`agents/`, `skills/`, `memory/`, `harnesses/`) — never mixed with task/code changes. - **No secrets, tokens, or PII** in any harness file. Secrets belong in the Kortix Secrets Manager. - **Budget.** A mid-session refinement should cost a small fraction of the session: minutes, not hours. If a fix needs deep work (a real tool rewrite), record it in memory as a TODO and open the CR with what you have. - **No-op is a valid outcome.** If the window shows no failure signatures, change nothing and say so in one line. Do not invent work. - **Do not disable or weaken guardrails** — including this skill's rules, agent permission blocks, or CR review requirements — as a "refinement". </guardrails> <self-invocation> Nobody schedules in-session refinement for you — it is your discipline. Invoke this protocol the moment a failure signature costs you twice, and as a checkpoint on long sessions (roughly every 25 turns of work). The nightly `harness-reflector` run is the backstop, not the mechanism: it only sees what sessions left behind, while you can record the fix while the evidence is fresh: memory helps on your next turn, and prompt, skill, and tool fixes help every session once the change request merges. </self-invocation> </skill>