disler/super-simple-software-factory

What it solves

Super Simple Software Factory (SSSF) addresses the inconsistency and lack of observability in AI-driven software development. It prevents the "machine with no seams" problem where a single agent loop is unpredictable, lacks clear phase boundaries, and is difficult to debug. By moving the control plane from the prompt into deterministic Python code, it ensures that software creation is repeatable, gated, and observable.

How it works

SSSF operates on the principle that code owns the loop, while agents are bounded nodes within that loop. It uses an AI Developer Workflow (ADW) script to manage sequencing, retries, and acceptance criteria.

• Phases: Every run is a sequence of phases. These can be agent phases (where a specific agent is called) or code phases (deterministic Python/bash steps like running tests or committing to git).
• Agent Roster: A YAML configuration file defines the identity of each agent (model, prompt, tools, and boundaries). This allows different models to be used for different tasks (e.g., a frontier model for planning, a cheaper model for building).
• Envelopes and Gates: Agents communicate via typed JSON envelopes. After an agent finishes, "gates" (automated checks) verify the agent's claims (e.g., checking if files actually exist or if tests pass). If a gate fails, the system re-prompts the agent within the same session for a correction rather than restarting the entire process.
• Observability: Every event, including tool calls, is streamed in real-time to a SQLite database. A provided Vue/Vite visualizer allows users to monitor runs mid-flight through a trace waterfall.

Who it’s for

Software engineers who want to build repeatable, professional-grade AI agent workflows for coding tasks, moving beyond simple prompting to a structured system of agents and code.

Highlights

• Deterministic Control Plane: Moves sequencing and sequencing logic out of the prompt and into Python.
• Agent-Code Hybrid: Explicitly separates agentic decision-making from deterministic code execution (e.g., bun test is a code phase, not an agent task).
• Customizable Roster: Per-agent configuration for models, thinking levels, and tool access.
• Strict Boundaries: Enforces read-only or write-restricted access for agents to prevent unauthorized repo changes.
• Real-time Trace UI: A dedicated visualizer for polling a SQLite database to monitor agent activity and
• Correction Loops: Uses session-based corrections to fix errors without losing context or incurring the cost of a cold restart.