create-harness-vibe-coding 0.1.2 → 0.1.4

package/templates/common/docs/harness/agent-workflow.md

@@ -1,145 +1,86 @@
-# Agent Workflow Harness
+# Agent Workflow
 
-> **职责**：约束 agent 如何实现一个功能。它不是 runtime 代码架构，而是 engineering harness：防止 AI 跳过需求、乱改边界、缺测试、没有闭环。
->
-> **原则**：小任务轻流程，大任务有文档；用测试和边界检查约束 agent，而不是靠长提示词。
+Use when implementing, reviewing, debugging, or coordinating subagents.
 
----
-
-## 1. 什么时候必须开 Feature Doc
-
-使用 [../features/_template.md](../features/_template.md) 创建一个新的 `docs/features/{{FEATURE_SLUG}}.md`。
-
-必须开文档：
-- 新增功能或用户可见行为。
-- 修改跨层契约、端口、状态机、数据流或权限规则。
-- 影响多个模块，或预计超过一个短会话。
-- 修复边界不清的 bug，需要先定义期望行为。
-- 需要 subagents 分工、TDD 或人工审批。
-
-可以不开文档：
-- 拼写、链接、注释等纯文档小修。
-- 单测试断言或单行安全修复，且边界完全清楚。
-- 只读调查或一次性命令输出。
-
-如果不确定，开一个短 feature doc。短文档比隐含假设便宜。
-
----
-
-## 2. Kiro-lite 流程
-
-每个非平凡功能按一个文件走完四段，不默认拆多个文件。
-
-1. **Requirements**：写清目标、非目标、验收标准。
-2. **Design**：写清影响范围、允许修改文件、不允许修改文件、接口/状态/数据流变化。
-3. **Tasks**：拆成可验证任务，每个任务有 owner、write set、验证命令。
-4. **Verification**：记录测试结果、边界检查、文档同步、剩余风险。
-
-只有当 feature doc 超过约 200 行，或任务需要多人/多 agent 长时间并行时，才升级为目录：
+## ReAct Loop
 
 ```text
-docs/features/{{FEATURE_SLUG}}/
-├── requirements.md
-├── design.md
-├── tasks.md
-└── verification.md
+Observe -> Load minimal context -> Plan -> Act -> Verify -> Update docs/harness/PLAN.md
 ```
 
----
-
-## 3. Subagent 分工
-
-Subagent 是分工工具，不是责任转移。主 agent 负责最终集成、验证和解释。
+If context grows, load [context-loading.md](context-loading.md) and split the work. If more than one agent is useful, load [dispatch.md](dispatch.md).
 
-| 角色 | 允许做 | 禁止做 | 输出 |
-| --- | --- | --- | --- |
-| Explorer | 只读调查、找上下文、列风险 | 修改文件、重构、下结论替代验证 | 相关文件、风险点、建议测试 |
-| Test Writer | 只写/改测试和测试 fixtures | 改生产代码、放宽断言 | 失败测试、测试意图 |
-| Implementer | 在指定 write set 内实现 | 触碰未授权文件、扩大 scope | 改动文件、实现说明 |
-| Reviewer | 只读审查边界、过度设计、缺测试 | 修改代码、重排任务 | findings、severity、文件行号 |
-| Verifier | 运行验证命令、汇总结果 | 改业务代码掩盖失败 | 命令、结果、失败原因 |
+## Feature Packet
 
-分工规则：
-- 同一时间并行 subagents 的 write set 必须不重叠。
-- Explorer 和 Reviewer 默认只读。
-- Test Writer 必须先于 Implementer，除非是纯文档或无法自动测试的变更。
-- Implementer 只能执行 feature doc 里列出的 tasks。
-- Verifier 的失败结果必须写回 feature doc，不能只在聊天里口头说明。
+Create `docs/features/{{FEATURE_SLUG}}.md` from [../features/_template.md](../features/_template.md) when work changes behavior, touches multiple files, crosses layers, or needs more than one short session.
 
----
+The packet must contain:
 
