# devloop

devloop 是跨 CLI 的 plugin marketplace，根目录下每个 plugin 独立交付和演进。`devloop/devloop`
是首个 Plugin，承载开发闭环；`code-taste` 提供设计判断 skill，`quality` 提供基于执行证据的质量
评估 skill，`example` 是占位示例。

---

## 项目定位与边界

devloop 托管聚焦开发者效率的 plugin 集合。本仓库**根层**只负责：

- 多 plugin marketplace 的索引（`.claude-plugin/marketplace.json` 等）
- 跨 plugin / 跨 CLI 的共用约定（`<PLUGIN_ROOT>` 占位、CLI-agnostic 共享路径布局）
- 多 CLI 接入位置约定（Claude / Codex / DeepSeek Harness / opencode）

明确**不在本文档展开**的内容：

- 具体 plugin 的设计动机、内部架构、hook 列表、状态文件、配置项 → 见对应 `<plugin>/README.md`
- 整个工作流落地的方案记录（feature 矩阵、版本规划等）→ 见 plan 文档

当前实施范围：`devloop` 支持 Claude Code、Codex 与 DeepSeek Harness。Claude/Codex 通过薄进程 hook adapter 接入；DSH bundle 同时挂载原生 Cordis adapter 并暴露包内 skills。三端共用 TypeScript Board、state、tool projection 与 policy。skill 调用的 Git/release/validation/review 脚本继续使用 Python。opencode 侧目前只有 `example` 占位 plugin 演示 marketplace 结构。

---

## 代码地图与核心模块

```
devloop/                              # ← 仓库根（marketplace）
│
├── .claude-plugin/marketplace.json   # Claude marketplace 索引
├── .agents/plugins/marketplace.json  # Codex marketplace 索引（Codex 标准路径）
├── .opencode/marketplace.json        # opencode marketplace 索引（占位，按协议补）
│
├── devloop/                          # plugin: 开发者日常工作流（Claude + Codex + DSH）
│   │                                 #   git / MR / lint / test / cwd-aware context / Board / 执行守卫
│   │                                 #   Claude 用 CwdChanged / FileChanged / native monitor；Codex 用 SessionEnd + Scheduled tasks
│   ├── .claude-plugin/plugin.json    #     Claude manifest
│   ├── .codex-plugin/plugin.json     #     Codex manifest（hooks 指向 hooks.codex.json）
│   ├── cordis.patch.yml              #     DSH bundle layer（挂载 adapter + 暴露 skills）
│   ├── skills/                       #     7 个 skill（CLI 共享，含一次性 monitor reconciliation）
│   ├── commands/                     #     slash commands（Claude 端）
│   ├── adapters/                     #     Claude/Codex hook dialect + DSH Cordis adapter
│   ├── domain/                       #     TS 共享领域模型与状态
│   ├── lib/                          #     TS 共享技术 seam
│   ├── hooks/                        #     TS policy/runtime 与 hook manifests
│   ├── tasks/                        #     周期 task 的发现描述
│   ├── scripts/                      #     skill-owned Python workflow 及其私有 domain/lib/tasks
│   ├── config/                       #     用户配置模板（config.json：workspaces / gitlab / precommit）
│   ├── monitors/monitors.json        #     Claude MR-sweep 后台轮询
│   └── README.md / AGENTS.md / CONCEPTS.md
│
├── code-taste/                       # plugin: 架构、边界、命名与可维护性判断（skill-only）
│   ├── .claude-plugin/plugin.json    #     Claude manifest
│   ├── .codex-plugin/plugin.json     #     Codex manifest
│   ├── skills/code-taste/            #     共享 skill 与分层 references
│   └── README.md
│
├── quality/                          # plugin: 基于项目真实测试资产的质量评估（skill-only）
│   ├── .claude-plugin/plugin.json    #     Claude manifest
│   ├── .codex-plugin/plugin.json     #     Codex manifest
│   ├── references/environment.md     #     E2E / Perf 共用的 Target、Runner、连接与准备契约
│   ├── skills/e2e/                   #     操作项目已有 E2E 能力，并渐进补充项目自有覆盖
│   ├── skills/perf/                  #     操作项目已有压力/容量能力，并解释或比较运行证据
│   ├── skills/trajectory/            #     评估 Agent 轨迹并组织效果/成本调优
│   └── README.md
│
├── example/                          # plugin: 占位演示，证明这是多 plugin marketplace
│   ├── .claude-plugin/plugin.json    #     Claude ✅
│   ├── .codex-plugin/plugin.json     #     Codex  ✅
│   └── commands/hello.md
│
├── scripts/                          # 仓库级工具脚本（跨 plugin），如版本号 bump
│   └── bump_plugin_version.py        #   被 `make bump-version` 调用
├── Makefile                          # 仓库级入口（`make help` 查看）
├── AGENTS.md                         # 本文档（仓库级）
├── README.md                         # 用户向 marketplace 总览（安装方式）
└── CONTRIBUTING.md                   # 新 plugin 接入规范
```

