IMPLEMENTATION GUIDE — Unified Agent OS
| Decision Type | Signals Required | Who Decides | |---------------|------------------|-------------| | Micro (naming, formatting) | 1 signal | Agent autonomy | | Meso (module design, API shape) | 2 signals | Agent + existing pattern | | Macro (architecture, schema, external contracts) | 3+ signals | Human approval required |
Full Public Reader
IMPLEMENTATION GUIDE — Unified Agent OS
---
Decision Rules
| Decision Type | Signals Required | Who Decides |
|---|---|---|
| Micro (naming, formatting) | 1 signal | Agent autonomy |
| Meso (module design, API shape) | 2 signals | Agent + existing pattern |
| Macro (architecture, schema, external contracts) | 3+ signals | Human approval required |
### Conflict Resolution
1. Invariants always win
2. Charter direction constraints override implementation preference
3. Existing working code > proposed redesign (unless invariant violated)
4. Simplicity > cleverness
---
Technology Stack
Core (Decided — 3+ signals converge)
| Layer | Technology | Rationale |
|---|---|---|
| Language | TypeScript | Existing Pulse v3 is TS; Clawdbot ecosystem is Node; type safety for API contracts |
| Runtime | Node.js / Bun | Compatible with existing skills; Bun for performance-critical paths |
| API Framework | Hono | Lightweight, edge-compatible, TypeScript-native |
| Database | PostgreSQL (Supabase) | Existing infrastructure; Row-Level Security for tenant isolation; real-time subscriptions |
| Cache / PubSub | Redis (Upstash) | Event bus, session state, rate limiting; serverless-compatible |
| Auth | Supabase Auth + API Keys | Supabase for dashboard SSO; API keys for programmatic access |
| Object Storage | Supabase Storage / S3 | Workspace files, skill packages, checkpoints |
| Deployment | Fly.io / Railway | Container-based; supports long-running processes (agent sessions) |
| Queue | BullMQ (Redis-backed) | Session scheduling, chain execution, retry logic |
Provisional (2 signals, may change)
| Layer | Technology | Rationale |
|---|---|---|
| Dashboard | Next.js 14+ | React ecosystem; SSR for initial load; API routes co-located |
| Real-time | WebSocket (Hono upgrade) + Supabase Realtime | Dual: WS for custom events, Supabase for DB changes |
| Observability | OpenTelemetry → Grafana Cloud | Standard tracing; affordable managed option |
| Billing | Stripe | Usage-based billing; metered subscriptions |
---
File Structure
unified-agent-os/
├── .governance/ # This governance scaffolding
│ ├── PROJECT_CHARTER.md
│ ├── GLOSSARY.md
│ ├── INVARIANTS.md
│ ├── IMPLEMENTATION_GUIDE.md
│ └── CHECKLIST.md
│
├── packages/ # Monorepo packages
│ ├── core/ # @agentos/core — shared types, events, constants
│ │ ├── src/
│ │ │ ├── types/ # Tenant, Session, Agent, Skill types
│ │ │ ├── events/ # Event definitions (typed)
│ │ │ └── constants/ # Status enums, limits, defaults
│ │ └── package.json
│ │
│ ├── engine/ # @agentos/engine — Pulse execution engine
│ │ ├── src/
│ │ │ ├── session/ # Session lifecycle (create, run, checkpoint, complete)
│ │ │ ├── chain/ # Chain DAG execution
│ │ │ ├── parallel/ # Parallel session coordinator
│ │ │ ├── gates/ # Quality gate runner
│ │ │ ├── rollback/ # Git-based rollback
│ │ │ └── model/ # Model router (multi-provider)
│ │ └── package.json
│ │
│ ├── heartbeat/ # @agentos/heartbeat — Proactive monitoring
│ │ ├── src/
│ │ │ ├── scheduler/ # Heartbeat interval management
│ │ │ ├── checks/ # Pluggable check system
│ │ │ ├── routing/ # Priority-based notification routing
│ │ │ └── quiet-hours/ # Time-aware suppression
│ │ └── package.json
│ │
│ ├── dreams/ # @agentos/dreams — Idea incubation
│ │ ├── src/
│ │ │ ├── garden/ # Dream lifecycle (spore→fruit)
│ │ │ ├── evolution/ # Cross-pollination, mutation
│ │ │ ├── interpreter/ # Dream→task compilation
│ │ │ └── collective/ # Multi-agent dream sharing
│ │ └── package.json
│ │
│ ├── skills/ # @agentos/skills — Skill registry & loader
│ │ ├── src/
│ │ │ ├── registry/ # Install, version, resolve
│ │ │ ├── marketplace/ # Publish, search, review
│ │ │ └── loader/ # Runtime skill injection
│ │ └── package.json
│ │
│ ├── api/ # @agentos/api — REST + WebSocket API
│ │ ├── src/
│ │ │ ├── routes/ # Hono route handlers
│ │ │ ├── middleware/ # Auth, rate-limit, tenant-context
│ │ │ ├── ws/ # WebSocket event streaming
│ │ │ └── webhooks/ # Inbound/outbound webhook handlers
│ │ └── package.json
│ │
│ ├── dashboard/ # @agentos/dashboard — Next.js web UI
│ │ ├── src/
│ │ │ ├── app/ # Next.js app router
│ │ │ ├── components/ # UI components
│ │ │ └── lib/ # Client-side SDK usage
│ │ └── package.json
│ │
│ ├── sdk/ # @agentos/sdk — TypeScript client SDK
│ │ ├── src/
│ │ │ ├── client.ts # API client
│ │ │ ├── types.ts # Re-exported types
│ │ │ └── stream.ts # Real-time event stream
│ │ └── package.json
│ │
│ └── cli/ # @agentos/cli — CLI tool
│ ├── src/
│ │ ├── commands/ # agent, session, skill, heartbeat, dream
│ │ └── config/ # Local config management
│ └── package.json
│
├── infra/ # Infrastructure as code
│ ├── supabase/ # Migrations, RLS policies, edge functions
│ ├── docker/ # Dockerfiles for each service
│ └── fly/ # Fly.io deployment configs
│
├── turbo.json # Turborepo config
├── package.json # Root workspace
├── tsconfig.base.json # Shared TS config
└── README.md---
Decomposition Rules
### Atomic Unit
One checklist item = one of:
- A single file/module created with clear interface
- A single API endpoint (route + handler + test)
- A single database migration
- A single integration between two modules
### Maximum Scope Per Task
- No task should touch more than 3 packages
- No task should exceed ~500 lines of new code
- No task should take more than 1 Pulse session
---
Validation Rules
### Per-Module
- TypeScript compiles with `strict: true`
- Exports have JSDoc comments
- Unit tests cover public API (>80
### Per-API-Endpoint
- OpenAPI spec matches implementation
- Request/response types generated from schema
- Rate limiting configured
- Auth middleware applied
### Per-Migration
- Up and down migrations exist
- RLS policies applied
- Tested with multi-tenant data
### Per-Integration
- Event types are shared via @agentos/core
- Error handling includes circuit breaker
- Retry logic is idempotent
---
Created: 2026-02-03 | Phase Zero
Promotion Decision
Keep in the searchable backlog until it intersects a live paper or system.
Source Anchor
unified-agent-os/.governance/IMPLEMENTATION_GUIDE.md
Detected Structure
Method · Figures · Code Anchors · Architecture