gathering-feature

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Gathering Feature 🌲🐾

Gathering Feature（功能集结开发）🌲🐾

The drum echoes through the forest. One by one, they come. The Bloodhound scouts the territory. The Elephant builds with unstoppable momentum. The Turtle hardens what was built — bone-deep security, not bolted on afterward. The Beaver tests the hardened code. The Raccoon audits for secrets and cleanup. The Deer ensures all can travel the paths. The Fox optimizes for speed. The Owl documents what was learned. When the gathering completes, a feature stands where before there was only forest — secure from birth.

鼓声在森林中回荡。它们逐一赶来：寻血猎犬勘察领地，大象势不可挡地推进构建，乌龟为已完成的工作筑牢根基——将安全融入骨髓，而非事后附加。海狸对加固后的代码进行测试，浣熊检查是否存在敏感信息并清理冗余，鹿确保所有路径都能顺畅通行，狐狸优化性能，猫头鹰记录所学内容。当集结完成时，原本的森林地带将矗立起一个功能完整的特性——从诞生之初就具备安全性。

When to Summon

何时发起集结

Building a complete feature from scratch
Major functionality spanning frontend, backend, and database
Features requiring exploration, implementation, testing, and documentation
When you want the full lifecycle handled automatically

从0到1构建完整功能
涵盖前端、后端和数据库的大型功能
需要探索、实现、测试和文档编写的功能
希望自动处理全生命周期的场景

Grove Tools for This Gathering

本次集结使用的Grove工具集

Use

gw

and

gf

throughout. Quick reference for feature work:

bash

undefined

全程使用

gw

和

gf

命令。功能开发快速参考：

bash

undefined

Orientation — start every gathering here

环境定位 — 每次集结都从这里开始

gw context

Exploration phase (Bloodhound)

探索阶段（寻血猎犬）

gf --agent search "pattern" # Find relevant code gf --agent func "functionName" # Find function definitions gf --agent usage "ComponentName" # Find where things are used gf --agent impact "module" # Understand change blast radius

gf --agent search "pattern" # 查找相关代码 gf --agent func "functionName" # 查找函数定义 gf --agent usage "ComponentName" # 查找组件使用位置 gf --agent impact "module" # 了解变更影响范围

Testing phase (Beaver)

测试阶段（海狸）

gw ci --affected --diagnose # Run CI on affected packages

gw ci --affected --diagnose # 对受影响的包运行CI

Shipping phase (after all animals complete)

交付阶段（所有环节完成后）

gw git pr-prep # Preflight check before PR gw git ship --write -a -m "feat: description" # Commit + push

---

gw git pr-prep # 提交PR前的预检 gw git ship --write -a -m "feat: description" # 提交并推送

---

The Gathering

集结流程

SUMMON → ORGANIZE → EXECUTE → VALIDATE → COMPLETE
   ↓         ↲          ↲          ↲          ↓
Receive  Dispatch   Animals    Verify   Feature
Request  Animals    Work       All      Ready

召唤 → 组织 → 执行 → 验证 → 完成
   ↓         ↲          ↲          ↲          ↓
接收  分派     各角色    验证所有   功能就绪
请求  任务     开展工作   交付项

Animals Mobilized

参与的角色（动物代表）

🐕 Bloodhound — Scout the codebase, understand patterns
🐘 Elephant — Build the multi-file feature
🐢 Turtle — Harden what was built (secure by design, not bolted on)
🦫 Beaver — Write comprehensive tests (including hardened code)
🦝 Raccoon — Security audit and cleanup
🦌 Deer — Accessibility audit
🦊 Fox — Performance optimization
🦉 Owl — Document the feature

🐕 寻血猎犬 — 勘察代码库，理解现有模式
🐘 大象 — 构建跨多文件的功能
🐢 乌龟 — 加固已构建的内容（设计即安全，而非事后附加）
🦫 海狸 — 编写全面的测试（包括加固后的代码）
🦝 浣熊 — 安全审计与清理
🦌 鹿 — 可访问性审计
🦊 狐狸 — 性能优化
🦉 猫头鹰 — 功能文档编写

Phase 1: SUMMON

阶段1：召唤

The drum sounds. The forest listens...

