vicnaum/vics-agent-skills/layered-summary

Layered Summary (AGENTS.md)

Generate a layered set of AGENTS.md files so that:

• Deeper directories are more detailed (files + key types/functions + local relationships).
• Higher directories are short rollups of their direct children (architecture map).

This is designed to pair well with Cursor's nested AGENTS.md support: when you work in a folder, you automatically get its local summary plus its ancestors' higher-level context.

Hard constraints

• Create/update only AGENTS.md files. Do not change other files.
• Operate only inside the target root subtree.
• No snippets/excerpts and no long quotes. Summaries must be short and checkable (paths/names).
• Use ASCII only; avoid non-ASCII characters.
• Delegate codebase exploration to Explore subagents (see "Subagent-first workflow"). The main agent remains the only writer of AGENTS.md.
• Don't stop mid-run: continue until the Completion criteria is satisfied. If you are forced to pause, leave a resumable checkpoint (see Resume after interruption) and ensure parent ledgers are accurate.
• Skip generated/vendored/third-party blobs. If present, mention them briefly (and why they exist) but don't document them exhaustively.
• Avoid speculation. Use [unclear] / [TBD] markers when needed.

Scripts (recommended)

Use these helper scripts to make planning/scaffolding/verification deterministic and resumable.

• All scripts support Repomix-style scoping flags:
• --include "<glob1,glob2,...>" (positive filter)
• -i/--ignore "<glob1,glob2,...>" (negative filter; ignore wins on conflicts)
• Globs are comma-separated and support ** (e.g., docs/**/*.md matches docs/README.md and deeper files).
• If you don't scope, the scripts will treat most directories with files as meaningful; use --include/--ignore to focus and avoid huge generated/vendor trees.
• The scripts also avoid descending into huge dependency directories by default and omit them from ledgers: node_modules/, bower_components/, jspm_packages/. If there's some valid reason to include them, pass an explicit --include that targets them.

• scripts/agents_plan.py
• Build a bottom-up "waves" schedule for a subtree (derived only; no writes).
• Supports --mode full and --mode update (git-based incremental planning).
• scripts/agents_scaffold.py
• Create-only scaffolder: creates missing DIR/AGENTS.md stubs for meaningful directories.
• Does not touch existing AGENTS.md files. Default is dry-run; pass --write to create.
• scripts/agents_verify.py
• Verify invariants: every meaningful dir has AGENTS.md, one-hop ledger matches filesystem, ASCII-only.
• With --strict: also fail on remaining [TBD] or unchecked - [ ].
• scripts/normalize_agents_ascii.py
• Optional ASCII normalizer for AGENTS.md (default dry-run; --write to edit).
• scripts/export_agents_md.py
• Optional export-only utility: copy AGENTS.md files from a subtree into a standalone folder.

Subagent-first workflow (required)

Use Explore subagents for every meaningful directory you process. Explore is read-only; it should only return analysis. The main agent must create/update AGENTS.md.

Concurrency / conflict rules

• Scheduling is bottom-up: start from the deepest meaningful leaf directories and work upward (postorder).
• Never run Explore on a directory until all meaningful descendants already have complete AGENTS.md. Always complete children first, then do the parent.
• If running multiple Explore tasks in parallel, only parallelize siblings (directories that do not contain each other).
• Prefer deterministic ordering (alphabetical) when choosing which sibling directories to process next, to keep results reproducible.

Explore subagent contract (exploring mode: very thorough)

For each directory DIR/ inside the target root:

• Run an Explore subagent with thoroughness level very thorough scoped to DIR/.
• The Explore subagent must:
• Discover and validate the directory's one-hop structure (immediate subdirectories + files).
• Identify which immediate subdirectories are meaningful vs skippable (and why).
• Analyze local files in DIR/ (if any). "Trust children" applies only to nested folders, not the current directory's own files.
• If immediate child AGENTS.md files exist, read them and incorporate their responsibilities into PURPOSE/RELATIONSHIPS. Treat child AGENTS.md as the source of truth for nested subfolders.
• Do not recursively explore child subdirectories' contents where child/AGENTS.md already exists. Prefer to synthesize from child/AGENTS.md instead.
• Exception: if something is missing/contradictory or the filesystem ledger does not match, it is OK to spot-check the child directory to resolve the discrepancy; keep spot-checks minimal and report to orchestrator why.
• Produce a structured report that the main agent can convert into the standard AGENTS.md template.
• Provide a short "PARENT ROLLUP" the main agent can copy into the parent's subdirectory checkbox entry.
• Use ASCII only, avoid big snippets/excerpts, and be explicit about uncertainty.

Use this exact output structure from the Explore subagent (so the main agent can paste/transform it reliably):

DIRECTORY
- path: <path relative to target root>
- kind: leaf | non-leaf | aggregator-only
 
PURPOSE
<1-3 sentences>
 
PARENT ROLLUP
- <1-2 sentences or 1-3 bullets; keep it short; include up to 3 concrete pointers (subdirs/files/symbol names)>
 
CONTENTS (ONE HOP)
SUBDIRECTORIES
- <name>/ - process | skip (<reason>)
...
 
FILES
- <file> - <role (1-2 sentences)>
  - key-items: <2-10 names or config keys>
  - interactions: <optional 0-2 bullets, paths/modules only>
...
 
KEY APIS (NO SNIPPETS)
- types/classes/interfaces: <comma-separated names> - <optional 1-liners>
- modules/packages: <comma-separated names> - <optional 1-liners>
- functions: <comma-separated names> - <optional 1-liners>
 
