skill-status-sync

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Status Sync Skill (Direct Execution)

状态同步Skill（直接执行版）

Direct execution skill for atomic status synchronization across TODO.md and state.json. This skill executes inline without spawning a subagent, avoiding memory issues.

这是一款用于在TODO.md和state.json之间原子化同步状态的直接执行版Skill。该Skill可内联执行，无需生成子Agent，避免内存问题。

Context References

上下文参考

Reference (do not load eagerly):

Path:

.opencode/context/core/patterns/jq-escaping-workarounds.md

- jq escaping patterns (Issue #1132)

参考文档（请勿预加载）：

路径：

.opencode/context/core/patterns/jq-escaping-workarounds.md

- jq转义模式（问题#1132）

Standalone Use Only

仅适用于独立使用

IMPORTANT: This skill is for STANDALONE USE ONLY.

Workflow skills (skill-researcher, skill-planner, skill-implementer, etc.) now handle their own preflight/postflight status updates inline. This eliminates the multi-skill halt boundary problem where Claude may pause between skill invocations.

Use this skill for:

Manual task status corrections
Standalone scripts that need to update task state
Recovery operations when workflow skills fail
Testing status update behavior in isolation

Do NOT use this skill in workflow commands (/research, /plan, /implement, /revise) - those commands now invoke a single skill that handles its own status updates.

重要提示：本Skill仅适用于独立使用场景。

工作流Skill（skill-researcher、skill-planner、skill-implementer等）现在可自行内联处理preflight/postflight状态更新。这消除了Claude可能在Skill调用之间暂停的多Skill中断边界问题。

本Skill的适用场景：

手动修正任务状态
需要更新任务状态的独立脚本
工作流Skill故障时的恢复操作
单独测试状态更新行为

请勿在工作流命令中使用本Skill（/research、/plan、/implement、/revise）——这些命令现在会调用单个Skill，由其自行处理状态更新。

Trigger Conditions

触发条件

This skill activates when:

Manual status correction is needed
Artifacts need to be linked outside normal workflow
Status synchronization recovery is needed between TODO.md and state.json

满足以下条件时激活本Skill：

需要手动修正状态
需要在常规工作流之外关联工件
需要恢复TODO.md和state.json之间的状态同步

API Operations

API操作

This skill exposes three primary operations:

Operation	Purpose	When to Use
`preflight_update`	Set in-progress status	GATE IN checkpoint
`postflight_update`	Set final status + link artifacts	GATE OUT checkpoint
`artifact_link`	Add single artifact link (idempotent)	Post-artifact creation

本Skill提供三个核心操作：

操作	用途	使用场景
`preflight_update`	设置进行中状态	GATE IN检查点
`postflight_update`	设置最终状态并关联工件	GATE OUT检查点
`artifact_link`	添加单个工件链接（幂等操作）	工件创建完成后

Execution

执行流程

1. Input Validation

1. 输入验证

Validate required inputs based on operation type:

For preflight_update:

```
task_number
```
- Must be provided and exist in state.json
```
target_status
```
- Must be an in-progress variant (researching, planning, implementing)
```
session_id
```
- Must be provided for traceability

For postflight_update:

```
task_number
```
- Must be provided and exist
```
target_status
```
- Must be a final variant (researched, planned, implemented, partial)
```
artifacts
```
- Array of {path, type} to link
```
session_id
```
- Must be provided

For artifact_link:

```
task_number
```
- Must be provided and exist
```
artifact_path
```
- Relative path to artifact
```
artifact_type
```
- One of: research, plan, summary

根据操作类型验证必填输入：

针对preflight_update：

```
task_number
```
- 必须提供且在state.json中存在
```
target_status
```
- 必须为进行中状态（researching、planning、implementing）
```
session_id
```
- 必须提供以确保可追溯性

针对postflight_update：

```
task_number
```
- 必须提供且存在
```
target_status
```
- 必须为最终状态（researched、planned、implemented、partial）
```
artifacts
```
- 包含{path, type}的数组，用于关联工件
```
session_id
```
- 必须提供

针对artifact_link：

```
task_number
```
- 必须提供且存在
```
artifact_path
```
- 工件的相对路径
```
artifact_type
```
- 可选值：research、plan、summary

2. Execute Operation Directly

2. 直接执行操作

Route to appropriate operation and execute using Bash (jq) and Edit tools.

路由到对应操作，使用Bash（jq）和编辑工具执行。

Operation: preflight_update

操作：preflight_update

Purpose: Set in-progress status at GATE IN checkpoint

Execution:

Validate task exists:

bash

task_data=$(jq -r --arg num "{task_number}" \
  '.active_projects[] | select(.project_number == ($num | tonumber))' \
  specs/state.json)

if [ -z "$task_data" ]; then
  echo "Error: Task {task_number} not found"
  exit 1
fi

Update state.json:

bash

jq --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" --arg status "{target_status}" \
  '(.active_projects[] | select(.project_number == {task_number})) |= . + {
    status: $status,
    last_updated: $ts
  }' specs/state.json > /tmp/state.json && mv /tmp/state.json specs/state.json

