64ccf0b85d
- Add feature-dev-test.sh: full 10-step E2E test for SDLC + Claude Code workflow - Update feature-development.md cookbook with complete workflow documentation - Fix SDLC orchestrator and project management handler improvements - Update scaffold-test.sh with minor fixes Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
296 lines
13 KiB
Markdown
296 lines
13 KiB
Markdown
# 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?
|