技能状态同步
- 作者仓库星标 435
- 作者仓库 nvim
- 领域
- 效率工具
- 作者声明的智能体
- 未找到明确声明;不据此推断已兼容或已测试
- 静态检查
- 88 / 100 · 启发式扫描,不代表运行安全
- 运行环境证据
- 未执行;当前没有隔离运行测试证据
- 作者 / 版本 / 许可证
- @benbrastmckie · 未声明许可证
- 上下文用量评级
- 低消耗
- 接入复杂程度
- 需简单配置
- 是否需要外部接口密钥
- 不需要
- 兼容的系统
- 未声明(默认跨平台)
- 运行环境要求
- 未检出明确要求
- 检测到的文件与系统行为
-
- 只读
- 允许写入 / 修改
- 命令执行
- 网络行为
- 仅限本地
- 安装命令数
- 无(仅作为资料)
需要注意: 未声明工具权限范围;实际权限由运行环境决定。
# Status Sync Skill (Direct Execution)
Direct execution skill for atomic status synchronization across TODO.md and state.json. This skill executes inline without spawning a subagent, avoiding memory issues.
## Context References
Reference (do not load eagerly):
- Path: `.claude/context/patterns/jq-escaping-workarounds.md` - jq escaping patterns (Issue #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.
## 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
## API Operations
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 |
---
## Execution
### 1. Input Validation
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
### 2. Execute Operation Directly
Route to appropriate operation and execute using Bash (jq) and Edit tools.
---
## Operation: preflight_update
**Purpose**: Set in-progress status at GATE IN checkpoint
**Execution**:
1. **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
```
2. **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 > specs/tmp/state.json && mv specs/tmp/state.json specs/state.json
```
3. **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.
---
## Operation: postflight_update
**Purpose**: Set final status and link artifacts at GATE OUT checkpoint
**Execution**:
1. **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 > specs/tmp/state.json && mv specs/tmp/state.json specs/state.json
```
2. **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
# 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 > specs/tmp/state.json && mv specs/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 > specs/tmp/state.json && mv specs/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.
---
## Operation: artifact_link
**Purpose**: Add single artifact link (idempotent)
**Execution**:
1. **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
```
2. **Add to state.json artifacts array**:
**IMPORTANT**: Use two-step jq pattern to avoid Issue #1132 escaping bug. See `jq-escaping-workarounds.md`.
```bash
# 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 > specs/tmp/state.json && mv specs/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 > specs/tmp/state.json && mv specs/tmp/state.json specs/state.json
```
3. **Add link to TODO.md** using Edit tool:
| Type | Format in TODO.md |
|------|-------------------|
| research | Count-aware format (see "Artifact Linking Format" in state-management.md) |
| plan | Count-aware format (see "Artifact Linking Format" in state-management.md) |
| summary | Count-aware format (see "Artifact Linking Format" in state-management.md) |
**Count-Aware Logic**: Use inline format for 1 artifact, multi-line list for 2+. See state-management.md for detection patterns and insertion examples.
**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".
---
## Return Format
### preflight_update returns:
```json
{
"status": "synced",
"summary": "Updated task #{N} to [{STATUS}]",
"previous_status": "not_started",
"new_status": "researching"
}
```
### postflight_update returns:
```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:
```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
If jq commands fail with INVALID_CHARACTER or syntax error (Issue #1132):
1. Log to errors.json with session_id and original command
2. Retry with two-step pattern from `jq-escaping-workarounds.md`
3. If retry succeeds, log recovery action
---
## 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:
```
### 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
章节与文件索引
按说明文件中的顺序排列。
上下文参考
仅供独立使用
触发条件
API操作
1. 输入验证
文件/命令 -> .claude/context/patterns/jq-escaping-workarounds.md · preflight_update · postflight_update · artifact_link · task_number · target_status · session_id · artifacts
内容校验值 -> 1e12076678f0
当前原文的自动摘译,尚未人工审校。
上下文参考
参考(不要急于加载):路径:
.claude/context/patterns/jq-escaping-workarounds.md- jq 转义模式(问题#1132)仅供独立使用
重要提示:此技能仅供独立使用。工作流程技能(技能研究员、技能规划者、技能实施者等)现在可以内联处理自己的飞行前/飞行后状态更新。这消除了克劳德可能在技能调用之间暂停的多技能暂停边界问题。将此技能用于: 手动任务状态更正 需要更新任务状态的独立脚本
触发条件
该技能在以下情况下激活: 需要手动状态更正 工件需要在正常工作流程之外进行链接 TODO.md 和 state.json 之间需要状态同步恢复
API操作
该技能公开了三个主要操作: 操作 · 目的 · 何时使用
preflight_update· 设置进行中状态 · GATE IN 检查点postflight_update· 设置最终状态 + 链接工件 · GATE OUT 检查点artifact_link· 添加单个工件链接(幂等) · 后工件创建1. 输入验证
根据操作类型验证所需的输入: 对于 preflight_update:
task_number- 必须提供并存在于 state.json 中target_status- 必须是正在进行的变体(研究、规划、实施)session_id- 必须提供以实现可追溯性