bf-resume

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Resume Workflow

恢复工作流

Overview

概述

세션 중단, context limit 도달, 에러 등으로 BF 워크플로우가 중간에 멈춘 경우, sprint-status.yaml의 상태를 분석하여 적절한 지점부터 워크플로우를 재개한다. bf-execute와 동일한 에픽 단위 루프를 사용하여 사람-시스템 경계를 유지한다.

当BF工作流因会话中断、达到context limit、错误等原因中途停止时，通过分析sprint-status.yaml的状态，从合适的点恢复工作流。使用与bf-execute相同的Epic级循环，维持人与系统的边界。

When to Use

使用场景

Claude Code 세션이 중단된 후 워크플로우를 이어서 진행할 때
사용자가
```
/bf-resume
```
을 입력했을 때
사용자가
```
/bf-resume --from {EPIC-ID}
```
로 특정 에픽부터 재개하고 싶을 때

Claude Code会话中断后，需要继续工作流时
用户输入
```
/bf-resume
```
时
用户输入
```
/bf-resume --from {EPIC-ID}
```
，希望从特定Epic开始恢复时

Prerequisites

前置条件

```
docs/sprint-status.yaml
```
존재
```
docs/tech-specs/{TICKET}-tech-spec.md
```
존재

存在
```
docs/sprint-status.yaml
```
存在
```
docs/tech-specs/{TICKET}-tech-spec.md
```

Error Handling

错误处理

sprint-status.yaml 미존재: "진행 중인 스프린트가 없습니다.
```
/bf-spec
```
으로 새 워크플로우를 시작하세요." 안내
tech-spec 미존재: "Tech Spec 파일이 없습니다.
```
/bf-spec
```
으로 먼저 Tech Spec을 작성하세요." 안내
```
--from
```
에 존재하지 않는 EPIC-ID 지정: "에픽 '{EPIC-ID}'이(가) sprint-status.yaml에 없습니다. 사용 가능한 에픽: {에픽 목록}" 안내
yq 미설치: "yq가 설치되지 않았습니다.
```
brew install yq
```
(macOS) 또는 https://github.com/mikefarah/yq#install (Linux)로 설치하세요." 안내

不存在sprint-status.yaml：提示“没有进行中的Sprint。请使用
```
/bf-spec
```
启动新工作流。”
不存在tech-spec：提示“没有Tech Spec文件。请先使用
```
/bf-spec
```
编写Tech Spec。”
```
--from
```
指定了不存在的EPIC-ID：提示“Epic '{EPIC-ID}'不存在于sprint-status.yaml中。可用Epic：{Epic列表}”
未安装yq：提示“未安装yq。请使用
```
brew install yq
```
（macOS）或https://github.com/mikefarah/yq#install（Linux）进行安装。”

Instructions

操作步骤

1. 상태 분석

1. 状态分析

yq 전제조건 체크 (최초 1회):

bash

command -v yq >/dev/null 2>&1 || { echo "❌ yq not installed. Install: brew install yq"; exit 1; }

docs/sprint-status.yaml

을 읽고 현재 스프린트 상태를 분석한다.

yq前置条件检查（首次执行1次）：

bash

command -v yq >/dev/null 2>&1 || { echo "❌ yq not installed. Install: brew install yq"; exit 1; }

读取

docs/sprint-status.yaml

，分析当前Sprint状态。

2. --from 옵션 처리

2. --from选项处理

--from {EPIC-ID}

옵션이 주어진 경우 해당 에픽 전체를 처음부터 재실행한다:

해당 에픽 내 모든 Story (done 포함)의

status

를

todo

로,

tdd

를

pending

으로,

review

를

pending

으로 리셋:

bash

# 에픽 내 각 Story별로 개별 yq 명령 실행 (select+할당 조합의 in-place 동작 불안정 방지)
yq -i '.<TICKET>.<EPIC>.<STORY-1>.status = "todo" | .<TICKET>.<EPIC>.<STORY-1>.tdd = "pending" | .<TICKET>.<EPIC>.<STORY-1>.review = "pending"' docs/sprint-status.yaml
# 각 Story에 대해 반복 실행

에픽의 e2e 상태도

