Compass recipes
Table of Contents
How to use compass, the developer toolkit for ORE Studio.
One CLI (projects/ores.compass/compass.sh) covers the doc/agile pillars
— Orient, Search, Scaffold, Capture, Journal — and the operational
pillars that fold in the standalone scripts, starting with Provision.
1. Orient
- How do I orient a new session? — full cold-start briefing: product
identity, where, last session, key recipes, memories (
bearings). - How do I see where we are? — current version, sprint, and in-flight
stories/tasks (
where/status). - How do I see what every worktree is doing? — branch / story / task /
PR per git worktree (
fleet). - How do I get a sprint or story status? — all stories or tasks grouped
by state (
sprint status/story status). - How do I get a ranked next-work-item suggestion? — prioritised list of
what to pick up next, scored from sprint state, fleet, and backlog
(
heading).
2. Search and indexing
- How do I index notes for compass? — build the FTS cache (
index). - How do I search docs with compass? — full-text search (
search).
3. Authoring
- How do I add a doc with compass? — create a doc via codegen
(
add). - How do I start a unit of work with compass? — fetch main, branch,
scaffold a linked story+task (
story new/task new).
4. Journal
- How do I know what I was working on? — restart recovery: read
the last entry and clock back on (
journal where/task start). - How do I use the session journal? — full journal reference: clocking on, overlap detection, manual updates, entry format.
5. Sprint
- How do I generate sprint health charts? — one-shot CSV extraction
- gnuplot rendering for all four sprint PNGs (
sprint charts).
- gnuplot rendering for all four sprint PNGs (
6. Captures
- How do I capture ideas from freeform text? — paste unstructured
notes; LLM decomposes into well-structured captures in
inbox/(compass capture --note).
7. Test
- How do I see an overview of the test run? — per-suite stats,
failures, and log excerpts from the last test run (
test results).
8. Shell
- How do I run the ores shell? — launch ores.shell with NATS and
login defaults from
.env; scripted sessions with-f(shell/shell -f FILE).
9. Provision
- How do I manage the checkout environment with compass? — generate,
diff, list, and version the
.env(env configure/diff/list/version [new]). - How do I manage the .env format version with compass? — show and
record the env-format version, and how a stale checkout is caught
(
env version/version new). - How do I initialise the NATS server config with compass? — render the
per-environment nats-server config and create the JetStream store dir (
nats init). - How do I generate NATS certificates with compass? — generate the CA
and per-service mTLS client certs (
nats certs/nats certs --force).
10. Navigating the doc graph
These commands moved into compass from ores.codegen (the tool now owns
doc navigation); the recipes live under Documentation recipes:
- How do I find docs matching a pattern? — filter the graph
(
compass list). - How do I show a doc by UUID? — one doc + inbound/outbound links
(
compass show).
11. See also
- ores.compass — the component model (pillars, structure, design).
- NATS — background on the messaging system managed by
compass nats. - Recipes — the full topic index.