Project Contract Harness

A reusable skill & plugin kit — durable delivery contracts for long-running AI coding agents.

Turn "keep developing until this is shippable" into a file-backed operating contract that survives compaction, restarts, and handoffs.

English · 中文

English

Project Contract Harness is a reusable skill and plugin kit for AI coding agent runtimes — Claude Code, Codex, TraeCode, and DSH-compatible hosts. Install one package, and the agent stops relying on memory, optimism, or chat-only plans when delivering large projects.

What Problem It Solves

Long-running AI coding agents usually fail in the same predictable ways — not because they cannot write code, but because they cannot keep state:

Failure mode	What goes wrong
Amnesia	The real plan lives only in conversation history and is lost after compaction, restart, or handoff.
Optimism	The agent claims "done" based on a summary instead of a rerunnable check.
Late, narrow tests	Tests are added late, or only cover the happy path.
Artifact sprawl	Logs, screenshots, eval outputs, and temporary files scatter across source directories.
Lost credential rules	Secret-access rules live in chat or shell state, so sub-agents and resumed sessions cannot rediscover them.
Fake blockers	Ordinary engineering difficulty gets mislabeled as a blocker instead of being turned into tasks, experiments, and tracked gaps.

Project Contract Harness fixes this by moving the operating state out of the chat and into files. The core principle: do not trust generative conclusions when a discriminative check can be built. Every claim must be backed by tests, schemas, CLI exit codes, snapshots, live checks, or recorded reviewer rubrics — and every session must leave evidence a brand-new agent can inspect after a restart.

How It Works

flowchart LR
    A[Probe .project-contract-harness/] --> B{State exists?}
    B -- yes --> C[Recover plan · tasks · gaps · evidence]
    B -- no --> D[Initialize the contract]
    C --> E[Analyze the repo]
    D --> E
    E --> F[Run tests & gates]
    F --> G{Gaps?}
    G -- yes --> H[Fix] --> F
    G -- no --> I[Deliver with evidence]

The default loop is test → gap → fix → targeted rerun → broader regression, repeated until the required gates close. Nothing important lives only in the conversation.

What It Gives An Agent

Capability	Effect
Recovery-first startup	Every session first probes `.project-contract-harness/` and resumes from durable state.
Persistent delivery contract	Plans, tasks, risks, decisions, gates, evidence, gaps, and handoff are written to files.
Discriminative validation	Claims must be backed by tests, schemas, CLI exits, snapshots, live checks, or recorded reviewer rubrics.
Evaluation matrix	The agent writes project-specific acceptance cases and turns failures into tracked gaps.
Closed-loop iteration	The default loop is `test → gap → fix → targeted rerun → broader regression`.
Layered regression	Checks are organized from static/schema through unit, integration, workflow, live/effect, and packaging gates.
Project-specific tooling	Bundled scripts bootstrap structure; the agent must create or select real runners for the target repo.
Secret-access contract	Credential names and validation rules are persisted without storing secret values.
Artifact discipline	Runtime outputs are centralized and indexed instead of scattered through source directories.
Watchdog and resource guard	Heavy commands require timeouts, heartbeat, cleanup, and process/resource awareness.
Autonomy boundary	The agent asks the user only for true external blockers after workarounds are recorded.
Privacy-safe packaging	Publication and handoff require private-data scans and package checks.

What Gets Created In A Target Project

When initialized, the target project gets a local harness directory:

.project-contract-harness/
  STARTUP.md          CONTRACT.md         PLAN.md
  TASKS.md            STATUS.md           DECISIONS.md
  RISKS.md            AUTONOMY.md         TOOLING.md
  SECRET_ACCESS.md    ARTIFACTS.md        RESOURCE_GUARD.md
  EVAL_MATRIX.md      GAPS.md             EVIDENCE.md
  HANDOFF.md
  gates.json          tasks.json          gaps.json
  eval-matrix.json    events.jsonl
  artifacts/

These files are not decorative. They are the operating surface the agent must read, update, and satisfy during development.

Choose One Deploy Path

Use exactly one package under deploy/. Each directory is a complete runtime package for one scenario. Package name: project-contract-harness.

Runtime	Copy or load this	Purpose
TraeCode native skill	`deploy/traecode-skills/project-contract-harness/`	Native `$project-contract-harness` skill.
DSH plugin	`deploy/dsh-plugin/project-contract-harness/`	Self-contained plugin with manifests, bundled skill, and dispatcher.
Claude project package	`deploy/claude-project/`	`CLAUDE.md` plus local `project-contract-harness-kit/`.
Codex project package	`deploy/codex-project/`	`AGENTS.md` plus local `project-contract-harness-kit/`.

