Skip to content

The Organization Stack

Work in this ecosystem lives across several places: an Obsidian vault for daily life organization, the Thalamus and arcs for in-flight GDD work, component docs/ directories for durable reference knowledge, and GitHub for trackable collaborative work. The organization stack is the model that names those four tiers and defines the promotion paths between them — so items move deliberately rather than drifting or getting lost.

The four tiers

The stack is read as audience/purpose tiers, not a simple durability ladder. Durability rises roughly across the tiers but not monotonically — an Area note in the Vault is permanent, while an arc in the Thalami tier is ephemeral.

Tier Artifact(s) Audience / purpose Horizon
Vault daily notes, project notes, area notes You — and your agent during the scribe ceremony. Life organization, every topic: personal, GDD, work daily: hours; project: weeks–months; area: permanent
Thalami (the thalami hoard) per-machine *-thalamus.md (observations + arcs), Intake.md, ArcDashboard.md You + your agents. GDD working memory, in-flight work weeks–months, pruned in housekeeping
Docs (<component>/docs/) repo README + docs index + topic files Anyone reading the repo. Durable reference knowledge permanent, versioned
GitHub issues, PRs, the companion Project board Collaborators / public. Trackable, durable, dynamic work long-lived, edited live

Both the Vault and the Thalami hoard are already git-synced across machines — neither tier is machine-specific. The distinction between them is audience: the Vault is human-facing life organization; the Thalami hoard is agent-facing GDD working memory.

Any Obsidian hoard scaffolded from the obsidian-vault template (ws hoard init obsidian-vault) plays the Vault role. Examples below name borgr — the maintainer's personal vault — as the concrete instance; the model works the same with any vault produced by the template, under any name.

The two ceremonies

Exactly two ceremonies move items across seams. Both are propose-then-confirm — neither moves anything silently.

The scribe ceremony (operating in borgr) owns Vault-internal drift and the Vault → Thalami bridge: daily-note bullets that have clarified their horizon drift to project or area notes, and daily-note #gdd bullets cross the bridge to Intake.md in the thalami hoard.

The GDD ceremony (orientation + housekeeping) owns the Thalami tier and everything to its right: Intake.md items are promoted to arcs when the work justifies one, arcs graduate to Docs (durable knowledge) or GitHub (trackable work), and inbound GitHub items are surfaced for the human's consideration — an arc is never created automatically from an inbound issue.

The bridge is the process of populating and draining Intake.md, not the file itself. Intake.md is a machine-agnostic file in the thalami hoard, sitting beside ArcDashboard.md. It holds pre-arc GDD work items — things lifted out of a daily note that belong in GDD-land but have not yet been shaped into an arc or assigned to a host. The scribe ceremony populates it; the GDD ceremony drains it — distributing items to the right host's *-thalamus.md and promoting to an arc when the work justifies one.

flowchart LR
    CAP["Capture<br/>daily note / Thalamus observation"]
    INTAKE["Intake.md<br/>thalami hoard"]
    ARC["Arc<br/>ArcDashboard"]
    DOCS["Component docs/"]
    GH["GitHub issue / PR / Project"]
    PRUNE["Pruned"]

    CAP -->|scribe ceremony| INTAKE
    INTAKE -->|GDD ceremony — promote when justified| ARC
    ARC -->|graduate — knowledge| DOCS
    ARC -->|graduate — trackable work| GH
    ARC -->|process residue| PRUNE
    GH -.->|surface inbound — human call| ARC

Capture wide, route narrow

There are exactly two capture surfaces, and everything funnels through one of them. Routing happens later, in a ceremony — never at capture time.

  • The borgr daily note is the universal capture surface. Any topic, captured the moment it occurs, with zero categorization required.
  • The Thalamus Observations section is the capture surface when you are already mid-GDD-session — an idea that surfaces during work is written there rather than forcing a context-switch into the vault.

Routing — the "where does it go" decision — is driven by three questions:

  1. Horizon — minutes/hours → stays a daily-note task. Days–weeks → arc-candidate. Bounded multi-step outcome → project. Open-ended responsibility → area.
  2. Audience — just you / life → stays in the Vault. GDD agent work → Intake.md → Thalami. Reference others will read → Docs. Collaborative / trackable → GitHub.
  3. Durability — ephemeral → leave it low; it will drift or be pruned. Durable → it must eventually reach Docs or GitHub, or it is at risk.

