coding-agent-harness 1.0.2 → 1.0.5

package/LICENSE-EXCEPTION.md

@@ -0,0 +1,37 @@
+# Additional Permission for Generated Harness Materials
+
+Copyright (c) 2026 ZeyuLi (FairladyZ)
+
+Coding Agent Harness is licensed under the GNU Affero General Public License
+version 3 or any later version (`AGPL-3.0-or-later`). This file grants an
+additional permission under section 7 of the AGPL.
+
+## Generated Harness Materials
+
+For the purposes of this permission, "Generated Harness Materials" means files
+created, copied, rendered, scaffolded, or installed into a target project by
+Coding Agent Harness from bundled or user-provided templates, presets, skills,
+reference packs, examples, or documentation skeletons. This includes generated
+or installed project governance files such as `AGENTS.md`, `CLAUDE.md`, task
+plans, review files, ledgers, walkthroughs, generated dashboard data, and other
+target-project harness documents.
+
+## Permission
+
+You may use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+Generated Harness Materials under the license terms of the target project or
+under any other terms chosen by that target project's copyright holder.
+
+The AGPL does not apply to a target project, to that target project's source
+code, or to Generated Harness Materials solely because Coding Agent Harness was
+used to create, copy, render, scaffold, install, or update those materials.
+
+## Limits
+
+This additional permission does not apply to Coding Agent Harness itself,
+including its CLI/runtime source code, dashboard implementation, package source,
+or the bundled templates, presets, skills, reference packs, examples, and
+documentation as distributed in this repository or package.
+
+This permission does not grant trademark rights or remove any third-party
+license obligations that may apply independently.

package/README.md

@@ -4,115 +4,123 @@
 
 English | [简体中文](README.zh-CN.md) | [日本語](docs-release/intl/ja-JP.md) | [한국어](docs-release/intl/ko-KR.md) | [Français](docs-release/intl/fr-FR.md) | [Español](docs-release/intl/es-ES.md) | [Deutsch](docs-release/intl/de-DE.md)
 
-Coding agents can write code quickly. The annoying part starts later: one session made a plan, another changed files, and the next agent has to guess what is still risky.
+![Coding Agent Harness architecture](docs-release/assets/harness-architecture.svg)
 
-Coding Agent Harness keeps that work in the repo: plans, progress, reviews, migration notes, and a dashboard that shows the current state.
+> An open-source, document-native, ready-to-use Agent Harness for keeping Codex, Claude Code, Gemini CLI, and other coding agents clear, transparent, and reviewable during long-running software work.
 
-![Coding Agent Harness dashboard overview](docs-release/assets/dashboard-overview-en.png)
+![Coding Agent Harness Dashboard](docs-release/assets/dashboard-overview.png)
 
-## What It Looks Like
+## At A Glance
 
-The harness is just files plus a local dashboard.
+Coding Agent Harness is not another collection of chat prompts. It turns the durable facts that coding agents need into repository files: entry agreements, task plans, execution evidence, regression results, dashboards, and closeout records.
 
-- `AGENTS.md` tells the next agent how this repo works.
-- `task_plan.md`, `progress.md`, and `review.md` keep the task from turning into chat history.
-- Checks and migration reports say what is safe, what is stale, and what still needs a human decision.
-- `harness dev` opens the dashboard for everyday review.
+The smallest loop is:
 
-## The Loop
+- A human states the goal, and the agent reads the repository Harness first.
+- The agent follows Diagnose → Decide → Scaffold → Configure → Verify → Deliver.
+- The CLI and Dashboard expose status, risk, migration plans, and review evidence.
+- The next agent resumes from repository facts instead of previous chat memory.
 
-| Step | Human Experience | Agent / CLI Surface |
-| --- | --- | --- |
-| Install | Give the agent one entrypoint. | `npx skills add FairladyZ625/coding-agent-harness --skill coding-agent-harness` |
-| Start | The agent scans first, then proposes an init or migration plan. | `npx --yes coding-agent-harness init ...` or `migrate-plan` |
-| Review | Open the dashboard and check the task state. | `npx --yes coding-agent-harness dev .` |
-| Verify | Run checks before handoff. | `npx --yes coding-agent-harness check --profile target-project .` |
+![Harness workflow](docs-release/assets/harness-workflow.svg)
 
