Home

kstrl

kstrl (CLI: ks) is a software factory for AI coding agents. It takes a product spec, red-teams it, decomposes it into components, builds each component with a coding agent in an isolated git worktree, measures every result with checks the agent did not write, feeds the gap back as the next instruction, and ships merged pull requests. It is designed to run unattended, to stop loudly at any bound it reaches, and to record every decision it makes.

The design rests on one rule: nothing the agent says about its own work is the final word. The story flag it sets is a claim; the reviewer's verdict on each acceptance criterion is the measurement. The reviewer's own claim to have searched thoroughly is a hint; calibration against planted bugs is the only proof it works. A green test suite is not enough on its own; the gate also reads whether the tests could have failed.

spec.md -> architect red-team -> component DAG -> per component:
  computed context -> engineer -> mechanical checks -> reviewer -> security
  -> knowledge distiller -> (optional human checkpoint) -> PR merge
-> cross-component contract tests -> evolution journal

Status

• Language: Python 3.11+, uv toolchain. License: MIT.
• Install: uv tool install kstrl (installs ks and kstrl).
• About 3,200 tests; strict mypy; ruff.
• The system map is generated from the code and published at https://0xfauzi.github.io/kstrl/atlas/; a CI job fails any pull request that leaves it stale.
• Current cycles, each with its own tracker and milestone:
  • R8 Dark Factory (milestone 1, #156): from "stops at merged PR" to a governed factory with continuous intake, a release stage, runtime feedback and earned autonomy. Governance, intake and the trust-boundary hardening have shipped; the release stage and runtime feedback are open.
  • R9 Continuous learning (milestone 2, #217): replace the template proposal generator with routed learning that is attributed and can retire itself, shared across every project the operator runs.
  • R10 Control loop (milestone 3, #235): make every check runnable by hand, take the "done" flag away from the agent's sole authority, discharge the retry context, bound work in flight, and give the operator's review comments a path into the next run. The Roadmap page explains the ID scheme.

How this wiki is organized

Page	What it answers
Vision and Philosophy	Why kstrl exists, the loop it is built as, what it refuses to trust, and what it deliberately keeps a human for
Architecture Overview	What runs, in what order, at what rate, and where state lives: the orientation layer over the canonical repo docs
Roadmap	The roadmap cycles, how roadmaps are governed, and where work stands
Getting Started	Install, scaffold a project, run the loop and the factory, watch it work
Contributing	The process rules (H1-H4), prompt-versioning and calibration discipline, coding standards, how to pick up work
Glossary	The project's vocabulary, from architect to worktree
Lessons	What each merged change taught, as pages you can operate

Canonical sources

The wiki orients; the repo governs. When the wiki and the repo disagree, the repo is right:

• The live system atlas - generated from the code: every component, what flows between them, what is built and what is planned, in switchable layers; click a component to see what it is to its neighbours
• README - product-level overview and quick start
• ARCHITECTURE.md - the low-level tour
• docs/control-loop-design.md - the loop as designed: what closes today, what each cycle closes next
• PRODUCT.md / DESIGN.md - product principles and the TUI visual system
• docs/adversarial-design.md - the 8-role taxonomy, invariants, known limitations
• docs/ - roadmaps, runbook, calibration notes, integration docs