Home

kstrl

kstrl (CLI: ks) is an adversarial coding-agent factory: a harness that takes a product spec, decomposes it into components, builds each component with AI coding agents in isolated git worktrees, subjects every diff to an adversarial review gauntlet, and ships the result as merged GitHub pull requests - designed to run unattended, with every decision recorded.

The factory's core bet: adversarial framing catches bugs that eager-to-please framing misses, and calibration - not self-report - is the only truth signal for whether an AI reviewer is actually working.

spec.md -> architect red-team -> component DAG -> per component:
  feedforward -> engineer -> mechanical verify -> 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).
• ~1,400 tests; strict mypy; ruff.
• Current work: the R8 Dark Factory cycle (milestone, tracking issue #156) - taking the factory from "stops at merged PR" to a governed autonomous factory with continuous intake, a release stage, runtime feedback, and earned autonomy.

How this wiki is organized

Page	What it answers
Vision and Philosophy	Why kstrl exists, the dark-factory frame, the doctrine, and what we deliberately refuse to automate
Architecture Overview	What runs, in what order, where state lives - the orientation layer over the canonical repo docs
Roadmap	The three roadmap cycles (adversarial hardening, A+ remediation, R8 dark factory), 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

Canonical sources

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

• README - product-level overview and quick start
• ARCHITECTURE.md - the low-level tour
• 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