Update TODO.md status marker:
- Find task entry:
```
grep -n "^### {task_number}\." specs/TODO.md
```
- Use Edit tool to change
```
[OLD_STATUS]
```
  to
```
[NEW_STATUS]
```

Status Mapping:

state.json	TODO.md
not_started	[NOT STARTED]
researching	[RESEARCHING]
planning	[PLANNING]
implementing	[IMPLEMENTING]

Return: JSON object with status "synced" and previous/new status fields.

用途：在GATE IN检查点设置进行中状态

执行步骤：

验证任务存在：

bash

task_data=$(jq -r --arg num "{task_number}" \
  '.active_projects[] | select(.project_number == ($num | tonumber))' \
  specs/state.json)

if [ -z "$task_data" ]; then
  echo "Error: Task {task_number} not found"
  exit 1
fi

更新state.json：

bash

jq --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" --arg status "{target_status}" \
  '(.active_projects[] | select(.project_number == {task_number})) |= . + {
    status: $status,
    last_updated: $ts
  }' specs/state.json > /tmp/state.json && mv /tmp/state.json specs/state.json

更新TODO.md状态标记：
- 查找任务条目：
```
grep -n "^### {task_number}\." specs/TODO.md
```
- 使用编辑工具将
```
[OLD_STATUS]
```
  修改为
```
[NEW_STATUS]
```

状态映射：

state.json	TODO.md
not_started	[NOT STARTED]
researching	[RESEARCHING]
planning	[PLANNING]
implementing	[IMPLEMENTING]

返回结果：包含status为"synced"以及之前/新状态字段的JSON对象。

Operation: postflight_update

操作：postflight_update

Purpose: Set final status and link artifacts at GATE OUT checkpoint

Execution:

Update state.json status and timestamp:

bash

jq --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" --arg status "{target_status}" \
  '(.active_projects[] | select(.project_number == {task_number})) |= . + {
    status: $status,
    last_updated: $ts
  }' specs/state.json > /tmp/state.json && mv /tmp/state.json specs/state.json

Add artifacts to state.json (for each artifact):

IMPORTANT: Use two-step jq pattern to avoid Issue #1132 escaping bug. See

jq-escaping-workarounds.md

bash

undefined

用途：在GATE OUT检查点设置最终状态并关联工件

执行步骤：

更新state.json的状态和时间戳：

bash

jq --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" --arg status "{target_status}" \
  '(.active_projects[] | select(.project_number == {task_number})) |= . + {
    status: $status,
    last_updated: $ts
  }' specs/state.json > /tmp/state.json && mv /tmp/state.json specs/state.json

向state.json添加工件（每个工件执行一次）：

重要提示：使用两步jq模式避免问题#1132中的转义错误。请参考

jq-escaping-workarounds.md

。

bash

undefined

Step 1: Update timestamp

jq --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
'(.active_projects[] | select(.project_number == {task_number})) |= . + { last_updated: $ts }' specs/state.json > /tmp/state.json && mv /tmp/state.json specs/state.json

Step 2: Add artifact (append to array)

jq --arg path "{artifact_path}"
--arg type "{artifact_type}"
'(.active_projects[] | select(.project_number == {task_number})).artifacts += [{"path": $path, "type": $type}]'
specs/state.json > /tmp/state.json && mv /tmp/state.json specs/state.json


3. **Update TODO.md status marker**:
   - Use Edit to change status: `[RESEARCHING]` -> `[RESEARCHED]`

4. **Link artifacts in TODO.md**:
   - Add research/plan/summary links in appropriate location

**Status Mapping**:
| state.json | TODO.md |
|------------|---------|
| researched | [RESEARCHED] |
| planned | [PLANNED] |
| implemented | [IMPLEMENTED] |
| partial | [PARTIAL] |

**Return**: JSON object with target_status and artifacts_linked fields.

---


3. **更新TODO.md状态标记**：
   - 使用编辑工具修改状态：`[RESEARCHING]` -> `[RESEARCHED]`

4. **在TODO.md中关联工件**：
   - 在对应位置添加研究/计划/总结链接

**状态映射**：
| state.json | TODO.md |
|------------|---------|
| researched | [RESEARCHED] |
| planned | [PLANNED] |
| implemented | [IMPLEMENTED] |
| partial | [PARTIAL] |

**返回结果**：包含target_status和artifacts_linked字段的JSON对象。

---

Operation: artifact_link

操作：artifact_link

Purpose: Add single artifact link (idempotent)

Execution:

Idempotency check:

bash

if grep -A 30 "^### {task_number}\." specs/TODO.md | grep -q "{artifact_path}"; then
  echo "Link already exists"
  # Return "skipped" status
fi

Add to state.json artifacts array:

IMPORTANT: Use two-step jq pattern to avoid Issue #1132 escaping bug. See

jq-escaping-workarounds.md

bash

undefined

用途：添加单个工件链接（幂等操作）

执行步骤：

幂等性检查：

bash

if grep -A 30 "^### {task_number}\." specs/TODO.md | grep -q "{artifact_path}"; then
  echo "Link already exists"
  # Return "skipped" status
