技能规划师

工程开发 社区

技能解读

当前原文的自动摘译,尚未人工审校。

上下文参考

参考(不要急于加载): .claude/context/formats/return-metadata-file.md - 元数据文件模式 .claude/context/patterns/postflight-control.md - 标记文件协议 .claude/context/patterns/jq-escaping-workarounds.md - jq 转义模式(问题#1132)

第 2 阶段:预检状态更新

如果脚本以非零值退出,则停止执行。退出代码 2 = state.json 失败;退出代码 3 = TODO.md 失败。

第 3a 阶段:计算工件数量

Planner 使用“prev”模式——与之前的研究共享同一轮。注意:计划不会增加next_artifact_number。只有研究才能推进顺序。

阶段 4a:内存检索(自动)

如果clean_flag为真则跳过。

第 4 阶段:准备委托上下文

尽早提取orchestrator_mode:先前的计划发现:查找最新的现有计划文件(如果有)以作为参考上下文传递。为子代理准备委派上下文:模型/工作量标志:将 model_flag 作为代理工具上的 model 参数(如果已设置)传递。包括effort_flag 作为推理深度的提示上下文(如果设置)。

流狐档案 运行与权限由流狐静态检查推断,不代表作者声明或实际测试结果。
领域
工程开发
作者声明的智能体
未找到明确声明;不据此推断已兼容或已测试
静态检查
88 / 100 · 启发式扫描,不代表运行安全
运行环境证据
未执行;当前没有隔离运行测试证据
作者 / 版本 / 许可证
@benbrastmckie · 未声明许可证
上下文用量评级
低消耗
接入复杂程度
需简单配置
是否需要外部接口密钥
不需要
兼容的系统
未声明(默认跨平台)
运行环境要求
未检出明确要求
检测到的文件与系统行为
  • 只读
  • 允许写入 / 修改
  • 命令执行
网络行为
仅限本地
安装命令数
无(仅作为资料)

需要注意: 未声明工具权限范围;实际权限由运行环境决定。

作者说明文件(原文) SKILL.md

# Planner Skill

Thin wrapper that delegates plan creation to `planner-agent` subagent.

**IMPORTANT**: Skill-internal postflight pattern — this skill handles all postflight operations after
the subagent returns, eliminating the "continue" prompt issue.

## Context References

Reference (do not load eagerly):
- `.claude/context/formats/return-metadata-file.md` - Metadata file schema
- `.claude/context/patterns/postflight-control.md` - Marker file protocol
- `.claude/context/patterns/jq-escaping-workarounds.md` - jq escaping patterns (Issue #1132)

---

## Execution Flow

### Stage 1: Input Validation

```bash
source .claude/scripts/skill-base.sh
skill_validate_input "$task_number"
# Exports: TASK_TYPE, TASK_STATUS, PROJECT_NAME, DESCRIPTION, PADDED_NUM, TASK_DIR
```

### Stage 2: Preflight Status Update

```bash
skill_preflight_update "$task_number" "plan" "$session_id"
```

If the script exits non-zero, stop execution. Exit code 2 = state.json failure; exit code 3 = TODO.md failure.

### Stage 3: Create Postflight Marker

```bash
skill_create_postflight_marker "$PADDED_NUM" "$PROJECT_NAME" "$session_id" "skill-planner" "plan"
```

### Stage 3a: Calculate Artifact Number

Planner uses "prev" mode — shares the same round as the preceding research.

```bash
skill_read_artifact_number "$task_number" "$PADDED_NUM" "$PROJECT_NAME" "plans/" "prev"
# Exports: ARTIFACT_NUMBER, ARTIFACT_PADDED
```

**Note**: Plan does NOT increment `next_artifact_number`. Only research advances the sequence.

### Stage 4a: Memory Retrieval (Auto)

Skip if `clean_flag` is true.

```bash
memory_context=""
if [ "$clean_flag" != "true" ]; then
  memory_context=$(bash .claude/scripts/memory-retrieve.sh "$DESCRIPTION" "$TASK_TYPE" "" 2>/dev/null) || memory_context=""
fi
```

### Stage 4: Prepare Delegation Context

Extract orchestrator_mode early:

```bash
orchestrator_mode=$(echo "$delegation_context" | jq -r '.orchestrator_mode // "false"' 2>/dev/null || echo "false")
```

**Prior plan discovery**: Find the latest existing plan file (if any) to pass as reference context.

```bash
prior_plan_path=$(ls -1 "specs/${PADDED_NUM}_${PROJECT_NAME}/plans/"*.md 2>/dev/null | sort -V | tail -1)
# prior_plan_path will be empty if no prior plans exist
```

Prepare delegation context for the subagent:

```json
{
  "session_id": "sess_{timestamp}_{random}",
  "delegation_depth": 1,
  "delegation_path": ["orchestrator", "plan", "skill-planner"],
  "timeout": 1800,
  "task_context": {
    "task_number": N,
    "task_name": "{PROJECT_NAME}",
    "description": "{DESCRIPTION}",
    "task_type": "{TASK_TYPE}"
  },
  "artifact_number": "{ARTIFACT_PADDED}",
  "effort_flag": "{effort_flag or null}",
  "model_flag": "{model_flag or null}",
  "orchestrator_mode": false,
  "roadmap_flag": "{roadmap_flag or false}",
  "research_path": "{path to research report if exists}",
  "prior_plan_path": "{prior_plan_path or empty}",
  "roadmap_path": "specs/ROADMAP.md",
  "metadata_file_path": "specs/{NNN}_{SLUG}/.return-meta.json"
}
```

**Model/Effort Flags**: Pass `model_flag` as `model` parameter on the Agent tool if set. Include `effort_flag` as prompt context for reasoning depth if set.

### Stage 4b: Read and Inject Format Specification

```bash
format_content=$(cat .claude/context/formats/plan-format.md)
```

### Stage 5: Invoke Subagent

**CRITICAL**: Use the **Agent** tool (`subagent_type: "planner-agent"`).

Build the prompt with these blocks in order:
1. Delegation context JSON
2. `<artifact-format-specification>` block with `{format_content}` (Plan Format Requirements)
3. `{memory_context}` block (only if non-empty; already wrapped in `<memory-context>` tags)
4. Task-specific instructions

**DO NOT** use `Skill(planner-agent)` or `Agent(subagent_type: "Plan")` — `Plan` is a built-in read-only subagent that CANNOT write files.

### Stage 5b: Self-Execution Fallback

If you performed work WITHOUT using the Agent tool, write `.return-meta.json` with status `"planned"` before proceeding to postflight. If you used the Agent tool, skip this stage.

---

## Postflight (ALWAYS EXECUTE)

### Stage 6: Read Metadata File

```bash
source .claude/scripts/skill-base.sh
skill_read_metadata "$PADDED_NUM" "$PROJECT_NAME"
# Exports: SUBAGENT_STATUS, ARTIFACT_PATH, ARTIFACT_TYPE, ARTIFACT_SUMMARY, MEMORY_CANDIDATES
```

### Stage 6a: Validate Artifact Content

```bash
skill_validate_artifact "$SUBAGENT_STATUS" "$ARTIFACT_PATH" "plan"
```

### Stage 7: Update Task Status (Postflight)

```bash
# Step 1: Update status
skill_postflight_update "$task_number" "plan" "$session_id" "$SUBAGENT_STATUS"

# Step 2: Write orchestrator handoff (only if orchestrator_mode=true)
skill_write_orchestrator_handoff "$orchestrator_mode" "$PADDED_NUM" "$PROJECT_NAME" \
  "plan" "$SUBAGENT_STATUS" "$ARTIFACT_SUMMARY" "$ARTIFACT_PATH" "$ARTIFACT_TYPE" "implement"
```

**On partial/failed**: `skill_postflight_update` skips non-success statuses — status remains "planning" for resume.

### Stage 8: Link Artifacts

```bash
skill_link_artifacts "$task_number" "$ARTIFACT_PATH" "$ARTIFACT_TYPE" "$ARTIFACT_SUMMARY" '**Plan**' '**Description**'
```

### Stage 9: Git Commit

```bash
git add -A
git commit -m "task ${task_number}: create implementation plan

Session: ${session_id}"
```

### Stage 10: Cleanup

```bash
skill_cleanup "$PADDED_NUM" "$PROJECT_NAME"
```

### Stage 11: Return Brief Summary

Return a brief text summary (NOT JSON):
```
Plan created for task {N}:
- {phase_count} phases defined, {estimated_hours} hours estimated
- Created plan at specs/{NNN}_{SLUG}/plans/MM_{short-slug}.md
- Status updated to [PLANNED]
- Changes committed
```

---

## Error Handling

- **Task not found or terminal state**: Exit immediately with error
- **Metadata missing**: Keep status "planning", do not cleanup marker, report error
- **Git commit failure**: Non-blocking (log and continue)
- **jq parse failure** (Issue #1132): Log to errors.json, retry with two-step pattern (already in skill_link_artifacts)
- **Subagent timeout**: Return partial; keep status "planning" for resume

---

## MUST NOT (Postflight Boundary)

After the agent returns, MUST NOT: edit source files, run build/test, use research tools, analyze task requirements, or write plan files.

Postflight is LIMITED TO: reading metadata, calling update-task-status.sh, linking artifacts, git commit, cleanup.

Reference: @.claude/context/standards/postflight-tool-restrictions.md

讨论

基于 GitHub Discussions。登录 GitHub 即可参与讨论、点赞、订阅更新。