rdev/cookbooks/VISION.md

threesix.ai Platform Vision

Agent-driven development at scale: 50+ projects, each with autonomous build capability.

The Vision

Team Member → Bot (Pantheon) → "Create a new project called X"
                    │
                    ▼
            ┌───────────────────────────────────────────────────┐
            │              rdev-api orchestrates:               │
            │                                                   │
            │  1. Create Gitea repo (jordan/X)                  │
            │  2. Activate Woodpecker CI (webhook auto-created) │
            │  3. Spin up claudebox-X (dedicated pod)           │
            │  4. Initialize .claude/ structure                 │
            │  5. Create DNS record (X.threesix.ai)             │
            │                                                   │
            └───────────────────────────────────────────────────┘
                    │
                    ▼
            ┌───────────────────────────────────────────────────┐
            │         claudebox-X ready for development         │
            │                                                   │
            │  Option A: Human directs Claude via Pantheon      │
            │            "Build a landing page for X"           │
            │                                                   │
            │  Option B: Bot autonomously builds based on spec  │
            │            "Here's the PRD, build it"             │
            │                                                   │
            └───────────────────────────────────────────────────┘
                    │
                    ▼
            Push to Gitea → Woodpecker builds → K8s deploys
                    │
                    ▼
            Live at https://X.threesix.ai

---

Current State vs Vision

Capability	Status	What Exists	Gap
Create Gitea repo	✅	POST /project	None
Create DNS record	✅	POST /project	None
Activate Woodpecker	⚠️	API exists, not wired	Add to POST /project
Spin up claudebox	❌	Manual StatefulSet	Need dynamic claudebox creation
Initialize .claude/	❌	Nothing	Need template + init
Human directs Claude	✅	POST /projects/{id}/claude	Works for existing claudeboxes
Bot autonomous build	⚠️	Claude endpoint exists	Need prompt orchestration
K8s deployment	✅	Webhook + deployer	Works

---

Gap Analysis

Gap 1: Woodpecker Activation Not in Project Creation

Current: Two separate API calls

POST /project              # Creates Gitea + DNS
POST ci.threesix.ai/api/repos?forge_remote_id=X  # Activates Woodpecker

Needed: Single call does both

POST /project  # Creates Gitea + DNS + Activates Woodpecker

Fix: Add WOODPECKER_API_TOKEN to rdev-api config, call Woodpecker API after Gitea creation.

---

Gap 2: No Dynamic Claudebox Creation

Current: Claudeboxes are manually created StatefulSets

# Each project needs a manually deployed claudebox-{project}.yaml
claudebox-pantheon-0   # Exists
claudebox-aeries-0     # Exists
claudebox-landing-0    # Does NOT exist

Needed: API creates claudebox on-demand

POST /project {"name": "landing"}
# Also creates claudebox-landing StatefulSet

Fix:

• Create claudebox template (parameterized StatefulSet)
• Add K8s client to rdev-api for creating StatefulSets
• Wire into POST /project flow

Resource consideration: Each claudebox uses ~256Mi-1Gi RAM. 50 projects = 12-50Gi RAM dedicated to claudeboxes. May need:

• On-demand spin-up (idle claudeboxes scale to 0)
• Shared worker pool (fewer claudeboxes, more projects)

---

Gap 3: No .claude/ Initialization

Current: Empty repo after creation

Needed: Repo initialized with Claude structure

project/
├── .claude/
│   ├── CLAUDE.md           # Project context
│   ├── commands/           # Slash commands
│   ├── skills/             # Reusable skills
│   └── agents/             # Agent definitions
├── .woodpecker.yml         # CI pipeline
└── README.md               # Basic readme

Fix:

• Create template repo or init script
• Claudebox runs init on first creation
• Or: Gitea repo template feature

---

Gap 4: Project ↔ Claudebox Mapping

Current: Two separate registries

• Projects: /project API (Gitea + DNS based)
• Claudeboxes: /projects API (K8s pod label based)

Needed: Unified registry

POST /project/landing/claude  # Works because landing has a claudebox

Fix:

• Merge the two systems
• Project creation = Gitea + DNS + Claudebox + Woodpecker
• Single source of truth (database)

---

Gap 5: Prompt Orchestration for Autonomous Build

Current: Raw prompt execution

POST /projects/pantheon/claude
{"prompt": "build a landing page"}  # Claude figures it out

