kodawari

# kodawari

> kodawari turns a written spec into finished, tested code — autonomously, and it
> proves every step instead of just claiming it. You give it a markdown file
> describing a feature; it plans, writes the code, runs your tests, has a second
> AI model review the result, fixes what review flags, and stops at a ship/no-ship
> decision. A pipeline, not a chat.

What makes it different: three separate LLM roles (planner, reviewer, executor)
so no model grades its own work; a strict no-fake-run guarantee (under
`KODAWARI_REVIEW_ENABLED=1`, "tests passed" means pytest really ran and a second
model really approved — unverifiable steps fail closed); a contract-first audit
trail where every step is a JSON-schema-validated artifact; and cross-run memory
that learns recurring failure patterns and shares portable lessons across
projects via `~/.kodawari/instincts.json`. Greenfield is first-class (empty dir +
spec → scaffolded, tested feature); large specs split into resumable slices. It's
a headless, CI-friendly alternative to interactive AI pair-programmers like Claude
Code, Cursor, Aider, and OpenHands. Python 3.11+, MIT licensed, public beta
(v0.1.2).

## Start here

- [README](https://github.com/liafei/kodawari/blob/main/README.md): Project overview, quick start, and how it works
- [Quickstart](https://github.com/liafei/kodawari/blob/main/docs/QUICKSTART.md): First run from a fresh checkout
- [User Guide](https://github.com/liafei/kodawari/blob/main/docs/USER_GUIDE.md): Install, run a feature, read status, interpret failures
- [Writing a PRD](https://github.com/liafei/kodawari/blob/main/docs/WRITING_PRD.md): How to write a spec kodawari understands

## Understand the pipeline

- [Pipeline Deep Dive](https://github.com/liafei/kodawari/blob/main/docs/PIPELINE_DEEP_DIVE.md): Every stage and safety mechanism inside `work-all`, with code locations
- [Capability Map](https://github.com/liafei/kodawari/blob/main/docs/CAPABILITY_MAP.md): Which backend supports which feature

## Reference

- [Stability Policy](https://github.com/liafei/kodawari/blob/main/STABILITY.md): Public API surface, CLI tiers, artifact schema, deprecation policy
- [Environment Variables](https://github.com/liafei/kodawari/blob/main/docs/contracts/ENV_VAR_REFERENCE.md): Every env var, what it does, and its default
- [Operator Runbook](https://github.com/liafei/kodawari/blob/main/docs/OPERATOR_RUNBOOK.md): Error codes, troubleshooting, multi-slice diagnostics
- [Changelog](https://github.com/liafei/kodawari/blob/main/CHANGELOG.md): Release history

## Optional

- [Documentation index](https://github.com/liafei/kodawari/blob/main/docs/README.md): Full doc set, including 中文 docs
- [Example: hello-bookmark](https://github.com/liafei/kodawari/tree/main/examples/hello-bookmark): 5-minute end-to-end demo (empty dir to tested FastAPI service)
- [Contributing](https://github.com/liafei/kodawari/blob/main/CONTRIBUTING.md): Ground rules for pull requests