-## 4. TDD 闭环
+- requirements and non-goals
+- acceptance criteria
+- allowed write set and forbidden scope
+- task list with verification commands
+- test results and residual risks
 
-默认闭环：
+## Standard Build Loop
 
 ```text
-feature doc -> failing test -> minimal implementation -> tests pass -> boundary check -> docs sync -> review -> close
+PRD/feature packet
+-> failing test or manual check
+-> minimal implementation
+-> verification
+-> review
+-> docs sync
+-> close or iterate
 ```
 
-TDD 规则：
-- 新行为先写失败测试，再实现。
-- bug fix 先写复现测试，再修复。
-- 重构先记录现有测试，再移动代码，最后证明行为未变。
-- 无法自动测试时，feature doc 必须写明人工验证步骤和不可自动化原因。
-- 不允许为了通过测试删除关键断言、放宽边界测试或跳过失败测试。
-
----
-
-## 4.1 矛盾处理
-
-当 agent 发现 PRD、architecture、ports、data-flow、state-machines、tests 或代码互相矛盾时：
-
-1. 停止实现，不继续猜测。
-2. 在 feature doc 的 Decision Log 记录冲突位置、冲突内容、可选解释和推荐选择。
-3. 如果冲突影响安全边界、端口合同、状态机或用户可见行为，先询问维护者。
-4. 如果冲突只影响命名、注释或明显过期文档，可以按代码和测试事实修正 docs，并在 Verification 记录原因。
-5. 修正后再继续 TDD 闭环。
+## Subagent Use
 
----
+Use subagents when a task needs broad reading, parallel work, cross-layer changes, independent review, or isolated debugging.
 
-## 5. Write Set 和边界
+Before spawn, define:
 
-Feature doc 必须写：
-- **Allowed write set**：本次允许修改哪些文件/目录。
-- **Forbidden scope**：明确不碰哪些文件/行为。
-- **Architecture impact**：是否影响 `architecture.md`、`ports.md`、`data-flow.md`、`state-machines.md`。
-- **Rollback note**：失败时如何回退本次改动，不要求回退用户已有改动。
+- role
+- task
+- mode
+- read boundary
+- write boundary
+- dependency
+- injected docs from [context-loading.md](context-loading.md)
+- return format
 
-默认禁止：
-- 顺手重构无关模块。
-- 为了实现一个功能修改公共契约但不更新 docs。
-- 让 harness 承担 domain 业务判断。
-- 绕过权限、审计、状态机和边界测试。
+Rules:
 
----
+- Explorer Pass, Reviewer, and Verifier are read-only.
+- Researcher and Docs Researcher are read-only unless explicitly asked to return a docs patch.
+- Planner and Architect are read-only unless explicitly asked to return a docs patch.
+- Test Writer writes tests before Implementer writes production code.
+- Implementer only writes inside its declared write set.
+- Writing agents run serially unless write sets are disjoint.
+- Debugger fixes the smallest failing path, not adjacent design.
+- Main agent integrates summaries, resolves conflicts, and runs final verification.
 
-## 6. 完成标准
+## Parallel Dispatch
 
-一个 feature 只有同时满足这些条件才算完成：
-- Requirements 的验收标准逐条可验证。
-- Tasks 全部完成或明确取消并说明原因。
-- 新增/修改行为有测试或人工验证记录。
-- 测试框架（如 pytest、vitest、go test）通过；如果不能通过，记录具体失败和是否与本次变更相关。
-- 架构边界测试通过，或 feature doc 记录为什么需要改变边界。
-- 受影响 docs 已同步。
-- Reviewer 没有未处理的 critical/high findings。
+Use [dispatch.md](dispatch.md) for multi-agent work. Default to at most three active agents. Prefer parallel read-only work first, then serial writes.
 
-## 6.1 快车道
+Every dispatched agent returns the handoff format defined in [dispatch.md](dispatch.md).
 
-满足以下全部条件时，可以不开完整 feature doc，但必须在提交说明或聊天结果里写清验证：
+## Conflict Rule
 
