dev-loop

No-implicit-start rule: Never start implementation without explicit instruction.

Work-origin rule: All work must originate from a tracked artifact: a GitHub issue (tracker-first), a persisted markdown plan file (local-planning), or — on the sanctioned lightweight path — the PR description itself as the spec-of-record (--lightweight, canonicalSpecSource: pr_body; no committed plan artifact; issue-less PR-first is size-gated by the light-mode threshold unless localImplementation.issueless sanctions it at any change scope). See Artifact Authority Contract for canonical mode definitions and settings. No work may originate from a PR (other than the sanctioned lightweight PR-body-as-spec path) or a direct local change unless explicitly requested.

Unified Dev Loop

This is the public dev-loop façade — a summary of the authoritative routing contract. The authoritative contract is Public Dev Loop Contract. Runtime evaluator: @dev-loops/core/loop/public-dev-loop-routing. For status/progress/readiness/merge-state/next-step queries, resolve authoritative artifact identity first; for issue targets, identity resolution is handled by the startup resolver. Fail closed to reconcile/unknown when unresolved. When an open linked PR exists, treat it as the single canonical artifact for the issue and reuse it instead of opening another PR.

Installed skill layout

Required installed runtime contract docs are shared bundled copies under ../docs/ from this skill directory. Read those bundled ../docs/ files from the installed skill layout — do not assume a source checkout. If a required bundled contract doc is missing, treat it as a packaging/installer bug.

Startup procedure

