deepseek-better-harness

Readme

# DeepSeek Better Harness

[![CI](https://github.com/guyuefangyuanl/deepseek-better-harness/actions/workflows/ci.yml/badge.svg)](https://github.com/guyuefangyuanl/deepseek-better-harness/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Node](https://img.shields.io/badge/node-%3E%3D22.19-brightgreen.svg)](package.json)
[![Zero runtime deps](https://img.shields.io/badge/runtime%20deps-0-blue.svg)](#zero-runtime-dependencies)

[Better Harness](https://github.com/QoderAI/better-harness) reviews an agent
project by separating evidence into three independent concerns. This repository
carries those three concerns to the
[DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) as **one DSH
bundle that registers three independently routable skills**.

Install once. Enable the lanes you want — the ones you leave out are never
registered, so they cost no routing surface and no context.

> **Unofficial.** Not affiliated with, endorsed by, or released by Qoder or
> DeepSeek. This is a community port of a boundary, not a redistribution of the
> product — see [NOTICE](NOTICE).

## The three lanes

| Lane | Reviews | Answers |
| --- | --- | --- |
| `session-evidence` | Authorized session facts | Where did the agent repeat work, hit friction, or lose a feedback loop? |
| `project-readiness` | The repository itself | Does this repo give an agent a clear change path, bounded risk, and executable verification? |
| `agent-assets` | Skills, presets, hooks, tools, MCP config | Are the agent assets discoverable, correctly routed, intact, and safely owned? |

Each lane contributes exactly one runtime skill through `ctx.skills`. A project
or user filesystem skill with the same name still overrides the bundled runtime
skill according to DSH precedence.

Each lane is also its own npm package under `packages/`, so a profile that wants
exactly one can install exactly one — see [Install](#install).

## Why this instead of the upstream product

### One lane, one job

Better Harness answers three different questions that fail in three different
ways. Collapsing them into a single "review my project" skill is what makes such
a skill vague enough to misfire. Here each lane is a separate skill with its own
boundary, and `config.lanes` decides which ones a profile registers at all:

```yaml
- id: deepseek-better-harness
  name: deepseek-better-harness
  config:
    lanes: [project-readiness]
```

Wanting a readiness review does not drag in a session analyzer, a scoring
engine, and a report renderer. An unknown lane name is a startup error, not a
silently smaller skill set.

### Zero runtime dependencies

Every package ships `"dependencies": {}`. The only declared dep is the DSH peer
package you already have. A bundle is 7 files and about 7 KB — it adds a
capability to your profile without adding a tree to your lockfile.

### Every skill says when *not* to fire

All three descriptions carry an explicit negative clause:

> Use when reviewing authorized DSH session facts for repeated work, agent
> friction, missing feedback loops, or outcome evidence. **Do NOT use** to read
> unapproved raw transcripts, infer hidden reasoning, score a whole repository,
> or inspect project assets.

Misrouting is the expensive failure in a skill layer — the model loads the wrong
skill at the wrong moment, burns context, and drifts. Because the three lanes
here are deliberately adjacent, the negative clause is what keeps a session
question from pulling in the asset auditor. Most community skills only write the
positive half.

### Evidence discipline is a mechanism, not a slogan

`harness-session-evidence` forces observed behavior, missing evidence, and
inference into separate buckets, and requires **at least two comparable
occurrences** before something may be called a pattern — one occurrence is a
candidate.

All three skills return evidence *candidates* rather than final severities or
repository-wide scores. That is not modesty: they ship no collectors, so they
are not entitled to the score. A skill that cannot see the evidence must report
that boundary instead of inventing a finding.

### Validation actually installs the plugin

`scripts/validate-packages.mjs` does not lint manifests. It `import()`s every
real `index.js`, captures the skill each one registers, then asserts bundle
identity, frontmatter, resource paths, description limits, and teardown. A
package that is structurally perfect but fails to register is caught here rather
than in your profile. CI runs it on Linux and Windows.

## Install

The repository root **is** the bundle: its manifest declares
`dsh.bundle.patch`, so DSH treats it as a profile layer and DSH Hub accepts it
as a submission. Tested baseline is DSH `0.1.0-rc.6`.

### From a commit

```powershell
dsh plugin --profile web add "github:guyuefangyuanl/deepseek-better-harness#<commit-sha>"
```

Pin a commit rather than a branch: the skill text is the product here, and you
want a review you can reproduce later.

### From a clone

```powershell
git clone https://github.com/guyuefangyuanl/deepseek-better-harness.git
dsh plugin --profile web add "link:C:/absolute/path/to/deepseek-better-harness"
```

On `0.1.0-rc.6` the profile reconciles itself — a dependency whose manifest
declares `dsh.bundle.patch` is appended to `dsh.profile.bundles` automatically,
so there is nothing to edit by hand. Confirm the layer landed:

```powershell
dsh --profile web --dump-config
```

If the layer is missing, DSH will have said why on stderr:

```text
dsh: warning: <name> declares no dsh.bundle — installed as a plain dependency,
not a profile layer
```

### Choosing lanes

All three lanes are enabled by default. To register only some of them, give the
bundle a `config.lanes` list in your profile patch:

```yaml
- id: deepseek-better-harness
  name: deepseek-better-harness
  config:
    lanes: [project-readiness, agent-assets]
```

Valid names are `session-evidence`, `project-readiness`, and `agent-assets`. An
unknown name, an empty list, or a non-array fails at startup instead of quietly
registering fewer skills than you asked for.

### Installing a single lane instead

Each lane is also a standalone package, for a profile that should never be able
to route to the other two:

```powershell
dsh plugin --profile web add "link:C:/absolute/path/to/deepseek-better-harness/packages/project-readiness"
```

Do not install both the root bundle and a lane package into one profile — the
lane would be registered twice.

### Requirements

The selected profile must already provide the DSH `skills` service and a
user/model skill surface. This bundle installs no lifecycle scripts: there is no
`preinstall`, `install`, `postinstall`, or `prepare`, and nothing is compiled on
your machine. What is in the tarball is what runs, and CI asserts that.

## Validate

No dependencies. Node.js 22:

```bash
node scripts/validate-packages.mjs
node scripts/pack-dry-run.mjs
```

## Two things that look like bugs and are not

**`parseCanonicalSkill` is duplicated verbatim in all three packages.** A shared
helper would couple three independently publishable bundles to a common
versioned runtime dependency for about thirty lines of parsing — and break the
zero-dependency property that makes a single-package install cheap. The
validator asserts every copy still produces an identical skill shape. See
[the design note](docs/specs/2026-08-20-dsh-plugin-extraction.md).

**Publishing is not automated.** Registry credentials, package ownership,
release tags, and community submission are external actions.

## Boundary

- Better Harness remains the full product: evidence collection, reconciliation,
  scoring, and rendering. This repository ports its three evidence *boundaries*
  as prompt-level skills and never claims an unavailable collector ran.
- These bundles contribute prompt text and a small loader. They open no ports,
  spawn no processes, and make no network requests. See [SECURITY.md](SECURITY.md).
- DSH is pre-release. Re-run the checks above before claiming support for a
  newer DSH than the declared baseline.

## Contributing and security

[CONTRIBUTING.md](CONTRIBUTING.md) covers the checks and the rules that are not
negotiable. [SECURITY.md](SECURITY.md) covers the trust boundary and how to
report a vulnerability.

## Author and license

Created and maintained by [@guyuefangyuanl](https://github.com/guyuefangyuanl).

MIT. See [NOTICE](NOTICE) for attribution and the unofficial-status statement.