rdev/vision.md

rdev: The Agent's Operating System

Platform: threesix.ai Category: Infrastructure / Agent Orchestration Platform Role: The runtime environment where AI agents become software engineers

The Problem: Agents Have No Workspace

Current agent systems suffer from The Phantom Limb problem: agents can think but they can't do. They generate code but have nowhere to run it. They propose changes but have no git repo. They want to deploy but have no infrastructure.

When you ask an agent to "build a landing page," it must:

• Beg for shell access (security nightmare)
• Dump code to chat (copy-paste purgatory)
• Hope you handle infra (manual setup hell)

Real example: A founder asks Claude to build a product landing page. Claude writes the code, but now what? The founder needs to set up a git repo, configure CI/CD, buy a domain, provision DNS, create a database, and figure out deployment. By the time infra is ready, the enthusiasm is gone. The code sits in a chat log. The product never launches.

The Solution: Give Agents a Full Developer Environment

rdev rejects the idea that agents are just "code generators." Instead, it models agent work as a Controlled Development Environment:

• Projects are isolated. Each agent workspace is a Kubernetes pod with its own git repo, secrets, and environment.
• Commands are executed. Shell, Git, and Claude Code commands run inside pods, not locally.
• Infrastructure is automatic. Git repos, CI/CD, DNS, databases, caches, and deployments provision on demand.
• Feature delivery is deterministic. A 10-phase SDLC lifecycle guides every feature from idea to production.

The Four Pillars

Every use case must demonstrate at least one pillar. If a shell script could do it, it's not a compelling use case.

Pillar	What It Enables	Shell Script Gap
First-Class Isolation	Each project in its own pod with dedicated workspace, credentials, network	Shared machine, credential leakage, no boundaries
Deterministic SDLC	Every feature follows 10-phase lifecycle with classifier-driven transitions	Manual process, skipped steps, undefined state
Infrastructure Orchestration	Git, CI/CD, DNS, DB, cache, deployment created via API	Hours of manual setup per project
Observable Execution	Every command logged, streamed, auditable	Fire-and-forget scripts, no visibility

The Core Data Model: The Project

The atomic unit is not a Container, VM, or Directory. It is the Project:

type Project struct {
    // Identity
    ID          string            // Kubernetes pod name
    Name        string            // Human-readable name
    Namespace   string            // K8s namespace isolation

    // Infrastructure
    GitRepo     *GitRepo          // Gitea repo with SSH/HTTPS URLs
    Domain      *Domain           // Custom subdomain + TLS
    Database    *Database         // CockroachDB isolated tenant
    Cache       *Cache            // Redis ACL-scoped namespace

    // Execution
    Status      ProjectStatus     // Running, Stopped, Failed
    Agent       CodeAgent         // Claude Code, OpenCode, etc.
    WorkDir     string            // /workspace inside pod

    // SDLC
    Features    []Feature         // Active feature branches
    Classifier  ClassifierEngine  // State machine for transitions
}

The SDLC Lifecycle

Every feature follows a deterministic 10-phase lifecycle. The classifier engine evaluates state and returns the next valid action.

Phase	What Happens	Artifacts Produced
Draft	Feature captured as rough idea	spec.md draft
Specified	Requirements refined, acceptance criteria defined	spec.md approved
Planned	Implementation strategy designed	design.md with component breakdown
Ready	Tasks extracted, blockers resolved	tasks.md with implementation items
Implementation	Code written task-by-task	Code commits, test coverage
Review	Code reviewed for quality	Review comments, fixes
Audit	Tech debt and security checked	Audit report
QA	Feature tested against spec	QA checklist, evidence
Merge	Feature branch merged to main	Git merge commit
Released	Deployed to production	Deployment record

The classifier is a pure function: given current state, it returns the next action. No ambiguity. No skipped steps.

The Work Queue: Scaled Agent Labor

Multiple agents can work across projects via the Worker Pool:

type WorkTask struct {
    // Identity
    ID          string            // UUID
    ProjectID   string            // Target project
    Command     string            // claude, shell, git

    // State
    Status      TaskStatus        // pending → running → completed/failed
    WorkerID    *string           // Assigned worker
    Error       *WorkTaskError    // Classified failure

    // Lifecycle
    Attempts    int               // Retry count
    CreatedAt   time.Time
    StartedAt   *time.Time
    CompletedAt *time.Time
}

Workers are stateless pods that poll for tasks. When a worker claims a task, it:

1. Executes the command in the target project's pod
2. Streams output back via SSE
3. Reports success/failure with error classification

Error classification enables smart retries:

Error Class	Behavior
RateLimited	Exponential backoff
AuthFailed	Fail immediately, notify
Timeout	Retry with longer timeout
StaleWorker	Reassign to healthy worker
ResourceExhausted	Wait for capacity

The Infrastructure Stack

A single API call provisions complete project infrastructure:

POST /projects
{
  "name": "acme-landing",
  "template": "astro-landing"
}

This triggers:

Step	Adapter	Result
1. Git repo	Gitea	git@gitea.orchard9.ai:projects/acme-landing.git
2. CI/CD	Woodpecker	Pipeline auto-activated, webhooks configured
3. DNS	Cloudflare	acme-landing.threesix.ai A record
4. TLS	Kubernetes	Wildcard cert via cert-manager
5. Database	CockroachDB	Tenant acme_landing with isolated schema
6. Cache	Redis	ACL-scoped acme-landing:* keys
7. Deployment	Kubernetes	Deployment + Service + Ingress

Total time: ~30 seconds. Manual equivalent: ~3 hours.

Architecture: The Hexagonal Stack