RELATIONSHIPS
- depends-on: <paths/modules> - <why>
- used-by: <paths/modules> - <why>
- data-control-flow:
  - <3-12 bullets, high level>
 
LEAF-ONLY (IF LEAF)
FILES (DETAILED)
- <file>
  - role: <why it exists>
  - key-items: <3-10 names>
  - interactions: <how it connects to sibling files>
  - knobs-invariants: <important constraints/tuning>
...
END-TO-END FLOW
- <5-12 bullets>
 
NOTES
- <0-n bullets; include [unclear] where needed>

Target root

• Use the user-provided root directory.
• If none is provided, default to reth/crates/engine.

Directory eligibility (meaningful vs skippable)

This skill and the helper scripts do not try to detect “code” vs “non-code” by language/framework.

Instead, scope is controlled by `--include` / `--ignore`, and a directory is treated as meaningful (must have an AGENTS.md) when:

• It is in-scope (not ignored; and if --include is provided, it is in the include-closure), and
• It either contains at least one in-scope non-`AGENTS.md` file, or contains at least one meaningful in-scope child directory (so it can roll up children).

Directories that are out-of-scope or empty can still appear in the one-hop ledger, but must be marked as skipped with an explicit reason (e.g., out of scope, generated, vendored, binary blobs, empty).

Optional: use tree for planning & quick verification (convenience)

If tree is available, use it for a fast, human-readable scan of what exists and to spot large/unwanted subtrees early.

• Quick overview (bounded depth):

tree -a -L 4 reth/crates/engine

• See where `AGENTS.md` already exists:

tree -a --prune -P 'AGENTS.md' reth/crates/engine

If tree is not available, use find/directory listings instead. tree is a convenience; the ledger invariant (one-hop subdirectory checklist in every AGENTS.md) is the correctness mechanism.

The grounding mechanism (don't miss folders)

Invariant: Every AGENTS.md must contain a one-hop inventory of its immediate subdirectories (excluding always-ignored and default-pruned dependency dirs unless explicitly included), and that list must match the filesystem under those rules.

Use checkbox statuses to make progress explicit:

• - [ ] \child/\ - [TBD] = discovered, not processed yet
• - [x] \child/\ - <short summary> = processed, summary filled from child/AGENTS.md
• - [x] \child/\ - (skip: <reason>) = inspected and intentionally skipped (e.g. out of scope, generated, vendored, empty)

Rule: Before leaving a directory, refresh the one-hop list from the filesystem and ensure no ledger-eligible child directory is missing from the list.

Standard AGENTS.md template

Use this structure everywhere (omit sections that truly don't apply). Leaf directories must be more detailed than one-line-per-file (see "Leaf directories: required detail" below).

# <directory-name>
 
## Purpose
<1-3 sentences describing what this directory provides and why it exists.>
 
## Contents (one hop)
### Subdirectories
-[ ] `child-a/` - [TBD]
-[ ] `child-b/` - [TBD]
 
### Files
-`<important local file>` - <role (1-2 sentences)> (e.g. `README.md`, `docs.md`, `package.json`, `pyproject.toml`)
  -**Key items**: <2-6 relevant names (headings/commands/config keys), or "n/a" if purely descriptive>
-`src/<file>` - <role (1-2 sentences)>
  -**Key items**: `TypeA`, `TypeB`, `fn_x()`, `CONST_Y`
  -**Interactions** (optional): <mentions of sibling files/modules this connects to>
-`<top-level file>` - <role (1-2 sentences)> (only if relevant to this directory's responsibility)
  -**Key items**: <2-6 names>
 
## Key APIs (no snippets)
-**Types / Classes / Interfaces**: `Foo`, `Bar` - <1-liners>
-**Modules / Packages**: `<name>` - <1-liners> (if applicable)
-**Functions**: `qux()` - <1-liners>
 
## Relationships
-**Depends on**: <paths/modules> - <why>
-**Used by**: <paths/modules> - <why>
-**Data/control flow**: <3-7 bullets, high level>
 
## Notes
<Optional. Preserve this section across re-runs. Put [unclear] items here if needed.>

All directories: minimum per-file detail

Even for non-leaf directories, avoid "just <role>" file entries.

Minimum requirement for every listed file:

• Role: 1-2 sentences describing why the file exists (not just "helpers").
• Key items: 2-6 concrete names (types/functions/constants/config keys) that help a reader know what to search for.
• Interactions: optional 1 bullet when it materially improves navigation (e.g., "feeds updates into <other file>", "spawns tasks consumed by <module>").

Leaf directories: required detail (make it "actionable")

If a directory has files but no meaningful subdirectories, treat it as a leaf and write a deeper, navigational summary:

• Replace "Files" one-liners with per-file mini-sections.
• For each file, include:
• Role (1-3 sentences: why it exists)
• Key items (3-10 names: important types/functions/constants)
• Interactions (how it calls/feeds other local files; mention channels/tasks/state where relevant)
• Knobs / invariants (important config flags, thresholds, safety requirements, ordering assumptions)
• Add a short End-to-end flow for the directory (5-12 bullets) describing how the pieces work together.

Use this leaf template (still no big snippets/excerpts):

## Files (detailed)
 
### `<file-a>`
-**Role**: <why it exists>
-**Key items**: `TypeA`, `TypeB`, `fn_x()`, `CONST_Y`
-**Interactions**: <uses/calls/emits/consumes; point to sibling files>
-**Knobs / invariants**: <important constraints or tuning>
 
### `<file-b>`
-**Role**: ...
-**Key items**: ...
-**Interactions**: ...
-**Knobs / invariants**: ...