Compass

Compass

Core Principle

Compass answers three questions about a codebase: where am I, what is this thing, and why does it exist? It answers them about the system — the logical thing the product is — not about the repository that currently realizes it. The codebase is one current realization; a Compass chart that survives a complete implementation rewrite is the one that was describing the system.

The durable half is the third question, and that is where the value is. A capable agent reconstructs where am I on demand, from the code, and gets better at it every release — repository maps, call graphs and hierarchical summaries are a crowded and improving field, and a chart competing on orientation is competing where its advantage shrinks. What no amount of reading reconstructs is which of two readings of the system a human agreed to. Given today's code, an agent can tell you what the system does; it cannot tell you whether that is the system anybody decided to have. Compass exists so that when code and intent disagree, the disagreement is visible and classifiable rather than silently resolved in the code's favour — §Classifying Disagreement is the product, not a maintenance procedure.

Applicability. The chart earns its keep in proportion to how non-local the work is. A one-file fix, a rename, a bug with a stack trace pointing at the line — read the code. Work that crosses a boundary, changes a rule, adds a party, or asks should this live here is what the chart is for. Say so in the host's usage hook: a chart that claims to be worth reading before every edit trains agents to skip it before any.

Compass is meta-code: a persistent logical model with two children — product behaviour and implementation coordinates — from which implementations can be understood, navigated, validated, discarded, and rebuilt.

Compass owns the logical system — concepts, phenomena, responsibilities, capabilities, rules, invariants, relationships, logical boundaries, ubiquitous language, and the reasons those things exist. Code owns the executable realization of that system. Implementation coordinates connect the two.

Authority rule. Repository structure is evidence about implementation, not authority over semantic architecture. Code may suggest architectural hypotheses. Code alone must not ratify L0–L2 semantic identity.

The deliverable is the chart — the architecture knowledge base itself — the first stop for non-local work (Applicability above), so recorded decisions sit on the path of the work that crosses them instead of being missed in passing. The method below is only how that information is produced and kept true.

Every chart document is agent-generated. The human teaches, validates, consults, and ratifies through the exploration loop's checkpoints; the human never writes chart content by hand.

Two nested things share the name: the compass skill (this package) and the compass registry (COMPASS.md, the L- artifact) — the skill is named after the first file worth having.

The Rewrite Test

The admission gate for everything semantic. For every proposed root, bounded context, actor, or block, ask:

> If all current source code were deleted and the same product rebuilt in another language, framework, repository layout, and deployment topology, would this thing still need to exist?

Yes → strong semantic Compass candidate. No → it is implementation metadata, a technical mechanism, a deployment decision, or Context Docs material.

Survive a TypeScript → Rust rewrite: Eligibility, Checkout, Document Review, Ranking, Settlement. Usually do not, absent a separate logical reason: ReactQueryProvider, CloudflareWorkerRouter, PrismaAdapter, src/features/orders/.

Strong invariant. A pure implementation rewrite should permit semantic Compass before == semantic Compass after while replacing most or all implementation coordinates. The more semantic Compass changes merely because technology or topology changed, the more implementation structure has leaked into the model.

The Invariance Test

Before creating, deleting, splitting, merging, promoting, or renaming any L0–L2 entity:

1. Describe what it represents without referring to source topology.
2. State its logical responsibility or phenomenon.
3. Identify important rules, inputs, outputs, effects, or invariants.
4. Identify how humans recognize it in the product or domain.
5. Only then map today's implementation locations.

Then ask: would this boundary still make sense after a structure-only refactor? If no, it is probably not a semantic boundary.

The Derivation Test

The two tests above interrogate one entity at a time, and a decomposition can fail while every member passes. Run this one over the finished list, at L0 and again at L2, before the level is ratified.

> Where did this list come from? Lay the block (or context) names beside the deployables, the packages, and the layers of the stack. If a set pairs off one-to-one with any of those, the cut was read off topology — however many members individually survive the rewrite test.

Individually they will survive. A vault survives a rewrite; a worker survives a rewrite. That is precisely why entity-level tests cannot catch this: the derivation is wrong, not the members.

The tell is a residue block. Once the deployables have taken the block slots, whatever they compose has nowhere left to go, so a container is invented to hold it — and its name is always a category rather than a responsibility: *-intelligence, *-services, core, shared, common, platform. Ask of every name: would a practitioner say this out loud, unprompted, to another practitioner? A name nobody says is a name nobody chose; it was computed from what was left over.

