# 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
```