@ikunin/sprintpilot 1.0.3 → 1.0.4

package/_Sprintpilot/Sprintpilot.md

@@ -25,6 +25,22 @@ When Sprintpilot or the git addon is active:
 - Each story gets its own isolated worktree and branch (`story/<key>`)
 - Commits use conventional format: `feat(<epic>): <title> (<key>)`
 
+### Autopilot configuration
+
+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.retrospective_mode` | `auto` | `auto` / `stop` / `skip` | How epic-end retrospectives are handled (see 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.
+- **`stop`** — autopilot pauses at epic completion. Run `/bmad-retrospective` interactively, then re-run `/sprint-autopilot-on` to resume. Use this when you want the full multi-persona discussion as part of your process.
+- **`skip`** — no retrospective artifact is written. **Not recommended** — you lose the epic-level learning record.
+
+Both settings are prompted during `sprintpilot install` (interactive mode) with existing values as defaults, so reinstalls preserve your choices.
+
 ---
 
 ## Full skill reference by lifecycle phase
@@ -59,7 +75,7 @@ See **Mandatory sequence per story** section below.
 
 | Skill | When to use |
 |-------|-------------|
-| `bmad-retrospective` | Run after all stories in an epic are `done`; saves lessons, marks epic `done` |
+| `bmad-retrospective` | Run after all stories in an epic are `done`; saves lessons, marks epic `done`. Under autopilot this is driven by `autopilot.retrospective_mode` (`auto` inline, `stop` to pause for interactive use, or `skip`). |
 
 ---
 

package/_Sprintpilot/manifest.yaml

@@ -1,6 +1,6 @@
 addon:
   name: sprintpilot
-  version: 1.0.3
+  version: 1.0.4
   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

@@ -18,3 +18,21 @@ autopilot:
   #
   # Set 0 to disable the limit and run until the sprint is complete.
   session_story_limit: 3
+
+  # Retrospective handling at epic completion.
+  #
+  # - "auto" (default): autopilot generates a deterministic retrospective
+  #   from sprint-status.yaml + decision-log.yaml, then continues with the
+  #   next epic. Safe under every CLI including Gemini CLI — no external
+  #   skill call, no persona simulation, single pass.
+  # - "stop": autopilot pauses at epic completion so you can run
+  #   /bmad-retrospective interactively. Re-run /sprint-autopilot-on to
+  #   resume with the next epic.
+  # - "skip": autopilot skips the retrospective entirely and continues.
+  #   NOT RECOMMENDED — you lose the epic-level learning record.
+  #
+  # Background: the external bmad-retrospective skill can enter a
+  # multi-persona discussion loop when driven by autopilot on some CLIs,
+  # which exhausts the token/memory budget. That's why "auto" generates
+  # the artifact inline instead of invoking the external skill.
+  retrospective_mode: auto

package/_Sprintpilot/skills/sprint-autopilot-on/workflow.md

@@ -138,6 +138,7 @@ All BMAD skills are fully automatable (auto-continue past menus, derive decision
 | `bmad-create-ux-design` | Automatable if PRD exists; BLOCKER if no PRD |
 | `bmad-party-mode` | Skip — inherently interactive |
 | `bmad-brainstorming` | Skip — inherently interactive |
+| `bmad-retrospective` | Under autopilot, handled per `autopilot.retrospective_mode`: `auto` (default — inline artifact, no external skill call), `stop` (pause so user runs `/bmad-retrospective` interactively, then resumes autopilot), or `skip` (not recommended). The external skill is NOT invoked from autopilot because it enters a multi-persona discussion loop under some CLIs. |
 
 ---
 
@@ -173,13 +174,15 @@ Resolve:
   </action>
   <action>Read `{project-root}/_Sprintpilot/modules/autopilot/config.yaml` (if present) and set:
   - `{{session_story_limit}}` from `autopilot.session_story_limit` (default: 3). A value of 0 disables the limit (run until sprint complete).
-  If the file or key is missing, fall back to 3.
+  - `{{retrospective_mode}}` from `autopilot.retrospective_mode` (default: `auto`). Valid values: `auto` | `stop` | `skip`. Any unknown value falls back to `auto`.
+  If the file or either key is missing, fall back to the defaults above.
   </action>
 </check>
 
 <check if="manifest does NOT exist">
   <action>Set `{{git_enabled}}` = false</action>
   <action>Set `{{session_story_limit}}` = 3</action>
+  <action>Set `{{retrospective_mode}}` = `auto`</action>
   <action>Log: "No _Sprintpilot/manifest.yaml found — running stock autopilot (no git)"</action>
 </check>
 
@@ -315,6 +318,34 @@ Resolve:
       - Advance to next non-done story
     - Update `{state_file}` with reconciled values
   </action>
+
+  <!-- Resume from a `retrospective_mode: stop` pause.
+       The user was told to run /bmad-retrospective interactively. If they
+       did, the epic is now `done` in {status_file} (or a retrospective
+       artifact exists). Otherwise, re-issue the instructions and halt. -->
+  <check if="{state_file}.paused_at is epic-complete-awaiting-retrospective">
+    <action>Set `{{paused_epic_id}}` from `{state_file}.paused_epic_id`</action>
+    <action>Check whether epic `{{paused_epic_id}}` is now `done` in `{status_file}` OR an artifact exists at `{implementation_artifacts}/retrospectives/epic-{{paused_epic_id}}-*.md`</action>
+    <check if="epic is done OR retrospective artifact exists">
+      <action>Clear `paused_at`, `paused_epic_id`, and `next_action` from `{state_file}`</action>
+      <action>Log: "Epic {{paused_epic_id}} retrospective detected — resuming autopilot"</action>
+    </check>
+    <check if="epic is NOT done AND no retrospective artifact">
+      <action>Report:
+      ```
+      Autopilot still paused — epic {{paused_epic_id}} retrospective not yet done.
+
+      Run `/bmad-retrospective` interactively for epic {{paused_epic_id}},
+      then re-run `/sprint-autopilot-on` to continue.
+
+      (To bypass, edit _Sprintpilot/modules/autopilot/config.yaml and set
+      retrospective_mode to `auto` or `skip`.)
+      ```
+      </action>
+      <action>STOP</action>
+    </check>
+  </check>
+
   <goto step="2">Jump to execution loop with reconciled state</goto>
 </check>
 
@@ -369,6 +400,7 @@ Resolve:
   Git integration: {{git_enabled}}
   Platform: {{platform}}
   Session limit: {{session_story_limit}} stories, then checkpoint + new session
+  Retrospective mode: {{retrospective_mode}}
 
   Beginning autonomous execution. I will only stop for true blockers or session checkpoints.
   ```
@@ -586,8 +618,12 @@ pr_base: {{pr_base}}
   <goto step="7">Mark story done</goto>
 </check>
 
-<check if="{{completed_skill}} was bmad-retrospective">
-  <action>Log: "Epic retrospective complete — BMAD skills will update sprint-status.yaml directly"</action>
+<check if="{{completed_skill}} is retrospective-auto">
+  <action>Log: "Epic retrospective generated inline by autopilot — sprint-status.yaml updated"</action>
+</check>
+
+<check if="{{completed_skill}} is retrospective-skip">
+  <action>Log: "Epic retrospective skipped per config — sprint-status.yaml updated inline"</action>
 </check>
 
 <check if="{{completed_skill}} was bmad-create-epics-and-stories">
@@ -858,10 +894,111 @@ Instruct: "Re-verify code review for story {{current_story}} — all patch findi
 
 <action>Check if ALL stories in this epic are `done`</action>
 <check if="epic complete">
-  <action>Create task "[epic] retrospective" → `in_progress`</action>
-  <action>INVOKE `bmad-retrospective` using Skill tool (retrospective skill updates sprint-status.yaml itself)</action>
-  <action>Mark retrospective task → `completed`</action>
-  <action>Set `{{completed_skill}}` = `bmad-retrospective`</action>
+  <action>Resolve `{{epic_id}}` (e.g. "1") and `{{epic_title}}` from `{status_file}` for the current epic</action>
+  <action>Create task "[epic {{epic_id}}] retrospective" → `in_progress`</action>
+
+  <!-- Retrospective handling is driven by `autopilot.retrospective_mode`
+       in modules/autopilot/config.yaml. See the SKILL AUTOMATABLE REFERENCE
+       table for rationale. The external `bmad-retrospective` skill is
+       NEVER invoked from autopilot — it enters a multi-persona discussion
+       loop under some CLIs. -->
+
+  <check if="{{retrospective_mode}} is auto">
+    <!-- Deterministic single-pass retrospective. No persona simulation,
+         no rounds, no external skill call. All inputs are on-disk. -->
+    <action>Collect from `{status_file}` for epic `{{epic_id}}`:
+      - list of done stories with { story-key, title, test_pass_count, patch_count }
+      - epic title, start/end dates if present
+    </action>
+    <action>Collect decision-log entries for epic `{{epic_id}}` from `{decision_log_file}` (match on `story` prefix `{{epic_id}}-` or `phase: autopilot:*` entries tagged to this epic)</action>
+    <action>Identify open risks / carry-over notes from sprint-status (any story with `notes` or `risks` fields, any `workaround` decisions in the log for this epic)</action>
+    <action>Ensure directory `{implementation_artifacts}/retrospectives/` exists</action>
+    <action>Write `{implementation_artifacts}/retrospectives/epic-{{epic_id}}-retrospective.md` using this template:
+    ```markdown
+    # Epic {{epic_id}} — {{epic_title}} — Retrospective
+
+    **Completed:** {current_date}
+    **Stories done:** {{n_done}}/{{n_total}}
+
+    ## Stories
+    {{#each stories}}
+    - **{{story-key}}** — {{title}}
+      - Tests: {{test_pass_count}}
+      - Patches applied: {{patch_count}}
+    {{/each}}
+
+    ## Key decisions
+    {{#each decisions}}
+    - [{{impact}}] {{category}}: {{decision}} — {{rationale}}
+    {{/each}}
+
+    ## Risks carried forward
+    {{#each open_risks}}
+    - {{risk}}
+    {{/each}}
+
+    ## Notes
+    Generated inline by Sprintpilot autopilot per `autopilot.retrospective_mode: auto`.
+    ```
+    </action>
+    <action>Update `{status_file}`:
+      - `epics.{{epic_id}}.status` = `done`
+      - `epics.{{epic_id}}.retrospective_path` = the retrospective file path (relative to project root)
+      - `epics.{{epic_id}}.completed_at` = {current_date}
+    </action>
+    <action>Append decision-log entry:
+      `{ category: workaround, decision: "retrospective generated inline", rationale: "autopilot.retrospective_mode=auto — avoids external skill's multi-persona loop", impact: low, phase: autopilot:retrospective, story: "epic-{{epic_id}}" }`
+    </action>
+    <action>Mark retrospective task → `completed`</action>
+    <action>Set `{{completed_skill}}` = `retrospective-auto`</action>
+  </check>
+
+  <check if="{{retrospective_mode}} is stop">
+    <!-- Pause autopilot so user can run /bmad-retrospective interactively.
+         On the next /sprint-autopilot-on the resume logic in step 1 will
+         detect the cleared state and move to the next epic. -->
+    <action>Update `{state_file}`:
+      - `paused_at` = `epic-complete-awaiting-retrospective`
+      - `paused_epic_id` = `{{epic_id}}`
+      - `next_action` = "run /bmad-retrospective interactively for epic {{epic_id}}, then re-run /sprint-autopilot-on"
+    </action>
+    <action>Append decision-log entry:
+      `{ category: workaround, decision: "paused for interactive retrospective", rationale: "autopilot.retrospective_mode=stop", impact: low, phase: autopilot:retrospective, story: "epic-{{epic_id}}" }`
+    </action>
+    <action>Mark retrospective task → `completed` (handed off to user)</action>
+    <action>Report:
+    ```
+    Autopilot paused — epic {{epic_id}} complete, retrospective handed off.
+
+    Per `autopilot.retrospective_mode: stop` in
+    _Sprintpilot/modules/autopilot/config.yaml, autopilot does not run the
+    retrospective automatically.
+
+    To continue:
+      1. Run `/bmad-retrospective` interactively for epic {{epic_id}}
+      2. When done, run `/sprint-autopilot-on` to resume with the next epic
+
+    State saved to: {state_file}
+    ```
+    </action>
+    <action>STOP</action>
+  </check>
+
+  <check if="{{retrospective_mode}} is skip">
+    <!-- User opted out of retrospective. Record and move on. -->
+    <action>Update `{status_file}`:
+      - `epics.{{epic_id}}.status` = `done`
+      - `epics.{{epic_id}}.retrospective_path` = null
+      - `epics.{{epic_id}}.retrospective_skipped` = true
+      - `epics.{{epic_id}}.completed_at` = {current_date}
+    </action>
+    <action>Append decision-log entry:
+      `{ category: workaround, decision: "retrospective skipped", rationale: "autopilot.retrospective_mode=skip (NOT RECOMMENDED)", impact: medium, phase: autopilot:retrospective, story: "epic-{{epic_id}}" }`
+    </action>
+    <action>Mark retrospective task → `completed` (skipped)</action>
+    <action>Set `{{completed_skill}}` = `retrospective-skip`</action>
+    <action>Log: "Epic {{epic_id}} retrospective skipped per config — continuing with next epic"</action>
+  </check>
 
   <!-- GIT: Epic completion — suggest merge, cleanup worktrees -->
   <check if="{{git_enabled}}">

package/lib/commands/install.js

@@ -64,6 +64,9 @@ const { V1_ADDON_DIR_NAME, V1_SKILL_NAMES, detectV1Installation } = require('../
 
 const ADDON_DIR = path.resolve(__dirname, '..', '..', '_Sprintpilot');
 const PROJECT_ADDON_DIR_NAME = '_Sprintpilot';
+const DEFAULT_SESSION_STORY_LIMIT = 3;
+const DEFAULT_RETROSPECTIVE_MODE = 'auto';
+const RETROSPECTIVE_MODES = ['auto', 'stop', 'skip'];
 const RUNTIME_RESOURCES = [
   'Sprintpilot.md',
   'manifest.yaml',
@@ -603,6 +606,211 @@ async function evictV1Installation(projectRoot, { dryRun, migrateV1, yes }) {
   return { migrated: true, moduleConfigSnapshot: snapshot };
 }
 
+// Parse the user's existing autopilot config (if any) so interactive prompts
+// can default to the current values AND so a v1 migration's patcher run
+// preserves user-edited values rather than overwriting them with bundled
+// defaults.
+//
+// Checks both locations, in order of precedence:
+//   1. `_Sprintpilot/modules/autopilot/config.yaml`  — normal upgrade
+//   2. `_bmad-addons/modules/autopilot/config.yaml`  — v1 legacy (bmad-
+//      autopilot-addon), picked up BEFORE evictV1Installation moves it
+//
+// Regex-based so we don't add a YAML parser dep for two scalar fields.
+// Unrecognized / unreadable files fall back to bundled defaults.
+async function readExistingAutopilotConfig(projectRoot, v1Snapshot) {
+  const out = { sessionStoryLimit: null, retrospectiveMode: null };
+  let raw = null;
+
+  // Precedence order:
+  //   1. `_Sprintpilot/modules/autopilot/config.yaml`  — normal upgrade
+  //   2. `_bmad-addons/modules/autopilot/config.yaml`  — v1 legacy still
+  //      on disk (install was invoked before evictV1Installation ran)
+  //   3. v1 in-memory snapshot                         — v1 legacy already
+  //      evicted; evictV1Installation captured the buffer before removing
+  //      the directory, so we extract the autopilot/config.yaml bytes
+  //      from there. Without this the patcher would overwrite the user's
+  //      v1-preserved values with bundled defaults.
+  const candidates = [
+    path.join(projectRoot, PROJECT_ADDON_DIR_NAME, 'modules', 'autopilot', 'config.yaml'),
+    path.join(projectRoot, V1_ADDON_DIR_NAME, 'modules', 'autopilot', 'config.yaml'),
+  ];
+  for (const file of candidates) {
+    if (!(await fs.pathExists(file))) continue;
+    try {
+      raw = await fs.readFile(file, 'utf8');
+      break;
+    } catch {
+      /* try next candidate */
+    }
+  }
+
+  if (raw == null && v1Snapshot && Array.isArray(v1Snapshot.autopilot)) {
+    const entry = v1Snapshot.autopilot.find((f) => f.relPath === 'config.yaml');
+    if (entry && Buffer.isBuffer(entry.buffer)) {
+      try {
+        raw = entry.buffer.toString('utf8');
+      } catch {
+        /* unreadable — fall back to defaults */
+      }
+    }
+  }
+
+  if (raw == null) return out;
+
+  // Both patterns tolerate a trailing `# comment` tail so users can annotate
+  // their config without breaking upgrade detection (e.g.
+  // `retrospective_mode: stop  # we want manual retros`). `[ \t]` rather
+  // than `\s` inside each line so matches never cross a newline.
+  const commentTail = /[ \t]*(?:#.*)?$/.source;
+
+  // `session_story_limit: 3`  — unquoted integer, optional trailing comment
+  const limitMatch = raw.match(
+    new RegExp(`^[ \\t]*session_story_limit:[ \\t]*(\\d+)${commentTail}`, 'm'),
+  );
+  if (limitMatch) {
+    const n = Number.parseInt(limitMatch[1], 10);
+    if (Number.isFinite(n) && n >= 0) out.sessionStoryLimit = n;
+  }
+  // `retrospective_mode: auto` — unquoted or single/double-quoted string,
+  // optional trailing comment
+  const modeMatch = raw.match(
+    new RegExp(`^[ \\t]*retrospective_mode:[ \\t]*["']?([a-zA-Z_-]+)["']?${commentTail}`, 'm'),
+  );
+  if (modeMatch && RETROSPECTIVE_MODES.includes(modeMatch[1])) {
+    out.retrospectiveMode = modeMatch[1];
+  }
+  return out;
+}
+
+// Rewrite the `session_story_limit:` and `retrospective_mode:` scalar lines
+// in the freshly-copied autopilot/config.yaml with the user's chosen values.
+// Done as a line-level string replacement instead of a token-substitution
+// because workflow.md uses the `{{session_story_limit}}` / `{{retrospective_mode}}`
+// variable-reference syntax — threading these keys through `renderString`
+// would match the inner `{key}` inside `{{key}}` and corrupt the workflow
+// variables to literal `{value}` strings.
+//
+// Handles three shapes for each key:
+//   1. line present with a value    → in-place replace (preserves trailing comment)
+//   2. line present with no value   → in-place fill
+//   3. line missing                 → append to the `autopilot:` block
+// (3) is the path that catches v1 (bmad-autopilot-addon) migrations whose
+// legacy config predates `retrospective_mode` — without it, the user's
+// prompted choice would be silently dropped.
+function applyScalar(source, key, value) {
+  // Structure of a YAML scalar line we support:
+  //   [indent][key]:[space(s)][value][space(s) + # comment]?
+  //
+  // Groups, non-greedy on value so the trailing-comment capture wins:
+  //   indent  — leading whitespace (preserved verbatim)
+  //   value   — `\S[^#\n]*?` — starts non-ws, stops as early as possible so
+  //             the comment tail can match. Optional, so this also matches
+  //             "key:\n" (no value at all) — P1-C.
+  //   tail    — `\s*#.*` — the whitespace-before-# is INSIDE the tail capture
+  //             so the original spacing ("value  # note") round-trips
+  //             instead of collapsing to a single space.
+  // Using [ \t] instead of \s everywhere INSIDE the line so the match
+  // cannot cross a newline — `\s*` would greedily consume the trailing
+  // `\n` after "key:" on an empty-value line, breaking the rewrite.
+  const replaceRe = new RegExp(`^([ \\t]*)${key}:[ \\t]*(\\S[^#\\n]*?)?([ \\t]*#.*)?$`, 'm');
+  if (replaceRe.test(source)) {
+    return source.replace(replaceRe, (_m, indent, _oldValue, tail) => {
+      return `${indent}${key}: ${value}${tail || ''}`;
+    });
+  }
+
+  // Key is absent. Append under the `autopilot:` block at the file's end.
+  // The bundled shipping config always starts with `autopilot:` at column
+  // 0 and indents children two spaces — match that style. If the file has
+  // no `autopilot:` header at all (hand-edited to a different shape), bail
+  // rather than guess.
+  if (!/^autopilot:\s*$/m.test(source)) return source;
+  const trimmed = source.endsWith('\n') ? source : `${source}\n`;
+  return `${trimmed}  ${key}: ${value}\n`;
+}
+
+async function patchAutopilotConfig(projectRoot, { sessionStoryLimit, retrospectiveMode }) {
+  const file = path.join(
+    projectRoot,
+    PROJECT_ADDON_DIR_NAME,
+    'modules',
+    'autopilot',
+    'config.yaml',
+  );
+  if (!(await fs.pathExists(file))) return;
+  const original = await fs.readFile(file, 'utf8');
+  let updated = applyScalar(original, 'session_story_limit', sessionStoryLimit);
+  updated = applyScalar(updated, 'retrospective_mode', retrospectiveMode);
+  if (updated !== original) {
+    await writeAtomic(file, updated);
+  }
+}
+
+async function resolveAutopilotSettings({ projectRoot, yes, dryRun, v1Snapshot }) {
+  const existing = await readExistingAutopilotConfig(projectRoot, v1Snapshot);
+  const defaultLimit = existing.sessionStoryLimit ?? DEFAULT_SESSION_STORY_LIMIT;
+  const defaultMode = existing.retrospectiveMode ?? DEFAULT_RETROSPECTIVE_MODE;
+
+  if (yes) {
+    if (existing.sessionStoryLimit != null || existing.retrospectiveMode != null) {
+      console.log(
+        pc.dim(
+          `Preserving autopilot config: session_story_limit=${defaultLimit}, retrospective_mode=${defaultMode}`,
+        ),
+      );
+    }
+    return { sessionStoryLimit: defaultLimit, retrospectiveMode: defaultMode };
+  }
+
+  if (dryRun) {
+    console.log(
+      pc.dim(
+        `[DRY RUN] Would prompt for autopilot config (current: session_story_limit=${defaultLimit}, retrospective_mode=${defaultMode})`,
+      ),
+    );
+    return { sessionStoryLimit: defaultLimit, retrospectiveMode: defaultMode };
+  }
+
+  const limitRaw = await prompts.text({
+    message: 'Autopilot: stories to fully implement per session (0 = unlimited)',
+    initialValue: String(defaultLimit),
+    validate(value) {
+      if (value == null || value === '') return undefined;
+      const n = Number.parseInt(value, 10);
+      if (!Number.isFinite(n) || String(n) !== String(value).trim() || n < 0) {
+        return 'Enter a non-negative integer (0 = unlimited)';
+      }
+      return undefined;
+    },
+  });
+  const sessionStoryLimit =
+    limitRaw == null || String(limitRaw).trim() === ''
+      ? defaultLimit
+      : Number.parseInt(String(limitRaw).trim(), 10);
+
+  const retrospectiveMode = await prompts.select({
+    message: 'Autopilot: retrospective handling at epic completion',
+    options: [
+      {
+        value: 'auto',
+        label: 'Auto — autopilot generates retrospective inline and continues (recommended)',
+      },
+      {
+        value: 'stop',
+        label: 'Stop — pause autopilot so you can run /bmad-retrospective manually',
+      },
+      {
+        value: 'skip',
+        label: 'Skip — do not generate a retrospective (NOT RECOMMENDED)',
+      },
+    ],
+    initialValue: defaultMode,
+  });
+
+  return { sessionStoryLimit, retrospectiveMode };
+}
+
 async function runInteractiveToolPicker(detected) {
   const options = ALL_TOOLS.map((tool) => ({
     value: tool,
@@ -665,12 +873,24 @@ async function runInstall(options = {}) {
 
   // 2. Resolve output_folder
   const outputFolder = await readOutputFolder(projectRoot);
-  const ctx = buildContext({ outputFolder });
   if (outputFolder !== '_bmad-output') {
     console.log(pc.dim(`Using output_folder: ${outputFolder}`));
     console.log('');
   }
 
+  // 2a. Autopilot configuration (prompt or preserve existing values).
+  // These values are patched into modules/autopilot/config.yaml AFTER the
+  // runtime copy — they're NOT threaded through `renderString`, because
+  // workflow.md's `{{session_story_limit}}` / `{{retrospective_mode}}`
+  // variable references would collide with single-brace token matching.
+  const { sessionStoryLimit, retrospectiveMode } = await resolveAutopilotSettings({
+    projectRoot,
+    yes,
+    dryRun,
+    v1Snapshot: v1ConfigSnapshot,
+  });
+  const ctx = buildContext({ outputFolder });
+
   // 3. Detect + select tools
   const detected = await detectInstalledTools(projectRoot);
 
@@ -888,6 +1108,12 @@ async function runInstall(options = {}) {
     // .sprintpilot-v1-snapshot*.json were added up-front in
     // evictV1Installation (step 0) so they're in place even if the
     // module-snapshot branch never runs.
+
+    // 6b. Apply the resolved autopilot settings. Runs AFTER step 6 (which
+    //     wrote the bundled default config) AND after the v1 snapshot
+    //     reapply (which might have restored an older config.yaml without
+    //     `retrospective_mode`). The user's prompted values always win.
+    await patchAutopilotConfig(projectRoot, { sessionStoryLimit, retrospectiveMode });
   }
 
   // 7. Verify git check-ignore
@@ -936,8 +1162,15 @@ async function runInstall(options = {}) {
   console.log('    multi_agent.max_parallel_analysis  5      Codebase analysis agents');
   console.log('');
   console.log('  _Sprintpilot/modules/autopilot/config.yaml');
+  // padEnd so the description column stays aligned across both rows,
+  // independent of the chosen values' widths (e.g. 2-digit limit, 4-char mode).
+  const apKey = (k) => k.padEnd(31, ' ');
+  const apVal = (v) => String(v).padEnd(6, ' ');
+  console.log(
+    `    ${apKey('autopilot.session_story_limit')}${apVal(sessionStoryLimit)} Stories to fully implement per run (0 = unlimited)`,
+  );
   console.log(
-    '    autopilot.session_story_limit    3      Stories to fully implement per run (0 = unlimited)',
+    `    ${apKey('autopilot.retrospective_mode')}${apVal(retrospectiveMode)} Epic-end retrospective: auto (inline) | stop (pause) | skip (not recommended)`,
   );
   console.log('');
   console.log('Multi-agent skills — run parallel subagents for faster analysis:');
@@ -963,4 +1196,15 @@ async function runInstall(options = {}) {
   console.log('Apache 2.0 License — Igor Kunin — https://github.com/ikunin/sprintpilot');
 }
 
-module.exports = { runInstall };
+module.exports = {
+  runInstall,
+  // Exported for unit tests only — do not depend on this surface elsewhere.
+  _internals: {
+    readExistingAutopilotConfig,
+    patchAutopilotConfig,
+    applyScalar,
+    RETROSPECTIVE_MODES,
+    DEFAULT_SESSION_STORY_LIMIT,
+    DEFAULT_RETROSPECTIVE_MODE,
+  },
+};

package/lib/prompts.js

@@ -27,6 +27,26 @@ async function confirm(opts) {
   return result;
 }
 
+async function text(opts) {
+  const clack = await loadClack();
+  const result = await clack.text(opts);
+  if (clack.isCancel(result)) {
+    clack.cancel('Cancelled');
+    process.exit(0);
+  }
+  return result;
+}
+
+async function select(opts) {
+  const clack = await loadClack();
+  const result = await clack.select(opts);
+  if (clack.isCancel(result)) {
+    clack.cancel('Cancelled');
+    process.exit(0);
+  }
+  return result;
+}
+
 async function intro(message) {
   const clack = await loadClack();
   clack.intro(message);
@@ -76,5 +96,7 @@ module.exports = {
   note,
   multiselect,
   confirm,
+  text,
+  select,
   log,
 };

package/lib/substitute.js

@@ -19,7 +19,7 @@ function renderString(text, ctx) {
   return out;
 }
 
-function buildContext({ outputFolder }) {
+function buildContext({ outputFolder } = {}) {
   const out = outputFolder || '_bmad-output';
   return {
     output_folder: out,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ikunin/sprintpilot",
-  "version": "1.0.3",
+  "version": "1.0.4",
   "description": "Sprintpilot — autopilot and multi-agent addon for BMad Method v6: git workflow, parallel agents, autonomous story execution",
   "license": "Apache-2.0",
   "repository": {
@@ -33,6 +33,9 @@
   "engines": {
     "node": ">=18.0.0"
   },
+  "scripts": {
+    "prepare": "node scripts/setup-git-hooks.mjs"
+  },
   "dependencies": {
     "@clack/core": "^1.0.0",
     "@clack/prompts": "^1.0.0",