Receive and parse the request:

Clarify the Feature:

What does this feature do?
Which users benefit?
What's in scope? What's out?
Any existing issues or specs?

Confirm:

"I'll mobilize a gathering for: [feature description]

This will involve:

🐕 Bloodhound scouting the codebase

🐘 Elephant building across [estimated files] files

🐢 Turtle hardening security by design

🦫 Beaver writing tests

🦝 Raccoon auditing for secrets and cleanup

🦌 Deer checking accessibility

🦊 Fox optimizing performance

🦉 Owl writing documentation

Proceed with the gathering?"

鼓声响起，森林侧耳倾听...

接收并解析需求：

明确功能需求：

该功能的作用是什么？
哪些用户会从中受益？
需求范围是什么？哪些不在范围内？
是否有现存的问题或规格说明？

确认内容：

"我将为以下需求发起集结：[功能描述]

本次集结将包含以下环节：

🐕 寻血猎犬勘察代码库

🐘 大象将在**[预估文件数]**个文件中构建功能

🐢 乌龟遵循设计即安全原则加固功能

🦫 海狸编写测试用例

🦝 浣熊检查敏感信息并清理冗余

🦌 鹿检查可访问性

🦊 狐狸优化性能

🦉 猫头鹰编写文档

是否开始集结？"

Phase 2: ORGANIZE

阶段2：组织

The animals assemble, knowing their roles...

Dispatch in sequence:

Dispatch Order:

Bloodhound ──→ Elephant ──→ Turtle ──→ Beaver ──→ Raccoon ──→ Deer ──→ Fox ──→ Owl
   │              │            │          │           │          │        │       │
   │              │            │          │           │          │        │       │
Scout          Build       Harden      Test       Secrets    a11y    Speed   Docs
Patterns      Feature     Security    Coverage    Cleanup    Check   Opt     Write

Cross-Cutting Standard — Signpost Error Codes: All animals MUST use Signpost error codes (from

@autumnsgrove/groveengine/errors

). This is not optional:

Elephant uses them when building (buildErrorJson in API routes, throwGroveError in page loads)
Turtle verifies all errors use Signpost codes during hardening (Phase 2E checklist)
Beaver tests that API routes return proper
```
error_code
```
fields

Raccoon audits for bare

throw error()

and

console.error

without

logGroveError()

Client-side feedback uses
```
toast
```
from
```
@autumnsgrove/groveengine/ui
```

See

AgentUsage/error_handling.md

for the full reference.

Dependencies:

Bloodhound must complete before Elephant (needs context)
Elephant must complete before Turtle (hardens what was built)
Turtle must complete before Beaver (tests the hardened code)
Beaver must complete before Raccoon (tests catch remaining issues)
Raccoon, Deer, Fox can run in parallel after Beaver
Owl last (documents everything)

Why Turtle before Beaver: Security is not a phase you bolt on after testing — it shapes what you build. The Turtle reviews Elephant's work and hardens it: adds input validation schemas, output encoding, parameterized queries, security headers. Then Beaver tests the hardened code, catching both functional and security regressions. This is secure by design.

各角色集结就位，明确自身职责...

按顺序分派任务：

任务分派顺序：

寻血猎犬 ──→ 大象 ──→ 乌龟 ──→ 海狸 ──→ 浣熊 ──→ 鹿 ──→ 狐狸 ──→ 猫头鹰
   │              │            │          │           │          │        │       │
   │              │            │          │           │          │        │       │
勘察模式      构建功能     加固安全      测试覆盖      安全清理    可访问性  性能优化  文档编写

通用标准——使用Signpost错误码： 所有角色必须使用Signpost错误码（来自

@autumnsgrove/groveengine/errors

），此项为强制要求：

大象在构建时使用该错误码（API路由中使用buildErrorJson，页面加载时使用throwGroveError）
乌龟在加固阶段验证所有错误均使用Signpost码（阶段2E检查清单）
海狸测试API路由是否返回正确的
```
error_code
```
字段
浣熊审计是否存在未使用
```
logGroveError()
```
的原生
```
throw error()
```
和
```
console.error
```
客户端反馈使用
```
@autumnsgrove/groveengine/ui
```
中的
```
toast
```
组件

