opencode-harness-kit 0.0.0-stage → 0.1.0

package/profiles/schema.json

@@ -0,0 +1,132 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/anomalyco/opencode-harness-kit/profiles/schema.json",
+  "title": "OpenCode harness profile",
+  "description": "Everything that changes when you change model. Plugins read this file and contain no model names of their own.",
+  "type": "object",
+  "required": ["id", "provider", "model", "retention", "limits", "effort", "roles"],
+  "additionalProperties": false,
+  "properties": {
+    "id": {
+      "type": "string",
+      "description": "Slug used as the profile filename and the oc-harness use argument."
+    },
+    "title": { "type": "string" },
+    "provider": {
+      "type": "string",
+      "description": "opencode provider id, e.g. opencode, opencode-go, anthropic."
+    },
+    "model": {
+      "type": "string",
+      "description": "Model id without the provider prefix, e.g. space-bunny-free."
+    },
+    "family": {
+      "type": ["string", "null"],
+      "description": "Model family for grouping. Stealth models report null upstream, so this may be set by hand."
+    },
+    "verified": {
+      "type": "string",
+      "description": "ISO date a human checked this profile against live metadata."
+    },
+    "retention": {
+      "enum": ["zero-retention", "may-train", "unknown"],
+      "description": "Must match an entry in retention.yml. A profile whose model is unknown there cannot become the default."
+    },
+    "notes": { "type": "string" },
+    "limits": {
+      "type": "object",
+      "required": ["context", "output"],
+      "additionalProperties": false,
+      "description": "Token ceilings from the provider catalog. `input` is absent for several Zen models, in which case the loader derives it from `context`.",
+      "properties": {
+        "context": { "type": "integer", "minimum": 1 },
+        "input": { "type": "integer", "minimum": 1 },
+        "output": { "type": "integer", "minimum": 1 }
+      }
+    },
+    "supports": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Capability flags. Missing or false means do not emit the related config.",
+      "properties": {
+        "reasoning": { "type": "boolean" },
+        "temperature": { "type": "boolean" },
+        "toolCall": { "type": "boolean" },
+        "structuredOutput": { "type": "boolean" },
+        "attachment": {
+          "type": "boolean",
+          "description": "Accepts image or video input. Gates screenshot-based verification."
+        }
+      }
+    },
+    "effort": {
+      "type": "object",
+      "description": "Available reasoning levels, lowest to highest. Empty means the model has no tunable effort.",
+      "properties": {
+        "levels": {
+          "type": "array",
+          "items": { "type": "string" },
+          "examples": [["low", "medium", "high", "xhigh", "max"]]
+        },
+        "default": { "type": "string" },
+        "reserveShare": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 0.5,
+          "default": 0.12,
+          "description": "Share of the input ceiling held back for reasoning and tool output growth."
+        }
+      }
+    },
+    "roles": {
+      "type": "object",
+      "description": "Requested effort per agent role. Resolved against effort.levels, never emitted raw.",
+      "additionalProperties": false,
+      "properties": {
+        "plan": { "$ref": "#/definitions/effortRequest" },
+        "build": { "$ref": "#/definitions/effortRequest" },
+        "reviewer": { "$ref": "#/definitions/effortRequest" },
+        "locate": { "$ref": "#/definitions/effortRequest" },
+        "verify": { "$ref": "#/definitions/effortRequest" }
+      }
+    },
+    "prune": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Deterministic context pruning. Only used when a model-driven compressor is unavailable or unproven.",
+      "properties": {
+        "enabled": { "type": "boolean" },
+        "keepRecentToolCalls": {
+          "type": "integer",
+          "minimum": 1,
+          "default": 6,
+          "description": "Verbatim tool outputs kept at the tail."
+        },
+        "keepRecentTurns": {
+          "type": "integer",
+          "minimum": 1,
+          "default": 3,
+          "description": "Trailing turns whose text and reasoning stay verbatim."
+        },
+        "keepUserMessages": {
+          "type": "boolean",
+          "default": true,
+          "description": "Never stub a user message. Their instructions are the point of the session."
+        }
+      }
+    },
+    "fallback": {
+      "type": "array",
+      "description": "Ordered profile ids to fall back to. Selection happens at session start, not mid-session: no opencode plugin hook can change a live session's model.",
+      "items": { "type": "string" }
+    }
+  },
+  "definitions": {
+    "effortRequest": {
+      "oneOf": [
+        { "type": "string", "description": "Desired level, resolved to the nearest available one." },
+        { "type": "null", "description": "This role should not set a variant at all." }
+      ]
+    }
+  }
+}

