gathering-feature

收集特性 🌲🐾

鼓声回荡在森林中。但这一次，一切都不一样。指挥者站在林间空地的中央——不是亲自做事，而是统筹安排。每只动物都带着全新的视角到来，阅读自己的指示，并全神贯注地工作。没有上下文疲劳。没有敷衍了事。也没有“代码会自己说明一切”。八只动物，八个全新的头脑，共同打造出恰到好处的特性。

何时召集

• 从零开始构建完整特性
• 涉及前端、后端和数据库的主要功能
• 需要探索、实现、测试和编写文档的特性
• 希望以稳定的质量完成每个阶段，处理整个生命周期时

重要： 这次集会是一个指挥者。它绝不会直接编写代码、测试或文档，而是派遣子 Agent——每只动物对应一个——并为其提供隔离的上下文和特定的模型。指挥者只负责管理交接和关卡检查。

---

集会

SUMMON → DISPATCH → GATE → DISPATCH → GATE → ... → CHORUS
  ↓         ↓        ↓        ↓        ↓              ↓
Spec    Bloodhound  Check  Elephant  Check    Final Verification
(self)   (haiku)     ✓     (opus)    ✓         & Summary

派遣的动物

顺序	动物	模型	职责	全新视角？
1	🐕 寻血猎犬	haiku	勘察代码库，绘制领域地图	是 — 只会看到规格说明
2	🐘 大象	opus	跨文件构建特性	是 — 只会看到规格说明和领域地图
3	🐢 乌龟	opus	加固安全性（对抗式审查）	是 — 只会看到文件列表，不会看到构建思路
4	🦫 河狸	sonnet	根据行为编写测试	是 — 只会看到文件列表，不会看到实现细节
5a	🦝 浣熊	sonnet	安全审计与清理	是 — 并行执行
5b	🦌 鹿	sonnet	无障碍审计	是 — 并行执行
5c	🦊 狐狸	sonnet	性能优化	是 — 并行执行
6	🦉 猫头鹰	opus	编写实际文档	是 — 接收完整摘要

参考： 加载 references/conductor-dispatch.md，查看子 Agent 的确切提示词和交接格式

---

阶段 1：召集

鼓声响起。指挥者步入林间空地……

指挥者（此技能）接收特性请求，并准备派遣计划：

• 澄清：此特性有什么作用？哪些用户会受益？范围包括什么？
• 确定受影响的软件包及大致文件数量
• 判断大象是否需要多 Agent 派遣（多个软件包中的文件超过 15 个）
• 与用户确认此次集会

输出： 确认特性规格说明、预计范围和派遣计划。

---

阶段 2：勘察（寻血猎犬）

指挥者发出信号。寻血猎犬进入森林……

Agent(bloodhound, model: haiku)
  Input:  feature spec only
  Reads:  bloodhound-scout/SKILL.md (MANDATORY)
  Output: territory map

派遣一个 haiku 子 Agent 勘察代码库。寻血猎犬只会收到特性规格说明——没有任何观点，也没有预先分析。它会阅读自己的技能文件，并执行完整的 SCENT → TRACK → HUNT → REPORT 工作流。

交接给指挥者： 领域地图（待修改文件、发现的模式、集成点、现有惯例、潜在障碍）。

关卡检查： 收到领域地图，且至少包含文件列表、模式摘要和集成点。如果内容不完整，则带着具体问题恢复该 Agent 的工作。

---

阶段 3：构建（大象）

地面震颤，大象到来……

Agent(elephant, model: opus)
  Input:  feature spec + territory map (from Bloodhound)
  Reads:  elephant-build/SKILL.md + references (MANDATORY)
  Output: built files list + implementation summary

派遣一个 opus 子 Agent 来构建该功能。大象会收到规格说明和领域地图——而不是寻血猎犬的推理过程，只会收到其结构化输出。

多 Agent 派遣（范围超过 15 个文件或涉及 3 个以上软件包时）：

Agent(elephant-backend, model: opus)   → API routes, services, migrations
Agent(elephant-frontend, model: opus)  → Svelte components, stores, pages    PARALLEL
Agent(elephant-schema, model: sonnet)  → Database migrations, types

Then: Agent(elephant-wire, model: opus) → Integration wiring across all three

每头小象都会阅读 elephant-build/SKILL.md，并且只负责自己的领域。

大象必须遵循的跨领域标准：

• 为所有错误路径标注错误代码（buildErrorJson、throwGroveError）
• 在边界处确保 Rootwork 类型安全（parseFormData、safeJsonParse）
• 参考：AgentUsage/error_handling.md、AgentUsage/rootwork_type_safety.md

交接给指挥者： 文件列表（每个新建或修改的文件）、实现摘要（构建了什么、关键决策）、任何未解决的问题。

关卡检查： 运行 gw ci --affected --fail-fast——至少必须通过编译。如果构建失败，向大象 Agent 提供错误输出并让其继续处理。

---

