egm-bootstrap

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

EGM Peanuts and Hay Bootstrap (

egm-bootstrap

)

EGM Peanuts 与 Hay Bootstrap (

egm-bootstrap

)

When running in Codex or ChatGPT Work, first read Codex integration. In Claude Code or Cowork, read

${CLAUDE_PLUGIN_ROOT}/docs/claude.md

first.

在 Codex 或 ChatGPT Work 中运行时，请先阅读 Codex 集成。在 Claude Code 或 Cowork 中，请先阅读

${CLAUDE_PLUGIN_ROOT}/docs/claude.md

。

Overview

概述

This skill automates the creation, correction, formatting, and correctness verification of Elephant-and-Goldfish Model (EGM) compliant

README.md

files across a directory tree. It establishes clear architectural contracts (interfaces, invariants, and side effects) for both human developers and AI assistants.

Peanuts: Leaf-level Component Package READMEs containing specific file contracts.
Hay: Parent-level Repository Blueprints that roll up child interface contracts into high-altitude indexes.

此 skill 自动化整个目录树中 Elephant-and-Goldfish Model（EGM）合规

README.md

文件的创建、修正、格式化和正确性验证。它为人类开发者和 AI 助手建立清晰的架构契约（接口、不变量和副作用）。

Peanuts：包含具体文件契约的叶级 Component Package README。
Hay：父级 Repository Blueprint，将子级接口契约汇总为高层索引。

Delegation

委派

A Goldfish runs in a fresh context with no conversation history. Spawn each subagent with your harness's subagent tool (Antigravity:

invoke_subagent

; Claude Code:

Agent

; Codex:

spawn_agent

). Each subagent is defined in

agents/<file>.md

, and its frontmatter

name

(for example

egm-zoom-out

) is the subagent type to request where your harness registers named subagents. Otherwise spawn a general-purpose subagent and tell it to read that persona file first. Pass the prompt verbatim and wait for the report. If your harness cannot nest subagents, use direct dispatch instead of the synthesizer. See

docs/harnesses.md

. If your harness has no subagent tool, run the scout steps inline.

Goldfish 在没有对话历史的新上下文中运行。使用 harness 的 subagent 工具启动每个 subagent（Antigravity：

invoke_subagent

；Claude Code：

Agent

；Codex：

spawn_agent

）。每个 subagent 定义在

agents/<file>.md

中，其 frontmatter

name

（例如

egm-zoom-out

）是请求 subagent 类型时所用的名称，前提是 harness 注册了具名 subagent。否则，启动一个通用 subagent，并要求它先读取该 persona 文件。逐字传递 prompt 并等待报告。如果 harness 无法嵌套 subagent，则直接分派，而不要使用 synthesizer。参见

docs/harnesses.md

。如果 harness 没有 subagent 工具，则内联执行 scout 步骤。

Inputs

输入

path
: The target root directory path to bootstrap (Required).
is_worker
: Internal parameter.
```
true
```
if executing as a worker Sub-Orchestrator (Optional, default:
```
false
```
).
sub_tree_root
: Internal parameter. The root path of the assigned subtree partition (Optional).
target_filename
: Target contract filename to generate or update (Optional, default:
```
"README.md"
```
). Supports alternate blueprint filenames such as
```
"EGM.md"
```
when pre-existing human-maintained READMEs must not be modified.

path
：要初始化的目标根目录路径（必填）。
is_worker
：内部参数。以 worker Sub-Orchestrator 身份执行时为
```
true
```
（可选，默认：
```
false
```
）。
sub_tree_root
：内部参数。已分配的子树分区根路径（可选）。
target_filename
：要生成或更新的目标契约文件名（可选，默认：
```
"README.md"
```
）。也支持
```
"EGM.md"
```
等备用 Blueprint 文件名，适用于必须不修改现有人工维护 README 的情况。

Execution Constraints (CRITICAL)

执行约束（关键）

No Code Generation: You are strictly limited to documentation. Do not write or refactor any functional source code.
VCS Isolation: Do not perform any version control commits (
```
git commit
```
,
```
git add
```
). All filesystem changes must be written locally using standard file-writing tools. Tracking and submitting is deferred to the human user.
Temporary File Isolation: Parallel workers sharing the workspace must perform all status tracking, check-pointing, and log writing in independent, worker-specific directories outside the project repository workspace.
Tool Usage (CRITICAL): Use your shell, file-reading, file-writing, and file-editing tools for directory discovery and contract/README generation. Adhere to clean Markdown formatting directly during generation (standard headers, tables, and fenced code blocks). If a project markdown formatter (e.g.
```
npx prettier --write
```
) is explicitly configured in the repository, it may optionally be invoked.
Subagent Delegation: Spawn sub-orchestrator workers in parallel.
Mandatory Safety Gate (CRITICAL): If you discover more than 15 subdirectories, you MUST immediately request user approval (using a structured question tool, if your harness has one, or plain chat) before proceeding with full-tree execution or unbounded subagent spawning.

不生成代码：严格限于文档处理。不得编写或重构任何功能性源代码。
VCS 隔离：不得执行任何版本控制提交（
```
git commit
```
、
```
git add
```
）。所有文件系统变更必须使用标准文件写入工具在本地写入。跟踪和提交工作延后由人工用户处理。
临时文件隔离：共享工作区的并行 worker 必须在项目仓库工作区之外的独立 worker 专属目录中执行所有状态跟踪、检查点记录和日志写入。
工具使用（关键）：使用 shell、文件读取、文件写入和文件编辑工具进行目录发现及契约/README 生成。生成时直接遵循整洁的 Markdown 格式（标准标题、表格和围栏代码块）。如果仓库中明确配置了 Markdown 格式化器（例如
```
npx prettier --write
```
），也可以选择调用它。
Subagent 委派：并行启动 Sub-Orchestrator worker。
强制安全门控（关键）：如果发现超过 15 个子目录，必须立即请求用户批准（如果 harness 提供结构化问题工具，则使用该工具，否则使用普通聊天），然后才能执行全树操作或不受限制地启动 subagent。