pending

으로 리셋:

bash

yq -i '.<TICKET>.<EPIC>.e2e = "pending"' docs/sprint-status.yaml

```
.ralph-progress/
```
디렉토리 내 해당 에픽 Story의 진행 파일(
```
{STORY-ID}.json
```
)이 있으면 삭제 (이전 Ralph Loop 진행 파일 정리).
메트릭 필드는 보존한다 (이전 시도의 기록).
재개 지점을 해당 에픽으로 설정한다.

참고:
--from
은 에픽 전체 재실행이다. 미완료 Story만 재실행하려면
--from
없이 실행하면 자동 판별된다.

当指定

--from {EPIC-ID}

选项时，重新执行整个Epic：

将该Epic内所有Story（包括已完成的）的

status

设为

todo

，

tdd

设为

pending

，

review

设为

pending

：

bash

# 针对每个Story单独执行yq命令（避免select+赋值组合的原地操作不稳定问题）
yq -i '.<TICKET>.<EPIC>.<STORY-1>.status = "todo" | .<TICKET>.<EPIC>.<STORY-1>.tdd = "pending" | .<TICKET>.<EPIC>.<STORY-1>.review = "pending"' docs/sprint-status.yaml
# 对每个Story重复执行

将Epic的e2e状态也重置为

pending

：

bash

yq -i '.<TICKET>.<EPIC>.e2e = "pending"' docs/sprint-status.yaml

如果
```
.ralph-progress/
```
目录内存在该Epic Story的进度文件(
```
{STORY-ID}.json
```
)，则删除（清理之前的Ralph Loop进度文件）。
保留指标字段（之前尝试的记录）。
将恢复点设置为该Epic。

注意：
--from
是重新执行整个Epic。如果只想重新执行未完成的Story，无需使用
--from
，系统会自动判断。

3. 자동 재개 지점 판별

3. 自动判断恢复点

옵션 없이 실행된 경우, 다음 우선순위로 재개 지점을 자동 판별한다 (위에서부터 순서대로 검사하여 첫 번째 매칭 적용):

a) Story가 하나도 없는 경우 (sprint-status.yaml은 있지만 Story 미생성):

재개 지점: Plan 단계 — orchestrate plan 모드부터 시작

b)
status: in_progress
인 Story가 있는 경우:

git status로 uncommitted 변경사항 확인
변경사항 있음: 사용자에게 "이전 진행 중이던 {STORY-ID}의 미커밋 변경사항이 있습니다." 확인 후 처리:
- "변경사항 유지" (기본): Story별 브랜치에 보관한다:
  bash
```
git checkout -b bf-stash/{STORY-ID}
git add --all -- ':!docs/' && git commit -m "[{TICKET}] 중단된 작업 백업"
git checkout {원래-브랜치}
```
  사용자에게 "
```
bf-stash/{STORY-ID}
```
  브랜치에 백업했습니다. 필요 시
```
git cherry-pick
```
  으로 복원 가능합니다." 안내
- "변경사항 폐기":
```
git checkout -- .
```
  으로 미커밋 변경 제거
- 어느 경우든
```
status: todo
```
  ,
```
tdd: pending
```
  ,
```
review: pending
```
  으로 리셋 → 에픽 재개 시 새 agent가 처음부터 구현
- 복수 Story가 동시에 in_progress인 경우: 각 Story별로 변경 파일을 식별하여 개별 브랜치에 보관. 파일 귀속이 불분명하면
```
bf-stash/mixed-{EPIC-ID}
```
  에 전체 보관
```
ralph_stuck: true
```
인 경우: bf-lead-implement 크래시로 orchestrate에 보고되지 못한 상태.
```
status: skipped
```
로 설정하여 orchestrate가 재처리하지 않도록 한다.
변경사항 없음 (
```
ralph_stuck: false
```
): git log에서 해당 Story ID 커밋 존재 여부 확인
bash
```
git log --oneline --grep="{STORY-ID}" | head -1
```
- 커밋 존재: agent가 커밋 후 보고 전에 중단된 것 (Lead 크래시 포함).
```
status: done
```
  ,
```
tdd: done
```
  으로 설정.
