create-handoff

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Create Handoff

创建工作交接文档

You are tasked with writing a handoff document to hand off your work to another agent in a new session. You will create a handoff document that is thorough, but also concise. The goal is to compact and summarize your context without losing any of the key details of what you're working on.

你的任务是编写一份工作交接文档，将你的工作移交给新会话中的另一个Agent。你需要创建一份既全面又简洁的交接文档。目标是在不丢失当前工作关键细节的前提下，精简并汇总相关上下文。

Process

流程

1. Filepath & Metadata

1. 文件路径与元数据

Use the following information to understand how to create your document:

First, determine the session name from existing handoffs:

bash

ls -td thoughts/shared/handoffs/*/ 2>/dev/null | head -1 | xargs basename

This returns the most recently modified handoff folder name (e.g.,

open-source-release

). Use this as the handoff folder name.

If no handoffs exist, use

general

as the folder name.

Create your file under:

thoughts/shared/handoffs/{session-name}/YYYY-MM-DD_HH-MM_description.yaml

, where:

```
{session-name}
```
is from existing handoffs (e.g.,
```
open-source-release
```
) or
```
general
```
if none exist
```
YYYY-MM-DD
```
is today's date
```
HH-MM
```
is the current time in 24-hour format (no seconds needed)
```
description
```
is a brief kebab-case description

Examples:

thoughts/shared/handoffs/open-source-release/2026-01-08_16-30_memory-system-fix.yaml

thoughts/shared/handoffs/general/2026-01-08_16-30_bug-investigation.yaml

使用以下信息了解如何创建文档：

首先，从现有交接文档中确定会话名称：

bash

ls -td thoughts/shared/handoffs/*/ 2>/dev/null | head -1 | xargs basename

该命令会返回最近修改的交接文件夹名称（例如：

open-source-release

），将其用作交接文件夹名称。

如果没有现有交接文档，使用

general

作为文件夹名称。

在以下路径下创建文件：

thoughts/shared/handoffs/{session-name}/YYYY-MM-DD_HH-MM_description.yaml

，其中：

```
{session-name}
```
来自现有交接文档（例如：
```
open-source-release
```
），若无则使用
```
general
```
```
YYYY-MM-DD
```
为当前日期
```
HH-MM
```
为24小时制的当前时间（无需秒数）
```
description
```
为简短的短横线分隔式描述

示例：

thoughts/shared/handoffs/open-source-release/2026-01-08_16-30_memory-system-fix.yaml

thoughts/shared/handoffs/general/2026-01-08_16-30_bug-investigation.yaml

2. Write YAML handoff (~400 tokens vs ~2000 for markdown)

2. 编写YAML格式的交接文档（约400个token，相比Markdown的约2000个token更精简）

CRITICAL: Use EXACTLY this YAML format. Do NOT deviate or use alternative field names.

The

goal:

and

now:

fields are shown in the statusline - they MUST be named exactly this.

yaml

---
session: {session-name from ledger}
date: YYYY-MM-DD
status: complete|partial|blocked
outcome: SUCCEEDED|PARTIAL_PLUS|PARTIAL_MINUS|FAILED
---

goal: {What this session accomplished - shown in statusline}
now: {What next session should do first - shown in statusline}
test: {Command to verify this work, e.g., pytest tests/test_foo.py}

done_this_session:
  - task: {First completed task}
    files: [{file1.py}, {file2.py}]
  - task: {Second completed task}
    files: [{file3.py}]

blockers: [{any blocking issues}]

questions: [{unresolved questions for next session}]

decisions:
  - {decision_name}: {rationale}

findings:
  - {key_finding}: {details}

worked: [{approaches that worked}]
failed: [{approaches that failed and why}]

next:
  - {First next step}
  - {Second next step}

files:
  created: [{new files}]
  modified: [{changed files}]

Field guide:

```
goal:
```
+
```
now:
```
- REQUIRED, shown in statusline
```
done_this_session:
```
- What was accomplished with file references
```
decisions:
```
- Important choices and rationale
```
findings:
```
- Key learnings
```
worked:
```
/
```
failed:
```
- What to repeat vs avoid
```
next:
```
- Action items for next session

DO NOT use alternative field names like
session_goal
,
objective
,
focus
,
current
, etc. The statusline parser looks for EXACTLY
goal:
and
now:
- nothing else works.

