@ikunin/sprintpilot 1.0.5 → 2.0.5

package/README.md

@@ -197,6 +197,32 @@ Output files:
 
 ---
 
+## Adaptive Process Scaling (v2)
+
+Sprintpilot v2 introduced **complexity profiles** as a first-class config dimension. The right amount of process for a 2-story bug-fix sprint is different from a 30-story green-field rebuild — and the cost of running the heavy flow on a small change is real (more LLM turns, more context rot, more time). One knob picks the right balance:
+
+| Profile | Per-story flow | Branching | Worktrees | Parallel stories | Use it for |
+|---------|---------------|-----------|-----------|------------------|-----------|
+| `nano` | `bmad-quick-dev` (one-shot) | `epic` (one PR per epic) | off | n/a | Tiny patch sprints, hot-fix runs |
+| `small` | Full 7-step BMad cycle | `story` (one PR per story) | on | off | Single-developer projects, ≤10 stories |
+| `medium` *(default)* | Full 7-step BMad cycle | `story` | on | off | Default — balanced for most sprints |
+| `large` | Full 7-step BMad cycle | `story` | on | **on** (Claude Code) | Multi-epic sprints, 20+ stories |
+| `legacy` | Pinned to v1.0.5 behavior byte-for-byte | `story` | on | off | Existing installs that want zero behavior change |
+
+Pick the profile at install time — interactive installer asks, non-interactive flag is `--profile <nano|small|medium|large|legacy>`. Missing profile defaults to `medium` with no behavior change vs. v1.0.5.
+
+**One knob per feature** — every v2 optimization layer can be disabled in isolation without uninstalling. See [Configuration Reference](docs/CONFIGURATION.md#autopilot-configuration-modulesautopilotconfigyaml).
+
+### What v2 ships on top of the core flow
+
+- **Phase timing instrumentation** — `mark` action emits `duration` records per skill phase; auto-emitted on critical paths (no LLM bracket calls to skip). `summarize-timings.js` reports hotspots > 5% of total time.
+- **State sharding** — non-critical writes accumulate in `.pending/` shards, flushed atomically at story boundaries / session checkpoints / sprint complete. Crash-recovery keys still write straight through.
+- **Conditional boot work** — clean-repo sessions skip the slow health-check / branch-reconciliation block (saves 8–30s per session).
+- **Cached reads** — TTL + source-mtime aware file cache; any writer's mtime advance forces a miss without explicit invalidate.
+- **Auto-inferred story DAG** — autopilot infers inter-story dependencies once after `bmad-sprint-planning` and writes `_Sprintpilot/sprints/dependencies.yaml` with an `# AUTO-INFERRED` marker. Hand-authored files are detected and respected silently.
+- **Parallel story dispatch** — when `parallel_stories: true` and the host supports it, layer-aware dispatch runs N stories concurrently in their own worktrees, then merges their state shards. Claude Code today; Gemini CLI experimentally.
+- **Cross-platform** — every workflow.md call site runs under bash, zsh, Git Bash, PowerShell, and cmd. Portable Node.js helpers replace POSIX-shell idioms.
+
 ## Quick Start
 
 ```bash
@@ -215,9 +241,12 @@ npx bmad-method install
 ```
 
 ```bash
-# 2. Install Sprintpilot (interactive — select your tool when prompted)
+# 2. Install Sprintpilot (interactive — select your tool and complexity profile when prompted)
 npx @ikunin/sprintpilot@latest
 
+# 2b. Or pick the profile non-interactively
+npx @ikunin/sprintpilot@latest install --tools claude-code --profile medium --yes
+
 # 3. Start the autopilot in your IDE
 /sprint-autopilot-on
 ```
@@ -298,6 +327,19 @@ All settings live in two YAML files — edit after install to customize behavior
 | `git.lock.stale_timeout_minutes` | `30` | Auto-remove orphaned lock files |
 | `git.worktree.cleanup_on_merge` | `true` | Delete worktrees after merge |
 
+### Autopilot (`_Sprintpilot/modules/autopilot/config.yaml`)
+
+| Setting | Default (medium) | Description |
+|---------|------------------|-------------|
+| `complexity_profile` | `medium` | One of `nano`, `small`, `medium`, `large`, `legacy`. Selects the per-story flow + which v2 layers are enabled. |
+| `autopilot.session_story_limit` | `3` (nano: `5`) | Stories per session before checkpoint. `0` = unlimited. |
+| `autopilot.retrospective_mode` | `auto` | `auto` (deterministic artifact) / `stop` (pause for `/bmad-retrospective`) / `skip`. |
+| `autopilot.auto_infer_dependencies` | `true` (nano + legacy: `false`) | Infer story DAG once after `bmad-sprint-planning`. Hand-authored sidecars (no `# AUTO-INFERRED` marker) are respected silently. |
+| `autopilot.phase_timings` | `true` (legacy: `false`) | Emit phase duration records via `log-timing.js mark`. |
+| `autopilot.coalesce_state_writes` | `true` (legacy: `false`) | Buffer non-critical state in `.pending/` shards. |
+| `autopilot.conditional_boot_work` | `true` (large + legacy: `false`) | Skip health-check / branch-reconciliation on clean repos. |
+| `autopilot.cache_shared_reads` | `true` (legacy: `false`) | TTL + mtime-aware file cache for hot reads. |
+
 ### Multi-Agent (`_Sprintpilot/modules/ma/config.yaml`)
 
 | Setting | Default | Description |
@@ -305,6 +347,11 @@ All settings live in two YAML files — edit after install to customize behavior
 | `multi_agent.enabled` | `true` | Enable parallel agent skills |
 | `multi_agent.max_parallel_research` | `3` | Concurrent research agents per batch |
 | `multi_agent.max_parallel_analysis` | `5` | Concurrent codebase analysis agents |
+| `ma.state_sharding` | `auto` (large: `always`) | `auto`, `always`, `never` — shards per-story state instead of contending on root YAMLs. |
+| `ma.parallel_stories` | `false` (large: `true`) | Dispatch independent stories from a DAG layer concurrently. Requires Claude Code (or Gemini CLI w/ experimental flag). |
+| `ma.max_parallel_stories` | `2` (large: `3`) | Cap on concurrent stories per layer. |
+| `ma.experimental_parallel_on_gemini` | `false` | Opt-in parallel dispatch under Gemini CLI (worktree-scoped subagents are still upstream). |
+| `ma.parallel_epics` | `false` | EXPERIMENTAL — cross-epic parallelism with merge-conflict preflight. Off on every profile by default. |
 
 See the [Configuration Reference](docs/CONFIGURATION.md) for the full list.
 

package/_Sprintpilot/Sprintpilot.md

@@ -31,8 +31,9 @@ Edit `_Sprintpilot/modules/autopilot/config.yaml`:
 
 | Setting | Default | Values | Purpose |
 |---------|---------|--------|---------|
-| `autopilot.session_story_limit` | `3` | integer ≥ 0 | Stories fully implemented per autopilot run before checkpoint. `0` = unlimited. |
+| `autopilot.session_story_limit` | `3` (nano: `5`) | integer ≥ 0 | Stories fully implemented per autopilot run before checkpoint. `0` = unlimited. Retuned in 2.0.1 after context-rot exposure on longer sessions; nano is cheaper per story so fits a higher cap. |
 | `autopilot.retrospective_mode` | `auto` | `auto` / `stop` / `skip` | How epic-end retrospectives are handled (see below). |
+| `autopilot.auto_infer_dependencies` | `true` (nano + legacy: `false`) | bool | 2.0.2 — autopilot session infers inter-story DAG once after `bmad-sprint-planning` and writes `_Sprintpilot/sprints/dependencies.yaml`. Hand-authored sidecars (no `# AUTO-INFERRED` marker) are detected and respected. See "Dependency Inference" below. |
 
 `retrospective_mode` options:
 - **`auto`** *(default)* — autopilot writes a deterministic retrospective artifact from `sprint-status.yaml` + `decision-log.yaml`, then continues. Single pass, no external skill call, safe under every CLI.
@@ -41,6 +42,18 @@ Edit `_Sprintpilot/modules/autopilot/config.yaml`:
 
 Both settings are prompted during `sprintpilot install` (interactive mode) with existing values as defaults, so reinstalls preserve your choices.
 
+### Dependency Inference
+
+After `bmad-sprint-planning` completes, the autopilot session reads `epics.md`, `architecture.md`, and `sprint-status.yaml` and emits a JSON dependency envelope. `_Sprintpilot/scripts/infer-dependencies.js` validates it (schema, unknown keys, self-deps, cross-epic edges, missing rationales, cycles) and writes `_Sprintpilot/sprints/dependencies.yaml` with an `# AUTO-INFERRED` marker header. The script never calls an LLM — the autopilot session is the inference caller.
+
+This unblocks parallel story dispatch (`parallel_stories: true` + `dispatch-layer.js`) without requiring users to discover and hand-author the sidecar. Hand-authored files (no marker) are respected silently. Failure modes (invalid JSON, validation errors) log and continue — `resolve-dag.js` falls back to its safe linear `ordering` strategy on dispatch.
+
+### Mandatory fresh-context finalize
+
+Independent of `session_story_limit`, the autopilot forces an extra session at end-of-sprint. When step 2 detects all stories are done, it writes `current_bmad_step = sprint-finalize-pending` to the state file and halts — it does **not** run step 10 (cleanup) in that session. The next `/sprint-autopilot-on` invocation reads the marker in step 1 and jumps directly to step 10 with a clean context window, where seven CRITICAL deterministic script calls run the cleanup (checkbox marking, worktree removal, lock release, artifact commit, sprint-complete state, verification, state-file delete).
+
+This behavior is not configurable: it's a mitigation for late-session instruction decay that was reliably dropping cleanup actions in long single-session runs. The extra session is short (typically ~60-100 turns, under $2). See `_Sprintpilot/skills/sprint-autopilot-on/workflow.md` step 2 and step 10 for the exact protocol.
+
 ---
 
 ## Full skill reference by lifecycle phase

package/_Sprintpilot/manifest.yaml

@@ -1,6 +1,6 @@
 addon:
   name: sprintpilot
-  version: 1.0.5
+  version: 2.0.5
   description: Sprintpilot — autopilot and multi-agent addon for BMad Method (git workflow, parallel agents, autonomous story execution)
   bmad_compatibility: ">=6.2.0"
   modules:

package/_Sprintpilot/modules/autopilot/config.yaml

@@ -2,6 +2,28 @@
 # Controls /sprint-autopilot-on session behavior.
 
 autopilot:
+  # Adaptive Process Scaling profile.
+  #
+  #   nano   — toy / tutorial / learning project, solo, small codebase.
+  #            Routes through bmad-quick-dev one-shot (PR 4+). Fastest.
+  #   small  — MVP / internal tool / prototype, solo or 1–2 devs.
+  #   medium — team product with real users. Default, recommended.
+  #   large  — production system, compliance / uptime stakes. Full
+  #            reconciliation, interactive retrospectives, tighter
+  #            checkpoints, parallelism on by default.
+  #   legacy — rollback to v1.0.5 behavior. No v2 optimizations active.
+  #            Pinned by version_pinned in profiles/legacy.yaml so future
+  #            changes cannot silently affect legacy users.
+  #
+  # Profile defaults live in _Sprintpilot/modules/autopilot/profiles/*.yaml.
+  # Override specific knobs here or in git/ma config.yaml — user overrides
+  # always win over profile defaults. See docs/adaptive-process-scaling.md.
+  #
+  # Missing key defaults to 'medium' (matches v1.0.5 behavior byte-for-byte).
+  # Upgrading v1 installs don't need to set this; new installs get it from
+  # the installer prompt or `sprintpilot install --profile <name>`.
+  complexity_profile: medium
+
   # Maximum stories to FULLY IMPLEMENT in a single autopilot session.
   #
   # "Fully implement" means the complete per-story cycle:

package/_Sprintpilot/modules/autopilot/profiles/_base.yaml

@@ -0,0 +1,45 @@
+# Adaptive Process Scaling — base defaults for all non-legacy profiles.
+# Per-profile YAML files override only the keys they want to change.
+# See docs/adaptive-process-scaling.md and docs/implementation-plan.md.
+
+name: _base
+version_pinned: null
+
+autopilot:
+  implementation_flow: full        # full | quick
+  # Proactive handoff threshold. Lowered from 5 → 3 because context rot
+  # (late-session instruction decay) caused the LLM to skip late-step
+  # actions in longer single-session runs. Keeping sessions short enough
+  # that every step 10 CRITICAL action fits comfortably inside the prompt
+  # budget is cheaper than paying for skipped cleanup actions.
+  session_story_limit: 3
+  retrospective_mode: auto
+  phase_timings: true              # M0, PR 2 — enabled by default (legacy overrides to false)
+  coalesce_state_writes: true      # M3, PR 6 — batch non-critical writes, flush at story boundary
+  conditional_boot_work: true      # M4, PR 7 — skip health-check + branch reconciliation on a clean repo
+  cache_shared_reads: true         # M5, PR 8 — memoize sprint-status / git-status / decision-log reads per loop iteration
+  # 2.0.2 — autopilot session infers inter-story DAG once after bmad-sprint-planning
+  # and writes _Sprintpilot/sprints/dependencies.yaml. Hand-authored sidecars
+  # (no AUTO-INFERRED marker) are detected and respected.
+  auto_infer_dependencies: true
+
+git:
+  granularity: story               # story | epic
+  worktree:
+    enabled: true
+  squash_on_merge: false
+
+ma:
+  parallel_stories: false
+  max_parallel_stories: 2
+  # PR 11 intra-epic parallelism safety rails. Honored by dispatch-layer.js
+  # when a host declares parallel support (see agent-adapter.js).
+  min_epic_duration_for_parallel_sec: 300
+  baseline_story_duration_sec: 180
+  max_consecutive_conflicts: 2
+  effective_parallel_floor: 1
+  parallel_epics: false
+  # PR 3: state_sharding semantics — auto = shard when parallelism is active,
+  # always = shard unconditionally (for forcing the code path in tests),
+  # never = write authoritative files directly (pre-PR behavior, rollback).
+  state_sharding: auto

package/_Sprintpilot/modules/autopilot/profiles/large.yaml

@@ -0,0 +1,22 @@
+# Large profile — production system, compliance / uptime stakes.
+# Parallelism on by default; full reconciliation every boot; tighter
+# session checkpointing; interactive retrospectives.
+
+name: large
+
+autopilot:
+  session_story_limit: 3
+  retrospective_mode: stop
+  conditional_boot_work: false     # always run full reconciliation
+
+ma:
+  parallel_stories: true
+  max_parallel_stories: 3
+  # PR 11 safety rails (inherited defaults via _base, overridden here).
+  max_consecutive_conflicts: 2
+  effective_parallel_floor: 1
+  # PR 12 cross-epic parallelism stays OFF even on large — experimental.
+  # Explicitly pinned (not inherited) so future _base changes can't silently
+  # flip it on for compliance-conscious users.
+  parallel_epics: false
+  state_sharding: always

package/_Sprintpilot/modules/autopilot/profiles/legacy.yaml

@@ -0,0 +1,35 @@
+# Legacy profile — rollback to pre-v2 (v1.0.5) behavior.
+#
+# Explicitly duplicates every setting that was default in v1.0.5 so future
+# changes to _base.yaml cannot silently affect legacy behavior. This is
+# the forward-compatibility guarantee: legacy produces a file-and-schema
+# superset match against the v1.0.5 snapshot.
+#
+# Unlike the other profile YAMLs, legacy does NOT extend _base. The
+# resolver detects version_pinned and skips the base overlay.
+
+name: legacy
+version_pinned: "v1.0.5"
+
+autopilot:
+  implementation_flow: full
+  session_story_limit: 3
+  retrospective_mode: auto
+  phase_timings: false
+  coalesce_state_writes: false
+  conditional_boot_work: false
+  cache_shared_reads: false
+  # Legacy is byte-for-byte v1.0.5; no v2 LLM calls.
+  auto_infer_dependencies: false
+
+git:
+  granularity: story
+  worktree:
+    enabled: true
+  squash_on_merge: false
+
+ma:
+  parallel_stories: false
+  max_parallel_stories: 2
+  parallel_epics: false
+  state_sharding: never

package/_Sprintpilot/modules/autopilot/profiles/medium.yaml

@@ -0,0 +1,5 @@
+# Medium profile — team product with real users (default).
+# Matches _base defaults. Parallelism is opt-in: edit ma/config.yaml
+# or run sprintpilot install --profile medium --parallel 2.
+
+name: medium

package/_Sprintpilot/modules/autopilot/profiles/nano.yaml

@@ -0,0 +1,35 @@
+# Nano profile — toy / tutorial / learning projects, solo.
+# Routes each story through bmad-quick-dev (one-shot Implement → Review
+# → Classify → Commit). Drops worktrees, per-story PRs, retrospectives,
+# and session checkpoints. Quality gates preserved via quick-dev's
+# internal review step.
+#
+# Behavior is gated on PR 4 (nano routing) landing. Until then this
+# profile is configurable but has no runtime effect.
+
+name: nano
+
+autopilot:
+  implementation_flow: quick
+  # Nano's quick-dev one-shot is cheaper per story, so nano can run longer
+  # sessions — but unlimited (0) runs into the same context-rot failure
+  # mode as the full flow. 5 stories per session keeps step 10's CRITICAL
+  # actions reliably in-context without paying for excessive session boots.
+  session_story_limit: 5
+  # Nano runs at epic granularity with parallelism off — auto-inferring a
+  # story DAG would just burn one LLM call per sprint and never get used.
+  auto_infer_dependencies: false
+  retrospective_mode: skip
+  # Nano safety net — if a story fails under quick-dev, escalate to the
+  # small profile for the remainder of the session (scope: session only,
+  # never written back to config.yaml).
+  nano:
+    fallback_on_tests_fail: true
+    fallback_on_quick_dev_high_severity: true
+    fallback_target: small
+
+git:
+  granularity: epic
+  worktree:
+    enabled: false
+  squash_on_merge: true

package/_Sprintpilot/modules/autopilot/profiles/small.yaml

@@ -0,0 +1,5 @@
+# Small profile — MVP / internal tool / prototype, solo or 1–2 devs.
+# Matches _base defaults; kept as a distinct file so --profile small
+# is always resolvable even if _base evolves.
+
+name: small

package/_Sprintpilot/modules/git/config.yaml

@@ -6,6 +6,14 @@ git:
   base_branch: main
   # Git status is tracked in git-status.yaml (Sprintpilot-owned), NOT sprint-status.yaml (BMad Method-owned)
 
+  # Branch + PR granularity.
+  #   story — one branch + one PR per story (default).
+  #   epic  — one branch + one PR per epic; stories committed on it.
+  #           Epic branch name: {branch_prefix}epic-{epic_id}.
+  #           Epic PR merges with --squash; the PR body lists each
+  #           story commit. Set on nano profile by default.
+  granularity: story
+
   # Branch naming
   branch_prefix: "story/" # prefix for story branches (e.g., story/1-2-user-auth)
   max_branch_length: 60 # truncate + 6-char hash if longer

package/_Sprintpilot/modules/ma/config.yaml

@@ -7,3 +7,45 @@ multi_agent:
   max_parallel_research: 3 # Max concurrent research agents per batch
   max_parallel_analysis: 5 # Max concurrent codebase analysis agents
   # session_story_limit NOT duplicated here — uses autopilot's single authoritative limit
+
+  # PR 11: intra-epic parallel story execution.
+  #   parallel_stories: true enables dispatch-layer.js on Claude Code;
+  #     other hosts silently fall back to sequential (per agent-adapter.js
+  #     detection — confidence high + supports_parallel true).
+  #   max_parallel_stories: cap on concurrent sub-agents per layer.
+  #   min_epic_duration_for_parallel_sec: skip parallelism for epics
+  #     whose estimated wall-clock is below this threshold (saves
+  #     dispatch overhead).
+  #   max_consecutive_conflicts: disable parallelism for the rest of the
+  #     session once N consecutive merge conflicts occur.
+  #   effective_parallel_floor: never drop below this mid-session even
+  #     after failure-driven concurrency reduction.
+  parallel_stories: false
+  max_parallel_stories: 2
+  min_epic_duration_for_parallel_sec: 300
+  baseline_story_duration_sec: 180
+  max_consecutive_conflicts: 2
+  effective_parallel_floor: 1
+
+  # EXPERIMENTAL: enable parallel_stories dispatch on Gemini CLI.
+  #
+  # Gemini CLI has a subagent primitive (invoke_subagent) but its
+  # worktree-scoped variant is not yet shipped upstream (tracker:
+  # github.com/google-gemini/gemini-cli#22967) and real-world parallelism
+  # reports serialization + quota throttling. Sprintpilot detects Gemini
+  # CLI via GEMINI_CLI=1 (env, HIGH confidence) or parent process `gemini`
+  # (MEDIUM), but supports_parallel stays false by default.
+  #
+  # Flip to true PER PROJECT once upstream worktree support lands (or to
+  # experiment at your own risk). Workflow logs an "experimental parallel"
+  # warning once per session when this is true AND host=gemini-cli.
+  experimental_parallel_on_gemini: false
+
+  # PR 12 — cross-epic parallelism (EXPERIMENTAL).
+  # Off by default on ALL profiles including large. Enabling requires:
+  #   1. Both epics carry `independent: true` in dependencies.yaml.
+  #   2. preflight-merge.js reports no conflicts between them.
+  #   3. max_parallel_epics is hardcoded at 2 — no tuning knob.
+  # A single cross-epic merge conflict in a session disables parallel_epics
+  # for the rest of the session.
+  parallel_epics: false

package/_Sprintpilot/scripts/agent-adapter.js

@@ -0,0 +1,247 @@
+#!/usr/bin/env node
+
+// agent-adapter.js — detect the host coding agent currently running the
+// Sprintpilot workflow. Output informs whether parallel sub-agent
+// dispatch (PR 11) is safe.
+//
+// Usage:
+//   agent-adapter.js detect [--project-root <path>]
+//
+// Output (stdout, JSON):
+//   {
+//     "host": "claude-code" | "cursor" | "windsurf" | "aider" | "cline"
+//           | "roo" | "trae" | "kiro" | "copilot" | "unknown",
+//     "supports_parallel": boolean,
+//     "detection_reason": string,
+//     "confidence": "high" | "medium" | "low"
+//   }
+//
+// Detection priority (first match wins):
+//   1. Env vars set by the running host           → HIGH confidence
+//   2. Parent process name                        → MEDIUM confidence
+//   3. Filesystem install markers                 → LOW confidence
+//
+// Tautology guard (concept §M13): filesystem markers prove the INSTALL
+// target, not the CURRENT host. confidence=low forces supports_parallel
+// = false regardless of which host the markers suggest.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+
+const { parseArgs } = require('../lib/runtime/args');
+const log = require('../lib/runtime/log');
+
+// Host capability table. supports_parallel is true only for hosts with
+// a first-class multi-agent API that Sprintpilot's dispatch-layer.js
+// can reliably drive — which today means worktree-scoped sub-agents
+// with parallel fan-out. Claude Code is the only host that meets both
+// bars at the time of writing. Gemini CLI has a subagent primitive
+// (invoke_subagent) but its worktree-scoped variant is still open
+// upstream (github.com/google-gemini/gemini-cli#22967) and real-world
+// parallelism reports serialization + quota throttling (#25534); hence
+// supports_parallel=false by default, with an experimental opt-in via
+// `ma.experimental_parallel_on_gemini: true` handled at workflow level.
+const HOSTS = {
+  'claude-code': { supports_parallel: true },
+  'gemini-cli': { supports_parallel: false, subagents: 'experimental' },
+  cursor: { supports_parallel: false },
+  windsurf: { supports_parallel: false },
+  aider: { supports_parallel: false },
+  cline: { supports_parallel: false },
+  roo: { supports_parallel: false },
+  trae: { supports_parallel: false },
+  kiro: { supports_parallel: false },
+  copilot: { supports_parallel: false },
+  unknown: { supports_parallel: false },
+};
+
+const ENV_DETECTORS = [
+  { host: 'claude-code', match: (env) => env.CLAUDECODE === '1' || !!env.CLAUDE_CODE_SESSION_ID },
+  // Gemini CLI sets GEMINI_CLI=1 for every subprocess it spawns
+  // (docs/tools/shell.md + docs/reference/commands.md as of v0.33.x).
+  { host: 'gemini-cli', match: (env) => env.GEMINI_CLI === '1' || !!env.GEMINI_CLI_SURFACE },
+  { host: 'cursor', match: (env) => !!env.CURSOR_SESSION_ID || !!env.CURSOR_TRACE_ID },
+  { host: 'windsurf', match: (env) => !!env.WINDSURF_SESSION },
+  { host: 'aider', match: (env) => !!env.AIDER_SESSION || !!env.AIDER_HISTORY_FILE },
+  { host: 'cline', match: (env) => !!env.CLINE_SESSION || !!env.CLINE_CONFIG },
+];
+
+const PARENT_DETECTORS = [
+  { host: 'claude-code', parent: 'claude' },
+  { host: 'gemini-cli', parent: 'gemini' },
+  { host: 'cursor', parent: 'cursor-agent' },
+  { host: 'aider', parent: 'aider' },
+];
+
+function help() {
+  log.out('Usage: agent-adapter.js detect [--project-root <path>]');
+}
+
+function detectFromEnv(env) {
+  for (const d of ENV_DETECTORS) {
+    if (d.match(env)) {
+      return { host: d.host, confidence: 'high', detection_reason: `env var set (${d.host})` };
+    }
+  }
+  return null;
+}
+
+// Parsers extracted as pure functions so the platform branches stay
+// unit-testable on any OS. Each takes the raw stdout from the platform
+// command and returns the basename or null. Negative test cases
+// (empty input, "INFO: No tasks…", malformed lines) covered by tests.
+
+/** Parse `ps -p <pid> -o comm=` output (POSIX). */
+function parsePsOutput(raw) {
+  if (!raw) return null;
+  const trimmed = raw.trim();
+  if (!trimmed) return null;
+  return path.basename(trimmed.split(/\s+/)[0]);
+}
+
+/**
+ * Parse `tasklist /FO CSV /NH` output (Windows). Strips `.exe` so the
+ * basename matches the POSIX path (so PARENT_DETECTORS only needs the
+ * non-extension name once).
+ *   Sample row: "claude.exe","12345","Console","1","123,456 K"
+ */
+function parseTasklistOutput(raw) {
+  if (!raw) return null;
+  const trimmed = raw.trim();
+  if (!trimmed || /^INFO:/i.test(trimmed)) return null; // "INFO: No tasks…"
+  const m = trimmed.match(/^"([^"]+)"/);
+  if (!m) return null;
+  return path.basename(m[1]).replace(/\.exe$/i, '');
+}
+
+function parentProcessName() {
+  try {
+    const pid = process.ppid;
+    if (process.platform === 'win32') {
+      const res = spawnSync(
+        'tasklist',
+        ['/FI', `PID eq ${pid}`, '/FO', 'CSV', '/NH'],
+        { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] },
+      );
+      if (res.status !== 0) return null;
+      return parseTasklistOutput(res.stdout || '');
+    }
+    // POSIX: macOS and Linux both support `ps -p <pid> -o comm=`.
+    const res = spawnSync('ps', ['-p', String(pid), '-o', 'comm='], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    if (res.status !== 0) return null;
+    return parsePsOutput(res.stdout || '');
+  } catch {
+    return null;
+  }
+}
+
+function detectFromParent() {
+  const parent = parentProcessName();
+  if (!parent) return null;
+  for (const d of PARENT_DETECTORS) {
+    if (parent === d.parent) {
+      return {
+        host: d.host,
+        confidence: 'medium',
+        detection_reason: `parent process '${parent}'`,
+      };
+    }
+  }
+  return null;
+}
+
+function detectFromFilesystem(projectRoot) {
+  const markers = [
+    { path: path.join(projectRoot, '.claude', 'skills'), host: 'claude-code' },
+    { path: path.join(projectRoot, '.claude-code'), host: 'claude-code' },
+    { path: path.join(projectRoot, '.cursor'), host: 'cursor' },
+    { path: path.join(projectRoot, '.windsurf'), host: 'windsurf' },
+    { path: path.join(projectRoot, '.aider.conf.yml'), host: 'aider' },
+    { path: path.join(projectRoot, '.cline'), host: 'cline' },
+  ];
+  for (const m of markers) {
+    if (fs.existsSync(m.path)) {
+      return {
+        host: m.host,
+        confidence: 'low',
+        detection_reason: `filesystem marker '${path.relative(projectRoot, m.path)}' — NOT proof of current host`,
+      };
+    }
+  }
+  return null;
+}
+
+function detect({ env = process.env, projectRoot = process.cwd() } = {}) {
+  const fromEnv = detectFromEnv(env);
+  if (fromEnv) {
+    const caps = HOSTS[fromEnv.host] || HOSTS.unknown;
+    return {
+      host: fromEnv.host,
+      supports_parallel: caps.supports_parallel,
+      detection_reason: fromEnv.detection_reason,
+      confidence: 'high',
+    };
+  }
+  const fromParent = detectFromParent();
+  if (fromParent) {
+    const caps = HOSTS[fromParent.host] || HOSTS.unknown;
+    return {
+      host: fromParent.host,
+      supports_parallel: caps.supports_parallel,
+      detection_reason: fromParent.detection_reason,
+      confidence: 'medium',
+    };
+  }
+  const fromFs = detectFromFilesystem(projectRoot);
+  if (fromFs) {
+    // Tautology guard: filesystem markers never enable parallel.
+    return {
+      host: fromFs.host,
+      supports_parallel: false,
+      detection_reason: fromFs.detection_reason,
+      confidence: 'low',
+    };
+  }
+  return {
+    host: 'unknown',
+    supports_parallel: false,
+    detection_reason: 'no env/parent/filesystem signal',
+    confidence: 'low',
+  };
+}
+
+function main() {
+  const { opts, positional } = parseArgs(process.argv.slice(2));
+  if (opts.help || positional.length === 0) {
+    help();
+    process.exit(opts.help ? 0 : 1);
+  }
+  const action = positional[0];
+  if (action !== 'detect') {
+    log.error(`unknown action '${action}'. Valid: detect`);
+    process.exit(1);
+  }
+  const projectRoot = opts['project-root'] || process.cwd();
+  const result = detect({ env: process.env, projectRoot });
+  process.stdout.write(`${JSON.stringify(result)}\n`);
+}
+
+module.exports = {
+  HOSTS,
+  ENV_DETECTORS,
+  PARENT_DETECTORS,
+  detectFromEnv,
+  detectFromParent,
+  detectFromFilesystem,
+  detect,
+  parsePsOutput,
+  parseTasklistOutput,
+};
+
+if (require.main === module) {
+  main();
+}