harness-plugin-architecture

name

harness-plugin-architecture

description

Use when 设计、审查或重构 cc-master / 类似项目的多 agent harness plugin adapter：新增或修复 host adapter、建立 N-host capability parity、判断 Track A / Track B、为跨 hooks/commands/skills/ccm 的能力建立 Capability INTENT / hook CONTRACT，或处理 Cursor IDE plugin 的非 1:1 语义。覆盖 source-to-adapter、SAP/PHIP、host-native manifest / path / hook / command 边界。Do NOT use when 只实现投影脚本（adapter-projection-engineering）、只做打包发布（plugin-release-engineering）、只改一个 skill body（cc-master-skillsmith），或只设计不改 plugin adapter 的 cross-harness headless CLI worker transport；后者以 design_docs/cross-harness-orchestration-capability-model.md 为合同 SSOT，按普通 engineering / dev loop 推进。

多 Harness 插件架构

你负责把项目维护成 paragoge 式的多 harness plugin/CLI 工程。先保护结构边界，再改具体实现。

先判断任务类型

• 改 runtime skill 语义：进入 plugin/src/skills/<skill>/canonical/。
• 改某 host 如何接收 skill：进入 plugin/src/skills/<skill>/adapters/<host>/strategy.yaml 和 plugin/src/skills/_hosts/<host>/。
• 改单个 hook 的业务契约：进入 plugin/src/hooks/<hook>/CONTRACT.md；改 coverage / stage / registration contract 才进入 plugin/src/hooks/_manifest/。
• 改某 host 的 hook 实现：进入 plugin/src/hooks/<hook>/implementations/<host>/ 和 plugin/src/hooks/_hosts/<host>/。
• 改跨 hooks / commands / skills / ccm 的用户可见能力：进入 Capability Card，再按 Track A / Track B 找单 surface contract 与 host adapter；读 references/n-host-capability-parity.md。
• 改可安装产物：改 projection 脚本，不手改 plugin/dist/<host>/。
• 改发布、打包、版本线：读 plugin-release-system.md。

架构不变量

plugin/src/ 是语义源，plugin/dist/<host>/ 是生成产物。不要从 dist 反推 source，也不要在 dist 中手修 bug。

Skills 走 SAP：

plugin/src/skills/<skill>/
  canonical/
  adapters/<host>/strategy.yaml

Hooks 走 PHIP：

plugin/src/hooks/
  _manifest/
  _hosts/<host>/
  <hook>/implementations/<host>/

Commands 和 host manifests 可以先保持当前 host 源布局，但一旦出现第二个 host，就必须下沉到 host adapter 层，避免共享 source 带 host 假设。

工作流程

1. 先确认目标 host、当前已支持的 host 集合和改动属于 plugin adapter 还是另一种 execution surface。
2. 列出会被改动的 projection surface：skills、hooks、commands、manifest、CLI install、release package。
3. 对每个 surface 明确 source-of-truth 和 generated output。
4. 改 source，并运行 projection。
5. 验证 host-native dist，而不是只验证 source。

何时读 references

• 设计或审查 plugin/src / plugin/dist 边界：读 references/source-to-adapter.md。
• 新增或修复 host adapter：读 references/host-adapter-boundaries.md，再读 design_docs/harnesses/<host>.md 和 design_docs/harnesses/compatibility-matrix.md。
• 新增 N+1 host、处理 Cursor 非 1:1 能力或跨 surface capability：读 references/n-host-capability-parity.md；Cursor IDE plugin 与 headless Agent CLI 的 scope 不可混用。
• 把 cross-harness 能力接入 origin plugin（cached context landing、host-native attempt invoke/bind、跨 session 提示）时：读 references/cross-harness-origin-integration.md；same-harness / other-harness CLI provider、quota store、supervisor 的架构与合同回到 design_docs/cross-harness-orchestration-capability-model.md，实现按普通 engineering / dev loop 推进。
• 盘点 runtime skill 正文里哪些内容该模块化 / 变量化 / overlay：读 design_docs/harnesses/skill-host-coupling-audit.md。

Skill adapter 纪律

• 默认模式是 canonical + slot/overlay。一个 skill 的方法论只应该有一份 canonical。
• unsupported_stub 只用于该 skill 的核心方法论在某 host 下确实不可用；如果只是机制不同，抽 slot。
• partial_overlay 是最后手段，不是解除 stub 的捷径。用它前先证明：哪些段落无法 slot 化、为什么不能通过 reference / overlay 表达、什么时候退回 canonical copy。
• master-orchestrator-guide 这类产品主路径 skill 尤其不能靠 partial fork 维护；主路径差异必须收敛成 host capability slots。
• 涉及 Codex 项目级 skills 或 .agents/skills 同步：读 references/codex-project-skills.md。
• 涉及打包、安装、版本线、发布：读 references/plugin-release-system.md。