Note: For Claude and Codex, copy the whole scenario directory or at least keep the entry file beside project-contract-harness-kit/. Copying only CLAUDE.md or AGENTS.md removes the local scripts and references that make the package self-contained. For DSH-compatible hosts, use the DSH plugin package; there is no separate prompt-only DSH package in this repository.

Install: TraeCode Skill

Copy the skill package into the skill search directory:

mkdir -p "${TRAE_HOME:-$HOME/.trae}/skills"
cp -R deploy/traecode-skills/project-contract-harness "${TRAE_HOME:-$HOME/.trae}/skills/project-contract-harness"

Use it in a prompt:

Use $project-contract-harness to recover or create this project's durable
harness, then close delivery gaps with evidence.

What happens:

The runtime loads SKILL.md from the installed skill directory.
The agent follows the skill instructions and reads references/ as needed.
Bootstrap helper scripts are available from scripts/.
The target project gets or reuses .project-contract-harness/.

Install: DSH Plugin

Copy the self-contained plugin directory into the plugin location used by the DSH host:

deploy/dsh-plugin/project-contract-harness/

The plugin package contains its own skill copy and does not depend on the TraeCode skill deploy directory:

project-contract-harness/
  dsh-plugin.json
  .codex-plugin/plugin.json
  scripts/dsh-entry.py
  skills/project-contract-harness/

Direct dispatcher commands:

python3 deploy/dsh-plugin/project-contract-harness/scripts/dsh-entry.py init --project-root /path/to/project
python3 deploy/dsh-plugin/project-contract-harness/scripts/dsh-entry.py check --project-root /path/to/project --allow-unverified
python3 deploy/dsh-plugin/project-contract-harness/scripts/dsh-entry.py scan --project-root /path/to/project
python3 deploy/dsh-plugin/project-contract-harness/scripts/dsh-entry.py watchdog check --project-root /path/to/project

What happens:

The DSH host reads dsh-plugin.json or .codex-plugin/plugin.json.
The manifest points to ./skills/project-contract-harness/SKILL.md.
Tool calls run through scripts/dsh-entry.py.
The dispatcher forwards commands to the bundled skill scripts.

Install: Claude Project Package

Copy the whole deploy directory into the target project or harness workspace:

deploy/claude-project/
  CLAUDE.md
  project-contract-harness-kit/

Place CLAUDE.md where the Claude runtime loads project instructions. Keep project-contract-harness-kit/ beside it.

What happens:

Claude receives the project-contract-harness operating rules as prompt text.
It is instructed to probe or create .project-contract-harness/.
Helper scripts are available from project-contract-harness-kit/scripts/.
Claude can initialize, check, scan, and watchdog the target project without relying on another skill install.

Install: Codex Project Package

Copy the whole deploy directory into the target project or harness workspace:

deploy/codex-project/
  AGENTS.md
  project-contract-harness-kit/

Place AGENTS.md where Codex loads project instructions. Keep project-contract-harness-kit/ beside it.

What happens:

Codex reads AGENTS.md as project instructions.
It applies the same recovery-first workflow.
Helper scripts are available from project-contract-harness-kit/scripts/.
Project-specific runners and tests are still created inside the target repo.

Target Project Workflow

Every deploy path drives the same workflow:

Probe for /path/to/project/.project-contract-harness/.
If present, recover state from startup, tasks, gaps, gates, evidence, tooling, secret access, artifact index, risks, and handoff.
If absent, initialize the harness.
If incomplete, add missing current-version files without --force; existing state is preserved and missing default gates are merged.
Analyze the repo before broad edits.
Create or select project-specific runners, eval suites, layered regressions, safe runners, secret-access checks, artifact rules, and package checks.
Iterate test → gap → fix → targeted rerun → broader regression.
Run check_contract.py --allow-unverified during setup and strict check_contract.py before delivery.

Validation Levels

The harness encourages each project to define its own layers, but the default mental model is:

Level	Purpose	Examples
L0	Static and schema checks	Formatting, type checks, manifest validation, JSON/schema checks.
L1	Unit checks	Pure logic, parser behavior, small deterministic functions.
L2	Integration checks	Local services, database adapters, file IO, API boundaries.
L3	Workflow checks	Full command paths, queued jobs, multi-step user flows, generated artifacts.
L4	Live or effect checks	Real runtime behavior, external-service smoke tests, visual/effect inspection.
L5	Package and compliance checks	Privacy scan, artifact index, release package listing, handoff completeness.

The evaluation matrix is not the finish line. Failing required cases become gaps, and required gaps must close through targeted reruns plus the relevant broader regression layer.