Review intent short-circuit (issue #1850): A plain review request against a PR ("review PR #N", "review this PR") is NOT a continue/fix/merge request. Recognize review intent BEFORE resolving authoritative state below, and dispatch straight to the standalone Review Skill (/dev-loops:loop-review <pr>, or /loop-review <pr> in the dev-loops repo itself) — never run loop startup/resolve-dev-loop-startup.mjs for this route. The review route is read-only (no branch push, no fix commit, no merge, no board move, no assignee claim) and ownership-exempt by construction: it is not one of the routing evaluator's strategies, so STRATEGY_OWNERSHIP_GATE never applies to it and it runs on a PR owned by anyone, or by no one — see Single-contributor ownership gate. Any other request (continue the loop, fix findings, merge, watch) proceeds through the ordinary startup procedure below, which still enforces the ownership gate exactly as before.

"Run the gates" is NOT review intent (issue #1913): review is a GATE_NAME but it gates nothing (informational, blocks no transition — see the tier comment in scripts/github/_gate-names.mjs: LIFECYCLE_GATES vs REVIEW_GATE). So a request phrased around gating — "run this PR through the gates", "gate this PR", "gate PR #N" — with NO explicit "review" word MUST NOT match the review short-circuit above. The discriminator is the same one question the vocabulary encodes: does it block a lifecycle transition? "Run the gates" means the lifecycle gates (draft_gate, pre_approval_gate), which run inside the ordinary loop via the startup flow below — NOT the standalone review command. Route these requests through loop startup/resolve-dev-loop-startup.mjs like any other continue request; do not dispatch /loop-review.

<!-- pi-only -->

Main agent (read-only)

The main agent must always dispatch the dev-loop async subagent for any dev-loop work. Do not run dev-loops loop startup or any startup resolver in the main agent. For async-required routes (config workflow.asyncStartMode, default required) the resolver needs an async run-id marker: the Pi runtime injects PI_SUBAGENT_RUN_ID into each async subagent's child env, or the main agent mints and propagates the neutral DEVLOOPS_RUN_ID before dispatch; under the Claude Code harness the requirement is relaxed automatically (no marker needed). The startup resolver also runs without a marker for non-async routes. Regardless, only the dev-loop subagent runs it — never the main agent.

After dispatching the async subagent in an interactive session, return control to the user — do NOT call subagent_wait to block on completion. Pi wakes the session on completion or needs-attention. The only exception is run-to-completion (the user explicitly asked for results reported back before continuing, or a skill must finish in one turn). Calling subagent_wait merely to wait freezes the interactive session for the full run duration and defeats async dispatch; the Pi platform default already says return control. This reinforces that default for the dev-loop dispatch pattern specifically. See Async dispatch posture in the Main Agent Contract.

<!-- /pi-only -->

Resolve authoritative state

Under the Claude Code harness the dev-loop runs as a single agent: run these steps directly — no read-only boundary and no separate async-subagent dispatch. See Main Agent Contract.

<!-- pi-only -->

CLI invocation (<dev-loops-package-root>): dev-loop CLI commands below are invoked as node <dev-loops-package-root>/cli/index.mjs <verb...> using the package-local CLI rather than npx, so they resolve unambiguously from the installed package without a global install. Resolve <dev-loops-package-root> via the first of these bounded candidates whose cli/index.mjs exists — never assume a single fixed layout (under a Pi user-level install the package lives at ~/.pi/agent/npm/node_modules/dev-loops/, so the old ../../.. package-relative guess from skills/dev-loop/SKILL.md overshoots the package root):

1. Node module resolution (best-effort first try): node -e "try{const p=require('node:path');console.log(p.resolve(p.dirname(require.resolve('dev-loops/cli/index.mjs')),'..'))}catch{process.exit(1)}" — resolves the package root when dev-loops is reachable from Node's module search path (notably under ~/.pi/agent/npm); this is cwd-dependent and commonly misses from a target-repo cwd, so the probe is wrapped in try/catch (no stack trace, exits non-zero on miss) — treat a non-zero exit as "probe missed, try the next candidate", not a hard failure.
2. Pi user-agent npm root (reliable for user-level installs): ~/.pi/agent/npm/node_modules/dev-loops.
3. Package-relative (legacy): ../../.. from this skill's own directory (the original package-local install layout).
4. Global npm root: $(npm root -g)/dev-loops.

NEVER fall back to find / or any unbounded filesystem walk to locate the CLI — it stalls and trips the needs-attention timeout. If every bounded candidate fails, stop and ask the orchestrator/operator for the dev-loops package root rather than searching. (The dev-loop agent resolves it analogously.)

<!-- /pi-only -->

Resolve authoritative state via the startup resolver (node <dev-loops-package-root>/cli/index.mjs loop startup --issue <n> for issues, node <dev-loops-package-root>/cli/index.mjs loop startup --pr <n> for PRs), then immediately build the handoff envelope via node <dev-loops-package-root>/cli/index.mjs loop build-envelope --input <resolver-output.json>. The envelope determines requiredReads, nextAction, stopRules, and acceptance — load only those files, execute only that bounded task. It is the first handoff artifact consumed before loading any route pack. See Workflow Handoff Contract for the derivation contract.

Retrospective checkpoint gate: the resolver reads .pi/dev-loop-retrospective-checkpoint.json (resolved from the repo's main checkout, not cwd-relative, so a worktree and the main checkout always see the same file) and, when the repo config workflow.requireRetrospective (set via .devloops at repo root) is true, bounds newer base-branch commits with local git ancestry and classifies each through GitHub's commit-to-PR association. A complete/skipped record becomes missing only when a newer commit is associated with a PR merged into the configured base branch; direct/release commits, unmerged PRs, and PRs merged into another base do not open a cycle. An unresolvable recorded SHA or unverifiable association fails closed to missing. When the resulting state is missing, the resolver returns needs_reconcile; loop build-envelope represents that terminal reconciliation with selectedStrategy: null and an actionable stop envelope. Complete or explicitly skip the retrospective before starting, carrying the cycle identity via checkpoint-contract.mjs --repo/--pr/--merge-commit (required for complete/skipped) and — for complete — the fresh-context provenance via --retro-context fresh --record-source <path> (mandatory per RETRO-FRESH-CONTEXT-MANDATORY; an inline self-authored retro fails the checkpoint).

Pre-flight PR gate (mandatory): Before working an existing PR, the dev-loop must run node <dev-loops-package-root>/cli/index.mjs loop handoff --repo <owner/name> --pr <number> and abort if action: "stop". When terminal: true, proceed inline. When terminal: false, resolve the blocking condition first.

Worktree cwd (mandatory): Always use a worktree checkout for git operations, file reads/writes, and validation commands — never use the main checkout.

A shell's working directory can reset to the primary checkout silently — after a subprocess run, or when a cd inside a compound command does not persist into the next one. A relative-path git add && git commit && git push

---

Content truncated.