Ecl Harness Engineer

ECL Harness 工程师

设计并创建 Harness 工程基础设施，使 AI 智能体能够在代码库中可靠工作。

核心理念："没有基础设施的智能，只是一个演示。"Agent Harness 是操作系统 —— LLM 只是 CPU。仓库成为唯一的真相之源 —— 如果智能体在上下文中看不到它，它就不存在。

何时使用本技能

• 当仓库需要 AI 智能体协作基础设施（例如 AGENTS.md、docs/ECL.md、docs/STATUS.md、harness 变更追踪，或机械验证闸门）时使用。
• 当审计现有 Agent Harness 是否缺少 ECL 生命周期文档、变更模板、lint 检查、环境契约或 CI 集成时使用。
• 当把重复的智能体工作流失败转化为仓库本地文档、测试、lint 规则或轻量级自动演化检查时使用。
• 不要用于普通的业务功能实现，除非请求的工作专门涉及创建或改进仓库 harness。

限制

• 本技能用于创建或审计 harness 基础设施；它不能替代目标项目的产品需求、实施规划、代码审查或发布批准。
• 生成的 ECL 文档、linters、脚本和 CI 示例必须先适配仓库的实际技术栈、安全模型和现有贡献者工作流，再强制执行。
• 自动演化建议仅为指导。请通过正常的审查、验证和回滚规范应用 harness 变更，而不是将其作为自主策略变更接受。

统一工作流

本技能遵循单一统一工作流，无论项目状态如何（空仓库、已有代码或已有 harness）。核心理念：检测当前状态与目标状态之间的差距，然后填补它。

默认采用核心 ECL harness。核心包含轻量级自动演化阈值检查： 统计已关闭的变更数量，达到阈值时生成待演化提示， 且 Codex 仅通过证据、验证、评分和回滚来应用 harness 改进。 智能体平台的高级能力（如 eval 数据集、执行追踪、持久状态、 检查点、长期记忆和指标）仅在用户明确要求 智能体评估、可观测性、可恢复执行或长期记忆时作为可选 profile 启用。

本技能改进目标仓库的智能体 harness。它不实现普通 业务功能，不替代编码智能体的规划模式，也不创建独立的需求产品。 规划模式适用于实时讨论；ECL 工件是仓库记录，后续智能体、 linters、CI 和归档历史可以查阅。

1. 快速检测 + 意图确认 — 了解现有内容、已通过的检查以及用户期望。
2. 分析 — 架构、harness 状态、环境和项目身份。
3. 入口审查 + 差异合成 — 区分小型工作与结构化工作，支持需求优先 和计划优先输入，并精确计算要创建或更新的内容。
4. 创建/更新 — 文档、状态交接、linters、ECL/变更脚本、环境配置和 CI。
5. 验证 + 交接 — 运行检查，归因失败原因，更新 STATUS.md，触发自动演化检查，并总结结果。

阶段 1：快速检测 + 意图确认

目标：在 5 分钟内理解项目状态和用户意图。

1.1 项目状态检测

运行此快速扫描：

# 统计文件
file_count=$(find . -type f ! -path './.git/*' ! -path './node_modules/*' ! -path './vendor/*' 2>/dev/null | wc -l)
code_files=$(find . -type f \( -name "*.go" -o -name "*.ts" -o -name "*.js" -o -name "*.py" -o -name "*.rs" \) ! -path './.git/*' ! -path './node_modules/*' ! -path './vendor/*' 2>/dev/null | wc -l)

# 检查 harness 组件
has_agents_md=$(test -f AGENTS.md && echo "yes" || echo "no")
has_architecture=$(test -f docs/ARCHITECTURE.md && echo "yes" || echo "no")
has_linters=$(ls scripts/lint-* 2>/dev/null | wc -l)
has_harness_dir=$(test -d harness && echo "yes" || echo "no")
has_ecl_doc=$(test -f docs/ECL.md && echo "yes" || echo "no")
has_changes_dir=$(test -d harness/changes && echo "yes" || echo "no")
has_change_templates=$(test -d harness/templates/change && echo "yes" || echo "no")
has_change_script=$(ls scripts/harness-change.* 2>/dev/null | wc -l)
has_evolve_script=$(ls scripts/harness-evolve.* 2>/dev/null | wc -l)
has_ecl_lint=$(ls scripts/lint-ecl.* 2>/dev/null | wc -l)
has_encoding_lint=$(ls scripts/lint-encoding.* 2>/dev/null | wc -l)
has_makefile=$(test -f Makefile && echo "yes" || echo "no")
has_package_json=$(test -f package.json && echo "yes" || echo "no")

