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

<!-- 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.

<!-- /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 and injects the state. When the checkpoint is missing and the repo config workflow.requireRetrospective (set via .devloops at repo root) is true, the resolver returns needs_reconcile. Complete or explicitly skip the retrospective before starting.

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.

Worktree fetch (mandatory): Always run git fetch origin before creating or reusing any worktree.

Resume from existing loop state

When the startup resolver returns a fresh-start routing but an existing outer-loop checkpoint (tmp/copilot-loop/<owner>/<repo>/pr-<n>/outer-loop-state.json) is present on disk, the dev-loop must check the checkpoint before treating the start as a fresh intake or follow-up:

1. Read the outer-loop checkpoint (authored by outer-loop.mjs).
2. If outerAction is continue_wait, reenter_copilot_loop, or reenter_reviewer_loop:
   • Skip issue-intake normalization or fresh-intake routing.
   • Route directly to the existing PR's follow-up path (the PR number is in the checkpoint's pr field). For reenter_copilot_loop, enter the copilot-pr-followup path. For reenter_reviewer_loop, enter the reviewer-loop path.
   • Use the checkpoint's copilotState and reviewerState as last-known context for re-attachment, then re-baseline with fresh detectors (copilot-pr-handoff.mjs or detect-copilot-loop-state.mjs) before acting on the state.
3. If outerAction is stop:
   • Report the reason field and the authoritative state from the checkpoint.
   • stop means the loop is blocked or needs a human decision; ask for direction rather than guessing or starting fresh.
4. If no checkpoint exists, or outerAction is done:
   • Treat as normal fresh startup (the existing startup resolver path).

This eliminates the manual "report-and-resume" or "exit and resume later" pattern when the deterministic state already knows the next action.

The outer-loop checkpoint is the canonical re-attachment artifact. Do not rely on chat context, local notes, or prose recollection of "where we left off."

Route table

Load only the route-specific internal skill required by selectedStrategy:

Strategy	Route pack to load
local_implementation	Local Implementation Skill
issue_intake	Copilot PR Follow-up Skill + Copilot Loop Operations + Issue Intake Procedure
copilot_pr_followup	Copilot PR Follow-up Skill + Copilot Loop Operations
external_pr_followup	same as copilot_pr_followup
reviewer_fixer	same as copilot_pr_followup
wait_watch	same as copilot_pr_followup
final_approval	same as copilot_pr_followup + Final Approval Skill

Do not preload route packs before the resolver selects the strategy.

Async dispatch

Async dispatch rule (enforced): the resolver fails closed for GitHub-first strategies when canonicalStateSummary.requiresAsyncDispatch is true (default required mode) — inline invocation without an async run-id marker (DEVLOOPS_RUN_ID or PI_SUBAGENT_RUN_ID) is rejected for those routes. Under the Claude Code harness this requirement is relaxed automatically. See Startup procedure.

Fallback gate-comment poster

When the @dev-loops/core package is not installed in the consumer repo, the full scripts/github/upsert-checkpoint-verdict.mjs helper (referenced from the copilot-pr-followup skill procedure) is unavailable. To keep the PR audit trail intact in that mode, the dev-loop skill ships a small gh-only fallback poster at scripts/post-gate-verdict-fallback.mjs (relative to the dev-loop skill root) that renders the same visible comment format and fails closed if posting cannot succeed.

Use the fallback poster only when the full helper cannot be reached:

1. Detect the missing helper: try node scripts/github/upsert-checkpoint-verdict.mjs --help from the consumer repo. If t

---

Content truncated.