Needed: Structured build orchestration

POST /project/landing/build
{
  "spec": "Create Astro landing page with coming soon message",
  "stack": "astro",
  "auto_deploy": true
}

Fix:

• Build orchestrator service
• Stack templates (astro, nextjs, go-api, etc.)
• Progress tracking
• Auto-commit and push

---

Proposed Architecture

┌─────────────────────────────────────────────────────────────────────────────┐
│                              rdev-api                                        │
│                                                                              │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐              │
│  │ Project Service │  │ Claudebox Mgr   │  │ Build Service   │              │
│  │                 │  │                 │  │                 │              │
│  │ - Create repo   │  │ - Create pod    │  │ - Stack temps   │              │
│  │ - Setup DNS     │  │ - Scale up/down │  │ - Orchestrate   │              │
│  │ - Activate CI   │  │ - Health check  │  │ - Auto-deploy   │              │
│  └────────┬────────┘  └────────┬────────┘  └────────┬────────┘              │
│           │                    │                    │                        │
│           └────────────────────┴────────────────────┘                        │
│                                │                                             │
│                    ┌───────────┴───────────┐                                │
│                    │   Unified Project DB   │                                │
│                    │                        │                                │
│                    │ - project_id           │                                │
│                    │ - gitea_repo           │                                │
│                    │ - claudebox_pod        │                                │
│                    │ - woodpecker_id        │                                │
│                    │ - dns_record           │                                │
│                    │ - build_status         │                                │
│                    └────────────────────────┘                                │
│                                                                              │
└─────────────────────────────────────────────────────────────────────────────┘
                                 │
                                 ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                           Infrastructure                                     │
│                                                                              │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐      │
│  │  Gitea   │  │Woodpecker│  │   Zot    │  │Cloudflare│  │   K8s    │      │
│  │ git.ts.ai│  │ ci.ts.ai │  │ registry │  │   DNS    │  │ projects │      │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘  └──────────┘      │
│                                                                              │
└─────────────────────────────────────────────────────────────────────────────┘

---

Implementation Phases

Phase A: Wire Woodpecker into Project Creation

• Add WOODPECKER_API_TOKEN to rdev-api
• After Gitea repo creation, activate in Woodpecker
• Test: POST /project activates CI automatically

Phase B: Dynamic Claudebox Creation

• Create claudebox template (parameterized YAML)
• Add K8s StatefulSet creation to rdev-api
• Wire into project creation
• Test: POST /project spins up claudebox-{name}

Phase C: .claude/ Initialization

• Create init template for new projects
• Claudebox runs init on startup
• Test: New project has .claude/ structure ready

Phase D: Unified Project Registry

• Merge project management and claudebox systems
• Single database tracks all project state
• /projects/{id}/claude works for any project

Phase E: Build Orchestration

• Stack templates (astro, nextjs, go-api)
• POST /project/{id}/build endpoint
• Progress tracking and auto-deploy

---

Quick Wins (Do First)

1. Wire Woodpecker activation - 1-2 hours

   • Already have the API call
   • Just needs token in config and call in project creation

2. Use pantheon as shared worker - Works now

   • For MVP, one claudebox can clone/build any project
   • Not scalable but proves the concept

3. Template .woodpecker.yml in project creation - 1 hour

   • When creating Gitea repo, include default .woodpecker.yml
   • Projects are CI-ready from creation

---

Cookbooks

Cookbook	Status	Description
Landing Page	Done	Simple single-component deployment
Feature Development	Done	Full-stack feature with chassis, OpenAPI, auth, design system

E2E Test Scripts

Script	Description
scripts/landing-test.sh	Landing page E2E test
scripts/feature-test.sh	Feature development E2E test
scripts/composable-test.sh	Composable monorepo E2E test
scripts/template-validation.sh	Template validation checks

---

Questions to Resolve

1. Claudebox scaling strategy?

   • One per project (resource heavy, 50 = lots of RAM)
   • Shared worker pool (fewer pods, queue-based)
   • On-demand (scale to zero when idle)

2. Who owns the project?

   • User-scoped (jordan/landing)
   • Org-scoped (threesix/landing)
   • Affects Gitea structure and permissions

3. Pantheon integration?

   • How does the bot receive "create project X" commands?
   • Slash command? Natural language?
   • Response format?