ai-dev-harness 0.1.0 → 0.1.1

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.
Files changed (32) hide show
  1. package/COLLEAGUE_TRIAL_GUIDE.md +147 -0
  2. package/README.md +116 -52
  3. package/dist/agent.js +44 -31
  4. package/dist/cli.js +65 -42
  5. package/dist/config.js +79 -8
  6. package/dist/context.js +53 -21
  7. package/dist/init.js +8 -20
  8. package/dist/integration.js +22 -91
  9. package/dist/mcp.js +29 -112
  10. package/dist/runPaths.js +1 -0
  11. package/dist/summarize.js +42 -39
  12. package/dist/templates.js +39 -215
  13. package/package.json +3 -1
  14. package/scripts/read-evidence.ps1 +9 -3
  15. package/scripts/run-harness.ps1 +8 -5
  16. package/templates/default-project/AGENTS.md +9 -0
  17. package/templates/default-project/SKILLS.md +13 -0
  18. package/templates/default-project/TOOLS.md +8 -0
  19. package/templates/default-project/skills/add_feature/SKILL.md +34 -0
  20. package/templates/default-project/skills/add_feature/context.yaml +30 -0
  21. package/templates/default-project/skills/add_feature/verify.yaml +2 -0
  22. package/templates/default-project/skills/fix_bug/SKILL.md +45 -0
  23. package/templates/default-project/skills/fix_bug/context.yaml +30 -0
  24. package/templates/default-project/skills/fix_bug/verify.yaml +2 -0
  25. package/templates/default-project/skills/update_docs/SKILL.md +28 -0
  26. package/templates/default-project/skills/update_docs/context.yaml +26 -0
  27. package/templates/default-project/skills/update_docs/verify.yaml +2 -0
  28. package/templates/default-project/skills/write_tests/SKILL.md +30 -0
  29. package/templates/default-project/skills/write_tests/context.yaml +29 -0
  30. package/templates/default-project/skills/write_tests/verify.yaml +2 -0
  31. package/templates/integrations/claude/SKILL.md +79 -0
  32. package/templates/integrations/codex/AGENTS_BLOCK.md +51 -0
