coding-agent-harness 1.0.2 → 1.0.5
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +32 -0
- package/CONTRIBUTING.md +98 -0
- package/LICENSE +661 -21
- package/LICENSE-EXCEPTION.md +37 -0
- package/README.md +244 -87
- package/README.zh-CN.md +77 -35
- package/SKILL.md +32 -24
- package/docs-release/README.md +9 -5
- package/docs-release/architecture/overview.md +17 -5
- package/docs-release/architecture/overview.zh-CN.md +9 -5
- package/docs-release/architecture/system-explainer/01-system-overview.md +217 -0
- package/docs-release/architecture/system-explainer/02-module-dependency.md +257 -0
- package/docs-release/architecture/system-explainer/03-task-lifecycle.md +304 -0
- package/docs-release/architecture/system-explainer/04-check-and-governance.md +239 -0
- package/docs-release/architecture/system-explainer/05-data-flow.md +276 -0
- package/docs-release/architecture/system-explainer/06-preset-and-migration.md +303 -0
- package/docs-release/architecture/system-explainer/README.md +67 -0
- package/docs-release/architecture/system-explainer/en-US/01-system-overview.md +226 -0
- package/docs-release/architecture/system-explainer/en-US/02-module-dependency.md +263 -0
- package/docs-release/architecture/system-explainer/en-US/03-task-lifecycle.md +319 -0
- package/docs-release/architecture/system-explainer/en-US/04-check-and-governance.md +250 -0
- package/docs-release/architecture/system-explainer/en-US/05-data-flow.md +290 -0
- package/docs-release/architecture/system-explainer/en-US/06-preset-and-migration.md +323 -0
- package/docs-release/architecture/system-explainer/en-US/README.md +70 -0
- package/docs-release/assets/dashboard-overview.png +0 -0
- package/docs-release/guides/agent-installation.en-US.md +39 -15
- package/docs-release/guides/agent-installation.md +43 -16
- package/docs-release/guides/contributing.md +100 -0
- package/docs-release/guides/contributing.zh-CN.md +99 -0
- package/docs-release/guides/document-audience-and-surfaces.en-US.md +3 -2
- package/docs-release/guides/document-audience-and-surfaces.md +3 -2
- package/docs-release/guides/full-legacy-migration-subagent-strategy.md +2 -2
- package/docs-release/guides/full-legacy-migration-subagent-strategy.zh-CN.md +2 -2
- package/docs-release/guides/legacy-migration-agent-prompt.md +0 -11
- package/docs-release/guides/legacy-migration-agent-prompt.zh-CN.md +0 -11
- package/docs-release/guides/migration-playbook.en-US.md +14 -15
- package/docs-release/guides/migration-playbook.md +14 -15
- package/docs-release/guides/parent-control-repository-pattern.en-US.md +7 -5
- package/docs-release/guides/parent-control-repository-pattern.md +7 -5
- package/docs-release/guides/preset-development.md +238 -0
- package/docs-release/guides/repository-operating-models.en-US.md +5 -4
- package/docs-release/guides/repository-operating-models.md +5 -4
- package/docs-release/guides/task-state-machine.en-US.md +224 -0
- package/docs-release/guides/task-state-machine.md +231 -0
- package/docs-release/intl/en-US.md +1 -1
- package/docs-release/intl/zh-CN.md +1 -1
- package/examples/minimal-project/docs/09-PLANNING/TASKS/demo-task/INDEX.md +60 -0
- package/examples/minimal-project/docs/09-PLANNING/TASKS/demo-task/findings.md +7 -0
- package/package.json +10 -4
- package/presets/legacy-migration/checks/preset-check.mjs +3 -0
- package/presets/legacy-migration/preset.yaml +134 -0
- package/presets/legacy-migration/scripts/plan-work-queue.mjs +4 -0
- package/presets/legacy-migration/scripts/scaffold-task-contracts.mjs +4 -0
- package/presets/legacy-migration/templates/execution_strategy.append.md +18 -0
- package/presets/legacy-migration/templates/findings.seed.md +17 -0
- package/presets/legacy-migration/templates/review.seed.md +12 -0
- package/presets/legacy-migration/templates/task_plan.append.md +9 -0
- package/presets/legacy-migration/templates/visual_map.append.md +12 -0
- package/presets/legacy-migration/workbench/dashboard-panels.yaml +2 -0
- package/presets/legacy-migration/workbench/migration-queue.schema.json +23 -0
- package/presets/lesson-sedimentation/preset.yaml +23 -0
- package/presets/lesson-sedimentation/templates/prompt.md +23 -0
- package/presets/module/preset.yaml +25 -0
- package/presets/module/templates/execution_strategy.append.md +8 -0
- package/presets/module/templates/task_plan.append.md +17 -0
- package/presets/standard-task/preset.yaml +31 -0
- package/presets/standard-task/templates/task_plan.append.md +7 -0
- package/references/adversarial-review-standard.md +2 -2
- package/references/agents-md-pattern.md +2 -2
- package/references/delivery-operating-model-standard.md +3 -3
- package/references/docs-directory-standard.md +6 -7
- package/references/harness-ledger.md +53 -96
- package/references/lessons-governance.md +88 -93
- package/references/module-parallel-standard.md +14 -14
- package/references/planning-loop.md +12 -6
- package/references/pull-request-standard.md +118 -0
- package/references/repo-governance-standard.md +11 -2
- package/references/review-routing-standard.md +7 -1
- package/references/ssot-governance.md +67 -59
- package/references/taskr-gap-analysis.md +600 -0
- package/references/walkthrough-closeout.md +7 -7
- package/scripts/check-harness.mjs +40 -301
- package/scripts/commands/dashboard-command.mjs +67 -0
- package/scripts/commands/migration-command.mjs +126 -0
- package/scripts/commands/preset-command.mjs +73 -0
- package/scripts/commands/task-command.mjs +328 -0
- package/scripts/harness.mjs +59 -260
- package/scripts/lib/capability-registry.mjs +82 -28
- package/scripts/lib/check-module-parallel.mjs +230 -0
- package/scripts/lib/check-profiles.mjs +90 -228
- package/scripts/lib/check-task-contracts.mjs +55 -0
- package/scripts/lib/core-shared.mjs +65 -2
- package/scripts/lib/dashboard-data.mjs +155 -24
- package/scripts/lib/dashboard-workbench.mjs +131 -12
- package/scripts/lib/dashboard-writer.mjs +20 -4
- package/scripts/lib/git-status-summary.mjs +46 -0
- package/scripts/lib/governance-index-generator.mjs +174 -0
- package/scripts/lib/governance-sync.mjs +611 -0
- package/scripts/lib/governance-table-boundary.mjs +175 -0
- package/scripts/lib/harness-core.mjs +6 -0
- package/scripts/lib/lesson-maintenance.mjs +36 -29
- package/scripts/lib/markdown-utils.mjs +33 -0
- package/scripts/lib/migration-planner.mjs +4 -6
- package/scripts/lib/migration-support.mjs +1 -1
- package/scripts/lib/phase-kind.mjs +50 -0
- package/scripts/lib/preset-audit-contracts.mjs +37 -0
- package/scripts/lib/preset-engine.mjs +494 -0
- package/scripts/lib/preset-registry.mjs +776 -0
- package/scripts/lib/preset-resource-contracts.mjs +83 -0
- package/scripts/lib/review-confirm-git-gate.mjs +248 -0
- package/scripts/lib/status-builder.mjs +88 -0
- package/scripts/lib/status-dashboard-renderer.mjs +105 -0
- package/scripts/lib/subagent-authorization-audit.mjs +196 -0
- package/scripts/lib/task-audit-metadata.mjs +385 -0
- package/scripts/lib/task-audit-migration.mjs +350 -0
- package/scripts/lib/task-completion-consistency.mjs +26 -0
- package/scripts/lib/task-index.mjs +93 -0
- package/scripts/lib/task-lesson-candidates.mjs +242 -0
- package/scripts/lib/task-lesson-sedimentation.mjs +326 -0
- package/scripts/lib/task-lifecycle/create-task-helpers.mjs +67 -0
- package/scripts/lib/task-lifecycle/phase-sync.mjs +88 -0
- package/scripts/lib/task-lifecycle/review-confirm.mjs +112 -0
- package/scripts/lib/task-lifecycle/review-gates.mjs +73 -0
- package/scripts/lib/task-lifecycle/review-submission.mjs +63 -0
- package/scripts/lib/task-lifecycle/scaffold-provenance.mjs +49 -0
- package/scripts/lib/task-lifecycle/template-files.mjs +53 -0
- package/scripts/lib/task-lifecycle/text-utils.mjs +24 -0
- package/scripts/lib/task-lifecycle.mjs +338 -477
- package/scripts/lib/task-metadata.mjs +118 -0
- package/scripts/lib/task-review-model.mjs +455 -0
- package/scripts/lib/task-scanner.mjs +193 -372
- package/scripts/lib/task-tombstone-commands.mjs +140 -0
- package/scripts/postinstall.mjs +14 -0
- package/skills/preset-creator/SKILL.md +179 -0
- package/skills/preset-creator/references/complex-task-skeleton/README.md +31 -0
- package/skills/preset-creator/references/complex-task-skeleton/artifacts/INDEX.md +12 -0
- package/skills/preset-creator/references/complex-task-skeleton/brief.md +43 -0
- package/skills/preset-creator/references/complex-task-skeleton/execution_strategy.md +71 -0
- package/skills/preset-creator/references/complex-task-skeleton/findings.md +24 -0
- package/skills/preset-creator/references/complex-task-skeleton/lesson_candidates.md +70 -0
- package/skills/preset-creator/references/complex-task-skeleton/long-running-task-contract.md +76 -0
- package/skills/preset-creator/references/complex-task-skeleton/progress.md +33 -0
- package/skills/preset-creator/references/complex-task-skeleton/references/INDEX.md +13 -0
- package/skills/preset-creator/references/complex-task-skeleton/review.md +107 -0
- package/skills/preset-creator/references/complex-task-skeleton/task_plan.md +111 -0
- package/skills/preset-creator/references/complex-task-skeleton/visual_map.md +50 -0
- package/skills/preset-creator/references/preset-package-skeleton.md +296 -0
- package/templates/AGENTS.md.template +24 -18
- package/templates/dashboard/assets/app-src/00-state.js +13 -0
- package/templates/dashboard/assets/app-src/10-router.js +5 -1
- package/templates/dashboard/assets/app-src/20-overview.js +18 -8
- package/templates/dashboard/assets/app-src/30-tasks.js +92 -246
- package/templates/dashboard/assets/app-src/35-task-detail.js +286 -0
- package/templates/dashboard/assets/app-src/45-review.js +241 -22
- package/templates/dashboard/assets/app-src/50-migration.js +24 -10
- package/templates/dashboard/assets/app-src/55-presets.js +375 -0
- package/templates/dashboard/assets/app-src/60-shared.js +3 -1
- package/templates/dashboard/assets/app-src/90-bindings.js +302 -29
- package/templates/dashboard/assets/app.css +1501 -376
- package/templates/dashboard/assets/app.css.manifest.json +10 -0
- package/templates/dashboard/assets/app.js +1240 -101
- package/templates/dashboard/assets/app.manifest.json +2 -0
- package/templates/dashboard/assets/css-src/00-foundation.css +346 -0
- package/templates/dashboard/assets/css-src/10-panels-flow.css +236 -0
- package/templates/dashboard/assets/css-src/20-briefs-controls.css +398 -0
- package/templates/dashboard/assets/css-src/30-task-index.css +739 -0
- package/templates/dashboard/assets/css-src/35-review-workspace.css +507 -0
- package/templates/dashboard/assets/css-src/40-detail-modules-migration.css +489 -0
- package/templates/dashboard/assets/css-src/45-presets.css +516 -0
- package/templates/dashboard/assets/css-src/50-responsive-overrides.css +551 -0
- package/templates/dashboard/assets/i18n.js +263 -23
- package/templates/ledger/Harness-Ledger.md +13 -25
- package/templates/lessons/lesson-arch-process-change.md +1 -1
- package/templates/lessons/lesson-new-doc.md +1 -1
- package/templates/lessons/lesson-ref-change.md +1 -1
- package/templates/planning/INDEX.md +87 -0
- package/templates/planning/brief.md +1 -1
- package/templates/planning/execution_strategy.md +31 -0
- package/templates/planning/lesson_candidates.md +18 -6
- package/templates/planning/module_session_prompt.md +1 -0
- package/templates/planning/optional/artifacts/INDEX.md +3 -3
- package/templates/planning/optional/references/INDEX.md +3 -3
- package/templates/planning/review.md +41 -0
- package/templates/planning/task_plan.md +5 -21
- package/templates/planning/visual_map.md +13 -9
- package/templates/planning/visual_map.simple.md +52 -0
- package/templates/reference/execution-workflow-standard.md +31 -3
- package/templates/reference/pull-request-standard.md +80 -0
- package/templates/reference/repo-governance-standard.md +7 -6
- package/templates/reference/review-routing-standard.md +6 -0
- package/templates/reference/walkthrough-standard.md +2 -1
- package/templates/verifier/verifier-output.md +1 -1
- package/templates-zh-CN/AGENTS.md.template +25 -19
- package/templates-zh-CN/ledger/Harness-Ledger.md +17 -40
- package/templates-zh-CN/planning/INDEX.md +87 -0
- package/templates-zh-CN/planning/brief.md +1 -1
- package/templates-zh-CN/planning/execution_strategy.md +30 -0
- package/templates-zh-CN/planning/lesson_candidates.md +18 -6
- package/templates-zh-CN/planning/module_session_prompt.md +1 -0
- package/templates-zh-CN/planning/review.md +41 -1
- package/templates-zh-CN/planning/task_plan.md +4 -44
- package/templates-zh-CN/planning/visual_map.md +14 -7
- package/templates-zh-CN/planning/visual_map.simple.md +48 -0
- package/templates-zh-CN/reference/adversarial-review-standard.md +1 -1
- package/templates-zh-CN/reference/docs-library-standard.md +1 -1
- package/templates-zh-CN/reference/execution-workflow-standard.md +33 -7
- package/templates-zh-CN/reference/harness-ledger-standard.md +2 -2
- package/templates-zh-CN/reference/pull-request-standard.md +106 -0
- package/templates-zh-CN/reference/repo-governance-standard.md +4 -3
- package/templates-zh-CN/reference/review-routing-standard.md +8 -1
- package/templates-zh-CN/reference/walkthrough-standard.md +3 -2
- package/templates-zh-CN/walkthrough/Closeout-SSoT.md +1 -1
- package/docs-release/assets/dashboard-overview-en.png +0 -0
- package/scripts/smoke-dashboard.mjs +0 -92
- package/scripts/test-harness.mjs +0 -1395
- package/templates/ssot/Feature-SSoT.md +0 -43
- package/templates/ssot/Lessons-SSoT.md +0 -44
- package/templates-zh-CN/ssot/Feature-SSoT.md +0 -49
- package/templates-zh-CN/ssot/Lessons-SSoT.md +0 -49
|
@@ -98,17 +98,6 @@ harness migrate-verify /tmp/cah-migration-project/session.json
|
|
|
98
98
|
|
|
99
99
|
如果后续继续清理 warning 或补活跃任务合同,第一次 session 只能作为 baseline。最终交付前要重新运行 `migrate-run` 生成新 session/dashboard,或者明确列出 baseline session 与最终检查证据的差异。
|
|
100
100
|
|
|
101
|
-
4. 用 session 创建 Complex Task preset:
|
|
102
|
-
|
|
103
|
-
```bash
|
|
104
|
-
harness new-task \
|
|
105
|
-
--budget complex \
|
|
106
|
-
--preset legacy-migration \
|
|
107
|
-
--from-session /tmp/cah-migration-project/session.json
|
|
108
|
-
```
|
|
109
|
-
|
|
110
|
-
这一步只创建任务骨架和 `evidence/<timestamp>/` 证据包,不会继续运行迁移、改写历史任务、stage 或 commit。生成的任务会写入 `Task Kind`、`Task Preset`、`Preset Version`、`Migration Target Level`、`Migration Achieved Level` 和 `Evidence Bundle`,后续 agent 应在这个 Complex Task 里推进迁移,而不是另起一套流程。
|
|
111
|
-
|
|
112
101
|
`migrate-verify` 通过不等于 full migration complete。完整迁移还必须满足:
|
|
113
102
|
|
|
114
103
|
- `migrate-plan` 是 `declared-capability`。
|
|
@@ -119,7 +108,7 @@ harness new-task \
|
|
|
119
108
|
- 任务索引页面能打开并显示全量任务。
|
|
120
109
|
- 至少一轮 subagent 对抗审查 PASS。
|
|
121
110
|
|
|
122
|
-
|
|
111
|
+
4. 按计划继续人工/agent 清理:
|
|
123
112
|
|
|
124
113
|
- `MP-01`:确认兼容层和 locale,保证历史文档没有被覆盖。
|
|
125
114
|
- `MP-02`:选择 capability,只声明项目事实已经支持的能力。
|
|
@@ -128,14 +117,14 @@ harness new-task \
|
|
|
128
117
|
- `MP-05`:升级当前 release/architecture/security/data review,不重写所有历史 review。
|
|
129
118
|
- `MP-06`:普通检查 warning 都有 owner/action/status 后,再使用 strict 作为门禁。
|
|
130
119
|
|
|
131
|
-
|
|
120
|
+
5. 普通迁移验证:
|
|
132
121
|
|
|
133
122
|
```bash
|
|
134
123
|
harness check --profile target-project /path/to/project
|
|
135
124
|
harness dashboard --out-dir /tmp/harness-dashboard /path/to/project
|
|
136
125
|
```
|
|
137
126
|
|
|
138
|
-
|
|
127
|
+
6. 严格切换验证:
|
|
139
128
|
|
|
140
129
|
```bash
|
|
141
130
|
harness check --profile target-project --strict /path/to/project
|
|
@@ -175,6 +164,16 @@ Baseline 模式下,只有 `current-active` 或 “仍被 SSoT 引用为当前
|
|
|
175
164
|
|
|
176
165
|
Status-aware rewrite 模式下,已有 `brief.md`、`execution_strategy.md`、`visual_map.md` 不是自动保留;如果证据显示它们只是旧模板、解析残留、语言错误或不能让人判断当前状态,就重写。历史任务可以只写可读索引卡或 residual,但这个判断必须有证据。
|
|
177
166
|
|
|
167
|
+
全局表和模块索引迁移不是人工重填。新版本只把任务生命周期汇总生成到 `Harness-Ledger.md`;旧的 `Feature-SSoT.md` 和 `Private-Feature-SSoT.md` 是 legacy 生命周期投影,切换时应先归档,不再重建。模块 `module_plan.md` 的 Steps 表和模块 `visual_map.md` 的拓扑表仍由模块任务文件生成。人看当前状态应优先看 Dashboard,Agent 需要快速定位时用 `task-list` / `task-index` 查询。旧项目切换前,先把旧生命周期表归档,再用生成器从任务文件重建当前索引:
|
|
168
|
+
|
|
169
|
+
```bash
|
|
170
|
+
harness governance rebuild --dry-run --archive /path/to/project
|
|
171
|
+
harness governance rebuild --archive --apply /path/to/project
|
|
172
|
+
harness task-list --json --search "keyword" /path/to/project
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
归档目录会保留旧生命周期表快照。确认 Dashboard、`task-list` / `task-index` 查询和新生成 Ledger 都能反映当前任务后,再由项目 owner 决定是否删除旧归档;迁移 agent 不应直接删除历史表证据。Delivery、Regression、Cadence、Closeout、Module Registry 等非任务生命周期治理表不是本步骤的删除对象,除非后续版本提供等价 scanner 和生成器。
|
|
176
|
+
|
|
178
177
|
Full semantic rewrite 模式下,所有任务都需要 standalone `brief.md`,但不能写空模板。历史任务的 brief 应该是“可读索引卡”:说明任务目标、第一眼应该看什么、证据来自哪里、状态判断和 residual。`visual_map.md` 是图表集合,不是路线图模板;只画能提高理解速度的 phase flow、sequence、architecture、data-flow、state、topology 或 decision map,不能为了过检查生成空图。
|
|
179
178
|
|
|
180
179
|
如果旧项目属于微服务、多仓、前后端分仓或依赖外部系统,迁移计划还必须询问用户是否有外部资料。不要把外部团队给的几十份文档直接迁入 `03/04/06`。先按 `external-source-intake-standard.md` 建立 `docs/04-DEVELOPMENT/external-source-packs/<source-key>/`,完成 source index 和 digest,再把稳定事实投影到 service profile、external context 和 integration contract。
|
|
@@ -286,7 +285,7 @@ Full cutover 的 dashboard smoke 必须验证:
|
|
|
286
285
|
| --- | --- | --- |
|
|
287
286
|
| Task Contract Worker | `docs/09-PLANNING/TASKS/**/brief.md`、`execution_strategy.md`、`visual_map.md`、同任务 `progress.md` 追加 | 清掉 task contract 缺口;在已确认 rewrite 模式下重写薄弱旧表面。 |
|
|
288
287
|
| Review/Capability Worker | `.harness-capabilities.json`、当前 strict review 文件 | 声明真实 capability,修 release-blocking review schema。 |
|
|
289
|
-
| Legacy Governance Worker | `AGENTS.md`、PR template、`docs/11-REFERENCE/**`、Ledger、Closeout SSoT、
|
|
288
|
+
| Legacy Governance Worker | `AGENTS.md`、PR template、`docs/11-REFERENCE/**`、Ledger、Closeout SSoT、lesson candidates/detail docs、walkthrough template | 清掉 legacy checker 聚合错误。 |
|
|
290
289
|
| Brief Coverage Workers | 按日期段或模块划分,写缺失或被点名薄弱的 `brief.md` | 把 dashboard brief coverage 变成 100%,并移除空模板。 |
|
|
291
290
|
| Quality Repair Worker | 只写 reviewer 点名的问题文件 | 修掉自动解析痕迹、空模板、语言不一致和证据薄弱。 |
|
|
292
291
|
|
|
@@ -16,7 +16,7 @@ Multi-repo projects often run into these failures:
|
|
|
16
16
|
|
|
17
17
|
- Frontend, backend, SDK, and services each have their own plans, and no one can tell where the global release is blocked.
|
|
18
18
|
- An agent starts inside a child repository, reads only local `AGENTS.md`, and misses cross-repo architecture constraints.
|
|
19
|
-
- Each repository maintains its own
|
|
19
|
+
- Each repository maintains its own handwritten task lifecycle table, and the states conflict.
|
|
20
20
|
- Review evidence, test evidence, and walkthroughs are scattered across repositories, making it hard to prove that a cross-repo task is complete.
|
|
21
21
|
|
|
22
22
|
The parent-control pattern solves a control-plane problem. It does not force code back into a monorepo. It moves the harness source of truth into one place.
|
|
@@ -62,7 +62,8 @@ It should contain:
|
|
|
62
62
|
- `docs/03-ARCHITECTURE/repository-topology.md`: repository topology, owners, boundaries, dependency direction.
|
|
63
63
|
- `docs/04-DEVELOPMENT/local-development.md`: cross-repo local startup, integration workflow, dependency setup.
|
|
64
64
|
- `docs/06-INTEGRATIONS/`: cross-service APIs, events, SDKs, databases, permissions, and external contracts.
|
|
65
|
-
- `docs/
|
|
65
|
+
- `docs/Harness-Ledger.md`: generated global task lifecycle index from task files.
|
|
66
|
+
- `docs/09-PLANNING/Delivery-SSoT.md`: cross-repo feature blocks, dependencies, and release orchestration.
|
|
66
67
|
- `docs/09-PLANNING/TASKS/`: cross-repo task contracts.
|
|
67
68
|
- `docs/05-TEST-QA/Regression-SSoT.md`: cross-repo regression gates.
|
|
68
69
|
- `docs/05-TEST-QA/Cadence-Ledger.md`: which changes trigger which checks.
|
|
@@ -94,7 +95,7 @@ They should contain:
|
|
|
94
95
|
- Repository-local reviews or pull requests.
|
|
95
96
|
- Repository-local test evidence.
|
|
96
97
|
|
|
97
|
-
Child repositories should not independently maintain
|
|
98
|
+
Child repositories should not independently maintain global task lifecycle tables, and they should not decide whether a cross-repo release is complete.
|
|
98
99
|
|
|
99
100
|
A child repository `AGENTS.md` can be short:
|
|
100
101
|
|
|
@@ -228,7 +229,7 @@ The agent does not need to read all docs in 100 repositories at startup. It read
|
|
|
228
229
|
|
|
229
230
|
Avoid:
|
|
230
231
|
|
|
231
|
-
- Each child repository maintaining its own global
|
|
232
|
+
- Each child repository maintaining its own global task lifecycle table.
|
|
232
233
|
- A parent repository with only a README and no task, regression, or closeout surface.
|
|
233
234
|
- Child `AGENTS.md` files copying large sections from the parent, causing drift.
|
|
234
235
|
- Starting cross-repo tasks from a child repository and backfilling parent records at the end.
|
|
@@ -241,7 +242,8 @@ To adopt the parent-control model, start with:
|
|
|
241
242
|
|
|
242
243
|
- Parent `AGENTS.md` states that this is the control repository.
|
|
243
244
|
- `docs/03-ARCHITECTURE/repository-topology.md` lists all child repositories.
|
|
244
|
-
- `docs/
|
|
245
|
+
- `docs/Harness-Ledger.md` is generated from task files as the global task lifecycle index.
|
|
246
|
+
- `docs/09-PLANNING/Delivery-SSoT.md` is maintained only when cross-repo release or block orchestration is needed.
|
|
245
247
|
- `docs/05-TEST-QA/Regression-SSoT.md` defines local, contract, integration, and release gates.
|
|
246
248
|
- Each child repository has only a short local `AGENTS.md`.
|
|
247
249
|
- New cross-repo tasks are created only in the parent repository.
|
|
@@ -16,7 +16,7 @@ English mirror: `docs-release/guides/parent-control-repository-pattern.en-US.md`
|
|
|
16
16
|
|
|
17
17
|
- 前端、后端、SDK、微服务各有自己的计划,没人知道全局 release 到底卡在哪里。
|
|
18
18
|
- Agent 从某个子仓库启动,只看到局部 `AGENTS.md`,忽略了跨仓架构约束。
|
|
19
|
-
-
|
|
19
|
+
- 每个仓库各自维护手写任务生命周期表,状态互相冲突。
|
|
20
20
|
- Review 证据、测试证据、walkthrough 分散在不同仓库,最后无法证明一个跨仓任务真正完成。
|
|
21
21
|
|
|
22
22
|
主控仓库模式解决的是控制面问题。它不是要求把代码放回单仓,而是把 Harness 的事实源收回一个地方。
|
|
@@ -62,7 +62,8 @@ product-control-repo/
|
|
|
62
62
|
- `docs/03-ARCHITECTURE/repository-topology.md`:仓库拓扑、owner、边界、依赖方向。
|
|
63
63
|
- `docs/04-DEVELOPMENT/local-development.md`:跨仓本地启动、联调、依赖安装。
|
|
64
64
|
- `docs/06-INTEGRATIONS/`:跨服务 API、事件、SDK、数据库、权限、外部系统契约。
|
|
65
|
-
- `docs/
|
|
65
|
+
- `docs/Harness-Ledger.md`:由任务文件生成的全局任务生命周期索引。
|
|
66
|
+
- `docs/09-PLANNING/Delivery-SSoT.md`:跨仓 feature block、依赖和 release 编排。
|
|
66
67
|
- `docs/09-PLANNING/TASKS/`:跨仓任务合同。
|
|
67
68
|
- `docs/05-TEST-QA/Regression-SSoT.md`:跨仓 regression gates。
|
|
68
69
|
- `docs/05-TEST-QA/Cadence-Ledger.md`:哪些变更触发哪些检查。
|
|
@@ -94,7 +95,7 @@ node tools/check-harness.mjs
|
|
|
94
95
|
- 本仓库局部 review 或 PR。
|
|
95
96
|
- 本仓库局部测试证据。
|
|
96
97
|
|
|
97
|
-
|
|
98
|
+
子仓库不应该单独维护全局任务生命周期表,也不应该自己决定跨仓 release 是否完成。
|
|
98
99
|
|
|
99
100
|
一个子仓库 `AGENTS.md` 可以很短:
|
|
100
101
|
|
|
@@ -228,7 +229,7 @@ Agent 不需要在启动时读 100 个仓库的所有文档。它先读父任务
|
|
|
228
229
|
|
|
229
230
|
避免这些做法:
|
|
230
231
|
|
|
231
|
-
-
|
|
232
|
+
- 每个子仓库各自维护全局任务生命周期表。
|
|
232
233
|
- 父仓库只有 README,没有任务、回归和 closeout。
|
|
233
234
|
- 子仓库 `AGENTS.md` 复制父仓库大段内容,导致漂移。
|
|
234
235
|
- 跨仓任务从子仓库启动,最后再补父仓库记录。
|
|
@@ -241,7 +242,8 @@ Agent 不需要在启动时读 100 个仓库的所有文档。它先读父任务
|
|
|
241
242
|
|
|
242
243
|
- 父仓库 `AGENTS.md` 写清楚它是 control repo。
|
|
243
244
|
- `docs/03-ARCHITECTURE/repository-topology.md` 列出所有子仓库。
|
|
244
|
-
- `docs/
|
|
245
|
+
- `docs/Harness-Ledger.md` 由任务文件生成全局任务生命周期索引。
|
|
246
|
+
- `docs/09-PLANNING/Delivery-SSoT.md` 只在需要跨仓 release / block 编排时维护。
|
|
245
247
|
- `docs/05-TEST-QA/Regression-SSoT.md` 定义局部、契约、集成、发布 gate。
|
|
246
248
|
- 每个子仓库只有短的局部 `AGENTS.md`。
|
|
247
249
|
- 新跨仓任务只在父仓库创建。
|
|
@@ -0,0 +1,238 @@
|
|
|
1
|
+
# Preset Development
|
|
2
|
+
|
|
3
|
+
Harness presets are declarative task method packages. A preset can add task metadata, render Markdown templates, require CLI inputs, generate evidence files, and pre-load shared reference bundles without writing JavaScript.
|
|
4
|
+
|
|
5
|
+
Use a preset when multiple tasks should start from the same method, evidence contract, or shared context. Do not create a preset for one-off prose. Good presets encode repeatable task behavior: required inputs, task kind, review/evidence expectations, shared references, and a small amount of task-plan guidance that tells the next agent what to read first.
|
|
6
|
+
|
|
7
|
+
`preset.yaml` uses the Harness manifest subset: nested mappings, scalar strings/numbers/booleans, and inline arrays such as `[standard, complex]`. Do not use block strings or dash-list YAML forms in preset manifests.
|
|
8
|
+
|
|
9
|
+
## Install Location
|
|
10
|
+
|
|
11
|
+
Project presets live in:
|
|
12
|
+
|
|
13
|
+
```text
|
|
14
|
+
<target>/.coding-agent-harness/presets/<preset-id>/
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
User-installed presets live in:
|
|
18
|
+
|
|
19
|
+
```text
|
|
20
|
+
~/.coding-agent-harness/presets/<preset-id>/
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
When a target is supplied, Harness discovers project presets first, then user presets, then bundled presets under the package `presets/` directory. Use project presets when a repository needs to override or pin a task method. Use user presets for personal reusable methods across repositories.
|
|
24
|
+
|
|
25
|
+
Bundled presets are not only fallback files. `npm install -g coding-agent-harness`
|
|
26
|
+
and `harness install-user` seed them into the user preset root, while
|
|
27
|
+
`harness init` seeds them into the project preset root. Re-run
|
|
28
|
+
`harness preset seed` for the user root or `harness preset seed --project <target>`
|
|
29
|
+
for the project root when a preset root is missing or incomplete.
|
|
30
|
+
|
|
31
|
+
## Dashboard Management
|
|
32
|
+
|
|
33
|
+
The Dashboard exposes a Presets view for the target project. Static dashboards
|
|
34
|
+
show a read-only catalog of discovered project, user, and bundled presets,
|
|
35
|
+
including source, purpose, compatible budgets, task kind, manifest path, and
|
|
36
|
+
resource counts.
|
|
37
|
+
|
|
38
|
+
Use the local dynamic Workbench when you want to manage presets from the web UI:
|
|
39
|
+
|
|
40
|
+
```bash
|
|
41
|
+
harness dev /path/to/project
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
In Workbench mode, the Presets view can check presets, install a local preset
|
|
45
|
+
directory, `.zip` archive, or bundled preset id into the project or user scope,
|
|
46
|
+
seed bundled presets into either scope, and uninstall project/user presets.
|
|
47
|
+
Bundled package presets are immutable from the Dashboard: they can be inspected,
|
|
48
|
+
checked, and used as install or seed sources, but not edited or deleted.
|
|
49
|
+
|
|
50
|
+
The CLI and filesystem remain canonical. The Dashboard calls the same preset
|
|
51
|
+
registry operations as `harness preset ...`; it does not store independent preset
|
|
52
|
+
state.
|
|
53
|
+
|
|
54
|
+
## Package Layout
|
|
55
|
+
|
|
56
|
+
```text
|
|
57
|
+
my-preset/
|
|
58
|
+
preset.yaml
|
|
59
|
+
templates/
|
|
60
|
+
task_plan.append.md
|
|
61
|
+
references/
|
|
62
|
+
upstream-contract.md
|
|
63
|
+
resources/
|
|
64
|
+
service-runbook.md
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
## Minimal Manifest
|
|
68
|
+
|
|
69
|
+
```yaml
|
|
70
|
+
id: custom-review
|
|
71
|
+
version: 1
|
|
72
|
+
purpose: Create a review task with preset evidence.
|
|
73
|
+
compatibleBudgets: [standard, complex]
|
|
74
|
+
localeSupport: [en-US, zh-CN]
|
|
75
|
+
task:
|
|
76
|
+
kind: review-task
|
|
77
|
+
defaultTaskId: custom-review-task
|
|
78
|
+
entrypoints:
|
|
79
|
+
newTask:
|
|
80
|
+
type: template
|
|
81
|
+
writes: [docs/09-PLANNING/TASKS/**]
|
|
82
|
+
audit: true
|
|
83
|
+
templates:
|
|
84
|
+
taskPlanAppend: templates/task_plan.append.md
|
|
85
|
+
inputs:
|
|
86
|
+
subject:
|
|
87
|
+
type: text
|
|
88
|
+
flag: --subject
|
|
89
|
+
required: true
|
|
90
|
+
templateValues:
|
|
91
|
+
subject:
|
|
92
|
+
from: inputs.subject
|
|
93
|
+
metadata:
|
|
94
|
+
ReviewSubject:
|
|
95
|
+
label: Review Subject
|
|
96
|
+
from: inputs.subject
|
|
97
|
+
evidence:
|
|
98
|
+
bundleDir: artifacts/preset
|
|
99
|
+
files:
|
|
100
|
+
subject:
|
|
101
|
+
path: subject.txt
|
|
102
|
+
type: text
|
|
103
|
+
value: inputs.subject
|
|
104
|
+
audit:
|
|
105
|
+
manifestRequired: true
|
|
106
|
+
evidenceFiles: [preset-audit.json, preset-manifest.json, write-scope.json]
|
|
107
|
+
writeScopes:
|
|
108
|
+
taskDocs:
|
|
109
|
+
path: docs/09-PLANNING/TASKS/**
|
|
110
|
+
access: write
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
## Reference Bundles
|
|
114
|
+
|
|
115
|
+
Use `resources.references` when a family of tasks shares the same outside context, such as another microservice, API contract, migration packet, reviewer input, or local verification runbook. Harness copies or renders these files into each created task directory, appends `references/INDEX.md` rows, and can add a required-read section to `task_plan.md`.
|
|
116
|
+
|
|
117
|
+
```yaml
|
|
118
|
+
resources:
|
|
119
|
+
references:
|
|
120
|
+
upstreamContract:
|
|
121
|
+
path: references/upstream-contract.md
|
|
122
|
+
template: templates/references/upstream-contract.md
|
|
123
|
+
index:
|
|
124
|
+
id: REF-001
|
|
125
|
+
type: code
|
|
126
|
+
summary: Shared upstream {{service}} contract for every task created by this preset.
|
|
127
|
+
usedBy: coordinator,worker,reviewer
|
|
128
|
+
serviceRunbook:
|
|
129
|
+
path: references/service-runbook.md
|
|
130
|
+
source: resources/service-runbook.md
|
|
131
|
+
index:
|
|
132
|
+
id: REF-002
|
|
133
|
+
type: runbook
|
|
134
|
+
summary: Local verification notes for the shared upstream service.
|
|
135
|
+
usedBy: worker
|
|
136
|
+
context:
|
|
137
|
+
requiredReads: [REF-001, REF-002]
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
Use `template` when the file needs `{{valueName}}` substitution. Use `source` when the file should be copied as static Markdown. `path`, `source`, and `template` must stay inside the preset package and generated task directory boundaries.
|
|
141
|
+
|
|
142
|
+
## Artifact Bundles
|
|
143
|
+
|
|
144
|
+
Use `resources.artifacts` for preset-provided fixtures, generated input packets, or review material that supports the task but is not a reference source of truth. Harness writes these files into the task's `artifacts/` area and appends `artifacts/INDEX.md`.
|
|
145
|
+
|
|
146
|
+
```yaml
|
|
147
|
+
resources:
|
|
148
|
+
artifacts:
|
|
149
|
+
inputPacket:
|
|
150
|
+
path: artifacts/input-packet.md
|
|
151
|
+
source: resources/artifacts/input-packet.md
|
|
152
|
+
index:
|
|
153
|
+
id: ART-001
|
|
154
|
+
type: fixture
|
|
155
|
+
summary: Shared fixture packet copied by the preset.
|
|
156
|
+
producedBy: preset
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
## Template Rendering
|
|
160
|
+
|
|
161
|
+
Templates use `{{valueName}}` placeholders from `templateValues`. `templateValues` and `metadata` support literal `value`, `default`, and dot-path `from` references such as `inputs.subject` or `task.title`; they do not evaluate arbitrary expressions.
|
|
162
|
+
|
|
163
|
+
`metadata` entries render first-class task plan lines such as `Review Subject: API contracts`.
|
|
164
|
+
|
|
165
|
+
```md
|
|
166
|
+
## Custom Review
|
|
167
|
+
|
|
168
|
+
Subject: {{subject}}
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
## Inputs
|
|
172
|
+
|
|
173
|
+
Supported input types:
|
|
174
|
+
|
|
175
|
+
| Type | Use |
|
|
176
|
+
| --- | --- |
|
|
177
|
+
| `text` | Reads a CLI flag value such as `--subject "API"` |
|
|
178
|
+
| `flag` | Reads a boolean CLI flag |
|
|
179
|
+
| `json-file` | Reads and validates a JSON file such as `--from-session session.json` |
|
|
180
|
+
|
|
181
|
+
`json-file` inputs can validate `validateOperation`, reject `planOnly`, require a target path, and route the task target from the JSON session.
|
|
182
|
+
|
|
183
|
+
## Evidence
|
|
184
|
+
|
|
185
|
+
Evidence files are written under the task directory and must match `writeScopes`.
|
|
186
|
+
|
|
187
|
+
Supported evidence types:
|
|
188
|
+
|
|
189
|
+
| Type | Output |
|
|
190
|
+
| --- | --- |
|
|
191
|
+
| `text` | Plain text from a value path |
|
|
192
|
+
| `json` | JSON from a value path |
|
|
193
|
+
| `input-json` | Raw resolved JSON input |
|
|
194
|
+
| `preset-audit` | Manifest audit payload |
|
|
195
|
+
| `preset-manifest` | Manifest snapshot |
|
|
196
|
+
| `write-scope` | Declared write scopes |
|
|
197
|
+
| `migration-verify` | Built-in migrate session verification |
|
|
198
|
+
| `migration-ledger` | Built-in migration phase ledger |
|
|
199
|
+
| `dashboard-hash` | Hash of the migration dashboard snapshot |
|
|
200
|
+
| `target-git-status` | Target Git status from migration session |
|
|
201
|
+
| `target-commit` | Current target commit |
|
|
202
|
+
| `harness-version` | Current package version |
|
|
203
|
+
| `generated-at` | Generation timestamp |
|
|
204
|
+
|
|
205
|
+
## Commands
|
|
206
|
+
|
|
207
|
+
```bash
|
|
208
|
+
harness preset check ./my-preset
|
|
209
|
+
harness preset install ./my-preset
|
|
210
|
+
harness preset install ./my-preset.zip
|
|
211
|
+
harness preset install ./my-preset --project /path/to/project
|
|
212
|
+
harness preset install legacy-migration --force
|
|
213
|
+
harness preset seed
|
|
214
|
+
harness preset seed --project /path/to/project
|
|
215
|
+
harness preset list --json /path/to/project
|
|
216
|
+
harness preset inspect custom-review --json /path/to/project
|
|
217
|
+
harness new-task --title "Custom review task" --preset custom-review --subject "API contracts" /path/to/project
|
|
218
|
+
harness preset uninstall custom-review
|
|
219
|
+
```
|
|
220
|
+
|
|
221
|
+
## Validation Method
|
|
222
|
+
|
|
223
|
+
For every preset, prove both the manifest and downstream task behavior:
|
|
224
|
+
|
|
225
|
+
1. Run `harness preset check ./my-preset`.
|
|
226
|
+
2. Install the folder and, if distributing an archive, install the `.zip` into an isolated HOME or disposable environment.
|
|
227
|
+
3. Create at least one task with `harness new-task --preset`.
|
|
228
|
+
4. For reference bundles, create two different tasks from the same preset and verify both contain the same shared `references/` files and independent audit/evidence bundles.
|
|
229
|
+
5. Run `harness status --json`, `harness task-index --json`, and `harness check --profile target-project <target>`.
|
|
230
|
+
6. Inspect `task_plan.md` to confirm required reads are visible before implementation starts.
|
|
231
|
+
|
|
232
|
+
## Boundaries
|
|
233
|
+
|
|
234
|
+
- Presets cannot write outside declared `writeScopes`.
|
|
235
|
+
- Presets do not run arbitrary JavaScript during `new-task`.
|
|
236
|
+
- Reference bundles are task-local snapshots. If the shared upstream context changes later, create a new preset version or a follow-up task rather than silently mutating historical tasks.
|
|
237
|
+
- Script and check entrypoints may exist in bundled packages, but the task creation path is YAML + templates + built-in processors.
|
|
238
|
+
- Use a new built-in processor only when multiple presets need the same capability and the behavior can be tested centrally.
|
|
@@ -92,7 +92,7 @@ Each repository should document its external boundary in:
|
|
|
92
92
|
|
|
93
93
|
The risk is harness fragmentation:
|
|
94
94
|
|
|
95
|
-
- The frontend
|
|
95
|
+
- The frontend local task state says a task is complete while the backend Regression SSoT is still red.
|
|
96
96
|
- An SDK breaking change is not projected into the product shell.
|
|
97
97
|
- An agent starts from a child repository, sees only local facts, and incorrectly treats the global task as complete.
|
|
98
98
|
|
|
@@ -124,7 +124,8 @@ product-control-repo/
|
|
|
124
124
|
The parent repository is the control plane. It owns:
|
|
125
125
|
|
|
126
126
|
- Overall architecture and repo topology.
|
|
127
|
-
- Cross-repo
|
|
127
|
+
- Cross-repo task lifecycle Ledger.
|
|
128
|
+
- Delivery SSoT when release or block orchestration is needed.
|
|
128
129
|
- Task plans, reviews, and walkthroughs.
|
|
129
130
|
- Regression SSoT and cross-repo cadence.
|
|
130
131
|
- Agent entrypoint and reading matrix.
|
|
@@ -152,7 +153,7 @@ The parent-control model fixes global truth in one place. Even if there are 100
|
|
|
152
153
|
|
|
153
154
|
This avoids:
|
|
154
155
|
|
|
155
|
-
- Conflicting
|
|
156
|
+
- Conflicting handwritten task lifecycle tables.
|
|
156
157
|
- Each child repo saying "done" while the release still cannot ship.
|
|
157
158
|
- Agents starting from the wrong repository and seeing only local context.
|
|
158
159
|
- Cross-repo review and regression evidence scattered across many places.
|
|
@@ -179,7 +180,7 @@ If cross-repo features remain common, create a parent-control repository.
|
|
|
179
180
|
Migration order:
|
|
180
181
|
|
|
181
182
|
1. Create the parent `AGENTS.md` and repo topology.
|
|
182
|
-
2. Move global
|
|
183
|
+
2. Move global Harness Ledger, Delivery SSoT, Regression SSoT, and walkthrough index into the parent repository.
|
|
183
184
|
3. Keep local `AGENTS.md` files in child repositories, but point global planning back to the parent.
|
|
184
185
|
4. Create new cross-repo tasks only in the parent repository.
|
|
185
186
|
5. Treat child repository commits as evidence for parent tasks.
|
|
@@ -92,7 +92,7 @@ sdk-repo/
|
|
|
92
92
|
|
|
93
93
|
多仓独立模式的风险是 Harness 分裂:
|
|
94
94
|
|
|
95
|
-
-
|
|
95
|
+
- 前端局部任务状态认为任务完成,后端 Regression SSoT 仍是红灯。
|
|
96
96
|
- SDK 的 breaking change 没有投影到产品 shell。
|
|
97
97
|
- Agent 从子仓库启动后,只看到局部事实,误以为全局任务已经结束。
|
|
98
98
|
|
|
@@ -124,7 +124,8 @@ product-control-repo/
|
|
|
124
124
|
父仓库是 control plane。它管理:
|
|
125
125
|
|
|
126
126
|
- 总体架构和 repo topology。
|
|
127
|
-
-
|
|
127
|
+
- 跨仓任务生命周期 Ledger。
|
|
128
|
+
- Delivery SSoT(需要 release / block 编排时)。
|
|
128
129
|
- 任务计划、review、walkthrough。
|
|
129
130
|
- Regression SSoT 和跨仓 cadence。
|
|
130
131
|
- Agent 启动入口和读文件矩阵。
|
|
@@ -152,7 +153,7 @@ product-control-repo/
|
|
|
152
153
|
|
|
153
154
|
这能避免:
|
|
154
155
|
|
|
155
|
-
-
|
|
156
|
+
- 多个手写任务生命周期表互相冲突。
|
|
156
157
|
- 每个子仓库都声称自己已经完成,但 release 仍不能发。
|
|
157
158
|
- Agent 从错误仓库启动,只看到局部上下文。
|
|
158
159
|
- 跨仓 review 和 regression 证据散落在不同地方。
|
|
@@ -179,7 +180,7 @@ product-control-repo/
|
|
|
179
180
|
迁移顺序:
|
|
180
181
|
|
|
181
182
|
1. 创建父仓库 `AGENTS.md` 和 repo topology。
|
|
182
|
-
2. 把全局
|
|
183
|
+
2. 把全局 Harness Ledger、Delivery SSoT、Regression SSoT、walkthrough index 收到父仓库。
|
|
183
184
|
3. 子仓库保留局部 `AGENTS.md`,但把全局计划指向父仓库。
|
|
184
185
|
4. 新跨仓任务只在父仓库创建 task。
|
|
185
186
|
5. 子仓库提交只作为父任务的 evidence。
|