fi

向state.json的artifacts数组添加条目：

重要提示：使用两步jq模式避免问题#1132中的转义错误。请参考

jq-escaping-workarounds.md

。

bash

undefined

Step 1: Update timestamp

Step 2: Add artifact (append to array)


3. **Add link to TODO.md** using Edit tool:

**Strip specs/ prefix** (TODO.md is inside specs/): `todo_link_path="${path#specs/}"`

| Type | Format in TODO.md |
|------|-------------------|
| research | `- **Research**: [research-{NNN}.md]({todo_link_path})` |
| plan | `- **Plan**: [implementation-{NNN}.md]({todo_link_path})` |
| summary | `- **Summary**: [implementation-summary-{DATE}.md]({todo_link_path})` |

**Insertion order**:
- research: after Language line
- plan: after Research line (or Language if no Research)
- summary: after Plan line

**Return**: JSON object with status "linked" or "skipped".

---


3. **使用编辑工具在TODO.md中添加链接**：

**移除specs/前缀**（TODO.md位于specs/目录下）：`todo_link_path="${path#specs/}"`

| 类型 | TODO.md中的格式 |
|------|-------------------|
| research | `- **Research**: [research-{NNN}.md]({todo_link_path})` |
| plan | `- **Plan**: [implementation-{NNN}.md]({todo_link_path})` |
| summary | `- **Summary**: [implementation-summary-{DATE}.md]({todo_link_path})` |

**插入顺序**：
- research：在Language行之后
- plan：在Research行之后（若无Research则在Language行之后）
- summary：在Plan行之后

**返回结果**：包含status为"linked"或"skipped"的JSON对象。

---

Return Format

返回格式

preflight_update returns:

preflight_update返回结果：

json

{
  "status": "synced",
  "summary": "Updated task #{N} to [{STATUS}]",
  "previous_status": "not_started",
  "new_status": "researching"
}

json

{
  "status": "synced",
  "summary": "Updated task #{N} to [{STATUS}]",
  "previous_status": "not_started",
  "new_status": "researching"
}

postflight_update returns:

postflight_update返回结果：

json

{
  "status": "{target_status}",
  "summary": "Updated task #{N} to [{STATUS}] with {M} artifacts",
  "artifacts_linked": ["path1", "path2"],
  "previous_status": "researching",
  "new_status": "researched"
}

json

{
  "status": "{target_status}",
  "summary": "Updated task #{N} to [{STATUS}] with {M} artifacts",
  "artifacts_linked": ["path1", "path2"],
  "previous_status": "researching",
  "new_status": "researched"
}

artifact_link returns:

artifact_link返回结果：

json

{
  "status": "linked|skipped",
  "summary": "Linked artifact to task #{N}" | "Link already exists",
  "artifact_path": "path/to/artifact.md",
  "artifact_type": "research"
}

json

{
  "status": "linked|skipped",
  "summary": "Linked artifact to task #{N}" | "Link already exists",
  "artifact_path": "path/to/artifact.md",
  "artifact_type": "research"
}

Error Handling

错误处理

Task Not Found

任务未找到

Return failed status with recommendation to verify task number.

返回失败状态，并建议验证任务编号。

Invalid Status Transition

无效状态转换

Return failed status with current status and allowed transitions.

返回失败状态，同时返回当前状态和允许的转换。

File Write Failure

文件写入失败

Return failed status with recommendation to check permissions.

返回失败状态，并建议检查权限。

jq Parse Failure

jq解析失败

If jq commands fail with INVALID_CHARACTER or syntax error (Issue #1132):

Log to errors.json with session_id and original command
Retry with two-step pattern from
```
jq-escaping-workarounds.md
```
If retry succeeds, log recovery action

如果jq命令因INVALID_CHARACTER或语法错误失败（问题#1132）：

记录到errors.json，包含session_id和原始命令
使用
```
jq-escaping-workarounds.md
```
中的两步模式重试
如果重试成功，记录恢复操作

Integration Notes

集成说明

For Workflow Commands: Do NOT use this skill directly. Workflow skills now handle their own status updates inline.

For Manual Operations: Use this skill for standalone status corrections:

undefined

针对工作流命令：请勿直接使用本Skill。工作流Skill现在可自行处理状态更新。

针对手动操作：使用本Skill进行独立状态修正：

undefined

Manual Status Correction

手动状态修正

Invoke skill-status-sync with:

operation: preflight_update or postflight_update
task_number: {N}
target_status: {valid_status}
session_id: manual_correction
artifacts: [{path, type}, ...] (for postflight only)


This skill ensures:
- Atomic updates across both files
- Consistent jq/Edit patterns
- Proper error handling
- Direct execution without subagent overhead

调用skill-status-sync时传入：

operation: preflight_update或postflight_update
task_number: {N}
target_status: {valid_status}
session_id: manual_correction
artifacts: [{path, type}, ...]（仅postflight操作需要）


本Skill可确保：
- 两个文件之间的原子化更新
- 一致的jq/编辑模式
- 完善的错误处理
- 无需子Agent开销的直接执行