Workflow 定义

你在仪表盘里定义和编辑 workflow：打开 Configuration → Workflows，每个 workflow 都是 一份带名字、有序的步骤列表，按用户和 workspace 存储。这才是运行时的事实来源。

workflows/ 目录里的 *.toml 文件（相对于你的 config.toml）是默认值。 Takuto Core 第一次遇到某个新用户/workspace 时，会用它们为该 workspace 播种 workflow； 事后再改 TOML 不会改变已经播种好的 workflow —— 那些要在仪表盘里改。你的默认值可以从 Takuto Core 仓库 附带的示例起步：

cp workflows/implement_ticket.example.toml workflows/implement_ticket.toml

本页其余部分记录的就是这份 TOML 的结构 —— 它既是播种文件的格式，也是你在仪表盘里 编辑那些相同字段时的一份便捷参考。

文件结构

每个文件都有一个顶层 name、一个可选的 depends_on，以及一个或多个 [[steps]]：

name = "Implement Ticket"

[[steps]]
name = "Implement ticket"
prompt = """
Follow the instructions below:
{description}
"""
repeat = 1

步骤字段

用 depends_on 串联 workflow

带 depends_on = ["implement_ticket"] 的定义，只有在 implement_ticket flow 完成 之后才会在 workflow 卡片上变得可用。“Merge base branch” 和 “Address PR comments” 这两个后续操作就是这样接线的 —— 主 flow 一旦完成，它们便在同一个 worktree 里运行。

prompt 占位符

这些是 Takuto Core 的运行时占位符 —— 单花括号。 在你的 prompt 里照原样写。 它们与本站的构建 token 无关。

lint、测试和提交 PR 都是 agent 步骤 prompt，不是引擎步骤。一个打印 MAESTRO_PR_URL: <url> 或写入 .takuto/outcome.toml 的步骤，能让 Takuto Core 记录 PR URL 并呈现 Address PR Comments 操作。

三个示例 workflow

setup 向导（以及示例文件夹）附带三个开箱即用的定义。

1. implement_ticket.toml —— 主流水线

一条完整的 实现 → 评审 → 提交 → lint/测试 → PR 流水线。注意那两个由 when 门控的 Implement ticket 步骤：一个用于无工单系统模式（使用 {description}），一个用于有 工单系统模式（从 system prompt 读取工单）。

name = "Implement Ticket"

# 实现（无工单系统）
[[steps]]
name = "Implement ticket"
prompt = """
Follow the instructions provided below:
{description}

BOUNDARIES: This step covers implementation only.
- Do NOT commit any changes — a dedicated "Commit changes" step follows.
- Do NOT create a PR — a dedicated "Create PR" step follows.

SCOPE CONSTRAINT: Only implement what is explicitly described above. Do not refactor
unrelated code; leave a # TODO if you spot something out of scope.
"""
when = "no_ticketing"
repeat = 1

# 实现（有工单系统）
[[steps]]
name = "Implement ticket"
prompt = """
Follow the instructions in the system prompt.
(same boundaries and scope rules as above)
"""
when = "ticketing"
repeat = 1

# 评审改动 —— 运行两次
[[steps]]
name = "Review changes"
prompt = """
Ticket context:
{ticket_context}

Review all changes on this branch relative to `{base_branch}`
(i.e. `git diff {base_branch}...HEAD`). Only address issues in code changed for this
ticket. Confirm each finding is genuine before fixing it. Do not create a PR.
"""
repeat = 2

# 提交改动
[[steps]]
name = "Commit changes"
prompt = """
Commit the work into logical, conventional commits. Never run git checkout/restore/
reset/clean/stash — only create commits. Do not create a PR.
"""
repeat = 1

# lint 和测试
[[steps]]
name = "Lint and test"
prompt = """
Run the project's linter and fix all issues; run the test suite and fix failures
(never delete or skip tests); run the formatter. Commit with
`chore: fix lint warnings, format, and failing tests`. Do not create a PR.
"""
repeat = 1

# 创建 PR —— 通过 create-pr skill
[[steps]]
name = "Create PR"
prompt = """
Ticket context:
{ticket_context}

The PR title must be a conventional commit message and must not contain the workflow
name, branch name, or ticket ID.
"""

[[steps.skills]]
name = "create-pr"
args = ["--no-draft"]
repeat = 1

2. address_pr_comments.toml —— 评审循环

依赖 implement_ticket。用 {pr_url} 拉取未解决的评审评论，修复它们，然后重新跑 lint/测试。

name = "Address PR Comments"
depends_on = ["implement_ticket"]

[[steps]]
name = "Fix review comments"
prompt = """
Pull request URL: {pr_url}

Ticket context:
{ticket_context}

Retrieve all unresolved PR review comments. For each: make the change, verify it
locally, commit with a descriptive message, and push to the PR branch. Do not bypass
linting or tests.
"""
repeat = 1

[[steps]]
name = "Lint and test"
prompt = """
Run the linter, test suite, and formatter; fix all issues; commit with
`chore: fix lint warnings, format, and failing tests`.
"""
repeat = 1

3. merge_base.toml —— 让分支保持最新

依赖 implement_ticket。拉取并把 base 分支合并进特性分支，解决冲突，然后重新跑 lint/测试。

name = "Merge Base Branch"
depends_on = ["implement_ticket"]

[[steps]]
name = "Merge base branch"
prompt = """
Fetch the latest `{base_branch}` from remote and merge it into the current branch.
Resolve conflicts — prefer the current branch for feature code, the base branch for
config/dependency files unless they conflict with this ticket's work. Run lint and
tests after the merge, then commit and push.
"""
repeat = 1

命令步骤与 run command

对于 lint 或构建这类确定性工作，命令步骤（commands = [...]）直接运行 shell 命令 且不消耗 AI token。另外，run command（按用户从 Configuration → Worktree Settings 配置）会作为按钮出现在已完成的 workflow 卡片上 —— 例如 “Dev Server”、 “Storybook” —— 并在服务器启动时自动转发端口。

关于这些步骤在生命周期中的位置，参见 工作原理。