Super Simple Software Factory

What It Does

Super Simple Software Factory (SSSF) is a single Claude Code skill (sssf) that stamps a repeatable software-development pipeline into any repository. The pipeline is an ADW (AI Developer Workflow): a deterministic Python script that owns phase sequencing, retries, and acceptance gates, while coding agents work inside named, bounded phases. Typed Pydantic envelopes carry context between agents, every event streams into a SQLite trace database, and a Vue visualizer polls that database live. The thesis, stated in the README and enforced throughout the code, is "agent proposes, code disposes": code owns the loop so the same prompt produces the same system twice. It targets developers and small teams who want their AI coding agents to run unattended through plan, build, test, review, and document phases with real guardrails, rather than one big agent owning its own loop.

The Good

The control-plane design is the right answer to a real problem, and it is enforced in code, not just described in prose. The runner (adw_modules/runner.py) makes success an earned state: every phase defaults to fail, and only a clean exit flips it. The finish() method settles two criteria together (every phase passed AND the run's acceptance test holds), so the SQLite status, the console banner, and the process exit code can never disagree. The README documents a bug this replaced, where a property wrote a green status to the database and terminal while the process exited 1. That kind of self-awareness, where the code records the failure mode it was built to prevent, is the standard the rest of the repo holds.

The permission model is the best GearScope has seen in any agent skill. adw_modules/permissions.py fingerprints the git working tree before an agent runs (via git diff --numstat plus untracked files) and compares it after. This catches what a tool allowlist cannot: an agent with bash that runs git checkout to discard uncommitted work counts as a modification, because a path that was dirty before and clean after has been reverted. Unauthorized changes are rolled back before the phase dies, and anything the rollback cannot undo (already-dirty work that the agent reverted) is named explicitly rather than silently dropped. The _glob translator deliberately makes * stop at a path separator (unlike fnmatch), so adws/adw_*.py cannot accidentally match files under adws/adw_modules/. The config's protected_files defaults to the factory's own code, so an agent can never edit the machinery that grades it. This is real sandboxing for agents, done with git.

The "known command is code, not an agent" rule saves tokens and removes nondeterminism. Hard rule 8 in the SKILL.md and the adw_simple_sdlc.py docstring both argue it directly: bun test and ruff check are not judgement calls, so they run as kind="code" phases through adw_modules/quality.py instead of asking an agent to rediscover the test runner every run. When a code phase fails, the raw runner output travels back to the builder as an envelope through the same door an agent report would use, so the repair loop is identical. This is a concrete, measurable cost reduction that most agent pipelines still pay every run.

All 20 Python modules compile clean and the typed internals verified end to end. The 14 functional checks I wrote against adw_modules all pass: config loads into a typed SSSFConfig with five agents, resolve() finds an agent and raises on a missing one, PhaseParams rejects both blank and name-restating descriptions (the validator is a real construction-time guard), BuildOutput and ReviewOutput envelopes parse, GateReport derives violations correctly, and the permission engine's _glob, _matches, permitted, and changed_paths behave exactly as documented. 3,377 lines of Python across the modules, and none of it is stub code.

Documentation matches the engineering standard. The SKILL.md (71-line body) is unusually disciplined: it opens with a lazy-load routing table, then an explicit rule that the orchestrator must not volunteer state it was not asked for, with a concrete example of how guessing a status board produced wrong table and column names. All 13 cross-references from the SKILL.md resolve to real files. Nine cookbooks and three references total 1,371 lines covering install, create/update ADW, config, prompting, handoff contracts, and observability. The README is 29 KB with seven custom SVG diagrams (swim lanes, control-plane contrast, envelope gates, trace paths). An example branch exists with a demo app the factory planned, built, tested, reviewed, and documented, plus the real traces from those runs.

Organic adoption is strong and fast. At review time the repo has 481 stars, 117 forks, and 14 watchers, created only five days earlier (2026-08-02). A 24 percent fork-to-star ratio with seven open issues is the signature of real usage, not passive stargazing. Seven issues on a five-day-old orchestration framework means people are installing and hitting edges, which is healthier than silence.

The Bad

v1 drives only the Pi coding agent, which is itself a niche runtime. The config schema accepts coding_agent: claude_code, but agents.validate() rejects it with "not implemented in v1 (pi only)", and agent_pi.py is the only real agent backend. Pi is the author's own coding-agent CLI (IndyDevDan). To run an ADW you need the pi binary on PATH plus provider API keys (the starter roster needs three: OpenRouter, Fireworks, OpenAI). For most readers this is a study-the-design skill rather than an install-and-run-today skill, because the runtime most of them already have (Claude Code, Codex, Cursor) is not wired up yet. The 117 forks suggest a meaningful cohort does run Pi, but it narrows the addressable audience sharply.

The repo ships no automated test suite of its own. For a framework whose entire value proposition is determinism, acceptance gates, and verifiable correctness, the absence of any tests/ directory is the most notable irony. Every claim I made above about the permission engine, the description validator, and the gate derivation I had to verify by writing my own checks. The code is high quality, but nothing in the repository runs those checks automatically, and nothing prevents a future edit from quietly breaking the invariants the design depends on.

There is no native Hermes or OpenClaw install path. The skill lives at .claude/skills/sssf/SKILL.md and uses Claude Code frontmatter (argument-hint). There is no .hermes/skills/ directory, no skills.sh or npx universal installer, and zero mentions of Hermes or OpenClaw anywhere in the source. A Hermes user can hand-copy or symlink the skill, but the /sssf install command and the .claude/ location are Claude Code specific. Given that this is the GearScope audience, the ecosystem fit is the weakest dimension.

The version and release story is missing. The repository has a single squashed commit on main, no git tags, no GitHub releases, no CHANGELOG, and no version field in the SKILL.md frontmatter. The SKILL.md itself documents a v1 scope and references a v2 (claude_code support), so the author thinks in versions, but none of that is visible to someone pinning or diffing. For a factory that emphasizes reproducibility, not being able to pin the factory itself is a gap.

Three runtimes are needed for the full experience. The ADWs run through uv run (which resolves pydantic, python-dotenv, pyyaml, rich via inline PEP 723 metadata), the recipes live in a justfile that needs just, and the visualizer needs bun. The raw uv run path works without just, and the SKILL.md says to observe via sqlite queries until the visualizer arrives, but the full documented experience assumes all three. None is exotic, but the install surface is wider than "one tool."

The SKILL.md contradicts itself on the visualizer. The v1 scope section says "The visualizer app ships in a later pass, observe via sqlite queries until then," but the visualizer is present in the repo (apps/visualizer/), the justfile has an obs recipe that boots it, and it typechecks clean. Either the caveat is stale or the app is half-wired, and a reader cannot tell which from the SKILL.md alone.

Smoke Test Results

Testing ran on the host (macOS 26.5.2, aarch64, uv 0.10.2, bun 1.3.x). The skill was cloned from GitHub and its Python internals were exercised through uv run with the declared inline dependencies. A live agent run was not possible because the Pi coding agent binary was not installed and no provider keys were set, so the smoke test covers install, config, the typed data layer, the permission engine, and the visualizer build rather than an end-to-end ADW execution.

Run A. Fresh clone, no deps preinstalled

$ git clone --depth 1 https://github.com/disler/super-simple-software-factory.git
PASS - cloned, 104 files (excl .git), 1.6 MB

$ python3 scripts/install.py (inside a fresh git repo)
PASS - stamped 44 file(s), added 5 .gitignore entries, exit 0

$ python3 scripts/install.py (second run, idempotency)
PASS - stamped 0, skipped 43 (already exist)

Pass rate: 3 of 3. The installer declares zero dependencies (stdlib only) and runs under any Python 3. It stamps the ADW scripts, modules, prompt templates, harness extensions, config, env sample, and justfile, then appends gitignore entries including a note that git add -A would otherwise commit bytecode.

Full fresh log →

Run B. Modules compile and config validates

$ find templates/adws scripts -name "*.py" | xargs python3 -m py_compile
PASS - ALL PY COMPILE OK (20 modules, 3,377 LOC)

$ uv run verify.py (14 functional checks via inline-dep resolution)
PASS - installed 11 packages (pydantic, pyyaml, rich, python-dotenv) in 53ms
PASS - 14/14 checks passed, exit 0

Pass rate: 2 of 2. This is the canonical install-correctness verdict. Every Python module compiles, the dependency resolver pulls exactly the four declared packages, and the typed internals behave as documented.

Full with-deps log →

Run C. Functional verification (does the design hold up?)

$ config loads + 5 agents parsed
PASS - planner, builder, scout, reviewer, documenter; defaults flow through

$ PhaseParams rejects name-echo description
PASS - PhaseParams(name="commit_plan", description="commit plan") raises

$ PhaseParams rejects blank description
PASS - blank/whitespace-only description raises at construction

$ _glob: * does not cross path sep
PASS - "adws/adw_*.py" matches adws/adw_simple_sdlc.py, rejects adws/adw_modules/runner.py

$ permitted(): protected blocked, writes unlocks
PASS - unrestricted agent blocked from protected_files; naming a path in writes unlocks it

$ permitted(): read-only agent (writes=[]) + runtime writable
PASS - repo path blocked, adws/adw_data/sessions path always allowed

$ agents.validate() fails fast on missing required agent
PASS - SystemExit naming the missing agent, before anything spawns

$ vue-tsc --noEmit (visualizer)
PASS - 53 packages installed, typecheck clean, exit 0

Functional pass rate: 8 of 8 spot checks, 14 of 14 total. The claims that matter most (typed envelopes, construction-time validators, the permission engine's path semantics, fail-fast config validation, the visualizer compiling) all hold. What could not be verified is a real agent run, because that needs Pi plus live provider keys.

Full functional log →

What the runs tell you

The runs say the framework's machinery is real and correct, not aspirational. The install is clean and idempotent, the typed layer and permission engine do exactly what the docs claim, and the visualizer builds. The one thing no host test can reach is the live agent loop, because v1 is Pi-only and the test environment had neither Pi nor provider keys. So the functional verdict is partial by necessity, not by laziness: everything that does not require a paid agent call is verified green, and the part that does is honestly flagged as untested here.

Setup Walkthrough

1. Get the skill into a repo. The simplest path is to copy .claude/skills/sssf/ from the cloned repository into your target repo, then type /sssf install inside Claude Code. The skill reads its own cookbooks/install.md and runs the installer.
2. Or run the installer directly: python3 scripts/install.py from the target repo root. It stamps 44 files (ADW scripts, modules, prompt templates, config, justfile, env sample) and is idempotent.
3. Install the Pi coding agent and put the pi binary on PATH (or set PI_PATH). This is the hard prerequisite the README does not foreground enough.
4. Copy .env.sample to .env and set the provider keys your roster needs. The starter roster names three providers (OpenRouter, Fireworks, OpenAI), but the env sample notes you can collapse to one by deleting per-agent model overrides.
5. Run a cheap read-only check first: uv run adws/adw_prompt.py "reply with a one-line summary of this repo" --agent scout. This proves the whole path (config validated, session minted, agent ran, envelope parsed, trace written) for a few cents.
6. (Optional) Install just for the recipe shortcuts (just demo, just sessions, just obs) and bun if you want the trace visualizer.

Post-install gotcha: the env sample warns that nothing validates your keys for you. agents.validate() checks that a model is written as provider/id, not that the provider is reachable, so a missing key surfaces when that agent runs, not at startup.

Alternatives

1. obyektif/planning-with-files or OthmanAdi/planning-with-files - file-based staged-execution skills that split a task into ordered steps with approval gates. Prefer SSSF when you want Python owning the loop with typed envelopes and after-the-fact permission enforcement rather than a markdown-and-prompt contract.
2. levi-qiao/octopus-skill - long-horizon orchestration as a markdown library with a single-writer ledger and a clean-context supervisor that re-verifies claimed work. Prefer SSSF when you want deterministic code phases (test, lint, build) as first-class pipeline steps rather than everything routed through agents.
3. Raw Claude Code or Codex subagents with your own harness - the default most teams start from. Prefer SSSF when the one-big-agent loop has started producing different output on repeated runs, or when you need provable write boundaries an agent cannot route around.