package/profiles/space-bunny-free.json

@@ -0,0 +1,42 @@
+{
+  "$comment": "Validated against models.dev on 2026-10-07. Regenerate with `oc-harness use --refresh`.",
+  "id": "space-bunny-free",
+  "title": "Space Bunny Free (OpenCode Zen)",
+  "provider": "opencode",
+  "model": "space-bunny-free",
+  "family": null,
+  "verified": "2026-10-07",
+  "retention": "zero-retention",
+  "notes": "Stealth preview reasoning model. Served over /v1/chat/completions (openai-compatible), which is the weaker cache dialect compared with models on /v1/responses. At the time of writing it is the only free model on Zen whose top reasoning effort is `max` and whose provider is zero-retention. Free for a limited time; expect the slot to rotate.",
+  "limits": {
+    "context": 1048576,
+    "input": 524288,
+    "output": 524288
+  },
+  "supports": {
+    "reasoning": true,
+    "temperature": false,
+    "toolCall": true,
+    "structuredOutput": false,
+    "attachment": true
+  },
+  "effort": {
+    "levels": ["low", "medium", "high", "xhigh", "max"],
+    "default": "max",
+    "reserveShare": 0.12
+  },
+  "roles": {
+    "plan": "max",
+    "build": "high",
+    "reviewer": "max",
+    "locate": "low",
+    "verify": "low"
+  },
+  "prune": {
+    "enabled": true,
+    "keepRecentToolCalls": 6,
+    "keepRecentTurns": 3,
+    "keepUserMessages": true
+  },
+  "fallback": ["x-preview-f-free", "longcat-2.5-preview-free", "deepseek-v4-flash-free"]
+}

package/profiles/x-preview-f-free.json

@@ -0,0 +1,41 @@
+{
+  "$comment": "Fallback tier 1 for space-bunny-free. Zero-retention, 1M context, and a `max` effort, but only three levels: there is no medium or xhigh, so roles asking for those resolve down to high.",
+  "id": "x-preview-f-free",
+  "title": "x-preview-f Free (OpenCode Zen)",
+  "provider": "opencode",
+  "model": "x-preview-f-free",
+  "family": null,
+  "verified": "2026-10-07",
+  "retention": "zero-retention",
+  "notes": "Only three effort levels (low, high, max) and a 131k completion ceiling, so long single answers are not its strength. Kept as first fallback: same 1M context class and the same zero-retention terms as the default.",
+  "limits": {
+    "context": 1000000,
+    "output": 131072
+  },
+  "supports": {
+    "reasoning": true,
+    "temperature": true,
+    "toolCall": true,
+    "structuredOutput": true,
+    "attachment": true
+  },
+  "effort": {
+    "levels": ["low", "high", "max"],
+    "default": "max",
+    "reserveShare": 0.12
+  },
+  "roles": {
+    "plan": "max",
+    "build": "high",
+    "reviewer": "max",
+    "locate": "low",
+    "verify": "low"
+  },
+  "prune": {
+    "enabled": true,
+    "keepRecentToolCalls": 6,
+    "keepRecentTurns": 3,
+    "keepUserMessages": true
+  },
+  "fallback": ["longcat-2.5-preview-free", "deepseek-v4-flash-free"]
+}

package/retention.yml

