Skip to content

Start From a Story

Describe your project in plain words. Get back a CompassAlpha structure you can build against.

The gentlest way to begin: you do not need to learn the framework's vocabulary first. You write a short, everyday description of what you want to build — a "user story" — and then sketch it out into the CompassAlpha structure yourself, by hand, following this page as you go. There's no federation running yet at the idea stage; this is a guided thinking exercise, and the worked example below is your template. This page walks a complete newcomer through that translation, step by step, defining every term as it appears. (Brand-new to the framework? Read the mental model first — it's the eight ideas everything here rests on.)

TL;DR

In plain terms: you say "I want to build X, made of parts A, B, and C", and then — guided by the example here — you give each part its own planning document, write down the project's rules, and lay out the order of work. No setup and no jargon are needed to start — the structure is something you sketch out, not a prerequisite you must learn first.

This is the greenfield path — starting a brand-new project from scratch. (Already have an existing, pre-AI-era codebase you want to bring in? That's the brownfield path — see Start From a Story — Existing Project.)

A few words you'll meet (defined once, here)

You'll see these terms below. Here's the plain-English version of each, so nothing is a surprise:

  • Component — one part of your project (e.g. "the login screen", "the billing engine"). You list these in your story.
  • Compass — the canonical planning document for one component, written at three zoom levels: 60K (the why / ideology), 30K (the how / mechanics), and 10K (the exact schema and rules, executable detail). One component → one compass. (More on the altitude descent →)
  • Charter — the project's rulebook: the handful of rules that apply across all components. It holds invariants (rules that must always hold true — e.g. "every invoice is immutable once issued") and primitives (shared building-block concepts every component reuses).
  • Axis — a track of work. A build axis writes code; a doctrine axis changes the rulebook. They take turns; they never run at the same time. (More →)

That's the whole vocabulary you need to follow this page.

The flow, at a glance

Start from a story — a plain-English brief is decomposed into one compass per component, a Charter is derived in lean or preference-led mode, the axes are presented in order, and a printed scope comes out

Left to right: your story comes in; it's decomposed into one compass per component (each at 60K/30K/10K); a Charter is derived (lean or preference-led); the axes are laid out in build order; and a printed scope comes out the other side. The detail of each step is below.

Step 1 — Write your story

Use this simple template. You fill in the angle-bracket parts in plain English:

As a <role>, I want to build <project>, with the following components:
<comp1>, <comp2>, … <compN>.
Put each component in its own compass.
For the Charter (the rulebook), use:
  (1) lean — let the rules develop as we go [the framework's default], OR
  (2) preference-led — set the rules to my stated preferences from the start.

You don't have to get it perfect. The role and the project line give context; the component list is the part that does the real work, because each component becomes its own compass.

A worked example

Say you're building a small book-tracking website. Your story might be:

"As a reader, I want to build Bookshelf, a website to track the books I own and want to read, with the following components: catalog (the books and their details), shelves (lists I sort books into), and accounts (sign-in and per-user data). Put each component in its own compass. For the Charter, use the lean mode — let the rules develop as we go."

Three components named: catalog, shelves, accounts. That's all the framework needs to begin.

Step 2 — Each component becomes a compass

You sketch out one compass per component — three here — using the example as your guide. Each compass is drafted at the three zoom levels, top to bottom, so the why is settled before the exact detail:

Compass 60K — the why 30K — the how 10K — the exact detail
catalog "A book is a durable record; the catalog is the source of truth for book identity." how a book is created, edited, de-duplicated the book table fields, the ISBN rule, the events emitted
shelves "A shelf is a user's private ordering of books they care about." how books are added/removed/reordered on a shelf the shelf + shelf_item schema, the ordering rule
accounts "An account is the identity everything else is scoped to." sign-in, sessions, per-user data boundaries the account schema, the session rule, what other compasses may read

Notice the cross-references: shelves and catalog both depend on accounts for "who owns this". Those edges get written down in each compass's 30K layer, so the components stay coherent with one another instead of drifting apart. (This is the codebase-coherence idea in action — say the vision, grow coherent code from it.)

Step 3 — The Charter is derived

The Charter is the project-wide rulebook. You chose one of two modes in your story:

  • Lean / emergent (the default). The Charter starts nearly empty and grows as the project teaches you what its real rules are. You discover, for example, that "every book must have a stable ID" matters across all three components — so it gets lifted into the Charter as an invariant, and now every component inherits it automatically. Best when you're exploring and don't yet know all the rules.
  • Preference-led. You state your rules up front, and the Charter is seeded with them from day one — e.g. "all timestamps are UTC", "accounts are soft-deleted, never hard-deleted". Best when you arrive with strong, known requirements.

Either way, the Charter ends up holding the invariants (always-true rules) and primitives (shared concepts) that the per-component compasses lean on. The difference is only when those rules get written: discovered along the way (lean) or declared at the start (preference-led).

Step 4 — The axes are presented in build order

Now the work is laid out as axes — the tracks you'll step through. For a greenfield project the order is:

  1. A short doctrine pass first (optional in lean mode) — just enough to write the initial Charter and the 60K of each compass, so everyone agrees on the why before code. The rulebook is UNLOCKED while this happens (you're allowed to change the rules).
  2. The build axis — the rulebook LOCKS, and code gets written against the now-settled compasses. If you discover a rule needs to change mid-build, you don't quietly change it; you open a new doctrine pass, change it there, then re-lock and resume. This "take turns, never overlap" rule is what stops the build from racing the rules. (Why →)

You step through these as cycles — bounded chunks of work — at whatever pace fits. You can also add more axes later (review, QA, ops, …) at any time; that's covered in axis declarations.

Step 5 — What you get out: the printed scope

The end of the translation is a printed scope — a plain summary you can act on:

PROJECT: Bookshelf  ·  mode: lean greenfield
COMPASSES (3):  catalog · shelves · accounts   (each: 60K/30K/10K)
CHARTER:        v0.1 (lean — grows as the project does)
                seeded invariant: "every book has a stable ID"
AXES:           doctrine pass (write Charter + 60K) → build axis (LOCKED)
FIRST CYCLE:    author the three compasses' 60K, then build catalog

That scope is your starting map — and you drew it by hand, no setup required. What happens next depends on who you are:

  • You don't write code yourself? Stop here — the plan is the part that's yours, and it's done. Take it to the Start with just an idea hand-off: give it to an AI assistant (with a ready-made kickoff) or a developer (with a one-line brief), and they stand the project up. You never need a terminal.
  • You're a developer (or working closely with one)? From here, standing it up gets more technical: follow the ordinary greenfield setup to bring up the repos and tiers, and the sample doctrine cycle to see a compass authored end-to-end. If that feels like a lot, the Bootstrap preset is the gentlest way to begin — still the full setup, just tuned slow and safe (operating presets →).

And if a full federation sounds like more than your project needs, that's worth checking honestly first — see Is CompassAlpha for you?.

Remember this

  • You start in plain English, not jargon. Describe the project and list its components; the structure is the output, not a prerequisite. (the mental model is the only background worth reading first.)
  • One component → one compass, each written 60K → 30K → 10K so the why is fixed before the detail.
  • The Charter is your project-wide rulebook, derived either lean (rules grow as you go) or preference-led (rules set up front).
  • Axes take turns — settle the rules, lock them, build; never both at once.
  • This is the greenfield path; bringing in an existing codebase is the brownfield path.

Next: Greenfield setup →