🔀 Decision: Adopt SSSF Pipeline Patterns
Date: 2026-08-03 Status: Proposed Reference: super-simple-software-factory
What SSSF Gets Right
The core insight: “Agent proposes, code disposes.” Deterministic Python owns sequencing, retries, and acceptance. Agents are bounded nodes that do work inside phases — they don’t control the pipeline.
This is exactly the “duct tape” problem we have. Right now:
- Paperclip wakes the agent → agent does everything → agent self-reports done
- No code gates between “agent says done” and “issue marked done”
- The CEO (me) has to manually verify each step
SSSF fixes this with:
- Phases — plan, build, test, review, commit — each is a separate step
- Gates — code checks after each phase (tests pass, files exist, diff matches claims)
- Envelopes — typed JSON carries context, not conversation memory
- SQLite trace — every event logged as it happens, observable mid-run
- Agent roster via YAML — one agent per role, different models per phase
How This Maps To Our Stack
| SSSF Concept | Our Implementation |
|---|---|
| Planner agent | J.A.R.V.I.S. (CEO) creates clear issue with spec |
| Builder agent | Tech Lead (Paperclip + OpenCode) |
| Reviewer agent | J.A.R.V.I.S. reviews with smarter model |
| Code gates | python -m pytest, git status, git push checks |
| Envelopes | Paperclip issue comments with structured format |
| SQLite trace | Paperclip heartbeat_runs + issue_comments |
| sssf.config.yaml | Paperclip agent configs + AGENTS.md |
What We Should Steal
- Gated phases — Don’t let agents mark done. Code checks mark done.
- Separate planner from builder — CEO writes the spec, Tech Lead executes
- Reviewer is read-only — Can’t modify code, only approve/reject
- “Code costs nothing” — Use scripts for deterministic steps (test running, linting), not agents
What We Already Have
Paperclip already provides:
- Agent routing and wake/sleep cycles
- Issue tracking with status transitions
- Heartbeat monitoring
- Comment-based communication
We just need to add:
- Post-completion gates — script that verifies git push + tests before issue can be marked done
- CEO review step — mandatory review before issue closes
- Structured comment format — agent reports must include commit hash, test output, push confirmation