# 检测技术栈
if test -f go.mod; then TECH="Go"
elif test -f package.json; then TECH="TypeScript/Node.js"
elif test -f requirements.txt || test -f pyproject.toml; then TECH="Python"
else TECH="Unknown"
fi

1.2 项目状态分类

基于检测结果：

同时分类 ECL 就绪度：

1.3 基线验证快照

对于已有项目，在创建或更新 harness 文件之前捕获尽力而为的基线。 该基线仅用于归因：它将预先存在的项目失败与 harness 工作引入的失败区分开。它不得用于削弱默认 CI。

仅运行项目中已存在的命令：

将每个命令记录为 pass、fail 或 missing，并附上简短的失败原因。如果某命令 在 harness 创建前失败，稍后将其报告为预先存在的项目债，而不是 harness 失败。默认 CI 仍然严格，除非用户 明确要求临时分阶段发布，否则仍应包含正常的业务闸门。

1.4 意图确认

在规划变更之前，对请求范围进行分类：

当用户确认工具可用时，确认范围。在 Codex 中，使用 request_user_input。 在其他平台上，使用等效的用户选择工具。如果没有此类工具，请使用 检测到的上下文并记录假设。

{
  "question": "What's your priority for this harness setup?",
  "header": "Scope",
  "multiSelect": false,
  "options": [
    {
      "label": "Core harness (Recommended)",
      "description": "Project-first AGENTS.md, ECL changes, STATUS handoff, auto-evolve threshold checks, linters, environment contract, and strict CI"
    },
    {
      "label": "Advanced harness",
      "description": "Core harness plus explicitly requested eval, trace, memory, checkpoint, or metrics infrastructure"
    },
    {
      "label": "Documentation only",
      "description": "AGENTS.md and project docs only; skip linters, scripts, and CI for now"
    }
  ]
}

如果为空仓库，还要询问基础信息：

{
  "question": "What tech stack for this project?",
  "header": "Tech Stack",
  "multiSelect": false,
  "options": [
    {"label": "Go", "description": "CLI tools, high-performance services, system programming"},
    {"label": "TypeScript/Node.js", "description": "Web APIs, full-stack apps, rapid prototyping"},
    {"label": "Python", "description": "Data processing, ML/AI, scripting"}
  ]
}

如果没有用户确认工具可用，请使用检测到的值并记录假设：

## Auto-Detected Context

| Field | Value | Confidence | Evidence |
|-------|-------|------------|----------|
| Tech Stack | {TECH} | High | Found {config file} |
| Project State | {state} | High | {criteria matched} |
| Scope | Core harness | Default | No user preference specified |

Proceeding with these assumptions. Tell me if any need adjustment.

1.5 ECL 工作入口规则

在为目标项目生成 ECL 指导时，保持流程足够小以方便使用：

决策树：

1. 如果已存在激活的变更，继续使用它；不要创建第二个激活上下文。
2. 如果变更是复制、注释、README 文本、格式，或显然的本地单文件修复 且没有运行时、API、数据、权限、架构或验证链影响，则视为小型变更。
3. 如果变更涉及 API、数据、权限、架构、多模块、发布/运行时 行为或不清晰的需求，则视为结构化变更。
4. 如果影响不明确，首先进行只读调查。如果检查后仍有不确定性， 询问一个高影响力问题或升级为结构化变更；不要假设是小型变更。

对于结构化变更，支持两种常见入口：