The "belongs in two places" problem dissolves: an item has one home for its current horizon and audience, and it moves as those change — it is never copied. A daily-note bullet that drifts unactioned across several days was simply mis-horizoned; the ceremony promotes it to a project, arc, or Intake.md rather than letting it rot in the daily note.

Graduation

When an arc completes, its residue splits three ways:

  • Knowledge — how something works, why a decision was made, conceptual reference — graduates to component docs/. Durable knowledge belongs in a real docs index plus topic files, not stranded in a closed arc.
  • Trackable work — follow-ups, deferred items, anything others should see — graduates to GitHub as an issue or PR. The arc closes as promoted with a pointer to the GitHub item.
  • Process residue — the day-to-day "did X, reviewed Y" churn — is not graduated. It is pruned in housekeeping. That is the ephemeral tier doing its job.

The ArcDashboard and the GitHub Project board are companions, not redundant: ArcDashboard shows in-flight private work across your machines — ephemeral, fast, pruned. The GitHub Project board shows graduated durable work — persistent, public, edited live. An arc with status: promoted is the hand-off marker between the two.

How the Docs tier is structured — the doc-shape ladder

The Docs tier has its own "start small, grow as needed" ladder, mirroring the stack as a whole. A component's documentation moves through four shapes as its content grows, and — like every seam here — graduation between shapes is propose-then-confirm during ceremony, never automatic:

  1. Loose root Markdown — a README.md plus optional root companions (CONTRIBUTING.md, CHANGELOG.md, …), no docs/ yet. Right for anything from brand-new to small-but-focused, where everything fits in a handful of root files.
  2. Plainly structured /docs — the README plus a docs/ directory holding a docs/README.md index and one topic file per concept, in plain Markdown with no site config. This is the shape a graduating arc's durable knowledge lands in.
  3. Themed docs site — adds a site config (MkDocs / Jekyll / equivalent), a theme, and navigation, and deploys to GitHub Pages. Right once navigation and search start to matter, or the audience extends beyond developers reading on GitHub.
  4. Custom site — beyond the standard frameworks. Named only so the ladder is finite; most components never reach it.

The Shape 1 → 2 trigger is exactly the graduation moment above: when a closing arc's durable knowledge would otherwise pile into a single root README, that is the signal to give the component a real docs/ index plus topic files. The per-shape structure, file roles, and anti-patterns are the operational detail an agent applies when actually writing docs — those live in the gdd-doc-writing skill.

The cadence ladder

The two ceremonies move items across seams as work happens. But the durable tier also needs periodic review — otherwise promoted issues are never looked at again. The model therefore defines a cadence ladder: ceremonies keyed to horizon, not only to session boundaries.

Cadence Ceremony Scope
Per session GDD orientation Picks up arcs, reads the Thalamus, sets session context
Daily / ad-hoc scribe micro + daily review Vault — daily note, project-status drift
Weekly scribe weekly synthesis + durable-tier sweep Vault weekly review + GitHub Project review
Monthly scribe monthly + GDD housekeeping at scale Thalami arc audit + Docs freshness + GitHub board grooming

The new element is the durable-tier sweep — a recurring walk of the GitHub Project board asking of each promoted issue: still relevant? stalled? needs an arc to actually move it? done and closeable? This is what keeps promoted work from rotting unseen.

The weekly and monthly passes have distinct focuses: the weekly sweep is a lightweight review (what is on the board, what is stalled); the monthly pass is grooming (deeper — re-prioritizing, closing dead items, checking Docs freshness). The durable-tier sweep is a step appended to the existing scribe weekly/monthly ceremony rather than a standalone ceremony — the scribe weekly synthesis is already the "zoom out" moment, so the review attaches there instead of adding another ceremony to remember.

Start small

The full stack — four tiers, two ceremonies, a cadence ladder — is the complete picture, but it is not all-or-nothing. You can adopt a subset and grow into the rest:

  • Vault only. Use borgr and the scribe ceremony for life organization. No Thalami bridge, no arcs, no GitHub Project. A complete, useful system on its own.
  • + Thalami. Add arcs and ArcDashboard for in-flight GDD work; the bridge connects the daily note to Intake.md. Where most solo GDD users will sit.
  • + Docs / GitHub. Add the graduation seams and the companion GitHub Project once work is durable or collaborative enough to warrant them.

Each tier is independently useful; each seam is dormant until the tier on its far side is in use. The model degrades gracefully — a missing tier means its seam is unused, not broken, and the routing rule still works: items simply have fewer possible homes.

Full design and rationale: organization-stack design doc.