/pipeline-resume

description: Recover full pipeline context after compaction — find the last active issue, reconstruct FORGE annotations, and resume work
argument-hint: "[issue number (optional — auto-detects if omitted)]"
install: extras

/pipeline-resume — Context Recovery After Compaction

> **Skill names**: `{FORGE_SKILL_PREFIX}` is `forgedock:` (plugin install) or empty (`install.sh`), resolved once per run by `commands/work-on.md` § Skill Name Resolution. If the skill is not found under either name, STOP and report "skill not found" — never run the phase inline.

**Input**: $ARGUMENTS

You are the context-recovery agent. When a session ends or context is compressed, all working state is lost. Your job is to restore it instantly — find the most recently active issue, read all FORGE annotations, reconstruct the current pipeline phase, and re-enter the pipeline exactly where it left off.

**Agent model policy**: `model: "haiku"`, `effort: low` (mechanical tier — context recovery, annotation reading, state reconstruction). Fallback: `model: "sonnet"` if rate-limited. Feature gate: pass `effort` only on Claude Code >= 2.1.154. **NEVER use plan mode (EnterPlanMode).** **NEVER use the Agent tool** — pipeline-resume re-enters the pipeline via `Skill(skill="{FORGE_SKILL_PREFIX}work-on", ...)` only. Using the Agent tool would restart the pipeline in an untracked subprocess rather than resuming the existing tracked session.

<!-- FORGE:SPEC_LOADED — pipeline-resume.md loaded and active. Agent is bound by this spec. -->

---

Phase 0: Config Resolution

Read `forge.yaml` to configure all project-specific variables before running any commands:

CONFIG_FILE="${FORGE_CONFIG:-forge.yaml}"
GH_REPO=$(yq '.project.owner + "/" + .project.repo' "$CONFIG_FILE")
GH_FLAG="-R $GH_REPO"
REPO_PATH=$(yq '.paths.root' "$CONFIG_FILE")
STAGING_BRANCH=$(yq '.branches.staging' "$CONFIG_FILE")

If `forge.yaml` is missing: stop and tell the user to run `npx forgedock init` to generate it.

---

Phase 1: Find Active Issue

1A: Parse input

Check `$ARGUMENTS`:

• **`--all-stalled`** (fleet recovery mode): shell out to `npx forgedock resume-stalled` to scan all in-flight issues for expired leases and re-dispatch them. This delegates to the durable engine's `scanStalls` for ground-truth stall detection. Add `--dry-run` if only a report is needed. Then STOP — fleet recovery is complete.

# Fleet recovery mode — delegate to the engine's resume-stalled CLI
if echo "$ARGUMENTS" | grep -q -- "--all-stalled"; then
    DRY_RUN_FLAG=""
    if echo "$ARGUMENTS" | grep -q -- "--dry-run"; then
        DRY_RUN_FLAG="--dry-run"
    fi
    echo "Fleet stall recovery: scanning all in-flight issues for expired leases…"
    npx forgedock resume-stalled $DRY_RUN_FLAG
    echo ""
    echo "Fleet recovery complete. To resume a single issue: /pipeline-resume <issue-number>"
    # STOP — fleet recovery does not fall through to single-issue resume.
fi

If `--all-stalled` was not specified, continue with single-issue resume:

• **Explicit issue number** (e.g., `610`, `#610`): strip `#`, set `TARGET_NUMBER={number}`, skip to Phase 2.
• **Empty**: proceed with auto-detection below.

1B: Query for in-progress issues

The `gh issue list --label` flag uses AND filtering when multiple labels are given. To find issues with ANY active workflow label, run one query per label and merge results:

# Find open issues with any active workflow label, sorted by most recently updated
# (gh --label uses AND, so query each label separately and merge)
ACTIVE_ISSUES=$(
  for LABEL in "workflow:investigating" "workflow:ready-to-build" "workflow:building" "workflow:in-review" "workflow:remediating"; do
    gh issue list {GH_FLAG} \
      --state open \
      --label "$LABEL" \
      --limit 10 \
      --json number,title,labels,updatedAt
  done | jq -s '
    flatten |
    unique_by(.number) |
    sort_by(.updatedAt) | reverse |
    .[] | {
      number,
      title,
      phase: (.labels | map(.name | select(startswith("workflow:"))) | first // "unknown"),
      updatedAt
    }
  ')
echo "$ACTIVE_ISSUES"

1C: Select issue

**If one result**: use it — set `TARGET_NUMBER={number}`.

**If multiple results**: display a ranked list (most recently updated first), then select the top entry:

## Active Issues Found (most recent first)

| # | Issue | Phase | Last Updated |
|---|-------|-------|--------------|
| 1 | #{number}: {title} | {phase} | {updatedAt} |
| 2 | #{number}: {title} | {phase} | {updatedAt} |
...

Auto-selecting #1 (most recently updated). Pass an explicit issue number to override.

Set `TARGET_NUMBER` to the top-ranked issue number.

1D: Fallback — no active label found

If `ACTIVE_ISSUES` is empty, search recent issues by FORGE annotation presence:

# Look for recently updated open issues with FORGE annotations (pipeline may have stalled pre-label)
RECENT_ISSUES=$(gh issue list {GH_FLAG} \
  --state open \
  --limit 20 \
  --json number,title,updatedAt \
  --jq 'sort_by(.updatedAt) | reverse | .[0:5] | .[] | {number, title, updatedAt}')

# For each candidate, check if it has FORGE annotations
for NUMBER in $(echo "$RECENT_ISSUES" | jq -r '.number'); do
  HAS_FORGE=$(gh api repos/{GH_REPO}/issues/$NUMBER/comments \
    --jq '[.[] | select(.body | test("<!-- FORGE:"))] | length > 0' 2>/dev/null || echo "false")
  if [ "$HAS_FORGE" = "true" ]; then
    TARGET_NUMBER=$NUMBER
    break
  fi
done

If still no candidate: display `No recent active issues found. To resume work on a specific issue, run: /pipeline-resume {issue-number}` and STOP.

---

Phase 2: Reconstruct Context

2A: Load issue state

ISSUE=$(gh issue view {TARGET_NUMBER} {GH_FLAG} \
  --json number,title,body,labels,state,milestone,updatedAt)

ISSUE_TITLE=$(echo "$ISSUE" | jq -r '.title')
ISSUE_STATE=$(echo "$ISSUE" | jq -r '.state')
ISSUE_LABELS=$(echo "$ISSUE" | jq -r '[.labels[].name] | join(", ")')
ISSUE_MILE