Multi-Surface Topology

Colibri lives on four surfaces simultaneously. Each serves a different purpose and each has a strict direction of truth. This document defines the contract between surfaces so that no two surfaces drift.

See also: colibri-system.md §5 for the short summary. This document is the long form.

1. The Four Surfaces

# Surface Physical location Purpose Editable?
1 Repository E:\AMS on disk, github.com/LastEld/AMS on cloud The authoritative source for all specs, docs, ADRs, skills, code Only via worktree PRs
2 Worktrees E:\AMS\.worktrees\claude\<task-slug> Per-task isolated editing copies, one branch each Yes — this is where all editing happens
3 Obsidian Vault C:\Users\Kamal\Documents\Obsidian Vault\Colibri\ Human reading + planning surface (graph, backlinks, daily notes) Only in _vault/ subtree; never in mirrored areas
4 GitHub Pages https://LastEld.github.io/AMS/ Public reading surface (Jekyll + just-the-docs remote theme) Never directly — built from docs/ by CI

2. Direction of Truth

Truth always flows away from the repository. The repo is authoritative; every other surface is a projection of it with additional write zones.

                     ┌─────────────────┐
                     │   Repository    │
                     │  (authoritative)│
                     └───┬──────┬──┬───┘
                         │      │  │
              (build)    │      │  │   (sync script)
                         ▼      │  ▼
                ┌──────────┐    │  ┌────────────────┐
                │  Pages   │    │  │ Obsidian Vault │
                │(read-only)│   │  │ (human reading)│
                └──────────┘    │  └────────────────┘
                                │           ▲
                                │           │ (mirror, never back)
                                ▼           │
                     ┌──────────────────┐   │
                     │    Worktrees     │───┘
                     │   (editable)     │
                     └────────┬─────────┘
                              │ (PR)
                              ▼
                     ┌─────────────────┐
                     │   Repository    │
                     └─────────────────┘

2.1 Worktrees → Repository

  • A worktree is created from origin/main on a new branch feature/<task-slug>.
  • Every edit, commit, and push happens inside the worktree.
  • Merge back is always a PR reviewed and merged by the human.
  • The main checkout (E:\AMS) may never be edited by an agent directly.
  • When a PR is merged, the worktree becomes stale and should be removed with git worktree remove.

2.2 Repository → Pages

  • GitHub Pages builds every push to main.
  • Source: everything under docs/ plus docs/_config.yml, docs/_includes/, and docs/assets/.
  • Theme: just-the-docs as a remote theme.
  • Hero block and custom CSS/JS live in docs/assets/css/custom.css and docs/assets/js/colibri-hero.js.
  • Pages is read-only from the agent’s point of view. Never scrape it for information; read the source under docs/.

2.3 Repository → Obsidian Vault

  • The colibri-docs-sync skill mirrors docs/ into the vault at C:\Users\Kamal\Documents\Obsidian Vault\Colibri\docs\.
  • Mirroring is one-way (repo → vault) and idempotent.
  • The sync skill never deletes files the vault created in _vault/ (see §3).
  • Obsidian users read the mirrored area. Planning happens in the vault-only area.

3. Obsidian Vault Layout

The vault has two zones with different rules:

Obsidian Vault/Colibri/
├── docs/              ← MIRROR ZONE   (repo → vault, repo is truth)
│   ├── index.md
│   ├── concepts/
│   ├── spec/
│   └── …
│
└── _vault/            ← PLANNING ZONE (vault-only, never committed to repo)
    ├── daily/            daily notes
    ├── rounds/           round planning scratch
    ├── meeting-notes/    ad hoc
    ├── sigma/            sigma orchestrator scratch
    ├── pm/               PM dispatch scratch
    └── README.md         vault bootstrap guide

Rule for the docs/ mirror zone: never edit a file here. If you want to change something, go to the repo, make the change in a worktree, PR it, let sync propagate.

Rule for the _vault/ planning zone: write whatever you want. This is the human’s scratchpad. It never gets committed to the repo. The sync skill will not touch it.

4. Sync Rules (full matrix)