Two further shapes of the same failure:

• A layer promoted to a block. foundation, platform, packages are positions in a dependency stack. A block carrying one of those names almost certainly holds members answering to different responsibilities — check by asking what each one refuses, and watch the answers fail to rhyme.
• A one-to-one map onto the language split. Two blocks because there is a python side and a TypeScript side is a topology cut wearing two hats. One responsibility spanning two languages is the normal condition, not a defect.

The repair is not renaming. Redraw from the domain: name the responsibilities first, from DOMAIN.md and the product, then ask where each currently lives. Expect several places, across layers — that is what a semantic cut looks like from a file tree, and it is why coordinates exist.

Chart Root

The chart lives in one directory the host project declares in its agent instructions (AGENTS.md, CLAUDE.md, or equivalent) — for example a .compass/ directory at the repository root. Read the declared root before any chart work. If no chart root is declared, ask the user to configure one; never invent a location or write chart files to an undeclared path. All layouts below are relative to {chart-root}.

Quick Reference: Levels

| Level | Name | Contains | Kind | Volatility | Budget | |-------|------|----------|------|-----------|--------| | L- | Compass | Registry of roots and externals | semantic | org changes | ≤100w/entry | | L0 | Domain | Bounded contexts, aggregates, context map. No tech. | semantic | years | ≤500w/context | | L1 | System Context | Actors + external systems. Human-ratified. | semantic | quarters | ≤400w + diagram | | L2 | Isolated Blocks | Major internal blocks. Tech enters here. | semantic identity, coordinate detail | months | ≤300w + diagram + component table | | L3 | Components | Logical modules mapped to code paths. | coordinate | weeks | ≤200w | | L4 | Viewports | Cross-cutting flows. 3–4 active max. | either | weeks | ≤500w/viewport | | L5 | Infrastructure | Shared code. Not documented. | — | — | — |

Kind decides who may change a thing and what evidence is required. Semantic identity (L0–L2) must pass the rewrite test and follows the human ratification path. Coordinates (an L2 block's technology and implementation coordinates, all of L3, every compass: marker) are expected to churn as the implementation changes; an agent may remap them without a semantic ratification.

The zoom vocabulary is Simon Brown's C4 model — read context/container/component with that prior — bent at both ends. Deltas: L0 (DDD's strategic layer) sits below the stack; L2 "isolated blocks" are C4 containers, and the file layout keeps C4's name (CONTAINERS.md); C4's Level 4 (code diagrams) is replaced by viewports — code diagrams rot fastest, so the chart stops at L3 and wires to code by coordinates instead; L- and L5 bracket the stack, above and below C4's reach. C4 supplies notation and zoom vocabulary; it does not define Compass's source of truth. Re-evaluate any C4-derived rule that conflicts with semantic orientation.

Propagation: top → down only. If L3 contradicts L0, L3 is wrong.

Scope and Roots

Declare before anything: Scope: [what is the system].

• Scope defines internal (L2–L4) vs external (L1 box).
• Levels are relative to the chosen scope, not absolute.
• The method is fractal: every external system is someone else's L1.

A chart exposes one or more roots — stable logical starting points from which where am I? has a useful independent answer. Roots do not need to correspond to repositories, deployables, services, folders, or C4 systems. A Python backend and a TypeScript frontend are two blocks of one root unless each carries independent logical identity.

Root admission test — all five required:

1. Humans recognize it as a coherent area of reasoning or work.
2. Its logical identity survives implementation restructuring (rewrite test).
3. It has meaningful internal responsibilities or phenomena.
4. Independent where am I? navigation is useful.
5. A human ratifies the root.

The strong challenge: if this repository were rebuilt from scratch, would humans still say "I am working on X"?

Roots may overlap. A domain living inside a wider product can also be its own root, and the same code then carries a coordinate in each. Overlap is expected, not a defect. Agents may propose roots; agents must not invent them.

