feat: streamline PM orchestration and memory routing

Author: uniStark

README.md

@@ -1,7 +1,7 @@
 <h1 align="center">starks</h1>
 
 <p align="center">
-  A task-launcher skill for Claude Code &amp; Codex — grill the requirements, optionally cross-review the plan across models, then run it with PM-mode parallel sub-agents.
+  Turn a rough request into verified delivery — adaptive task tiers, optional Claude↔Codex plan review, lean PM-mode sub-agents, and evidence before “done.”
 </p>
 
 <p align="center">
@@ -17,19 +17,50 @@
 
 ## Why starks?
 
-A single model has systematic blind spots — it tends to miss the same edge cases it didn't think to ask about. But simple work shouldn't pay for heavy process either, so starks tiers every task and keeps trivial jobs fast. At the one decision point that matters, handing the plan to *the other* model for a second opinion (Claude↔Codex) catches gaps before any code is written.
+Most agent workflows are either too casual for a large change or too ceremonial for a small one. starks adapts: tiny edits stay tiny, while complex work gets requirement grilling, an explicit plan gate, PM orchestration, two-stage review, and fresh verification.
+
+Its distinctive move is at the plan boundary: **you** decide whether Claude and Codex should challenge each other's thinking before implementation. During execution, a responsive PM keeps child agents focused with small, one-way context packs instead of making every agent reread the entire project history.
+
+## Signature features
+
+- **Task tiering** — trivial / light / full modes scale the process to the risk. Simple work stays fast; only genuine complexity pays for the full workflow.
+- **Cross-model review (you choose)** — at the hard plan gate, choose **start now / ask the other model / revise**. Claude↔Codex review is never automatic and never silently skipped.
+- **Work-conserving scheduling** — a dependency DAG and Ready queue fill open slots as soon as safe work appears. Strongly coupled slices stay sequential instead of being split for vanity parallelism.
+- **Lean sub-agents** — the PM sends each flat child a compact **“派活单 + 随身小抄”** (work order + context cheat sheet). Children do not reload the session, shared memory, general project docs, or recent commits; they return one bounded **“收工小票”** (completion receipt).
+- **Truthful status board** — the PM stays responsive, shows real state rather than invented percentages or ETAs, and keeps accepting `QUERY`, `ADD`, `CHANGE`, `REPLACE`, and `PRIORITY` while execution continues.
+- **Two-stage review** — spec compliance comes first, code quality second. Failed slices go back for bounded rework instead of disappearing into a vague “done.”
+- **Verification gate** — no “done / passing / fixed” claim without freshly-run evidence that matches the acceptance criteria.
+- **Scoped shared memory** — Claude and Codex can share cross-project Obsidian facts without auto-loading a vault. Reads are opt-in, scoped, and budgeted; writes need separate, enumerated approval; routing prefers a sanitized stable `repo_id`.
+- **Dual-platform, recursion-safe** — one `SKILL.md` serves Claude Code and Codex. A cross-reviewer answers once and exits instead of invoking starks again.
+
+## The signature PM loop
+
+```text
+request
+  └─ task tier → requirement grill → plan
+                                  └─ you choose: start / cross-review / revise
+                                                   │
+PM: dependency DAG + Ready queue                    │ optional Claude↔Codex pass
+  ├─ 派活单 + 随身小抄 → flat child A ─┐            │
+  ├─ 派活单 + 随身小抄 → flat child B ─┼─→ 收工小票 ─┘
+  └─ keep the board live + accept new user input ──→ spec review → code review → verification
+```
+
+The PM is the only context-convergence point. A child gets its goal, allowed files, direct dependencies, constraints, acceptance criteria, and expected evidence—not the full conversation. It may inspect named targets, required direct dependencies, and mandatory project rules; if something is missing, it reports **缺料** rather than expanding scope on its own. Only the PM may spawn children, so the agent tree stays one level deep and predictable.
 
-## Features
+Every child closes with a compact receipt:
+
+```text
+【收工小票】
+- 收工状态：已交卷 / 缺料 / 等老板拍板 / 翻车
+- 动了什么：...
+- 验收证据：...
+- 留下的雷：...
+- 产物位置：...
+- 建议下一棒：...
+```
 
