Compass

Table of Contents

This is the entry point for the ORE Studio cybernetic information architecture and the top-level orientation for the doc/ tree. Read it first on a new contact; come back to it any time you need to remember where something lives. The meta/ subdirectory defines the contract every document follows; this file explains the layout that contract sits inside.

A note on the compass tool

The word "Compass" names both this document and a Python CLI tool, ores.compass, that lives in projects/ores.compass/. Both share the same intent — orientation inside the repository — but operate differently: this document is a static map a human reads; the tool computes orientation on demand against the live org-roam graph and offers quality-of-life shortcuts for both humans and LLMs. A human uses it to search docs (compass find "query"), inspect what is in flight (compass where), or start a unit of work without manually creating branches and files (compass story new / compass task new). An LLM uses it to resolve doc references without hallucinating paths, discover recipes before generating one from scratch, and scaffold agile artefacts with correct frontmatter. Where this document tells you where things are, the tool gets you there.

Folder layout

doc/
├── compass.org           ← this file; read first
├── orientation.org       ← navigation guide, by reader intent
├── meta/                 ← the contract: how documents are shaped
├── agile/                ← the operational tree
│   ├── versions/         ← the composition tree (the bulk of v2)
│   └── product_backlog/  ← pre-sprint ideas (next / deferred buckets)
├── recipes/              ← operational how-tos, by topic
├── knowledge/            ← cross-cutting reference material
│   └── external/         ← reference docs for systems we don't own
├── identity/             ← product vision, out-of-scope
├── functions/            ← named roles across levels (one per system)
├── llm/                  ← LLM config: instructions, settings, skills, memories
│   ├── skills/           ← Claude Code skills, one per slug
│   └── memory/           ← Claude Code session-feedback memory
├── plans/                ← historical design plans (retained for record)
├── manual/               ← user-facing PDF/LaTeX manual
├── prompts/              ← reusable LLM prompts
├── samples/              ← screenshots and product imagery
├── analysis/             ← older one-off analyses (v1, mostly historical)
└── investigations/       ← targeted deep-dive investigations

meta/ — how documents are shaped

See Meta for the full index. The five contract documents, read in order on first contact; refer back to individual ones as needed.

  1. Glossary — what we mean by task, story, sprint, version, function, plan, recipe and many other such terms. This is not a ORE Studio glossary — for example, it will not contain Computational Finance terms such as volatility (vol). Instead, it is focused on terms around our information architecture.
  2. Cybernetic levels — the five levels of concern and what each is responsible for.
  3. Document types — every document type, its frontmatter contract, filename convention, required sections.
  4. Lifecycle — Describes the TODO state transitions and where each state lives.
  5. Execution model — how LLMs and agents operate inside this system.

agile/: the operational tree

See Agile for the full index.

Everything related to the rolling agile process: versions of the product, their sprints, the stories and tasks that compose them, and the product backlog of pre-sprint ideas.

agile/versions/: the composition tree

See Versions for the full index.

Where the operational documents live. Path shape: 

agile/versions/<version>/<sprint>/<story_folder>/<task_slug>.org
                                                ↑       ↑
                                                story.org sits at this level too

Stories and sprints are folders (they contain children); tasks are flat files (they are leaves). One sprint per lexicographic step: sprint_01, sprint_02, … The lexicographically-highest sprint folder is the current sprint.

agile/product_backlog/: the pre-sprint queue

See Product backlog for the full index.

Holds captures — ideas not yet pulled into a sprint as stories. Split into two buckets:

  • =next/=|=deferred — candidate work for the next version.
  • next/=|=deferred/= — longer-term wishlist.

When a capture is promoted into a sprint, the file moves into the appropriate sprint folder and its #+type: flips from capture to story. The :ID: is preserved so links keep working.

recipes/: how do I do X?

See Recipes for the full index.

Short, tested, executable how-tos grouped by topic (recipes/<topic>/how_do_i_xxx.org). Each recipe answers one NLP question. Shell commands inside #+begin_src sh :results verbatim blocks so they run in place via C-c C-c.

Engineering principles