From → To Allowed? How Frequency
Repo → Worktree Yes git worktree add Per task
Worktree → Repo Yes PR merge Per task completion
Repo → Obsidian docs/ Yes colibri-docs-sync On demand / per round
Obsidian docs/ → Repo No — Never
Repo → Pages Yes GitHub Actions Jekyll build Per push to main
Pages → Repo No — Never
Obsidian _vault/ → Repo No — Never
Repo → Obsidian _vault/ No — Never
Worktree → Obsidian No — Worktrees are for PR only

Any row marked No is a conflict-of-truth that would cause drift. Treat accidental violations as bugs.

5. File Placement Rules

When creating a new file, use this decision tree:

  1. Is it a spec, concept, ADR, guide, or tutorial? → docs/ in the repo.
  2. Is it a skill definition? → .agents/skills/<skill-name>/SKILL.md in the repo.
  3. Is it a per-task scratch plan for an agent? → .agents/spawns/<round>/<task>.md in the repo.
  4. Is it the human’s daily planning note or meeting note? → _vault/daily/ in the Obsidian vault.
  5. Is it round scratch that may or may not become a real doc? → _vault/rounds/rNN-<theme>/ in the vault. Promote to docs/ in the next round if it proves useful.
  6. Is it an asset (image, SVG, font)? → docs/assets/ (if served by Pages) or assets/ (top-level, if used in-repo only).

6. What Gets Published to Pages

Every file under docs/ is potentially public. Before committing:

  • Never put secrets in docs/.
  • Never put personal information in docs/.
  • Never put internal-only dispatch notes in docs/ — use _vault/ or .agents/spawns/.
  • Jekyll excludes: docs/_config.yml controls exclude: entries. If a file should exist in the repo but not on Pages, add it to exclude:.

Current exclude: patterns (R73 ground state):

exclude:
  - vendor/
  - node_modules/
  - .agents/
  - .worktrees/
  - '*.tmp'

7. Round Boundaries Across Surfaces

When a round closes, the surfaces must be reconciled:

  1. Sigma seals the round in the repo (docs/session-seal-sN.md updated).
  2. PR merged by the human.
  3. Pages rebuilds automatically.
  4. colibri-docs-sync runs to push the sealed state into Obsidian Vault/docs/.
  5. Human updates _vault/rounds/rNN-<theme>/summary.md if they want a private round card.
  6. Worktree for the round is removed with git worktree remove — the branch stays until deleted from GitHub.

A round is not complete until all four surfaces reflect the same state of main.

8. Asset Inventory

Path Purpose Surface
docs/assets/images/colibri-logo.svg Custom hummingbird mark (hero) Pages + repo
docs/assets/css/custom.css Pages theme overrides, hero styles, Greek overlay Pages
docs/assets/js/colibri-hero.js Greek overlay interaction, pretext-powered tooltips Pages
assets/colibriv0.png Original hummingbird artwork (v0, untracked) Repo only (not served)
_vault/ assets Vault-local images, daily note attachments Vault only

The assets/colibriv0.png in the repo top-level is currently untracked (per git status at session start). It will be either committed into docs/assets/images/ (if used on Pages) or moved to _vault/ during R74.

9. Common Mistakes to Avoid

  • Editing a file in the vault mirror zone — your edit will be silently overwritten on next sync. Always go through a worktree PR.
  • Committing _vault/ files — the vault is not part of the repo. If you see _vault/ in a git diff, that means the paths are wrong.
  • Editing E:\AMS\docs\ directly without a worktree — breaks the worktree rule in CLAUDE.md.
  • Trusting Pages for content — Pages is a projection. If a fact is wrong on Pages, it’s wrong in the repo too; fix the repo, not Pages.
  • Syncing Obsidian back to the repo — the sync skill is one-way. Two-way sync is a bug.

10. Future Surfaces (not yet live)

These are mentioned in planning but are not part of R73:

  • Linear or Jira mirror — deferred; task store is the repo + AMS.
  • Discord or Slack bot — deferred to post-Phase 0.
  • Public API documentation site — will live under Pages as a sub-tree when Phase 0 ships.
  • Self-hosted runtime dashboard — Phase 2+.

Until they exist, there are four surfaces. Not five. Not six.

Part of the R73 unification corpus. Governed by colibri-system.md.

Back to top

Colibri — documentation-first MCP runtime. Apache 2.0 + Commons Clause.

This site uses Just the Docs, a documentation theme for Jekyll.