```
.ralph-progress/{STORY-ID}.json
```
  이 있으면
```
ralph_retries
```
  와
```
ralph_approaches
```
  를 sprint-status.yaml에 반영 (
```
model_used
```
  는 bf-lead-implement가 결정하므로 이 경우
```
null
```
  로 유지)
- 커밋 미존재: 구현이 시작되지 않았거나 중간에 중단된 것.
```
status: todo
```
  ,
```
tdd: pending
```
  ,
```
review: pending
```
  으로 리셋
```
.ralph-progress/
```
디렉토리에 해당 Story 진행 파일이 있으면 삭제 (리셋 Story만)
재개 지점: 해당 에픽

c) 미완료 에픽이 있는 경우 (일부 Story가
todo
이거나 e2e/review가 미완):

재개 지점: 해당 에픽 (orchestrate epic 모드가 sprint-status.yaml을 읽고 이미 done인 Story를 건너뜀)

d) 모든 에픽의 e2e가 terminal state (
passed
|
skipped
|
escalated
|
max-regression-cycles
)이고 모든 Story
review: approved
인 경우:

"모든 에픽이 완료되었습니다.
```
/bf-archive-sprint
```
를 실행하세요." 안내
종료.

如果未指定选项执行，将按以下优先级自动判断恢复点（从上到下依次检查，应用第一个匹配项）：

a) 没有任何Story的情况（存在sprint-status.yaml但未生成Story）：

恢复点：Plan阶段 — 从orchestrate plan模式开始

b) 存在
status: in_progress
的Story时：

通过git status检查未提交的更改
存在更改：提示用户“存在之前正在进行的{STORY-ID}的未提交更改。”，并提供处理选项：
- “保留更改”（默认）：保存到Story专属分支：
  bash
```
git checkout -b bf-stash/{STORY-ID}
git add --all -- ':!docs/' && git commit -m "[{TICKET}] 中断工作的备份"
git checkout {原分支}
```
  提示用户“已备份到
```
bf-stash/{STORY-ID}
```
  分支。需要时可通过
```
git cherry-pick
```
  恢复。”
- “丢弃更改”：通过
```
git checkout -- .
```
  删除未提交的更改
- 无论哪种情况，都将
```
status: todo
```
  、
```
tdd: pending
```
  、
```
review: pending
```
  重置 → 恢复Epic时由新的agent从头开始实现
- 如果多个Story同时处于in_progress状态：识别每个Story的更改文件，分别保存到专属分支。如果文件归属不明确，则全部保存到
```
bf-stash/mixed-{EPIC-ID}
```
当
```
ralph_stuck: true
```
时：因bf-lead-implement崩溃导致未向orchestrate报告状态。将
```
status: skipped
```
设置为orchestrate不再重新处理。
不存在更改（
```
ralph_stuck: false
```
）：检查git log中是否存在该Story ID的提交
bash
```
git log --oneline --grep="{STORY-ID}" | head -1
```
- 存在提交：agent提交后、报告前中断（包括Lead崩溃）。将
```
status: done
```
  、
```
tdd: done
```
  设置。如果存在
```
.ralph-progress/{STORY-ID}.json
```
  ，则将
```
ralph_retries
```
  和
```
ralph_approaches
```
  反映到sprint-status.yaml中（
```
model_used
```
  由bf-lead-implement决定，因此此处保持
```
null
```
  ）
- 不存在提交：实现尚未开始或中途中断。将
```
status: todo
```
  、
```
tdd: pending
```
  、
```
review: pending
```
  重置
如果
```
.ralph-progress/
```
目录中存在该Story的进度文件，则删除（仅重置的Story）
恢复点：该Epic

c) 存在未完成Epic的情况（部分Story为
todo
或e2e/review未完成）：

恢复点：该Epic（orchestrate epic模式读取sprint-status.yaml，跳过已完成的Story）

d) 所有Epic的e2e处于终端状态(
passed
|
skipped
|
escalated
|
max-regression-cycles
)且所有Story的
review: approved
时：

提示“所有Epic已完成。请执行
```
/bf-archive-sprint
```
。”
退出。

4. 재개 지점 제시

