---

name: egm-bootstrap license: Apache-2.0 disable-model-invocation: true description: Bootstrap directory README.md files across a repository subtree.

EGM Peanuts and 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.

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.

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.

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.

Execution Constraints (CRITICAL)

1. No Code Generation: You are strictly limited to documentation. Do not write or refactor any functional source code.
2. 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.
3. 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.
4. 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.
5. Subagent Delegation: Spawn sub-orchestrator workers in parallel.
6. 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.

---

Workflow

Step 0: Ecosystem & Verification Discovery

1. 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>
2. Record as VerificationCommand to populate generated README contracts.

---

Step 1: Startup Branching Control

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

---

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

1. 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.

2. 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.

3. 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.

4. Calculate the total count of pruned directories and maximum depth. Proceed to Step 3: Execution Strategy Selection.

---

Step 3: Execution Strategy Selection (Root Orchestrator)

1. 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.

2. 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.

---

Step 4: Sub-Orchestrator Worker Flow

1. 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

2. 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 comp