完整参考请查看

AgentUsage/error_handling.md

。

依赖关系：

寻血猎犬必须在大象之前完成（需要先获取上下文信息）
大象必须在乌龟之前完成（乌龟加固已构建的内容）
乌龟必须在海狸之前完成（海狸测试加固后的代码）
海狸必须在浣熊之前完成（测试可发现剩余问题）
浣熊、鹿、狐狸可在海狸完成后并行开展工作
猫头鹰最后执行（记录所有内容）

为何乌龟在海狸之前： 安全并非测试完成后再附加的环节——它会影响你构建的内容。乌龟会审核大象的工作并进行加固：添加输入验证模式、输出编码、参数化查询、安全头。随后海狸对加固后的代码进行测试，同时捕获功能和安全方面的回归问题。这正是设计即安全的体现。

Phase 3: EXECUTE

阶段3：执行

The animals work. The forest transforms...

Execute each phase:

🐕 BLOODHOUND — SCOUT

"Scouting the codebase for [feature]..."

Output:
- Files that will need changes
- Patterns to follow
- Integration points identified
- Potential obstacles found

🐘 ELEPHANT — BUILD

"Building [feature] with momentum..."

Output:
- All required files created/modified
- Frontend components
- Backend API endpoints
- Database schema changes
- Integration wired

🐢 TURTLE — HARDEN

"Withdrawing to study what was built..."

Output:
- Input validation added (Zod schemas on all endpoints)
- Output encoding verified (context-aware)
- Parameterized queries enforced (zero concatenation)
- Security headers configured (CSP, HSTS, etc.)
- Error handling hardened (generic messages, no leaks)
- Defense-in-depth layers applied

🦫 BEAVER — TEST

"Building test dams for confidence..."