4. 提示恢复点

워크플로우 재개 지점 분석
- 티켓: {TICKET}
- 현재 상태: {상태 요약}
- 재개 에픽: {epic-id} (총 N개 중 M번째)
- skipped Story: {있으면 목록 표시}
- 이유: {판별 근거}

계속 진행하시겠습니까?

skipped(stuck) Story가 있으면 함께 표시한다. 이전 실행에서 이미 auto-skip 되었으므로, 사람이 수정을 원하면 에픽 결과 확인 시점에서 modification.md로 지시할 수 있다.

工作流恢复点分析
- 工单: {TICKET}
- 当前状态: {状态摘要}
- 恢复Epic: {epic-id}（共N个中的第M个）
- skipped Story: {存在则显示列表}
- 原因: {判断依据}

是否继续？

如果存在skipped(stuck) Story，一并显示。由于之前的执行中已自动跳过，若用户需要修改，可在查看Epic结果时通过modification.md指示。

5. 재개 실행

5. 执行恢复

사용자 확인 후, 재개 지점에 따라:

Plan 미완:

orchestrate (plan 모드) 스폰 (
```
model: sonnet
```
— plan 모드는 단순 라우터 역할)
전달: tech-spec 경로, conventions.md 경로
수신 후: sprint-status.yaml의 에픽/스토리 구조를 사람에게 제시
이후 에픽 루프 진입 (Step 6)

에픽 재개:

bf-execute와 동일한 에픽 루프 진입 (Step 6)

用户确认后，根据恢复点执行：

Plan未完成：

启动orchestrate（plan模式）(
```
model: sonnet
```
— plan模式仅作为简单路由)
传递：tech-spec路径、conventions.md路径
接收后：向用户展示sprint-status.yaml中的Epic/Story结构
之后进入Epic循环（步骤6）

恢复Epic：

进入与bf-execute相同的Epic循环（步骤6）

6. 에픽 루프 (bf-execute와 동일)

6. Epic循环（与bf-execute相同）

재개 에픽부터 순서대로 순회한다. 각 에픽에 대해:

从恢复Epic开始依次遍历。针对每个Epic：

6a. orchestrate (epic 모드) 스폰

6a. 启动orchestrate（epic模式）

Task tool 사용,
```
model: opus
```
전달:
```
mode: "epic"
```
,
```
epic_id
```
, tech-spec 경로, conventions.md 경로
- 수정 재실행인 경우:
```
modification_path
```
  추가 전달
수신 대기:
```
"done"
```
+ sprint-status.yaml 경로 + review.md 경로

使用Task tool，
```
model: opus
```
传递：
```
mode: "epic"
```
、
```
epic_id
```
、tech-spec路径、conventions.md路径
- 如果是修改后重新执行：额外传递
```
modification_path
```
等待接收：
```
"done"
```
+ sprint-status.yaml路径 + review.md路径

6b. 에픽 결과 제시

6b. 展示Epic结果

orchestrate 완료 후 sprint-status.yaml과 review.md를 읽어 사람에게 제시한다:

undefined

orchestrate完成后，读取sprint-status.yaml和review.md并展示给用户：

undefined

Epic {EPIC-ID} 완료

Epic {EPIC-ID}完成

Story 결과

Story结果

스토리	상태	난이도	재시도 횟수	Stuck
story-1	done	S	0	-
story-2	done	M	2	-
story-3	skipped (stuck)	L	5	stuck.md 참조

故事	状态	难度	重试次数	Stuck
story-1	done	S	0	-
story-2	done	M	2	-
story-3	skipped (stuck)	L	5	参考stuck.md

E2E: {passed | skipped | escalated | max-regression-cycles}

Integration Review: Blockers {N}건, Recommended {N}건

集成评审: 阻塞问题 {N}个, 建议改进 {N}个

상세: docs/reviews/{EPIC-ID}-review.md

详情: docs/reviews/{EPIC-ID}-review.md

⚠️ (모든 Story가 skipped인 경우에만 표시) 이 에픽의 모든 Story가 skipped(stuck) 상태입니다. 진행 시 해당 기능이 구현되지 않은 상태로 넘어갑니다.

