dev-loops 0.2.3 → 0.2.5

package/.claude/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "dev-loops",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "description": "Agent-harness-agnostic dev-loop: agents, skills, and hooks for GitHub/Copilot-driven development loops.",
   "author": {
     "name": "Manuel Fittko",

package/.claude/skills/copilot-pr-followup/SKILL.md

@@ -53,7 +53,11 @@ Use this helper output as source of truth for the normal routing seam. Interpret
 ```sh
 node <resolved-skill-scripts>/loop/run-watch-cycle.mjs --repo <owner/name> --pr <number>
 ```
-Persistent async watch/fix loop, not handoff-only behavior: `watch → detect → if threads found, fix + reply + resolve → re-request → watch again → … → pre_approval_gate → merge`. **PERSISTENCE MODEL: Subagents do bounded implementation tasks and exit on external wait. The main session drives the loop and re-dispatches when continuation is feasible.** A single returned watch cycle is never completion by itself. If `cycleDisposition` is `pending` and `terminal` is `false`, the subagent exits on the wait boundary; the main session re-dispatches another watch boundary. Max watch timeout: **30 minutes** (from `policy-constants.mjs` COPILOT_REVIEW_WAIT_TIMEOUT_MS); expired budget + still `waiting_for_copilot_review` = hard stop. If the user explicitly asks for async handoff-only behavior, say that out loud and stop after the handoff boundary.
+Persistent async watch/fix loop, not handoff-only behavior: `watch → detect → if threads found, fix + reply + resolve → re-request → watch again → … → pre_approval_gate → merge`. A single returned watch cycle is never completion by itself.
+
+> Under the Claude Code harness, run this loop **inline in a single agent**: the helper-owned wait tools (`dev-loops loop watch-cycle`, `gh run watch`, `dev-loops gate probe-copilot`) block inline and return — when `cycleDisposition` is `pending` and `terminal` is `false`, run the next watch cycle yourself. Do not exit on the wait boundary to have a parent re-dispatch the loop; keep driving it in this agent until a terminal state or the watch budget expires. (Delegating a bounded fix to the `fixer` agent, per Step 6, is still fine — that is task delegation, not re-dispatching the watch loop.)
+
+Max watch timeout: **30 minutes** (from `policy-constants.mjs` COPILOT_REVIEW_WAIT_TIMEOUT_MS); expired budget + still `waiting_for_copilot_review` = hard stop. If the user explicitly asks for async handoff-only behavior, say that out loud and stop after the handoff boundary.
 
 **4. Low-level helpers**
 ```sh
@@ -133,8 +137,8 @@ already has an outer-loop checkpoint, check whether the checkpoint implies an au
    (including `timestamp` and potentially incrementing `waitCycles`).
    Read the on-disk artifact without mutating it.
 2. If `outerAction` is `continue_wait`:
-   - The loop was waiting. The subagent exits; the main session re-dispatches a fresh
-     `dev-loop` async subagent that resumes from the checkpoint.
+   - The loop was waiting; resume it from the checkpoint.
+     Under the Claude Code harness, continue the wait inline (run the next watch cycle yourself).
 3. If `outerAction` is `reenter_copilot_loop`:
    - The copilot inner loop needs action. Run `copilot-pr-handoff.mjs` to determine the
      exact next step and proceed.
@@ -145,8 +149,8 @@ already has an outer-loop checkpoint, check whether the checkpoint implies an au
 6. If no checkpoint exists or `outerAction` is `done`:
    - Continue with normal step sequencing.
 
-Do not skip this guard when transitioning between async subagent runs on the same PR.
-The outer-loop checkpoint is the canonical re-attachment artifact for the subagent.
+Do not skip this guard when resuming work on the same PR.
+The outer-loop checkpoint is the canonical re-attachment artifact.
 
 ## Step 6: Async watch behavior
 
@@ -162,8 +166,7 @@ Preferred approach:
 - `timeout`/`idle` → re-run `copilot-pr-handoff.mjs --watch-status <status>` once to refresh state; if still `waiting_for_copilot_review` after 30-minute watch budget exhausted, hard stop with `watch timeout — PR #<number> needs manual attention`
 - zero-timeout `idle` probes are for explicit one-shot status/reattach checks only; they are not the normal async wait mechanism
 - after a successful fix / reply-resolve / re-request cycle, returning to `waiting_for_copilot_review` is a persistence boundary: resume the watcher instead of reporting completion
-- if a child async run exits and the refreshed state remains non-terminal (for example `waiting_for_copilot_review`) before merge and without a hard stop, treat that as early exit and the main session re-dispatches the same-PR follow-up path when feasible (the subagent exits on external wait)
-- dispatch fix findings to `fixer` subagent; do not run inline fix passes in-watcher
+- dispatch fix findings to the `fixer` agent; do not run inline fix passes in-watcher
 - do not report completion while unresolved Copilot feedback remains
 
 ### Canonical async dispatch wording
@@ -177,8 +180,8 @@ Key rules:
 - agent-authored shell polling is forbidden: do not use `nohup`, detached shell jobs, `tmux`, `screen`, or ad hoc `for i in $(seq ...)`, `while true`, `until ...; do sleep ...; done`, or `sleep`-retry bash loops
 - do not wrap repeated `gh pr view`, `gh pr checks`, `gh api`, or `detect-copilot-loop-state.mjs` calls inside shell polling loops
 - do not bypass session-based async notifications with detached shell automation
-- if Pi async subagents or the designated async follow-up skill are not appropriate or available, stop and report rather than improvising a shell watcher
-- the async-start contract is enforced in code: `outer-loop.mjs` fails closed without a visible Pi-managed async run id when `workflow.asyncStartMode: required`
+- if the designated async follow-up skill is not appropriate or available, stop and report rather than improvising a shell watcher
+- the async-start contract is enforced in code: `outer-loop.mjs` fails closed without a visible async run id when `workflow.asyncStartMode: required` (relaxed automatically under the Claude Code harness — see #830)
 
 ### Async delegation guard rules (#524)
 

package/.claude/skills/dev-loop/SKILL.md

@@ -21,29 +21,25 @@ Required installed runtime contract docs are shared bundled copies under `../doc
 
 ## Startup procedure
 
-### Main agent (read-only)
+### Resolve authoritative state
 
-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 (`DEVLOOPS_RUN_ID`, or the `PI_SUBAGENT_RUN_ID` alias) that the Pi harness injects when it dispatches the async subagent; 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.
+> 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](../docs/main-agent-contract.md).
 
-### Dev-loop subagent (post-dispatch)
-
-The subagent resolves authoritative state via the startup resolver (`npx dev-loops loop startup --issue <n>` for issues, `npx dev-loops loop startup --pr <n>` for PRs), then immediately builds the handoff envelope via `npx dev-loops 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](../docs/workflow-handoff-contract.md) for the derivation contract.
+Resolve authoritative state via the startup resolver (`npx dev-loops loop startup --issue <n>` for issues, `npx dev-loops loop startup --pr <n>` for PRs), then immediately build the handoff envelope via `npx dev-loops 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](../docs/workflow-handoff-contract.md) 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-delegation gate (mandatory — subagent only):** Before delegating async work targeting an existing PR, the dev-loop subagent must run `node scripts/loop/copilot-pr-handoff.mjs --repo <owner/name> --pr <number>` and abort if `action: "stop"`. When `terminal: true`, proceed inline. When `terminal: false`, resolve the blocking condition first.
+**Pre-flight PR gate (mandatory):** Before working an existing PR, the dev-loop must run `node scripts/loop/copilot-pr-handoff.mjs --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 — subagent only):** Always use a worktree checkout for git operations, file reads/writes, and validation commands — never use the `main` checkout.
+**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 — subagent only):** Always run `git fetch origin` before creating or reusing any worktree.
+**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
-subagent must check the checkpoint before treating the start as a fresh intake or follow-up:
+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`:
@@ -87,7 +83,6 @@ Do not preload route packs before the resolver selects the strategy.
 
 **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 the `PI_SUBAGENT_RUN_ID` alias) is rejected for those routes. Under the Claude Code harness this requirement is relaxed automatically. See [Startup procedure](#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.
@@ -104,14 +99,14 @@ When `@dev-loops/core` is available again, switch back to the full helper. The f
 
 ## Read-only info shortcut
 
-The main agent may handle info/handoff requests directly via `npx dev-loops loop info` without dispatching the async `dev-loop` subagent:
+Info/handoff requests can be served directly via `npx dev-loops loop info` (read-only; no full dev-loop run required):
 - `npx dev-loops loop info --issue <n>` — human-readable issue state summary (strategy, route, linked PR, next action)
 - `npx dev-loops loop info --pr <n>` — human-readable PR state summary (branch, CI, threads, rounds, action)
 - `npx dev-loops loop info --issue <n> --json` — machine-readable JSON output
 
-## Guard rules (subagent reference)
+## Guard rules
 
-**Handoff envelope precedence:** The subagent builds the envelope immediately after authoritative-state resolution and treats it as the first handoff artifact. Read it first, load only `requiredReads`, execute `nextAction`. See [Dev-loop subagent](#dev-loop-subagent-post-dispatch). Derivation contract: [Workflow Handoff Contract](../docs/workflow-handoff-contract.md).
+**Handoff envelope precedence:** The dev-loop builds the envelope immediately after authoritative-state resolution and treats it as the first handoff artifact. Read it first, load only `requiredReads`, execute `nextAction`. See [Resolve authoritative state](#resolve-authoritative-state). Derivation contract: [Workflow Handoff Contract](../docs/workflow-handoff-contract.md).
 
 **Handoff contract rule:** When no envelope is present, use the `workflow-handoff-contract.md` contract. Never delegate with abbreviated task summaries. Include deterministic routing inputs, explicit `cwd`, bounded task scope, exit conditions.
 
@@ -134,7 +129,7 @@ All PRs must pass the full gate pipeline before merge. No scope is exempt: docs-
 ## Authority boundary
 
 - Source code, tests, config, CI, and shared contract docs are authoritative.
-- Main-agent delegation contract: [Main Agent Contract](../docs/main-agent-contract.md) — absolute read-only boundary; all mutations flow through `dev-loop` async subagent.
+- Main-agent delegation contract: [Main Agent Contract](../docs/main-agent-contract.md) — how dev-loop work is structured per harness (Pi: read-only main agent + async-subagent dispatch; Claude: a single agent runs the steps directly).
 - Before any state-changing action, get explicit confirmation unless already authorized.
 - A question requires an answer, not an action.
 - Stop and ask rather than guessing when facts don't agree.

package/.claude/skills/docs/main-agent-contract.md

@@ -1,85 +1,13 @@
 # Main-agent delegation contract
 
-> **Absolute read-only boundary.** The main agent must never mutate files tracked by the repository.
-> All mutations flow through the `dev-loop` async subagent.
+How dev-loop work is structured depends on the harness.
 
-## Contract
+**Under the Claude Code harness, the dev-loop runs as a single agent.** The agent invoked for
+dev-loop work performs the steps directly — it reads and writes repository files, runs git and PR
+lifecycle operations, runs the `dev-loops` CLI (including state-changing `gate` / `pr` / `loop`
+subcommands), and posts gate verdicts under the operating session's identity. There is no separate
+read-only "main agent" and no mandatory async-subagent dispatch: the dev-loop agent owns the work
+end to end. The draft-gate `gh pr ready` guard still applies (harness-agnostic). A read-only
+boundary can be re-imposed optionally via the Write/Edit guard hook — opt-in with
+`DEVLOOPS_MAIN_AGENT_READONLY=1` (default fail-open) — for repos that want it.
 
-The main agent is **read-only** for every file tracked by the repository. Every
-write, edit, delete, commit, branch, push, and PR lifecycle operation must flow
-through the `dev-loop` async subagent.
-
-This contract is a hard rule, not a default or guideline. The main agent must
-never rationalize a direct mutation — not because the work is small, not
-because "the user said yes," not because it is running from a worktree.
-
-## Main agent owns (allowed)
-
-- Read, inspect, search any repo file
-- `git worktree list`, `git status`, `git log` (read-only git). `git fetch` is also allowed (updates local refs but does not touch tracked working-tree files).
-- `gh issue view / create / edit / comment / close` (GitHub API, not file mutations)
-- `gh pr view / list` (read-only GitHub API)
-- Write to `/tmp` or other non-repo paths (e.g., issue body drafts)
-- Delegate to the `dev-loop` agent (async, with worktree cwd)
-- Report findings, ask questions, get confirmation
-- `npm test`, `npm run verify` (read-only validation)
-
-## Main agent must NEVER
-
-- `write`, `edit`, or delete any file tracked by the repo
-- `git commit`, `git push`, create branches, create worktrees
-- Run state-changing dev-loops CLI subcommands (`gate`, any state-changing `loop` subcommand, `pr` commands — those belong inside `dev-loop`).
-- Delegate implementation to any agent other than `dev-loop`
-
-## Dev-loop agent (async) owns
-
-- ALL file mutations in the repo (write, edit, delete)
-- ALL git operations (branch, commit, push)
-- ALL PR lifecycle (create, draft, review, merge)
-- Sub-delegation to developer, fixer, review, quality agents
-
-## Boundary examples
-
-| Operation | Verdict |
-|---|---|
-| `gh issue create --title "..." --body "..."` | Allowed — mutates GitHub, not files tracked by the repository |
-| Write to `/tmp/issue-body.md` | Allowed — outside the repo |
-| Write to `packages/core/src/foo.mjs` | **BREACH** — must delegate to `dev-loop` |
-| `git status` | Allowed — read-only |
-| `git commit -m "..."` | **BREACH** — must delegate to `dev-loop` |
-| `subagent dev-loop` | Allowed — correct delegation |
-| `subagent fixer` | Allowed only when called from within `dev-loop`; describe the task as part of the message |
-
-## Dev-loop startup
-
-When a user triggers the dev loop, the main agent must immediately dispatch the
-`dev-loop` async subagent. The subagent owns the startup resolver, route selection,
-and all subsequent implementation steps. The main agent never runs `dev-loops loop startup`
-directly.
-
-## Enforcement posture
-
-- Under **Pi**, this contract is enforced by convention and review.
-- Under **Claude Code**, the **Edit/Write tool** path is enforced **mechanically** by a
-  `PreToolUse` Write/Edit hook (`.claude/hooks/pre-tool-use-write-guard.mjs`, wired via
-  `.claude/settings.json` for this repo's own sessions and via `.claude/hooks/hooks.json` for the
-  Claude plugin): a Write/Edit whose target is inside the repo working tree and not
-  gitignored is **denied** when it originates from the main agent, and allowed only inside the
-  `dev-loop` subagent context (detected via the neutral `DEVLOOPS_RUN_ID` run-id contract, or
-  the dev-loop `agent_type` — a generic subagent is not authorized).
-  Strict enforcement is opt-in via `DEVLOOPS_MAIN_AGENT_READONLY=1` (default fail-open) so
-  adopting the harness does not retroactively break a repo's own interactive dev; full run-id
-  propagation into the Claude subagent context completes with the headless/agent wiring.
-- **Scope of mechanical enforcement:** the hook covers the Edit and Write tools. Bash-driven
-  repo mutations the contract also forbids (`git commit`/`git push`/branch creation, in-place
-  edits like `sed -i`, shell redirection `> file` / `tee`) run through the Bash tool and remain
-  **convention-enforced** for now; the only Bash command the gate hook blocks is the ungated
-  `gh pr ready`. Tightening Bash-mutation coverage is possible follow-up.
-- A companion `PreToolUse` Bash hook reproduces the `gh pr ready` draft-gate guard.
-- A `dev-loop` async subagent should still reject delegation attempts that bypass the contract.
-
-## Non-goals
-
-- Pre-commit hooks (out of scope; the boundary is enforced at the Claude tool layer).
-- Changing dev-loop resolver behavior
-- Modifying the subagent API itself

package/CHANGELOG.md

@@ -2,6 +2,38 @@
 
 All notable changes to this project will be documented in this file.
 
+## 0.2.5
+
+### Changed
+
+- **Claude Code: the Copilot PR follow-up loop runs inline** (#838, completing the umbrella
+  collapse from #837). The copilot-pr-followup skill's Pi "persistence model" — *subagents do
+  bounded work and exit on the wait boundary; the main session re-dispatches* — is now scoped to
+  Pi via `<!-- pi-only -->`. Under the Claude harness the single dev-loop agent runs the
+  `watch → fix/reply/resolve → re-request → watch` loop **inline**: the helper-owned wait tools
+  (`dev-loops loop watch-cycle`, `gh run watch`, `dev-loops gate probe-copilot`) block inline and return, so
+  the agent keeps looping until terminal or the watch budget expires — no exit-and-redispatch. The
+  outer-loop checkpoint, watch budget, the forbidden-shell-watcher rules, and the gate requirements
+  are unchanged and harness-agnostic. Pi behavior is unchanged.
+
+## 0.2.4
+
+### Changed
+
+- **Claude Code: the dev-loop runs as a single agent** (#837). The Pi "umbrella" execution model —
+  a strictly read-only main agent that must dispatch an async `dev-loop` subagent, with all
+  mutations and state-changing CLI (`gate`/`pr`/`loop`) confined to that subagent — is now scoped
+  to Pi only. Under the Claude harness the dev-loop agent performs the steps directly: it reads and
+  writes repo files, runs git/PR operations, runs the `dev-loops` CLI, and **posts gate verdicts
+  under the operating session's identity** (fixing clean gates that previously stalled, unable to
+  record their verdict without separate "coordinator authority"). The `gh pr ready` draft-gate
+  guard still applies, and the read-only boundary remains available opt-in via
+  `DEVLOOPS_MAIN_AGENT_READONLY=1`. Implemented by scoping the Pi read-only/dispatch contract in
+  `main-agent-contract.md` and the dev-loop skill's startup procedure behind `<!-- pi-only -->`
+  markers; the asset generator now applies that stripping to bundled contract docs too, so the
+  Claude plugin ships the single-agent model while Pi keeps the full contract. Pi behavior is
+  unchanged. (Follow-up #838 tracks the copilot-pr-followup/conductor async-execution model.)
+
 ## 0.2.3
 
 ### Added

package/package.json

@@ -68,7 +68,7 @@
   },
   "dependencies": {
     "mermaid": "11.15.0",
-    "@dev-loops/core": "^0.2.3"
+    "@dev-loops/core": "^0.2.5"
   },
   "repository": {
     "type": "git",
@@ -78,7 +78,7 @@
     "url": "https://github.com/mfittko/dev-loops/issues"
   },
   "homepage": "https://github.com/mfittko/dev-loops#readme",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "files": [
     "cli/",
     "lib/",

package/scripts/claude/generate-claude-assets.mjs

@@ -14,7 +14,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
-import { transformAgent, transformSkill } from "@dev-loops/core/claude/asset-generation";
+import { transformAgent, transformSkill, stripPiOnlyBlocks } from "@dev-loops/core/claude/asset-generation";
 
 /**
  * Collect the generated assets as { target, content } pairs (target is repo-relative).
@@ -63,7 +63,12 @@ export function collectGeneratedAssets({ repoRoot = process.cwd() } = {}) {
   return assets;
 }
 
-/** Recursively collect `*.md` files under a source dir as verbatim {target, content} bundle assets. */
+/**
+ * Recursively collect `*.md` files under a source dir as {target, content} bundle assets.
+ * Bodies are passed through `stripPiOnlyBlocks` so bundled contract docs can scope Pi-runtime
+ * prose out of the Claude copies via `<!-- pi-only -->` markers (a no-op for marker-free docs,
+ * so the existing verbatim bundle is unchanged).
+ */
 function collectBundle(repoRoot, srcRel, targetRel) {
   const out = [];
   const absDir = path.join(repoRoot, srcRel);
@@ -74,7 +79,7 @@ function collectBundle(repoRoot, srcRel, targetRel) {
     } else if (entry.name.endsWith(".md")) {
       out.push({
         target: `${targetRel}/${entry.name}`,
-        content: fs.readFileSync(path.join(absDir, entry.name), "utf8"),
+        content: stripPiOnlyBlocks(fs.readFileSync(path.join(absDir, entry.name), "utf8")),
       });
     }
   }

package/skills/copilot-pr-followup/SKILL.md

@@ -57,7 +57,15 @@ Use this helper output as source of truth for the normal routing seam. Interpret
 ```sh
 node <resolved-skill-scripts>/loop/run-watch-cycle.mjs --repo <owner/name> --pr <number>
 ```
-Persistent async watch/fix loop, not handoff-only behavior: `watch → detect → if threads found, fix + reply + resolve → re-request → watch again → … → pre_approval_gate → merge`. **PERSISTENCE MODEL: Subagents do bounded implementation tasks and exit on external wait. The main session drives the loop and re-dispatches when continuation is feasible.** A single returned watch cycle is never completion by itself. If `cycleDisposition` is `pending` and `terminal` is `false`, the subagent exits on the wait boundary; the main session re-dispatches another watch boundary. Max watch timeout: **30 minutes** (from `policy-constants.mjs` COPILOT_REVIEW_WAIT_TIMEOUT_MS); expired budget + still `waiting_for_copilot_review` = hard stop. If the user explicitly asks for async handoff-only behavior, say that out loud and stop after the handoff boundary.
+Persistent async watch/fix loop, not handoff-only behavior: `watch → detect → if threads found, fix + reply + resolve → re-request → watch again → … → pre_approval_gate → merge`. A single returned watch cycle is never completion by itself.
+
+<!-- pi-only -->
+**PERSISTENCE MODEL: Subagents do bounded implementation tasks and exit on external wait. The main session drives the loop and re-dispatches when continuation is feasible.** If `cycleDisposition` is `pending` and `terminal` is `false`, the subagent exits on the wait boundary; the main session re-dispatches another watch boundary.
+<!-- /pi-only -->
+
+> Under the Claude Code harness, run this loop **inline in a single agent**: the helper-owned wait tools (`dev-loops loop watch-cycle`, `gh run watch`, `dev-loops gate probe-copilot`) block inline and return — when `cycleDisposition` is `pending` and `terminal` is `false`, run the next watch cycle yourself. Do not exit on the wait boundary to have a parent re-dispatch the loop; keep driving it in this agent until a terminal state or the watch budget expires. (Delegating a bounded fix to the `fixer` agent, per Step 6, is still fine — that is task delegation, not re-dispatching the watch loop.)
+
+Max watch timeout: **30 minutes** (from `policy-constants.mjs` COPILOT_REVIEW_WAIT_TIMEOUT_MS); expired budget + still `waiting_for_copilot_review` = hard stop. If the user explicitly asks for async handoff-only behavior, say that out loud and stop after the handoff boundary.
 
 **4. Low-level helpers**
 ```sh
