---

name: task-planning description: Use this bundled skill to create, update, and clear the in-memory todo state required before real bundled tool calls when task planning is enabled. metadata: short-description: Lightweight todo planning workflow

Task Planning

Use this skill when bundled tool calls require a plan. The gateway stores a lightweight in-memory plan state per client/session and per content-derived planningId. It does not persist plans across gateway restarts and it does not render UI.

Workflow

1. First read this complete SKILL.md and use the returned skillToken.
2. Before a real bundled tool call, call task-planning with action: "update" and the current todo list.
3. Use the returned planningId on the next real bundled tool call.
4. Reuse the same planningId across multiple tool calls while working through the plan. It does not expire after successful tool calls.
5. Do not update the plan after every tool call just because a tool ran. A single plan step may require many tool calls.
6. The gateway may include a single planningReminder field on successful bundled tool results. It only refers to the current in_progress item and may include a concise set_status call to mark that item completed.
7. If the same planningId uses shell_command three or more times in a row without a plan update or another successful bundled tool, the gateway may include shellCommandReminder. Use it as a nudge to combine related shell commands, read multiple files in one pass when useful, or prefer efficient search commands such as rg and rg --files. A shell command that starts with rg resets this counter.
8. If multi_edit_file fails three or more times in a row for the same planningId, the gateway may include editFailureReminder. Use it as a nudge to inspect exact file content, simplify the operation, split unrelated changes, or fall back to a focused shell script when structured edits keep failing.
9. If the approach or step list changes, call action: "update" with the new plan and use the returned new planningId. Stop using the old planningId; clear it if needed.
10. Use action: "set_status" for simple state changes. If item is omitted, it updates the current in_progress item. When that item is set to completed and pending items remain, the gateway automatically starts the next pending item as in_progress and returns it as nextItem.
11. When every plan item is updated to completed, the gateway closes that planningId and it can no longer be used for real bundled tool calls. Then omit the temporary todo list from the final response unless the user asks for it.

Status Values

Use these status labels when showing a checklist:

• pending - not started yet
• in_progress - currently being worked on
• completed - finished and no longer active

Suggested Format

{
  "action": "update",
  "explanation": "Starting the implementation",
  "plan": [
    { "step": "Inspect existing skill registration", "status": "completed" },
    { "step": "Add the planning gate", "status": "in_progress" },
    { "step": "Run focused tests", "status": "pending" }
  ],
  "skillToken": "<token from this SKILL.md>"
}

The response includes:

{
  "planning": {
    "planningId": "plan-..."
  }
}

Pass those fields to the next real bundled tool call:

{
  "planningId": "plan-..."
}

For concise status updates, prefer set_status instead of sending the full plan again:

{
  "action": "set_status",
  "planningId": "plan-...",
  "status": "completed",
  "skillToken": "<token from this SKILL.md>"
}

That marks the current in_progress item as completed. If more work remains, the response includes nextItem; continue with that item using the same planningId. To update a specific array item, use a 1-based item number:

{
  "action": "set_status",
  "planningId": "plan-...",
  "item": 2,
  "status": "in_progress",
  "skillToken": "<token from this SKILL.md>"
}

For final responses, summarize what changed and any verification performed. Do not keep the planning checklist in the final answer unless the user explicitly asks for it.