• 需求优先输入：将目标用户/场景、证据、成功标准、 验收标准、非目标、约束、假设和风险提取到 spec.md。
• 计划优先输入：将用户计划视为草稿，将 WHAT/WHY 拆分到 spec.md，将 HOW 拆分到 plan.md，然后只询问影响实施方向或验收的高影响力空白。 如果计划完整且不与仓库证据冲突，不要重复完整 访谈。如果它与代码、文档、命令或现有 harness 约束冲突，请记录 冲突并返回到入口审查。

问题允许且预期，但必须有界：每轮最多询问三个高影响力问题。低风险未知项变成假设；高影响力未知项变成 [NEEDS CLARIFICATION: ...] 并阻塞实施，直至解决。

对于复杂的结构化变更，使用轻量级迭代循环，而不是将第一个 规范视为最终：

Draft Spec -> Draft Plan -> Review Gaps -> Revise Spec/Plan -> Gate -> Tasks

默认最多两个循环。如果关键空白仍然存在，继续最多五个循环；之后，记录一个 阻塞器而不是从猜测中实施。plan.md 必须包含任何规划中发现的规范 空白，因为计划经常暴露缺失的验收、边界、权限、数据或验证 要求。

阶段 2：分析

目标：深入理解代码库架构、harness 状态和环境要求。

2.1 执行模式

仅当用户授权委托且环境支持时使用子智能体。否则，内联执行相同的职责。

如果使用子智能体，分配：

• 代码架构分析：遵循 agents/analyzer.md；输出 harness/.analysis/architecture.json。
• Harness 状态审计：遵循 agents/auditor.md；输出 harness/.analysis/audit.json。
• 环境分析：遵循 references/environment-detection-guide.md；输出 harness/.analysis/environment.json。

如果内联工作，则在阶段 3 之前产生相同的三个分析工件或等效的内存摘要。

2.2 项目身份提取

对于已有项目，在编写文档之前提取目标项目含义：

• 一句话项目身份：它做什么，为谁做。
• 核心工作流或领域模型：用户/系统流程、关键实体、API 资源、作业或命令。
• 主要源代码入口以及常见变更所属的位置。

使用 README.md、清单、入口点、路由/控制器、模式/模型和关键源 目录。Harness 文件不足以作为项目身份的证据。

2.3 适配器选择

检测到技术栈后，在创建 linters、脚本、CI 或 环境配置之前加载匹配的适配器。适配器指导覆盖特定语言的通用模板。

对于 TypeScript/Node.js 项目，优先使用 Node/TS 原生输出：scripts/lint-deps.mjs 或 等效文件，scripts/lint-quality.mjs、npm/包管理器脚本，以及 Node/TS GitHub Actions。 除非项目实际上是 Go 或已经将 Makefile 作为主要命令界面，否则不要将 Go linter 或仅 Makefile 模式适配到 TypeScript。

2.4 命令界面选择

在创建 ECL 脚本之前，选择目标项目的命令界面。不要假设 PowerShell 是唯一的 Windows 选项。该选择通常是自动的；除非项目证据冲突或用户已表达硬性约束，否则不要要求用户 选择脚本格式。

优先级：

1. 现有项目入口点：包管理器脚本、Makefile 目标、README 命令， 或 CI shell 约定。
2. 明确的用户/项目约束。如果项目拒绝 .ps1，不要将 PowerShell 作为唯一的 harness 入口点。
3. 允许时的 Bash profile。对于接受 Bash 的 Windows 项目，生成 .sh 脚本并 记录先决条件：Git Bash、WSL、MSYS2 或 CI Linux runner。
4. 当项目接受 Windows 原生 PowerShell 时的 PowerShell profile。保持与 Windows PowerShell 5.1 和 PowerShell 7 兼容。
5. 当这些运行时已经是项目的一等依赖时使用 Node 或 Python profiles。

当证据稀缺时的默认：对于 TypeScript/Node 项目选择 Node/包管理器脚本； 对于允许 Bash 的 Windows 项目选择 Bash profile 并记录 Git Bash/WSL/MSYS2；否则 选择适配器的原生轻量级脚本 profile。