@@ -137,8 +145,10 @@ already has an outer-loop checkpoint, check whether the checkpoint implies an au
    (including `timestamp` and potentially incrementing `waitCycles`).
    Read the on-disk artifact without mutating it.
 2. If `outerAction` is `continue_wait`:
-   - The loop was waiting. The subagent exits; the main session re-dispatches a fresh
-     `dev-loop` async subagent that resumes from the checkpoint.
+   - The loop was waiting; resume it from the checkpoint.
+     <!-- pi-only -->Under Pi the subagent exits and the main session re-dispatches a fresh
+     `dev-loop` async subagent that resumes from the checkpoint.<!-- /pi-only -->
+     Under the Claude Code harness, continue the wait inline (run the next watch cycle yourself).
 3. If `outerAction` is `reenter_copilot_loop`:
    - The copilot inner loop needs action. Run `copilot-pr-handoff.mjs` to determine the
      exact next step and proceed.
@@ -149,8 +159,8 @@ already has an outer-loop checkpoint, check whether the checkpoint implies an au
 6. If no checkpoint exists or `outerAction` is `done`:
    - Continue with normal step sequencing.
 
-Do not skip this guard when transitioning between async subagent runs on the same PR.
-The outer-loop checkpoint is the canonical re-attachment artifact for the subagent.
+Do not skip this guard when resuming work on the same PR<!-- pi-only --> (under Pi, between async subagent runs)<!-- /pi-only -->.
+The outer-loop checkpoint is the canonical re-attachment artifact.
 
 ## Step 6: Async watch behavior
 