Bootstrap Commands

The helper scripts are templates and structural guards, not the final project test suite:

python3 deploy/traecode-skills/project-contract-harness/scripts/init_contract.py --project-root /path/to/project
python3 deploy/traecode-skills/project-contract-harness/scripts/check_contract.py --project-root /path/to/project --allow-unverified
python3 deploy/traecode-skills/project-contract-harness/scripts/privacy_scan.py /path/to/project --forbidden-word PrivateProductName
python3 deploy/traecode-skills/project-contract-harness/scripts/watchdog.py check --project-root /path/to/project

In a real large project, the agent should write or adopt project-specific scripts and record them in .project-contract-harness/TOOLING.md.

Repository Layout

deploy/                                      # user-facing deployment packages
  traecode-skills/project-contract-harness/  # native skill package
  dsh-plugin/project-contract-harness/       # self-contained DSH plugin
  claude-project/                            # CLAUDE.md plus local kit
  codex-project/                             # AGENTS.md plus local kit
source/                                      # canonical maintainer source
  skills/project-contract-harness/           # canonical skill source
  plugins/project-contract-harness/          # canonical plugin source
  variants/                                  # prompt adapters for project files
LICENSE                                      # Apache-2.0 license

For deployment, prefer deploy/. For development, edit source/ and sync the runtime packages.

Privacy And Portability

This repository is deliberately sanitized. It contains no reference-project names, private paths, host identifiers, credentials, or environment-specific data. Generated target-project harnesses should follow the same rule for any artifact that will be published, shared, or packaged.

License

Apache License 2.0. See LICENSE.

中文

Project Contract Harness 是一套可复用的 skill 和插件套件，面向 AI coding agent 运行时——Claude Code、Codex、TraeCode 以及 DSH 兼容 host。装上一个包， agent 在交付大型项目时就不再依赖记忆、乐观总结或只存在于聊天里的计划。

它解决什么问题

长周期 AI coding agent 的失败方式高度可预测——不是因为不会写代码，而是因为 存不住状态：

失败模式	具体表现
失忆	真实计划只存在于对话历史中，一旦压缩、重启或交接就丢失。
盲目乐观	agent 依据总结声称"完成"，但没有可复跑的检查。
测试又晚又窄	测试补得太晚，或者只覆盖 happy path。
产物泛滥	日志、截图、评估输出和临时文件散落在源码目录里。
凭证规则丢失	密钥访问规则写在聊天或临时 shell 状态里，子 agent 和续跑 session 找不到。
假阻塞	普通工程困难被误判为阻塞，而不是转成任务、实验和受跟踪的缺口。

**Project Contract Harness 的解法：把运行状态从聊天搬进文件。**核心原则是 当可以建立判别式检查时，不信任生成式结论。每个结论都必须由测试、schema、 CLI 退出码、snapshot、live check 或记录好的评审 rubric 支撑；每个 session 都必须留下新 agent 重启后也能检查的证据。

工作原理

flowchart LR
    A[探测 .project-contract-harness/] --> B{状态存在?}
    B -- 是 --> C[恢复 计划·任务·缺口·证据]
    B -- 否 --> D[初始化交付合同]
    C --> E[分析仓库]
    D --> E
    E --> F[运行测试与门禁]
    F --> G{有缺口?}
    G -- 有 --> H[修复] --> F
    G -- 无 --> I[带证据交付]

默认循环是 test → gap → fix → targeted rerun → broader regression，反复执行直到必需门禁全部关闭。任何重要信息都不允许只存在于对话里。

它能给 agent 什么能力

能力	效果
恢复优先启动	每个 session 先探测 `.project-contract-harness/`，从持久状态恢复。
持久化交付合同	计划、任务、风险、决策、gate、证据、缺口和交接都写入文件。
判别式验证	结论必须由测试、schema、CLI exit、snapshot、live check 或记录好的评审 rubric 支撑。
评估矩阵	agent 写项目专属验收 case，并把失败项转成受跟踪缺口。
闭环迭代	默认循环是 `test → gap → fix → targeted rerun → broader regression`。
分层回归	检查从静态/schema、单测、集成、工作流、真实效果到打包合规分层组织。
项目专属工具	内置脚本只做 bootstrap，agent 必须为目标项目创建或选择真实 runner。
密钥访问合同	持久化凭证名称和验证规则，但不保存密钥值。
产物纪律	运行产物集中管理和索引，不污染源码目录。
Watchdog 和资源守护	重任务必须有超时、心跳、清理和进程/资源意识。
自主边界	只有真实外部阻塞才问用户，普通困难要先自主转成实验和缺口。
脱敏打包	发布和交接前要跑隐私扫描与包检查。

