Agentic Dev

agentic-dev

A three-stage agentic pipeline that turns a checked-in `plan.md` into merged pull requests, so a Python project can go from 1–2 hand-written PRs/week to 10–20+ agent-produced PRs/week — with **human review as the only merge gate**.

plan.md ─▶ [1 slice] ─▶ GitHub issues ─▶ [2 write-tests] ─▶ failing-tests branch ─▶ [3 implement] ─▶ PR ─▶ human review ─▶ merge
             daily              ≤10/day                          ≤10/day
                                              [gc] daily: retire stale branches/PRs, unstick dead runs

Each stage runs an agent CLI — `claude` (Anthropic) or `grok` ([xai-org/grok-build](https://github.com/xai-org/grok-build)), selected with `AGENT_BACKEND` — inside a disposable Docker container, does one unit of work, and hands off through **issues** and **branches/PRs** — never shared local state. See [`agentic-dev-plan.md`](agentic-dev-plan.md) for the full design rationale, label state machine, rollout plan, and failure-mode analysis.

Repository layout

agentic-dev-plan.md            design doc (read this for the "why")
README.md                      this file
Dockerfile                     builds agentic-dev:{claude,grok}-latest
.dockerignore                  build context is an allowlist: agentic/ only
Makefile                       build / run / operate targets (`make help`)
examples/plan.md               sample plan.md the slicer consumes
agentic/
  entrypoint/                  run INSIDE the container, one unit of work each
    slice.sh                   Stage 1  — plan.md -> issues
    write-tests.sh             Stage 2  — issue -> failing tests   (env: ISSUE)
    implement.sh               Stage 3  — failing tests -> green -> PR (env: ISSUE)
    gc.sh                      housekeeping
  lib/
    common.sh                  shared bash helpers: phases, the exit trap,
                               budget_guard, run_agent, the heartbeat
    stream_filter.py           summarises the agent's NDJSO