-- 只影响拼写、链接、注释、单个测试断言或单行安全修复。
-- 不改变跨层端口、状态机、数据流、权限、审计或用户可见行为。
-- 不新增依赖，不移动文件，不扩大 public API。
-- 能用一个命令或一次人工检查验证。
+If PRD, docs/harness/PLAN.md, architecture, ports, tests, or code disagree:
 
-如果快车道过程中发现影响范围变大，立即补 feature doc。
+1. stop implementation
+2. record the conflict in `docs/harness/PLAN.md` or the feature doc
+3. choose the smallest reversible decision
+4. ask the maintainer when user-visible behavior or security is affected
 
----
+## Completion Gate
 
-## 7. 外部参考
+Close only when:
 
-- OpenAI ExecPlans：复杂任务要有自包含、可恢复、可验证的执行计划。
-- GitHub Spec Kit：constitution -> specify -> plan -> tasks -> implement。
-- Kiro Specs：requirements -> design -> tasks，适合约束 agent 先想清楚再写代码。
-- Claude Code Subagents / Hooks：focused subagents、权限限制、hook-based guardrails。
+- acceptance criteria are satisfied
+- verification evidence is recorded
+- architecture, ports, data-flow, or state docs are synced if affected
+- no unresolved critical/high review findings remain
+- `docs/harness/PLAN.md` states the final status or next iteration

package/templates/common/docs/harness/architecture.md

@@ -1,87 +1,90 @@
 # Harness Architecture — {{projectName}}
 
-> **职责**：定义系统的分层结构、组件全景和关键设计决策。
-> **不写什么**：代码细节（AI 能读代码）、API 文档（放 docstring）。
+> **Responsibility**: Defines the system layering structure, component overview, and key design decisions.
+> **Does NOT cover**: Code details (AI can read code), API documentation (placed in docstrings).
 >
-> 哲学来源：arc42 第 5 章 (Building Block View) + C4 Model Level 3 (Component) + matklad 的轻量 ARCHITECTURE.md。
+> Philosophical sources: arc42 Chapter 5 (Building Block View) + C4 Model Level 3 (Component) + matklad's lightweight ARCHITECTURE.md.
 
 ---
 
-## 1. 分层规则
+## 1. Layering Rules
 
-<!-- 这是整个架构最硬性的约束。每个层的"允许依赖什么"必须明确。 -->
+<!-- This is the hardest constraint in the entire architecture. Each layer's "allowed dependencies" must be explicit. -->
 
 ```
 ┌──────────────────────────┐
-│     interfaces/          │  ← 用户入口（CLI / API / UI）
-│     可依赖: harness       │
+│     interfaces/          │  ← User entry (CLI / API / UI)
+│     May depend on: harness│
 ├──────────────────────────┤
-│     harness/             │  ← 通用运行外壳：编排、安全、审计、调度
-│     可依赖: application   │    不包含业务规则
+│     harness/             │  ← Generic runtime shell: orchestration,
+│     May depend on:        │     security, auditing, scheduling
+│       application         │     Contains no business rules
 ├──────────────────────────┤
-│     application/         │  ← 业务用例编排
-│     可依赖: domain        │
+│     application/         │  ← Business use-case orchestration
+│     May depend on: domain │
 ├──────────────────────────┤
-│     domain/              │  ← 纯业务对象 + 端口协议
-│     只依赖: 标准库         │    不依赖任何外部实现
+│     domain/              │  ← Pure business objects + port protocols
+│     Only depends on:      │     Depends on no external implementations
+│       standard library    │
 ├──────────────────────────┤
-│     infrastructure/      │  ← 适配器实现（数据源、外部服务）
-│     实现 domain 的端口     │
+│     infrastructure/      │  ← Adapter implementations (data sources,
+│     Implements domain     │     external services)
+│       ports               │
 └──────────────────────────┘
 ```
 
-**硬约束**：
-- domain 绝不导入 infrastructure/ 或 interfaces/
-- application 只依赖 domain
-- harness 协调流程但不包含领域业务规则
-- 所有跨层通信通过 domain 定义的端口协议
+**Hard Constraints**:
+- domain must never import infrastructure/ or interfaces/
+- application only depends on domain
+- harness coordinates workflows but contains no domain business rules
+- All cross-layer communication goes through port protocols defined in domain
 
 ---
 
