SuperAPI AI Directory

workflow

Coding & development

View repository

Updated 10-16 02:35

About this skill

Workflow Runner

Execute the workflow defined in .workflows/<name>/workflow.md , advancing stage by stage until all are complete. Usage:/workflow <name>。

Coordinator role — CRITICAL

CRITICAL: During the workflow run, you are the coordinator, not the executor.

When the stage's subagent is non-empty:

  • MUST Delegate via the Agent tool
  • MUST NOT Use Edit/Write on the project source code (except stages.json)
  • If you find yourself writing business code,stop immediately, and call Agent instead

When subagent is empty: handle it yourself (conversation, coordination, lightweight operations).

Lifecycle

1. Initialization

Read workflow.md, parse it into a stages array, and write stages.json.

Write path: ~/.talos/<workspace>/<workflowName>/$CLAUDE_CODE_SESSION_ID/stages.json

  • <workspace> = current project directory name (basename "$PWD")
  • For the directory name, use $CLAUDE_CODE_SESSION_IDdirectly (i.e., the current session ID); no additional generation is needed
  • Ensure the directory exists before writing

stages.json top-level structure:

{
  "workflowName": "default",
  "title": "简短、有意义的工作流标题",
  "stages": [
    {
      "stage": -1,
      "name": "prepare 名称",
      "desc": "...",
      "status": "pending",
      "summary": null,
      "subagent": null
    },
    {
      "stage": 0,
      "name": "stage 名称",
      "desc": "...",
      "status": "pending",
      "summary": null,
      "subagent": ["agent-name"]  // 正文中 "委托 **X** agent" → ["X"],没有则 null
    }
  ]
}

Optional prepare section: If workflow.md contains a section starting with ## prepare — <name> , parse it as a special entry and write it as the first item of the stages array:{ "stage": -1, "name": "<name>", "desc": "<正文>", "status": "pending", "subagent": null }. The prepare subagent is always empty—the coordinator handles it itself and does not delegate. Workflows without this section do not generate this entry, and the lifecycle is unchanged.

title generation rule: Understand the user's intent and summarize in one sentence what this workflow is to do.

status enum values:pending(waiting),running(in progress),skipped(skipped),completed(complete).

1.5 Preparation (only when a prepare entry exists)

  1. Set prepare's status to runningand write stages.json.
  2. According to prepare's desc description, the coordinator itself performs environment preparation (e.g., reading context, updating stages.json top-level fields, creating a branch/worktree, switching directories, etc.). In this phase, the coordinatormay onlyperform environment preparation operations, and must not write business code.
  3. Self-check: verify whether the preparation artifacts declared in desc are ready.
  4. If passed, mark status as completedand write summary; if not passed, report to the user and wait.

2. Execution loop

Only when stage -1 exists in the stages array, the execution loop should start only after its status is completed or skipped . Workflows without prepare start directly from the first numbered stage.

Execute each stage in order:

  1. Pre-check — Confirm that the previous stage's status is completed or skipped. Stage 1 skips this check. If the previous stage does not satisfy this, do not continue advancing; report the current status and let the user decide.
  2. Set status — Before entering the stage, first update that stage's status to "running", and write stages.json.
  3. Evaluate skip — Based on the skip condition for that stage in workflow.md ("skip when XX") and the current context, determine whether to skip. If the condition is clearly satisfied, mark status: "skipped", and state the skip reason in the summary. If unsure, ask the user.
  4. Announce — Tell the user which stage is about to be executed and how it will be executed (which agent it is delegated to / handled by yourself).
  5. Execute — Execute the stage in the announced manner. When delegating via the Agent tool, always require in the prompt that the subagent first load the memorizer skill.
  6. Self-check — Re-read the desc of the current stage, and check item by item whether the completion criteria are met. Do not assume that finishing execution means completion—verify whether the deliverables exist and whether they meet the requirements of the desc.
  7. Update status — After the self-check passes, mark status: "completed", write to summary. If it does not pass, report what is missing and ask the user how to proceed.

3. Completion

After all stages pass:

  • Report to the user that the workflow as a whole is complete
  • List a summary of the artifacts produced by all stages

Memo

When delegating a subagent via the Agent tool, always include in the prompt:

"Use the memorizer skill to obtain the ability to read from and write to memory; when the task is complete, state whether memory needs to be written."

Rules

  • workflow.md is the single source of truth
  • When encountering an error, report to the user first before continuing