coding-agent-harness 1.0.1 → 1.0.4

package/docs-release/assets/harness-architecture.svg

@@ -0,0 +1,163 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="100%" viewBox="0 0 1400 760" role="img" aria-labelledby="title desc">
+  <title id="title">Prompt, context, and harness engineering comparison</title>
+  <desc id="desc">A side-by-side architecture diagram comparing prompt engineering, context engineering, and harness engineering for coding agents.</desc>
+  <defs>
+    <marker id="arrowhead" markerWidth="18" markerHeight="18" refX="15" refY="9" orient="auto" markerUnits="strokeWidth">
+      <path d="M2 2L16 9L2 16Z" fill="#476b32"/>
+    </marker>
+    <filter id="paperShadow" x="-4%" y="-4%" width="108%" height="108%">
+      <feDropShadow dx="0" dy="1" stdDeviation="1.4" flood-color="#000000" flood-opacity="0.12"/>
+    </filter>
+  </defs>
+  <style>
+    .outer{fill:#fffdf9;stroke:#ddd5c7;stroke-width:2}
+    .dash{fill:none;stroke:#2f332e;stroke-width:2;stroke-dasharray:8 7}
+    .arrow-band{fill:#d7e1de;opacity:.95}
+    .arrow-stroke{fill:none;stroke:#476b32;stroke-width:0}
+    .prompt-band{fill:#fee8a7;stroke:#111;stroke-width:4}
+    .context-band{fill:#b7d2eb;stroke:#111;stroke-width:4}
+    .harness-band{fill:#c5dfb2;stroke:#111;stroke-width:4}
+    .prompt-col{fill:#f8f0d8}
+    .context-col{fill:#eaf3fb}
+    .harness-col{fill:#eaf3e3}
+    .prompt-floor{fill:#c6b47a}
+    .context-floor{fill:#8ba6bd}
+    .harness-floor{fill:#8fa887}
+    .card{fill:#fff;stroke:#efe9de;stroke-width:1.2;filter:url(#paperShadow)}
+    .card-round{fill:#fff;stroke:#e8ece9;stroke-width:1.2;filter:url(#paperShadow)}
+    .prompt-text{fill:#846500}.context-text{fill:#21557f}.harness-text{fill:#3f672e}
+    .prompt-icon{stroke:#d79a00}.context-icon{stroke:#2d65ad}.harness-icon{stroke:#5c9d42}
+    .ink{fill:#111}.muted{fill:#727272}.caption{fill:#777b82}
+    .heading{font-family:Georgia, 'Times New Roman', serif;font-size:31px;font-weight:700}
+    .sub{font-family:Georgia, 'Times New Roman', serif;font-size:25px}
+    .band{font-family:'Courier New', ui-monospace, monospace;font-size:25px;font-weight:700;letter-spacing:.5px}
+    .card-title{font-family:Georgia, 'Times New Roman', serif;font-size:26px;font-weight:700}
+    .card-sub{font-family:system-ui,-apple-system,'Segoe UI',sans-serif;font-size:18px;font-style:italic;font-weight:500}
+    .small{font-family:system-ui,-apple-system,'Segoe UI',sans-serif;font-size:16px}
+    .caption-text{font-family:system-ui,-apple-system,'Segoe UI',sans-serif;font-size:24px;font-style:italic}
+    .icon{fill:none;stroke-width:3.2;stroke-linecap:round;stroke-linejoin:round}
+  </style>
+
+  <rect x="48" y="42" width="1304" height="636" rx="8" class="outer"/>
+  <rect x="56" y="88" width="1288" height="70" class="arrow-band"/>
+  <path d="M56 88H1288L1342 123L1288 158H56Z" fill="#d7e1de"/>
+  <rect x="56" y="88" width="1288" height="70" class="dash"/>
+
+  <rect x="82" y="97" width="360" height="52" rx="14" class="prompt-band"/>
+  <text x="262" y="131" text-anchor="middle" class="ink band">Prompt Engineering</text>
+  <rect x="490" y="97" width="388" height="52" rx="14" class="context-band"/>
+  <text x="684" y="131" text-anchor="middle" class="ink band">Context Engineering</text>
+  <rect x="926" y="97" width="390" height="52" rx="14" class="harness-band"/>
+  <text x="1121" y="131" text-anchor="middle" class="ink band">Harness Engineering</text>
+
+  <rect x="82" y="158" width="360" height="486" class="prompt-col"/>
+  <rect x="82" y="612" width="360" height="32" class="prompt-floor"/>
+  <rect x="490" y="158" width="388" height="486" class="context-col"/>
+  <rect x="490" y="612" width="388" height="32" class="context-floor"/>
+  <rect x="926" y="158" width="390" height="486" class="harness-col"/>
+  <rect x="926" y="612" width="390" height="32" class="harness-floor"/>
+
+  <text x="262" y="187" text-anchor="middle" class="prompt-text heading">Single-call</text>
+  <text x="262" y="223" text-anchor="middle" class="prompt-text sub">Optimize the model input</text>
+  <text x="684" y="187" text-anchor="middle" class="context-text heading">Multi-step context</text>
+  <text x="684" y="223" text-anchor="middle" class="context-text sub">Optimize what the model sees</text>
+  <text x="1121" y="187" text-anchor="middle" class="harness-text heading">System-level</text>
+  <text x="1121" y="223" text-anchor="middle" class="harness-text sub">Optimize how the agent runs</text>
+
+  <rect x="124" y="250" width="276" height="94" class="card"/>
+  <g transform="translate(148 274)" class="icon prompt-icon">
+    <rect x="0" y="0" width="39" height="48" rx="3"/>
+    <path d="M9 12H29M9 23H25M9 34H20"/>
+    <path d="M33 36L48 51M48 51L58 36M48 51V18"/>
+  </g>
+  <text x="376" y="288" text-anchor="end" class="prompt-text card-title">Instruction</text>
+  <text x="376" y="315" text-anchor="end" class="muted card-sub">role, task, constraints</text>
+
+  <rect x="124" y="386" width="276" height="94" class="card"/>
+  <g transform="translate(147 410)" class="icon prompt-icon">
+    <rect x="0" y="0" width="24" height="24" rx="3"/>
+    <rect x="33" y="0" width="24" height="24" rx="3"/>
+    <rect x="0" y="34" width="24" height="24" rx="3"/>
+    <rect x="33" y="34" width="24" height="24" rx="3"/>
+    <path d="M7 12H17M40 12H50M7 46H17M40 46H50"/>
+  </g>
+  <text x="376" y="424" text-anchor="end" class="prompt-text card-title">Examples</text>
+  <text x="376" y="451" text-anchor="end" class="muted card-sub">format and persona</text>
+
+  <rect x="124" y="522" width="276" height="94" class="card"/>
+  <g transform="translate(149 545)" class="icon prompt-icon">
+    <circle cx="29" cy="29" r="24"/>
+    <circle cx="29" cy="29" r="9"/>
+    <path d="M29 5V18M53 29H40M29 53V40M5 29H18"/>
+    <path d="M49 8L57 1M57 1L57 12M57 1H46"/>
+  </g>
+  <text x="376" y="560" text-anchor="end" class="prompt-text card-title">Iteration</text>
+  <text x="376" y="587" text-anchor="end" class="muted card-sub">refine wording</text>
+
+  <rect x="522" y="250" width="324" height="94" rx="28" class="card-round"/>
+  <g transform="translate(545 274)" class="icon context-icon">
+    <ellipse cx="25" cy="8" rx="22" ry="8"/>
+    <path d="M3 8V38C3 43 13 48 25 48S47 43 47 38V8"/>
+    <path d="M3 23C3 28 13 33 25 33S47 28 47 23"/>
+    <circle cx="58" cy="43" r="13"/>
+    <path d="M68 53L81 66"/>
+  </g>
+  <text x="820" y="288" text-anchor="end" class="context-text card-title">Retrieval</text>
+  <text x="820" y="315" text-anchor="end" class="muted card-sub">load files, docs, outputs</text>
+
+  <rect x="522" y="386" width="324" height="94" rx="28" class="card-round"/>
+  <g transform="translate(548 411)" class="icon context-icon">
+    <rect x="12" y="8" width="48" height="48" rx="4"/>
+    <path d="M22 0V8M34 0V8M46 0V8M22 56V64M34 56V64M46 56V64M4 18H12M4 32H12M4 46H12M60 18H68M60 32H68M60 46H68"/>
+  </g>
+  <text x="820" y="424" text-anchor="end" class="context-text card-title">Memory</text>
+  <text x="820" y="451" text-anchor="end" class="muted card-sub">progress and decisions</text>
+
+  <rect x="522" y="522" width="324" height="94" rx="28" class="card-round"/>
+  <g transform="translate(547 546)" class="icon context-icon">
+    <path d="M0 8H64L44 31V56L22 66V31Z"/>
+    <path d="M13 8V0M32 8V0M51 8V0"/>
+    <path d="M16 21H48"/>
+  </g>
+  <text x="820" y="560" text-anchor="end" class="context-text card-title">Filtering</text>
+  <text x="820" y="587" text-anchor="end" class="muted card-sub">remove stale context</text>
+
+  <rect x="958" y="244" width="326" height="76" rx="34" class="card-round"/>
+  <g transform="translate(982 266) scale(.78)" class="icon harness-icon">
+    <path d="M12 12L24 24M24 24L12 36M24 24H58"/>
+    <rect x="58" y="8" width="42" height="32" rx="5"/>
+    <path d="M69 24H90"/>
+  </g>
+  <text x="1258" y="276" text-anchor="end" class="harness-text card-title">CLI &amp; tools</text>
+  <text x="1258" y="301" text-anchor="end" class="muted card-sub">init, status, check</text>
+
+  <rect x="958" y="340" width="326" height="76" rx="34" class="card-round"/>
+  <g transform="translate(984 364) scale(.78)" class="icon harness-icon">
+    <rect x="0" y="0" width="68" height="44" rx="4"/>
+    <path d="M10 32L26 20L38 27L58 11"/>
+    <circle cx="26" cy="20" r="3"/><circle cx="38" cy="27" r="3"/><circle cx="58" cy="11" r="3"/>
+  </g>
+  <text x="1258" y="372" text-anchor="end" class="harness-text card-title">Dashboard</text>
+  <text x="1258" y="397" text-anchor="end" class="muted card-sub">inspect status and risks</text>
+
+  <rect x="958" y="436" width="326" height="76" rx="34" class="card-round"/>
+  <g transform="translate(985 459) scale(.78)" class="icon harness-icon">
+    <path d="M35 4L65 16V36C65 55 52 68 35 73C18 68 5 55 5 36V16Z"/>
+    <path d="M22 39L32 49L52 27"/>
+  </g>
+  <text x="1258" y="468" text-anchor="end" class="harness-text card-title">Guardrails</text>
+  <text x="1258" y="493" text-anchor="end" class="muted card-sub">boundaries and approvals</text>
+
+  <rect x="958" y="532" width="326" height="76" rx="34" class="card-round"/>
+  <g transform="translate(985 555) scale(.78)" class="icon harness-icon">
+    <path d="M8 34C8 19 20 8 36 8S64 19 64 34S52 60 36 60"/>
+    <path d="M36 60H16M16 60L25 50M16 60L25 70"/>
+    <path d="M28 31L36 39L50 24"/>
+  </g>
+  <text x="1258" y="564" text-anchor="end" class="harness-text card-title">Review loop</text>
+  <text x="1258" y="589" text-anchor="end" class="muted card-sub">regression, closeout, lessons</text>
+
+  <path d="M442 123H490" stroke="#2f332e" stroke-width="2" fill="none"/>
+  <path d="M878 123H926" stroke="#2f332e" stroke-width="2" fill="none"/>
+  <text x="700" y="725" text-anchor="middle" class="caption caption-text">From optimizing one prompt, to managing context, to engineering the agent's operating system.</text>
+</svg>

package/docs-release/assets/harness-workflow.svg

@@ -0,0 +1,64 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="100%" viewBox="0 0 1400 420" role="img" aria-labelledby="title desc">
+  <title id="title">Harness adoption workflow</title>
+  <desc id="desc">A six-step workflow diagram for adopting Coding Agent Harness: diagnose, decide, scaffold, configure, verify, and deliver.</desc>
+  <defs>
+    <marker id="arrow" viewBox="0 0 10 10" refX="8" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
+      <path d="M2 1L8 5L2 9" fill="none" stroke="context-stroke" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/>
+    </marker>
+    <filter id="shadow" x="-4%" y="-4%" width="108%" height="108%">
+      <feDropShadow dx="0" dy="1" stdDeviation="1.2" flood-color="#000000" flood-opacity="0.12"/>
+    </filter>
+  </defs>
+  <style>
+    .outer{fill:#fffdf9;stroke:#ddd5c7;stroke-width:2}
+    .dash{fill:none;stroke:#2f332e;stroke-width:2;stroke-dasharray:8 7}
+    .track{fill:#eef2ed}
+    .card{fill:#fff;stroke:#eee6d9;stroke-width:1.2;filter:url(#shadow)}
+    .teal{fill:#e5f3ed;stroke:#1d9e75}.blue{fill:#e6f1fb;stroke:#378add}.amber{fill:#faeeda;stroke:#ba7517}.green{fill:#eaf3de;stroke:#639922}
+    .ink{fill:#111}.muted{fill:#686868}.teal-text{fill:#0f6e56}.blue-text{fill:#185fa5}.amber-text{fill:#854f0b}.green-text{fill:#3b6d11}
+    .title{font-family:Georgia,'Times New Roman',serif;font-size:32px;font-weight:700}
+    .sub{font-family:system-ui,-apple-system,'Segoe UI',sans-serif;font-size:18px;font-style:italic;font-weight:500}
+    .mono{font-family:'Courier New',ui-monospace,monospace;font-size:22px;font-weight:700}
+    .small{font-family:system-ui,-apple-system,'Segoe UI',sans-serif;font-size:16px}
+    .connector{stroke:#777;stroke-width:2;fill:none}
+  </style>
+
+  <rect x="58" y="44" width="1284" height="316" rx="8" class="outer"/>
+  <text x="86" y="86" class="ink mono">Harness adoption workflow</text>
+  <text x="86" y="116" class="muted small">Use the same path for a clean install or a legacy project migration.</text>
+  <rect x="86" y="144" width="1228" height="72" rx="0" class="track"/>
+  <rect x="86" y="144" width="1228" height="72" class="dash"/>
+
+  <rect x="110" y="132" width="170" height="96" rx="12" class="card teal"/>
+  <text x="195" y="166" text-anchor="middle" class="teal-text title">Diagnose</text>
+  <text x="195" y="194" text-anchor="middle" class="muted sub">read repo facts</text>
+
+  <rect x="320" y="132" width="170" height="96" rx="12" class="card blue"/>
+  <text x="405" y="166" text-anchor="middle" class="blue-text title">Decide</text>
+  <text x="405" y="194" text-anchor="middle" class="muted sub">choose mode</text>
+
+  <rect x="530" y="132" width="170" height="96" rx="12" class="card amber"/>
+  <text x="615" y="166" text-anchor="middle" class="amber-text title">Scaffold</text>
+  <text x="615" y="194" text-anchor="middle" class="muted sub">write docs</text>
+
+  <rect x="740" y="132" width="170" height="96" rx="12" class="card blue"/>
+  <text x="825" y="166" text-anchor="middle" class="blue-text title">Configure</text>
+  <text x="825" y="194" text-anchor="middle" class="muted sub">capabilities</text>
+
+  <rect x="950" y="132" width="170" height="96" rx="12" class="card amber"/>
+  <text x="1035" y="166" text-anchor="middle" class="amber-text title">Verify</text>
+  <text x="1035" y="194" text-anchor="middle" class="muted sub">checks pass</text>
+
+  <rect x="1160" y="132" width="130" height="96" rx="12" class="card green"/>
+  <text x="1225" y="166" text-anchor="middle" class="green-text title">Deliver</text>
+  <text x="1225" y="194" text-anchor="middle" class="muted sub">PR / handoff</text>
+
+  <path d="M280 180H320" class="connector" marker-end="url(#arrow)"/>
+  <path d="M490 180H530" class="connector" marker-end="url(#arrow)"/>
+  <path d="M700 180H740" class="connector" marker-end="url(#arrow)"/>
+  <path d="M910 180H950" class="connector" marker-end="url(#arrow)"/>
+  <path d="M1120 180H1160" class="connector" marker-end="url(#arrow)"/>
+
+  <rect x="204" y="272" width="992" height="44" rx="22" fill="#fff" stroke="#ddd5c7" stroke-width="1.2" filter="url(#shadow)"/>
+  <text x="700" y="300" text-anchor="middle" class="muted sub">Dashboard, session.json, review records, and regression evidence make the handoff inspectable.</text>
+</svg>

package/docs-release/guides/agent-installation.en-US.md

@@ -0,0 +1,237 @@
+# Agent Installation Guide
+
+Chinese source: `docs-release/guides/agent-installation.md`
+
+This guide is written for coding agents that install or upgrade Harness inside a target project. The README keeps only the human-facing positioning, quick start, and minimum commands. Operational details live here and in `SKILL.md`.
+
+## Operating Contract
+
+The main operator for this CLI is usually an agent inside the target project, not the end user. The agent should not ask the user to study command flags, template folders, or capability choices. Those decisions must happen during Diagnose / Decide and be explained in the delivery summary.
+
+Commands in this guide are written with an installed `harness` command. The agent must first check `command -v harness`. If the target environment does not have `harness`, do not silently install globally. Ask the user whether `npm install -g coding-agent-harness` is allowed. Run that global install only after explicit approval. If the user does not approve or does not respond, run the same CLI with `npx --yes coding-agent-harness <command>`. Maintainers debugging from the source checkout can replace the same command with `node scripts/harness.mjs`.
+
+`harness init` does not add this npm package to the target project's dependencies. It only writes Harness docs, templates, and the registry. Delivery summaries must not imply that the target project now has an npm dependency installed. The first `npx` run downloads the package into npm cache; it is not a project dependency or a global command install. When CLI access is needed, keep using `npx --yes coding-agent-harness ...`, a user-approved global `harness`, or `node scripts/harness.mjs` from the source checkout.
+
+`npx skills add FairladyZ625/coding-agent-harness --skill coding-agent-harness`
+is not a zero-write operation. It copies the Skill into `.agents/skills/coding-agent-harness/`
+inside the target project and writes `skills-lock.json`. If the user asks for a strict
+read-only scan, skip Skill installation first and use `npx --yes coding-agent-harness status`
+/ `migrate-plan` for the scan; install the Skill or run write commands only after the user
+confirms write access.
+
+This repository also publishes the nested `preset-creator` Skill for agents that author
+reusable Harness preset packages. Since the repository has both a root `SKILL.md` and a
+nested Skill, list or install it with `--full-depth`:
+
+```bash
+npx skills add FairladyZ625/coding-agent-harness --list --full-depth
+npx skills add FairladyZ625/coding-agent-harness --skill preset-creator --full-depth
+```
+
+Use `coding-agent-harness` to operate Harness in a target project. Use `preset-creator`
+only when the agent is designing a reusable preset for a repeatable task family with
+shared references, artifacts, evidence, or complex-task overlays.
+
+Use the v1.0 six-phase flow:
+
+1. Diagnose: scan project structure, language, existing docs, CI, collaboration model, external dependencies, and risk surfaces.
+2. Decide: choose locale, delivery model, capability packs, and whether external source intake is needed.
+3. Scaffold: run `harness init` or `harness add-capability`.
+4. Configure: adapt generated docs to project facts. Do not present templates as customized standards.
+5. Verify: run CLI checks and native project evidence.
+6. Deliver: report residuals, owners, and next actions.
+
+If Diagnose finds a microservice, multi-repo, split frontend/backend, or platform subsystem, or the code references external services, SDKs, API gateways, message queues, webhooks, contracts, schemas, or mocks, the agent must ask the user whether external source material exists. Small source sets can be linked from `Source Evidence`; large source sets use `docs/11-REFERENCE/external-source-intake-standard.md` and `docs/04-DEVELOPMENT/external-source-packs/<source-key>/`, then project stable conclusions into `03/04/06`.
+
+## Locale Rules
+
+- When the user is present, ask whether Harness docs should use Chinese or English.
+- Non-interactive installation must pass `--locale zh-CN` or `--locale en-US`; do not rely on the default.
+- Use `zh-CN` for Chinese users or Chinese-first projects.
+- Use `en-US` for English teams, English-first repositories, or explicit English requests.
+- Do not mix `templates/` and `templates-zh-CN/` in one target project. Schema fields, filenames, status enums, commands, and cross-tool protocol tokens may remain English.
+
+## New Project Initialization
+
+Use this path when the target project has no legacy Harness:
+
+```bash
+harness init \
+  --locale zh-CN \
+  --capabilities core,dashboard \
+  /path/to/project
+```
+
+If the target environment does not have `harness`, ask the user whether global installation is allowed. If approved, run `npm install -g coding-agent-harness`. Without approval, use:
+
+```bash
+npx --yes coding-agent-harness init \
+  --locale zh-CN \
+  --capabilities core,dashboard \
+  /path/to/project
+```
+
+Choose capabilities conservatively:
+
+| Capability | Default | When to choose |
+| --- | --- | --- |
+| `core` | Yes | Always install. This is the document kernel. |
+| `dashboard` | No | A user or agent needs a local status page, static evidence snapshot, or localhost dynamic workbench. |
+| `safe-adoption` | No | A legacy Harness project adopts v1.0 while preserving history. |
+| `adversarial-review` | No | Release, architecture, security, data, or policy risk needs independent review artifacts. |
+| `long-running-task` | No | An agent needs to execute across many turns without asking the user at every step. |
+| `module-parallel` | No | Two or more independent modules need owners, a registry, and synchronization rules. |
+| `subagent-worker` | No | Code-editing subagents need independent worktrees and commit-backed handoff; requires `module-parallel`. |
+
+The JSON output from `init` includes a `report`. The delivery summary must include:
+
+- locale
+- selected capabilities and the reason for every optional capability
+- created / skipped files
+- the recommended daily entry from `nextCommands`, such as `harness dev` or `npx --yes coding-agent-harness dev .`
+- project-specific edits made during Configure
+- verification commands and results
+- residual owner / action / status
+- whether anything was committed, and whether dogfood artifacts were cleaned
+
+`init` does not modify `package.json` by default. Use `--add-npm-scripts` only when the user explicitly wants npm scripts in the target project. That option requires an existing `package.json` and does not overwrite existing `harness:dev` or `harness:dashboard` scripts.
+
+## External Source Intake
+
+When a project depends on external microservices, repositories, or external-team documents, agents should not drop those materials directly into `03-ARCHITECTURE`, `04-DEVELOPMENT`, or `06-INTEGRATIONS`. Use this order:
+
+```text
+Inventory -> Classify -> Sanitize -> Digest -> Project -> Verify -> Residual
+```
+
+Rules:
+
+- Ask the user for external architecture docs, API docs, diagrams, meeting notes, links, source paths, or exported packets.
+- Confirm whether the material may be copied into the repository; non-committable material is represented by path, URL, owner, access condition, and digest only.
+- If there are more than 5 external documents, multiple topics, or continuing growth, create `docs/04-DEVELOPMENT/external-source-packs/<source-key>/`.
+- `external-source-packs/` stores source indexes, digests, and projection status only.
+- Stable facts must be written back to `03-ARCHITECTURE/services/<service-key>.md`, `04-DEVELOPMENT/external-context/<service-key>.md`, or `06-INTEGRATIONS/<contract>.md`.
+- Unconfirmed or conflicting material stays in the source pack or `Do Not Assume`.
+
+## User-Level Registration
+
+If the user already has the `harness` CLI from npm or source, register this skill into user-level agent directories so each project does not need a copied skill:
+
+```bash
+harness install-user --agent codex --global
+harness doctor-user --agent codex
+```
+
+`npm install -g coding-agent-harness`, `harness install-user`, and `harness init`
+seed bundled presets:
+
+- User presets: `~/.coding-agent-harness/presets/<preset-id>/`
+- Project presets: `<target>/.coding-agent-harness/presets/<preset-id>/`
+
+Before initializing or taking over a task, agents must run
+`harness preset list --json [target]` and choose `--preset` only after checking
+the available presets. To repair missing bundled presets, run
+`harness preset seed` or `harness preset seed --project <target>`.
+
+Supported agent targets:
+
+| Agent | User directory |
+| --- | --- |
+| `codex` | `~/.codex/skills/coding-agent-harness` |
+| `claude` | `~/.claude/skills/coding-agent-harness` |
+| `gemini` | `~/.gemini/skills/coding-agent-harness` |
+| `openclaw` | `~/.openclaw/skills/coding-agent-harness` |
+| `agents` | `~/.agents/skills/coding-agent-harness` |
+| `all` | install into every directory above |
+
+Safety rules:
+
+- Interactive confirmation is the default. Non-interactive runs must pass `--yes` or first use `--dry-run`.
+- Existing files are not overwritten by default; only missing files are added.
+- Use `--force` only for explicit forced updates.
+- `doctor-user` checks that `SKILL.md`, templates, references, bundled presets, CLI scripts, this guide, and the user-level preset seed exist.
+
+## Legacy Harness Migration
+
+Use this path when the target project already has an older Harness. Do not rebuild the old docs tree and do not hand-assemble the process with `add-capability`. Start with the verifiable migration rail:
+
+```bash
+harness migrate-run \
+  --locale zh-CN \
+  --session-dir /tmp/cah-migration-project \
+  --out-dir /tmp/cah-migration-project/dashboard \
+  /path/to/old-project
+
+harness migrate-verify \
+  /tmp/cah-migration-project/session.json
+```
+
+Rules:
+
+- Do not overwrite existing `AGENTS.md`, `CLAUDE.md`, `docs/Harness-Ledger.md`, SSoTs, walkthroughs, task progress, or historical task plans.
+- When the old project mixes Chinese and English, explicitly pass `--locale zh-CN` or `--locale en-US`.
+- Only add the missing v1.0 templates and capability registry.
+- Existing project facts may be merged, appended, or recorded as residuals. They must not be replaced with generic templates.
+- Historical contract gaps become `adoption-needed` warnings in normal mode.
+- `--strict` must still fail on legacy checker failures or unresolved historical contract gaps.
+- Archive old global tables and module indexes first, then regenerate them with `harness governance rebuild --archive --apply`; those tables are agent indexes, while humans should use the Dashboard for status.
+- `migrate-verify` must pass before the migration output is reported as usable, and the dashboard path must be HTML.
+- For detailed migration strategy, read `docs-release/guides/migration-playbook.md` or `docs-release/guides/migration-playbook.en-US.md`. If the user requires proof that the old project is fully migrated, also read `docs-release/guides/full-legacy-migration-subagent-strategy.md` or `docs-release/guides/full-legacy-migration-subagent-strategy.zh-CN.md`.
+
+The agent must read `session.json` and `migrate-plan.json`, then migrate active tasks, current reviews, and truly adopted capabilities step by step. Subagent review must prove dashboard brief coverage, strict check, and final session all pass.
+
+## Task Lifecycle
+
+After initialization or migration, agents should not manually copy task folders. Use lifecycle commands:
+
+```bash
+harness new-task phase-2-lifecycle \
+  --title "Phase 2 task lifecycle" \
+  --locale en-US \
+  /path/to/project
+
+harness task-start phase-2-lifecycle \
+  --message "Start lifecycle slice implementation" \
+  /path/to/project
+
+harness task-log phase-2-lifecycle \
+  --message "Completed CLI and template updates" \
+  --evidence "command:TARGET:npm-test:passed" \
+  /path/to/project
+
+harness review-confirm TASKS/phase-2-lifecycle \
+  --reviewer "Human Reviewer" \
+  --confirm phase-2-lifecycle \
+  /path/to/project
+
+harness task-complete phase-2-lifecycle \
+  --message "Verification loop completed" \
+  /path/to/project
+```
+
+Rules:
+
+- Do not manually copy task templates or create partial task folders. `harness check` enforces the file set created by `new-task`.
+- `new-task --budget simple` creates `brief.md`, `task_plan.md`, `visual_map.md`, and `progress.md`.
+- `new-task` defaults to `standard` and creates the simple files plus `execution_strategy.md`, `findings.md`, `lesson_candidates.md`, and `review.md`.
+- `new-task --budget complex` creates the standard files plus `references/INDEX.md` and `artifacts/INDEX.md`.
+- Existing task directories are not overwritten. Renaming or continuing old tasks is a coordinator decision.
+- `task-start`, `task-block`, and `task-complete` only update lifecycle status and logs in `progress.md`.
+- `task-log` only appends execution records. Evidence uses `type:PATH:summary`, for example `command:TARGET:npm-test:passed`.
+- `review-confirm` appends a human review confirmation to `review.md` and a log entry to `progress.md`. It must reject open P0/P1/P2 findings marked `Open: yes` or `Blocks Release: yes`.
+- CLI-owned lifecycle and lesson commands auto-commit allowlisted writes in a clean Git root. Dirty state appears in `status` / dashboard warnings and blocks those mechanical commits. Agent-owned manual edits still need proactive commits; deferred commits must record the no-commit reason, owner, and next step.
+- `status --json` keeps old `task.state` for compatibility and adds `lifecycleState`, `reviewStatus`, `closeoutStatus`, and `stateConflicts`. `done` means implementation finished; it does not mean `closed`.
+- For human operation, start the local HTML workbench with `harness dev /path/to/project`. It binds to `127.0.0.1`, chooses a port automatically, opens the browser, and refreshes when docs change. In headless or CI contexts, use `harness dev --no-open /path/to/project`.
+- The lower-level compatible entry point remains `harness dashboard --workbench --out-dir /tmp/harness-workbench /path/to/project`. Static dashboard files remain read-only and must not host human confirmation actions.
+- `task-list --json` and `status --json` are the read entry points for dashboards, reviewers, and later agents.
+
+## Verification Commands
+
+Before closing installation or upgrade, run at least:
+
+```bash
+harness check --profile target-project /path/to/project
+harness status --json /path/to/project
+harness dev --no-open --out-dir /tmp/harness-workbench /path/to/project
+harness dashboard --out /tmp/harness-dashboard.html /path/to/project
+```