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🔗

• orient-cwd -- describes the current working directory.
• orient-git -- describes the surrounding git repo, if any.
• orient-project -- inlines root orientation docs and detects a meta repo.
• orient-entrypoints -- detects entrypoint systems (Makefile etc.) and lists their targets.
• summarize-md-toc -- emits a markdown file's heading structure as a bullet list.

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