重要提示：必须严格使用此YAML格式，不得偏离或使用其他字段名称。

goal:

和

now:

字段会显示在状态栏中——它们的名称必须完全一致。

yaml

---
session: {来自记录的会话名称}
date: YYYY-MM-DD
status: complete|partial|blocked
outcome: SUCCEEDED|PARTIAL_PLUS|PARTIAL_MINUS|FAILED
---

goal: {本次会话完成的内容 - 显示在状态栏}
now: {下一次会话应首先执行的操作 - 显示在状态栏}
test: {验证工作的命令，例如：pytest tests/test_foo.py}

done_this_session:
  - task: {第一项已完成任务}
    files: [{file1.py}, {file2.py}]
  - task: {第二项已完成任务}
    files: [{file3.py}]

blockers: [{任何阻塞问题}]

questions: [{留给下一次会话的未解决问题}]

decisions:
  - {决策_name}: {理由}

findings:
  - {关键发现}: {详情}

worked: [{有效的方法}]
failed: [{失败的方法及原因}]

next:
  - {第一个下一步操作}
  - {第二个下一步操作}

files:
  created: [{新建文件}]
  modified: [{修改的文件}]

字段说明：

```
goal:
```
+
```
now:
```
- 必填，显示在状态栏中
```
done_this_session:
```
- 已完成的工作及相关文件引用
```
decisions:
```
- 重要决策及其理由
```
findings:
```
- 关键收获
```
worked:
```
/
```
failed:
```
- 可复用的方法与需避免的方法
```
next:
```
- 下一次会话的行动项

请勿使用
session_goal
、
objective
、
focus
、
current
等替代字段名称。状态栏解析器只会识别完全匹配的
goal:
和
now:
——其他名称均无效。

3. Mark Session Outcome (REQUIRED)

3. 标记会话结果（必填）

IMPORTANT: Before responding to the user, you MUST ask about the session outcome.

Use the AskUserQuestion tool with these exact options:

Question: "How did this session go?"
Options:
  - SUCCEEDED: Task completed successfully
  - PARTIAL_PLUS: Mostly done, minor issues remain
  - PARTIAL_MINUS: Some progress, major issues remain
  - FAILED: Task abandoned or blocked

After the user responds, index and mark the outcome:

bash

undefined

重要提示：在回复用户之前，你必须询问会话结果。

使用AskUserQuestion工具，提供以下确切选项：

Question: "本次会话进展如何？"
Options:
  - SUCCEEDED: 任务成功完成
  - PARTIAL_PLUS: 基本完成，仅存在少量问题
  - PARTIAL_MINUS: 取得部分进展，但存在重大问题
  - FAILED: 任务已放弃或被阻塞

用户回复后，索引并标记结果：

bash

undefined

Mark the most recent handoff (works with PostgreSQL or SQLite)

标记最新的交接文档（支持PostgreSQL或SQLite）

Use git root to find project, then opc/scripts/core/

使用git根目录查找项目，然后进入opc/scripts/core/

PROJECT_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || echo "${CLAUDE_PROJECT_DIR:-.}")

First, index the handoff into the database

首先，将交接文档索引到数据库中

cd "$PROJECT_ROOT/opc" && uv run python scripts/core/artifact_index.py --file thoughts/shared/handoffs/{session_name}/{filename}.yaml

Then mark the outcome

然后标记结果

cd "$PROJECT_ROOT/opc" && uv run python scripts/core/artifact_mark.py --latest --outcome <USER_CHOICE>


**IMPORTANT:** Replace `{session_name}` and `{filename}` with the actual values from step 1.

These commands auto-detect the database (PostgreSQL if configured, SQLite fallback).

**Note:** If indexing fails, the marking step will show "Database marking was not available" - this is acceptable for the first handoff but indicates the indexing step was skipped.

cd "$PROJECT_ROOT/opc" && uv run python scripts/core/artifact_mark.py --latest --outcome <USER_CHOICE>


**重要提示：将`{session_name}`和`{filename}`替换为步骤1中的实际值。**

这些命令会自动检测数据库（已配置则使用PostgreSQL，否则回退到SQLite）。

**注意：如果索引失败，标记步骤会显示“Database marking was not available”——对于首次交接文档，这是可接受的，但表示索引步骤已被跳过。**

