dev-loops 0.2.2 → 0.2.4

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

@@ -1,6 +1,6 @@
 {
   "name": "dev-loops",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "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

@@ -225,6 +225,7 @@ When unresolved feedback exists, use a narrow follow-up loop:
     - if the refreshed snapshot reports unresolved threads, re-enter the reply/resolve loop for the missed threads
 12. only after GitHub-side reply/resolve work is done for the addressed threads and the refreshed thread snapshot proves zero unresolved threads remain, decide whether another Copilot pass is desired
     - resolve the review-round cap from config via `resolveRefinementConfig(config, "maxCopilotRounds")` from `@dev-loops/core/config`; default config ships `maxCopilotRounds: 5`
+    - **Opt out entirely:** `maxCopilotRounds: 0` disables the external Copilot review gate for the repo — the loop runs `draft_gate → pre_approval_gate` with the local harness only, never requesting or waiting on Copilot. Use this when the repo has no Copilot reviewer configured or prefers local-harness-only review.
     - use the completed Copilot review-round count from `detect-copilot-loop-state.mjs` / `copilot-pr-handoff.mjs` as the current PR's review-round count
     - if completed review rounds have reached the maximum (default: 5), do **not** re-request Copilot review
     - when the round limit is reached **and** the refreshed thread snapshot proves zero unresolved threads **and** current-head CI is green or credibly green, treat that clean state as eligible for `pre_approval_gate` fallback instead of deadlocking on another Copilot rerequest

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,37 @@
 
 All notable changes to this project will be documented in this file.
 
+## 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
+
+- **Opt out of the Copilot review gate via `refinement.maxCopilotRounds: 0`** (#832). For repos
+  without a Copilot reviewer configured (or that prefer local-harness-only review), setting
+  `maxCopilotRounds: 0` disables the external Copilot review cycle entirely — the loop runs
+  `draft_gate → pre_approval_gate` with no Copilot request or wait. The config schema now accepts
+  `0` (`nonnegative`; negative still rejected); `evaluatePrGateCoordination` routes `0` through the
+  existing `internal_only` path, `shouldGuardCopilotReviewRequest` never forces a request at `0`,
+  and the watch-cycle handoff (`copilot-pr-handoff`) skips the request too. Default (`5`) unchanged.
+  Documented in the README, extension config docs, and the `copilot-pr-followup` skill.
+
 ## 0.2.2
 
 ### Fixed

package/README.md

@@ -193,7 +193,7 @@ npx dev-loops gates   # see what reviewers will check
 Key surfaces:
 - **Gate angles** — which review lenses run at draft and pre-approval gates
 - **Persona prompts** — focused instructions per angle (DRY, KISS, YAGNI, SRP, SoC, and more)
-- **Refinement** — fan-out count and mode for parallel review variants
+- **Refinement** — fan-out count and mode for parallel review variants; `refinement.maxCopilotRounds` caps Copilot re-review rounds (default `5`), and **`maxCopilotRounds: 0` disables the Copilot review gate entirely** for local-harness-only review (`draft_gate → pre_approval_gate`, no Copilot) — useful when the repo has no Copilot reviewer configured
 - **Autonomy** — which gates require operator confirmation
 - **Workflow defaults** — retrospective enforcement, draft-first posture, dev-mode policy
 

package/extension/README.md

@@ -133,7 +133,9 @@ personas:
 
 # Override gate requirements
 refinement:
-  fanOut: 5      # run 5 parallel review variants instead of 3
+  fanOut: 5            # run 5 parallel review variants instead of 3
+  maxCopilotRounds: 0  # 0 disables the Copilot review gate entirely (local-harness-only
+                       # review: draft_gate → pre_approval_gate, no Copilot). Default: 5.
 
 autonomy:
   stopAt:

package/package.json

@@ -68,7 +68,7 @@
   },
   "dependencies": {
     "mermaid": "11.15.0",
-    "@dev-loops/core": "^0.2.2"
+    "@dev-loops/core": "^0.2.4"
   },
   "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.2",
+  "version": "0.2.4",
   "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/scripts/loop/copilot-pr-handoff.mjs

@@ -366,12 +366,31 @@ export async function runHandoff(options, { env = process.env, ghCommand = "gh"
   // Detect internal tooling PRs — suppress Copilot review request step entirely.
   // Internal-only PRs (scripts/docs/tests/config) skip the request, not just the wait.
   let internalOnlySkipCopilot = false;
-  // Skip internal detection in sequential stub/test mode to avoid consuming stub entries.
-  // Claims-mode stubs handle interleaved calls; detection runs normally.
-  if (!env.GH_SEQUENCE_PATH || env.GH_STUB_MODE === "claims") {
-  if (options.watchStatus === undefined &&
+  // Config opt-out (#832): maxCopilotRounds: 0 disables the external Copilot review
+  // gate for the repo (local-harness-only review). Treat it like an internal-only PR
+  // — skip the request, not just the wait — regardless of stub/sequence mode. This
+  // mirrors the gate-coordination side, which routes maxCopilotRounds: 0 to internal_only.
+  if (refinementConfig?.maxCopilotRounds === 0 &&
+      options.watchStatus === undefined &&
       (interpretation.state === STATE.PR_READY_NO_FEEDBACK ||
        interpretation.state === STATE.READY_TO_REREQUEST_REVIEW)) {
+    internalOnlySkipCopilot = true;
+    interpretation = {
+      ...interpretation,
+      state: STATE.INTERNAL_TOOLING_DIRECT_GATE,
+      nextAction: NEXT_ACTIONS[STATE.INTERNAL_TOOLING_DIRECT_GATE],
+      allowedTransitions: TRANSITIONS[STATE.INTERNAL_TOOLING_DIRECT_GATE] || [STATE.DONE],
+    };
+  }
+  // Skip internal detection in sequential stub/test mode to avoid consuming stub entries.
+  // Claims-mode stubs handle interleaved calls; detection runs normally.
+  if (
+    !internalOnlySkipCopilot &&
+    (!env.GH_SEQUENCE_PATH || env.GH_STUB_MODE === "claims") &&
+    options.watchStatus === undefined &&
+    (interpretation.state === STATE.PR_READY_NO_FEEDBACK ||
+      interpretation.state === STATE.READY_TO_REREQUEST_REVIEW)
+  ) {
     try {
       const internalCheck = await detectPrInternalOnly(options, { env, ghCommand });
       if (internalCheck.ok && internalCheck.internalOnly) {
@@ -387,7 +406,6 @@ export async function runHandoff(options, { env = process.env, ghCommand = "gh"
       // Best-effort: if detection fails, fall through to normal request behavior
     }
   }
-  }
 
   let reviewRequestStatus;
   const shouldRequestReview = !internalOnlySkipCopilot && options.watchStatus === undefined

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

@@ -229,6 +229,7 @@ When unresolved feedback exists, use a narrow follow-up loop:
     - if the refreshed snapshot reports unresolved threads, re-enter the reply/resolve loop for the missed threads
 12. only after GitHub-side reply/resolve work is done for the addressed threads and the refreshed thread snapshot proves zero unresolved threads remain, decide whether another Copilot pass is desired
     - resolve the review-round cap from config via `resolveRefinementConfig(config, "maxCopilotRounds")` from `@dev-loops/core/config`; default config ships `maxCopilotRounds: 5`
+    - **Opt out entirely:** `maxCopilotRounds: 0` disables the external Copilot review gate for the repo — the loop runs `draft_gate → pre_approval_gate` with the local harness only, never requesting or waiting on Copilot. Use this when the repo has no Copilot reviewer configured or prefers local-harness-only review.
     - use the completed Copilot review-round count from `detect-copilot-loop-state.mjs` / `copilot-pr-handoff.mjs` as the current PR's review-round count
     - if completed review rounds have reached the maximum (default: 5), do **not** re-request Copilot review
     - when the round limit is reached **and** the refreshed thread snapshot proves zero unresolved threads **and** current-head CI is green or credibly green, treat that clean state as eligible for `pre_approval_gate` fallback instead of deadlocking on another Copilot rerequest

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