Components

Design docs

docs/00 through docs/07 — the reasoning trail, in the order it was written. Each doc stands alone; together they are the argument for why Ujima looks the way it does.

00 – 07

Read top to bottom the first time; after that, each is a reference for one question.

00
INTENT
What the Ujima system is actually trying to accomplish — five distinct problems usually conflated, treated as separate concerns because they have different correct solutions.
docs/00-INTENT.md · 69 lines
The five problems
P1 Transport — agents need to talk to each other
P2 Shared state — who's doing what, what happened, who's blocked
(+3 more, one per doc section)
01
ADVERSARIAL REVIEW
The hostile audit of v1/v2. Every finding is either directly evidenced in the actual old folders or a failure mode the design cannot prevent — ranked by severity, each ending with how Ujima fills the hole.
docs/01-ADVERSARIAL-REVIEW.md · 111 lines
H-01, verbatim finding
"...a directive stuck in .READY since 2026-02-15. Antigravity never saw its directive. Nobody noticed for months."
02
ARCHITECTURE
Decomposed and reassembled. Six design principles, then the alternatives considered and why files+CLI won over each.
docs/02-ARCHITECTURE.md · 161 lines
Principle 6, verbatim
"Governance stays prose; mechanics become code." — the reason souls and mandates stay markdown while delivery, IDs, timestamps, caps, and escalation timers became cli/ujima.py.
03
DEPLOYMENT
The same workspace runs at three tiers, each a strict superset — you never rebuild, you add.
docs/03-DEPLOYMENT.md · 96 lines
The three tiers
T1 Local — CLI only, manual sessions T2 Synced — + git remote, scheduled sweep T3 Autonomous — + heartbeat runner, watchers, notifiers
04
NEXT LEVEL
Skills, plugins, microservices, CLIs, and where this goes — everything ordered by leverage-per-effort, all built on top of the L0 file contract, nothing replacing it. Source of the maturity ladder on the Roadmap page.
docs/04-NEXT-LEVEL.md · 73 lines
Maturity ladder, verbatim
M0 Folder → M1 Tooled → M2 Adapted → M3 Autonomous → M4 Served (→ M5 Federated, this showcase's own addition for the next tier beyond the doc's table)
05
MIGRATION
Bringing v1 and v2 into Ujima by freezing, not converting. History becomes a checkpoint + cold archive; only live identity and unfinished business move.
docs/05-MIGRATION.md · 35 lines
The rule, verbatim
"Do not script a lossy transform of two years of prose — summarize it once, well, and point at the originals."
06
ECOSYSTEM INTEGRATION
Ujima × Heimdall/Bifrost × Headbox — three different layers of the same stack, each answering a different question, integrating only through plugins/bridges, never through merging.
docs/06-ECOSYSTEM-INTEGRATION.md · 114 lines
The three-layer answer
Team → Ujima: who's doing what, who told whom? Machine → Heimdall/Bifrost: what machines exist, are they alive? Project → Headbox: what are a repo's standing rules?
07
CONVENE-DOPE
Discuss, Organize, Prioritize, Execute — the design for self-organizing initiatives. Full breakdown on the Convene / D.O.P.E. component page.
docs/07-CONVENE-DOPE.md · 209 lines · see components-convene.html
Status line, verbatim
"Status: DESIGN APPROVED (2026-07-02) — pending written-spec review before implementation planning."