所有 profiles 必须实现相同的 ECL 不变量和命令集。harness-change、 harness-evolve、lint-ecl 和 lint-encoding 可以实现为 .ps1、.sh、.mjs、 或 .py，但文档、CI、Makefile/package 脚本和验证命令必须一致地使用所选 入口点。

2.5 等待分析完成

当子智能体运行时，等待它们的最终报告。等待期间，你可以：

• 审查任何现有文档
• 为阶段 4 准备模板

2.5 针对空项目

跳过阶段 2 的分析智能体。而是：

• 使用 references/greenfield-templates.md 中的模板
• 根据用户的技术栈选择做出决策
• 设计标准的 3 层架构

阶段 3：差异合成

目标：合并分析结果并精确计算需要创建/更新的内容。

3.1 读取分析结果

cat harness/.analysis/architecture.json
cat harness/.analysis/audit.json
cat harness/.analysis/environment.json

3.2 计算差异

创建差异列表：

## Delta: What Needs to Be Done

### Core To Create (doesn't exist)
- [ ] AGENTS.md
- [ ] docs/ECL.md
- [ ] docs/STATUS.md
- [ ] docs/ARCHITECTURE.md
- [ ] scripts/lint-deps.go
- [ ] scripts/harness-change.{ps1|sh|mjs|py}
- [ ] scripts/harness-evolve.{ps1|sh|mjs|py}
- [ ] scripts/lint-ecl.{ps1|sh|mjs|py}
- [ ] scripts/lint-encoding.{ps1|sh|mjs|py}
- [ ] harness/changes/{active,parking,archive}
- [ ] harness/templates/change/
- [ ] harness/config/environment.json
- [ ] harness/evolution/{state.json,results.tsv,proposals/} (`pending.md` is generated later only when the archive threshold is reached)

### Optional Advanced (only if explicitly requested)
- [ ] harness/eval/ — agent evaluation datasets and runner inputs
- [ ] harness/trace/ — execution traces for agent runs
- [ ] harness/state/ — executor runtime state
- [ ] harness/checkpoints/ — resumable execution checkpoints
- [ ] harness/memory/ — long-term agent memory experiments
- [ ] harness/metrics/ — execution and quality metrics

### To Update (exists but has gaps)
- [ ] docs/DEVELOPMENT.md — missing build commands
- [ ] scripts/lint-quality.py — missing 3 packages in layer map

### Already Good (no changes needed)
- [x] Makefile — has all required targets
- [x] .github/workflows/ci.yml — properly configured

3.3 与用户确认（如确认工具可用）

对于重大变更：

{
  "question": "I've analyzed the codebase. Ready to proceed with these changes?",
  "header": "Confirm",
  "multiSelect": false,
  "options": [
    {"label": "Yes, proceed with all", "description": "Create/update all identified items"},
    {"label": "Show me the details first", "description": "I'll explain what each change involves"},
    {"label": "Only critical items", "description": "Just P0/P1 items, skip P2/P3 for now"}
  ]
}

阶段 4：创建/更新

目标：从差异中创建或更新所有 harness 文件。

4.1 执行模式

仅当授权并可用时使用子智能体。否则，内联执行相同的工作。如果使用并行 worker，保持写入作用域不相交。

创建职责：

• 文档：遵循 agents/creator-docs.md；创建/更新 AGENTS.md、docs/ECL.md、docs/STATUS.md、docs/ARCHITECTURE.md、docs/DEVELOPMENT.md 和设计文档。AGENTS.md 是目标项目的入口映射，而不是 harness 创建记录。保持首屏以项目为主，但在上下文加载中保留 ECL/当前变更优先级：AGENTS.md -> docs/ECL.md -> 激活变更（如果存在）-> 自动演化待办（如果存在）-> 否则 docs/STATUS.md -> 任务特定的项目文档。
• Linters：遵循 agents/creator-linters.md；创建/更新依赖、质量、ECL 和编码检查。
• 配置和脚本：遵循 agents/creator-config.md；创建/更新环境契约、harness 脚本、变更目录/模板、轻量级演化状态、harness-change、harness-evolve、Makefile 目标和 CI。仅当确认的范围需要时才创建高级目录。

