Not one AI doing everything badly. Five specialist AI workers — each with a unique identity, behavioral profile, and domain of mastery — doing one thing exceptionally well, coordinated through a structured mailbox architecture.
5
Specialist AI Workers
1,642+
Tests Passing
0
Merges Without Review
Docs companion
The docs version explains roles, ownership boundaries, custom AI workers, and how workers avoid collision during work.
The project owner sets direction. Keith starts as Lead and becomes CPO for software development, translating strategy into specs. PROMI orchestrates. Sophi, Marv, and Sage execute in parallel — each in their own domain, none stepping on the others.
You
Project Owner / Architect
Keith
Lead → CPO for software
PROMI
Master Orchestrator
leads →
Sophi
Backend · Python API · Database
Marv
Frontend · Frontend Framework · Visual Canvas
Sage
Docs · ADRs · Knowledge Graph
Each AI worker has a unique identity, behavioral constraints, creativity/compliance profile, and a clear list of what they can and cannot do. Boundaries are not optional.
Lead -> CPO
Product strategy, specs, coordination
"Strategic thinker. Converts the Lead role into product direction for software projects."
Can Do
Cannot Do
Master Orchestrator
Orchestration, change detection, AI worker lifecycle
"Precision orchestrator. Never improvises. Ensures nothing slips through the cracks."
Can Do
Cannot Do
Backend Engineer
APIs, databases, service architecture
"Maximum precision. Compliance 1.0. Sophi does not guess — she verifies, then commits."
Can Do
Cannot Do
Frontend Engineer
Frontend frameworks, visual canvas, UI components
"Linear-inspired precision. Every pixel earns its place. Marv designs systems, not screens."
Can Do
Cannot Do
Knowledge Keeper
Documentation, ADRs, knowledge graph management
"The institutional memory. If it happened, Sage documented it. If it's not documented, it didn't happen."
Can Do
Cannot Do
Architecture Note
Creativity and compliance scores are not static personality traits — they are model-agnostic behavioural parameters set per worker via Steering Profiles. Sophi runs at compliance 1.0 because backend code requires zero ambiguity. Sage runs at creativity 0.6 because good documentation requires judgment, not just transcription. Every score is a deliberate engineering decision, and every profile works consistently regardless of the underlying model powering the worker.
Marv is not just "the frontend worker." He has a design philosophy, a reference bar of the world's best interfaces, and a 7-step decision framework for every pixel. Marv designs systems, not screens.
Marv's Design Philosophy
6 Design Principles
All spacing, sizing, and positioning in multiples of 8px. 4px for micro-adjustments only. If it doesn't land on the grid, it gets moved.
Hierarchy through weight and opacity, not size proliferation. A page with 8 font sizes is a page without hierarchy.
Color is never decorative. Every hue earns its place by carrying meaning: status, action, alert, or identity.
Every interactive element ships with: default, hover, active, disabled, and loading states. Missing a state is a bug, not a design choice.
60fps or it doesn't ship. GPU-accelerated transforms only (translate, scale, opacity). No layout-triggering properties in animations.
When in doubt, study the masters: Linear, Vercel, Supabase, Figma, shadcn/ui, Raycast. Taste is built by osmosis.
Marv's Reference Bar
"Taste is built by osmosis. Study the best interfaces until their decisions become instinct."
7-Step Design Decision Framework
Before Marv writes a single line of code, he runs every UI element through this framework. No exceptions. A component that hasn't been questioned hasn't been designed.
What is the user trying to do?
Start from intention. Not from "what component can I use here?" — from "what does success look like for the person using this?"
What is the simplest element that communicates that?
A link, a button, a label, a card? Default to the most primitive element that does the job. Don't reach for complexity.
Does it need animation, or just be there?
Animation earns its place by adding meaning: revealing state, communicating direction, confirming action. Otherwise, it's noise.
What's its hover state? Active? Disabled? Loading?
Design all five states before writing a single line of code. A component isn't designed until all states are resolved.
Does it respect the 8pt grid?
Count the pixels. 8, 16, 24, 32, 40, 48, 64. If a value isn't in that sequence, it needs a reason.
Does it pass contrast? Is color earned?
WCAG AA minimum. Color must carry intent. Ask: if I remove this color, does the design still communicate the same thing?
Can I delete half of it and still say the same thing?
The best edit is a deletion. If the answer is yes, start cutting. Simplicity is not a constraint — it's the output of rigorous editing.
Each release adds capabilities, refines taste, and expands the frontier of what Marv can build. A key milestone was the turning point. Today he operates at his most capable level yet.
Basic scaffolding. Tailwind defaults. Functional, not beautiful. The canvas exists. Marv learns to place pixels.
React Flow canvas. First real layout challenge. Nodes, edges, viewports. Rough edges visible — but the foundation takes shape.
Canvas interactions: drag, connect, resize. Marv learns spatial thinking. Event handling becomes instinct.
Skill engine UI. First multi-step modal flow. Animation awareness grows. Marv begins to think about transitions, not just states.
Internal MVP polish. Design system awareness begins. Marv starts asking "does this match the others?" for the first time.
Auth flows. Complex multi-step UX. Form validation mastery. Marv learns that trust is built in micro-interactions.
Production hardening. Loading states, error boundaries, edge cases handled. Marv stops shipping happy paths and starts shipping complete paths.
Full overhaul. Inter → Space Grotesk. Navy → Teal palette. Toast notification system. Skeleton loading screens. Typography scale locked. Glass morphism system born. Everything before this was practice.
Marketing site. Pixel-perfect at every breakpoint. Glass morphism refined. Particle background. Astro infographics with zero JS. Marv operates at Linear-level craft.
AI workers communicate through a mailbox pattern. No direct calls — messages flow through a structured queue, ensuring full traceability and graceful failure handling. Click Play to watch a sprint task flow from Keith through the team.
Mailbox Pattern Simulator
Click Play to watch AI workers collaborate.
Message Log
No messages yet. Press Play to start.
Three patterns work together to make parallel AI worker execution safe, traceable, and resilient. Each is a deliberate engineering decision — not a framework default.
Every AI worker has an inbox. Messages are enqueued, not delivered via direct call. No worker can be overwhelmed. Graceful degradation is built in.
Direct calls create tight coupling and cascading failures. The mailbox pattern decouples senders from receivers — if Sophi is busy, the message waits. If Sophi is down, the message persists.
The project Lead owns accountable direction; PROMI coordinates the operating loop. Sophi, Marv, and Sage claim tasks atomically from a shared queue — no duplicate work, no gaps.
The Lead/worker model scales horizontally. Add more AI workers for faster throughput. The Lead stays accountable for direction while PROMI keeps the trace moving.
Tasks are claimed with a database-level lock (SELECT FOR UPDATE). The first AI worker to claim it owns it. This prevents race conditions in parallel workloads.
When two workers read the same task simultaneously, only one can hold the lock. The other retries. This ensures exactly-once delivery — the same task never runs twice.
Under the Hood
Queue
Distributed task queue backed by in-memory cache. Tasks are serialised and distributed with sub-millisecond enqueue latency.
Persistence
Relational database task table with status transitions: pending → claimed → running → done / failed. Full audit trail.
Observability
Every message, every state change, every worker action is logged. Replay any sprint. Debug any failure.
Want to extend the team? Design your own custom AI workers with 9 configurable knobs.
Next: Section 2 of 20
See how PROMI orchestrates your entire AI worker team — task routing, autonomous handoffs, quality gates, circuit breaker, and scheduled operations. Zero manual coordination.
Explore PROMI OrchestrationOr jump to any section on theTechnology Overview →