Core documents that explain why the project is built the way it is — the theory behind the architecture, the methodology behind the tools.

  • Model Assisted Software Development — the MASD methodology itself: the logical-physical space, the four metamodels, the six principles, the backout strategy, and the automation spectrum (pure theory, no project-specific content).
  • Applied MASD — how ORE Studio instantiates MASD: the technical spaces, profiles, the two codegen routes, the currency reference implementation, and the full facet catalogue.
  • System Model — the four-layer architecture and component inventory.

knowledge/: durable reference

See Knowledge for the full index; external reference docs are under External knowledge.

Cross-cutting knowledge that outlives any sprint. Lives under knowledge/<topic>/. Component-specific knowledge (e.g. an architecture analysis tied to one component's code) lives co-located with the code at projects/<comp>/docs/, not here.

Identity, functions

  • identity/ — system-5 docs: product identity; what's out of scope. Holds the durable identity statements that filter candidate versions and far captures.
  • functions/ — system-spanning named roles. One function per cybernetic level (S1 Agent, S2 Orchestrator, S3 Sprint Planner, S3* Auditor, S4 Version Planner, S5 Identity Steward), plus the index page. A function doc is the priming context an LLM session loads when it takes on that role.

llm/ — LLM configuration and artefacts

See LLM Configuration and Artefacts for the full description. Summary:

  • llm_instructions.org (LLM instructions) — the mandatory session entry point; lists non-negotiable rules and links to every other reference.
  • claude_code_settings.org (Claude Code Settings) — literate source for .claude/settings.json; regenerate with compass build --direct settings.
  • skills/ — Claude Code skills, one per kebab-case slug. Each SKILL.org is task-shaped: how to perform a specific unit of work end-to-end. The catalogue lives at Claude Code Skills.
  • memory/ — persistent project-scope memory for LLM sessions. One memory per file; the catalogue lives at Project memory. Write here when the user gives feedback worth keeping across sessions.

Developer links

Developer Links (doc/developer.org) — quick-reference index of external developer resources: GitHub, Doxygen, Discord, CDash, and CI pipelines. Start here when onboarding or sharing links with a new contributor or LLM agent.

Secondary folders

  • plans/ (Plans) — historical design plans, one YYYY-MM-DD-name.org per plan. Plans inside a sprint live as the * Plan section of the task/story; this folder is for one-off cross-cutting designs retained for the record.
  • manual/ — user-facing manual. The root file is ORE Studio User Manual at manual/user_guide/user_manual.org; chapters live under manual/user_guide/chapters/. Surfaced to end users, not part of the developer-doc tree.
  • prompts/ (Prompts) — reusable LLM prompts that don't fit cleanly as a skill.
  • samples/ (Samples) — screenshots and product imagery referenced from product identity and visual mockups.
  • analysis/ (Analysis) — older one-off analyses from before v2. Some still useful as background context; not actively maintained.
  • investigations/ (Investigations) — targeted deep-dive investigations into specific technical problems.

Reserved folders

  • audit/ — system-3 scripts and reports enforcing invariants (orphan tasks, stale recipes, broken links, etc.). Empty in this branch.

Core invariants

  • Every stateful document carries the standard frontmatter described in document types.
  • Folders encode composition, not state. A document's TODO state lives on its * Status headline as an org-mode TODO keyword.
  • Composition is strict: a version is made up of one or more sprints; a sprint is made up of one or more stories; a story is made up of one or more tasks; a task is one PR. No exceptions.
  • A story belongs to exactly one sprint. Work that spans sprints closes the current story and opens a successor in the next sprint, with #+predecessor=/=#+successor links.
  • Plans are transient. They live as the * Plan section inside a task or story; decisions distil into the story; the section is cleared when the task closes.
  • Document references are id-links ([[id:UUID][...]]), never [[file:...]]. Paths can change; IDs don't.
  • The user is not responsible for filing. Periodic audit jobs catch drift.

Out of scope here

This document describes the layout. The contract that every document follows lives in document types. The vocabulary used across the system lives in glossary.

Emacs 29.1 (Org mode 9.6.6)