@delegance/claude-autopilot 7.11.0-pre.3 → 7.11.0

package/CHANGELOG.md

@@ -2,6 +2,172 @@
 
 - v5.6 Phase 7 (docs reconciliation) — pending.
 
+## 7.11.0 — 2026-05-20
+
+**v7.11.0 — Concurrent subagent dispatch (GA).** This release closes the
+v7.11.0 stack landed as `v7.11.0-pre.1` through `v7.11.0-pre.5` and ships
+the user-facing skill + schema + release wiring. The implementation was
+split into six PRs for reviewability (see PR links below); the published
+version users install is `7.11.0` on npm `latest`. The five `pre.*` tags
+remain in git history as the implementation breakdown.
+
+Spec: [PR #187](https://github.com/axledbetter/claude-autopilot/pull/187)
+([`docs/superpowers/specs/2026-05-19-v7.11.0-concurrent-subagent-execution-design.md`](docs/superpowers/specs/2026-05-19-v7.11.0-concurrent-subagent-execution-design.md)).
+
+Implementation PRs:
+- [#197](https://github.com/axledbetter/claude-autopilot/pull/197) — dep graph foundations (`v7.11.0-pre.1`).
+- [#198](https://github.com/axledbetter/claude-autopilot/pull/198) — locking primitives (`v7.11.0-pre.2`).
+- [#199](https://github.com/axledbetter/claude-autopilot/pull/199) — event + budget atomicity (`v7.11.0-pre.3`).
+- [#200](https://github.com/axledbetter/claude-autopilot/pull/200) — scheduler + worktree lifecycle (`v7.11.0-pre.4`).
+- [#201](https://github.com/axledbetter/claude-autopilot/pull/201) — merge orchestrator (`v7.11.0-pre.5`).
+- This PR (#193) — SKILL integration + release wiring.
+
+### Added
+
+- **Concurrent subagent dispatch in autopilot Step 3.** The sequential
+  one-task-at-a-time loop is replaced with a tier-based scheduler that
+  dispatches independent plan tasks in parallel into isolated per-task
+  worktrees under `.claude/worktrees/<run-ulid>/<task-id>/`. A dedicated
+  integration worktree at `.claude/worktrees/<run-ulid>/integration/` owns
+  the only checkout of `feature/<topic-slug>`; the main repo working tree
+  is never touched for the duration of the run.
+- **`depends_on:` annotation in plan files** (documented in
+  `skills/writing-plans/SKILL.md`). Tasks declare dependencies by `### Task
+  N: <name>` reference; the scheduler builds a DAG, detects cycles, and
+  topologically sorts tasks into dispatchable tiers. Multi-commit task
+  branches are cherry-picked in `git rev-list --reverse base..tip` order,
+  producing a linear feature-branch history.
+- **`concurrency:` config block in `guardrail.config.yaml`** (schema:
+  `presets/schemas/guardrail.config.schema.json`). New keys:
+  - `maxParallelSubagents` (int, **range 1..8**, default 3) — invalid
+    values fail at config-load with a schema validation error.
+  - `perSubagentTimeoutMs` (int ms, default 30 minutes).
+  - `assumeIndependentWithoutDependsOn` (bool, default false).
+  - `useDedicatedMergeWorktree` (bool, default true).
+  - `allowMergeCommitsInTasks` (bool, default false).
+- **`budgets.perSubagentUSD`** — HARD cost cap per subagent. Dispatch is
+  rejected when `preFlightEstimate > perSubagentUSD`; an in-flight
+  subagent is SIGTERMed (process group; SIGKILL after 30s) and emits
+  `task.failed` if actual cost exceeds the cap mid-execution. Set to
+  `null` to disable.
+- **11 new run-state event types** for concurrent dispatch:
+  `task.started`, `task.budget_reserved`,
+  `task.budget_increased_reservation`, `task.budget_released`,
+  `task.completed`, `task.failed`, `task.merged`,
+  `task.merge_conflict`, `task.merge_aborted`, `task.timeout`,
+  `task.budget_halt`. All event writes route through a per-run serialized
+  writer that holds an exclusive `flock` on `events.ndjson` for the
+  `(replay → check → append → release)` critical section. **The
+  append is a single `O_APPEND` write (atomic at the byte level) but
+  is NOT followed by `fsync` per event** — see "Audit-log durability"
+  below for the rationale and the no-fsync limitation.
+- **Cross-process repo lock** at `.claude/run-state/repo.lock`, acquired
+  by every CLI command that mutates repo state (autopilot, run resume,
+  runs gc, runs cleanup). Uses `flock(LOCK_EX|LOCK_NB)` — NOT
+  check-then-create. Stale-lock detection (PID not running on host AND
+  acquired > 1 hour ago) surfaces an explicit
+  `claude-autopilot runs cleanup --force-unlock` recovery command — no
+  auto-clear.
+- **In-process git operation queue** serializing all repo-level git
+  operations (worktree add/remove, branch create/delete, cherry-pick,
+  abort, GC) so concurrent scheduler callers cannot corrupt
+  `.git/refs/` or pack files.
+- **Public package subpath export** `./concurrent-dispatch` — consumers
+  can `import { runScheduler, computeEffectiveConcurrency }` from
+  `@delegance/claude-autopilot/concurrent-dispatch` without deep-importing
+  into compiled paths.
+- **Skill integration:** `skills/autopilot/SKILL.md` Step 2 now creates
+  `feature/<topic-slug>` as a ref-only (no checkout in main worktree),
+  and Step 3 invokes the concurrent dispatcher with the fallback rule
+  enforced by `src/core/concurrent-dispatch/dep-graph.ts`. New skill
+  `skills/writing-plans/SKILL.md` documents the `depends_on:` annotation,
+  the three-clause fallback policy, and walks through a mixed
+  annotated/unannotated plan example.
+
+### Changed — new failure modes (operator-visible)
+
+These are **new behaviors v7.10.0 did not have**. Read carefully before
+upgrading:
+
+- **Cherry-pick conflict halts the run.** The merge orchestrator does NOT
+  auto-resolve, even for trivial conflicts. Diagnostics
+  (`git diff --name-only --diff-filter=U`, `git ls-files -u`, full
+  porcelain) are persisted to
+  `.claude/run-state/<run-ulid>/conflicts/<task-id>.md` BEFORE
+  `cherry-pick --abort` clears the working tree. The user resolves by
+  (a) adding an explicit `depends_on:` to the plan and rerunning,
+  (b) manually resolving in the preserved worktree, or
+  (c) marking the offending pair as sequential in
+  `guardrail.config.yaml`.
+- **Interrupted tasks require explicit confirmation on resume.** A task
+  in state `started` with NO terminal event (no `task.completed`,
+  `task.failed`, `task.timeout`) is classified `interrupted` by
+  `claude-autopilot run resume <ulid>`. The CLI refuses to auto-merge
+  any partial commits — the user must pass
+  `--confirm-interrupted-tasks <task-id>...` to either re-dispatch from
+  a clean branch (discarding partial commits) or merge what's there
+  (user accepts risk). This is stricter than the pass-1 draft, which
+  would have auto-merged "if commits present" — that was unsafe because
+  commits alone do not prove the subagent finished its task contract.
+- **`budgets.perSubagentUSD` is a HARD cap, not soft.** Dispatch is
+  rejected pre-flight if the estimate exceeds the cap, and a running
+  subagent is killed (SIGTERM → SIGKILL of its process group) if actual
+  cost overruns. To get soft-reservation semantics, omit
+  `perSubagentUSD` and rely solely on `perRunUSD`.
+- **Task branches with merge commits are rejected by default.** Set
+  `concurrency.allowMergeCommitsInTasks: true` if your subagents
+  legitimately produce merge commits.
+- **Audit-log durability — documented limitation.** Event writes are
+  single-`write(O_APPEND)` per JSONL line under the exclusive `flock`,
+  but the writer does NOT `fsync(events.ndjson)` per event. A power
+  loss between two appends can therefore lose the last few events even
+  though the file lock was held atomically. This is a deliberate
+  trade-off: per-event fsync would dominate scheduler throughput at
+  high concurrency. If your environment requires per-event durability,
+  set `maxParallelSubagents: 1` and the audit-log will degrade to
+  v7.10.0 semantics.
+
+### Fallback policy (backwards compatibility)
+
+Plans without `depends_on:` annotations continue to work without changes:
+
+- `concurrency.maxParallelSubagents: 1` → sequential dispatch
+  reproducing v7.10.0 behavior exactly.
+- ZERO tasks declare `depends_on:` → sequential by default. Existing
+  plans are NEVER silently parallelized. Override with
+  `concurrency.assumeIndependentWithoutDependsOn: true` to opt in to
+  file-overlap inference.
+- At least one task declares `depends_on:` → explicit deps + file-
+  overlap inference for the remaining unannotated tasks.
+
+Cycle detection runs in all three cases before dispatch begins.
+
+### Resume semantics
+
+`claude-autopilot run resume <ulid>` classifies tasks by their LAST
+terminal event in `events.ndjson`:
+
+- `task.merged` → DONE; skip.
+- `task.completed` (no merged) → eligible; re-run merge orchestrator if
+  deps are merged.
+- `task.failed` → terminal; surface, do not retry without intervention.
+- `task.merge_conflict` → terminal; surface report path; user must
+  resolve before resume continues.
+- `task.timeout` → terminal (dual emission of `task.timeout` +
+  `task.failed`).
+- `task.started` with no terminal event → INTERRUPTED; requires
+  `--confirm-interrupted-tasks <task-id>...`.
+
+### Out of scope (deferred, per spec)
+
+- Hosted profile sharing — separate spec.
+- AI-generated custom config — separate spec.
+- v6 run-state engine integration into the autopilot skill — issue #180.
+- Frontend quality — issue #178.
+- Expand/contract migration safety — issue #179.
+- Parallelizing validate / codex-review / bugbot steps — separate spec.
+- Distributed execution across machines — separate spec.
+
 ## 7.10.1 — 2026-05-13
 
 **v7.10.1 — `examples` verb.** Patch release. Closes the discoverability

package/dist/src/cli/help-text.d.ts

@@ -37,6 +37,18 @@ export declare const HELP_GROUPS: HelpGroup[];
  * `claude-autopilot help <verb>` will show just the row in that case.
  */
 export declare const HELP_OPTIONS: Record<string, string>;
+/**
+ * Documentation block for the v7.11.0+ `concurrency:` configuration in
+ * `guardrail.config.yaml`. Rendered by `claude-autopilot help concurrency`
+ * (advisory pointer — there is no `concurrency` verb; this is config docs).
+ *
+ * Keep this block in sync with:
+ *   - `presets/schemas/guardrail.config.schema.json` (the validated shape)
+ *   - `skills/autopilot/SKILL.md` Step 3 (the fallback rule consumer)
+ *   - `skills/writing-plans/SKILL.md` (`depends_on:` annotation contract)
+ *   - `src/core/concurrent-dispatch/dep-graph.ts` (`DEFAULT_FALLBACK_POLICY`)
+ */
+export declare const CONCURRENCY_CONFIG_BLOCK = "guardrail.config.yaml \u2014 concurrency block (v7.11.0+):\n\n  concurrency:\n    maxParallelSubagents: 3              # int, range 1..8, default 3\n    perSubagentTimeoutMs: 1800000        # int ms, default 30 min (1,800,000)\n    assumeIndependentWithoutDependsOn: false  # bool, default false\n    useDedicatedMergeWorktree: true      # bool, default true\n    allowMergeCommitsInTasks: false      # bool, default false\n\n  budgets:\n    perRunUSD: 10                        # number USD, existing\n    perPhaseUSD: 5                       # number USD, existing\n    perSubagentUSD: 3                    # number USD or null (v7.11.0+)\n                                         #   HARD cap per subagent: dispatch\n                                         #   is rejected if preflight estimate\n                                         #   exceeds it; an in-flight subagent\n                                         #   is SIGTERMed if actual cost\n                                         #   exceeds it. Set null to disable.\n\nKeys:\n\n  maxParallelSubagents\n    Maximum concurrent subagents. Schema range 1..8 (enforced at config-load\n    via presets/schemas/guardrail.config.schema.json \u2014 invalid values fail).\n    Effective concurrency at runtime is further clamped by\n    providerRateLimitConcurrency and the remaining task count. Setting to 1\n    reproduces v7.10.0 sequential behavior exactly.\n\n  perSubagentTimeoutMs\n    Hard per-subagent timeout. On expiry the scheduler SIGTERMs the\n    subagent's entire process group (kill -TERM -<pgid>); SIGKILL follows\n    after 30s if no response. Emits both task.timeout (informational) and\n    task.failed (terminal, error_type: 'timeout') events.\n\n  assumeIndependentWithoutDependsOn\n    Fallback policy for plans where ZERO tasks declare depends_on. Default\n    false = run sequentially (preserves v7.10.0 semantics). Set true to opt\n    in to file-overlap inference for unannotated plans. Has no effect when\n    at least one task in the plan declares depends_on.\n\n  useDedicatedMergeWorktree\n    When true (default), the merge orchestrator cherry-picks task branches\n    inside a dedicated integration worktree at\n    .claude/worktrees/<run-ulid>/integration/ \u2014 the main repo working tree\n    is never touched. Disable only if your repo cannot afford the extra\n    worktree (rarely necessary).\n\n  allowMergeCommitsInTasks\n    When false (default), the merge orchestrator rejects task branches that\n    contain merge commits. Subagents are expected to produce a linear\n    sequence of commits on top of base_sha.\n\n  budgets.perSubagentUSD\n    HARD per-subagent cost cap. Dispatch is rejected when preFlightEstimate\n    > perSubagentUSD. An in-flight subagent is killed and emits task.failed\n    with error_type: 'budget_exceeded' if actual_cost_usd exceeds the cap\n    mid-run. Set to null to disable the per-subagent cap entirely (in which\n    case only the perRunUSD soft reservation applies).\n\nFallback rule (single source of truth \u2014 enforced in\nsrc/core/concurrent-dispatch/dep-graph.ts):\n\n  1. concurrency.maxParallelSubagents: 1 \u2192 sequential dispatch.\n  2. ZERO tasks declare depends_on \u2192 sequential, unless\n     assumeIndependentWithoutDependsOn: true.\n  3. At least one task declares depends_on \u2192 use explicit deps + file-\n     overlap inference for unannotated tasks.\n\nSee skills/writing-plans/SKILL.md for the depends_on annotation contract.";
 /**
  * Global flags advertised in --help. These work across most verbs (per-verb
  * support varies; v6.0.1 wires them into `scan` first, additional verbs land

package/dist/src/cli/help-text.js

@@ -364,6 +364,86 @@ function padVerb(verb) {
     const WIDTH = 16;
     return verb.length >= WIDTH ? verb + ' ' : verb + ' '.repeat(WIDTH - verb.length);
 }
+/**
+ * Documentation block for the v7.11.0+ `concurrency:` configuration in
+ * `guardrail.config.yaml`. Rendered by `claude-autopilot help concurrency`
+ * (advisory pointer — there is no `concurrency` verb; this is config docs).
+ *
+ * Keep this block in sync with:
+ *   - `presets/schemas/guardrail.config.schema.json` (the validated shape)
+ *   - `skills/autopilot/SKILL.md` Step 3 (the fallback rule consumer)
+ *   - `skills/writing-plans/SKILL.md` (`depends_on:` annotation contract)
+ *   - `src/core/concurrent-dispatch/dep-graph.ts` (`DEFAULT_FALLBACK_POLICY`)
+ */
+export const CONCURRENCY_CONFIG_BLOCK = `guardrail.config.yaml — concurrency block (v7.11.0+):
+
+  concurrency:
+    maxParallelSubagents: 3              # int, range 1..8, default 3
+    perSubagentTimeoutMs: 1800000        # int ms, default 30 min (1,800,000)
+    assumeIndependentWithoutDependsOn: false  # bool, default false
+    useDedicatedMergeWorktree: true      # bool, default true
+    allowMergeCommitsInTasks: false      # bool, default false
+
+  budgets:
+    perRunUSD: 10                        # number USD, existing
+    perPhaseUSD: 5                       # number USD, existing
+    perSubagentUSD: 3                    # number USD or null (v7.11.0+)
+                                         #   HARD cap per subagent: dispatch
+                                         #   is rejected if preflight estimate
+                                         #   exceeds it; an in-flight subagent
+                                         #   is SIGTERMed if actual cost
+                                         #   exceeds it. Set null to disable.
+
+Keys:
+
+  maxParallelSubagents
+    Maximum concurrent subagents. Schema range 1..8 (enforced at config-load
+    via presets/schemas/guardrail.config.schema.json — invalid values fail).
+    Effective concurrency at runtime is further clamped by
+    providerRateLimitConcurrency and the remaining task count. Setting to 1
+    reproduces v7.10.0 sequential behavior exactly.
+
+  perSubagentTimeoutMs
+    Hard per-subagent timeout. On expiry the scheduler SIGTERMs the
+    subagent's entire process group (kill -TERM -<pgid>); SIGKILL follows
+    after 30s if no response. Emits both task.timeout (informational) and
+    task.failed (terminal, error_type: 'timeout') events.
+
+  assumeIndependentWithoutDependsOn
+    Fallback policy for plans where ZERO tasks declare depends_on. Default
+    false = run sequentially (preserves v7.10.0 semantics). Set true to opt
+    in to file-overlap inference for unannotated plans. Has no effect when
+    at least one task in the plan declares depends_on.
+
+  useDedicatedMergeWorktree
+    When true (default), the merge orchestrator cherry-picks task branches
+    inside a dedicated integration worktree at
+    .claude/worktrees/<run-ulid>/integration/ — the main repo working tree
+    is never touched. Disable only if your repo cannot afford the extra
+    worktree (rarely necessary).
+
+  allowMergeCommitsInTasks
+    When false (default), the merge orchestrator rejects task branches that
+    contain merge commits. Subagents are expected to produce a linear
+    sequence of commits on top of base_sha.
+
+  budgets.perSubagentUSD
+    HARD per-subagent cost cap. Dispatch is rejected when preFlightEstimate
+    > perSubagentUSD. An in-flight subagent is killed and emits task.failed
+    with error_type: 'budget_exceeded' if actual_cost_usd exceeds the cap
+    mid-run. Set to null to disable the per-subagent cap entirely (in which
+    case only the perRunUSD soft reservation applies).
+
+Fallback rule (single source of truth — enforced in
+src/core/concurrent-dispatch/dep-graph.ts):
+
+  1. concurrency.maxParallelSubagents: 1 → sequential dispatch.
+  2. ZERO tasks declare depends_on → sequential, unless
+     assumeIndependentWithoutDependsOn: true.
+  3. At least one task declares depends_on → use explicit deps + file-
+     overlap inference for unannotated tasks.
+
+See skills/writing-plans/SKILL.md for the depends_on annotation contract.`;
 /**
  * Global flags advertised in --help. These work across most verbs (per-verb
  * support varies; v6.0.1 wires them into `scan` first, additional verbs land
@@ -409,6 +489,8 @@ export function buildHelpText() {
             }
         }
     }
+    lines.push(CONCURRENCY_CONFIG_BLOCK);
+    lines.push('');
     lines.push('Run \x1b[36mclaude-autopilot help <command>\x1b[0m for command-specific options.');
     return lines.join('\n') + '\n';
 }

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@delegance/claude-autopilot",
-  "version": "7.11.0-pre.3",
+  "version": "7.11.0",
   "type": "module",
   "publishConfig": {
-    "tag": "next"
+    "tag": "latest"
   },
   "description": "Autonomous development pipeline for Claude Code: brainstorm → spec → plan → implement → migrate → validate → PR → review → merge. Multi-model, local-first, every phase a skill you can intervene in.",
   "keywords": [
@@ -53,6 +53,10 @@
       "types": "./dist/src/core/run-state/sameness-detector.d.ts",
       "default": "./dist/src/core/run-state/sameness-detector.js"
     },
+    "./concurrent-dispatch": {
+      "types": "./dist/src/core/concurrent-dispatch/index.d.ts",
+      "default": "./dist/src/core/concurrent-dispatch/index.js"
+    },
     "./bin/claude-autopilot.js": "./bin/claude-autopilot.js",
     "./bin/guardrail.js": "./bin/guardrail.js",
     "./package.json": "./package.json"

package/presets/schemas/guardrail.config.schema.json

@@ -0,0 +1,70 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/axledbetter/claude-autopilot/presets/schemas/guardrail.config.schema.json",
+  "title": "guardrail.config.yaml",
+  "description": "Top-level shape of guardrail.config.yaml. Only blocks that are validated at config-load are listed under properties; unrecognized keys are still permitted today (additionalProperties: true) so existing presets continue to parse while new validated blocks land in subsequent releases.",
+  "type": "object",
+  "required": ["configVersion"],
+  "additionalProperties": true,
+  "properties": {
+    "configVersion": {
+      "type": "integer",
+      "minimum": 1
+    },
+    "budgets": {
+      "type": "object",
+      "additionalProperties": true,
+      "description": "Cost caps in USD. `perRunUSD` and `perPhaseUSD` are enforced run-wide. `perSubagentUSD` is a HARD cap per concurrent subagent — dispatch is rejected if the preflight estimate exceeds it, and a running subagent is SIGTERMed if its actual cost overruns the cap. Leave `perSubagentUSD` null/omitted to fall back to a soft `perRunUSD`-only reservation model. additionalProperties is intentionally `true` in v7.11.0 for backwards-compatibility with existing user configs that may carry historical budget keys; a future minor will enumerate the full set and tighten this to `false`.",
+      "properties": {
+        "perRunUSD": {
+          "type": "number",
+          "minimum": 0
+        },
+        "perPhaseUSD": {
+          "type": "number",
+          "minimum": 0
+        },
+        "perSubagentUSD": {
+          "type": ["number", "null"],
+          "minimum": 0,
+          "description": "HARD per-subagent cost cap in USD. Dispatch is rejected when preFlightEstimate > perSubagentUSD; an in-flight subagent is killed and emits task.failed if actual_cost_usd exceeds it mid-run. Set to null to disable the per-subagent cap and rely solely on perRunUSD."
+        }
+      }
+    },
+    "concurrency": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Concurrent subagent dispatch settings (v7.11.0+). All keys are optional; defaults reproduce v7.10.0 sequential behavior for plans without depends_on annotations.",
+      "properties": {
+        "maxParallelSubagents": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 8,
+          "default": 3,
+          "description": "Maximum number of concurrent subagents (effective concurrency is further clamped by providerRateLimitConcurrency and taskCount). Setting to 1 reproduces v7.10.0 sequential behavior exactly. Above 8 the API rate limits dominate and additional parallelism does not help."
+        },
+        "perSubagentTimeoutMs": {
+          "type": "integer",
+          "minimum": 1000,
+          "default": 1800000,
+          "description": "Hard timeout per subagent in milliseconds (default 30 minutes). On timeout the scheduler SIGTERMs the subagent's process group; SIGKILL follows after 30 seconds if no response."
+        },
+        "assumeIndependentWithoutDependsOn": {
+          "type": "boolean",
+          "default": false,
+          "description": "When false (default), a plan in which ZERO tasks declare depends_on is run sequentially — preserving v7.10.0 semantics. Set true to opt in to file-overlap inference for unannotated plans."
+        },
+        "useDedicatedMergeWorktree": {
+          "type": "boolean",
+          "default": true,
+          "description": "When true (default), the merge orchestrator cherry-picks task branches inside a dedicated integration worktree under .claude/worktrees/<run-ulid>/integration/ so the main working tree is never mutated by the autopilot run. Disable only if your repo cannot afford the extra worktree (rarely necessary)."
+        },
+        "allowMergeCommitsInTasks": {
+          "type": "boolean",
+          "default": false,
+          "description": "When false (default), the merge orchestrator rejects task branches that contain merge commits. Subagents are expected to produce a linear sequence of commits on top of base_sha."
+        }
+      }
+    }
+  }
+}

package/skills/autopilot/SKILL.md

@@ -188,26 +188,81 @@ Output: Plan at docs/superpowers/plans/YYYY-MM-DD-<topic>.md
 
 After the plan is written but BEFORE committing it, run `npx tsx scripts/codex-review.ts <plan-path>`. Apply CRITICAL findings (sequencing errors, missing test coverage on a load-bearing path, schema/migration ordering bugs) to the plan inline. Then commit. Always use subagent-driven development for execution — do not ask the user.
 
-### Step 2: Set up worktree
+### Step 2: Set up feature branch (ref only — do NOT check out in main worktree)
 
 ```
 Invoke: superpowers:using-git-worktrees
 Branch: feature/<topic-slug>
+Mode:   create as a ref only; leave the main worktree on its prior branch.
 ```
 
-### Step 3: Execute plan
+Step 2 creates `feature/<topic-slug>` but does NOT check it out in the main
+worktree. Concurrent dispatch (Step 3) will create the SOLE checkout of the
+feature branch in `.claude/worktrees/<run-ulid>/integration/` — git linked
+worktrees forbid the same branch being checked out twice, so the scheduler
+must own the only checkout. The main repo working tree stays untouched for the
+entire run.
+
+If you are using `superpowers:using-git-worktrees`, pass it the "branch only,
+no checkout" mode (or equivalent) so it stops at `git branch
+feature/<topic-slug> <base-sha>` and does not run `git checkout` /
+`git worktree add` against the main repo.
+
+### Step 3: Execute plan (concurrent dispatch)
 
 ```
-Invoke: superpowers:subagent-driven-development
-Input: The plan file
-Mode: dispatch fresh subagent per task
+Invoke: claude-autopilot's concurrent dispatcher
+Input:  The plan file (with depends_on: annotations where applicable)
+Mode:   dispatch fresh subagents in parallel per the dep graph
 ```
 
-For each task:
-- Dispatch implementer subagent
-- On completion: verify commit landed in worktree
-- Skip formal spec/quality review to maintain speed (the validate step catches issues)
-- If subagent fails to write to worktree: implement directly
+**Default effective concurrency:**
+`min(3, providerRateLimitConcurrency, taskCount)`.
+Override via `guardrail.config.yaml` `concurrency.maxParallelSubagents`
+(schema range `1..8`).
+
+**Fallback rule (single source of truth — also enforced in
+`src/core/concurrent-dispatch/dep-graph.ts`):**
+
+- If `concurrency.maxParallelSubagents: 1` → sequential (reproduces v7.10.0
+  behavior exactly).
+- If ZERO tasks in the plan have `depends_on:` annotations → sequential,
+  unless `concurrency.assumeIndependentWithoutDependsOn: true` (opt in to
+  file-overlap inference).
+- If at least one task has `depends_on:` → use the explicit deps + fall back
+  to file-overlap inference for the remaining unannotated tasks.
+
+For each task, the scheduler:
+- creates a per-task worktree at `.claude/worktrees/<run-ulid>/<task-id>/`,
+  branched from the current feature tip (`base_sha` captured at dispatch);
+- dispatches an implementer subagent to commit on
+  `autopilot/<run-ulid>/<task-id>`;
+- on success, runs the merge orchestrator (under the cross-process repo lock)
+  to cherry-pick `base_sha..task_branch_tip_sha` onto the integration
+  worktree's `feature/<topic-slug>` checkout in plan-declaration order.
+
+**On any task failure**: halt the run, SIGTERM in-flight subagent process
+groups (kill -TERM -<pgid>; SIGKILL after 30s if no response), and surface a
+breakdown to the user:
+- `merged`: tasks whose commits are on the feature branch (guaranteed-good
+  set).
+- `completed-but-unmerged`: commits exist on per-task branches; worktrees
+  preserved for inspection.
+- `in-flight`: subagents that received SIGTERM; worktrees preserved.
+
+**On cherry-pick conflict**: diagnostics are written to
+`.claude/run-state/<run-ulid>/conflicts/<task-id>.md` BEFORE
+`cherry-pick --abort` runs; the run halts and the user resolves manually
+(add an explicit `depends_on:` to the plan, or fix the conflict in the
+preserved worktree).
+
+**Subagent contract:** subagent writes its own commits in its worktree. If
+the subagent fails to write to its worktree, fall back to direct
+implementation in that worktree only — never in the integration worktree or
+main repo working tree.
+
+Skip formal spec/quality review per task to maintain speed; the validate
+step (Step 4) catches issues across the merged feature branch.
 
 ### Step 4: Validate
 

package/skills/writing-plans/SKILL.md

@@ -0,0 +1,188 @@
+---
+name: writing-plans
+description: Write an implementation plan from an approved spec — task-by-task breakdown with files-to-change, step checkboxes, and (v7.11.0+) optional depends_on annotations for concurrent subagent dispatch. Use when the user has an approved spec and needs a plan ready for /implement or claude-autopilot Step 3.
+---
+
+# Writing plans
+
+A plan turns an approved spec into a sequence of executable tasks. Each task
+is the atomic unit dispatched to one subagent. Tasks declare the files they
+touch, the steps the subagent should perform, and optionally the other tasks
+they depend on (v7.11.0+).
+
+> **For the underlying brainstorming + spec flow**, see
+> `superpowers:brainstorming` and `superpowers:writing-plans` from the
+> superpowers plugin. This document is the claude-autopilot-side companion
+> covering the `depends_on:` annotation introduced in v7.11.0 and the
+> fallback policy that governs how it interacts with concurrent dispatch.
+
+## Plan file shape
+
+Plans live at `docs/superpowers/plans/YYYY-MM-DD-<topic>.md`. Top-level
+structure:
+
+```markdown
+# <Topic> Implementation Plan
+
+> **For agentic workers:** Use claude-autopilot Step 3 (concurrent dispatch)
+> or superpowers:subagent-driven-development to execute this plan task-by-task.
+
+**Goal:** <one-paragraph statement>
+**Architecture:** <one-paragraph statement>
+**Tech Stack:** <brief notes>
+
+---
+
+### Task 1: <task name>
+
+**Files:**
+- Create: `src/foo.ts`
+- Test: `tests/foo.test.ts`
+
+- [ ] **Step 1: <step name>**
+
+<step content — code blocks, instructions, etc.>
+
+- [ ] **Step 2: <step name>**
+
+<more content>
+
+### Task 2: <task name>
+
+**Files:**
+- Modify: `src/bar.ts`
+
+- [ ] **Step 1: ...**
+```
+
+Each task has:
+- A heading `### Task N: <name>` (numbered case-sensitively; the name is
+  human-readable and may be fuzzy-matched in `depends_on:` references).
+- A `**Files:**` block listing files this task creates, modifies, or tests.
+- One or more `- [ ] **Step N: ...**` checkboxes the subagent ticks as it
+  implements.
+
+## `depends_on:` annotation (v7.11.0+)
+
+To enable concurrent execution, annotate tasks that depend on other tasks.
+The annotation goes on its own line in the task header, after `**Files:**`:
+
+```markdown
+### Task 3: Wire foo into bar
+
+**Files:**
+- Modify: `src/bar.ts`
+- Modify: `src/foo.ts:42-60`
+
+**depends_on:** Task 1, Task 2
+
+- [ ] **Step 1: ...**
+```
+
+### Rules
+
+- `depends_on:` is **optional**. If absent, the scheduler infers
+  dependencies from file overlap (two tasks touching the same path become a
+  sequential pair, ordered by plan-declaration index).
+- References are by `### Task N: <name>` heading. **The task number is
+  matched case-sensitively; the name is fuzzy-matched** so minor wording
+  drift between the reference and the heading is tolerated.
+- Multiple deps are comma-separated: `**depends_on:** Task 1, Task 2`.
+- Cycles are a **hard error**. The scheduler surfaces the cycle path and
+  refuses to dispatch.
+- A task that **modifies** a file another task **creates** has an implicit
+  dependency on the creating task — the scheduler injects it automatically,
+  even without an explicit annotation.
+- File overlap without an explicit `depends_on:` produces a **warning**, not
+  an error. The scheduler treats overlapping tasks as a sequential pair in
+  plan-declaration order. Surfaced in the run report so the user can add an
+  explicit annotation if the inferred ordering was wrong.
+
+## Fallback policy (single source of truth)
+
+The fallback policy lives in `src/core/concurrent-dispatch/dep-graph.ts`
+(`DEFAULT_FALLBACK_POLICY` + `buildDepGraph`) and is mirrored in
+`skills/autopilot/SKILL.md` Step 3:
+
+1. **`concurrency.maxParallelSubagents: 1`** → sequential dispatch.
+   Reproduces v7.10.0 behavior exactly. Use this as the escape hatch.
+2. **ZERO tasks in the plan have `depends_on:`** → sequential by default.
+   Existing plans without annotations are never silently parallelized.
+   Override with `concurrency.assumeIndependentWithoutDependsOn: true` to
+   opt in to file-overlap inference for an unannotated plan.
+3. **At least one task has `depends_on:`** → use the explicit deps + fall
+   back to file-overlap inference for the remaining unannotated tasks.
+
+Cycle detection runs in all three cases before dispatch begins.
+
+## Example — mixed annotated + unannotated tasks
+
+```markdown
+# Banking integration plan
+
+**Goal:** wire Fiserv adapter into the data sync pipeline.
+**Architecture:** adapter under app/services/banking-integrations/adapters,
+sync orchestrator under inbound/, compliance check piggy-backs on the sync.
+
+---
+
+### Task 1: Fiserv adapter skeleton
+
+**Files:**
+- Create: `app/services/banking-integrations/adapters/fiserv.adapter.ts`
+- Test: `app/services/banking-integrations/adapters/__tests__/fiserv.adapter.test.ts`
+
+- [ ] **Step 1: Define the adapter class extending BaseBankingAdapter.**
+
+### Task 2: Borrower-matcher service
+
+**Files:**
+- Create: `app/services/banking-integrations/inbound/borrower-matcher.service.ts`
+- Test: `app/services/banking-integrations/inbound/__tests__/borrower-matcher.service.test.ts`
+
+- [ ] **Step 1: Implement EIN-then-name-then-email matching.**
+
+### Task 3: Wire adapter into data sync
+
+**Files:**
+- Modify: `app/services/banking-integrations/inbound/bank-data-sync.service.ts`
+- Modify: `app/services/banking-integrations/adapters/fiserv.adapter.ts`
+
+**depends_on:** Task 1, Task 2
+
+- [ ] **Step 1: Call the adapter from syncBankData; pipe results through borrower-matcher.**
+
+### Task 4: Update CHANGELOG
+
+**Files:**
+- Modify: `CHANGELOG.md`
+
+- [ ] **Step 1: Prepend a Banking integration entry under Unreleased.**
+```
+
+How the scheduler resolves this plan with `maxParallelSubagents: 3` and
+`assumeIndependentWithoutDependsOn: false`:
+
+- Task 1 and Task 2 declare no overlap with each other and have no
+  `depends_on:`, but Task 3 declares `depends_on: Task 1, Task 2` — so the
+  plan has at least one annotation, the explicit-deps + file-overlap
+  inference branch is used.
+- Tier 0: `Task 1, Task 2, Task 4` (no satisfied deps, no overlap with each
+  other) — dispatched in parallel up to `maxParallelSubagents`.
+- Tier 1: `Task 3` — eligible only after Tasks 1 and 2 reach state
+  `merged`.
+
+If you remove the `**depends_on:** Task 1, Task 2` line from Task 3, the
+plan has zero annotations, falls back to sequential dispatch, and runs
+Tasks 1 → 2 → 3 → 4 in plan-declaration order — reproducing v7.10.0
+behavior.
+
+## When NOT to annotate
+
+- The plan is small (≤ 3 tasks) and the wall-clock gain is not worth the
+  annotation maintenance cost.
+- All tasks touch the same handful of files (high overlap, no
+  parallelizable structure).
+- You want to ship the plan against v7.10.0 with the
+  `concurrency.maxParallelSubagents: 1` escape hatch and add annotations in
+  a follow-up.