dev-loops is a shared home for Pi-centered development workflow infrastructure.
The durable goal is to ship a reusable toolkit for Pi-based local and GitHub-first development loops without letting workflow mechanics drift back into ad hoc markdown or repo-specific shell glue.
Use PLAN.md for durable repo-level truth:
- product intent
- architecture direction
- workflow contract
- medium-term roadmap
Do not use PLAN.md for one-off issue execution plans, PR-specific checklists, or temporary implementation notes. Those belong in:
- GitHub issues / PRs
Phase Plan(docs/phases/phase-<n>.md) for active local-phase planningtmp/artifacts for transient execution detail
-
Supplemental residual-evidence reconciliation has three stages: unqualified assessment snapshots (#2918), accepted records (#2920), then thread closure (#2919). Only snapshots are available; parent #2917's acceptance criteria remain unchanged. See ADR 0180.
-
This repo is currently a source-loaded workspace, not a published npm-package workflow.
-
dev-loopis the single public workflow entrypoint; see Public Dev Loop Contract for the canonical public routing/shorthand contract. -
For active implementation and release work in this repo, the default routed path should still prefer the GitHub-first internal strategies when practical.
-
The local implementation strategy remains supported when the user explicitly wants local phase-bounded work.
-
GitHub issues are the backlog and GitHub PRs are the main execution trail for remote-loop work.
-
Installing the package with
pi install git:github.com/mfittko/dev-loopsexposes packaged skills throughpackage.jsonpi.skills;/dev-loops installand/dev-loops updateare removed — usepi install/pi updatedirectly.
This repo is meant to provide four durable layers.
Reusable role definitions under agents/ for work such as:
- coordination
- implementation
- docs
- review
- fixing
- quality
- refinement
These should stay broadly reusable and should not become thinly disguised repo-specific workflow scripts.
Thin workflow entrypoint agents are still allowed, but they must stay thin, defer sequencing and workflow policy to the skill, and avoid replacing the generic role agents.
Reusable Pi workflow skills under skills/, especially:
dev-loopas the single public façade for start/continue/state requests- split internal route packs behind
dev-loop:issue-intake,copilot-pr-followup,local-implementation, andfinal-approval
Skills own sequencing, handoff rules, and operator-facing workflow policy. The public entrypoint should expose user intent; internal strategy names should stay minimal and should not be preserved as compatibility shims without an explicit active contract.
Thin package-level UX under extension/ and cli/ for:
- readiness and diagnostics
- shell access to shared deterministic helpers
- lightweight orchestration glue that defers real mechanics to scripts/core modules
Deterministic helpers under packages/core/ and scripts/ for the mechanical parts of the workflows, including:
- review-thread parsing
- loop-state detection
- GitHub request/watch helpers
- issue/PR linkage
- phase-file support
- conductor-adjacent ownership, routing, inspection, and steering seams
Keep durable judgment and operator guidance in markdown, but move repeatable operational logic behind deterministic helpers whenever practical.
Prefer thin entrypoint agents, thin skills, thin CLI wrappers, and thin extension surfaces over duplicated logic in many places.
Prefer one concise canonical workflow/documentation surface over backwards-compatibility shims, legacy aliases, or duplicate prompt layers.
Do not preserve legacy names or compatibility seams by default. Keep them only when an explicitly approved active contract still requires them.
Shared pure logic should live in reusable package-friendly modules where practical, but the repository must remain runnable as a source-loaded checkout during the current phase of the project.
For GitHub/Copilot workflows, GitHub issues and PRs are the authoritative execution trail. Local docs should explain and support that flow, not replace it with a parallel backlog.
For new ideas that are not already anchored to an existing issue, keep the proposal-first intake posture used by the GitHub-first autopilot workflow: classify first, emit a proposal artifact, and mutate GitHub state only after the proposal is explicit and approved. The safety layer should fail closed through the bounded stop states stopped_overlap_needs_decision, stopped_low_confidence, stopped_explicit_reject.
Whenever a merged slice changes durable project truth, update the affected durable docs before considering the slice closed. In practice this usually means checking some combination of:
- README
PLAN.md- Implementation State
- Implementation Workflow
- relevant contract/state-graph docs under
docs/ - Scripts Documentation when a script surface changes
Today the repository already includes:
- reusable role agents
- packaged workflow skills for local and GitHub-first work
- a
/dev-loopsextension anddev-loopsshell CLI - deterministic GitHub helpers for review-thread capture, Copilot request/watch, issue-to-PR detection, and reviewer draft staging
- deterministic loop-state helpers for Copilot, reviewer, tracker, and outer-loop orchestration
- conductor-adjacent ownership, routing, inspection, and steering contracts in the source tree
- opt-in Codex conductor model/effort settings at initial and resumed coordinator dispatch; worker and reviewer settings remain outside this slice
- root and package-level tests plus CI on Node 24
The initial foundation phases are complete:
- Phase 1 — imported-asset normalization
- Phase 2 — dedicated refiner-agent support
- Phase 3 — extension/setup UX
- Phase 4 — shared deterministic library/package work
- Phase 5 — deterministic script surfaces
- Phase 6 — public release hardening
See Implementation State for the current execution snapshot.
Phase 8 is the current active durable phase. main already includes a partial Phase 8 implementation: the dev-loop config schema/loader, reviewer-role resolution, strategy-default routing integration, conductor model wiring, and the supporting contract tests.
The durable phase plan lives in Phase 8 Plan.
This ordering is an explicit deviation from the repo's normal one-phase-at-a-time posture: Phase 8 was pulled forward before the planned Phase 7 pilot executed. The durable docs now record that deviation directly instead of leaving contradictory claims about which phase is current.
Phase 7 is still a valid planned pilot, but it is currently deferred rather than completed. No target repository has been chosen yet and the bounded second-repo portability proof has not run.
Success for Phase 7 still means:
- one real non-bootstrap target repo
- one bounded non-mutating pilot path
- one thin downstream override example
- only the smallest portability fixes required for that pilot
Keep the durable plan parked at Phase 7 Plan until the repo is ready to resume that portability proof.
Once Phase 8 closes, either resume the deferred Phase 7 pilot or deliberately replan from current GitHub evidence instead of letting both phases stay half-active in durable docs. Likely follow-up areas still include:
- finishing any remaining Phase 8 closure work
- the downstream portability proof preserved in Phase 7
- further shrinkage of markdown-owned operational logic
- clearer operator-facing inspection / steering / projection surfaces
- broader multi-repo and tracker-first adoption only after the bounded pilot proves the basics
For the current stage of the repo, avoid expanding into:
- a generic workflow DSL
- support for every forge or every repo convention
- broad publish/distribution strategy work before the source-loaded boundary is proven well enough
- a parallel backlog system outside GitHub issues and PRs
- large issue-specific execution plans embedded in durable repo docs