4. Confirm completion

4. 确认完成

After marking the outcome, respond to the user:

Handoff created! Outcome marked as [OUTCOME].

Resume in a new session with:
/resume_handoff path/to/handoff.yaml

##. Additional Notes & Instructions

more information, not less. This is a guideline that defines the minimum of what a handoff should be. Always feel free to include more information if necessary.
be thorough and precise. include both top-level objectives, and lower-level details as necessary.
avoid excessive code snippets. While a brief snippet to describe some key change is important, avoid large code blocks or diffs; do not include one unless it's necessary (e.g. pertains to an error you're debugging). Prefer using
```
/path/to/file.ext:line
```
references that an agent can follow later when it's ready, e.g.
```
packages/dashboard/src/app/dashboard/page.tsx:12-24
```

标记结果后，回复用户：

交接文档已创建！结果标记为[OUTCOME]。

在新会话中恢复工作请使用：
/resume_handoff path/to/handoff.yaml

—

补充说明与指引

—

宁多勿少：这是交接文档的最低要求指南。如有必要，随时可以添加更多信息。
全面且精准：既包含顶层目标，也按需包含底层细节。
避免过多代码片段：虽然简短的片段有助于描述关键变更，但应避免大段代码块或差异对比；除非必要（例如与你正在调试的错误相关），否则不要包含。优先使用Agent后续可以跟进的
```
/path/to/file.ext:line
```
引用，例如
```
packages/dashboard/src/app/dashboard/page.tsx:12-24
```

create-handoff

Original

Translation

Create Handoff

创建工作交接文档

Process

流程

1. Filepath & Metadata

1. 文件路径与元数据

2. Write YAML handoff (~400 tokens vs ~2000 for markdown)

2. 编写YAML格式的交接文档（约400个token，相比Markdown的约2000个token更精简）

DO NOT use alternative field names like
`session_goal`
,
`objective`
,
`focus`
,
`current`
, etc. The statusline parser looks for EXACTLY
`goal:`
and
`now:`
- nothing else works.

请勿使用
`session_goal`
、
`objective`
、
`focus`
、
`current`
等替代字段名称。状态栏解析器只会识别完全匹配的
`goal:`
和
`now:`
——其他名称均无效。

3. Mark Session Outcome (REQUIRED)

3. 标记会话结果（必填）

Mark the most recent handoff (works with PostgreSQL or SQLite)

标记最新的交接文档（支持PostgreSQL或SQLite）

Use git root to find project, then opc/scripts/core/

使用git根目录查找项目，然后进入opc/scripts/core/

First, index the handoff into the database

首先，将交接文档索引到数据库中

Then mark the outcome

然后标记结果

4. Confirm completion

4. 确认完成

补充说明与指引

create-handoff

Original

Translation

Create Handoff

创建工作交接文档

Process

流程

1. Filepath & Metadata

1. 文件路径与元数据

2. Write YAML handoff (~400 tokens vs ~2000 for markdown)

2. 编写YAML格式的交接文档（约400个token，相比Markdown的约2000个token更精简）

DO NOT use alternative field names like session_goal, objective, focus, current, etc. The statusline parser looks for EXACTLY goal: and now: - nothing else works.

请勿使用session_goal、objective、focus、current等替代字段名称。 状态栏解析器只会识别完全匹配的goal:和now:——其他名称均无效。

3. Mark Session Outcome (REQUIRED)

3. 标记会话结果（必填）

Mark the most recent handoff (works with PostgreSQL or SQLite)

标记最新的交接文档（支持PostgreSQL或SQLite）

Use git root to find project, then opc/scripts/core/

使用git根目录查找项目，然后进入opc/scripts/core/

First, index the handoff into the database

首先，将交接文档索引到数据库中

Then mark the outcome

然后标记结果

4. Confirm completion

4. 确认完成

补充说明与指引

DO NOT use alternative field names like
`session_goal`
,
`objective`
,
`focus`
,
`current`
, etc. The statusline parser looks for EXACTLY
`goal:`
and
`now:`
- nothing else works.

请勿使用
`session_goal`
、
`objective`
、
`focus`
、
`current`
等替代字段名称。状态栏解析器只会识别完全匹配的
`goal:`
和
`now:`
——其他名称均无效。