@namewta/speculo 1.0.22 → 2.0.1

package/template/skills/archive-and-consolidate/references/consolidation-rules.md

@@ -1,69 +0,0 @@
-# Consolidation Rules
-
-从已完成 change 的知识产物中提取、分类并合并到 workflow state root 声明的持久化 store。
-
-## 提取来源
-
-对每个候选 change，扫描以下知识产物：
-
-1. Evidence 与 Goal Plan — 交付边界、验证证据和残余风险
-2. Change 自身的 ADR.md — 架构决策记录
-3. LOG.md — 设计决策日志（可能含未正式记录的 ADR）
-4. CONTEXT.md — 项目规范术语
-5. diagnosis、reviews、prototypes、questionnaires 和任何 workflow 自定义知识产物
-
-## Store 映射与合并策略
-
-### adr/（架构决策记录目录）
-
-- **提取条件**：满足三项 ADR 特征（不可逆 + 令人意外 + 真实权衡）。
-- **序号分配**：扫描现有 `adr/` 中最大序号，新 ADR 取 N+1，四位零填充（`0001`、`0002`...）。
-- **文件命名**：`<NNNN>-<kebab-slug>.md`。
-- **内容格式**：标题、状态（Accepted）、日期、决策上下文、决策内容、后果。
-- **Supersede 处理**：若新 ADR 取代旧 ADR，在旧 ADR 开头添加 `> **Superseded by [ADR-NNNN](./NNNN-<slug>.md)**`；不删除旧 ADR。
-- **从 LOG 提升**：LOG.md 中满足 ADR 标准且尚未写入 change ADR.md 的决策 → 创建正式 ADR，注明"从 LOG.md 提升"；已有 change ADR 时只评估该唯一候选，不重复生成。
-
-### context/（领域词汇表目录）
-
-- **提取条件**：项目特有的领域术语，不是通用编程概念。
-- **合并方式**：将新术语合并到 `context/` 目录下的现有术语文件中。若目录为空，创建首个术语文件。
-- **条目格式**：遵循 `**术语名**：定义` + `_Avoid_: 同义词` 格式。
-- **冲突检测**：若术语已在 context/ 中存在定义，比较两者：
-  - 一致 → 跳过（记录"已存在"）
-  - 不同 → 标记 `needs-confirmation`，展示两个版本
-- **保留现有**：已有的 `_Avoid_` 标注和术语分组不覆盖。
-- **术语更名**：若新术语取代旧术语，在旧术语的 `_Avoid_` 中保留旧名称，创建新术语条目。
-
-### 其他知识 store（若 INDEX.md 声明）
-
-若 `INDEX.md` 持久化约定表声明了 `adr/` 和 `context/` 以外的知识 store：
-
-- **提取条件**：按知识类型匹配最合适的 store。
-- **合并方式**：默认使用 append 语义；目录型 store 创建新文件，文件型 store 追加条目。
-- **冲突处理**：与已有内容矛盾 → 标记 `needs-confirmation`。
-- **未声明则跳过**：不向 INDEX.md 未声明的路径写入。
-
-## 保护规则
-
-- **永不盲覆盖**：所有写入使用 append/merge 语义；不会不经提示地覆盖已有内容。
-- **目录 store（adr/、context/）**：首次写入时若目录不存在则自动创建。
-- **不创建未声明 store**：只写入 INDEX.md 持久化约定表中声明的 store。
-- **来源溯源**：所有合并内容标注来源 change 名称和日期。
-- **禁止跨 workflow**：合并范围限定于当前 workflow 声明的 stores。
-
-## Store 创建策略
-
-默认行为（无显式声明时）：
-
-| store | 行为 |
-|-------|------|
-| `adr/` | 首次写入时自动创建目录 |
-| `context/` | 首次写入时自动创建目录 |
-| 其他已声明 store | 若不存在则跳过并警告；不自动创建 |
-
-## 完成标准
-
-- 每个 change 的知识产物都已扫描和分类。
-- 每个提取候选项已评定毕业状态和目标 store。
-- 冲突项已标记 `needs-confirmation` 并提供双方版本。
-- 合并计划中每项都有来源 change、目标 store、动作（create/merge/append）和判定理由。