package/templates/integrations/claude/SKILL.md ADDED
@@ -0,0 +1,79 @@
1
+ ---
2
+ name: ai-dev-harness
3
+ description: 从 Claude Code 对话中触发可审计的 AI Dev Harness CLI，并在当前对话中展示 Harness 执行过程。
4
+ ---
5
+
6
+ # AI Dev Harness
7
+
8
+ 当用户要求使用 Harness、AI Dev Harness、可审计执行、CodeGraph/Knowledge Graph 上下文，或要求执行 `fix_bug`、`add_feature`、`write_tests`、`update_docs` 这些技能时，使用本 Skill。
9
+
10
+ ## Agent MCP Preflight
11
+
12
+ 运行 Harness 命令前，优先使用 Claude Code 已配置的 MCP 工具：
13
+
14
+ - 使用 CodeGraph MCP 检查相关文件、符号、依赖、调用方和影响范围。
15
+ - 使用 Knowledge Graph MCP 检查 ADR、模块说明、接口说明、历史决策和 runbook。
16
+ - 在当前对话中先总结 MCP 发现，再调用 Harness。
17
+ - 把关键 MCP 发现带入 Harness 的任务文本，让审计记录保留决策上下文。
18
+
19
+ 请使用以下预检总结格式：
20
+
21
+ ```text
22
+ ## MCP Preflight Findings
23
+ - CodeGraph tools used:
24
+ - Related files:
25
+ - Related symbols:
26
+ - Callers / dependencies:
27
+ - Impact scope:
28
+ - Knowledge Graph tools used:
29
+ - ADRs / decisions:
30
+ - Module notes:
31
+ - API notes / runbooks:
32
+ - Missing context:
33
+ ```
34
+
35
+ 不要在 Harness 内部实现单独的 MCP transport。SSE MCP 访问属于 Claude Code 的 MCP 客户端能力。
36
+
37
+ ## Harness Command
38
+
39
+ MCP preflight 完成后，在仓库根目录运行：
40
+
41
+ ```bash
42
+ powershell -ExecutionPolicy Bypass -File ".harness/ai-dev-harness/scripts/run-harness.ps1" -Task "<task>" -Skill <skill> -Agent claude -Live
43
+ ```
44
+
45
+ 兜底直接命令：
46
+
47
+ ```bash
48
+ {{HARNESS_COMMAND}} run --task "<task>" --skill <skill> --agent claude --live
49
+ ```
50
+
51
+ ## Skill Mapping
52
+
53
+ - 缺陷或回归问题：`fix_bug`
54
+ - 范围明确的功能：`add_feature`
55
+ - 添加或改进测试：`write_tests`
56
+ - 只读分析或文档：`update_docs`
57
+
58
+ 只读分析时，在任务里明确写入：“Do not modify repository files”。
59
+
60
+ ## 过程汇报
61
+
62
+ 命令执行期间和结束后，在当前对话中报告：
63
+
64
+ - 使用了哪些 MCP 工具，以及关键上下文发现。
65
+ - Harness live output 中当前可见的生命周期阶段。
66
+ - Harness 打印的证据目录。
67
+ - `summary.md`
68
+ - `verify.json`
69
+ - `agent_contract.json`
70
+ - `audit.jsonl`
71
+ - MCP 工具不可用或上下文缺失情况。
72
+
73
+ 必要时可读取证据：
74
+
75
+ ```bash
76
+ powershell -ExecutionPolicy Bypass -File ".harness/ai-dev-harness/scripts/read-evidence.ps1" -Run <run_id_or_path>
77
+ ```
78
+
79
+ 除非用户明确要求直接手工处理，否则实现类任务不要绕过 Harness。
package/templates/integrations/codex/AGENTS_BLOCK.md ADDED
@@ -0,0 +1,51 @@
1
+ ## AI Dev Harness
2
+
3
+ 当用户要求使用 Harness、可审计执行、CodeGraph/Knowledge Graph 辅助研发，或要求执行以下技能时，使用 AI Dev Harness CLI：
4
+
5
+ - `fix_bug`
6
+ - `add_feature`
7
+ - `write_tests`
8
+ - `update_docs`
9
+
10
+ 运行 Harness 前，优先使用 Codex 已配置的 MCP 工具：
11
+
12
+ - 查询 CodeGraph MCP，获取相关文件、符号、依赖、调用方和影响范围。
13
+ - 查询 Knowledge Graph MCP，获取 ADR、模块说明、接口说明、历史决策和 runbook。
14
+ - 在当前对话中简要报告 MCP 发现。
15
+ - 把关键发现带入 Harness 的任务文本，让审计记录保留上下文。
16
+
17
+ 请使用以下预检总结格式：
18
+
19
+ ```text
20
+ ## MCP Preflight Findings
21
+ - CodeGraph tools used:
22
+ - Related files:
23
+ - Related symbols:
24
+ - Callers / dependencies:
25
+ - Impact scope:
26
+ - Knowledge Graph tools used:
27
+ - ADRs / decisions:
28
+ - Module notes:
29
+ - API notes / runbooks:
30
+ - Missing context:
31
+ ```
32
+
33
+ 不要在 Harness 内部实现或期待 SSE MCP transport。SSE MCP 访问属于 Codex MCP 客户端能力。
34
+
35
+ MCP preflight 完成后，在仓库根目录运行：
36
+
37
+ ```bash
38
+ powershell -ExecutionPolicy Bypass -File ".harness/ai-dev-harness/scripts/run-harness.ps1" -Task "<task>" -Skill <skill> -Agent codex -Live
39
+ ```
40
+
41
+ 兜底直接命令：
42
+
43
+ ```bash
44
+ {{HARNESS_COMMAND}} run --task "<task>" --skill <skill> --agent codex --live
45
+ ```
46
+
47
+ 只读分析时，在任务里明确写入 “Do not modify repository files”，通常使用 `update_docs`。
48
+
49
+ 每次 Harness 运行期间和结束后，报告可见生命周期进度、证据目录、`summary.md`、`verify.json`、`agent_contract.json`、`audit.jsonl`，以及 MCP 工具不可用或上下文缺失情况。
50
+ 需要时使用 `.harness/ai-dev-harness/scripts/read-evidence.ps1` 打印证据摘要。
51
+ v1 不直接写入 Knowledge Graph；使用 `persist_suggestions.md`。