Layer	Package	Role
Handlers	internal/handlers/	HTTP endpoints, request validation, auth
Services	internal/service/	Business logic orchestration
Ports	internal/port/	Interface contracts (no implementation)
Adapters	internal/adapter/	Infrastructure implementations
Domain	internal/domain/	Pure business models (zero dependencies)

The hexagonal metaphor:

• Domain: Pure truth. No imports except stdlib.
• Ports: Contracts. What the domain needs from the world.
• Adapters: Implementations. Kubernetes, Postgres, Gitea, etc.
• Services: Orchestration. Coordinate ports to achieve business goals.

                    ┌────────────────────┐
                    │   HTTP Handlers    │
                    └─────────┬──────────┘
                              │
                    ┌─────────▼──────────┐
                    │   Service Layer    │
                    └─────────┬──────────┘
                              │
        ┌─────────────────────┼─────────────────────┐
        │                     │                     │
┌───────▼───────┐   ┌────────▼────────┐   ┌───────▼───────┐
│   Kubernetes  │   │    PostgreSQL   │   │     Gitea     │
│   Adapter     │   │    Adapter      │   │    Adapter    │
└───────────────┘   └─────────────────┘   └───────────────┘

The Agent Registry

rdev supports multiple agent providers through a unified interface:

Agent	Capabilities	Use Case
Claude Code	Full IDE replacement, complex reasoning	Feature implementation
OpenCode	Fast iteration, cost-effective	Simple fixes, testing
Custom	Extensible via registry	Specialized workflows

Agents are interchangeable. The same work task can target different agents based on complexity, cost, or capability requirements.

Key Capabilities

Streaming Execution

Commands stream output in real-time via Server-Sent Events:

GET /projects/acme-landing/events
Accept: text/event-stream

data: {"type":"output","line":"Installing dependencies..."}
data: {"type":"output","line":"Building production bundle..."}
data: {"type":"complete","exit_code":0}

SDLC Orchestration

Ask the classifier what to do next:

GET /projects/acme-landing/sdlc/features/user-auth/next

{
  "action": "implement-task",
  "task_id": "task-003",
  "reason": "All blockers resolved, tasks available"
}

Operation Audit Trail

Every operation is logged with step-level granularity:

GET /projects/acme-landing/audit

[
  {
    "operation_id": "op-123",
    "type": "sdlc_execute",
    "steps": [
      {"name": "read_state", "status": "completed", "duration_ms": 45},
      {"name": "classify", "status": "completed", "duration_ms": 12},
      {"name": "execute_action", "status": "completed", "duration_ms": 8234}
    ]
  }
]

Visual Verification (Planned)

Playwright captures screenshots and video for AI evaluation:

POST /projects/acme-landing/verify
{
  "url": "https://acme-landing.threesix.ai",
  "viewports": ["desktop", "tablet", "mobile"],
  "capture_video": true
}

The Composable Monorepo

Projects can be composable monorepos with independent components:

acme-platform/
├── services/
│   ├── api/           # Go API service
│   └── worker/        # Background job processor
├── apps/
│   ├── web/           # React frontend
│   └── landing/       # Astro marketing site
└── packages/
    └── shared/        # Shared types and utilities

Each component has:

• Independent deployment pipeline
• Own database/cache isolation
• Separate CI/CD triggers
• Shared monorepo patterns

The Git Analogy

Git Concept	rdev Equivalent
Repository	Project (isolated pod with workspace)
Branch	Feature (SDLC lifecycle instance)
Commit	Artifact (spec, design, code, test)
Merge	Phase transition to Released
CI/CD	Woodpecker pipeline (auto-triggered)
Deploy	Kubernetes Deployment (auto-provisioned)

When to Use rdev

Use rdev when:

• You want agents to execute code, not just generate it
• You need isolated, auditable agent workspaces
• You want deterministic feature delivery with clear phases
• You need complete project infrastructure on demand
• You're building a platform where agents do development work

Use raw Kubernetes when:

• You're running traditional containerized workloads
• You don't need agent execution capabilities
• You want manual control over every resource
• You're not doing agent-driven development

Use GitHub/GitLab when:

• You have human-only development workflows
• You want managed SaaS with full features
• You don't need agent isolation

For agent-driven development at scale: rdev is the operating system.

Future Vision

Multi-Cluster Federation (Planned)

Projects distributed across clusters based on region, compliance, or capacity.

Agent Collaboration (Planned)

Multiple agents working on the same project with coordination protocols and conflict resolution.

Pattern Learning (Planned)

Successful patterns extracted from completed features and applied to new projects automatically.

The Swarm (Planned)

A pool of specialized agents (frontend, backend, devops, QA) that self-organize around feature delivery.

The Kubernetes Analogy

K8s Concept	rdev Purpose
Pod	Project isolation boundary
Namespace	Multi-tenancy separation
Service	Internal project communication
Ingress	External project access
ConfigMap	Project configuration
Secret	Encrypted credentials
Job	Work task execution
CronJob	Scheduled maintenance

Why "Remote Developer"?

The name captures the essence: rdev is a remote developer that never sleeps.

• Remote: Runs in the cloud, accessible via API
• Developer: Does real development work, not just code generation
• Deterministic: Every action follows defined rules
• Observable: Every operation is logged and auditable
• Scalable: Worker pools handle unlimited concurrent tasks

When you dispatch work to rdev, you're not asking for code suggestions. You're assigning a task to a developer who will:

1. Clone the repo
2. Create a feature branch
3. Write the code
4. Run the tests
5. Submit for review
6. Deploy to production

The difference? This developer is an AI agent with a full development environment, not a human with a laptop.

---

rdev: Give your agents a proper workspace.