137 lines
4.9 KiB
Markdown
137 lines
4.9 KiB
Markdown
# Software Factory: Paperclip Integration
|
|
|
|
Close the loop: Plan → Build → Test → Verify → Ship, orchestrated through Paperclip with JWT auth.
|
|
|
|
---
|
|
|
|
## Overview
|
|
|
|
The course teaches 5 pillars. Paperclip is the infrastructure that runs them as an autonomous factory.
|
|
|
|
| Course Module | Course Concept | Paperclip Component |
|
|
|---------------|---------------|---------------------|
|
|
| M1 | Agent Harness | Agent definitions, adapter config |
|
|
| M3 | Security (L0-L5) | Damage control, JWT auth tiers |
|
|
| M4 | Orchestration | Org chart, goals, delegation |
|
|
| M5 | CI/CD Production | Heartbeat execution, budgets |
|
|
| M6 | Economics | Cost tracking per agent/task |
|
|
| M7 | Always-On Agents | Scheduled routines, heartbeats |
|
|
|
|
---
|
|
|
|
## Authentication Tiers (from Paperclip)
|
|
|
|
Paperclip supports 3 JWT auth tiers matching your security needs:
|
|
|
|
| Tier | Trust Model | Token | Use Case |
|
|
|------|-------------|-------|----------|
|
|
| **1. Local** | Same machine | Short-lived JWT (48h) | Local dev, claude-local adapter |
|
|
| **2. CLI** | Shell access | Long-lived API key | Remote agents, CI/CD |
|
|
| **3. Self-register** | Autonomous external | Invite URL → JWT | OpenClaw, third-party agents |
|
|
|
|
Tier 1 is the simplest: Paperclip mints a JWT, passes it to the agent as `PAPERCLIP_API_KEY` at invocation time. No manual setup.
|
|
|
|
---
|
|
|
|
## Quick Start: Paperclip + Course Stack
|
|
|
|
```bash
|
|
# 1. Start Paperclip in auth mode
|
|
cd paperclip
|
|
pnpm dev --bind lan
|
|
|
|
# 2. Verify health
|
|
curl -sS http://127.0.0.1:3100/api/health | jq
|
|
|
|
# 3. Create an agent in Paperclip UI
|
|
# - Go to http://127.0.0.1:3100/CLA/company/agents
|
|
# - Create agent with adapter type matching your CLI
|
|
|
|
# 4. Run a task through the factory pipeline
|
|
```
|
|
|
|
---
|
|
|
|
## Factory Pipeline
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ FACTORY PIPELINE │
|
|
│ │
|
|
│ PLAN ──► BUILD ──► TEST ──► VERIFY ──► SHIP │
|
|
│ │ │ │ │ │ │
|
|
│ ▼ ▼ ▼ ▼ ▼ │
|
|
│ CEO Agent CI/CD Verifier Paperclip │
|
|
│ Board Chains Pipeline Agent Heartbeat │
|
|
│ │
|
|
│ ─────── Paperclip JWT Auth ──────── (all authenticated) ── │
|
|
└─────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
### Step 1: Plan (CEO Board)
|
|
```bash
|
|
# Create a strategic decision in Paperclip as an issue
|
|
# CEO Board agent receives it, debates, produces a plan
|
|
# Plan stored as Paperclip issue with sub-tasks
|
|
```
|
|
|
|
### Step 2: Build (Agent Chains)
|
|
```bash
|
|
# Paperclip heartbeat picks up the task
|
|
# Assigns to coding agent (Claude Code / Pi / OpenCode)
|
|
# Agent runs with Tier 1 JWT auth (PAPERCLIP_API_KEY)
|
|
# Results committed to git worktree
|
|
```
|
|
|
|
### Step 3: Test (CI/CD)
|
|
```bash
|
|
# Golden dataset runs against the code
|
|
# pass@k evaluated
|
|
# If pass rate > threshold, proceed to verify
|
|
# If not, send back to Build
|
|
```
|
|
|
|
### Step 4: Verify (Verifier Agent)
|
|
```bash
|
|
# Read-only verifier agent checks every claim
|
|
# Confidence ladder: PERFECT → VERIFIED → PARTIAL → FEEDBACK → FAILED
|
|
# If FEEDBACK or FAILED, send back to Build
|
|
# If PERFECT or VERIFIED, proceed to Ship
|
|
```
|
|
|
|
### Step 5: Ship (Paperclip Heartbeat)
|
|
```bash
|
|
# Paperclip marks issue as done
|
|
# Heartbeat run logged with cost and token usage
|
|
# Next heartbeat picks up next task
|
|
# Factory continues autonomously
|
|
```
|
|
|
|
---
|
|
|
|
## Why JWT Auth Closes the Loop
|
|
|
|
Without JWT auth, each step requires manual credential setup. With JWT:
|
|
|
|
1. **Plan**: CEO Board agent has a Paperclip API key → can create issues
|
|
2. **Build**: Coding agent receives JWT at invocation → authenticates to Paperclip → reports progress
|
|
3. **Test**: CI/CD runner has a service account → posts results back to Paperclip
|
|
4. **Verify**: Verifier agent has read-only JWT → checks work, reports confidence
|
|
5. **Ship**: Paperclip heartbeat authenticates to itself → marks done, logs costs
|
|
|
|
No human touches credentials at any step. The factory runs lights-off.
|
|
|
|
---
|
|
|
|
## Status: What's Ready
|
|
|
|
Paperclip's auth plan documents all 3 tiers. The local adapter (Tier 1) is partially implemented — env vars are passed, the `PAPERCLIP_API_KEY` JWT just needs to be added to the env injection. This is the last code change needed before the factory loop closes completely.
|
|
|
|
## Status: What's Needed
|
|
|
|
```
|
|
[ ] Add PAPERCLIP_API_KEY (JWT) to local adapter env injection
|
|
[ ] Create factory pipeline skill that chains the 5 steps
|
|
[ ] Add factory dashboard showing pipeline status in Paperclip UI
|
|
```
|