阶段 4：强化（乌龟）

乌龟缓缓靠近。它只看得到已构建的内容——看不到构建缘由……

Agent(turtle, model: opus)
  Input:  file list ONLY (not Elephant's reasoning — fresh adversarial eyes)
  Reads:  turtle-harden/SKILL.md + references (MANDATORY)
  Output: hardening report + applied fixes

派遣一个 opus 子 Agent 进行安全强化。乌龟只会收到文件列表——不会收到大象的实现摘要。这是有意为之：乌龟应该以对抗性的全新视角审查代码，而不是认同构建者的推理。

乌龟强化的内容：

• 输入验证（所有入口点都使用 Zod 模式）
• 输出编码（根据上下文进行编码，富文本使用 DOMPurify）
• 参数化查询（SQL 中不得使用字符串拼接）
• 安全标头（带随机数的 CSP、HSTS、X-Frame）
• 标注错误代码（验证大象是否正确使用）
• Rootwork 边界安全（验证信任边界处没有 as 类型断言）

交接给指挥者： 强化报告（发现了什么、修复了什么、应用了哪些防御层）、更新后的文件列表。

关卡检查： 运行 gw ci --affected --fail-fast——强化后仍必须通过编译。如果出现问题，让乌龟 Agent 继续处理。

---

阶段 5：测试（海狸）

海狸勘察溪流。它不知道水坝是如何建成的——只知道水坝应该能承受什么……

Agent(beaver, model: sonnet)
  Input:  file list + feature spec (NOT implementation details)
  Reads:  beaver-build/SKILL.md + references (MANDATORY)
  Output: test suite + test results

派遣一个 sonnet 子 Agent 编写测试。海狸会收到文件列表和原始功能规格说明——而不是大象的实现摘要或乌龟的强化报告。测试应该依据行为编写，而不是通过阅读代码编写。

海狸测试的内容：

• 功能行为（依据规格说明，而非代码）
• 安全回归（API 路由返回正确的 error_code 字段）
• 边界验证（拒绝错误输入）
• Catch 块类型守卫（isRedirect/isHttpError）

交接给指挥者： 测试文件列表、测试结果（通过/失败数量）、发现的任何行为缺口。

关卡检查： 所有测试都必须通过。运行 gw ci --affected --fail-fast --diagnose。如果测试失败，向海狸 Agent 提供失败输出并让其继续处理。如果测试发现实现缺陷，记录下来，由指挥者决定是让大象还是乌龟继续处理。

---

阶段 6：审计（浣熊 + 鹿 + 狐狸——并行）

三只动物同时进入空地。它们各有不同的视角……

同时派遣三个子 Agent：

Agent(raccoon, model: sonnet)  → Input: file list + feature scope
  Reads: raccoon-audit/SKILL.md
  Focus: secrets, dead code, dependency audit, unsafe patterns

Agent(deer, model: sonnet)     → Input: UI file list + feature spec      PARALLEL
  Reads: deer-sense/SKILL.md
  Focus: keyboard nav, screen readers, contrast, touch targets

Agent(fox, model: sonnet)      → Input: hot path files + feature spec
  Reads: fox-optimize/SKILL.md
  Focus: bundle size, query performance, lazy loading

每只动物都独立工作，不会看到其他动物的发现。指挥者汇总三份报告。

交接给指挥者： 三份报告——审计发现、无障碍性发现、性能发现，以及各只动物进行的任何修复。

关卡检查： 审查全部三份报告。如果有动物发现了需要修复的问题：

• 安全问题 → 指挥者应用修复或重新派遣针对性的 Agent
• 无障碍性问题 → 指挥者应用修复
• 性能问题 → 指挥者应用修复
• 所有修复完成后，重新运行 gw ci --affected --fail-fast --diagnose

---

阶段 7：编写文档（猫头鹰）

猫头鹰睁开双眼。它听到了所有内容——现在，它要开口了……

Agent(owl, model: opus)
  Input:  FULL gathering summary (spec, territory map, file list,
          hardening report, test results, audit/a11y/perf reports)
  Reads:  owl-archive/SKILL.md + references (MANDATORY)
  Output: actual documentation written to files

派遣一个 opus 子 Agent 编写文档。猫头鹰会收到完整的调研摘要——它需要上下文才能写出有意义的文档。使用 Opus，因为编写文档需要亲切的语气、鲜明的风格，以及判断哪些内容值得记录的能力。

猫头鹰要编写的内容：

• 帮助文章或面向用户的文档（如果功能对用户可见）
• API 文档（如果新增了端点）
• 内联代码注释（用于解释不言自明的逻辑，而不是说“代码会说明一切”）
• 更新所有受影响的现有文档

交接给指挥者： 文档文件列表，以及所记录内容的摘要。

关卡检查： 确认文档文件存在且有实际内容（而非占位内容）。

---

阶段 8：合唱

黎明破晓。指挥者举起双手。森林开始歌唱……

指挥者运行最终验证并呈现摘要：

# Final verification — the whole gathering's work proven sound
pnpm install
gw ci --affected --fail-fast --diagnose

组件审查关卡（适用于包含 UI 组件的功能）：

在进行页面级验证之前，使用 Showroom 单独审查大象构建或修改的每个 UI 组件：

# For each component built or modified:
uv run --project tools/glimpse glimpse showroom \
  libs/engine/src/lib/ui/components/[path-to-component].svelte

# For new components, scaffold fixtures first:
uv run --project tools/glimpse glimpse showroom \
  libs/engine/src/lib/ui/components/[path-to-component].svelte --scaffold

必须解决所有 Showroom 合规性问题，才能继续。如果发现问题，请根据具体发现恢复大象 Agent 的工作。

视觉验证（适用于包含 UI 的功能）：

uv run --project tools/glimpse glimpse matrix \
  "http://localhost:5173/[feature-page]?subdomain=midnight-bloom" \
  --seasons autumn,winter --themes light,dark --logs --auto

完成报告：

🌲 GATHERING FEATURE COMPLETE

Feature: [Name]

DISPATCH LOG
  🐕 Bloodhound (haiku)  — [territory mapped, X files identified]
  🐘 Elephant (opus)      — [Y files built across Z packages]
  🐢 Turtle (opus)        — [N hardening fixes applied, M defense layers]
  🦫 Beaver (sonnet)      — [P tests written, all passing]
  🦝 Raccoon (sonnet)     — [audit clean / N issues fixed]
  🦌 Deer (sonnet)        — [a11y verified / N issues fixed]
  🦊 Fox (sonnet)         — [performance verified / N optimizations]
  🦉 Owl (opus)           — [documentation written at: paths]

GATE LOG
  After Scout:    ✅ territory map complete
  After Build:    ✅ compiles clean
  After Harden:   ✅ compiles clean, hardening applied
  After Test:     ✅ all tests pass
  After Audit:    ✅ findings resolved
  After Document: ✅ docs written (not stubs)
  Showroom:       ✅ all components pass compliance audit
  Final CI:       ✅ gw ci --affected passes

The forest grows. The feature lives.

---

指挥者规则

切勿亲自执行动物的工作

指挥者负责派遣，不负责侦察、构建、加固、测试、审查或编写文档。如果发现自己在写代码，请停下来——你应该派遣子 Agent。

全新视角是优势

乌龟和海狸有意接收比完整历史更少的上下文。乌龟看不到大象的推理过程（对抗式全新视角）。海狸看不到实现细节（行为测试）。这种隔离能带来更好的结果。

每次阶段转换都要检查关卡

每个动物完成工作后都要运行验证。不要让错误状态蔓延——尽早发现。

尽可能并行执行

浣熊、鹿和狐狸同时运行。三个全新的 Agent，分别关注不同事项，彼此之间不共享上下文。

重型阶段使用多个 Agent

如果大象要在多个软件包中修改 15 个或更多文件，请拆分为专注不同领域的子大象。每个都要阅读技能文件，各自处理负责的领域，然后由一个整合 Agent 汇总。

恢复，不要重启

如果关卡检查失败，请向未通过的 Agent 提供错误上下文并恢复其工作。不要启动新的 Agent——恢复工作的 Agent 已经掌握先前工作的上下文。

沟通

• “鼓声响起……”（召集）
• “正在派遣[动物]……”（启动子 Agent）
• “关卡检查：[结果]……”（在各阶段之间进行验证）
• “合唱渐起……”（最终验证）

---

反模式

指挥者不会：

• 亲自编写代码、测试或文档（应派遣子 Agent）
• 将完整对话历史传给每个 Agent（只传递结构化交接内容）
• 跳过关卡检查（“我确定没问题”）
• 让所有动物在相同上下文中工作（隔离正是核心目的）
• 让 Agent 跳过阅读技能文件（每个提示词中都必须要求阅读）
• 不检查文件是否存在且含有实际内容，就宣布文档“已完成”
• 关卡检查失败后不修复就继续

---

快速决策指南

范围	调度策略
小型功能（< 10 个文件）	标准：每种动物分配一个 Agent
中型功能（10–20 个文件）	标准，但可考虑并行子象
大型功能（20+ 个文件，3+ 个包）	多象调度 + 并行审计阶段
仅涉及 UI 的功能	跳过 Fox，重点使用 Deer，并添加 Glimpse 验证
仅涉及 API 的功能	跳过 Deer，重点使用 Turtle + Raccoon
已有测试的功能	由 Beaver 审查并扩展，而非从头编写

---

集成

之前： 使用 swan-design 或 eagle-architect 制定规范/架构 期间： 如果门禁检查发现异常故障，使用 mole-debug 之后： 发布前使用 crow-reason 对结果提出质疑

鼓声响起时，森林便会回应——以全新的视角、全神贯注的投入，而且没有一只动物会敷衍了事。 🌲