**CLI 范围差异**：`devloop` 当前支持 Claude Code、Codex 与 DSH。`skills/` 共享；`commands/` 仍是 Claude slash command 入口，Codex 无同构 slash command，主要由 skill 名 + bundled hooks 作为入口；DSH bundle 暴露同一组 skills，并加载 `@compforge/devloop/dsh`。Claude 的 native monitor 与 Codex Scheduled task 分别驱动同一个一次性 reconciliation 入口。opencode 待协议明确。

详细：[`devloop/README.md`](./devloop/README.md)（使用向） · [`devloop/AGENTS.md`](./devloop/AGENTS.md)（开发向）。

---

## 关键约定

### `<PLUGIN_ROOT>` 占位符（跨 plugin 通用）

按"谁来解析"分两层处理，两层都不需要为新 CLI 做 sed：

**(1) 配置文件层（CLI 解析）**——`hooks/hooks.json` / `plugin.json` 这种由 CLI 直接读取的配置文件：

- 命令字符串里**统一写 `${CLAUDE_PLUGIN_ROOT}`**。
- Claude Code 原生认这个占位符；Codex 提供 `PLUGIN_ROOT` 作为标准名，同时保留 `CLAUDE_PLUGIN_ROOT` / `CLAUDE_PLUGIN_DATA` 作为兼容别名。
- Codex 还额外提供 `PLUGIN_DATA`（可写数据目录）供插件持久化状态。
- Claude 使用 `hooks/hooks.json`，Codex 使用 `hooks/hooks.codex.json`；两个 manifest 显式选择 Harness 身份，并进入同一套 TypeScript runtime/core。

**(2) 文档/SKILL.md 层（AI 解析）**——人写给 AI 看的 markdown：

- 写 `<PLUGIN_ROOT>` 占位，AI 执行时按当前 CLI 映射到实际 env 变量值。
- Claude → `${CLAUDE_PLUGIN_ROOT}`；Codex → `${PLUGIN_ROOT}`（`CLAUDE_PLUGIN_ROOT` 亦可用，为兼容别名）。

加新 CLI 时：配置文件层多半零改动（如果新 CLI 也兼容 `CLAUDE_PLUGIN_ROOT`），文档层在 AI 提示词里多列一行映射即可。

### CLI-agnostic 共享路径布局

每个 plugin 内部建议以下目录跨 CLI 共享：

- `<plugin>/skills/`、`<plugin>/commands/`：内容 CLI 无关
- `<plugin>/domain/`：TypeScript 领域模型、状态变化与生命周期规则；归属看领域事实的 owner
- `<plugin>/lib/`：TypeScript 跨入口技术能力和外部适配，不放领域对象
- `<plugin>/hooks/`：TypeScript 事件 adapter，依赖 `domain/lib`
- `<plugin>/scripts/`：skill-owned workflow；允许保留 Python 及其私有辅助包，但 Harness runtime 不得依赖它

Codex 与 Claude 的 command hook 都使用 stdin/stdout JSON，但支持事件和 payload 细节不能靠猜测合并；manifest 显式设置 Harness 身份，adapter 再映射到共享 TypeScript core。opencode 待协议明确时再决定差异隔离层。

### 加新 plugin 的流程

1. 新建 `<plugin>/` 子目录
2. 写需要支持的 CLI 的 manifest（`.claude-plugin/plugin.json` 等）
3. 在每个 CLI 的 `marketplace.json` 追加一项
4. 写 `<plugin>/README.md`，至少包含：能做什么、安装、配置、限制
5. 遵守 `<PLUGIN_ROOT>` 与共享路径布局约定

### 改动 plugin 后：bump 版本号

影响用户体验的 plugin 改动，跑 `make bump-version PLUGIN=<name>`（详见 `make help`）——否则 `/plugin update` 拉不到新版。

---

## References

- 各 plugin 使用 / 安装 / 配置：`<plugin>/README.md`
- 各 plugin 设计与开发：`<plugin>/AGENTS.md`
- 各 plugin 内跨 skill 共享术语：`<plugin>/CONCEPTS.md`（若有）