-## 2. Harness 核心组件
+## 2. Harness Core Components
 
 ### 2.1 Runner / Loop
 
-- **职责**：驱动一次任务从输入到完成：加载上下文、调用 application use-case、处理停止条件。
-- **设计决策**：
-  - Runner 只编排，不解释领域含义 — 为什么：保持 harness 可复用于不同业务域
-  - 停止条件显式建模 — 为什么：防止 agent loop 无限运行或静默半完成
-- **不负责**：业务规则、领域对象创建细节、外部服务实现
+- **Responsibility**: Drives a task from input to completion: loading context, calling application use-cases, handling stop conditions.
+- **Design Decision**:
+  - Runner only orchestrates, does not interpret domain meaning — Rationale: keeps harness reusable across different business domains
+  - Stop conditions are explicitly modeled — Rationale: prevents agent loops from running indefinitely or silently half-completing
+- **Does NOT handle**: Business rules, domain object creation details, external service implementations
 
 ### 2.2 Permission Policy
 
-- **职责**：决定某个工具、文件、网络或外部动作是否允许执行。
-- **设计决策**：
-  - 默认拒绝高风险动作，允许规则显式声明 — 为什么：底座要先保证安全边界
-- **不负责**：判断业务动作是否正确
+- **Responsibility**: Decides whether a given tool, file, network, or external action is allowed to execute.
+- **Design Decision**:
+  - High-risk actions are denied by default, allow rules are explicitly declared — Rationale: the platform must first guarantee security boundaries
+- **Does NOT handle**: Judging whether a business action is correct
 
 ### 2.3 Event Bus / Audit Trail
 
-- **职责**：记录任务生命周期、工具调用、失败、人工审批和最终结果。
-- **设计决策**：
-  - 事件追加写入，审计记录不可原地改写 — 为什么：方便回放、排错和复盘
-- **不负责**：替业务系统保存最终数据
+- **Responsibility**: Records task lifecycle, tool invocations, failures, human approvals, and final results.
+- **Design Decision**:
+  - Events are append-only, audit records cannot be overwritten in place — Rationale: facilitates replay, debugging, and post-mortem analysis
+- **Does NOT handle**: Saving final data on behalf of business systems
 
 ### 2.4 State / Checkpoint Store
 
-- **职责**：保存可恢复状态、上下文摘要、任务进度和中断点。
-- **设计决策**：
-  - 状态格式必须可序列化 — 为什么：便于 replay、resume、测试和迁移
-- **不负责**：长期业务数据库建模
+- **Responsibility**: Saves recoverable state, context summaries, task progress, and interrupt points.
+- **Design Decision**:
+  - State format must be serializable — Rationale: enables replay, resume, testing, and migration
+- **Does NOT handle**: Long-term business database modeling
 
 ### 2.5 Tool Registry
 
-- **职责**：注册可调用工具及其输入/输出契约、权限标签和错误语义。
-- **设计决策**：
-  - 工具契约写清输入、输出、错误和副作用 — 为什么：降低 agent 误用工具的概率
-- **不负责**：工具内部业务实现
+- **Responsibility**: Registers callable tools along with their input/output contracts, permission labels, and error semantics.
+- **Design Decision**:
+  - Tool contracts explicitly specify input, output, errors, and side effects — Rationale: reduces the probability of agent tool misuse
+- **Does NOT handle**: Internal business implementation of tools
 
 ---
 
-## 3. 架构约束（不可协商）
+## 3. Architectural Constraints (Non-Negotiable)
 