-## Try It In A Project
+## What It Is
 
-Use `npx` first. It does not add the CLI to your project dependencies.
+Coding Agent Harness is a project engineering framework for AI coding agents.
 
-```bash
-npx --yes coding-agent-harness init --locale en-US --capabilities core,dashboard .
-npx --yes coding-agent-harness dev .
-npx --yes coding-agent-harness check --profile target-project .
-```
+It adds working agreements, document structure, task lifecycle, regression evidence, and review loops directly into your repository so agents can read, execute, update, and verify the project from durable local facts.
 
-For Chinese templates:
+## Why It Exists
 
-```bash
-npx --yes coding-agent-harness init --locale zh-CN --capabilities core,dashboard .
-```
+Generating a few thousand lines of code with AI is not the hard part. The hard part is keeping the agent oriented after days of work, preventing parallel agents from overwriting each other, and letting a new agent continue from repository facts instead of chat memory.
 
-If you want a static evidence snapshot instead of the live local workbench:
+Coding Agent Harness turns those facts into part of the project.
 
-```bash
-npx --yes coding-agent-harness dashboard --out-dir tmp/harness-dashboard .
-open tmp/harness-dashboard/index.html
-```
+## Core Strengths
 
-## What The Agent Reads
+### Open Source, Simple, Ready To Use
 
-Harness is ordinary repository content. There is no database to run.
+Harness runs as ordinary project files: Markdown, templates, check scripts, static dashboard snapshots, and an optional local dynamic Workbench. The core package has no third-party runtime dependencies and does not require a background service or database. When a human needs web actions, `harness dev` starts a temporary localhost-only workbench.
 
-```text
-AGENTS.md
-docs/
-  03-ARCHITECTURE/
-  04-DEVELOPMENT/
-  05-TEST-QA/
-  09-PLANNING/TASKS/
-  10-WALKTHROUGH/
-  11-REFERENCE/
-```
+Give the installation prompt to your agent, and it can initialize, scan, migrate, and verify the target project.
 
-Typical task files:
+### Compatible With Coding Agents
 
-```text
-task_plan.md
-execution_strategy.md
-visual_map.md
-progress.md
-review.md
-lesson_candidates.md
-```
+Any agent that can read files, write files, and run commands can use this Harness. It works with Codex, Claude Code, Gemini CLI, Cursor-style agents, OpenClaw, and similar coding agents.
+
+### Document-Native And Transparent
+
+Important project state stays visible in the repository:
+
+- what the current task is
+- why it matters
+- how it should be executed
+- where the evidence is
+- whether regression passed
+- what residual risks remain
+- which tasks are complete and which still need work
+
+Humans can read briefs, dashboards, and migration reports. Agents can read structured docs, task contracts, and check results.
+
+### Built For Long-Running Work
+
+Harness covers the continuity layer of real development: task lifecycle, Brief, Execution Strategy, Visual Map, Progress Log, Review, Regression Evidence, Closeout, and Lessons.
 
-Humans scan the dashboard. Agents read the files. That is the whole trick.
+It gives each agent step context, evidence, and a finish condition.
 
-## Language Support
+### Reusable Presets For Task Families
 
-| Language | Public intro | README / guides | Executable templates |
-| --- | --- | --- | --- |
-| English | Full | Full | Full |
-| Simplified Chinese | Full | Full | Full |
-| Japanese | Intro | Routing only | Use English templates |
-| Korean | Intro | Routing only | Use English templates |
-| French | Intro | Routing only | Use English templates |
-| Spanish | Intro | Routing only | Use English templates |
-| German | Intro | Routing only | Use English templates |
+A preset is a versioned, declarative task method package. It does not install a
+new agent and it does not replace the Harness. It tells `harness new-task` how
+to create a task for a repeatable work type: what task kind to set, which inputs
+to ask for, which shared references or artifacts to copy into the task, which
+files the agent must read first, and what audit/evidence files should prove the
+task was created correctly.
 
