compass🔗

Small scripts for rapidly orienting in a project area.

Each script is standalone: run individually for debugging, or compose into larger summaries (e.g. an agent's system prompt).

Conventions🔗

• One concern per script.
• Output is markdown, scoped so the top-level output fits under an h3 or smaller. Composers wrap in larger sections as needed.
• If a script has nothing applicable to say, it stays silent (exits 0 with no output). Errors are different: surface those.
• Bash for now. Nushell on the table once we want to pass structured data between scripts.

Scripts🔗

• find-project-root -- prints the project root path (git toplevel), or exits 1.
• orient-contextdocs -- finds orientation docs from the project root down to a given path.
• orient-cwd -- describes the current working directory.
• orient-entrypoints -- detects entrypoint systems (Makefile etc.) and lists their targets.
• orient-files -- classifies files by type (extension, shebang, etc) and counts them.
• orient-git -- describes the surrounding git repo, if any.
• orient-project -- inlines root orientation docs and detects a meta repo.
• skim-makefile -- summarizes a Makefile's targets as a bullet list.
• skim-md-toc -- emits a markdown file's heading structure as a bullet list, with line ranges.

Scripts share verb-prefix conventions (orient-*, skim-*, ...) so they tab-complete as groups when you remember the kind of thing you want but not the specific name.

Tests🔗

Tests live in test-bin/, named <subject>.test, and run directly:

./test-bin/skim-md-toc.test

They're kept out of bin/ deliberately: bin/ gets symlinked out to a wider audience, and tests shouldn't ride along.