-- `domain/` 只定义业务模型、业务不变量和端口协议，不导入 `harness/`、`infrastructure/` 或 `interfaces/`。
-- `harness/` 可以协调流程、安全门、审计和停止条件，但不能决定业务含义。
-- 所有跨层外部能力都通过 `domain` 端口表达，适配器实现放在 `infrastructure/`。
-- 拒绝和失败必须能被测试或在 feature doc 中写明人工验证。
-- 审计事件追加记录，不原地改写。
+- `domain/` only defines business models, business invariants, and port protocols; does not import `harness/`, `infrastructure/`, or `interfaces/`.
+- `harness/` may orchestrate workflows, security gates, auditing, and stop conditions, but must not determine business meaning.
+- All cross-layer external capabilities are expressed through `domain` ports; adapter implementations live in `infrastructure/`.
+- Rejections and failures must be testable or documented with manual verification steps in the feature doc.
+- Audit events are append-only, never overwritten in place.

package/templates/common/docs/harness/context-loading.md

@@ -0,0 +1,93 @@
+# Context Loading Protocol
+
+Use when context is growing, subagents are needed, or an agent is unsure which harness doc applies.
+
+## Routing Authority
+
+`docs/README.md` is the primary router. This file is a secondary context-splitting protocol for subagents and long tasks.
+
+If this file and `docs/README.md` disagree, follow `docs/README.md`, record the assumption in `docs/harness/PLAN.md`, and update this file later.
+
+## Main Context
+
+Always keep:
+
+- `CLAUDE.md`
+- `MEMORY.md`
+- `docs/README.md`
+- `docs/harness/PLAN.md` when active
+- current feature doc when active
+
+Load other docs only by trigger.
+
+## Trigger Matrix
+
+| Trigger | Load |
+| --- | --- |
+| idea, scope, MVP | `docs/harness/lifecycle.md`, `docs/research/PRD.md` |
+| research, competitors, stack choice | `docs/research/README.md`, `docs/research/research-results.md` |
+| official docs, API, SDK, version, limits | `docs/research/README.md`, `docs/harness/architecture.md`, `docs/domain/ports.md` as needed |
+| layer, dependency, module boundary | `docs/harness/architecture.md`, `docs/domain/ports.md` |
+| task split, owner, write set | `docs/harness/PLAN.md`, `docs/harness/agent-workflow.md` |
+| parallel agents, dispatch, worktree decision | `docs/harness/dispatch.md`, `docs/harness/PLAN.md` |
+| event, retry, failure path | `docs/harness/data-flow.md` |
+| status, transition, resume | `docs/harness/state-machines.md` |
+| subagent spawn | this file plus the role pack below |
+
+## Subagent Packs
+
+Explorer Pass:
+- inject: question, read boundary, relevant docs
+- forbid: writes
+- return: files found, facts, risks, suggested tests
+
+Planner:
+- inject: user goal, lifecycle phase, PRD or PLAN section, dispatch constraints
+- forbid: production code
+- return: tasks, dependencies, read/write sets, dispatch table, gates, open questions
+
+Researcher:
+- inject: question, decision needed, source boundaries, tool options
+- forbid: production code
+- return: sources, adopted/rejected/watch decisions, risks, research-results.md patch
+
+Docs Researcher:
+- inject: library/API/config, implementation question, version/date constraints
+- forbid: production code
+- return: official links, constraints, errors, examples, affected docs
+
+Architect:
+- inject: PRD, current architecture, ports
+- forbid: implementation
+- return: boundary decision, affected docs, risks
+
+Test Writer:
+- inject: acceptance criteria, feature doc, test write set
+- forbid: production code
+- return: failing tests and test intent
+
+Implementer:
+- inject: task, tests, allowed write set, forbidden scope
+- forbid: unrelated refactor and test loosening
+- return: changed files and implementation notes
+
+Reviewer:
+- inject: diff, acceptance criteria, architecture docs
+- forbid: writes
+- return: findings by severity, missing tests, boundary issues
+
+Debugger:
+- inject: failing command, error output, related files
+- forbid: broad rewrites
+- return: root cause, fix, proof
+
+Verifier:
+- inject: verification commands and acceptance criteria
+- forbid: code changes
+- return: commands run, results, residual risk
+
+## Handoff Rule
+
+Only the subagent summary enters main context. If details are needed, load the named files directly instead of replaying the subagent conversation.
+
+Use the handoff format in [dispatch.md](dispatch.md) for every dispatched agent.

