# 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
```bash
POST /project              # Creates Gitea + DNS
POST ci.threesix.ai/api/repos?forge_remote_id=X  # Activates Woodpecker
```

**Needed:** Single call does both
```bash
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
```yaml
# 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
```bash
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
```bash
POST /projects/pantheon/claude
{"prompt": "build a landing page"}  # Claude figures it out
```

**Needed:** Structured build orchestration
```bash
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](./landing-page.md) | Done | Simple single-component deployment |
| [Feature Development](./feature-development.md) | 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-dev-test.sh` | Feature development E2E test (Claude + SDLC flow) |
| `scripts/scaffold-test.sh` | Scaffold validation E2E test (patterns/components) |
| `scripts/composable-test.sh` | Composable monorepo E2E test |
| `scripts/sdlc-test.sh` | SDLC API endpoint validation |
| `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?
