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**:

```go
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**:

```go
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:

```http
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:

```http
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:

```http
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:

```http
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:

```http
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.**