featuring

Featuring

Generate _FEATURES.md files — top-down documentation of what a codebase does, organized by feature/capability, anchored to specific source symbols.

tree-sitting tells you WHAT symbols exist. _FEATURES.md tells you WHY they exist and what they accomplish together.

For large codebases, the root _FEATURES.md decomposes into sub-feature files linked by capability area — not by folder structure. An agent starts at the root and is drawn into sub-files only when working on a relevant area.

Dependency

Requires tree-sitting skill. Uses its engine for AST scanning.

uv venv /home/claude/.venv 2>/dev/null
uv pip install tree-sitter-language-pack --python /home/claude/.venv/bin/python

tree-sitting caches its scan to /tmp/treesit-cache, keyed by repo path plus skip set. That cache persists symbols and imports but NOT file source, so a cache HIT returns source=None. gather.py re-reads those files from disk; do not assume entry.source is populated if you write against the engine directly. (Before this was handled, gather crashed on its second run against a repo while the first succeeded — diagnosed 2026-08-22.)

For quick structural orientation before running gather.py, use tree-sitting's CLI:

TREESIT=/mnt/skills/user/tree-sitting/scripts/treesit.py

# Complete tree, sparse detail — see the full shape
/home/claude/.venv/bin/python $TREESIT /path/to/repo --depth=-1 --detail=sparse

Workflow: Multi-Pass Synthesis

Feature documentation is built in three passes. The overview is written LAST, after all features are understood — not first.

Pass 1: Orientation (quick scan)

/home/claude/.venv/bin/python /mnt/skills/user/featuring/scripts/gather.py /path/to/repo \
  --skip tests,.github,node_modules --source-budget 8000

--orient when you are not writing the file. The full output is a complete symbol inventory — 5,697 lines on a 71k-line repo — and it exists so a _FEATURES.md can cite every symbol. When the deliverable is your own understanding (a review, an orientation read), pass --orient: complexity assessment, decomposition ranking, directory tree and entry points, and nothing else. ~115 lines. Reaching for head on the full output means --orient was the right mode.