-Intro-only pages are deliberately small. Agent-executable templates stay in English and Simplified Chinese first, because stale translated instructions are worse than no translation.
+Use presets when a group of tasks share the same setup. For example, several
+interface tasks may all depend on the same upstream microservice contract,
+fixture packet, runbook, and verification checklist. Instead of repeating that
+context in every prompt, put it in a preset and create each task with
+`harness new-task --preset <preset-id> ...`.
+
+Harness ships bundled presets, `harness init` seeds them into the target project,
+and teams can add project-local presets under `.coding-agent-harness/presets/`.
+The `preset-creator` Skill is for authoring these preset packages; the Harness
+CLI is what checks, installs, lists, and applies them.
+
+### Safe Migration For Existing Projects
+
+Legacy project migration starts with a scan, a migration plan, a recommended migration mode, and user confirmation. Only then should the agent write files. Final status is proven with a dashboard and checks.
 
 ## Good Fit
 
-This is useful when:
+Coding Agent Harness is useful for:
 
-- agents work on real repositories for days or weeks;
-- multiple agents or developers share the same project;
-- task state, review evidence, and regression results need to survive across sessions;
-- an existing project has old plans, migration notes, or scattered agent instructions;
-- the important parts of AI work should not live only in chat logs.
+- teams using coding agents on real software projects;
+- projects that run for days, weeks, or many iterations;
+- work involving multiple agents or multiple developers;
+- repositories with historical task docs, regression records, or migration notes;
+- teams that want AI development to be visible, reviewable, and reusable.
 
-## Install The Skill
+## Quick Start
 
-If your agent supports Skills:
+### Install The Skills
+
+If your agent supports Skills, inspect this repository's Skill entries with `npx`.
+Because the repository has a root Skill plus nested Skills, use `--full-depth`
+when you want to see or install `preset-creator`:
 
 ```bash
-npx skills add FairladyZ625/coding-agent-harness --list
+npx skills add FairladyZ625/coding-agent-harness --list --full-depth
 npx skills add FairladyZ625/coding-agent-harness --skill coding-agent-harness
+npx skills add FairladyZ625/coding-agent-harness --skill preset-creator --full-depth
 ```
 
-Install into the global Codex skill directory:
+Use the Skills separately:
+
+- `coding-agent-harness`: for installing, migrating, operating, and reviewing a Harness inside a target project.
+- `preset-creator`: for authoring reusable Harness preset packages when a family of tasks shares a method, external references, artifacts, evidence requirements, or complex-task skeleton overlays. This Skill includes its own Complex Task skeleton reference, so an agent can build a correct preset without already knowing Harness internals.
+
+Install a Skill into the global Codex skill directory:
 
 ```bash
 npx skills add FairladyZ625/coding-agent-harness \
@@ -122,40 +130,183 @@ npx skills add FairladyZ625/coding-agent-harness \
   -y
 ```
 
-Agents should not silently run a global npm install. If a long-lived `harness` command is desired, ask the human first:
+For the Preset Creator Skill:
+
+```bash
+npx skills add FairladyZ625/coding-agent-harness \
+  --skill preset-creator \
+  --full-depth \
+  --agent codex \
+  --global \
+  -y
+```
+
+The CLI is not automatically added to the target project's dependencies. Use `npx` when you need to run Harness commands. The first run downloads the package into the local npm cache; it does not write to the target project:
+
+```bash
+npx --yes coding-agent-harness init --locale zh-CN --capabilities core,dashboard .
+npx --yes coding-agent-harness dev .
+npx --yes coding-agent-harness check --profile target-project .
+```
+
+If you want to use `harness` as a long-lived system command, install it globally:
 
 ```bash
 npm install -g coding-agent-harness
 harness --help
 ```
 
-## Agent Prompt
+The npm install seeds bundled presets into `~/.coding-agent-harness/presets/`.
+`harness init` also seeds those presets into the target project at
+`.coding-agent-harness/presets/`, so agents can discover stable task methods
+with `harness preset list --json`.
+
+Agents must not silently run a global install. They may run `npm install -g coding-agent-harness` only after the user explicitly approves changing the global npm environment. Without that approval, keep using `npx --yes coding-agent-harness ...`.
+
+### Commands For Humans
+
+Initialize a Chinese Harness:
+
+```bash
+npx --yes coding-agent-harness init --locale zh-CN --capabilities core,dashboard .
+```
+
+Start the local dynamic Workbench:
+
+```bash
+npx --yes coding-agent-harness dev .
+```
 