目标项目中会创建什么

初始化后，目标项目会得到本地 harness 目录：

.project-contract-harness/
  STARTUP.md          CONTRACT.md         PLAN.md
  TASKS.md            STATUS.md           DECISIONS.md
  RISKS.md            AUTONOMY.md         TOOLING.md
  SECRET_ACCESS.md    ARTIFACTS.md        RESOURCE_GUARD.md
  EVAL_MATRIX.md      GAPS.md             EVIDENCE.md
  HANDOFF.md
  gates.json          tasks.json          gaps.json
  eval-matrix.json    events.jsonl
  artifacts/

这些文件不是装饰文档，而是 agent 在开发过程中必须读取、更新和满足的运行界面。

选择一个部署路径

只需要选择 deploy/ 下的一个包。每个目录都是一个场景下的完整运行包。包名：project-contract-harness。

运行时	复制或加载这个目录	用途
TraeCode 原生 skill	`deploy/traecode-skills/project-contract-harness/`	原生 `$project-contract-harness` skill。
DSH 插件	`deploy/dsh-plugin/project-contract-harness/`	自包含插件，带 manifest、内置 skill 和 dispatcher。
Claude 项目包	`deploy/claude-project/`	`CLAUDE.md` 加本地 `project-contract-harness-kit/`。
Codex 项目包	`deploy/codex-project/`	`AGENTS.md` 加本地 `project-contract-harness-kit/`。

注意： Claude 和 Codex 场景要复制整个目录，或至少保持入口文件与 project-contract-harness-kit/ 同级。只复制 CLAUDE.md 或 AGENTS.md 会丢失本地脚本和参考资料。DSH 兼容 host 使用 DSH 插件包；本仓库不再提供单独的 prompt-only DSH 包。

安装：TraeCode Skill

把 skill 包复制到 TraeCode 的 skill 搜索目录：

mkdir -p "${TRAE_HOME:-$HOME/.trae}/skills"
cp -R deploy/traecode-skills/project-contract-harness "${TRAE_HOME:-$HOME/.trae}/skills/project-contract-harness"

在 prompt 中使用：

Use $project-contract-harness to recover or create this project's durable
harness, then close delivery gaps with evidence.

实际发生的事情：

运行时加载已安装 skill 目录里的 SKILL.md。
agent 按 skill 指令执行，并按需读取 references/。
bootstrap helper 脚本来自 scripts/。
目标项目会创建或复用 .project-contract-harness/。

安装：DSH 插件

把自包含插件目录复制到 DSH host 使用的插件位置：

deploy/dsh-plugin/project-contract-harness/

插件包自带一份 skill 副本，不依赖 TraeCode skill 部署目录：

project-contract-harness/
  dsh-plugin.json
  .codex-plugin/plugin.json
  scripts/dsh-entry.py
  skills/project-contract-harness/

可以直接运行 dispatcher 命令：

python3 deploy/dsh-plugin/project-contract-harness/scripts/dsh-entry.py init --project-root /path/to/project
python3 deploy/dsh-plugin/project-contract-harness/scripts/dsh-entry.py check --project-root /path/to/project --allow-unverified
python3 deploy/dsh-plugin/project-contract-harness/scripts/dsh-entry.py scan --project-root /path/to/project
python3 deploy/dsh-plugin/project-contract-harness/scripts/dsh-entry.py watchdog check --project-root /path/to/project

实际发生的事情：

DSH host 读取 dsh-plugin.json 或 .codex-plugin/plugin.json。
manifest 指向 ./skills/project-contract-harness/SKILL.md。
工具调用通过 scripts/dsh-entry.py 执行。
dispatcher 会把命令转发到插件内置 skill 的脚本。

安装：Claude 项目包

复制整个部署目录到目标项目或 harness 工作区：

deploy/claude-project/
  CLAUDE.md
  project-contract-harness-kit/

把 CLAUDE.md 放到 Claude 读取项目指令的位置，并保持 project-contract-harness-kit/ 与它同级。

实际发生的事情：

Claude 通过 prompt 文本获得 project-contract-harness 的工作规则。
它会先探测或创建 .project-contract-harness/。
helper 脚本来自 project-contract-harness-kit/scripts/。
Claude 不需要依赖额外的 skill 安装，也能初始化、检查、扫描和执行 watchdog。

安装：Codex 项目包

复制整个部署目录到目标项目或 harness 工作区：

deploy/codex-project/
  AGENTS.md
  project-contract-harness-kit/