@@ -0,0 +1,110 @@
+# Data retention and privacy, curated by hand.
+#
+# models.dev describes capability and price. It does NOT describe what a
+# provider does with your prompts. That gap is why this file exists: the most
+# consequential choice in a coding agent is often invisible in the metadata.
+#
+# Values:
+#   zero-retention  provider keeps nothing, no training
+#   may-train       prompts and/or completions may be used to improve the model
+#   unknown         not verified here; `oc-harness use` refuses to make it a
+#                   default until a human fills this in
+#
+# Sources: https://opencode.ai/docs/zen (Privacy section). Re-verify on their
+# release notes; terms change without a model rename.
+
+defaults:
+  unknown: unknown
+
+models:
+  opencode/space-bunny-free:
+    retention: zero-retention
+    note: >-
+      "Its provider follows a zero-retention policy and does not use your data
+      for model training." Free for a limited time; stealth model with no public
+      identity.
+    verified: 2026-10-07
+    source: https://opencode.ai/docs/zen
+
+  opencode/space-bunny:
+    retention: zero-retention
+    note: Same provider as space-bunny-free, paid route on the Go plan.
+    verified: 2026-10-07
+    source: https://opencode.ai/docs/zen
+
+  opencode/longcat-2.5-preview-free:
+    retention: zero-retention
+    note: "free on OpenCode for a limited time. Its provider follows a zero-retention policy."
+    verified: 2026-10-07
+    source: https://opencode.ai/docs/zen
+
+  # The two entries below are not named individually in the Privacy section.
+  # They fall under the general policy - providers follow zero-retention and do
+  # not train on your data, with a named exception list - so this is inferred
+  # from that list rather than quoted. Re-check before relying on it for
+  # anything sensitive.
+
+  opencode/x-preview-f-free:
+    retention: zero-retention
+    note: >-
+      Not named in the Privacy exception list, so the general zero-retention
+      policy applies. Inferred, not quoted.
+    verified: 2026-10-07
+    source: https://opencode.ai/docs/zen
+
+  opencode/deepseek-v4-flash-free:
+    retention: zero-retention
+    note: >-
+      Not named in the Privacy exception list, so the general zero-retention
+      policy applies. Inferred, not quoted. This route is also documented as
+      returning 429 for extended periods, so see docs/KNOWN-LIMITS.md.
+    verified: 2026-10-07
+    source: https://opencode.ai/docs/zen
+
+  opencode/muse-spark-1.3-contributor-free:
+    retention: may-train
+    note: >-
+      "Heavily discounted token pricing in exchange for permission to use your
+      prompts and completions to train future Meta models." 1M context, but its
+      top reasoning effort is xhigh, not max. Kept as an example of a
+      capability/privacy tradeoff, never as a default for private code.
+    verified: 2026-10-07
+    source: https://opencode.ai/docs/zen
+
+  opencode/muse-spark-1.3:
+    retention: may-train
+    note: Same Meta contributor terms as the free variant.
+    verified: 2026-10-07
+    source: https://opencode.ai/docs/zen
+
+  opencode/big-pickle:
+    retention: may-train
+    note: "collected data may be used to improve the model" during its free period.
+    verified: 2026-10-07
+    source: https://opencode.ai/docs/zen
+
+  opencode/exo-free:
+    retention: may-train
+    note: "collected data may be used to improve the model" during its free period.
+    verified: 2026-10-07
+    source: https://opencode.ai/docs/zen
+
+  opencode/fledge-alpha-free:
+    retention: may-train
+    note: "collected data may be used to improve the model" during its free period.
+    verified: 2026-10-07
+    source: https://opencode.ai/docs/zen
+
+  opencode/mimo-v2.5-free:
+    retention: may-train
+    note: "collected data may be used to improve the model" during its free period.
+    verified: 2026-10-07
+    source: https://opencode.ai/docs/zen
+
+  opencode/nemotron-3-ultra-free:
+    retention: may-train
+    note: >-
+      NVIDIA free trial endpoints. Trial use only, do not submit personal or
+      confidential data; sessions are logged.
+    verified: 2026-10-07
+    source: https://opencode.ai/docs/zen