@@ -166,8 +176,10 @@ Preferred approach:
 - `timeout`/`idle` → re-run `copilot-pr-handoff.mjs --watch-status <status>` once to refresh state; if still `waiting_for_copilot_review` after 30-minute watch budget exhausted, hard stop with `watch timeout — PR #<number> needs manual attention`
 - zero-timeout `idle` probes are for explicit one-shot status/reattach checks only; they are not the normal async wait mechanism
 - after a successful fix / reply-resolve / re-request cycle, returning to `waiting_for_copilot_review` is a persistence boundary: resume the watcher instead of reporting completion
+<!-- pi-only -->
 - if a child async run exits and the refreshed state remains non-terminal (for example `waiting_for_copilot_review`) before merge and without a hard stop, treat that as early exit and the main session re-dispatches the same-PR follow-up path when feasible (the subagent exits on external wait)
-- dispatch fix findings to `fixer` subagent; do not run inline fix passes in-watcher
+<!-- /pi-only -->
+- dispatch fix findings to the `fixer` agent; do not run inline fix passes in-watcher
 - do not report completion while unresolved Copilot feedback remains
 
 ### Canonical async dispatch wording
@@ -181,8 +193,8 @@ Key rules:
 - agent-authored shell polling is forbidden: do not use `nohup`, detached shell jobs, `tmux`, `screen`, or ad hoc `for i in $(seq ...)`, `while true`, `until ...; do sleep ...; done`, or `sleep`-retry bash loops
 - do not wrap repeated `gh pr view`, `gh pr checks`, `gh api`, or `detect-copilot-loop-state.mjs` calls inside shell polling loops
 - do not bypass session-based async notifications with detached shell automation