package/template/skills/archive-and-consolidate/references/knowledge-graduation.md

@@ -1,53 +0,0 @@
-# Knowledge Graduation Criteria
-
-判定 change 中的知识是否值得提取到 workflow state root 声明的持久化 store。默认只提取满足标准的；其余归为 `ephemeral`，留在归档 change 中。
-
-## 毕业标准（三项满足任一即提取）
-
-1. **稳定机制**：知识描述的是持久架构模式、设计原则或系统约束，不是临时实现细节或过渡方案。
-   - ✅ "认证模块使用 JWT + refresh token 双令牌机制"
-   - ❌ "临时绕过了 rate limiter，等待 PR #342 合并后移除"
-
-2. **重复教训**：同一洞察在多个 change 中出现（>1 个 change 引用或触及）。
-   - ✅ 三个不同 change 都遇到"时区转换必须用 UTC 存储、展示层转换"的坑
-   - ❌ 仅在一个 change 的调试过程中发现，未被其他 change 证实
-
-3. **接手者必知**：缺少此知识会导致后续开发者做出错误决策或重复已解决的争论。
-   - ✅ "选择 PostgreSQL 而非 MongoDB 的原因：需要 ACID 事务和 JSONB 的混合查询能力"
-   - ❌ "lint 配置将 max-line-length 设为 120 而非 100"
-
-## 反毕业标准（满足任一项则不提取）
-
-- 仅适用于单次 change 的实现细节（具体行号、临时变量名、中间重构步骤）。
-- 已解决的临时变通方案（workaround 已被正式修复取代）。
-- 调试日志、故障排查过程记录（除非提炼出可复用的诊断方法）。
-- 脱离完整 change 上下文会产生误导的内容。
-- 纯个人偏好且无项目级约束力（"我习惯用 X"）。
-
-## 候选去重
-
-同一决定已由 change 自身的 ADR.md 充分捕获时，以该 ADR 作为唯一毕业候选，不再从 LOG、Evidence 或其他工件生成重复候选。这只消除重复，不跳过永久知识毕业评估；通过标准的 change ADR 仍应进入永久 `adr/` 合并计划。
-
-## 决策流程
-
-对每段待评估知识：
-
-```
-1. 满足任一毕业标准？ → 否 → ephemeral（留在归档 change）
-2. 触发任一反毕业标准？ → 是 → ephemeral
-3. 提取 → 进入合并计划
-```
-
-## 知识分类与目标映射
-
-| 知识类型 | 判定特征 | 目标 store |
-|---------|---------|-----------|
-| **架构决策** | 不可逆、令人意外、涉及真实权衡 | `adr/<NNNN>-<slug>.md` |
-| **领域术语** | 项目特有的概念定义，不是通用编程术语 | `context/` 目录（合并到术语文件） |
-| **领域模型/规则/教训** | 实体关系、显式约束、踩坑经验 | 若 INDEX.md 声明了对应 store 则映射；否则归入 `adr/`（作为决策记录）或保留 ephemeral |
-
-> **注意**：目标 store 以 `INDEX.md` 持久化约定表的实际声明为准。上表为默认映射。若 workflow 未声明某个 store，对应知识归入最接近的已声明 store 或保留 ephemeral。
-
-## Ephemeral 分类
-
-被判定为 `ephemeral` 的知识**不删除**——它随归档 change 保留在 `archive_root/<YYYY-MM>/<change>/` 中，供未来按需查阅。只是不提升到 workflow 级持久化 store。

package/template/skills/docs-sync/SKILL.md

