Concepts / Knowledge tree
Start shallow. Follow what matters.
A knowledge tree gives the agent candidates to inspect. Summaries and declared relationships help it choose the next step.
Indexes explain; the filesystem lists
A directory's index.md describes its purpose and rules. The directory's actual files and indexed subdirectories are its structural inventory. You do not need a second handwritten list of every child.
This illustrative SDLC tree separates two concerns:
.cumaru/
index.md
domain.md
config.yaml
specs/
index.md
authentication/
index.md
sessions.md
payments/
index.md The authentication index introduces that area. Its session concern can describe the current session contract and reference the relevant source files.
Source: the recursive node model.
A summary helps select the next file
Each candidate has a short summary: in YAML frontmatter. cumaru tree reads those summaries without loading Markdown bodies. A valid summary is a trimmed string of 32 to 512 Unicode code points.
For a session-expiration task, the agent can choose authentication from the first list, then inspect its session concern. Payments can remain outside the task's context unless a relevant relationship leads there.
cumaru tree specs
cumaru tree specs/authentication
cumaru map specs/authentication/sessions.md These paths are examples. Run the commands against paths that exist in your project.
Source: tree's candidates and summary contract.
Use different tools for different questions
treelists candidate files and directories with their summaries.maplists literal Markdown headings and line-range selectors.getreads selected file ranges, such as a selector returned by map.contextranks local Markdown by an English query. Scores are experimental relevance signals, not proof of correctness or completeness.
These commands help discover evidence. They do not decide which evidence answers the task.
Sources: map, get, and context.
Relationships give the tree meaning
In domains that declare them, depends-on: is a strong loading signal and relates: asks the agent to consider another concern. A reference table can connect a durable concern to source files. These relationships have different purposes; being nearby on disk does not make two concerns related.
An empty relationship list does not prove isolation. When a shared change may reach another concern, inspect relevant summaries and source references before fixing its scope.
Source: cross-reference discovery.
Stop at the relevant evidence
Expand one directory, select relevant candidates, and repeat only on the branches that survive. Read the selected bodies. Stop when further candidates and declared relationships add no relevant concern. A recursive audit with --deep is useful for checking a branch, not the default instruction to load it all.