Super Simple Software Factory: a Python control plane with coding agents as bounded nodes

The problem: an agent that writes code once but never the same way twice

The README states the failure mode plainly: everyone can get an agent to write code once, almost nobody gets the same result twice. When one model owns its own loop, there is no phase boundary, so you cannot say which step failed. There is no acceptance criterion you can name, so done means the agent stopped talking. A retry is a cold start that discards what the agent just learned, and the only trace is a transcript you read like a novel.

The project's answer is a division of labour. Code owns sequencing, retries and acceptance. The agent owns only the work inside one bounded phase. That single line produces the rest of the design: phases become the unit of the trace, typed JSON envelopes become the only way context crosses a seam, and gates become the definition of done.

It is aimed at engineers who already drive coding agents from a shell and are tired of nondeterministic multi-step runs. It is not aimed at someone who wants a hosted service with a dashboard and a billing page, because there is no such thing here: the repository is a skill directory plus Python scripts.

How the control plane works: ADW scripts, phases, envelopes and a SQLite trace

An ADW script (AI Developer Workflow) is the top-level Python program that owns a run. It decides sequencing, retries and acceptance. Agents are invoked as nodes inside named phases rather than being handed the whole SDLC. The README describes the run as swim lanes on a time axis: engineer, code, planner, builder and reviewer phases, each block labelled with its duration, with one phase still running and the next still queued.

Context crosses a seam as a typed JSON envelope. That is the mechanism worth understanding, because it is what makes a correction cheaper than a restart. When a phase fails, the failure comes back to the builder as an envelope through the same door an agent's report would have used, so the repair loop is identical whether the failing node was a model or a subprocess.

Every event streams into SQLite while the run is still happening, and the UI polls that database. The README names the file as adws/adw_data/sssf.db. Because the trace is written during the run rather than reconstructed afterwards, you can inspect a phase that is still executing instead of waiting for a final transcript.

The design also makes a deliberate distinction about when not to use a model. A phase can be declared kind="code". The README's example is that bun test is not a judgement call and neither is ruff check, so invoking an agent to rediscover your test runner burns a context window to learn what a subprocess already knows, and charges for it on every run. Agents are for the parts that need reading and deciding.

Installing the sssf skill and running your first two phases

There are two install paths. The agentic one copies .claude/skills/sssf/ into the target repo and then you type /sssf install inside Claude Code. The README is explicit that the skill is named sssf, so the command is the skill name followed by the install argument, and there is no bare /install command. The agent then reads the skill's own cookbooks/install.md.

The manual path has prerequisites: uv, pi, sqlite3, and an API key for whichever providers your roster names. bun is needed only for the visualizer. Copy the skill directory first.

mkdir -p .claude/skills
cp -r /path/to/super-simple-software-factory/.claude/skills/sssf .claude/skills/

Then stamp the factory. The README stresses that this runs from the target repo root, because the current working directory is where everything lands.

uv run .claude/skills/sssf/scripts/install.py
cp .env.sample .env
pi --version
git init && git commit --allow-empty -m init

The .env copy is where you set OPENROUTER_API_KEY. The pi --version check confirms pi is on PATH, or you set PI_PATH in .env instead. The git commit matters because chains that end in a commit phase need an existing repository.

The smoke test is two cheap read-only runs, end to end. just demo runs them, just sessions shows what just happened, and just obs opens the trace UI, which needs bun. If you do not have just, every recipe is one line, and the raw form of just demo is shown in the README as follows.

uv run adws/adw_prompt.py "reply with a one-line summary of this repo" --agent scout

Green on the smoke test means the whole path works: config validated, session minted, Pi ran, envelope parsed, events landed in adws/adw_data/sssf.db. Fix it there before composing anything larger, because every multi-agent chain rides this exact path. Re-running install.py is safe: it skips files that already exist and reports what it skipped, so a second run doubles as a drift check. The --force flag refreshes stamped code but overwrites all stamped files, including sssf.config.yaml and your prompts, so commit first.

Which API keys you need depends on your roster, not on this repo

Every model entry in sssf.config.yaml is written as provider/model-id, and the provider half decides which key is required. Which key pi reads for a given provider comes from ~/.pi/agent/models.json. That indirection is the part that will confuse a first-time user, because the config file alone does not tell you what to export.