package/templates/common/docs/harness/data-flow.md

@@ -1,23 +1,23 @@
-# 数据流 — {{projectName}}
+# Data Flow — {{projectName}}
 
-> **职责**：定义每个事件/请求的完整生命周期——正常路径 + 所有失败分支。
-> **这是整个 docs 里最重要的文件**——AI 实现时最常编造的就是失败路径行为。写清楚就不会。
+> **Purpose**: Define the complete lifecycle of each event/request — happy path + all failure branches.
+> **This is the most important file in the entire docs folder** — what AI most often invents during implementation is failure-path behavior. Write it clearly and it won't.
 >
-> 哲学来源：EventCatalog 模式 + arc42 第 6 章 (Runtime View)。
+> Philosophy source: EventCatalog pattern + arc42 Chapter 6 (Runtime View).
 
 ---
 
-## 1. 事件目录
+## 1. Event Catalog
 
-| 事件类型 | 生产者 | 消费者 | Payload 关键字段 | 投递语义 | 排序要求 |
+| Event Type | Producer | Consumer | Payload Key Fields | Delivery Semantics | Ordering Requirements |
 | --- | --- | --- | --- | --- | --- |
 | `{{EVENT_1}}` | `{{PRODUCER}}` | `{{CONSUMERS}}` | `{{KEY_FIELDS}}` | {{SEMANTICS}} | {{ORDERING}} |
 
 ---
 
-## 2. 核心流程
+## 2. Core Flows
 
-### 2.1 正常路径
+### 2.1 Happy Path
 
 ```mermaid
 sequenceDiagram
@@ -37,23 +37,23 @@ sequenceDiagram
     Runner-->>Caller: {{FINAL_RESULT}}
 ```
 
-### 2.2 失败路径
+### 2.2 Failure Paths
 
-每个失败点必须写清：
-- **触发条件**
-- **系统行为**
-- **事件发布**
-- **调用方感知**
-- **恢复方式**
+Each failure point must clearly document:
+- **Trigger condition**
+- **System behavior**
+- **Event publishing**
+- **Caller perception**
+- **Recovery method**
 
 ---
 
-## 3. 错误处理约定
+## 3. Error Handling Conventions
 
-- **可重试错误**：{{POLICY}}
-- **不可重试错误**：{{POLICY}}
-- **静默忽略**：{{POLICY}}
+- **Retryable errors**: {{POLICY}}
+- **Non-retryable errors**: {{POLICY}}
+- **Silent ignore**: {{POLICY}}
 
 ---
 
-> **提示**：当前 data-flow.md 是空模板。请按项目实际流程填写。格式参考 ECC 仓库的实际项目示例。
+> **Note**: This data-flow.md is currently an empty template. Fill it in according to your project's actual flows. For format reference, see real project examples in the ECC repository.

package/templates/common/docs/harness/dispatch.md

