dev-loops

Turn GitHub issues into merged PRs with zero manual steps between issue and approval.

What is a dev loop?

A dev loop is an AI-driven development cycle. It takes a GitHub issue through seven lifecycle phases — from intake to merge — with deterministic routing, self-correcting review gates, and autonomous execution until the human approval checkpoint.

Lifecycle phases:

| Phase | What happens | |---|---| | issue_intake | Normalize the issue, confirm scope, detect linked PRs | | refinement | Elaborate spec, run bounded audit, harden acceptance criteria | | implementation | Build the accepted scope on a feature branch or via Copilot | | draft_gate | Gate review at the draft→ready boundary before marking PR ready | | feedback_resolution | Fix, reply to, and resolve review threads on GitHub | | pre_approval_gate | Final gate review: verify evidence, CI, and unresolved threads | | merge | Merge the PR and write the retrospective checkpoint |

Each phase is consultable from the deterministic state model in packages/core/src/loop/lifecycle-state.mjs. The public routing contract is Public Dev Loop Contract.

Quick start

Use dev-loop as the single public workflow entrypoint:

• start dev loop on issue 112 — start work on an issue
• auto dev loop on issue 112 — autonomous execution until human approval
• continue dev loop on PR 88 — continue follow-up on an open PR

The dev-loop entrypoint resolves authoritative state, picks the correct internal strategy, and routes work deterministically. Users never need to choose internal strategy names. See the canonical shorthand example mapping in the Public Dev Loop Contract.

Install from npm

CLI only

npm install -g dev-loops        # global install
dev-loops --help                # verify

Or run directly without installing:

npx dev-loops --help

Pi extension

To use /dev-loops inside Pi:

pi install npm:dev-loops        # global Pi extension
dev-loops --help

You can also install from git:

pi install git:github.com/mfittko/dev-loops    # global
pi install -l git:github.com/mfittko/dev-loops # project-local

The CLI requires Node >=20 and a GitHub-authenticated gh CLI for repository workflows. See Requirements.

Docker

A deterministic container image with all required tooling for dev-loop operation.

Build

docker build -t dev-loops .

Environment variables

| Variable | Purpose | Required for smoke test | |---|---|---| | GH_TOKEN | GitHub personal access token for gh CLI and API calls | Yes | | OPENAI_API_KEY | LLM provider key (needed only when running pi / LLM-backed dev-loop operations) | No |

Smoke test

Verify the image works with a minimal dev-loop info call:

docker run --rm -e GH_TOKEN="$GH_TOKEN" dev-loops dev-loops loop info --repo mfittko/dev-loops --issue 1

Toolchain verification

Check that all required tools are reachable:

docker run --rm dev-loops node --version
docker run --rm dev-loops pi --version
docker run --rm dev-loops dev-loops --version
docker run --rm dev-loops gh --version
docker run --rm dev-loops git --version

Repeatable builds

The Dockerfile pins exact versions for Node.js (via base image), pi CLI, pi extensions, and gh CLI. Paired with the committed package-lock.json, repeat builds produce functionally identical toolchain versions.

Runtime patterns

Interactive Pi with host config (writable):

docker run -it --rm \
  -e GH_TOKEN="$GH_TOKEN" \
  -v "$HOME/.pi:/home/node/.pi" \
  dev-loops pi

Shares sessions, models, settings. Container writes session logs to host ~/.pi.

Interactive Pi clean (no config sharing):

docker run -it --rm \
  -e GH_TOKEN="$GH_TOKEN" \
  -e OPENAI_API_KEY="$OPENAI_API_KEY" \
  dev-loops pi

Ephemeral ~/.pi inside container. Provider auth via env vars.

Full dev-loop with live repo worktree:

git clone --mirror [email protected]:owner/repo.git /tmp/mirror
git --git-dir=/tmp/mirror worktree add /tmp/run /tmp/mirror/main

docker run -it --rm \
  -e GH_TOKEN="$GH_TOKEN" \
  -v "$HOME/.pi:/home/node/.pi" \
  -v /tmp/run:/workspace \
  dev-loops pi