→ Multi-root cases and worked examples: [references/blocks-and-levels.md](references/blocks-and-levels.md#roots)

Compass Registry (L-)

The registry is the first artifact worth having: one page from which every root, external, and demoted almost-external is reachable.

COMPASS.md is tiered — roots in one table, external systems in a second, named dependencies that are not external systems in a third — so a demotion stays recorded and nothing gets silently re-elevated.

The registry describes the system's boundary, never its own approval trail. Root ratification is a gate on the agent's behaviour (see Boundaries), and recording who ratified what, when, or whether a page has an owner puts the chart's production into the chart. Name the fact a reader needs — what a root is, why a thing sits outside the boundary — never the test that decided it.

→ Registry template: [references/blocks-and-levels.md](references/blocks-and-levels.md#compass-registry-template)

Ubiquitous Language

Each root owns {root}/GLOSSARY.md, the canonical owner of that root's ubiquitous language. Every local product or domain term used architecturally appears there. Do not fill it with implementation terminology unless humans genuinely use that terminology as part of the domain.

When a glossary-defined term is used semantically in chart prose, render it in bold: "A Matter contains Documents and may produce Findings." Never bold filenames, paths, source identifiers, code, or Mermaid syntax.

Terms need not be globally unique. When one word means different things in different bounded contexts, record each meaning with its context explicitly.

Where product language and implementation language differ, the product or domain term is canonical and the code term is recorded as an implementation alias. Source naming never silently wins.

GLOSSARY.md owns terminology. DOMAIN.md owns relationships, contexts, aggregates, events, and invariants.

→ Glossary format: [references/blocks-and-levels.md](references/blocks-and-levels.md#glossarymd-format)

Exploration Loop

Continuous loop: orient → scan → probe → adjust, triangulating three sources rather than comparing two — product/domain reality, the chart, and the implementation. Code yields a candidate model; product and domain reality verify it. Never derive L0/L1 semantics from code shape alone.

| State | What exists | Human role | Exit when | |-------|------------|------------|-----------| | 0 Clean slate | Nothing | Teacher | Scope + candidate roots + 2–5 blocks + externals + actors on scratchpad | | 1 First pass | Scratchpad | Validator | L0 + glossary reviewed, L2 docs, boundaries resolved, levels calibrated | | 2 Documented | L0–L2 | Consultant | L3 docs, boundary viewport (or L4 skipped) | | 3 Deep knowledge | L0–L4 | Ratifier | No exit (steady state) |

States can regress per-block (new block → state 0, semantic change → state 1). A pure restructuring does not regress a state — it remaps coordinates.

Always state confidence explicitly: "I believe X based on [evidence]. Confidence: medium."

→ Full procedures, product/domain evidence sources, scratchpad format: [references/exploration.md](references/exploration.md)

Level Calibration

Calibration is about semantic scale — breadth of logical responsibility — never lines of code, module count, or implementation complexity. After any decomposition, check whether siblings at one level sit at comparable semantic scale:

• oversized concept → consider promoting it (its own level, or its own root if it passes admission);
• several overly fine-grained concepts → consider grouping them under one named umbrella;
• uneven siblings → verify whether they actually belong at the same semantic zoom.

Run calibration as a pass after discovery. The first decomposition is not assumed correctly scaled.

→ Procedure: [references/exploration.md](references/exploration.md#level-calibration)

Viewports (L4)

Four viewport types — runtime, domain, boundary, lifecycle — with creation triggers and procedures in [references/blocks-and-levels.md](references/blocks-and-levels.md#l4--viewports).

Select by task:

• Work within one block → runtime (if needed)
• Change domain concept → domain + boundary
• Debug wrong output → lifecycle
• Modify bridge → boundary

Create: start with a question → trace L3 participants → mermaid diagram → document seams → name by question.

Skip L4 if L3 components are small and loosely coupled.

Block Documentation (BEM)

Blocks document themselves. Consumers document relationships: when block A uses block B, the why, the relied capabilities, and the replacement conditions live in A, never in B.

→ Per-level doc formats, the consumer-relationship block, and promotion criteria: [references/blocks-and-levels.md](references/blocks-and-levels.md)

Coordinate System

• Address: dot-separated path from the root down — root, root.block, or root.block.component, as deep as the coordinate is accurate (unique names per parent).
• Coordinate: compass: in a code comment, written in the host language's comment syntax (//, #, --, …).
• Validate: address exists, code path still matches, no stale markers.

Coordinate laws (treat as invariants):

• A coordinate is a location, not a definition. // compass: checkout.payment.authorisation means the logic implemented here participates in this Compass location. It does not mean this source file defines that semantic boundary. Coordinates may change while the place stays the same.
• Coordinates bubble up. Prefer one accurate coordinate covering a whole s

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: theKashey
• Source: theKashey/skills
• License: MIT

Install and usage instructions live in the source repository linked above.