@@ -1,32 +0,0 @@
----
-name: docs-sync
-description: Audit and update project documentation and AGENTS/CLAUDE handbooks for a confirmed Git range; use only for documentation synchronization.
-metadata: {"speculo-id": "docs-sync", "speculo-kind": "skill", "speculo-legacy-name": "Docs Sync"}
----
-
-# Docs Sync
-
-## Enter and select effects
-
-Use only for requested documentation synchronization, not implementation, repository cleanup or arbitrary commits. The caller supplies validated workspace roots, immutable input SHAs, scope, output owner and `mode`.
-
-| Mode | Select when | Allowed effects |
-|---|---|---|
-| `audit` (default) | User asks to inspect/review or has not authorized edits | Read only; return findings in the conversation. No report files, checkpoints, sidecars, staging or commits. |
-| `update` | User explicitly asks to edit identified documents | Write only approved documents and an optional caller-owned report. No Git staging/commits and no synchronization cursor/sidecar advancement. |
-| `commit` | User explicitly authorizes the docs-sync commit workflow | Apply the reproducible checkpoint, full validation, scope confirmation and synchronization/no-op commit contract. Never push or rewrite history. |
-
-Selecting the capability is not authorization for every mode. Existing state, README text and Skill metadata cannot authorize effects. Never silently upgrade `audit` or `update` to `commit`.
-
-## Procedure
-
-1. Read [mode and input rules](references/mode-contract.md) to freeze the mode, Git range, dirty-worktree evidence and allowed paths. Only `commit` reads [Git/state contract](references/git-state-contract.md). Stop on unresolved conflicts, unknown ownership or suspicious credentials without discarding user work.
-2. Read [workflow scope](references/workflow-scope-contract.md) to discover installed packages and unique owners. Audit proposes scope in the response; update uses explicitly approved targets; only commit confirms and persists cursors/sidecars.
-3. Read [document lifecycle](references/document-lifecycle-contract.md) and classify each affected document as add/update/delete/merge/keep/propose-only. Whole-file deletion and protected knowledge remain separately authorized; audit only reports proposals.
-4. Load only the relevant writing branch: README uses [README contract](references/readme-contract.md) and [writing guide](references/readme-writing-guide.md); CHANGELOG uses [changelog contract](references/changelog-contract.md); agent handbooks use [agents contract](references/agents-contract.md). Handbook mode defaults to incremental; missing handbook, topology change or explicit user request selects rebuild.
-5. For Agent-consumed instructions or pointers, read [agent writing](references/agents/agent-writing.md). Preserve source ownership, activation boundaries, required quantities and validation; do not shorten by removing safeguards. Project prose defaults to simplified Chinese, README.md remains English, CHANGELOG follows the existing language; do not translate code/URLs/versions.
-6. Verify factual changes and applicable project checks, reread output, and report input SHAs, dirty-source limitations, scope, actual effects, verification and blockers. Use [report shape](assets/report-template.md); audit returns it without writing, update marks `not-committed` and does not advance state, commit additionally returns [state](assets/state-template.json) and [workflow scope](assets/workflow-scope-template.json) for the owning command to commit and reread.
-
-## Stop and return
-
-Missing scope, source ownership, required reference, permission, validation or recovery evidence stops the affected write set. Do not fabricate completion or clean unrelated work. A report and a green structure check are not proof that the underlying documentation is correct. Return results to the declared caller; do not create an independent Skill state tree.

package/template/skills/docs-sync/assets/report-template.md

@@ -1,46 +0,0 @@
----
-command: docs-sync
-mode: <bootstrap|incremental|no-op>
-handbook_mode: <incremental|rebuild>
-scope: <workspace|multi-workflow|workflow>
-workflows: []
-changes: []
-generated_at: <ISO-8601>
----
-
-# Docs Sync Report
-
-## Git Range
-
-- From: `<FROM_SHA|null>`
-- To: `<INPUT_HEAD>`
-- Replay: `git diff <FROM_SHA>..<INPUT_HEAD>` 或 `bootstrap current facts`
-
-## Workspace Cleanup
-
-[记录 checkpoint commit、显式文件清单和运行前验证；无需 checkpoint 时写 `none`。]
-
-## Confirmed Scopes
-
-[记录全局 project targets、各 workflow project/state targets、scope revision 和本次确认变化。]
-
-## Evidence And Lifecycle
-
-| Target | Action | Evidence | Result |
-|---|---|---|---|
-
-## Workflow Sources
-
-[按 workflow 记录读取的 WORKFLOW/PERSISTENCE、archive、声明 store 和受保护候选；空集合写 `[]`。]
-
-## Synced Assets
-
-[列出实际新增、修改、合并或删除的文档与知识资产；no-op 写 `[]`。]
-
-## Verification
-
-[记录实际运行的命令、结果与未运行原因。]
-
-## State
-
-[记录全局 state 与 sidecar 的 schema、revision、pending 迁移项和原子写入结果。]

