| name | kortix-harness-refinement |
| description | The continual-harness refinement protocol — how an agent inspects its recent trajectory for failure signatures and improves its own harness (agent prompts, sub-agents, skills, memory) in place, mid-session, landing changes on the session branch immediately and promoting them to `main` only through a change request. Load this skill when a refinement prompt arrives mid-session, when the `harness-reflector` agent runs, or whenever you decide your own scaffolding needs repair. |
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 | .kortix/opencode/agents/<name>.md (body) | Each agent's instructions and strategy |
| Sub-agents | .kortix/opencode/agents/*.md | Specialist agents the orchestrator invokes |
| Skills | .kortix/opencode/skills/<name>/SKILL.md | Reusable routines: text heuristics and guides |
| Tools | .kortix/opencode/tools/*.ts | Executable code: wrappers, scripts, automations |
| Memory | .kortix/memory/ | Persistent facts, strategies, observations |
Refinement means: read your recent trajectory, find where the harness
failed you, and fix the harness — not just the immediate task. A harness
edit made mid-session takes effect on your next turn, because agents,
skills, and memory are read from disk. You do not restart; refinement is
reset-free and its value compounds over the life of the session.
This protocol has two operating modes:
Scan the trajectory window (your recent turns, or the digest) for these
signatures. Each one names the component to fix:
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.
For project-level reflection (the `harness-reflector` run), do not skim a
digest and call it a review. Work through every session:
**In-session refinement (session branch — immediate):**
- **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 `.kortix/` changes —
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".
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 fix your harness live
and benefit from the fix on your very next turn.