-Send this to an agent inside your target project:
+The Workbench includes a Presets view for checking, installing, seeding, and
+uninstalling project or user presets. Static dashboards show the same preset
+catalog as read-only evidence.
+
+Generate a static Dashboard that can be opened offline:
+
+```bash
+npx --yes coding-agent-harness dashboard --out-dir tmp/harness-dashboard .
+open tmp/harness-dashboard/index.html
+```
+
+Run target-project checks:
+
+```bash
+npx --yes coding-agent-harness check --profile target-project .
+```
+
+### Prompt For Agents
+
+Send this to the agent inside your target project:
 
 ```text
 Install and read Coding Agent Harness first:
 
 npx skills add FairladyZ625/coding-agent-harness --skill coding-agent-harness
 
-First diagnose the project structure, then give me an initialization or migration plan.
+First check whether this environment has the harness command.
+
+If it does not, do not silently install globally. Ask me first:
+"This environment does not have the harness command. May I run npm install -g coding-agent-harness?
+This changes the global npm environment and then lets you use harness directly.
+If you do not approve, I will use npx --yes coding-agent-harness ... temporarily and will not write to project dependencies."
+
+Only after I explicitly approve, run:
+npm install -g coding-agent-harness
+harness preset list --json
+
+If I do not approve or do not respond, run CLI commands with:
+npx --yes coding-agent-harness <command>
+
+Set up Coding Agent Harness in the current project.
+Use Chinese templates by default. If the project is clearly an English team or English documentation project, ask me before switching to English.
+
+First diagnose the project structure, then give me an initialization plan.
+If this is a microservice, multi-repo, split frontend/backend, or externally integrated project, proactively ask me whether I have external architecture docs, API docs, diagrams, meeting notes, links, source paths, or exported packets.
+If the external material is large, create an external-source-packs index and digests first, then project stable conclusions into 03-ARCHITECTURE / 04-DEVELOPMENT / 06-INTEGRATIONS.
+After confirmation, execute Diagnose → Decide → Scaffold → Configure → Verify → Deliver.
+When initializing, run:
+npx --yes coding-agent-harness init --locale zh-CN --capabilities core,dashboard .
+npx --yes coding-agent-harness preset list --json .
+
+After initialization, use the dynamic web UI for daily viewing and human confirmations:
+npx --yes coding-agent-harness dev .
+
+If you only need an offline evidence snapshot, generate a static dashboard:
+npx --yes coding-agent-harness dashboard --out-dir tmp/harness-dashboard .
+
 Do not overwrite existing business docs, historical tasks, regression records, or user changes.
+When finished, report created files, check results, and recommended next steps.
+```
 