-- **Task tiering** — every task is sorted into trivial / light / full before anything runs, so simple work stays fast and only real complexity triggers the full flow.
-- **Cross-model review (you choose)** — at sign-off you can send the plan to the *other* engine (Claude↔Codex) for a critical second pass. Never automatic, never silently skipped — it's offered as an option.
-- **Work-conserving scheduling** — full tasks use a dependency DAG and Ready queue. Safe Ready work fills each open slot immediately; tightly-coupled work stays sequential instead of being force-split.
-- **Truthful status board** — the PM remains responsive, posts live progress in commentary, and accepts `QUERY`, `ADD`, `CHANGE`, `REPLACE`, and `PRIORITY` messages while work continues.
-- **Two-stage review** — a reviewer checks spec compliance, then a reviewer checks code quality; failures loop back.
-- **Verification gate** — no "done / passing / fixed" claim without freshly-run evidence on the spot.
-- **Scoped shared memory** — Claude and Codex can share cross-project Obsidian facts, but nothing is searched, listed, read, or written automatically. Read access is task-scoped and budgeted; write access is separately enumerated and approved.
-- **Dual-platform** — one `SKILL.md`, symlinked into both Claude Code and Codex.
-- **Anti-recursion guard** — when invoked as a cross-reviewer, starks answers once and exits instead of re-entering its own flow.
+That receipt feeds the live board and review queue without dumping raw logs, long diffs, or duplicate project context back into the PM.
 
 ## Requirements
 
@@ -72,7 +103,7 @@ starks doesn't run the same heavyweight pipeline on everything. When real work s
 - **light** — a single clear concern across a few files. Do it (or confirm in one line) and skip the parallel / cross-review machinery, but the verification gate still applies.
 - **full** — multi-file, architectural, large behavior change, or genuinely uncertain. This runs the whole flow.
 
-For a full-tier task the flow is: **ask whether to route shared project memory** when history may help (default: skip; the task-scoped approval names the metadata scan, files, and context budget) → **grill** the requirements — multiple-choice first, batching independent questions — to surface hidden assumptions, edges, and success criteria → **draft** a plan → **present it for one decision** (a hard gate: start now / cross-review first / revise). Only if you pick cross-review does the plan go to the other model; the revised version comes back for sign-off. After approval the PM uses work-conserving scheduling, runs the **two-stage review**, and holds the **verification gate**. At task end, reusable facts are offered as a separate, enumerated write; read approval never implies write approval. See the [PM orchestration reference](references/pm-orchestration.md) and [memory protocol](references/memory.md) for details.
+For a full-tier task the flow is: **ask whether to route shared project memory** when history may help (default: skip; the task-scoped approval names the metadata scan, files, and context budget) → **grill** the requirements — multiple-choice first, batching independent questions — to surface hidden assumptions, edges, and success criteria → **draft** a plan → **present it for one decision** (a hard gate: start now / cross-review first / revise). Only if you pick cross-review does the plan go to the other model; the revised version comes back for sign-off. After approval the PM uses work-conserving scheduling, gives each flat child agent a minimal work order/context pack, accepts only a bounded completion receipt, runs the **two-stage review**, and holds the **verification gate**. At task end, reusable facts are offered as a separate, enumerated write; read approval never implies write approval. See the [PM orchestration reference](references/pm-orchestration.md) and [memory protocol](references/memory.md) for details.
 
 Cross-review uses one stable wrapper; the full plan always travels over stdin:
 

README.zh-CN.md

@@ -2,7 +2,7 @@
 
 # starks
 
-**一个个人「任务启动器」skill，同时适配 Claude Code 与 Codex CLI。**
+**把一句模糊需求送到可验证交付：任务分档、Claude↔Codex 可选互审、轻装 PM 子代理，以及“没证据不算完”。**
 
 [English](README.md) | 简体中文
 
@@ -15,19 +15,50 @@
 
 ## 为什么做 starks？
 