@@ -0,0 +1,82 @@
+# Dispatch Protocol
+
+Purpose: coordinate a small set of subagents without building a scheduler.
+
+Use when work needs parallel reading, independent review, cross-layer analysis, or more than one bounded implementation pass.
+
+## Principles
+
+- Main agent owns the final decision, integration, and verification.
+- Prefer three or fewer active agents.
+- Read-only agents may run in parallel.
+- Writing agents run serially unless write sets are disjoint.
+- Use a worktree when two agents may touch overlapping files or long-running branches.
+- Only summaries enter main context. Load named files directly when details are needed.
+
+## Dispatch Loop
+
+```text
+Goal
+-> Fill PLAN tasks and Parallel Dispatch
+-> Run parallel read-only agents
+-> Main agent integrates findings
+-> Test Writer defines failing test or manual check
+-> Implementer makes bounded change
+-> Reviewer checks diff
+-> Verifier records evidence
+-> Main agent updates PLAN and closes or iterates
+```
+
+## Modes
+
+| Mode | Use When | Constraint |
+| --- | --- | --- |
+| Parallel Read | research, exploration, architecture review, docs/API check | no writes |
+| Serial Write | tests, implementation, docs sync | one writer at a time |
+| Isolated Worktree | overlapping write sets or competing approaches | merge only after review |
+
+## Common Agents
+
+| Agent | Mode | Purpose |
+| --- | --- | --- |
+| `planner` | Parallel Read | split goal into tasks, dependencies, write sets |
+| Explorer Pass | Parallel Read | bounded read-only exploration when no dedicated agent is needed |
+| `researcher` | Parallel Read | product, market, ecosystem, dependency research |
+| `docs-researcher` | Parallel Read | official docs, API, SDK, version, limits |
+| `architect` | Parallel Read | layer boundaries, ports, data flow, state impact |
+| `test-writer` | Serial Write | failing test or manual verification plan |
+| `implementer` | Serial Write | minimal change inside declared write set |
+| `debugger` | Serial Write | smallest fix for a reproduced failure |
+| `reviewer` | Parallel Read | diff review, risks, missing tests |
+| `verifier` | Parallel Read | run checks and record evidence |
+
+## Dispatch Rules
+
+- Every dispatch row needs task, agent, mode, read set, write set, dependency, output, and status.
+- A write set of `none` means read-only.
+- If two write sets overlap, do not run those agents in parallel.
+- If an agent returns uncertainty, mark the row `Blocked` or add a follow-up row.
+- If docs, tests, and code disagree, stop implementation and record the conflict in `PLAN.md`.
+
+## Handoff Format
+
+Subagents return summaries in this shape:
+
+```text
+Agent:
+Task:
+Mode:
+Files read:
+Files changed:
+Findings:
+Evidence:
+Risks:
+Next:
+PLAN patch:
+```
+
+Use `Files changed: none` for read-only agents. Use `PLAN patch: none` when no state update is needed.
+
+## Statuses
+
+Allowed dispatch statuses: Pending / In Progress / Returned / Integrated / Blocked / Verified.

package/templates/common/docs/harness/extension.md

@@ -0,0 +1,67 @@
+# Extension Contract
+
+Purpose: keep stack-specific agents, skills, rules, and hooks compatible with this harness.
+
+Use during setup whenever adding assets from ECC, SuperClaude, toolboxes, or local project conventions.
+
+## Agent Contract
+
+Every added agent must have frontmatter:
+
+```yaml
+---
+name: stack-agent-name
+description: Use when ...
+tools: Read, Grep, Glob
+model: sonnet
+skills: harness-context
+---
+```
+
+Choose one harness skill:
+
+| Agent Type | Skill |
+| --- | --- |
+| research, docs, API lookup | `harness-research` |
+| planning, architecture, context split | `harness-context` |
+| tests, implementation, debugging, review, verification | `harness-build-loop` |
+
+Agent body must state:
+
+- load first
+- inputs required
+- allowed write set or read-only
+- forbidden scope
+- verification or evidence
+- return format from [dispatch.md](dispatch.md)
+
+## Skill Contract
+
+Every added skill must state:
+
+- when to use
+- docs to load
+- required inputs
+- allowed writes
+- output format
+- whether to update `docs/harness/PLAN.md`
+- whether to use [dispatch.md](dispatch.md)
+
+Skills should extend the harness. They should not replace `docs/README.md`, `PLAN.md`, `context-loading.md`, `dispatch.md`, or `agent-workflow.md`.
+
+## Rules
+
+- Do not add broad agents that can write anywhere.
+- Do not add agents whose role overlaps an existing common agent without naming the difference.
+- Do not add tools that bypass project permissions or user approval.
+- Do not run stack-specific writing agents in parallel unless write sets are disjoint.
+- If an added asset conflicts with this harness, adapt the asset instead of changing the core contract.
+
+## Registration
+
+After adding assets:
+
+- list agents in `MEMORY.md#Agents`
+- list skills in `MEMORY.md#Skills`
+- update `docs/harness/PLAN.md` when the asset affects current work
+- run `node scripts/validate-harness.mjs`