진행하시겠습니까?

다음 에픽으로 진행
수정 후 재실행 (수정 내용 입력)
워크플로우 중단

undefined

⚠️（仅当所有Story均为skipped时显示）该Epic的所有Story均处于skipped(stuck)状态。继续的话，将在未实现该功能的情况下推进。

是否继续？

进入下一个Epic
修改后重新执行（输入修改内容）
中断工作流

undefined

6c. 사람 판단 처리

6c. 处理用户判断

사람의 선택에 따라:

1. 다음 에픽으로 진행:

해당 에픽의 사람 수용 상태를 sprint-status.yaml에 반영한다 (

yq -i

사용):

```
status: skipped
```
인 Story의
```
review
```
를
```
"approved"
```
로 설정 (사람이 skip을 수용)
```
review: pending
```
인
```
status: done
```
Story의
```
review
```
를
```
"approved"
```
로 설정 (사람이 Blocker를 수용)

bash

yq -i '.<TICKET>.<EPIC>.<SKIPPED-STORY>.review = "approved"' docs/sprint-status.yaml
yq -i '.<TICKET>.<EPIC>.<DONE-STORY>.review = "approved"' docs/sprint-status.yaml

다음 에픽의 6a로 이동한다.

2. 수정 후 재실행:

사람이 수정 내용을 텍스트로 입력한다.
bf-resume이 수정 내용을 분석하여 대상 Story를 추론하고, 사람에게 확인한다.
```
docs/reviews/{EPIC-ID}-modification.md
```
에 기록한다 (bf-execute의 modification.md 형식과 동일).
git commit하지 않는다 — docs/ 산출물은 Phase 4 Archive에서 일괄 커밋한다.
같은 에픽에 대해 orchestrate를 epic 모드로 다시 스폰한다 (
```
modification_path
```
전달).
6b로 돌아가 결과를 다시 제시한다.

3. 워크플로우 중단:

현재 상태를 안내하고 종료한다.

根据用户的选择执行：

1. 进入下一个Epic：

将该Epic的用户接受状态反映到sprint-status.yaml中（使用

yq -i

）：

将
```
status: skipped
```
的Story的
```
review
```
设置为
```
"approved"
```
（用户接受跳过）
将
```
review: pending
```
的
```
status: done
```
Story的
```
review
```
设置为
```
"approved"
```
（用户接受阻塞问题）

bash

yq -i '.<TICKET>.<EPIC>.<SKIPPED-STORY>.review = "approved"' docs/sprint-status.yaml
yq -i '.<TICKET>.<EPIC>.<DONE-STORY>.review = "approved"' docs/sprint-status.yaml

进入下一个Epic的6a步骤。

2. 修改后重新执行：

用户输入修改内容的文本。
bf-resume分析修改内容，推断目标Story，并向用户确认。
记录到
```
docs/reviews/{EPIC-ID}-modification.md
```
中（与bf-execute的modification.md格式相同）。
不执行git commit — docs/产物在Phase 4 Archive中统一提交。
针对同一Epic，以epic模式重新启动orchestrate（传递
```
modification_path
```
）。
返回6b步骤，重新展示结果。

3. 中断工作流：

提示当前状态并退出。

7. 전체 완료

7. 全部完成

모든 에픽 완료 후, bf-execute와 동일하게 후처리 단계를 안내한다.

워크플로우가 완료되었습니다.

다음 단계:
1. /bf-archive-sprint — 스프린트 아카이빙
2. /bf-metrics — 메트릭 분석 (선택)
3. /bf-update-conventions — 컨벤션 업데이트

所有Epic完成后，与bf-execute相同，提示后续处理步骤。

工作流已完成。

下一步：
1. /bf-archive-sprint — 归档Sprint
2. /bf-metrics — 指标分析（可选）
3. /bf-update-conventions — 更新规范

Output Format

输出格式

대화로 재개 지점 분석 결과를 출력하고, 사용자 확인 후 에픽 단위 루프를 실행한다. modification.md 외 별도 파일 생성 없음.

以对话形式输出恢复点分析结果，用户确认后执行Epic级循环。除modification.md外，不生成其他文件。