-Use npx unless I explicitly approve a global npm install:
+If the target already has an older Harness, use this:
+
+```text
+Install and read Coding Agent Harness first:
+
+npx skills add FairladyZ625/coding-agent-harness --skill coding-agent-harness
+
+First check whether this environment has the harness command.
+
+If it does not, do not silently install globally. Ask me first:
+"This environment does not have the harness command. May I run npm install -g coding-agent-harness?
+This changes the global npm environment and then lets you use harness directly.
+If you do not approve, I will use npx --yes coding-agent-harness ... temporarily and will not write to project dependencies."
+
+Only after I explicitly approve, run:
+npm install -g coding-agent-harness
+harness preset list --json
+
+If I do not approve or do not respond, run CLI commands with:
 npx --yes coding-agent-harness <command>
 
-After confirmation, execute Diagnose -> Decide -> Scaffold -> Configure -> Verify -> Deliver.
-When finished, report created files, check results, Dashboard URL or HTML path, and recommended next steps.
+This project already has an older Harness. Do not edit files yet.
+
+First run a detailed scan and give me a migration plan:
+1. Check git status, Harness status, task count, brief coverage, visual_map coverage, warnings/actions/residuals, strict status, and dashboard usability.
+2. If this is a microservice, multi-repo, split frontend/backend, or externally integrated project, proactively ask me for external source material; when the material is large, create an external-source-packs index and digests before projecting facts into 03/04/06.
+3. Recommend the migration mode from project evidence:
+   - baseline-preserve: safe adoption first; only add necessary structure and visibility.
+   - status-aware-rewrite: rewrite current or reopened tasks from SSoT, Ledger, progress, review, and git evidence.
+   - full-semantic-rewrite: rewrite task briefs / execution_strategy / visual_map so the old project becomes v1.0-readable.
+4. Report the recommended mode, rationale, expected write scope, estimated token/time cost, risks, and whether subagents are needed.
+5. Ask me the confirmation questions you need, then wait for my confirmation before writing files.
+
+During the scan phase, run at least:
+npx --yes coding-agent-harness status --json .
+npx --yes coding-agent-harness migrate-plan --json --limit 1000 .
+
+When the migration is complete, report the dynamic workbench URL or static dashboard HTML, session.json, normal/strict checks, migrate-plan summary, and whether full-cutover verification passes. If human review confirmation is required, expose that action in the local web workbench; static dashboards are read-only evidence snapshots.
+```
+
+## Contributing
+
+External contributors should start with [`CONTRIBUTING.md`](CONTRIBUTING.md). It covers repository layout, pull request expectations, root package checks, Dashboard smoke tests, npm package dry runs, and GUI submodule validation. The detailed public workflow also lives in [`docs-release/guides/contributing.md`](docs-release/guides/contributing.md).
+
+If you want your coding agent to make a contribution, send it this prompt:
+
+```text
+I want to contribute a focused change to FairladyZ625/coding-agent-harness.
+
+Start from the latest main branch and create a new feature branch. Read README.md and CONTRIBUTING.md first. Before editing files, inspect the relevant code/docs and give me a short plan.
+
+Keep the change scoped. Use only public repository files and do not rely on maintainer-local state, hidden workflows, credentials, generated dashboards, temporary files, or ignored local-only files.
+
+Run the checks that match the change. For docs-only changes, run git diff --check. For root package changes, run npm install, npm test, npm run smoke:dashboard, npm run check, node scripts/harness.mjs check --profile target-project examples/minimal-project, npm run pack:dry-run, and git diff --check as relevant. If the change touches harness-gui, also run cd harness-gui && npm ci && npm run typecheck && npm test && npm run build.
+
+When done, summarize what changed, list verification results, call out any skipped checks with reasons, and prepare the PR using the repository template.
 ```
 
 ## Learn More
 
-- Docs release index: [`docs-release/README.md`](docs-release/README.md)
+- Contributor guide: [`CONTRIBUTING.md`](CONTRIBUTING.md)
+- Detailed contributor guide: [`docs-release/guides/contributing.md`](docs-release/guides/contributing.md)
 - Agent installation guide: [`docs-release/guides/agent-installation.en-US.md`](docs-release/guides/agent-installation.en-US.md)
-- Architecture overview: [`docs-release/architecture/overview.md`](docs-release/architecture/overview.md)
-- Migration playbook: [`docs-release/guides/migration-playbook.en-US.md`](docs-release/guides/migration-playbook.en-US.md)
-- Operating models: [`docs-release/guides/repository-operating-models.en-US.md`](docs-release/guides/repository-operating-models.en-US.md)
 - Minimal project example: [`examples/minimal-project/`](examples/minimal-project/)
+- Legacy migration playbook: [`docs-release/guides/migration-playbook.en-US.md`](docs-release/guides/migration-playbook.en-US.md)
+- Full legacy migration strategy: [`docs-release/guides/full-legacy-migration-subagent-strategy.md`](docs-release/guides/full-legacy-migration-subagent-strategy.md)
+- Architecture overview: [`docs-release/architecture/overview.md`](docs-release/architecture/overview.md)
+- Deep architecture explainer (zh-CN): [`docs-release/architecture/system-explainer/`](docs-release/architecture/system-explainer/) — system design, module dependencies, task lifecycle, check system, data flow, and preset/migration engine with design rationale
+- Deep architecture explainer (en-US): [`docs-release/architecture/system-explainer/en-US/`](docs-release/architecture/system-explainer/en-US/)
 
 ## Star History
 
@@ -163,4 +314,10 @@ When finished, report created files, check results, Dashboard URL or HTML path,
 
 ## License
 
-MIT
+AGPL-3.0-or-later with an additional permission for Generated Harness
+Materials.
+
+See [`LICENSE`](LICENSE) and [`LICENSE-EXCEPTION.md`](LICENSE-EXCEPTION.md).
+The additional permission keeps files generated or installed into a target
+project from becoming AGPL-covered solely because Coding Agent Harness created
+or updated them.