package/template/skills/docs-sync/references/agents/agent-writing.md

@@ -1,75 +0,0 @@
-# Agent 文档写作
-
-任何由 agent 消费的文档的撰写参考——一份 skill、一个 `AGENTS.md` / `CLAUDE.md`、一份通过指针到达的文档。包装形式不同，撰写之道相同：同样的杠杆让每一份文档都可预测——agent 每次都走相同的*流程*，而不是产出相同的输出。
-
-## 上下文指针
-
-**上下文指针（context pointer）** 是 agent 上下文中持有的一条引用，它指明某份上下文之外的资料，并编码了到达它的条件。一份 skill 的 description 是指针；`AGENTS.md` 中一行指向某文档的引用，也是同一个东西。决定 agent 何时——以及多可靠地——到达该资料的，是指针的*措辞*，而不是它的目标。一个措辞薄弱的指针指向一份必读资料，就是一个变异 bug：先打磨措辞；只有打磨失败时，才把资料内联进来。
-
-指针承担两项工作——说明资料是什么，并列出应触发到达它的**分支**（branch 是文档处理的某个不同情况，因此不同运行会走不同的路径）。一个始终加载的指针，每个字都要在每一轮对话中付出成本，所以它比正文更需要被毫不留情地精简：
-
-- **前置引导词**——触发工作是在指针上完成的。
-- **每个分支一个触发器。** 只是给同一分支换了个说法的同义词，等于把同一个分支写了两遍；把它们合并，只保留真正不同的分支。
-- **删掉正文已经承载的身份信息。**
-
-## 两种负载
-
-你添加的每份文档和每个指针，都要花掉两种预算之一：
-
-- **上下文负载（context load）**——始终加载的资料对 agent 窗口的代价：`AGENTS.md` 里的一行、一份 skill 描述、任何每轮对话都待在上下文里的东西，无论是否触发，都在消耗 token 和注意力。
-- **认知负载（cognitive load）**——对人类的代价：存在哪些文档、何时该去取哪一份。人类就是索引。这不是需要最小化的成本——它是人类主动性的价格；在人类判断重要的地方花它，在无关紧要的地方拿掉它。
-
-只通过指针到达的资料，免去了上下文负载，代价是指针自身的那一行；完全没有指针的资料，则完全压在认知负载上。
-
-## 信息层级
-
-一份文档由两种内容类型构成——**步骤**（agent 执行的有序操作）和**参考**（按需查阅的定义、规则、事实）——两者自由混合：全是步骤（一份菜谱）、全是参考（一次 review 的规则、本技能），或两者兼有。核心决策是每一块内容在**信息层级**上所处的位置，这是一把按 agent 需要资料的即时程度排序的梯子：
-
-1. **文件内步骤**——第一层级：agent 做什么，按顺序。
-2. **文件内参考**——按需查阅。它常常是一个合理扁平的并列集合（一次 review 的全部规则在同一条横档上）——这没什么不好，不是坏味道。
-3. **外置参考（disclosed reference）**——推到独立文件里，通过上下文指针到达，只在指针触发时加载。从同一文件夹的兄弟文件，一直到住在任何地方、任何文档都能指向的完全外部参考。
-
-推得太少，顶层会臃肿；推得太多，你会把 agent 真正需要的资料藏起来。这个张力就是全部决策所在。
-
-**渐进式披露（progressive disclosure）** 是沿梯子向下的移动——从主文件中移出、放到指针后面——让顶层保持可读。它首先不是 token 优化：它是保护层级的方式。分支是最干净的披露测试：每个分支都要用到的内容内联保留，只有部分分支会碰到的内容推到指针后面。当一份文档有步骤时，本应披露的文件内参考会埋没这些步骤，让"照做"变成抛硬币——这不只是可读性杠杆，而是变异杠杆。
-
-**就近放置（co-location）** 是文件内部的伴侣：梯子决定一块内容*下探多深*，就近放置决定它落到那里后*旁边放着什么*。把一个概念的定义、规则和注意事项放在同一个标题下，而不是散落各处，这样读到一部分时，相邻部分也随之而来。判断标准：文档读起来应该像专门写给 agent 的文档——归组的内容如此，散落的内容则不然。（它与重复不同：重复是在两个地方重述同一层含义；散落是把一层含义打碎到多处。）
-
-**臃肿（sprawl）** 是这里的失败模式：一份文档单纯地太长，即使每一行都是活的、独一无二的。注意力在过剩内容中变薄，而每一行额外的内容都是又多一条需要保持相关的东西。解药就是那把梯子：把参考披露到指针后面，并按分支或序列拆分，让每条路径只携带它需要的东西。
-
-## 步骤与完成标准
-
-每个步骤都以一个**完成标准（completion criterion）** 收尾——告诉 agent 工作已完成的条件。两个属性使它成为杠杆：
-
-- **清晰度**——agent 能否区分"完成"与"未完成"？一个模糊的边界（"已达成理解"）会招致**提前完成（premature completion）**：在步骤真正完成之前就结束它，注意力滑向*看起来完成了*。仍可见的后续步骤——**完成后的步骤（post-completion steps）**——提供拉力；标准的清晰度是阻力。按顺序防御：**先磨利边界**（局部且廉价）；只有当边界不可约地模糊*且*你观察到赶工行为时，才通过拆分序列隐藏后续步骤——而隐藏只在真正的上下文边界处有效（一次交接或一个 subagent 派遣；内联调用会让后续步骤留在上下文中，什么也清不掉）。
-- **要求强度（demand）**——它要求多少。"每个修改过的模型都被说明"逼出彻底的工作，而"生成一份变更清单"不会。要求强度驱动**苦功（legwork）**——agent 在工作内部做的挖掘，它藏在措辞里而不是写成独立步骤——并且它不绑定步骤："每条规则都适用"绑定一整个扁平的参考集合，正如"每个步骤都完成"绑定一条序列，这正是一份纯参考文档仍然带着穷尽性门槛的方式。
-
-最强的标准既可核查又穷尽。
-
-## 何时拆分
-
-把一份文档拆成两份，要花掉两种负载之一，所以只有在切口值得时才拆：
-
-- **按序列拆分**——拆分一段步骤序列，此时完成后的步骤会诱使 agent 赶工眼前的步骤。让它们不可见，会驱动当前任务上更多的苦功。当心反向情况：合并序列会让每个步骤都暴露在后续步骤面前，招致提前完成。
-
-## 引导词
-
-**引导词（leading word）** 是一个早已存在于模型预训练中的紧凑概念，agent 在运行文档时用它思考（_lesson_、_fog of war_、_tracer bullets_）。以 token 形式重复、永不用句子重述，它累积出一个分布式的定义，并以最少的 token 锚定一整个行为区域——通过征用模型已有的先验。自己造词也行，只要定义清楚，但一个生造的词征用不到任何先验——你在定义 token 上付出的，正是预训练词免费给予的；先用已有的词。
-
-它双重锚定。在正文里是*执行*：每次该词出现，agent 都伸手取同样的行为；在扁平参考内部，它把注意力聚焦到要找的一类事物上。在指针里是*调用*：当同一个词同时存在于你的 prompts、你的文档和你的代码库时，agent 会把这份共享语言与资料联系起来，更可靠地到达它。
-
-寻找用引导词重构的机会。一个在三个地方展开的三件套、一个花一句话指向同一个概念的指针——每一处都是渴望塌缩成单个 token 的段落：
-
-- "fast, deterministic, low-overhead" → _tight_（一个 _tight_ 循环）。
-- "a loop you believe in" → _red_——一个模糊的闸门变成二元的可观察状态（遇到 bug 循环变 _red_，或不变）。
-
-你赢两次：更少的 token，以及一个更锋利的钩子让 agent 挂上它的思考。假设每份文档都携带着引导词可以退役的重述——去把它们找出来。
-
-**否定式表述（negation）** 是这个杠杆旁边的失败模式：用禁止来引导，会把被禁止的行为拖进上下文，让它变得*更容易*被激活，而不是更难。_不要想大象_，然后脑子里就全是大象；否定是一个脆弱的修饰符，会被强激活的概念碾过去，于是禁令有一半读起来像是在指示去做那件事。用**肯定式**提示——陈述目标行为（"写一行注释"），让被禁止的行为永远不被说出来。只有当你实在无法用肯定句式表达时，一条禁令才配占有一席之地；即使如此，也要配上肯定的目标，让注意力落在"做什么"上。
-
-## 精简
-
-- 让每个含义都有**单一事实来源（single source of truth）**：一个权威的位置，这样改变行为就是改一处。**重复（duplication）**——同一含义出现在多个地方——耗费维护成本和 token，并把一个含义在梯子上的显著性抬到超过它实际等级的高度。（它是引导词的意外反面：引导词是有意重复一个 token，从来不是重复含义。）
-- **环境（environment）** 也是事实来源——`package.json` 脚本、配置文件、目录布局、`--help` 输出——而重述环境的文档就是一份**缓存（cache）**：一次查询的副本，只有当查询本身昂贵时才值得负担这份负载。只缓存 agent 无法通过查找得到的东西：不成文的约定、选择背后的原因、任何配置文件都不会招认的坑。把"一个文件一条命令"式的查找留给环境，在那里它们不会过期。
-- 逐行检查**相关性（relevance）**：它是否仍然与文档所做的事有关？一行内容失去相关性，要么因为从未作用于任务（纯叙述，或一个本应披露的分支），要么因为行为或世界变化而过期。更短的文档更容易保持相关。没有精简纪律，默认的归宿是**沉积（sediment）**：一层层过期的内容沉淀下来——因为添加感觉安全、删除感觉冒险——直到你必须钻穿它们才能找到仍然活着的东西。
-- 逐句猎杀**无效指令（no-ops）**：一句模型本来就默认遵守的指令，花了负载却没说出任何东西。判断标准——它是否改变了相对默认的行为？——是模型相对的，不是读者相对的：两个人争论一句无效指令，争论的是默认是什么，而且要靠运行文档来裁决，不是靠辩论。当一句指令不合格时，删除整句，而不是从里面删词。这个判断标准也给引导词打分：一个弱到打不过默认的词（在 agent 已经够"be thorough"的地方写*要彻底*）就是无效指令，修法是换一个更强的词（*毫不留情*），而不是换一种技巧。