Workflow

工作流

Step 0: Ecosystem & Verification Discovery

步骤 0：生态系统与验证发现

Inspect the repository root for package/build manifests:

Node.js / TypeScript:
```
package.json
```
->
```
npm test
```
(or
```
pnpm test
```
/
```
yarn test
```
)
Rust:
```
Cargo.toml
```
->
```
cargo test
```
Go:
```
go.mod
```
->
```
go test ./...
```
Python:
```
pyproject.toml
```
/
```
pytest.ini
```
/
```
setup.py
```
->
```
pytest
```
C/C++ / Make:
```
Makefile
```
->
```
make test
```
Bazel:
```
BUILD
```
/
```
BUILD.bazel
```
->
```
bazel test //...
```
None found:
```
<test-command>
```

Record as
```
VerificationCommand
```
to populate generated README contracts.

检查仓库根目录中的包管理或构建清单：

Node.js / TypeScript：
```
package.json
```
->
```
npm test
```
（或
```
pnpm test
```
/
```
yarn test
```
）
Rust：
```
Cargo.toml
```
->
```
cargo test
```
Go：
```
go.mod
```
->
```
go test ./...
```
Python：
```
pyproject.toml
```
/
```
pytest.ini
```
/
```
setup.py
```
->
```
pytest
```
C/C++ / Make：
```
Makefile
```
->
```
make test
```
Bazel：
```
BUILD
```
/
```
BUILD.bazel
```
->
```
bazel test //...
```
未找到：
```
 <test-command>
```

记录为
```
VerificationCommand
```
，用于填充生成的 README 契约。

Step 1: Startup Branching Control

步骤 1：启动分支控制

Check the
```
is_worker
```
input parameter.
If
```
is_worker
```
is
```
true
```
, jump directly to Step 4: Sub-Orchestrator Worker Flow to process the assigned
```
sub_tree_root
```
.
If
```
is_worker
```
is
```
false
```
or unset, proceed as the Root Orchestrator to Step 2: Incremental Scoping & Safety Gate.

检查
```
is_worker
```
输入参数。
如果
```
is_worker
```
为
```
true
```
，则直接跳转到 步骤 4：Sub-Orchestrator Worker 流程，处理分配的
```
sub_tree_root
```
。
如果
```
is_worker
```
为
```
false
```
或未设置，则以 Root Orchestrator 身份继续执行 步骤 2：增量范围界定与安全门控。

Step 2: Incremental Scoping & Safety Gate (Root Orchestrator)

步骤 2：增量范围界定与安全门控（Root Orchestrator）

Incremental BFS Discovery: Map the target
```
path
```
tree level-by-level (BFS) using a directory queue, listing one directory level at a time. (CRITICAL: never run a recursive search such as
```
find
```
or
```
ls -R
```
.)
- Preserve intermediate folder nodes.
- Ignore symbolic links to prevent infinite recursion.
- Ignore hidden/system directories (
```
.git
```
  ,
```
.antigravity
```
  ,
```
node_modules
```
  ,
```
venv
```
  ,
```
dist
```
  ,
```
build
```
  ,
```
third_party
```
  ).
- Read
```
.gitignore
```
  and
```
.egmignore
```
  (if present) and ignore matching glob patterns.
- Preserve package and build manifests (
```
package.json
```
  ,
```
Cargo.toml
```
  ,
```
go.mod
```
  ,
```
pyproject.toml
```
  ,
```
Makefile
```
  ,
```
BUILD
```
  ) in the discovery map to extract verification targets later.
Safety Gate & Unbounded Spawning Approval (CRITICAL): During the BFS loop, if the total running count of discovered directories exceeds 15, immediately pause discovery and request user approval (using a structured question tool, if your harness has one, or plain chat) to warn the user and request approval for full-tree execution:
- ```
question
```
  : "The target directory tree contains more than 15 subdirectories. This is a large execution scope. Do you want to proceed with full-tree bootstrapping?"
- ```
options
```
  :