-单个模型存在系统性盲区——独自审查自己的方案，往往看不见自己看不见的东西。但简单任务不该被一套重流程拖累，所以 starks 先**按任务分档**决定走多重：琐碎的直接做，复杂的才上全流程。在关键节点，让**另一个**模型（Claude↔Codex）互审方案，能显著降低出错率。一句话：用最轻的开销解决简单事，用跨模型互审守住复杂事。
+很多 Agent 工作流不是太随意，就是太讲仪式：大任务缺少约束，小改动却被流程拖慢。starks 会自己分档——小事轻装上阵，复杂任务才进入需求拷问、方案门禁、PM 编排、两阶段审查和完成验证。
+
+它最有辨识度的设计在两个地方：方案阶段由**用户**决定要不要让 Claude 与 Codex 互相挑刺；执行阶段由主 PM 单向整理最小上下文，子代理不用反复吞 Session、记忆库和整套项目文档。
+
+## 特色功能
+
+- **任务分档**——trivial / 轻量 / 完整三档按风险匹配流程。简单任务不交“流程税”，真正复杂的任务才走全套。
+- **跨模型互审（用户可选）**——方案门禁只给三个清楚选项：**直接开干 / 先让另一端模型互审 / 修改方案**。Claude↔Codex 互审不自动触发，也不会失败后偷偷跳过。
+- **持续补位调度**——依赖 DAG 与 Ready 队列一有安全任务就填补空闲槽位；强耦合切片保持串行，不为看起来“多线程”而硬拆。
+- **轻装子代理**——主 PM 给每个单层子代理一张 **“派活单 + 随身小抄”**。子代理不重读 Session、共享记忆、通用项目文档和近期提交，完工只交一张有长度边界的 **“收工小票”**。
+- **真实进度看板**——主 PM 保持响应，只展示真实状态，不虚构百分比和 ETA；执行中仍可接收 `QUERY`、`ADD`、`CHANGE`、`REPLACE`、`PRIORITY`。
+- **两阶段审查**——先核对需求与规格，再检查代码质量；不合格切片有限回炉，不会混进一句模糊的“已完成”。
+- **完成门禁**——宣称「完成 / 通过 / 修好」之前，必须有与验收标准对应的当场验证证据。
+- **受控跨项目记忆**——Claude 与 Codex 可以共享 Obsidian 事实，但绝不自动加载整个库；读取需按任务授权且有预算，写入需单独枚举确认，路由优先使用脱敏稳定的 `repo_id`。
+- **双平台、防套娃**——Claude Code 与 Codex 共用一份 `SKILL.md`；一次性互审 Agent 只给意见就退出，不会反向再次调用 starks。
+
+## 招牌 PM 工作流
+
+```text
+用户需求
+  └─ 任务分档 → 需求拷问 → 起草方案
+                              └─ 用户三选：开干 / 跨模型互审 / 改方案
+                                               │
+PM：依赖 DAG + Ready 队列                       │ 可选 Claude↔Codex 互审
+  ├─ 派活单 + 随身小抄 → 单层子代理 A ─┐        │
+  ├─ 派活单 + 随身小抄 → 单层子代理 B ─┼─→ 收工小票 ─┘
+  └─ 实时更新看板 + 继续接用户新需求 ──→ 规格审查 → 质量审查 → 完成验证
+```
+
+主 PM 是唯一的上下文汇合点。子代理只拿到目标、允许读写的文件、必要直接依赖、约束、验收标准和证据要求，而不是整段对话。它可以查看派活单点名的目标文件、必要直接依赖和强制生效的项目规则；发现信息不足就报告 **“缺料”**，不能自行扩大范围。只有 PM 可以派代理，因此代理树始终只有一层，清楚、可控、不套娃。
 
-## 特性
+每个子代理最后只交一张结构化小票：
+
+```text
+【收工小票】
+- 收工状态：已交卷 / 缺料 / 等老板拍板 / 翻车
+- 动了什么：...
+- 验收证据：...
+- 留下的雷：...
+- 产物位置：...
+- 建议下一棒：...
+```
 
-- **任务分档**——trivial / 轻量 / 完整三档，先判断再决定走多重，不让重流程拖累简单任务。
-- **跨模型互审（用户可选）**——关键节点把方案交给另一端模型（Claude↔Codex）补盲区、纠错；由用户拍板是否启用，不自动触发。
-- **持续补位调度**——完整任务先建立依赖 DAG 与 Ready 队列，安全的 Ready 工作会立即填满空闲槽位；强耦合工作保持串行，不为追求并发而强拆。
-- **真实进度看板**——主 PM 保持响应，在 commentary 展示实时进度，并在执行中继续接收 `QUERY`、`ADD`、`CHANGE`、`REPLACE`、`PRIORITY` 类消息。
-- **两阶段审查**——先查规格合规，再查代码质量；不过则回炉。
-- **完成门禁**——宣称「完成 / 通过 / 修好」之前，必须有当场跑出的验证证据。
-- **受控跨项目记忆**——Claude 与 Codex 可共享 Obsidian 事实，但默认不搜索、不列举、不读写；读取按任务授权并受预算约束，写入须另行枚举和确认。
-- **双平台**——Claude Code 与 Codex CLI 共用同一份 skill 契约。
-- **防递归守卫**——被另一端模型调起做一次性互审时，自动跳过主流程，不会无限套娃。
+这张小票直接进入实时看板和审查队列，不把原始长日志、巨型 diff 或重复的项目上下文重新灌回主 PM。
 
 ## 环境要求
 
@@ -74,7 +105,7 @@ starks 先对任务**分档**，再决定走多重：
   2. **拷问需求**——多选优先，互不依赖的小问题合并一次问，挖出隐藏假设、边界条件与成功标准。
   3. **起草方案**——收口需求并做轻量任务拆解。
   4. **呈现方案 + 用户定夺**——把方案交给用户三选：**A 直接开干 / B 先让另一端模型互审再定 / C 修改方案**。仅当选 B 才跑跨模型互审，整合修订版后回到本步重新定夺。互审不自动触发，也不闷头跳过。