Mounts live repo worktree over baked-in /workspace. One isolated Pi session per container.

Workflow posture

• Use dev-loop as the single public façade for all routed work
• Prefer the GitHub-first path for active implementation and release work
• Use local implementation only when explicitly requested
• Internal routed logic stays behind the public façade

This repo is shared Pi workflow infrastructure built on generic role agents plus thin workflow entrypoint agents where needed. Thin workflow entrypoint agents are allowed when they only load a skill and defer policy to it.

Phase 8 is the active durable phase; Phase 7 second-repo pilot is deferred. See Docs Index for the full execution snapshot.

Configuration

Gate review angles, refinement settings, persona mappings, and workflow defaults are config-driven via .pi/dev-loop/defaults.yaml. Consumer repos override values in .devloops at repo root (legacy .pi/dev-loop/settings.yaml still loads with a deprecation warning). The loader also accepts .yml and .json extensions and legacy overrides.* files as fallback formats. See Extension Documentation for details.

npx dev-loops gates   # see what reviewers will check

Key surfaces:

• Gate angles — which review lenses run at draft and pre-approval gates
• Persona prompts — focused instructions per angle (DRY, KISS, YAGNI, SRP, SoC, and more)
• Refinement — fan-out count and mode for parallel review variants
• Autonomy — which gates require operator confirmation
• Workflow defaults — retrospective enforcement, draft-first posture, dev-mode policy

Full details: Extension Documentation and .pi/dev-loop/defaults.yaml.

Package surface

The dev-loops package ships both a standalone CLI and a Pi extension. Consumer repos should prefer pinned Pi package installs; global npm installs are optional, not part of the Pi runtime contract.

Pi extension:

pi install npm:dev-loops@<version>                         # global, pinned npm package
pi install -l npm:dev-loops@<version>                      # project-local, pinned npm package
pi install git:github.com/mfittko/dev-loops@<tag-or-sha>   # global, pinned git ref
pi install -l git:github.com/mfittko/dev-loops@<tag-or-sha> # project-local, pinned git ref

Project-local installs write to .pi/settings.json; after the project is trusted, Pi auto-installs missing packages on startup. Install pi-subagents the same way when the repo depends on async loop behavior.

Inside Pi, use dev-loop as the single public skill/agent entrypoint:

subagent({
  agent: "dev-loop",
  task: "Start dev loop on issue 123 in owner/repo..."
})

Do not call internal routed skills such as local-implementation, copilot-pr-followup, or final-approval directly; dev-loop selects them from the current GitHub/repo state.

The /dev-loops command surface is for readiness and configuration UX:

/dev-loops status
/dev-loops doctor
/dev-loops gates

CLI:

npx dev-loops@<version> gates

Use npm install -g dev-loops only if you want the shell command available outside Pi.

The package exposes the /dev-loops extension command surface, the dev-loops shell CLI, and packaged skills from package.json pi.skills.

See Extension Documentation for the full command and package-install contract.

Requirements

• Node >=20
• gh installed and authenticated for GitHub/Copilot workflows
• pi-subagents for async workflow assumptions
• A Pi host that satisfies peer dependencies on @earendil-works/pi-coding-agent and @earendil-works/pi-tui

Development

npm run verify   # canonical root verification (tests + dev-loop tests)

CI splits into a small changed-files gate plus parallel verify and conditional viewer-smoke jobs. npm ci + npm run verify run on every change, while the workspace-local Playwright WebKit cache and viewer smoke run only when files in the bounded inspect-run viewer surface or its smoke-path dependencies change.

Further reading

• Docs Index — active docs, canonical-owner pointers, and current phase status
• Extension Documentation — README-driven extension spec
• Scripts Documentation — deterministic script contracts
• UI Smoke Harness — reusable local Playwright/WebKit smoke baseline
• UI Artifact Contract — screenshot/state artifact contract and CI-promotion rules
• UI Designer Review Loop — designer + vision (uiReviewMode: vision) review loop contract