package/skills/space-build/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: space-build
+description: Implement one planned task and verify it with a real command. Use when the plan is settled and files need to change.
+---
+
+# Build one task, then prove it
+
+## Steps
+
+1. **Read the task from `.space/tasks.md`, not from the conversation.** The file
+   the plan wrote is the requirement; memory of the request is not. If there is
+   no file, ask for the plan first — a task with no verify command in it is not
+   a task you can finish.
+2. **Locate before you read.** `grep`/`glob` for the candidate files, then
+   `read` with an `offset`/`limit` for the range you need. Reading whole files to
+   find out where something lives was the most expensive habit measured on this
+   setup: 2,966 full-file reads against 249 searches, about twelve per search.
+3. **Read the whole file before editing it** - not a grep hit, the file. Partial
+   reads produce edits that contradict code you did not see.
+4. **Make the smallest change** that satisfies the task. If the task is bigger
+   than it looks, stop and say so rather than quietly expanding it.
+5. **Run the verify command the plan named.** That command, not a different one,
+   not a subset.
+6. **On failure, read the actual message.** Not the last ten lines, the error.
+   Fix the cause, then run it again. The third identical attempt is a signal to
+   stop and report.
+7. **Mark the task done in `.space/tasks.md`** and paste the verify command's
+   verbatim final lines into its `verify:` line. A task marked done without
+   that has not been verified.
+8. **Report the command and its verbatim output.**
+
+## Test-first when the plan called for it
+
+If the plan said test first, write the failing test and watch it fail. A test
+that has never failed has not been shown to test anything.
+
+## Never
+
+- Leave a `TODO`, a stub, or a commented-out block for later. Partial work
+  reported as complete is the failure mode this exists to prevent.
+- Widen the task. A drive-by refactor belongs in its own plan.
+- Skip a failing test to get to green. Report it.
+- Claim a result you did not run.
+
+## Handing back
+
+Which task, which command, which result. If anything is unfinished, list it
+explicitly rather than letting the review step find it.
+
+**If you were handed back here by `space-review`**, you have a blocker with a
+`file:line` and a failing command, not a fresh task. Fix that specific thing.
+Do not re-read the plan, do not look for other improvements, and do not treat
+the review as a suggestion. A blocker that gets fixed together with a refactor
+cannot be verified on its own.

package/skills/space-finish/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: space-finish
+description: Close out a task: confirm checks, summarise the change, and hand the publish decision to a human. Use when work is implemented and reviewed.
+---
+
+# Finish
+
+Reached only when `space-review` pass 1 was clean. If there is an open
+blocker, you are at the wrong step: send it to `space-build` instead. Finishing
+over an unreviewed or blocked change is the failure this skill exists to stop.
+
+## Steps
+
+1. **Read `.space/tasks.md` first.** Any task still `pending` or `blocked`
+   means the work is unfinished: stop and say which one. The file is the
+   requirement, same as it was for `space-review`.
+2. **Run the checks one final time, on the final state of the tree.** A green
+   suite from before the last edit is not a green suite. Use `verify`.
+3. **Read the diff once more as a whole.** Reviewers read task by task; you
+   read the change as someone who has never seen it will.
+4. **Check the documentation.** Did this change make a document describe
+   something that no longer exists? Fix the document, do not note it for later.
+5. **Write the summary** a person needs in order to trust the change without
+   reading the whole diff. Anything the Decisions section of `.space/tasks.md`
+   marked as deliberately not done belongs in the summary, with its reason.
+6. **Check the install is still whole.** If this project is driven by a generated
+   config or profile, run its verify command. A hand-edit survives a regeneration
+   silently, and that is how a zero-retention claim ends up running on a
+   may-train model.
+2. **Read the diff once more as a whole.** Reviewers read task by task; you
+   read the change as someone who has never seen it will.
+3. **Check the documentation.** Did this change make a document describe
+   something that no longer exists? Fix the document, do not note it for later.
+4. **Write the summary** a person needs in order to trust the change without
+   reading the whole diff.
+5. **Check the install is still whole.** If this project is driven by a generated
+   config or profile, run its verify command. A hand-edit survives a regeneration
+   silently, and that is how a zero-retention claim ends up running on a
+   may-train model.
+
+## Summary shape
+
+- What changed, in one sentence.
+- Which checks ran and their results, verbatim.
+- What was deliberately not done, and why.
+- Anything risky or irreversible.
+
+## The publish boundary
+
+Publishing is a human action. Do not `git push`, do not open a pull request, do
+not publish a package, do not change repository visibility, even if the task
+seems to imply it. The guard will block `git push` in code, but the boundary
+is yours to hold, not only the hook's.
+
+Leave the tree in a state a human can review: on a branch, with the change
+visible in `git diff`.
+
+## Do not
+
+- Do not declare success over a failing check.
+- Do not squash, rebase, or force-push to tidy history.
+- Do not delete a failing test to make the suite green. A reported failure is
+  information; a deleted test is lost information.