-- if Pi async subagents or the designated async follow-up skill are not appropriate or available, stop and report rather than improvising a shell watcher
-- the async-start contract is enforced in code: `outer-loop.mjs` fails closed without a visible Pi-managed async run id when `workflow.asyncStartMode: required`
+- if the designated async follow-up skill is not appropriate or available, stop and report rather than improvising a shell watcher
+- the async-start contract is enforced in code: `outer-loop.mjs` fails closed without a visible async run id when `workflow.asyncStartMode: required` (relaxed automatically under the Claude Code harness — see #830)
 
 ### Async delegation guard rules (#524)
 

package/skills/dev-loop/SKILL.md

@@ -22,29 +22,33 @@ Required installed runtime contract docs are shared bundled copies under `../doc
 
 ## 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 (`DEVLOOPS_RUN_ID`, or the `PI_SUBAGENT_RUN_ID` alias) that the Pi harness injects when it dispatches the async subagent; 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 -->
 
-### Dev-loop subagent (post-dispatch)
+### Resolve authoritative state
 
-The subagent resolves authoritative state via the startup resolver (`npx dev-loops loop startup --issue <n>` for issues, `npx dev-loops loop startup --pr <n>` for PRs), then immediately builds the handoff envelope via `npx dev-loops 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](../docs/workflow-handoff-contract.md) for the derivation contract.
+> 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](../docs/main-agent-contract.md).
+
+Resolve authoritative state via the startup resolver (`npx dev-loops loop startup --issue <n>` for issues, `npx dev-loops loop startup --pr <n>` for PRs), then immediately build the handoff envelope via `npx dev-loops 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](../docs/workflow-handoff-contract.md) 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-delegation gate (mandatory — subagent only):** Before delegating async work targeting an existing PR, the dev-loop subagent must run `node scripts/loop/copilot-pr-handoff.mjs --repo <owner/name> --pr <number>` and abort if `action: "stop"`. When `terminal: true`, proceed inline. When `terminal: false`, resolve the blocking condition first.
+**Pre-flight PR gate (mandatory):** Before working an existing PR, the dev-loop must run `node scripts/loop/copilot-pr-handoff.mjs --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 — subagent only):** Always use a worktree checkout for git operations, file reads/writes, and validation commands — never use the `main` checkout.
+**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 — subagent only):** Always run `git fetch origin` before creating or reusing any worktree.
+**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
-subagent must check the checkpoint before treating the start as a fresh intake or follow-up:
+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`:
@@ -105,14 +109,14 @@ When `@dev-loops/core` is available again, switch back to the full helper. The f
 
 ## Read-only info shortcut
 
-The main agent may handle info/handoff requests directly via `npx dev-loops loop info` without dispatching the async `dev-loop` subagent:
+Info/handoff requests can be served directly via `npx dev-loops loop info` (read-only; no full dev-loop run required):
 - `npx dev-loops loop info --issue <n>` — human-readable issue state summary (strategy, route, linked PR, next action)
 - `npx dev-loops loop info --pr <n>` — human-readable PR state summary (branch, CI, threads, rounds, action)
 - `npx dev-loops loop info --issue <n> --json` — machine-readable JSON output
 
-## Guard rules (subagent reference)
+## Guard rules
 
-**Handoff envelope precedence:** The subagent builds the envelope immediately after authoritative-state resolution and treats it as the first handoff artifact. Read it first, load only `requiredReads`, execute `nextAction`. See [Dev-loop subagent](#dev-loop-subagent-post-dispatch). Derivation contract: [Workflow Handoff Contract](../docs/workflow-handoff-contract.md).
+**Handoff envelope precedence:** The dev-loop builds the envelope immediately after authoritative-state resolution and treats it as the first handoff artifact. Read it first, load only `requiredReads`, execute `nextAction`. See [Resolve authoritative state](#resolve-authoritative-state). Derivation contract: [Workflow Handoff Contract](../docs/workflow-handoff-contract.md).
 
 **Handoff contract rule:** When no envelope is present, use the `workflow-handoff-contract.md` contract. Never delegate with abbreviated task summaries. Include deterministic routing inputs, explicit `cwd`, bounded task scope, exit conditions.
 
@@ -135,7 +139,7 @@ All PRs must pass the full gate pipeline before merge. No scope is exempt: docs-
 ## Authority boundary
 
 - Source code, tests, config, CI, and shared contract docs are authoritative.
-- Main-agent delegation contract: [Main Agent Contract](../docs/main-agent-contract.md) — absolute read-only boundary; all mutations flow through `dev-loop` async subagent.
+- Main-agent delegation contract: [Main Agent Contract](../docs/main-agent-contract.md) — how dev-loop work is structured per harness (Pi: read-only main agent + async-subagent dispatch; Claude: a single agent runs the steps directly).
 - Before any state-changing action, get explicit confirmation unless already authorized.
 - A question requires an answer, not an action.
 - Stop and ask rather than guessing when facts don't agree.

package/skills/docs/main-agent-contract.md

@@ -1,6 +1,18 @@
 # Main-agent delegation contract
 
-> **Absolute read-only boundary.** The main agent must never mutate files tracked by the repository.
+How dev-loop work is structured depends on the harness.
+
+**Under the Claude Code harness, the dev-loop runs as a single agent.** The agent invoked for
+dev-loop work performs the steps directly — it reads and writes repository files, runs git and PR
+lifecycle operations, runs the `dev-loops` CLI (including state-changing `gate` / `pr` / `loop`
+subcommands), and posts gate verdicts under the operating session's identity. There is no separate
+read-only "main agent" and no mandatory async-subagent dispatch: the dev-loop agent owns the work
+end to end. The draft-gate `gh pr ready` guard still applies (harness-agnostic). A read-only
+boundary can be re-imposed optionally via the Write/Edit guard hook — opt-in with
+`DEVLOOPS_MAIN_AGENT_READONLY=1` (default fail-open) — for repos that want it.
+
+<!-- pi-only -->
+> **Absolute read-only boundary (Pi).** The main agent must never mutate files tracked by the repository.
 > All mutations flow through the `dev-loop` async subagent.
 
 ## Contract
@@ -83,3 +95,4 @@ directly.
 - Pre-commit hooks (out of scope; the boundary is enforced at the Claude tool layer).
 - Changing dev-loop resolver behavior
 - Modifying the subagent API itself
+<!-- /pi-only -->