把 AGENTS.md 放到 Codex 读取项目指令的位置，并保持 project-contract-harness-kit/ 与它同级。

实际发生的事情：

Codex 读取 AGENTS.md 作为项目指令。
它执行同一套恢复优先工作流。
helper 脚本来自 project-contract-harness-kit/scripts/。
项目专属 runner 和测试仍然要在目标项目中创建。

目标项目工作流

所有部署路径最终都会驱动同一套流程：

探测 /path/to/project/.project-contract-harness/。
如果存在，从 startup、tasks、gaps、gates、evidence、tooling、secret access、artifact index、risks 和 handoff 恢复状态。
如果不存在，则初始化 harness。
如果不完整，在不使用 --force 的情况下补齐当前版本缺失文件；保留既有状态，并合并缺失的默认 gates。
大范围编辑前先分析项目。
创建或选择项目专属 runners、eval suites、分层回归、safe runners、 secret-access checks、artifact rules 和 package checks。
循环执行 test → gap → fix → targeted rerun → broader regression。
setup 期间运行 check_contract.py --allow-unverified，交付前运行严格 check_contract.py。

验证层级

harness 鼓励每个项目定义自己的层级，但默认模型是：

层级	目的	示例
L0	静态和 schema 检查	格式、类型检查、manifest 校验、JSON/schema 检查。
L1	单元检查	纯逻辑、parser 行为、小型确定性函数。
L2	集成检查	本地服务、数据库适配、文件 IO、API 边界。
L3	工作流检查	完整命令路径、队列任务、多步用户流程、生成产物。
L4	真实或效果检查	真实运行行为、外部服务 smoke test、视觉/效果检查。
L5	打包和合规检查	隐私扫描、产物索引、发布包清单、交接完整度。

评估矩阵不是终点。必需 case 失败后要变成缺口，必需缺口必须通过定向重跑和相关更大层级回归来关闭。

Bootstrap 命令

helper 脚本只是模板和结构守护，不是最终项目测试套件：

python3 deploy/traecode-skills/project-contract-harness/scripts/init_contract.py --project-root /path/to/project
python3 deploy/traecode-skills/project-contract-harness/scripts/check_contract.py --project-root /path/to/project --allow-unverified
python3 deploy/traecode-skills/project-contract-harness/scripts/privacy_scan.py /path/to/project --forbidden-word PrivateProductName
python3 deploy/traecode-skills/project-contract-harness/scripts/watchdog.py check --project-root /path/to/project

在真实大型项目里，agent 应该编写或采纳项目专属脚本，并记录到 .project-contract-harness/TOOLING.md。

仓库目录

deploy/                                      # 面向用户的部署包
  traecode-skills/project-contract-harness/  # 原生 skill 包
  dsh-plugin/project-contract-harness/       # 自包含 DSH 插件
  claude-project/                            # CLAUDE.md 加本地 kit
  codex-project/                             # AGENTS.md 加本地 kit
source/                                      # canonical maintainer source
  skills/project-contract-harness/           # canonical skill source
  plugins/project-contract-harness/          # canonical plugin source
  variants/                                  # 项目文件 prompt adapters
LICENSE                                      # Apache-2.0 license

部署时优先使用 deploy/。维护时编辑 source/，再同步到运行包。

隐私和可移植性

本仓库已经脱敏，不包含参考项目名称、私有路径、宿主标识、凭证或环境特定信息。任何会被发布、分享或打包的目标项目 harness 产物，也应该遵守同样规则。

协议

Apache License 2.0。见 LICENSE。

Navigation Menu

Repository files navigation

Project Contract Harness

English

What Problem It Solves

How It Works

What It Gives An Agent

What Gets Created In A Target Project

Choose One Deploy Path

Target Project Workflow

Validation Levels

Bootstrap Commands

Repository Layout

Privacy And Portability

License

中文

它解决什么问题

工作原理

它能给 agent 什么能力

目标项目中会创建什么

选择一个部署路径

目标项目工作流

验证层级

Bootstrap 命令

仓库目录

隐私和可移植性

协议

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
deploy		deploy
source		source
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md

Latest commit

History

Folders and files

Repository files navigation

Project Contract Harness

English

What Problem It Solves

How It Works

What It Gives An Agent

What Gets Created In A Target Project

Choose One Deploy Path

Target Project Workflow

Validation Levels

Bootstrap Commands

Repository Layout

Privacy And Portability

License

中文

它解决什么问题

工作原理

它能给 agent 什么能力

目标项目中会创建什么

选择一个部署路径

目标项目工作流

验证层级

Bootstrap 命令

仓库目录

隐私和可移植性

协议

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages