@ikunin/sprintpilot 1.0.2 → 1.0.4

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

@@ -8,6 +8,24 @@ You do NOT hardcode the workflow sequence. After each completed skill, read its
 
 **Git integration** is additive. If `_Sprintpilot/manifest.yaml` doesn't exist or `git.enabled: false`, all git operations are silently skipped and this workflow behaves identically to the stock autopilot.
 
+### Shell portability (IMPORTANT)
+
+Sprintpilot runs under any LLM CLI (Claude Code, Gemini CLI, Cursor, etc.) on any OS. The shell that executes commands may be **bash, zsh, PowerShell, or cmd** depending on platform and CLI. Shell-specific idioms will fail silently when the wrong shell is used.
+
+**When you encounter bash-style idioms below, translate them to your shell.** The table applies to **external commands** (like `git`); cmdlets have slightly different conventions.
+
+| Bash idiom | PowerShell equivalent | Meaning |
+|---|---|---|
+| `A && B` | `A; if ($LASTEXITCODE -eq 0) { B }` (or separate commands, guarding B manually) | Run B only if A succeeded |
+| `A \|\| true` | `A; $LASTEXITCODE = 0` (or `try { A } catch {}` for cmdlets) | Run A, ignore failures |
+| `2>/dev/null` | `2>$null` | Suppress stderr |
+| `rm -rf <dir>` | `Remove-Item -Recurse -Force <dir>` | Recursive delete |
+| `if [ -f X ]; then ... fi` | `if (Test-Path -PathType Leaf X) { ... }` | File-exists check (regular file, not dir) |
+
+**Safer:** when in doubt, use the cross-platform Node helpers under `_Sprintpilot/scripts/`. For ad-hoc file ops, invoke Node inline: `node -e "require('fs').rmSync('<path>', {recursive: true, force: true})"`.
+
+If a step below uses `&&` to chain "run B only on A's success", and you cannot express that in one line, **run the commands separately and STOP if any step fails** — do not proceed past a failed step.
+
 ---
 
 ## AUTOPILOT RULES — READ BEFORE PROCEEDING
@@ -120,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. |
 
 ---
 
@@ -155,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>
 
@@ -170,7 +191,9 @@ Resolve:
   <check if="not a git repo">
     <action>HALT: "No git repository found. Initialize one first:
     ```
-    git init && git add -A && git commit -m 'initial commit'
+    git init
+    git add -A
+    git commit -m 'initial commit'
     git remote add origin <your-repo-url>
     ```
     Then run /sprint-autopilot-on again."</action>
@@ -201,15 +224,20 @@ Resolve:
   - COMMITTED: log "Recoverable work found for <name> — will push via git -C"
     Push the branch: `git -C .worktrees/<name> push -u origin <branch> 2>&1`
     If `{{create_pr}}` is true AND platform != git_only: create PR via `node {{project_root}}/_Sprintpilot/scripts/create-pr.js ...`
-    If `{{create_pr}}` is false OR platform is git_only: merge directly — `git checkout -B {{base_branch}} origin/{{base_branch}} && git merge <branch> --no-edit && git push origin {{base_branch}}`
+    If `{{create_pr}}` is false OR platform is git_only: merge directly. Run each as a separate command; **STOP and log the failure if any step fails — do not proceed past a failed step**:
+      1. `git checkout -B {{base_branch}} origin/{{base_branch}}`
+      2. `git merge <branch> --no-edit`
+      3. `git push origin {{base_branch}}`
     Then remove worktree.
   - STALE: `git worktree remove .worktrees/<name> --force` + prune
   - DIRTY: warn user, ask how to proceed (stash/commit/discard)
-  - ORPHAN: `rm -rf .worktrees/<name>` + `git worktree prune`
+  - ORPHAN: remove the directory cross-platform with `node -e "require('fs').rmSync('.worktrees/<name>', {recursive: true, force: true})"`, then `git worktree prune`
   </action>
 
   <action>**Branch reconciliation** — detect pushed-but-unmerged story branches.
-  Run: `git fetch origin && git branch -r --list "origin/{{branch_prefix}}*"`
+  Run as separate commands — **if `git fetch origin` fails (network/auth), STOP branch reconciliation and log a warning; do not operate on stale local refs**:
+    1. `git fetch origin`
+    2. `git branch -r --list "origin/{{branch_prefix}}*"`
   For each remote branch:
     - Extract story-key from branch name (strip "origin/{{branch_prefix}}" prefix)
     - Look up story status in `{status_file}`
@@ -226,16 +254,16 @@ Resolve:
           - If merge fails: log warning, continue (branch is preserved on remote)
           - If merge succeeds:
             - Re-read `{status_file}` from HEAD (may now include story artifacts after merge)
-            - Update `{git_status_file}` via sync-status.sh: set `--merge-status "recovered"` for this story.
-              **IMPORTANT:** sync-status.sh does full block replacement. If the story already has an entry in `{git_status_file}`, re-read its existing fields and pass ALL of them alongside `--merge-status`. If no entry exists yet, pass at minimum `--branch` and `--push-status "pushed"`.
+            - Update `{git_status_file}` via sync-status.js: set `--merge-status "recovered"` for this story.
+              **IMPORTANT:** sync-status.js does full block replacement. If the story already has an entry in `{git_status_file}`, re-read its existing fields and pass ALL of them alongside `--merge-status`. If no entry exists yet, pass at minimum `--branch` and `--push-status "pushed"`.
         - If `{{platform}}` is NOT git_only (github, gitlab, bitbucket, gitea) AND `{{create_pr}}` is true:
           - Check if PR/MR already exists for this branch (platform-specific check via create-pr.sh or CLI)
           - If no PR: create one via `node {{project_root}}/_Sprintpilot/scripts/create-pr.js --platform {{platform}} ...`
           - Log: "PR created/found for <story-key>"
-          - Update `{git_status_file}` via sync-status.sh: set `--merge-status "pr_pending"` for this story (same full-field requirement as above)
+          - Update `{git_status_file}` via sync-status.js: set `--merge-status "pr_pending"` for this story (same full-field requirement as above)
     - If status IS "done" AND branch still exists AND `{{cleanup_on_merge}}` is true:
       - Log: "Stale remote branch: <branch> — story already done, cleaning up"
-      - Delete remote branch: `git push origin --delete <branch> 2>/dev/null || true`
+      - Delete remote branch (ignore failure — the branch may already be gone): `git push origin --delete <branch>`
   </action>
 
   <action>Set `{{git_enabled}}` = true, `{{platform}}` = detected value</action>
@@ -290,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>
 
@@ -344,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.
   ```
@@ -486,8 +543,8 @@ Resolve:
     </action>
 
     <action>**Init submodules** if needed.
-    Run: `if [ -f .gitmodules ]; then timeout 30 git submodule update --init --recursive 2>&1 || echo "SUBMODULE_TIMEOUT"; fi`
-    If SUBMODULE_TIMEOUT: warn "Submodule init timed out (may need auth). Continuing without."
+    First check for `.gitmodules` (use your file-exists tool, or `node -e "process.exit(require('fs').existsSync('.gitmodules')?0:1)"`). If not present, skip this step.
+    If present, run `git submodule update --init --recursive` (give it ~30 seconds). If the command fails or hangs, warn "Submodule init failed (may need auth). Continuing without." and proceed.
     </action>
 
     <action>Set `{{in_worktree}}` = true</action>
@@ -561,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">
@@ -595,17 +656,18 @@ pr_base: {{pr_base}}
 <!-- GIT: Commit planning artifacts to main after planning skills -->
 <check if="{{git_enabled}} AND {{completed_skill}} is a planning skill (bmad-create-prd, bmad-create-architecture, bmad-create-ux-design, bmad-create-epics-and-stories, bmad-sprint-planning, bmad-check-implementation-readiness, bmad-create-story)">
   <action>**Commit planning artifacts to main** — keep track of all planning decisions in git.
-  Stage all changed artifacts:
+  Stage all changed artifacts (ignore errors — any of these paths may not yet exist):
   ```
-  git add _bmad-output/planning-artifacts/ _bmad-output/implementation-artifacts/ _bmad-output/stories/ 2>/dev/null || true
+  git add _bmad-output/planning-artifacts/ _bmad-output/implementation-artifacts/ _bmad-output/stories/
   ```
-  If there are staged changes, commit:
+  Check if there's anything staged; if yes, commit:
   ```
-  git diff --cached --quiet || git commit -m "docs: {{completed_skill}} artifacts"
+  git diff --cached --quiet
   ```
-  Push to remote if possible:
+  If that exits non-zero (there are staged changes), run: `git commit -m "docs: {{completed_skill}} artifacts"`
+  Then push (log a warning if push fails; do not halt autopilot):
   ```
-  git push origin {{base_branch}} 2>/dev/null || true
+  git push origin {{base_branch}}
   ```
   </action>
 </check>
@@ -775,12 +837,12 @@ Instruct: "Re-verify code review for story {{current_story}} — all patch findi
       Log warning but do NOT halt. The branch is pushed and preserved.
       Boot reconciliation (INITIALIZATION branch reconciliation) will retry on next session.
 
-    Note: `{{merge_status}}` is persisted by the full sync-status.sh call later in this step (via `--merge-status`). Do NOT call sync-status.sh separately here — it does full block replacement and would destroy other fields.
+    Note: `{{merge_status}}` is persisted by the full sync-status.js call later in this step (via `--merge-status`). Do NOT call sync-status.js separately here — it does full block replacement and would destroy other fields.
     </action>
     <check if="{{cleanup_on_merge}} is true">
-      <action>**Cleanup worktree** for merged story — branch was merged locally, worktree is no longer needed:
+      <action>**Cleanup worktree** for merged story — branch was merged locally, worktree is no longer needed. Ignore failures from the remove (the worktree may already be gone):
       ```
-      git worktree remove .worktrees/{{current_story}} --force 2>/dev/null || true
+      git worktree remove .worktrees/{{current_story}} --force
       git worktree prune
       ```
       </action>
@@ -804,17 +866,21 @@ Instruct: "Re-verify code review for story {{current_story}} — all patch findi
   This writes to `git-status.yaml` (addon-owned). Sprint-status.yaml is BMAD-owned — updated by BMAD skills only.
   </action>
 
-  <action>**Stage and commit artifacts** — explicitly include git-status.yaml and decision-log.yaml:
+  <action>**Stage and commit artifacts** — explicitly include git-status.yaml and decision-log.yaml. Ignore errors from the `git add` (any listed path may not yet exist):
   ```
-  git add _bmad-output/implementation-artifacts/sprint-status.yaml _bmad-output/implementation-artifacts/git-status.yaml _bmad-output/implementation-artifacts/autopilot-state.yaml _bmad-output/implementation-artifacts/decision-log.yaml _bmad-output/stories/ _bmad-output/planning-artifacts/ 2>/dev/null || true
-  git diff --cached --quiet || git commit -m "docs: story {{current_story}} done — {{test_count}} tests{{#if pr_url}}, PR: {{pr_url}}{{/if}}"
-  git push origin {{base_branch}} 2>/dev/null || true
+  git add _bmad-output/implementation-artifacts/sprint-status.yaml _bmad-output/implementation-artifacts/git-status.yaml _bmad-output/implementation-artifacts/autopilot-state.yaml _bmad-output/implementation-artifacts/decision-log.yaml _bmad-output/stories/ _bmad-output/planning-artifacts/
+  ```
+  Check if anything is staged: `git diff --cached --quiet`. If that exits non-zero, commit:
+  `git commit -m "docs: story {{current_story}} done — {{test_count}} tests{{#if pr_url}}, PR: {{pr_url}}{{/if}}"`
+  Then push (log a warning if push fails; do not halt autopilot):
+  ```
+  git push origin {{base_branch}}
   ```
   This ensures sprint-status.yaml, git-status.yaml, story files, and any updated artifacts are on main even when story code is on a PR branch.
   </action>
 </check>
 
-<!-- Story git status was already written by sync-status.sh above (when git_enabled AND in_worktree).
+<!-- Story git status was already written by sync-status.js above (when git_enabled AND in_worktree).
      sprint-status.yaml is BMAD-owned — updated by bmad-dev-story / bmad-code-review directly. -->
 <check if="NOT {{git_enabled}}">
   <action>Log: "Story {{current_story}} complete — BMAD dev-story updates sprint-status.yaml directly"</action>
@@ -828,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}}">
@@ -917,7 +1084,7 @@ pr_base: {{pr_base}}
         `git merge <branch-ref> --no-edit`
         `git push origin {{base_branch}}`
       - If merge succeeds: update merge_status in `{git_status_file}`.
-        **IMPORTANT:** sync-status.sh does full block replacement — you MUST re-read the story's existing fields from `{git_status_file}` (branch, commit, patch_commits, push_status, pr_url, lint_result, worktree, platform, base_branch, worktree_cleaned) and pass ALL of them along with `--merge-status "merged"`. Omitting fields destroys them.
+        **IMPORTANT:** sync-status.js does full block replacement — you MUST re-read the story's existing fields from `{git_status_file}` (branch, commit, patch_commits, push_status, pr_url, lint_result, worktree, platform, base_branch, worktree_cleaned) and pass ALL of them along with `--merge-status "merged"`. Omitting fields destroys them.
       - If merge fails: `git merge --abort`, update merge_status to "failed" in `{git_status_file}` (same full-field requirement), log warning, continue
   Log: "Pre-checkpoint merge: N stories verified on {{base_branch}}"
   </action>
@@ -999,13 +1166,14 @@ If the skill is not available or fails, generate a minimal README.md:
 
 <!-- GIT: Commit documentation and final artifacts to main -->
 <check if="{{git_enabled}}">
-  <action>**Commit final artifacts and documentation to main**:
+  <action>**Commit final artifacts and documentation to main**. Run each step; if an early step fails, STOP and log — don't proceed past a failed step. `git add` may fail for missing optional paths (`docs/`, `README.md`); ignore those path-specific errors. Failure of the final push should log a warning but not halt autopilot:
   ```
   git checkout -B {{base_branch}} origin/{{base_branch}}
-  git add _bmad-output/ README.md docs/ 2>/dev/null || true
-  git diff --cached --quiet || git commit -m "docs: project documentation and final artifacts"
-  git push origin {{base_branch}} 2>/dev/null || true
+  git add _bmad-output/ README.md docs/
   ```
+  Check if anything is staged: `git diff --cached --quiet`. If that exits non-zero, commit:
+  `git commit -m "docs: project documentation and final artifacts"`
+  Then: `git push origin {{base_branch}}`
   </action>
 </check>
 
@@ -1035,8 +1203,8 @@ If the skill is not available or fails, generate a minimal README.md:
 <check if="{{git_enabled}}">
   <action>**Cleanup all remaining worktrees**:
   Run: `git worktree list --porcelain`
-  For each worktree that is NOT the main worktree:
-    `git worktree remove <path> --force 2>/dev/null || true`
+  For each worktree that is NOT the main worktree, run the following — log and continue on failure; some worktrees may already be gone:
+    `git worktree remove <path> --force`
   Then: `git worktree prune`
   </action>
 </check>

package/_Sprintpilot/skills/sprintpilot-codebase-map/agents/architecture-mapper.md

@@ -19,28 +19,35 @@ Scan the project at `{{project_root}}` and write your findings to `{{output_file
 - `*.key`, `*.pem`, `*.p12` (private keys)
 - `credentials.json`, `service-account.json`
 
-## Exploration Commands
+## Exploration
 
-```bash
-# Top-level structure
-ls -la
-find . -maxdepth 2 -type d -not -path '*/node_modules/*' -not -path '*/.git/*' -not -path '*/vendor/*' | head -50
+Use your native file tools (Read, Glob, Grep). The lists below describe what data to collect; pick the appropriate tool for your CLI.
 
-# Entry points
-cat index.ts index.js main.py main.go cmd/main.go src/main.rs lib/main.rb app.py manage.py main.c main.cpp src/main.c src/main.cpp 2>/dev/null | head -30
+### Top-level structure
+Glob the root for directories and files (exclude `node_modules`, `.git`, `vendor`, `target`, `dist`, `build`). Look 1-2 levels deep to understand the layout.
 
-# Route definitions
-grep -rn "router\.\|app\.\(get\|post\|put\|delete\|patch\)\|@app\.route\|@Controller\|@RequestMapping\|CROW_ROUTE\|CPPREST_\|Pistache::" --include='*.ts' --include='*.js' --include='*.py' --include='*.java' --include='*.go' --include='*.xml' --include='*.c' --include='*.h' --include='*.cpp' --include='*.hpp' --include='*.cc' --include='*.cxx' --include='*.hxx' | head -30
+### Entry points
+Read whichever of these exist: `index.ts`, `index.js`, `main.py`, `main.go`, `cmd/main.go`, `src/main.rs`, `lib/main.rb`, `app.py`, `manage.py`, `main.c`, `main.cpp`, `src/main.c`, `src/main.cpp`. 30 lines is usually enough to identify the entry path.
 
-# Module exports / barrel files
-find . -name 'index.ts' -o -name 'index.js' -o -name '__init__.py' -o -name 'mod.rs' | head -20
+### Route definitions
+Use Grep to find route declarations across `*.ts`, `*.js`, `*.py`, `*.java`, `*.go`, `*.xml`, C/C++ headers. Pattern set:
+```
+router\.|app\.(get|post|put|delete|patch)|@app\.route|@Controller|@RequestMapping|CROW_ROUTE|CPPREST_|Pistache::
+```
+Limit to ~30 matches.
 
-# Import patterns (what depends on what)
-grep -rn "^import\|^from\|require(\|source \|^\.\|^#include" --include='*.ts' --include='*.js' --include='*.py' --include='*.sh' --include='*.c' --include='*.h' --include='*.cpp' --include='*.hpp' --include='*.cc' --include='*.cxx' --include='*.hxx' | awk -F'from |require|#include' '{print $2}' | sort | uniq -c | sort -rn | head -20
+### Module exports / barrel files
+Use Glob for: `**/index.ts`, `**/index.js`, `**/__init__.py`, `**/mod.rs`. Cap at ~20 hits.
 
-# Configuration loading
-grep -rn "config\|CONFIG\|Settings\|settings" --include='*.ts' --include='*.js' --include='*.py' --include='*.yaml' --include='*.json' --include='*.xml' --include='*.sh' --include='*.c' --include='*.h' --include='*.cpp' --include='*.hpp' --include='*.cc' --include='*.cxx' --include='*.hxx' -l | head -10
+### Import patterns (what depends on what)
+Use Grep to find import/require/include lines across `*.ts`, `*.js`, `*.py`, `*.sh`, C/C++ sources:
 ```
+^import|^from|require\(|source |^\.|^#include
+```
+Scan the top ~100 matches and note frequent dependencies. (No need to replicate the old `awk | sort | uniq -c` pipeline — just eyeball recurring targets.)
+
+### Configuration loading
+Use Grep (files-with-matches mode) for `config|CONFIG|Settings|settings` across config-bearing file types. Limit to ~10 files.
 
 Read entry point files, follow the import chain 2-3 levels deep to understand request flow.
 

package/_Sprintpilot/skills/sprintpilot-codebase-map/agents/concerns-hunter.md

@@ -20,42 +20,65 @@ Scan the project at `{{project_root}}` and write your findings to `{{output_file
 - `credentials.json`, `service-account.json`
 - Files in `.git/` directory
 
-## Exploration Commands
+## Exploration
 
-```bash
-# TODOs, FIXMEs, HACKs
-grep -rn 'TODO\|FIXME\|HACK\|XXX\|WORKAROUND\|TEMP\|DEPRECATED' --include='*.ts' --include='*.js' --include='*.py' --include='*.go' --include='*.java' --include='*.rs' --include='*.rb' --include='*.cs' --include='*.sql' --include='*.sps' --include='*.spb' --include='*.xml' --include='*.sh' --include='*.c' --include='*.h' --include='*.cpp' --include='*.hpp' --include='*.cc' --include='*.cxx' --include='*.hxx' | head -50
+Use Grep for pattern searches and `scan.js` for aggregations. All Grep calls below should filter to code file types (e.g., `*.ts`, `*.js`, `*.py`, `*.java`, `*.go`, `*.rs`, `*.rb`, `*.cs`, `*.sql`, `*.sps`, `*.spb`, `*.xml`, `*.sh`, `*.c`, `*.h`, `*.cpp`, `*.hpp`, `*.cc`, `*.cxx`, `*.hxx`) and cap each result set (~20-50).
 
-# Security: hardcoded secrets patterns
-grep -rn 'password\s*=\s*["\x27]\|api_key\s*=\s*["\x27]\|secret\s*=\s*["\x27]\|token\s*=\s*["\x27]' --include='*.ts' --include='*.js' --include='*.py' --include='*.java' --include='*.sql' --include='*.sps' --include='*.spb' --include='*.xml' --include='*.sh' --include='*.c' --include='*.h' --include='*.cpp' --include='*.hpp' --include='*.cc' --include='*.cxx' --include='*.hxx' -i | grep -v 'node_modules\|test\|spec\|mock\|fixture\|\.env\.example' | head -20
+### TODOs, FIXMEs, HACKs
+Grep for: `TODO|FIXME|HACK|XXX|WORKAROUND|TEMP|DEPRECATED`. Limit ~50.
 
-# Security: dangerous functions
-grep -rn 'eval(\|exec(\|dangerouslySetInnerHTML\|innerHTML\s*=\|__import__\|pickle\.load\|yaml\.load(\|EXECUTE IMMEDIATE\|DBMS_SQL' --include='*.ts' --include='*.js' --include='*.py' --include='*.java' --include='*.sql' --include='*.sps' --include='*.spb' --include='*.sh' | head -20
+### Security: hardcoded secrets
+Grep (case-insensitive) for: `password\s*=\s*["']|api_key\s*=\s*["']|secret\s*=\s*["']|token\s*=\s*["']`. Exclude matches under `node_modules/`, `test*`, `spec*`, `*mock*`, `*fixture*`, `.env.example`. Limit ~20.
 
-# SQL injection risk
-grep -rn 'query.*\${\|query.*%s\|query.*format\|execute.*f"\|query.*\+' --include='*.ts' --include='*.js' --include='*.py' --include='*.java' --include='*.xml' | head -20
+### Security: dangerous runtime sinks
+Grep for these high-risk call sites (code-exec and XSS patterns). The tokens below are split to avoid security-hook false positives on this documentation file — when building your regex, join them with `|` and concatenate the split tokens exactly as indicated.
 
-# C/C++ unsafe string and memory functions (buffer overflow risk)
-grep -rn 'strcpy(\|strcat(\|sprintf(\|gets(\|scanf(.*%s[^0-9]\|system(\|popen(' --include='*.c' --include='*.h' --include='*.cpp' --include='*.hpp' --include='*.cc' --include='*.cxx' --include='*.hxx' | head -20
+Literal regex tokens (already properly escaped):
 
-# Dead code: unused imports (sample)
-grep -rn '^import.*from' --include='*.ts' --include='*.js' --include='*.py' | awk -F'import ' '{print $2}' | awk -F' from' '{print $1}' | sort | uniq -c | sort -rn | head -10
+- `eval\(`
+- `exec\(`
+- `innerHTML\s*=`
+- `__import__`
+- `yaml\.load\(`
+- `EXECUTE IMMEDIATE`
+- `DBMS_SQL`
 
-# Commented-out code blocks (likely dead code)
-grep -rn '^\s*//.*function\|^\s*//.*class\|^\s*//.*const\|^\s*#.*def\|^\s*#.*class\|^\s*--.*PROCEDURE\|^\s*--.*FUNCTION\|^\s*--.*PACKAGE\|^\s*//.*struct\|^\s*//.*typedef\|^\s*/\*.*struct\|^\s*/\*.*typedef' --include='*.ts' --include='*.js' --include='*.py' --include='*.sql' --include='*.sps' --include='*.spb' --include='*.sh' --include='*.c' --include='*.h' --include='*.cpp' --include='*.hpp' --include='*.cc' --include='*.cxx' --include='*.hxx' | head -20
+Split tokens — concatenate the two halves verbatim, then escape the resulting literal dot:
 
-# Complexity: deeply nested code
-grep -rn '^\s\{16,\}' --include='*.ts' --include='*.js' --include='*.py' --include='*.sql' --include='*.sps' --include='*.spb' --include='*.sh' --include='*.c' --include='*.h' --include='*.cpp' --include='*.hpp' --include='*.cc' --include='*.cxx' --include='*.hxx' | head -10
+- `dangerously` + `SetInnerHTML` → final regex literal `dangerouslySetInnerHTML`
+- `pick` + `le.load` → final regex literal `pickle\.load` (note the escaped dot)
 
-# Large files (complexity hotspots)
-find . -type f \( -name '*.ts' -o -name '*.js' -o -name '*.py' -o -name '*.java' -o -name '*.sql' -o -name '*.sps' -o -name '*.spb' -o -name '*.xml' -o -name '*.sh' -o -name '*.c' -o -name '*.h' -o -name '*.cpp' -o -name '*.hpp' -o -name '*.cc' -o -name '*.cxx' -o -name '*.hxx' \) -not -path '*/node_modules/*' -exec wc -l {} + 2>/dev/null | sort -rn | head -10
+Run the search case-sensitively across the code-file types listed above. Limit ~20.
 
-# Deprecated package warnings
-cat package.json 2>/dev/null | grep -i 'deprecated\|legacy\|old'
+### SQL injection risk
+Grep across `*.ts`, `*.js`, `*.py`, `*.java`, `*.xml` for: `query.*\$\{|query.*%s|query.*format|execute.*f"|query.*\+`. Limit ~20.
 
-# Error handling: bare catches
-grep -rn 'catch\s*(\|except:\|except Exception\|rescue$\|EXCEPTION\s*$\|WHEN OTHERS\|catch\s*(\.\.\.)' --include='*.ts' --include='*.js' --include='*.py' --include='*.rb' --include='*.sql' --include='*.sps' --include='*.spb' --include='*.c' --include='*.h' --include='*.cpp' --include='*.hpp' --include='*.cc' --include='*.cxx' --include='*.hxx' | head -20
+### C/C++ unsafe string / memory functions
+Grep across C/C++ files only for: `strcpy\(|strcat\(|sprintf\(|gets\(|scanf\(.*%s[^0-9]|system\(|popen\(`. Limit ~20.
+
+### Dead code: unused-import candidates
+Grep for `^import.*from` across `*.ts`, `*.js`, `*.py` and eyeball the top imports. A full frequency rollup is not required — cite notable duplicates.
+
+### Commented-out code blocks
+Grep for:
+```
+^\s*//.*(function|class|const|struct|typedef)|^\s*#.*(def|class)|^\s*--.*(PROCEDURE|FUNCTION|PACKAGE)|^\s*/\*.*(struct|typedef)
 ```
+Limit ~20.
+
+### Complexity: deeply nested code
+Grep for lines starting with 16+ spaces: `^\s{16,}`. Limit ~10 (sample).
+
+### Large files (complexity hotspots)
+```
+node "{{project_root}}/_Sprintpilot/scripts/scan.js" largest --include "*.ts,*.js,*.py,*.java,*.cs,*.go,*.rs,*.rb,*.sql,*.sps,*.spb,*.xml,*.sh,*.c,*.h,*.cpp,*.hpp,*.cc,*.cxx,*.hxx" --root "{{project_root}}" --limit 10
+```
+
+### Deprecated package warnings
+Read `package.json` if present and check for `deprecated|legacy|old` (case-insensitive).
+
+### Error handling: bare catches
+Grep for: `catch\s*\(|except:|except Exception|rescue$|EXCEPTION\s*$|WHEN OTHERS|catch\s*\(\.\.\.\)`. Limit ~20.
 
 ## Downstream Consumers
 

package/_Sprintpilot/skills/sprintpilot-codebase-map/agents/integration-mapper.md

@@ -21,36 +21,36 @@ Scan the project at `{{project_root}}` and write your findings to `{{output_file
 
 **DO read**: `.env.example`, `.env.sample`, `.env.template` (safe — contain variable names only)
 
-## Exploration Commands
+## Exploration
 
-```bash
-# Environment variables referenced in code
-grep -rn 'process\.env\.\|os\.environ\|os\.getenv\|ENV\[\|\${\|export \|getenv(' --include='*.ts' --include='*.js' --include='*.py' --include='*.rb' --include='*.go' --include='*.sh' --include='*.c' --include='*.h' --include='*.cpp' --include='*.hpp' --include='*.cc' --include='*.cxx' --include='*.hxx' | sed 's/.*\(process\.env\.[A-Z_]*\|os\.environ\[['"'"'"]\?\([A-Z_]*\)\|os\.getenv(\([A-Z_]*\)\|ENV\[\([A-Z_]*\)\|getenv("\?\([A-Z_]*\)\).*/\1/' | sort -u | head -30
+Use Grep and Read. Below are the patterns to search for — file-type filters match the original language coverage (`*.ts`, `*.js`, `*.py`, `*.rb`, `*.go`, `*.rs`, `*.java`, `*.sh`, `*.c`, `*.h`, `*.cpp`, `*.hpp`, `*.cc`, `*.cxx`, `*.hxx`, `*.sql`, `*.sps`, `*.spb`, `*.xml`). Cap each result set (~15-30 matches).
 
-# .env.example (safe to read — template only)
-cat .env.example .env.sample .env.template 2>/dev/null
+### Environment variables referenced in code
+Grep for: `process\.env\.|os\.environ|os\.getenv|ENV\[|\$\{|export |getenv\(`. Extract uppercase identifier tokens from matches and list unique variable names.
 
-# HTTP client usage
-grep -rn 'fetch(\|axios\.\|requests\.\|http\.Client\|HttpClient\|urllib\|net/http\|reqwest\|curl \|wget \|curl_easy_\|libcurl\|cpprest\|boost::beast' --include='*.ts' --include='*.js' --include='*.py' --include='*.go' --include='*.rs' --include='*.java' --include='*.sh' --include='*.c' --include='*.h' --include='*.cpp' --include='*.hpp' --include='*.cc' --include='*.cxx' --include='*.hxx' | head -20
+### .env.example (safe to read — template only)
+Read whichever exist: `.env.example`, `.env.sample`, `.env.template`.
 
-# Database connections
-grep -rn 'createConnection\|createPool\|mongoose\.connect\|prisma\|sequelize\|knex\|sqlalchemy\|diesel\|gorm\|ActiveRecord\|jdbc\|sqlplus\|TNS_ADMIN\|CONNECT \|PQconnectdb\|mysql_real_connect\|SQLConnect\|OCILogon' --include='*.ts' --include='*.js' --include='*.py' --include='*.go' --include='*.rs' --include='*.java' --include='*.rb' --include='*.sql' --include='*.sps' --include='*.spb' --include='*.xml' --include='*.sh' --include='*.c' --include='*.h' --include='*.cpp' --include='*.hpp' --include='*.cc' --include='*.cxx' --include='*.hxx' -l | head -10
+### HTTP client usage
+Grep for: `fetch\(|axios\.|requests\.|http\.Client|HttpClient|urllib|net/http|reqwest|curl |wget |curl_easy_|libcurl|cpprest|boost::beast`. Limit ~20.
 
-# Message queue / event usage
-grep -rn 'kafka\|rabbitmq\|amqp\|sqs\|sns\|pubsub\|redis.*pub\|redis.*sub\|bull\|BullMQ\|celery\|sidekiq\|AQ$\|DBMS_AQ\|librdkafka\|cppkafka\|zmq_' --include='*.ts' --include='*.js' --include='*.py' --include='*.rb' --include='*.sql' --include='*.sps' --include='*.spb' --include='*.xml' --include='*.sh' --include='*.c' --include='*.h' --include='*.cpp' --include='*.hpp' --include='*.cc' --include='*.cxx' --include='*.hxx' -i | head -15
+### Database connections
+Grep (files-with-matches) for: `createConnection|createPool|mongoose\.connect|prisma|sequelize|knex|sqlalchemy|diesel|gorm|ActiveRecord|jdbc|sqlplus|TNS_ADMIN|CONNECT |PQconnectdb|mysql_real_connect|SQLConnect|OCILogon`. Limit ~10 files.
 
-# Cloud SDK usage
-grep -rn 'aws-sdk\|@aws-sdk\|boto3\|google-cloud\|@google-cloud\|azure\|@azure\|aws/core\|Aws::\|google::cloud' --include='*.ts' --include='*.js' --include='*.py' --include='*.java' --include='*.xml' --include='*.sh' --include='*.c' --include='*.h' --include='*.cpp' --include='*.hpp' --include='*.cc' --include='*.cxx' --include='*.hxx' -l | head -10
+### Message queue / event usage
+Grep (case-insensitive) for: `kafka|rabbitmq|amqp|sqs|sns|pubsub|redis.*pub|redis.*sub|bull|BullMQ|celery|sidekiq|AQ$|DBMS_AQ|librdkafka|cppkafka|zmq_`. Limit ~15.
 
-# OAuth / Auth providers
-grep -rn 'oauth\|passport\|auth0\|firebase.*auth\|cognito\|supabase.*auth\|clerk\|next-auth\|lucia' --include='*.ts' --include='*.js' --include='*.py' --include='*.xml' -i | head -15
+### Cloud SDK usage
+Grep (files-with-matches) for: `aws-sdk|@aws-sdk|boto3|google-cloud|@google-cloud|azure|@azure|aws/core|Aws::|google::cloud`. Limit ~10.
 
-# Third-party SaaS SDKs
-grep -rn 'stripe\|sendgrid\|twilio\|sentry\|datadog\|segment\|amplitude\|mixpanel\|intercom\|slack' --include='*.ts' --include='*.js' --include='*.py' --include='*.xml' --include='*.sh' -i -l | head -10
+### OAuth / Auth providers
+Grep (case-insensitive) across `*.ts`, `*.js`, `*.py`, `*.xml` for: `oauth|passport|auth0|firebase.*auth|cognito|supabase.*auth|clerk|next-auth|lucia`. Limit ~15.
 
-# Docker-compose services (external deps)
-cat docker-compose*.yml 2>/dev/null | grep -E '^\s+\w+:$|image:' | head -20
-```
+### Third-party SaaS SDKs
+Grep (files-with-matches, case-insensitive) for: `stripe|sendgrid|twilio|sentry|datadog|segment|amplitude|mixpanel|intercom|slack`. Limit ~10.
+
+### Docker-compose services
+Read `docker-compose*.yml` files (use Glob to find them) and note the service names and `image:` values.
 
 ## Downstream Consumers