ECL 变更模板必须包含 summary.md、spec.md、plan.md、tasks.md 和 reviews/review.md。spec.md 捕获 WHAT/WHY，plan.md 捕获 HOW 和规划中发现的规范空白，且 tasks.md 仅在规范/计划闸门足够好以实施后才生成。不要要求旧的归档变更包含 plan.md；兼容性适用于历史。

重要：不要创建静态验证配置，例如 harness/config/verify.json。验证计划由执行器在运行时从 environment.json 和任务上下文生成。

严格的 CI 规则：默认 CI 必须包含正常的业务质量闸门（lint、typecheck、test、 build，以及后端/包特定的等价物，当可用时）加上 harness 检查。不要移除 或跳过业务闸门，因为基线已经是红色。如果基线已经为红色，请说明 CI 将保持红色，直到预先存在的项目问题被修复。仅当用户明确要求时，才生成分阶段或宽松的 CI。

命令界面规则：为选定的 profile 创建 ECL 脚本，而不是硬编码 shell。如果在 Windows 上选择 Bash，请在生成的环境/开发文档中记录 Git Bash、WSL、MSYS2 或 CI Linux shell 要求。如果选择 PowerShell，请检测 pwsh 是否可用；如果不可用， 使用 powershell -NoProfile -ExecutionPolicy Bypass。PowerShell 模板必须与 Windows PowerShell 5.1 兼容：避免像 TrimStart(".\") 这样的歧义重载，并避免非 ASCII 乱码标记字符串字面量在 .ps1 中；用 Unicode 码点或其他 PS5 安全的构造表示标记。

4.2 对于空项目：还创建业务代码计划

对于空项目，添加一个更多智能体：

Agent("create-exec-plan", prompt="""
Create execution plan for business code (harness-executor will implement this):

Tech stack: {TECH}
Project type: {from user choice}
Architecture: 3-layer (Types → Core → Entry Points)

Create: docs/exec-plans/active/bootstrap-code.md

Contents:
- Full source code for initial project structure
- main.go/index.ts/main.py entry point
- Basic types and core logic
- Test files

This is for harness-executor to implement — not ecl-harness-engineer's responsibility.
""")

4.3 等待创建完成

智能体将在完成时通知。收集它们遇到的任何问题。

阶段 5：验证 + 交接

目标：确保一切正常工作，然后交接或呈现结果。

5.1 运行验证

# 0. 与基线快照进行比较
# 重新运行在阶段 1 中捕获的相同现有 lint/typecheck/test/build 命令。

# 1. Harness 检查通过
make verify-harness || npm run lint:harness || {generated_harness_lint_command}

# 2. 架构 linters 通过
make lint-arch || npm run lint:arch

# 3. 业务构建/测试闸门运行
go build ./... || npm run build || python -m compileall .

# 4. AGENTS.md 大小检查
wc -l AGENTS.md  # Should be 80-120 lines

# 4b. AGENTS.md 内容闸门
# 确认它解释了项目身份、核心工作流/领域模型、源代码入口、
# 基于任务的验证、激活变更优先于 STATUS 的加载，并且不包含
# ECL Harness Engineer 内部边界语言。

# 5. 所有预期文件存在
test -f AGENTS.md && echo "✓ AGENTS.md"
test -f docs/ARCHITECTURE.md && echo "✓ ARCHITECTURE.md"
test -f docs/ECL.md && echo "✓ ECL.md"
test -f docs/STATUS.md && echo "✓ STATUS.md"
test -f scripts/lint-deps* && echo "✓ lint-deps"
test -f scripts/harness-change.* && echo "✓ harness-change"
test -f scripts/lint-ecl.* && echo "✓ lint-ecl"
test -f scripts/harness-evolve.* && echo "✓ harness-evolve"
test -d harness/ && echo "✓ harness/"
test -d harness/changes && echo "✓ harness/changes"
test -f harness/evolution/state.json && echo "✓ evolution state"

# 6. 设计文档存在（不仅仅是索引）
find docs/design-docs -name "*.md" ! -name "index.md" | wc -l

对每个验证结果进行分类：

AGENTS.md 内容闸门：

• 新智能体可以在 30 秒内了解项目做什么。
• 核心产品/系统工作流或领域模型可见。
• 主要源代码入口和任务到目录的映射可见。
• 验证指南映射到任务类型。
• 上下文加载首先读取 docs/ECL.md，然后在存在时读取激活变更。
• 如果没有激活变更且 harness/evolution/pending.md 存在，则在 docs/STATUS.md 之前读取它，将其提为待维护，除非 用户已优先处理当前任务，否则询问是否立即处理。读取或询问不会启动自动演化，且必须 不阻塞普通用户工作。
• 如果没有激活变更且没有待演化，则上下文加载在任务特定的项目文档之前读取 docs/STATUS.md。
• 对于结构化工作，docs/ECL.md 解释小型变更与结构化变更、有界入口 审查、计划优先输入处理以及规范/计划审查闸门。
• 归档历史通过 docs/STATUS.md 路径或 harness/changes/INDEX.json 选择性加载，从历史 summary.md 开始。
• 没有技能内部边界泄漏，例如描述本技能自身范围限制作为目标项目规则的章节或句子。

5.2 STATUS.md 交接更新

当目标项目使用 ECL 变更时，将 docs/STATUS.md 维护为轻量级交接文件。 它在存在激活变更时不是权威的，但在激活变更关闭后它成为默认的近期历史 入口点。

关闭变更交接协议：

1. 在运行 harness-change close 之前，读取激活变更 summary.md、spec.md、 plan.md、tasks.md 和相关的 reviews/；更新 docs/STATUS.md，包括已完成的工作、 验证结果、剩余风险和下一个推荐的恢复点。
2. 运行 close 命令，使激活变更移动到 harness/changes/archive/... 且 harness/changes/INDEX.json 被重建。
3. 关闭后，使用最终的归档路径再次更新 docs/STATUS.md，通常指向 归档的 summary.md。
4. 运行 harness lint 命令（npm run lint:harness、make verify-harness，或生成的 ECL lint 命令）以确认 STATUS、ECL 结构和 INDEX 状态一致。

钩子和 CI 可以验证 docs/STATUS.md，但不得自动写入它或移动变更。

5.3 自动演化检查

核心 harness 默认包含轻量级自动演化。脚本层仅检测 是否有足够的新归档证据，并写入 harness/evolution/pending.md；Codex 执行 语义改进过程。

触发模型：harness-change close 和 reindex 运行 harness-evolve check；new 仅在待办存在时提醒。 钩子和 CI 可以警告，但不得修改文档、脚本、STATUS 或变更。 生成的脚本不调用子智能体。它们仅统计归档证据并创建待办 上下文。当没有激活变更且 Codex 注意到待维护时，除非 用户已优先处理当前任务，否则应询问用户是否立即处理。询问不会启动 待演化。

harness/evolution/pending.md 是维护提醒，不是硬锁。读取它用于上下文 不会启动待演化。当 Codex 创建或使用 auto-evolve-harness-* 变更、写入演化提案/结果或根据待办 证据编辑 Harness 文件时，待演化开始。一旦开始，使用提案、一个 harness/evolution/results.tsv 行和 harness-evolve mark-complete 完成；否则停车或关闭阻塞，而不是已完成。

仅应用通过审查的最小证据支持差异。没有独立评分者 = 没有自动应用：用户批准处理待办意味着当环境支持时，有权请求独立 审计/子智能体。如果环境仍需要明确授权，请询问一次。如果评分不可用、被拒绝或询问后仍未获得授权， 记录 noop 和 eval_mode=dry_run，保留提案，运行 mark-complete，然后停止。 机制修复 （harness-evolve、待办模板、lint）本身不通过完成待演化；修复后， 仍评估候选归档或留下工作停车/阻塞。

详细的提案格式、评分权重、状态值和复杂度预算位于 references/ecl-harness.md。

5.4 呈现摘要

## Harness Infrastructure Complete

**Project**: {project-name}
**Tech Stack**: {TECH}
**Files Created/Updated**: {count}

### Created Files
- AGENTS.md ({N} lines)
- docs/ARCHITECTURE.md
- docs/ECL.md
- docs/STATUS.md
- docs/DEVELOPMENT.md
- docs/design-docs/{component}.md
- scripts/lint-deps.{ext}
- scripts/lint-quality.{ext}
- scripts/harness-change.{ps1|sh|mjs|py}
- scripts/lint-ecl.{ps1|sh|mjs|py}
- scripts/lint-encoding.{ps1|sh|mjs|py}
- scripts/harness-evolve.{ps1|sh|mjs|py}
- harness/config/environment.json
- harness/changes/
- harness/evolution/
- harness/templates/change/
- Makefile

### Verification Results
- Harness checks: ✓
- Architecture checks: ✓
- Business gates: ✓ or pre-existing failures listed below
- AGENTS.md size: ✓ ({N} lines)

### Pre-existing Project Failures
- {List baseline-red commands and short reasons, or "None observed."}

### New Regressions Introduced By Harness
- {List commands that passed before and failed after, or "None observed."}

### Next Steps
{For empty projects: "Run harness-executor to implement business code from docs/exec-plans/active/bootstrap-code.md"}
{For existing projects: "The harness is ready. AI agents can now use AGENTS.md as their entry point."}

5.5 自动交接（对于空项目）

如果这是一个带有 bootstrap exec-plan 的空项目，则调用 harness-executor：

Skill(skill="harness-executor")

上下文："实现位于 docs/exec-plans/active/bootstrap-code.md 的 bootstrap exec-plan"

核心原则

1. 仓库作为唯一真相之源

智能体无法访问 Slack、Google Docs 或部落知识。如果它不在仓库中，它对智能体就不存在。

2. AGENTS.md 是地图，不是手册

保持 80-120 行。链接到详细文档，不要嵌入它们。

3. 机械地强制不变量

Linter 错误必须是智能体可操作的：

✗ BAD: "Forbidden import in core/types/user.go"

✓ GOOD: "core/types/user.go:15 imports core/config (layer 0 → layer 2).
         Layer 0 packages must have NO internal dependencies.

         Fix options:
         1. Move config-dependent logic to a higher layer
         2. Pass the config value as a parameter
         3. Use dependency injection via an interface"

4. 构建以删除

每个组件都应该是可替换的。昨天需要复杂流水线的功能明天可能只是一个提示。

5. 从简单开始

原子化、有据可查的工具 > 复杂的智能体编排。不要过度工程化。

6. 变更状态是显式的

为个人开发使用单个 harness/changes/active/ 任务。使用生成的 scripts/harness-change.* 命令将暂停的工作移动到 parking/，将关闭的工作移动到 archive/。在激活工作关闭后，将 docs/STATUS.md 维护为软交接摘要。永远不要手动编辑 harness/changes/INDEX.json；它是由 park、close、resume 和 reindex 重新生成的索引。结构化变更使用 spec.md（WHAT/WHY）、plan.md（HOW）和 tasks.md（可执行工作）。

7. Harness 从证据中演化

每隔几次关闭的变更，生成的 scripts/harness-evolve.* check 命令可能会创建 harness/evolution/pending.md。将其视为从真实归档证据改进 harness 规则的维护提醒，而不是不相关用户工作的硬阻塞器。如果开始根据待办 证据行动，首先刷新 harness/changes/INDEX.json 并使用当前合格的归档 窗口；旧待办文件中的候选归档是触发快照，不是唯一的证据。 然后以提案 + results.tsv + mark-complete 完成，或停车/阻塞该工作。 不要将一次性业务 bug 转化为永久流程。仅保留改进审计 分数并通过验证的变更。

参考文件

阶段 2 和阶段 4 子智能体的智能体提示位于 agents/。

对于小型项目（< 20 个文件）或当子智能体不可用时，请内联执行阶段，而不是生成智能体。