package/skills/space-plan/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: space-plan
+description: Turn a vague request into an executable plan before any code is written. Use when a task is ambiguous, touches several files, or two people could disagree about done.
+---
+
+# Plan before building
+
+Most wasted agent time is not bad code, it is solving the wrong problem well.
+
+## The loop these four skills form
+
+```
+space-plan ─one task─▶ space-build ─verify passes─▶ space-review ─pass 1 clean─▶ space-finish ─▶ human
+                                ▲                         │
+                                └──── back to build, on a blocker: the file:line, the requirement
+                                                          missed, and the failing output
+```
+
+The only backwards edge is `space-review → space-build`: a blocker is the loop
+working, not the loop failing, and the only way out of a blocker is to fix the
+thing it names. `space-plan` is never a backwards edge. Each forward edge names
+what it hands over:
+
+| From | To | Hands over |
+|---|---|---|
+| `space-plan` | `space-build` | one task: exact paths, the concrete change, the verify command |
+| `space-build` | `space-review` | the command that ran, and its verbatim output |
+| `space-review` | `space-build` | on a blocker: the `file:line`, the requirement missed, the failing output |
+| `space-review` | `space-finish` | pass 1 clean: the diff as a whole |
+| `space-finish` | human | the summary, the checks, and what was deliberately left undone |
+
+**Re-plan only when the request itself was wrong**, not when a task turns out
+harder than estimated. The second case is a build failure and belongs in
+`space-build`.
+
+## Write the plan down
+
+A plan that only lives in the context gets lost the first time the context is
+pruned, which is exactly the moment the loop needs it. So the plan ends as a
+file, and every later step reads the file instead of the conversation.
+
+- Path: `.space/tasks.md` in the project you are planning for.
+- Format: [`reference/task-template.md`](reference/task-template.md) — goal,
+  constraints, decisions, risks, and one task per bullet with its files, its
+  concrete change, and its verify command.
+- `space-plan` creates it and keeps the Tasks section current. `space-build`
+  works from the task in the file. `space-review` diffs against it.
+  `space-finish` treats any task still `pending` or `blocked` as unfinished.
+
+## When this applies
+
+Use it when any of these is true:
+
+- The request has no single obvious file to change.
+- Nobody could tell from the diff whether the task was finished.
+- More than one design would satisfy the wording.
+- The task is a feature rather than a fix.
+
+Skip it for a single obvious edit. Writing a plan for `fix the typo` is waste.
+
+## Steps
+
+1. **Read first, but narrowly.** Grep the file names that must be involved,
+   then read the functions you need with an offset. A plan built on assumed
+   paths is worse than no plan: it reads as confident and sends the build step
+   to the wrong place. Reading whole files to check whether a function exists is
+   not orientation, it is 20x the context.
+2. **State the goal in one sentence, in the caller's words.** If you cannot,
+   you do not understand the request yet. Ask **one** specific question, and only
+   when a wrong guess would cost money, break the build irreversibly, publish
+   something, or be irreversible. Everything else you decide yourself.
+3. **List the constraints.** What must not change. What is out of scope. What
+   already exists that must keep working.
+4. **Break it into tasks that fit in a few minutes each.** For every task:
+   - exact file paths
+   - the concrete change, not "handle errors"
+   - the verify command, and what passing looks like
+5. **Order so the repository stays working.** Every step should leave the tests
+   green. A plan whose middle step is red is a plan that gets abandoned.
+6. **Name the risks** and the cheapest way to find out early.
+7. **Write it to `.space/tasks.md`** using `reference/task-template.md`, then
+   hand that file over with the plan summary.
+
+## What to hand off
+
+The `.space/tasks.md` file, plus a summary a reviewer can read in one screen:
+the goal sentence, the decisions you made rather than asked about, and the risks.
+Then let the agent that runs the plan load the `space-build` skill for one task at
+a time and `space-review` after the set. Use the `locate` agent to close gaps in
+your evidence first: it is read-only, and a gap closed before the plan is written
+costs a fraction of a gap found during the build.
+
+Do not batch the builds. One task at a time is what keeps the verify command
+attributable to a change.
+
+## Failure modes
+
+- Planning from the request alone, without reading code. This is the main one.
+- Tasks sized "and then the rest". They cannot be verified, so they are not tasks.
+- A plan that requires a decision you cannot make. That is a question, and it
+  belongs at the top, not buried in task 6.