package/template/skills/docs-sync/references/agents/claude-redirect.md

@@ -1,39 +0,0 @@
-# CLAUDE.md Redirect Contract
-
-## 规则
-
-需要 Claude 适配且有独立 AGENTS 作用域的目录使用轻量导入文件，新增或明确归工具所有的 `CLAUDE.md` 内容为：
-
-```
-# CLAUDE.md
-
-@AGENTS.md
-```
-
-此格式与 [`../agents-contract.md`](../agents-contract.md) 的规定一致（该契约为权威）：`AGENTS.md` 始终是唯一的权威代理手册，`CLAUDE.md` 永远只是宿主导入入口。
-
-## 设计缘由
-
-- Claude Code 会读取 `CLAUDE.md` 获取项目/模块级指令。
-- 内容全部在 `AGENTS.md` 中，`CLAUDE.md` 只是入口指针。
-- 零维护成本：`AGENTS.md` 更新时不需要同步 `CLAUDE.md`。
-
-## 生成条件
-
-- 目录有独立手册且需要 Claude 适配 → 生成 `CLAUDE.md`
-- scripts-docs 同样按独立作用域和 Claude 适配需求判断，不无条件生成
-- 目录已有多行非重定向 `CLAUDE.md` → 向用户确认后改写为重定向，原内容全量迁移到 `AGENTS.md`（处置与 agents-contract 一致）
-- 目录已有精确匹配的工具生成桥接 → 可更新导入；用户修改或 owner 不明时保留并报告差异
-
-## 不生成 CLAUDE.md 的目录
-
-- 没有独立作用域约束且无需手册的目录
-- 忽略目录（`node_modules` 等）
-- `.git` 目录
-- 任何已在 `.gitignore` 中的目录
-
-## 文件格式
-
-- 三行：`# CLAUDE.md` 标题、空行、@AGENTS.md 导入
-- 无 frontmatter、无额外内容
-- 文件以换行符结尾（POSIX 约定）

