deepseek-foreman 0.2.1 → 0.2.2

package/README.en.md

@@ -4,10 +4,16 @@ English | [中文](README.md)
 
 # deepseek-foreman
 
-Write work as tickets and dispatch them to **cheaper models**; the Lead only breaks down the work, dispatches it, re-runs the acceptance commands personally, sends it to a **different vendor** for read-only review, and verifies every finding one by one. When nobody is around, it keeps working through the queue.
+**A strong model as foreman, cheap models doing the work, another vendor reviewing — multi-model teamwork that is cheaper and better.** Write work as tickets and dispatch them to **cheaper models**; the Lead only breaks down the work, dispatches it, re-runs the acceptance commands personally, and verifies every finding one by one. When nobody is around, it keeps working through the queue.
 
 Built for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (`dsh`).
 
+**Beginners: three steps** (no cordis / YAML / CLI experience needed):
+
+1. Install dsh with routes for ≥2 different vendors;
+2. add `deepseek-foreman` from the plugin page;
+3. open a new session and say "**help me set up foreman — I have models from \<two vendors\>**".
+
 > **Version 0.2.0 of this project was itself iterated to completion using this very system** — 19 tickets overnight; see [docs/dogfooding.md](docs/dogfooding.md).
 
 ## Origin
@@ -150,6 +156,22 @@ The full sprint ran in one night (2026-09-30 23:00 – 2026-10-01 12:00); the nu
 
 **Token spend** (source: screenshot of the dsh subagent panel; measurement base = cumulative tokens of that build session): build tickets ran 330K–590K tokens each, verification calls 6K–16K tokens each. All build tokens were spent on cheap models — the Lead's context only holds tickets, receipts and review comments, never source code; that is the cost-saving mechanism. No strict A/B experiment was run, so no percentage claims are made; readers can check every line item in the dsh subagent panel themselves.
 