package/skills/space-plan/reference/task-template.md

@@ -0,0 +1,47 @@
+# Task contract: `.space/tasks.md`
+
+`space-plan` writes this file into the project it is planning for. It is the
+one artifact the whole loop reads, so it has to survive a session whose context
+has been pruned. Never keep it in your head.
+
+```markdown
+# <goal, one sentence, in the caller's words>
+
+## Constraints
+- <what must not change, what must not be touched>
+
+## Decisions
+- <date> <decision, one line> — <why; links to plan/summary if there is one>
+
+## Risks
+- <the thing most likely to go wrong, and the cheapest way to find out early>
+
+## Tasks
+- [ ] <task, small enough to finish in a few minutes>
+  - files: <exact paths to change>
+  - change: <what the change is, concretely, not "handle errors">
+  - verify: <the exact command, and what passing looks like>
+  - status: pending | done | blocked
+- [x] <finished task>
+  - files: <paths>
+  - change: <what was done, including anything the original task did not name>
+  - verify: <the command that was actually run, and its verbatim final lines>
+  - status: done
+```
+
+How the loop uses it:
+
+| step | does |
+|---|---|
+| `space-plan` | creates and rewrites the Tasks section; records Decisions and Risks |
+| `space-build` | reads the task, writes only what it names, marks it done with the real verify output |
+| `space-review` | reads the Tasks section as the requirement, diffs against it in pass 1 |
+| `space-finish` | treats any `pending` or `blocked` task as "not finished", and asks for the summary decision |
+
+Rules:
+
+- One file per body of work. Start a new one only when the goal changes.
+- A task is `done` only with the verify command's real output pasted into its
+  `verify:` line. A task marked done without it has not been verified.
+- Add a Decisions line the moment something was chosen rather than asked. That
+  is the line that stops the next session re-litigating it.

package/skills/space-review/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: space-review
+description: Review a change in two passes, spec compliance then code quality, without editing. Use before committing or deciding a task is done.
+---
+
+# Review in two passes
+
+The order matters. Quality opinions on a change that does the wrong thing are
+noise, and they bury the finding that mattered.
+
+## Pass 1 - does it do what was asked
+
+Style is out of scope. Only the question of whether the task got done. The
+requirement is the Tasks section of `.space/tasks.md`, in the format
+`space-plan` wrote — not the conversation, and not your guess at the
+intent. If there is no file, there is no requirement to review against: say
+so and stop.
+
+- Every requirement in the task met? Name the ones that are not, with
+  `file:line`.
+- Anything in the diff the task did not ask for?
+- Does the verify command the task named exist, and does it pass?
+- Any file described as changed that is not actually in the diff?
+
+Any failure here is a **blocker**. Report it and hand it back to `space-build`
+with the location and the verify output that shows it. A review that stops
+without naming where to go next is a half result: the task is still open and
+now has an extra person who knows it is.
+
+## Pass 2 - is it any good
+
+Only if pass 1 was clean.
+
+- Duplication that will cost something on the next change
+- Error paths that swallow the reason a thing failed
+- Edge cases the tests do not cover, named specifically rather than gestured at
+- Names that do not match what they hold
+- Dead code, debug leftovers, commented-out blocks
+
+## Rules
+
+- Every finding needs a location and a consequence. "This could be clearer" is
+  not a finding. "If the API returns a list, this takes the first element and
+  silently drops the rest" is.
+- Severity is real: `blocker`, `should-fix`, `nit`. Do not inflate to look
+  thorough.
+- Propose the smallest change that removes the defect. Not a rewrite.
+- **Silence is a valid result.** Say the diff is clean. Inventing findings to
+  fill a review costs the author more than an empty review.
+
+## Report
+
+Two sections. If pass 1 blocked, one section plus the reason.