package/template/skills/docs-sync/references/agents/content-contract.md

@@ -1,213 +0,0 @@
-# Content Contract
-
-所有 AGENTS.md 都必须写成**模块导读**，不能退化成目录卡片。每个章节都要回答明确问题。
-
-## 必填章节
-
-每个 AGENTS.md 必须包含以下章节。章节名称保留英文，正文使用中文。
-
-### 1. `Scope`
-
-回答：
-- 这个文件覆盖哪些目录？
-- 哪些更深层 manifest 会接管说明？
-- 哪些内容明确不覆盖？
-
-写法：2-4 句话，边界清晰。
-
-### 2. `Module Positioning`
-
-回答：
-- 当前目录是什么角色？
-- 它在整个项目中承担什么位置？
-- 为什么它存在？
-
-写法：标记角色（如 `capability-module`），点出它在项目分层中的坐标。
-
-### 3. `Directory Structure`
-
-回答：
-- 直接子目录有哪些？各自承担什么？
-- 关键文件有哪些？它们为什么重要？
-- 主要实现区在哪？测试区在哪？
-
-写法：只列 5-10 项对排查问题有用的目录和文件，不做全量目录树。
-
-### 4. `Responsibilities`
-
-回答：
-- 当前模块负责什么？
-- 明确不负责什么？
-
-写法：用列表承载 3-6 条职责。负面影响（不负责什么）同样重要。
-
-### 5. `Core Logic`
-
-回答：
-- 模块如何工作？
-- 关键装配顺序、处理链路或数据流是什么？
-- 它的核心机制是什么？
-
-写法：3-6 句话解释主干逻辑。不要展开每个文件的细节。
-
-### 6. `Key Entry Points`
-
-回答：
-- 先看哪些具体文件？
-- 从哪个目录开始依次下钻？
-
-写法：**必须点名具体文件、类、目录或测试入口**。禁止只写 `src/`、`api/`、`controller/` 这类空泛词。
-
-好例子：
-- `src/main.ts` — 应用启动入口
-- `src/router/index.ts` — 路由注册
-- `src/api/user.ts` — 用户相关接口封装
-- `tests/user.spec.ts` — 用户模块测试
-
-差例子：
-- `src/` — 主实现
-- `api/` — 接口层
-
-### 7. `Usage And Change Notes`
-
-回答：
-- 典型使用入口是什么？
-- 修改时优先检查哪些配置、依赖或调用链？
-- 最容易误改的边界在哪里？
-
-写法：2-4 条高信息量可执行提醒。禁止写成“修改时注意兼容性”“按需查看相关代码”这类空话。
-
-好例子：
-- “新增接口时先确认 controller 所属归档单元，再同步检查 bo/vo 和前端接口契约。”
-- “改请求层时先检查 `packages/core`、环境变量和下载链路。”
-
-差例子：
-- “修改时注意兼容性。”
-- “需要时查看相关代码。”
-
-### 8. `Dependencies And Collaboration`
-
-回答：
-- 直接依赖了哪些项目/仓库内部模块？
-- 被哪些兄弟模块消费？
-- 模块间如何协作？
-
-写法：列表形式。区分“我依赖谁”和“谁依赖我”。
-
-### 9. `Investigation Rule`
-
-回答：
-- 当本文件不够时，按什么顺序继续读源码？
-- 文档与代码冲突时怎么办？
-
-写法：**必须写成可执行顺序**。每一步点名具体文件或目录。
-
-好例子：
-```
-1. 先读 pom.xml 了解依赖和模块声明。
-2. 再读 src/main/java/.../Application.java 了解启动装配。
-3. 然后按 controller → service → domain → mapper 顺序下钻。
-4. 仍不够时，读 src/test/ 了解预期行为。
-5. 文档与代码冲突时以代码事实为准。
-```
-
-差例子：
-- “需要时查看源码。”
-- “先看 controller、service、domain。”
-
-### 10. `Core Commands`
-
-回答：
-- 当前模块最常用的构建/测试/运行命令是什么？
-- 哪些命令是非标准的、AGENTS 无法从 manifest 推断的？
-
-写法：只写 AGENTS 猜不到的命令。从 `package.json` scripts 或 `pom.xml` 插件显而易见的命令不用写。
-
-### 11. `Verification`
-
-回答：
-- 最小可执行验证是什么？
-- 如何确认模块正常工作？
-
-写法：1-2 条具体命令。
-
-### 12. `Routing`
-
-回答：
-- 上级 manifest 在哪？
-- 子级 manifest 有哪些？
-
-写法：
-```
-- 上级：[../AGENTS.md](../AGENTS.md)
-- 子级：
-  - [子模块A](./子模块A/AGENTS.md) — 一句话定位
-  - [子模块B](./子模块B/AGENTS.md) — 一句话定位
-```
-
-每个子级链接后附一句话定位。`repo-root` 无上级，不写上级行。
-
-### 13. `References`
-
-回答：
-- 关键 manifest、配置、源码入口、测试入口在哪？
-
-写法：用相对路径列出 3-8 个关键引用。只列对 AGENTS 有用的，不做全文索引。
-
-## 禁止项
-
-以下内容**一律禁止**出现在 AGENTS.md 中：
-
-| 禁止 | 原因 |
-|------|------|
-| 逐文件的结构列表 | AGENTS 可通过阅读代码库发现 |
-| 标准语言约定 | AGENTS 已知（如“React 是声明式 UI 库”） |
-| 通用建议 | “编写干净的代码”“处理错误”等无操作价值 |
-| 从 manifest 显而易见的命令 | 如 `npm test`、`mvn clean install` |
-| 经常变化的信息 | 版本号、日期、人员名单——用路径引用源文件 |
-| 长教程或演练 | 移到 references 中 |
-| `Key Entry Points` 中只写目录名 | 必须点名具体文件、类 |
-| `Usage And Change Notes` 中的空话 | 必须可执行 |
-| `Investigation Rule` 中的空话 | 必须有具体文件和顺序 |
-| 复制大段源码或配置全文 | 引用路径即可 |
-| 宣传性语言 | “业界领先的”“强大的”“优雅的” |
-
-## 角色额外要求
-
-### `repo-root`
-
-- 解释顶层分层理由，不只列模块名
-- 写清“从根级定位问题后，下一步怎么进入子模块”
-- `Usage And Change Notes` 要提醒：根级改动容易联动 workspace 配置、顶层 scripts 和索引
-
-### `scripts-docs`
-
-- 说明独有规则的实际作用域；没有 manifest 时不虚构模块信息
-- 概括各类子树各自承载什么
-- 区分“可直接执行的脚本”“SQL 资产”“配置模板”“运行时数据目录”
-- 明确“只到根目录这一层”，不为子目录生成子级文档
-- `Usage And Change Notes` 必须写清：哪些可运行、哪些只是资产索引
-
-### `aggregator`
-
-- 解释当前聚合为什么存在
-- 给出子模块的分组逻辑，不只是列模块名
-- 写清“哪些问题必须进入哪个子模块继续调查”
-
-### `runnable-app`
-
-- 写清启动入口、运行时装配
-- 写清内部依赖模块如何接入
-- `Usage And Change Notes` 要提醒：运行时改动应先看哪些入口、哪些配置联动最易漏
-
-### `capability-module`
-
-- 写清导出面、核心分层
-- 写清内部依赖与上游消费方
-- `Usage And Change Notes` 要提醒：新增接口/类型/配置时优先检查的层次
-
-### `contract-module`
-
-- 写清约束了什么、被谁消费
-- 没有 `src/` 时显式说明这是约束层
-- `Usage And Change Notes` 要提醒：改约束会影响哪些消费方