-  5. **PM 持续调度子代理**——安全的 Ready 工作会在槽位释放后持续补位，无需等待整波完成；写集合冲突或强耦合的工作仍保持串行。
+  5. **PM 持续调度子代理**——安全的 Ready 工作会在槽位释放后持续补位，无需等待整波完成；PM 用“派活单 + 随身小抄”给最小上下文，子代理不套娃、不自行扩域，只用“收工小票”回传结果。
   6. **两阶段审查**——先查规格合规，再查代码质量；不过回炉，最多 2 次，仍不过交回用户定夺。
   7. **完成门禁**——当场跑出验证证据才能宣称「完成 / 通过」。
   8. **写入前询问**——任务终局有可复用事实时，枚举目标文件和事实后单独询问；读取授权不能复用为写入授权。

SKILL.md

@@ -60,7 +60,7 @@ description: Use when starting real work — building a feature, adding or chang
 1. **拷问 grill** — 先按需询问是否读取记忆；仅获准后按预算读取，再读相关文件与近期 commit，集中提问隐藏假设、边界和成功标准。
 2. **起草方案** — 收口需求并拆解任务，不另造冗长 plan 文件。
 3. **呈现方案 + 一次定夺** — 让用户选 **A 直接开干 / B 先让另一个模型（Claude↔Codex）互审再定 / C 改方案**。仅 B 运行互审，整合修订后回到本步再次定夺；不得自动互审或闷头跳过不提。
-4. **PM 编排** — 维护依赖图与 `Ready` 队列；有安全任务且可用并发槽位空闲就立即补位，不等待整波。并行写集合必须互斥，冲突时顺序执行或使用隔离 worktree；不得为追求代理数量硬拆任务。
+4. **PM 编排** — 维护依赖图与 `Ready` 队列，用“派活单”派发、用“收工小票”回收；有安全任务且可用并发槽位空闲就立即补位，不等待整波。并行写集合必须互斥，冲突时顺序执行或使用隔离 worktree；不得为追求代理数量硬拆任务。
 5. **两阶段审查** — 先按 `prompts/spec-review.md` 查 spec 合规，再按 `prompts/code-review.md` 查代码质量；不过就回炉，最多回炉 2 次，仍不过则报告卡点并让用户定夺。
 6. **完成门禁** — 当场运行能证明验收标准的完整验证，读清结果后才可作完成声明。
 7. **记忆收尾** — 任务终局且有实质可复用进展时最多询问一次；仅用户对枚举内容明确同意且平台规则允许才写入。
@@ -75,7 +75,8 @@ description: Use when starting real work — building a feature, adding or chang
 
 ## PM 与审查边界
 
-- 子代理 prompt 必须 focused、self-contained，并写清 focused goal、write ownership、output 与 acceptance；
+- 子代理只接收主 PM 生成的“派活单 + 随身小抄”，不得主动读取 session、项目记忆、通用项目文档或近期 commit；仅可读取点名目标文件、必要直接依赖与强制生效的项目规则，缺料就回报，不得自行扩域；
+- 只有主 PM 能派子代理；子代理与 reviewer 不得再派生代理。返回必须使用“收工小票”，没有合格小票不进入审查；
 - 平台支持显式模型参数时才请求 `STARKS_AGENT_MODEL`，否则继承平台配置并如实说明；
 - 主 PM 须保持响应：存在可委派任务时不长期占用大块实现，并在 commentary 展示真实看板，不虚构百分比或 ETA；
 - 用户变更已批准的计划、架构或验收标准时，只暂停受影响切片，并重新打开 HARD-GATE；
@@ -96,6 +97,6 @@ description: Use when starting real work — building a feature, adding or chang
 |---|---|
 | 把完整档降成轻量以绕过确认 | 重新分档；完整档回到 HARD-GATE。 |
 | 自动跑互审、完全不提互审，或失败后静默略过 | 回到用户三选；失败明确报告并重新授权。 |
-| 超出可用槽位、并行写集合相撞，或伪称指定了不受支持的模型 | 缩小并行、隔离写集，并如实说明平台能力。 |
+| 超出可用槽位、并行写集合相撞、子代理套娃，或伪称指定了不受支持的模型 | 缩小并行、隔离写集、收回主 PM 调度，并如实说明平台能力。 |
 | 没验证就说“应该没问题 / 已完成” | 回到完成门禁，取得新鲜证据。 |
 | 未询问就扫描/读写记忆、超预算、复用读取授权写入，或触碰 `private/` | 停止操作并报告；不得绕过权限。 |