The starter roster deliberately mixes providers, so out of the box it wants three keys. The default, builder and scout models are google/gemini-3.6-flash, served via openrouter, so they need OPENROUTER_API_KEY. The planner is fireworks/accounts/fireworks/models/kimi-k3, which needs FIREWORKS_API_KEY. The reviewer and documenter are openai/gpt-5.6-terra and openai/gpt-5.6-luna, which need OPENAI_API_KEY.

The practical consequence is that a fresh clone is not runnable with one key. You either hold all three, or you edit the roster so every model resolves to a provider you already pay for. That is a configuration decision the README leaves to you, and it is worth making before the smoke test rather than after a failed run.

Where the factory is the wrong tool

The repository does not ship a rollback story, and the README does not document one. The only destructive operation it describes is --force, which overwrites all stamped files including your configuration and prompts. The mitigation offered is to commit first. There is no described mechanism for reverting a stamped factory to a previous version other than your own version control.

A second boundary is the dependency chain. You need uv, pi, sqlite3 and at least one provider key before anything runs, and the trace UI additionally needs bun. That is a real install surface for what the README frames as a simple factory. If your team standardises on a different agent runtime, the bounded-node design does not transfer without rewriting the invocation layer, because the skill drives pi.

Third, the value proposition is explicitly a bet on repetition. The README says the bill for skipping the code-versus-agent distinction is paid on run one hundred and run one thousand, not on run one. If you are doing a one-off refactor, the setup cost of a stamped config, a roster and a trace database is not repaid. This is infrastructure for workflows you intend to run many times, not a tool for a single large task.

Finally, the deterministic claim has a limit. Python owns sequencing and acceptance, but the nodes are still models. The graph is repeatable; the output inside a phase is not guaranteed identical. What you get is a named place to look when a phase misbehaves, not reproducibility of the model's text.

How this differs from chaining agents in a single prompt

The obvious alternative is the pattern most people already use: one capable model with a long prompt that tells it to plan, implement, test and review, sometimes with sub-agents spawned from inside that loop. The difference is where the control plane lives.

In the single-prompt approach, the model owns sequencing. Phase boundaries exist only as prose in the prompt, so a failure is diagnosed by reading the transcript and guessing which instruction was dropped. Retries restart the conversation. There is no acceptance criterion you can name, which is exactly the problem the README opens with.

Here, sequencing lives in an ADW script. The model cannot skip a phase or reorder the graph, because it does not own the graph. Retries are handled by Python, and because the session stays alive, a correction is cheaper than a restart. The trace is a SQLite table written during the run rather than a transcript you parse afterwards.

The trade-off is real in both directions. A single prompt is faster to write and needs no install. This project needs a stamped directory, a roster of providers, and a working pi on PATH before the first phase runs. You are buying diagnosability and repeatability with setup time, and the README is upfront that the return shows up at scale.

Licence and the cost of keeping a stamped factory current

The repository is MIT licensed, which permits use, modification and redistribution provided the copyright notice and permission notice are retained. That is permissive enough for internal tooling and for stamping into a proprietary repository. This is a description of the licence text, not legal advice; if the factory ends up inside a product you distribute, have counsel read the LICENSE file rather than this paragraph.

The upgrade path is the interesting cost. Because the factory is stamped into your repo rather than installed as a dependency, there is no package manager tracking a version for you. Keeping current means re-running install.py, which skips existing files and reports what it skipped, and that report is effectively your drift check. Refreshing stamped code to the skill's current version means --force, which overwrites all stamped files including sssf.config.yaml and your prompts. So the upgrade ritual is: commit, force, then diff the config and prompts against what you had. Teams that edit their roster heavily will feel that most, because the roster is one of the files --force replaces.

The repository does not list releases, so there is no changelog to read before a refresh. The last push to main was on 2026-08-04, which is recent enough that the code you clone should match the README, but you are diffing against your own last stamp rather than against a version number.

Editorial conclusion

Adopt it if you already run coding agents from a terminal and want the sequencing, retries and acceptance criteria to live in Python instead of a prompt. Skip it if you want a hosted product or a GUI-first workflow: this is a skill directory you copy into a repo, and the visualizer needs bun. Before committing to it, run the two read-only smoke runs and confirm the events land in adws/adw_data/sssf.db, then check that ~/.pi/agent/models.json maps every provider named in sssf.config.yaml to a key you hold.

Frequently asked questions

Official sources

1. disler/super-simple-software-factory on GitHub
2. Issues
3. License: MIT
4. Project website
5. README