Output:
- Integration tests for user flows
- Unit tests for complex logic
- Security regression tests (from Turtle's hardening)
- Edge case coverage
- All tests passing

🦝 RACCOON — AUDIT

"Rummaging for security risks..."

Output:
- Secrets scan (none found)
- Vulnerability check (clean)
- Input validation verified
- Auth checks confirmed

🦌 DEER — SENSE

"Sensing accessibility barriers..."

Output:
- Keyboard navigation works
- Screen reader compatible
- Color contrast passes
- Reduced motion respected

🦊 FOX — OPTIMIZE

"Hunting for performance gains..."

Output:
- Bundle size optimized
- Database queries fast
- Images optimized
- Caching implemented

🦉 OWL — ARCHIVE

"Archiving knowledge for the forest..."

Output:
- Help documentation written
- API documentation updated
- Code comments added
- README updated

各角色开始工作，森林开始转变...

执行每个环节：

🐕 寻血猎犬 — 勘察

"正在为[功能]勘察代码库..."

输出内容：
- 需要修改的文件
- 需遵循的现有模式
- 已识别的集成点
- 发现的潜在障碍

🐘 大象 — 构建

"正在全力构建[功能]..."

输出内容：
- 所有已创建/修改的必要文件
- 前端组件
- 后端API端点
- 数据库架构变更
- 已完成集成配置

🐢 乌龟 — 加固

"正在深入分析已构建的内容..."

输出内容：
- 添加输入验证（所有端点使用Zod模式）
- 验证输出编码（上下文感知）
- 强制使用参数化查询（禁止字符串拼接）
- 配置安全头（CSP、HSTS等）
- 加固错误处理（通用提示，避免信息泄露）
- 应用纵深防御层

🦫 海狸 — 测试

"正在构建测试屏障，确保功能可靠..."

输出内容：
- 用户流集成测试
- 复杂逻辑单元测试
- 安全回归测试（基于乌龟的加固内容）
- 边缘场景覆盖
- 所有测试通过

🦝 浣熊 — 审计

"正在排查安全风险..."

输出内容：
- 敏感信息扫描（未发现）
- 漏洞检查（无问题）
- 输入验证已验证
- 权限检查已确认

🦌 鹿 — 感知

"正在检测可访问性障碍..."

输出内容：
- 键盘导航正常
- 兼容屏幕阅读器
- 颜色对比度达标
- 支持减少动画效果

🦊 狐狸 — 优化

"正在寻找性能优化空间..."

输出内容：
- 包体积优化
- 数据库查询提速
- 图片优化
- 缓存已实现

🦉 猫头鹰 — 归档

"正在为森林记录知识..."

输出内容：
- 编写帮助文档
- 更新API文档
- 添加代码注释
- 更新README

Phase 4: VALIDATE

阶段4：验证

The work is done. Each animal verifies their contribution...

MANDATORY: Run full affected-package verification before the gathering concludes.

This is the final quality gate — the moment the entire gathering's work is proven sound:

bash

undefined

集结工作已完成，各角色验证自身贡献...

强制要求：在集结结束前运行完整的受影响包验证。

这是最终的质量关卡——验证整个集结工作成果的可靠性：

bash

undefined

Step 1: Sync all dependencies

步骤1：同步所有依赖

pnpm install

Step 2: Run affected-only CI — lint, check, test, build on ONLY packages the gathering touched

步骤2：仅对集结涉及的包运行CI — 包括lint、检查、测试、构建

gw ci --affected --fail-fast --diagnose


**If verification fails:** Identify which animal's work caused the failure. Return to that phase, fix the issue, and re-run verification. The gathering does not conclude on broken code.

**Validation Checklist (after CI passes):**

- [ ] CI: `gw ci --affected` passes clean (lint, check, test, build)
- [ ] Bloodhound: All integration points mapped
- [ ] Elephant: Feature functional end-to-end
- [ ] Turtle: Input validation on all entry points
- [ ] Turtle: Output encoding on all exit points
- [ ] Turtle: Security headers configured
- [ ] Turtle: Defense-in-depth layers verified
- [ ] Beaver: All tests passing, coverage adequate
- [ ] Raccoon: No secrets or dead code found
- [ ] Deer: WCAG AA compliance verified
- [ ] Fox: Performance targets met
- [ ] Owl: Documentation complete

**Quality Gates:**

If CI fails: → Read diagnostics (--diagnose output) → Identify the responsible animal phase → Fix the issue → Re-run: gw ci --affected --fail-fast --diagnose → Repeat until clean

If any animal finds critical issues: → Return to that phase → Fix the issue → Re-run CI verification → Continue validation

If all gates pass: → Proceed to COMPLETE

---

gw ci --affected --fail-fast --diagnose


**若验证失败：** 确定是哪个角色的工作导致了问题。返回对应阶段，修复问题后重新运行验证。集结工作不会在代码存在问题的情况下结束。

**验证检查清单（CI通过后）：**

- [ ] CI：`gw ci --affected`全部通过（lint、检查、测试、构建）
- [ ] 寻血猎犬：已映射所有集成点
- [ ] 大象：功能端到端可用
- [ ] 乌龟：所有入口点均已添加输入验证
- [ ] 乌龟：所有出口点均已添加输出编码
- [ ] 乌龟：已配置安全头
- [ ] 乌龟：已验证纵深防御层
- [ ] 海狸：所有测试通过，覆盖率达标
- [ ] 浣熊：未发现敏感信息或死代码
- [ ] 鹿：已验证符合WCAG AA标准
- [ ] 狐狸：达到性能指标
- [ ] 猫头鹰：文档已完成

**质量关卡规则：**

若CI失败： → 查看诊断信息（--diagnose输出） → 确定负责的角色环节 → 修复问题 → 重新运行：gw ci --affected --fail-fast --diagnose → 重复操作直至全部通过

若任何角色发现严重问题： → 返回对应阶段 → 修复问题 → 重新运行CI验证 → 继续完成验证

若所有关卡通过： → 进入完成阶段

---

Phase 5: COMPLETE

阶段5：完成

The gathering ends. A feature stands complete...

Completion Report:

markdown

undefined

集结工作结束，功能完整交付...

完成报告：

markdown

undefined

🌲 GATHERING FEATURE COMPLETE

🌲 GATHERING FEATURE 完成

Feature: [Name]

功能名称：[名称]

Animals Mobilized

参与的角色

🐕 Bloodhound → 🐘 Elephant → 🐢 Turtle → 🦫 Beaver → 🦝 Raccoon → 🦌 Deer → 🦊 Fox → 🦉 Owl

🐕 寻血猎犬 → 🐘 大象 → 🐢 乌龟 → 🦫 海狸 → 🦝 浣熊 → 🦌 鹿 → 🦊 狐狸 → 🦉 猫头鹰

What Was Built

构建内容

Files Changed: [count]
New Components: [list]
API Endpoints: [list]
Database Changes: [summary]

修改文件数： [数量]
新增组件： [列表]
API端点： [列表]
数据库变更： [摘要]

Quality Verification

质量验证

✅ Tests: [X] passing, [Y]% coverage
✅ Hardened: Input validation, output encoding, security headers
✅ Security: No secrets or vulnerabilities found
✅ Accessibility: WCAG AA compliant
✅ Performance: [metrics]
✅ Documentation: Complete

✅ 测试：[X]项通过，覆盖率[Y]%
✅ 安全加固：已添加输入验证、输出编码、安全头
✅ 安全审计：未发现敏感信息或漏洞
✅ 可访问性：符合WCAG AA标准
✅ 性能：[指标]
✅ 文档：已完成

Artifacts Created

生成的产物

Source code (committed)
Tests ([location])
Documentation ([location])
Migration scripts (if applicable)

源代码（已提交）
测试用例（[位置]）
文档（[位置]）
迁移脚本（如适用）

Time Elapsed

耗时

[Duration]

The forest grows. The feature lives.

---

[时长]

森林不断生长，功能正式上线。

---

Example Gathering

集结示例

User: "/gathering-feature Add a bookmarking system for posts"

Gathering execution:

🌲 SUMMON — "Mobilizing for: Bookmarking system. Allow users to save posts for later."
🌲 ORGANIZE — "Dispatch sequence: Bloodhound → Elephant → Turtle → Beaver → Raccoon + Deer + Fox → Owl"
🌲 EXECUTE —
- 🐕 Scout: "Found post components, user service patterns, database conventions"
- 🐘 Build: "Created bookmark service, API endpoints, UI components, database schema"
- 🐢 Harden: "Added Zod validation on bookmark endpoints, parameterized all queries, output encoding on bookmark titles, CSP headers configured"
- 🦫 Test: "Added 18 tests covering CRUD operations, auth checks, security regressions, edge cases"
- 🦝 Audit: "No secrets, clean dependencies, dead code removed"
- 🦌 Sense: "Keyboard nav works, screen reader announces, contrast passes"
- 🦊 Optimize: "Lazy loaded bookmarks, indexed queries, compressed images"
- 🦉 Archive: "Help doc written, API documented, code commented"
🌲 VALIDATE — "All quality gates pass"
🌲 COMPLETE — "Feature deployed, hardened, tested, audited, documented — secure from birth"

When the drum sounds, the forest answers. 🌲

用户请求： "/gathering-feature 为帖子添加书签系统"

集结执行流程：

🌲 召唤 — "正在为以下需求发起集结：书签系统。允许用户保存帖子以便后续查看。"
🌲 组织 — "任务分派顺序：寻血猎犬 → 大象 → 乌龟 → 海狸 → 浣熊 + 鹿 + 狐狸 → 猫头鹰"
🌲 执行 —
- 🐕 勘察："已找到帖子组件、用户服务模式、数据库约定"
- 🐘 构建："已创建书签服务、API端点、UI组件、数据库架构"
- 🐢 加固："已在书签端点添加Zod验证，所有查询均使用参数化方式，书签标题已添加输出编码，已配置CSP安全头"
- 🦫 测试："已添加18个测试用例，覆盖CRUD操作、权限检查、安全回归、边缘场景"
- 🦝 审计："未发现敏感信息，依赖项无问题，已移除死代码"
- 🦌 感知："键盘导航正常，屏幕阅读器可识别，颜色对比度达标"
- 🦊 优化："已实现书签懒加载，查询已建立索引，图片已压缩"
- 🦉 归档："已编写帮助文档，更新API文档，添加代码注释"
🌲 验证 — "所有质量关卡均已通过"
🌲 完成 — "功能已部署，已完成安全加固、测试、审计、文档编写——从诞生之初就具备安全性"

鼓声响起，森林响应召唤。 🌲