```
["Yes, proceed with full tree bootstrapping", "No, abort execution"]
```
- (CRITICAL: After requesting approval, you MUST wait for the user's response before continuing or spawning any workers).
- If the user selects abort, terminate execution immediately.
Bottom-up Post-Pruning Pass: Once mapping is complete (and approved), walk the mapped tree bottom-up (leaves to root). Filter out non-code and test-only directories:
- Source Code Files: Files matching recognized source code, schema, and contract extensions:
  - Systems & Compiled:
```
.c
```
    ,
```
.cc
```
    ,
```
.cpp
```
    ,
```
.cxx
```
    ,
```
.h
```
    ,
```
.hh
```
    ,
```
.hpp
```
    ,
```
.rs
```
    ,
```
.go
```
    ,
```
.zig
```
    ,
```
.lean
```
  - Managed & Enterprise:
```
.java
```
    ,
```
.kt
```
    ,
```
.scala
```
    ,
```
.cs
```
    ,
```
.fs
```
  - Scripting & Dynamic:
```
.py
```
    ,
```
.rb
```
    ,
```
.php
```
    ,
```
.lua
```
    ,
```
.sh
```
    ,
```
.bash
```
  - Web & Mobile:
```
.ts
```
    ,
```
.tsx
```
    ,
```
.js
```
    ,
```
.jsx
```
    ,
```
.mjs
```
    ,
```
.cjs
```
    ,
```
.swift
```
    ,
```
.m
```
    ,
```
.dart
```
  - Data & Schemas / IDLs:
```
.sql
```
    ,
```
.proto
```
    ,
```
.graphql
```
    ,
```
.gql
```
    ,
```
.thrift
```
    ,
```
.prisma
```
  - Infrastructure / Declarative Code:
```
.tf
```
    ,
```
.hcl
```
    ,
```
.cue
```
    (Excludes build manifests, lockfiles, test fixtures, documentation, and generic data dumps like
```
.csv
```
    ,
```
.tsv
```
    ,
```
.parquet
```
    ).
- Test Directory Exclusion: Exclude directories containing exclusively test code (e.g. named
```
tests
```
  ,
```
testing
```
  ,
```
testdata
```
  , or containing only files matching
```
*_test.*
```
  ,
```
*Test.*
```
  ,
```
test_*.*
```
  , or
```
*.spec.*
```
  ).
- Non-Code Filtering: Exclude any directory that contains no source code files AND contains no subdirectories with code. Retain empty intermediate folders only if they have child directories that contain code.
Calculate the total count of pruned directories and maximum depth. Proceed to Step 3: Execution Strategy Selection.

增量 BFS 发现：使用目录队列逐层映射目标
```
path
```
树，每次仅列出一个目录层级。（关键：绝不运行
```
find
```
或
```
ls -R
```
等递归搜索。）
- 保留中间文件夹节点。
- 忽略符号链接，以防止无限递归。
- 忽略隐藏或系统目录（
```
.git
```
  、
```
.antigravity
```
  、
```
node_modules
```
  、
```
venv
```
  、
```
dist
```
  、
```
build
```
  、
```
third_party
```
  ）。
- 读取
```
.gitignore
```
  和
```
.egmignore
```
  （如果存在），并忽略与其中的 glob 模式匹配的内容。
- 在发现映射中保留包管理和构建清单（
```
package.json
```
  、
```
Cargo.toml
```
  、
```
go.mod
```
  、
```
pyproject.toml
```
  、
```
Makefile
```
  、
```
BUILD
```
  ），以便稍后提取验证目标。
安全门控与无界启动批准（关键）：在 BFS 循环期间，如果已发现目录的总数超过 15，请立即暂停发现并请求用户批准（如果 harness 提供结构化问题工具，则使用该工具，否则使用普通聊天），提醒用户并请求批准执行全树操作：
- ```
question
```
  : "目标目录树包含超过 15 个子目录。这是一个大型执行范围。是否要继续对整个树进行 bootstrapping？"
- ```
options
```
  :
```
["是，继续对整个树进行 bootstrapping", "否，中止执行"]
```
- （关键：请求批准后，必须等待用户响应，然后才能继续执行或启动任何 worker）。
- 如果用户选择中止，请立即终止执行。
自底向上的剪枝处理：映射完成（并获得批准）后，自底向上遍历映射树（从叶节点到根节点）。过滤非代码目录和仅含测试的目录：
- 源代码文件：匹配已知源代码、schema 和契约扩展名的文件：
  - 系统与编译型：
```
.c
```
    、
```
.cc
```
    、
```
.cpp
```
    、
```
.cxx
```
    、
```
.h
```
    、
```
.hh
```
    、
```
.hpp
```
    、
```
.rs
```
    、
```
.go
```
    、
```
.zig
```
    、
```
.lean
```
  - 托管与企业级：
```
.java
```
    、
```
.kt
```
    、
```
.scala
```
    、
```
.cs
```
    、
```
.fs
```
  - 脚本与动态语言：
```
.py
```
    、
```
.rb
```
    、
```
.php
```
    、
```
.lua
```
    、
```
.sh
```
    、
```
.bash
```
  - Web 与移动端：
```
.ts
```
    、
```
.tsx
```
    、
```
.js
```
    、
```
.jsx
```
    、
```
.mjs
```
    、
```
.cjs
```
    、
```
.swift
```
    、
```
.m
```
    、
```
.dart
```
  - 数据与 Schema / IDL：
```
.sql
```
    、
```
.proto
```
    、
```
.graphql
```
    、
```
.gql
```
    、
```
.thrift
```
    、
```
.prisma
```
  - 基础设施与声明式代码：
```
.tf
```
    、
```
.hcl
```
    、
```
.cue
```
    （不包括构建清单、锁文件、测试夹具、文档以及
```
.csv
```
    、
```
.tsv
```
    、
```
.parquet
```
    等通用数据转储。）
- 测试目录排除：排除仅包含测试代码的目录，例如名为
```
tests
```
  、
```
testing
```
  、
```
testdata
```
  的目录，或只包含
```
*_test.*
```
  、
```
*Test.*
```
  、
```
test_*.*
```
  、
```
*.spec.*
```
  文件的目录。
- 非代码过滤：排除既不包含源代码文件、也不包含带代码子目录的目录。仅当空中间文件夹的子目录中包含代码时，才保留该文件夹。
计算剪枝后的目录总数和最大深度。然后进入 步骤 3：执行策略选择。

Step 3: Execution Strategy Selection (Root Orchestrator)

步骤 3：执行策略选择（Root Orchestrator）

Direct Execution Strategy (Directory Count <= 5):
- If the total count of pruned directories is 5 or fewer, execute the bottom-up documentation directly in the current thread.
- Jump to Step 4: Sub-Orchestrator Worker Flow (treating the Root Orchestrator as the worker for the entire
```
path
```
  ), and then proceed to Step 5: Root Compilation & Termination.
Unbounded Parallel Subagent Swarm Strategy (Directory Count > 5):
- (CRITICAL: If Directory Count > 15, you MUST verify that you have received explicit user approval before proceeding. If not yet approved, request approval immediately and wait for the user's response before spawning workers).
- Partition the discovery map into independent subtree branches using the Adaptive Depth Partitioning Algorithm:
  1. Set
```
depth = 1
```
    .
  2. Extract directory nodes from the discovery map located at the current
```
depth
```
    .
  3. If the count of nodes at
```
depth
```
    is between 3 and 5: select these nodes as subtree partition roots.
  4. If the count of nodes at
```
depth
```
    < 3: increment
```
depth
```
    (up to a max of 3) and repeat step 2.
  5. If the count of nodes at
```
depth
```
    > 5: group the largest branches (by total nested folder count) into 3-4 separate partitions, combine the remaining small branches into a single fallback partition subtree, and select these as partition roots.
  6. Fallback: If
```
depth
```
    reaches 3 and count is still < 3, select the immediate children of the root (or fall back to sequential execution).
- Spawn Unbounded Sub-Orchestrators: For each partition subtree root, use your harness's subagent tool to spawn a parallel worker:
  - Subagent:
```
egm-bootstrap-orchestrator
```
    (
```
agents/bootstrap_orchestrator.md
```
    ) (or a general-purpose subagent)
  - ```
  Prompt
```
  : "Run egm-bootstrap with path=
```
  [path]
```
  , is_worker=true, sub_tree_root=
```
  [partition_root]
```
  , target_filename=
```
  [target_filename]
```
  ."
- Unbounded Execution: Spawn all Sub-Orchestrators in parallel without artificial concurrency limits (as authorized by the user during the safety gate).
- Go idle and wait for all worker subagents to return their JSON subtree index payloads. Jump to Step 5: Root Compilation & Termination.

直接执行策略（目录数 <= 5）：
- 如果剪枝后的目录总数不超过 5，则在当前线程中直接自底向上生成文档。
- 跳转到 步骤 4：Sub-Orchestrator Worker 流程，将 Root Orchestrator 视为负责整个
```
path
```
  的 worker，随后进入 步骤 5：根节点编译与终止。
无界并行 Subagent 群集策略（目录数 > 5）：
- （关键：如果目录数 > 15，必须确认已获得用户的明确批准。如果尚未批准，请立即请求批准，并在启动 worker 前等待用户响应。）
- 使用 自适应深度分区算法，将发现映射划分为相互独立的子树分支：
  1. 设置
```
depth = 1
```
    。
  2. 从发现映射中提取位于当前
```
depth
```
    的目录节点。
  3. 如果
```
depth
```
    处的节点数介于 3 到 5 之间，则选择这些节点作为子树分区根节点。
  4. 如果
```
depth
```
    处的节点数小于 3，则将
```
depth
```
    增加 1（最多增加到 3），并重复步骤 2。
  5. 如果
```
depth
```
    处的节点数大于 5，则按嵌套文件夹总数将最大的分支分为 3 到 4 个独立分区，将剩余的小分支合并为一个备用分区子树，并选择这些分支作为分区根节点。
  6. 备用方案：如果
```
depth
```
    增加到 3 后节点数仍小于 3，则选择根节点的直接子节点，或回退到顺序执行。
- 启动无界 Sub-Orchestrator：针对每个分区子树根节点，使用 harness 的 subagent 工具并行启动 worker：
  - Subagent：
```
egm-bootstrap-orchestrator
```
    （
```
agents/bootstrap_orchestrator.md
```
    ），或使用通用 subagent。
  - ```
  Prompt
```
  ："使用 path=
```
  [path]
```
  、is_worker=true、sub_tree_root=
```
  [partition_root]
```
  、target_filename=
```
  [target_filename]
```
  运行 egm-bootstrap。"
- 无界执行：在用户通过安全门控授权后，不设置人为并发限制，并行启动所有 Sub-Orchestrator。
- 闲置并等待所有 worker subagent 返回 JSON 子树索引载荷。然后进入 步骤 5：根节点编译与终止。

Step 4: Sub-Orchestrator Worker Flow

步骤 4：Sub-Orchestrator Worker 流程

Scout Registration: Use a read-only
```
goldfish-explorer
```
scout. Where your harness supports defining subagents at runtime, register it with:
- ```
name
```
  :
```
goldfish-explorer
```
- ```
description
```
  :
```
Read-only codebase explorer scout.
```
- ```
system_prompt
```
  : >- You are a read-only codebase explorer. Your task is to analyze the source files in the target directory and return a concise, factual summary. Do not write or modify any files. Return a JSON object containing the directory's public symbols (interface), invariants, and side effects matching schema: {"interface": [], "invariants": [], "side_effects": []}. Never infer RPC methods, routes, status enums, or invariants from file or directory names alone; cite the exact
```
[file:symbol_or_flag]
```
  for every entry, and output
```
["None"]
```
  if no explicit invariants or side effects exist in code.
- ```
enable_write_tools
```
  :
```
false
```
- ```
enable_subagent_tools
```
  :
```
false
```
Post-Order Traversal: Walk the assigned
```
sub_tree_root
```
(or
```
path
```
) in post-order (deepest leaves first). For each directory
```
D
```
:
- Correction & Modification Policy: Check if
```
target_filename
```
  (default:
```
README.md
```
  ) already exists in
```
D
```
  .
  - If
```
target_filename
```
    exists, do not overwrite it completely. Instead, read its existing content.
  - Scout Scan Requirement: Whether
```
target_filename
```
    exists or not, always scan the source code using the
```
goldfish-explorer
```
    scout for
```
D
```
    to compile the true code symbol boundary.
  - Legacy Extraction & Correction: If
```
target_filename
```
    exists, call the reasoning LLM with prompt: > "Analyze the following unstructured documentation content. Extract all public symbol names, classes, interfaces, invariants, and side effects. Format your response strictly as a JSON object matching the following schema: { "interface": string[], "invariants": string[], "side_effects": string[] }." Merge these extracted symbols with the scout's code symbols. Use your file-editing tool (or your file-writing tool) to correct and update the existing contract file to be EGM compliant while preserving developer notes and descriptions.
- Scout Spawning & Constraints: Spawn
```
goldfish-explorer
```
  for
```
D
```
  .
  - Scout Constraints: No per-directory or per-file byte cap; every non-test file in
```
D
```
    is read in full. Bound each scout call to about 1,500 lines of source instead: list top-level definitions (class/func/def/route/flag lines) with your search tool, cut the directory's files into chunks at those boundaries (never mid-body; small files share a chunk), spawn one
```
goldfish-explorer
```
    per chunk in parallel, and merge their JSON. Give each chunk the file's imports and top-level definition list so it can judge visibility. Check build-manifest deps and
```
import
```
    /
```
#include
```
    statements before attributing an RPC service, schema, or message type to a local file. Read non-test files in this order:
    1. Contracts, schemas, and build manifests (
      .h
      ,
      .hh
      ,
      .hpp
      ,
      .proto
      ,
      .graphql
      ,
      .gql
      ,
      .thrift
      ,
      .prisma
      ,
      .sql
      DDL, interface classes); extract exact DDL table names and exported build targets.
    2. Module entry points (
      main.*
      ,
      index.*
      ,
      lib.*
      ,
      mod.*
      ,
      __init__.py
      , or files matching directory name), then production source/query files alphabetically.
    3. Templates and configs: up to 200 lines each (800 in config-only directories); exclude
      .css
      /
      .scss
      .
    4. Test files (
      *_test.*
      ,
      *Test.*
      ,
      test_*.*
      ,
      *.spec.*
      ): ignore entirely, including in hybrid directories.
  - Child Fault Tolerance: If the scout fails or times out, log a warning, use placeholder values
```
["(Details pending/documentation failed)"]
```
    , and continue execution.
- Parent Context Propagation: When processing a parent directory
```
P
```
  , retrieve the compiled interface summaries of its immediate child subdirectories.
  - Propagation Heuristics:
    1. If the child was documented during this run, retrieve its public interface directly from the in-memory execution cache.
    2. If the child was corrected/modified (Correction Policy), use the merged legacy extraction symbols.
  - Pass these child symbol blocks as prompt context when invoking
```
P
```
    's explorer scout.
- Verification Command Target Lookup: Populate the Verification section using the discovered
```
VerificationCommand
```
  .
  - If the project uses Bazel/BUILD files: check if a
```
BUILD
```
    file exists in
```
D
```
    or the nearest ancestor, referencing
```
bazel test
```
    /
```
bazel build
```
    with valid target patterns (
```
//[package_path]/...
```
    or
```
//[package_path]:all
```
    , never
```
//[package_path]...
```
    or
```
//[package_path]:...
```
    ). Use
```
bazel run
```
    for interactive runner targets.
  - If the project uses other manifests (
```
package.json
```
    ,
```
Cargo.toml
```
    ,
```
go.mod
```
    ,
```
pyproject.toml
```
    ,
```
Makefile
```
    ), populate with the corresponding test runner command.
  - If no verification command is identified, omit or use a placeholder.
- Directory Classification & Template Generation: Generate or correct
```
target_filename
```
  using your file-writing tool or your file-editing tool based on
```
D
```
  's classification.
  - Component Package (Peanut):
```
D
```
    contains direct source code files. Use the Component Package README Template. (If it also has child subdirectories, include relative links to their contracts in the Interface section).
  - Repository Blueprint (Hay):
```
D
```
    contains no direct source code files, but contains subdirectories with code contracts. Use the Intermediate Blueprint README Template.
  - Link Formatting Policy (CRITICAL): Package contract files must use a hybrid link formatting approach to balance portability and clarity:
    1. Relative Links to Existing Files Only: Use relative paths (e.g.,
      ./child/${target_filename}
      or
      ../sibling/${target_filename}
      ) for child contracts and sibling file references within the same codebase subsystem. (CRITICAL: Only generate
      [Child](./child/${target_filename})
      links for child directories that exist in the pruned
      subtree_index
      and contain an actual
      ${target_filename}
      . If a child directory contains a
      SKILL.md
      or other non-contract asset, link directly to
      ./child/SKILL.md
      or format it as an unlinked bullet point. Never output speculative links to non-existent contract files).
    2. Absolute Links: Use standard URLs or repository paths for referencing files outside the package subsystem (e.g., cross-package dependencies).
- Markdown Formatting: Immediately after writing or correcting
```
target_filename
```
  in
```
D
```
  , ensure clean markdown formatting (valid headers, tables, and code fences). If a project markdown formatter (e.g.
```
npx prettier --write
```
  ) is configured in the repository, you may execute it on
```
target_filename
```
  .
Worker Reporting: Once the assigned subtree is fully traversed, compile the
```
subtree_index
```
array containing the
```
path
```
,
```
summary
```
,
```
interface
```
,
```
invariants
```
, and
```
side_effects
```
for every processed directory.
If
```
is_worker
```
is
```
true
```
, read the Worker Return Interface Schema relative to this skill directory, then return a matching JSON payload to the Root Orchestrator and terminate. If
```
is_worker
```
is
```
false
```
(sequential mode), proceed directly to Step 5: Root Compilation & Termination.

Scout 注册：使用只读的
```
goldfish-explorer
```
scout。如果 harness 支持在运行时定义 subagent，请按如下方式注册：
- ```
name
```
  ：
```
goldfish-explorer
```
- ```
description
```
  ：只读的代码库探索 scout。
- ```
system_prompt
```
  ：>- 你是一个只读的代码库探索者。你的任务是分析目标目录中的源文件，并返回简洁、基于事实的摘要。不得写入或修改任何文件。返回一个 JSON 对象，其中包含与以下 schema 匹配的目录公共符号（interface）、不变量（invariants）和副作用（side effects）：{"interface": [], "invariants": [], "side_effects": []}。绝不能仅根据文件名或目录名推断 RPC 方法、路由、状态枚举或不变量；每个条目都必须引用准确的
```
[file:symbol_or_flag]
```
  ，如果代码中不存在明确的不变量或副作用，则输出
```
["None"]
```
  。
- ```
enable_write_tools
```
  ：
```
false
```
- ```
enable_subagent_tools
```
  ：
```
false
```
后序遍历：以后序方式遍历分配的
```
sub_tree_root
```
或
```
path
```
，优先处理最深的叶节点。对于每个目录
```
D
```
：
- 修正与修改策略：检查
```
D
```
  中是否已存在
```
target_filename
```
  （默认：
```
README.md
```
  ）。
  - 如果
```
target_filename
```
    已存在，不要完全覆盖它。应改为读取其现有内容。
  - Scout 扫描要求：无论
```
target_filename
```
    是否存在，都始终使用
```
goldfish-explorer
```
    scout 扫描
```
D
```
    的源代码，以确定真实的代码符号边界。
  - 旧版内容提取与修正：如果
```
target_filename
```
    已存在，请使用以下 prompt 调用推理 LLM：> "分析以下非结构化文档内容。提取所有公共符号名称、类、接口、不变量和副作用。将响应严格格式化为与以下 schema 匹配的 JSON 对象：{"interface": string[], "invariants": string[], "side_effects": string[]}。" 将提取出的符号与 scout 提供的代码符号合并。使用文件编辑工具或文件写入工具，修正并更新现有契约文件，使其符合 EGM 要求，同时保留开发者备注和说明。
- Scout 启动与约束：为
```
D
```
  启动
```
goldfish-explorer
```
  。
  - Scout 约束：单个目录或单个文件不设字节上限；
```
D
```
    中的每个非测试文件都必须完整读取。改为将每次 scout 调用限制在约 1,500 行源代码以内：使用搜索工具列出顶层定义（class/func/def/route/flag 行），在这些边界处将目录文件切分为多个块（绝不能从函数体中间切分；小文件可以共用一个块），并行启动一个
```
goldfish-explorer
```
    处理每个块，然后合并其 JSON。将文件的 imports 和顶层定义列表提供给每个块，以便其判断可见性。在将 RPC 服务、schema 或消息类型归属于某个本地文件之前，检查构建清单依赖以及
```
import
```
    /
```
#include
```
    语句。按以下顺序读取非测试文件：
    1. 契约、schema 和构建清单（
      .h
      、
      .hh
      、
      .hpp
      、
      .proto
      、
      .graphql
      、
      .gql
      、
      .thrift
      、
      .prisma
      、
      .sql
      DDL、接口类）；提取准确的 DDL 表名和导出的构建目标。
    2. 模块入口点（
      main.*
      、
      index.*
      、
      lib.*
      、
      mod.*
      、
      __init__.py
      ，或与目录名称匹配的文件），然后按字母顺序处理生产源代码或查询文件。
    3. 模板和配置：每个最多 200 行，仅含配置的目录最多 800 行；排除
      .css
      /
      .scss
      。
    4. 测试文件（
      *_test.*
      、
      *Test.*
      、
      test_*.*
      、
      *.spec.*
      ）：完全忽略，包括混合目录中的测试文件。
  - 子项容错：如果 scout 执行失败或超时，请记录警告，使用占位值
```
["(Details pending/documentation failed)"]
```
    ，然后继续执行。
- 父级上下文传播：处理父目录
```
P
```
  时，检索其直接子目录的已编译接口摘要。
  - 传播启发式规则：
    1. 如果子目录在本次运行中已被记录，则直接从内存执行缓存中检索其公共接口。
    2. 如果子目录已按修正策略进行修正或修改，则使用合并后的旧版内容提取符号。
  - 调用
```
P
```
    的 explorer scout 时，将这些子级符号块作为 prompt 上下文传入。
- 验证命令目标查找：使用发现的
```
VerificationCommand
```
  填充验证章节。
  - 如果项目使用 Bazel/BUILD 文件，检查
```
D
```
    或最近的祖先目录中是否存在
```
BUILD
```
    文件，并引用带有有效目标模式的
```
bazel test
```
    /
```
bazel build
```
    （
```
//[package_path]/...
```
    或
```
//[package_path]:all
```
    ，绝不能使用
```
//[package_path]...
```
    或
```
//[package_path]:...
```
    ）。对于交互式 runner 目标，使用
```
bazel run
```
    。
  - 如果项目使用其他清单（
```
package.json
```
    、
```
Cargo.toml
```
    、
```
go.mod
```
    、
```
pyproject.toml
```
    、
```
Makefile
```
    ），则填入相应的测试运行器命令。
  - 如果未识别出验证命令，则省略该章节或使用占位内容。
- 目录分类与模板生成：根据
```
D
```
  的分类，使用文件写入工具或文件编辑工具生成或修正
```
target_filename
```
  。
  - Component Package（Peanut）：
```
D
```
    包含直接源代码文件。使用 Component Package README 模板。（如果它还包含子目录，请在 Interface 章节中加入指向这些目录契约的相对链接。）
  - Repository Blueprint（Hay）：
```
D
```
    不包含直接源代码文件，但包含具有代码契约的子目录。使用 Intermediate Blueprint README 模板。
  - 链接格式策略（关键）：Package 契约文件必须采用兼顾可移植性和清晰度的混合链接格式：
    1. 仅使用指向现有文件的相对链接：对于同一代码库子系统内的子级契约和同级文件引用，使用相对路径（例如
      ./child/${target_filename}
      或
      ../sibling/${target_filename}
      ）。（关键：仅当子目录存在于剪枝后的
      subtree_index
      中且实际包含
      ${target_filename}
      时，才生成形如
      [Child](./child/${target_filename})
      的链接。如果子目录包含
      SKILL.md
      或其他非契约资产，则直接链接到
      ./child/SKILL.md
      ，或将其格式化为无链接的项目符号。绝不能输出指向不存在契约文件的推测性链接。）
    2. 绝对链接：引用 Package 子系统外部的文件时，使用标准 URL 或仓库路径（例如跨 Package 依赖）。
- Markdown 格式：写入或修正
```
D
```
  中的
```
target_filename
```
  后，立即确保 Markdown 格式整洁（有效标题、表格和代码围栏）。如果仓库中配置了 Markdown 格式化器（例如
```
npx prettier --write
```
  ），可以对
```
target_filename
```
  执行该格式化器。
Worker 报告：分配的子树完全遍历后，编译
```
subtree_index
```
数组，其中包含每个已处理目录的
```
path
```
、
```
summary
```
、
```
interface
```
、
```
invariants
```
和
```
side_effects
```
。
如果
```
is_worker
```
为
```
true
```
，请相对于此 skill 目录读取 Worker Return Interface Schema，然后向 Root Orchestrator 返回匹配的 JSON 载荷并终止。如果
```
is_worker
```
为
```
false
```
（顺序模式），则直接进入 步骤 5：根节点编译与终止。

Step 5: Root Compilation & Termination (Root Orchestrator)

步骤 5：根节点编译与终止（Root Orchestrator）

Receive Worker Payloads: Collect the JSON
```
subtree_index
```
payloads returned by all parallel Sub-Orchestrators.
- Root Fault Tolerance: If a parallel worker fails or times out, log a warning, insert a placeholder warning link (
```
[Subtree Root] (Documentation failed / Subagent execution timeout)
```
  ) in the root Blueprint's subdirectory index, and complete the remaining compilation. (Worker failures leaving partial files are handled as an incremental progress feature; the Correction Policy allows resuming on subsequent runs).
Intermediate Directory Documentation: Identify any intermediate directories sitting between the root
```
path
```
and the partitioned subtree roots.
- Process these intermediate directories sequentially bottom-up.
- Generate Intermediate Blueprint contract files using the compiled summaries returned by the workers.
- Ensure clean formatting and valid relative links for each Intermediate Blueprint contract file.
Root Directory Documentation: The target root
```
path
```
of the execution is always classified as the Repository Root (Blueprint / Hay).
- Check if
```
target_filename
```
  already exists in
```
path
```
  . If present, apply the Correction & Modification Policy to read and retain the existing title, metadata, and architectural overview at the top of the root contract file.
- Check if
```
path
```
  itself contains any direct source files. If present, spawn a
```
goldfish-explorer
```
  scout for
```
path
```
  to extract local symbols and invariants, appending them under the optional
```
## Local Interface & Invariants
```
  section.
- Compile the final root
```
target_filename
```
  using the Repository Root Blueprint Template, rolling up all top-level subdirectory boundaries. Ensure any root architecture or sequence diagrams strictly match the synchronous / asynchronous boundaries, operation names, and storage backends in the child
```
subtree_index
```
  payloads without inventing unverified nodes.
- Write the root
```
target_filename
```
  using your file-writing tool.
Final Correctness Verification (CRITICAL): You MUST perform a final verification pass across ALL created and modified contract files in the
```
subtree_index
```
(including all child package contracts like
```
pkg1/${target_filename}
```
and
```
pkg2/${target_filename}
```
) as a correctness check before concluding work. You MUST explicitly read every single created or modified contract file to verify its content. Do not skip any child contract files. Verify:
- EGM Compliance & Code Grounding: Ensure
```
Interface
```
  ,
```
Invariants
```
  , and
```
Side Effects
```
  sections exist, cite real code symbols/flags/tables from the scout extraction, and contain zero speculative or unverified claims.
- Markdown Syntax: Ensure clean headers, valid tables, and proper code block fences.
- Valid & Resolvable Links (CRITICAL): Ensure all subdirectory and sibling links use valid relative paths (
```
./subdir/${target_filename}
```
  or
```
./subdir/SKILL.md
```
  ), and explicitly verify that every referenced target file actually exists on the filesystem. Remove or correct any broken relative references.
- Valid Targets: Verify verification targets match project test configuration and use valid target syntax (for Bazel,
```
/...
```
  or
```
:all
```
  , never
```
:...
```
  ).
Optional Drift Review (CRITICAL): After verification, ask the user (using a structured question tool, if your harness has one, or plain chat) to offer running a drift report on the generated documentation updates:
- ```
question
```
  : "Do you want to run the EGM Drift Report on the generated contract updates to check for consistency with the codebase?"
- ```
options
```
  :
```
["(Recommended) Yes, run drift report on modified contracts", "No, skip drift review"]
```
- If the user selects "Yes", run the
```
egm-drift-report
```
  skill targeting the modified contracts to verify both missing code coverage and doc-to-code hallucinations (verifying every documented method, route, enum, database table, and invariant against local source files and recording discrepancies in the drift report for human triage). (Note: While
```
egm-drift-report
```
  is often used for design documents, it can be applied to EGM-compliant contracts as a variant).
Terminate execution successfully.

接收 Worker 载荷：收集所有并行 Sub-Orchestrator 返回的 JSON
```
subtree_index
```
载荷。
- 根节点容错：如果并行 worker 执行失败或超时，请记录警告，在根 Blueprint 的子目录索引中插入占位警告链接
```
[Subtree Root](Documentation failed / Subagent execution timeout)
```
  ，并完成其余编译工作。（worker 失败后留下的部分文件被视为增量进度功能的一部分；修正策略允许在后续运行中继续处理。）
中间目录文档：识别位于根
```
path
```
与分区子树根节点之间的所有中间目录。
- 自底向上依次处理这些中间目录。
- 使用 worker 返回的已编译摘要生成 Intermediate Blueprint 契约文件。
- 确保每个 Intermediate Blueprint 契约文件格式整洁且相对链接有效。
根目录文档：执行的目标根
```
path
```
始终分类为 Repository Root（Blueprint / Hay）。
- 检查
```
path
```
  中是否已存在
```
target_filename
```
  。如果存在，则应用 修正与修改策略，读取并保留根契约文件顶部的现有标题、元数据和架构概述。
- 检查
```
path
```
  本身是否包含任何直接源代码文件。如果包含，则为
```
path
```
  启动
```
goldfish-explorer
```
  scout，以提取本地符号和不变量，并将其追加到可选的
```
## Local Interface & Invariants
```
  章节中。
- 使用 Repository Root Blueprint 模板编译最终根
```
target_filename
```
  ，汇总所有顶层子目录边界。确保根架构图或时序图严格符合子级
```
subtree_index
```
  载荷中的同步或异步边界、操作名称和存储后端，且不引入未经验证的节点。
- 使用文件写入工具写入根
```
target_filename
```
  。
最终正确性验证（关键）：结束工作前，必须对
```
subtree_index
```
中所有已创建和修改的契约文件（包括
```
pkg1/${target_filename}
```
和
```
pkg2/${target_filename}
```
等所有子级 Package 契约）执行最终验证。必须明确读取每一个已创建或修改的契约文件，不得跳过任何子级契约文件。验证以下内容：
- EGM 合规性与代码依据：确保存在 Interface、Invariants 和 Side Effects 章节，引用 scout 提取出的真实代码符号、标志或表，并且不包含任何推测性或未经验证的主张。
- Markdown 语法：确保标题、表格和代码块围栏整洁有效。
- 链接有效且可解析（关键）：确保所有子目录和同级链接使用有效的相对路径（
```
./subdir/${target_filename}
```
  或
```
./subdir/SKILL.md
```
  ），并明确验证每个被引用的目标文件确实存在于文件系统中。删除或修正所有无效的相对引用。
- 目标有效：验证目标与项目测试配置一致，并使用有效的目标语法；对于 Bazel，应使用
```
/...
```
  或
```
:all
```
  ，绝不能使用
```
:...
```
  。
可选漂移审查（关键）：验证完成后，询问用户（如果 harness 提供结构化问题工具，则使用该工具，否则使用普通聊天），询问是否对生成的文档更新运行漂移报告：
- ```
question
```
  ："是否要对生成的契约更新运行 EGM Drift Report，以检查其与代码库的一致性？"
- ```
options
```
  ：
```
["（推荐）是，对修改后的契约运行 drift report", "否，跳过 drift review"]
```
- 如果用户选择“是”，则运行
```
egm-drift-report
```
  skill，并将其目标设为已修改的契约，以验证代码覆盖缺口和文档到代码的幻觉；将每个已记录的方法、路由、枚举、数据库表和不变量与本地源文件进行核对，并把差异记录在漂移报告中，供人工分类处理。（注意：
```
egm-drift-report
```
  通常用于设计文档，但也可以作为变体应用于 EGM 合规契约。）
成功终止执行。

Templates

模板

Before writing any contract file, read the README templates relative to this skill directory. It defines the Component Package (Peanuts), Repository Root (Blueprint / Hay), and Intermediate Blueprint README templates referenced above.

写入任何契约文件之前，请相对于此 skill 目录读取 README 模板。其中定义了上文引用的 Component Package（Peanuts）、Repository Root（Blueprint / Hay） 和 Intermediate Blueprint README 模板。

egm-bootstrap

Original

Translation

EGM Peanuts and Hay Bootstrap (
`egm-bootstrap`
)

EGM Peanuts 与 Hay Bootstrap (
`egm-bootstrap`
)

Overview

概述

Delegation

委派

Inputs

输入

Execution Constraints (CRITICAL)

执行约束（关键）

Workflow

工作流

Step 0: Ecosystem & Verification Discovery

步骤 0：生态系统与验证发现

Step 1: Startup Branching Control

步骤 1：启动分支控制

Step 2: Incremental Scoping & Safety Gate (Root Orchestrator)

步骤 2：增量范围界定与安全门控（Root Orchestrator）

Step 3: Execution Strategy Selection (Root Orchestrator)

步骤 3：执行策略选择（Root Orchestrator）

Step 4: Sub-Orchestrator Worker Flow

步骤 4：Sub-Orchestrator Worker 流程

Step 5: Root Compilation & Termination (Root Orchestrator)

步骤 5：根节点编译与终止（Root Orchestrator）

Templates

模板

egm-bootstrap

Original

Translation

EGM Peanuts and Hay Bootstrap (egm-bootstrap)

EGM Peanuts 与 Hay Bootstrap (egm-bootstrap)

Overview

概述

Delegation

委派

Inputs

输入

Execution Constraints (CRITICAL)

执行约束（关键）

Workflow

工作流

Step 0: Ecosystem & Verification Discovery

步骤 0：生态系统与验证发现

Step 1: Startup Branching Control

步骤 1：启动分支控制

Step 2: Incremental Scoping & Safety Gate (Root Orchestrator)

步骤 2：增量范围界定与安全门控（Root Orchestrator）

Step 3: Execution Strategy Selection (Root Orchestrator)

步骤 3：执行策略选择（Root Orchestrator）

Step 4: Sub-Orchestrator Worker Flow

步骤 4：Sub-Orchestrator Worker 流程

Step 5: Root Compilation & Termination (Root Orchestrator)

步骤 5：根节点编译与终止（Root Orchestrator）

Templates

模板

EGM Peanuts and Hay Bootstrap (
`egm-bootstrap`
)

EGM Peanuts 与 Hay Bootstrap (
`egm-bootstrap`
)