# Shared Build Workspace — How It Works

**Date:** 2026-04-29
**Status:** Active protocol

---

## The Problem We Solved

When Socrates and Daedalus work on the same feature:
- Socrates writes API code in `workspace-socrates/`
- Daedalus writes templates in `workspace-daedalus/` (or sometimes `shared/`)
- Neither sees the other's files until Wadsworth manually copies them
- Integration fails because they built against different assumptions

## The Solution: Shared Build Directory

```
shared/build-{YYYYMMDD}/
├── SPEC.md              ← Wadsworth writes the contract
├── backend/             ← Socrates writes API + routes
│   ├── router.py
│   └── models.py
├── frontend/            ← Daedalus writes templates + CSS
│   ├── index.html
│   └── style.css
└── integration.md       ← Both update as they work
```

## Workflow

### 1. Wadsworth Creates Build Directory

```bash
mkdir shared/build-20260429
cat > shared/build-20260429/SPEC.md << 'EOF'
# Build: Event State Machine

## Contract
- `POST /api/events/{id}/confirm` → HTML response (not JSON)
- `POST /api/events/{id}/decline` → HTML response, fades out
- `POST /api/events/{id}/reschedule` → HTML, accepts form data

## File Mapping
| Agent | Source | Destination |
|-------|--------|-------------|
| Socrates | router.py changes | backend/router_patch.py |
| Daedalus | events.html | frontend/events.html |
| Daedalus | style.css additions | frontend/style_patch.css |

## Integration Check
- [ ] API returns HTML, not JSON
- [ ] Buttons visible on all event types
- [ ] HTMX swap works without page reload
EOF
```

### 2. Dispatched to Both Agents

**Socrates handoff:**
```
What: Build event state API in shared/build-20260429/backend/
Files: shared/build-20260429/SPEC.md
Success: SPEC.md integration checks all pass
```

**Daedalus handoff:**
```
What: Build event buttons in shared/build-20260429/frontend/
Files: shared/build-20260429/SPEC.md
Success: SPEC.md integration checks all pass
```

### 3. Both Work Simultaneously

- Socrates writes `backend/router_patch.py`
- Daedalus writes `frontend/events.html`
- Both check `integration.md` for updates

### 4. Wadsworth Verifies

```bash
# Test integration
curl -H "Host: family.hoffdesk.com" \
  http://localhost:8000/api/events-dashboard | grep button
```

### 5. Merge to Production

```bash
# Copy backend changes
cp shared/build-20260429/backend/router_patch.py \
   workspace-socrates/hoffdesk-api/dashboard/router.py

# Copy frontend changes
cp shared/build-20260429/frontend/events.html \
   shared/project-docs/dashboard/templates/events.html

# Restart server
```

### 6. Archive

```bash
mv shared/build-20260429 shared/archive/build-20260429
```

## Benefits

| Before | After |
|--------|-------|
| Agents write to separate workspaces | Both write to same directory |
| Wadsworth manually copies files | Wadsworth just merges verified build |
| Integration errors discovered late | Integration checked continuously |
| Wrong directory mistakes | Single target, no confusion |
| No rollback | Archive directory = instant rollback |

## When to Use

**Use shared build:**
- API + UI integration (backend + frontend)
- Spec changes affect multiple agents
- Matt wants to review before production

**Use own workspace:**
- Independent backend work (Socrates alone)
- Independent design work (Daedalus alone)
- Quick fixes that don't cross boundaries

## File Template

```markdown
# Build: {feature-name}

## Status: 🟡 IN PROGRESS

## Agent Assignments
| Agent | File | Status |
|-------|------|--------|
| Socrates | backend/ | 🟡 Active |
| Daedalus | frontend/ | 🟡 Active |

## Integration Checks
- [ ] Backend returns correct format
- [ ] Frontend renders correctly
- [ ] Both work together

## Notes
- Socrates: Working on POST endpoints
- Daedalus: Waiting for API spec confirmation
```