Lopy

Lopy is a lightweight kit for using AI coding agents as bounded task, ticket, and code review loops.

Lopy is based on the loop engineering concept: instead of giving one AI agent a large open-ended job, you define small repeatable loops with clear inputs, boundaries, budgets, validation rules, and handoff states. Each loop does one kind of work, stops at a known exit condition, and passes the result to the next loop or to a human.

Instead of asking one agent to do everything, you give each agent a small job:

• Implement the task or ticket.
• Review the pull request or merge request.
• Fix review comments, test failures, merge conflicts, and coverage gaps.
• Hand off to a human when the code review is clean enough.

The goal is simple: make Claude Code, Codex, Cursor, Aider, OpenHands, and other agents more useful, safer, and cheaper to run.

Why This Exists

AI coding agents can waste tokens when they explore too much, refactor outside the task, reread unchanged code, or keep working after the useful stopping point.

Lopy solves that by giving every loop:

• A narrow mission.
• Clear inputs.
• Allowed and forbidden actions.
• Token and tool budgets.
• Validation requirements.
• Stop conditions.
• Task statuses, review states, and labels for handoff.
• Coordination records that prevent duplicate parallel work.

The Three Loops

1. Implementer Loop

Takes one approved task or ticket, researches only the relevant context, writes a short plan, makes the smallest useful change, adds or updates tests, runs validation, and opens a pull request or merge request.

2. Reviewer Loop

Reviews one pull request or merge request for correctness, missing tests, coverage gaps, security risks, stale branches, merge conflicts, CI failures, and scope creep. It leaves actionable comments or marks the review ready for human review.

3. Fixer Loop

Resolves review comments, failing checks, coverage errors, merge conflicts, and stale branch problems on an existing pull request or merge request. It does not expand the feature.

Quick Start

Clone this repo:

git clone https://github.com/your-name/lopy.git

Copy the small runtime kit into your project:

cp -r lopy/templates/basic/.lopy .

On Windows PowerShell:

Copy-Item -Recurse lopy\templates\basic\.lopy .

Customize:

.lopy/project-contract.md
.lopy/task-sources.yml
.lopy/coordination.yml

Then call a loop from your AI coding tool:

Use .lopy/loops/implementer.md.
Target task: github issue #42.
Follow .lopy/project-contract.md.
Do only the requested task.
Stop when the PR or MR is opened, blocked, or ready for human review.

Calling Loops

Use one loop at a time:

Run Implementer Loop on jira ticket APP-123.

Run Reviewer Loop on PR #55.

Run Fixer Loop on PR #55. Resolve unresolved review comments only.

See docs/calling-loops.md.

Task Sources

Lopy works on tasks, not only GitHub issues. A task can come from:

GitHub Issues
GitLab Issues
Jira
Linear
ClickUp
Asana
Trello
Azure DevOps Boards
Notion
Monday.com
Shortcut
YouTrack

Each source should be normalized into the same task shape: title, description, acceptance criteria, status, priority, links, attachments, allowed scope, forbidden scope, and definition of done.

See docs/task-sources.md.

Parallel Work

Lopy can support parallel agents, but only when work is claimed, isolated, and reducible.

The core rule is:

Parallel reads are cheap. Parallel writes need claims, path locks, separate branches or worktrees, and a reducer.

Agents should claim a task before researching deeply, lock paths before editing, check recent findings before repeating searches, and publish a small run record when they stop.

See docs/coordination-graph.md.

Preflight And Fallbacks

Each loop should run a short preflight before deep research or edits.

Preflight:
- Target readable
- Branch and working tree checked
- Coordination records checked
- Required CLIs and tokens checked
- CI or local validation path known

If automation is unavailable, Lopy should use a safe manual fallback: push the branch when allowed, save ready-to-paste PR/MR or review text under .lopy/handoffs/, and give the human one clear next action.

See docs/preflight.md and docs/manual-fallbacks.md.

Documentation

• docs/calling-loops.md — how to call each loop.
• docs/task-sources.md — normalized task shape and status mapping.
• docs/coordination-graph.md - parallel work, claims, path locks, and run records.
• docs/preflight.md - setup checks before loop work begins.
• docs/manual-fallbacks.md - safe behavior when CLIs, tokens, or CI are unavailable.
• docs/state-machine.md — states, claiming, handoffs, and stop rules.
• docs/loop-boundaries.md — scope locks and escalation.
• docs/token-budgeting.md — budget levels and anti-waste rules.
• docs/validation-contract.md — validation, coverage, flaky tests, branch updates.
• docs/security-rules.md — sensitive files, untrusted content, prompt injection.
• docs/github-labels.md — the GitHub label protocol.

Repository Layout

docs/                         Full explanation of the workflow.
loops/                        Canonical loop prompts.
templates/basic/.lopy/
                              Small kit users copy into their projects.
templates/basic/.lopy/calls/  Fill-in prompts for calling loops.
templates/basic/.lopy/handoffs/
                              Ready-to-paste manual fallback text.
examples/                     Example workflows.
adapters/                     Tool-specific calling notes.
.github/                      Labels and templates for this repo.

Core Principle

The agent should do the smallest scoped task that advances the current task, ticket, pull request, or merge request state.

It must stop when:

• The exit condition is met.
• Validation passes and the handoff is complete.
• Scope would expand beyond the task, ticket, PR, or MR.
• A human decision is required.
• The token or tool budget is reached.

Status

This repo is documentation-first. It does not require a package manager, a hosted service, or a specific AI vendor.

Automation can be added later, but the first version works anywhere you can paste instructions into an AI coding agent.