+Per-plugin contribution and the two companion pieces are covered under [Works with](#works-with) below.
+
+## Works with
+
+The three pieces cover one segment each and add up:
+
+| Piece | What it does | How to get it |
+|---|---|---|
+| **deepseek-foreman (this package)** | the strong model foremen: dispatch, personally re-run acceptance, verify item by item; cheap models build; another vendor reviews read-only. `pick_route`'s four hard constraints + physical read-only `subagent_readonly` | **included in this package** (takes effect on install) |
+| **Concise-output persona** ([persona.example.md](persona.example.md)) | ponytail-style output discipline: check yourself level by level before acting (don't do it if it can be skipped, reuse before writing new, one line before ten), conclusion first, one-or-two-sentence reports | **included, opt-in**: select-all copy the template → the `personaPrefix` field of the system-prompt plugin in dsh settings → save |
+| **Behaviour-constraint skill** (e.g. superpowers) | guard rails for the agent's behaviour: TDD, acceptance-first rules | **bring your own, optional** |
+
+**Mechanism**: the persona hangs on the `personaPrefix` field of dsh's system-prompt plugin (deployment layer) and **child sessions inherit it automatically** (verified: both the `dsh-subagent` source and actual child-session behaviour) — workers receive deployment-level discipline, so it need not be restated per ticket.
+
+**Honest accounting**: the overall numbers from the 19 tickets are in [Field data](#field-data) above; per-plugin isolated quantification **has had no A/B control, so no numbers are given** — only mechanisms: build dominates token spend → cheap workers; dialogue and judgement stay terse → persona; quality holds → cross-vendor review + item-by-item verification. The three mechanisms each own one segment, and they stack.
+
 ## Status
 
 Installed into dsh desktop 0.2.0-rc.2 (Intel iMac) and verified live: cold start is normal, `pick_route` is callable by the model, the vision constraint really blocks and returns a fallback; the final `subagent_readonly` state is live-verified too (read-only tool set enforced, delegation tools blocked).

package/README.md

@@ -4,10 +4,16 @@
 
 # deepseek-foreman
 
-把活写成工单派给**更便宜的模型**去做，Lead 只负责拆活、派活、亲自重跑验收命令、派**另一家厂商**只读审查、逐条核实。人不在的时候按队列接着干。
+**让强模型当工头、便宜模型干活、别家厂商审查——多模型协作，又省又好。** 把活写成工单派给**更便宜的模型**去做，Lead 只负责拆活、派活、亲自重跑验收命令、逐条核实。人不在的时候按队列接着干。
 
 面向 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（`dsh`）。
 
+**小白三步**（没碰过 cordis / YAML / CLI 也能上手）：
+
+1. 装 dsh，配好 ≥2 家厂商的模型；
+2. 插件页点装 `deepseek-foreman`；
+3. 开新会话，说一句「**帮我配 foreman，我有 \<某两家\> 的模型**」。
+
 > **本项目的 0.2.0 就是用这套系统自己迭代完成的**——19 张工单 overnight，详见 [docs/dogfooding.md](docs/dogfooding.md)。
 
 ## 来源
@@ -148,6 +154,22 @@ bundle 的 `cordis.patch.yml` 里**新增插件行要包在 `insert:` 下**：
 
 **token 开销**（来源：dsh 子代理面板截图；口径＝该次施工会话累计 token）：施工类工单 33 万–59 万 token/单，验证类调用 0.6 万–1.6 万 token/次。施工 token 全部发生在便宜模型上，Lead 上下文只放工单/回执/审查意见、不读代码——这就是省钱机制。未做严格 A/B 对照实验，不给百分比承诺；读者可在 dsh 子代理面板自行核对每条开销。
 
+逐插件的贡献口径与另外两件搭配件，见下面的[联合使用效果](#联合使用效果)一节。
+
+## 联合使用效果
+
+三件套合在一起用，各管一段、叠加生效：
+
+| 件 | 干什么 | 怎么拿到 |
+|---|---|---|
+| **deepseek-foreman（本包）** | 强模型当工头：派单、亲自重跑验收、逐条核实；便宜模型施工；别家厂商只读审查。`pick_route` 四条硬约束 + `subagent_readonly` 物理只读 | **本包含**（装包即生效） |
+| **精简输出 persona**（[persona.example.md](persona.example.md)） | ponytail 式输出纪律：动手前逐级自检（能不做就不做、能复用不新写、能一行不十行）、输出先结论、汇报一两句 | **本包含，可选启用**：全选复制模板 → dsh 设置里 system-prompt 插件的 `personaPrefix` → 保存 |
+| **行为约束类 skill**（如 superpowers） | 给 agent 的行为装护栏：TDD、验收先行那套规矩 | **自备，可选** |
+
+**机制**：persona 挂在 dsh 的 system-prompt 插件 `personaPrefix`（deployment 层），**子会话自动继承**（已实证：dsh-subagent 源码 + 子会话实际行为双重印证）——工人拿到的是部署级纪律，每张工单不用按次重述。
+
+**口径（诚实）**：19 张工单的整体数据见上文[实测数据](#实测数据)；逐插件的孤立量化贡献**没做 A/B 对照，不给数字**，只讲机制——token 大头在实现 → 便宜工人；对话与判断从简 → persona 精简；质量不降 → 异族审查 + 逐条核实。三个机制各管一段，叠加生效。
+
 ## 状态
 
 已装进 dsh 桌面版 0.2.0-rc.2（Intel iMac）并 live 验证：冷启动正常，`pick_route` 可被模型调用，视觉约束会真的拦截并给 fallback；`subagent_readonly` 最终态同样 live 实测通过（只读工具集生效、委派工具被拦死）。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "deepseek-foreman",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Foreman for DeepSeek Harness: your best model leads, cheaper models build, a rival vendor reviews. Role-to-route adjudication with peak-window, vision, output-size and cross-vendor-review constraints.",
   "type": "module",
   "main": "lib/index.js",
@@ -18,7 +18,8 @@
     "lib/index.d.ts",
     "cordis.patch.yml",
     "roles.example.yml",
-    "skill/"
+    "skill/",
+    "persona.example.md"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json"

package/persona.example.md

@@ -0,0 +1,23 @@
+<!--
+  用法（可选，但推荐——工人的输出纪律全靠它）：
+  1. 全选复制下面的规则正文；
+  2. 打开 dsh 设置 → system-prompt 插件 → personaPrefix 字段，粘贴进去；
+  3. 保存即生效。
+  该字段在 deployment 层，子会话自动继承：派出去的工人自动带上这套纪律，
+  每张工单不用重述。不装 ponytail / i-have-adhd 之类的插件也能拿到精简输出。
+  不装也能用本包，只是工人输出会更啰嗦。
+-->
+
+# 精简输出 persona 模板
+
+以下 9 条即提示词正文，按需删改：
+
+1. **先结论，再理由。** 回答开头就给答案，一句话说得清的不写三段。
+2. **动手前逐级自检**：能不做就不做、能复用不新写、能一行不写十行。
+3. **只做被要求的事**：不加没被要求的功能、抽象、配置项、注释、依赖、重构。
+4. **汇报一两句**：做完只说改了哪个文件、验收结果；不写逐行流水账。
+5. **证据不压缩**：验收命令与输出原样贴出，不为省篇幅删改、不摘抄。
+6. **不编**：不编数字、不编命令输出；没验证的明说没验证。
+7. **范围之外先问**：需求不明就问一句，不猜、不擅自扩范围。
+8. **先证据后结论**：跑过验收命令、见到输出，才可以说「完成 / 通过」。
+9. **默认中文汇报**（对方要求别的语言除外）。