القائمة
🎯 在 Trellis 项目 planning 阶段, 指导编写 task 文件夹内的 prd.md / design.md / implement.md, 把任务编排理念 (五要素拆分、执行层选择、资源互斥、失败回退) 内嵌到文档中。让后续 dispatch 与执行有据可依, 而不是写完 PRD 才临时想怎么拆
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
planning 入口 + 单一真值源 (用户显式 /skein-plan 或被 skein-flow 委托)。新建 SKEIN task 做需求梳理: 判新旧 + create 登记 + 交互式 brainstorm + grill 硬门。产出 prd.md + design.md + 子任务/依赖 DAG 落 task.json。无参 = 停在 start 前 (只规划不执行); --continue = 返回工件路径供 flow 激活。硬约束: 未跑 grill / 未 subtask add 禁进 exec; design.md 仅 planning 阶段可写
两层规则记忆 (基于 .skein/spec)。planning 时 recall 召回相关规则、task finish 后 sediment 沉淀学习 + prune 自动精简过期/重复/断链规则。core 常驻硬规 + recall 按需召回, 经判定门自动写盘 (不逐次问用户)。产出 .skein/spec 下 core/recall 规则文件 + index。另支持空仓 bootstrap 播种规则基线、记忆大面积失效 (大重构/换栈) 时 reconstruct 可逆归档后按项目类型分型重建、maintain 手动体检 (超预算/stale/断链/重复/废弃)。硬约束: sediment+prune 异步 fire-and-forget 不阻塞 finish; core 只留硬约束
task check 阶段质量验证。exec 产物完成后、finish 前使用。派 skein-checker 跑 lint/type-check/tests/契约 + 一致性核查, 回传通过|失败|冲突报告。未过或检出冲突不放行 finish。验证与修复分离。
task exec 阶段执行编排调度门 + /skein-exec 闭环入口。作命令: 有入参→强制建 task 走闭环 (委托 skein-flow: plan→exec→check→finish, 不 inline); 无入参→驱动 .skein 既有 ready/active task 各走闭环。作 skill: 被 skein-flow exec 委托, main 按 depends_on DAG 为每个 subtask 选合适 agent 各执行 1 个, 改动落 task worktree。回传各 subtask 产物 / 需要 / 失败。硬约束: 并发上限 2、完成即派、main 禁亲改源码、载体单 subagent 不递归、异步等待 MUST 输出任务清单
task 收尾闭环门。check 全绿后使用 (被 skein-flow finish 委托, 或用户显式 "收尾/归档/闭环") — 派 skein-finisher 收尾勘察 (diff/subtask 核对/悬挂清单, 同步门) → skein finish (commit→merge→archive→销 worktree, 先闭环) → 异步 fire-and-forget 派 skein-specer 跑 sediment 判定门 + 自主写盘 (不阻塞 finish)
强制 task 闭环。复杂/多步/跨文件请求, 或用户显式要求把请求作为 SKEIN task 处理时使用 — 强推 plan→exec→check→finish 全流程, main 作调度器派 subagent 在 worktree 内执行, 禁 inline 直接做
| name | trellisx-orchestrate |
| description | 🎯 在 Trellis 项目 planning 阶段, 指导编写 task 文件夹内的 prd.md / design.md / implement.md, 把任务编排理念 (五要素拆分、执行层选择、资源互斥、失败回退) 内嵌到文档中。让后续 dispatch 与执行有据可依, 而不是写完 PRD 才临时想怎么拆 |
在 trellis active task 的 planning 阶段, 把任务编排理念内嵌到 prd.md / design.md / implement.md。Dispatch 与执行阶段直接读这些文档落地, 避免"写完 PRD 才临时想怎么拆"。
| 立场 | 说明 |
|---|---|
| 编排即文档 | 五要素 / 执行层 / 资源互斥不是临时口头约定, 必须写进 PRD / design / implement |
| 拒绝模糊 PRD | PRD 必须列 deliverable 矩阵 + 验收, 禁开放式"实现 X 功能" |
| 自包含 | 全部规则就地内嵌, 不引外部 |
| 串行优先 | 共享 task 文件写入 / 同一 active task 状态切换必须串行 |
作用域边界统一判定 (与 trellisx-flow 共用同一表, 消除冲突):
| 特征 | 判定 |
|---|---|
| 纯查询 / 文档阅读 / 问答 (无改动) | 豁免, 不建 task |
| 单文件单处改, ≤20 行且位置已知 | 豁免 |
| 跨 ≥2 文件 / 单文件多处 / 多步骤改 | 必建 task |
| 需外部调研 (库选型/方案对比) 或产出文档交付 | 必建 task (调研为 research subtask) |
| 边界模糊 | MUST AskUserQuestion 由用户裁定 |
无 task → 不进执行编排 → 执行规约豁免。Planning 阶段不派执行 subagent: brainstorm 主线由 main 同步前台 (subagent 不能 AskUserQuestion); 纯信息调研可派 trellis-research 并行, 但设计决策由 main 汇总裁定。
建 task 后拆 ≥ 2 subtask:
python3 ./.trellis/scripts/task.py create "<title>" --slug <name> # 建 task
python3 ./.trellis/scripts/task.py start <name> # 进 planning, after_start hook 自动建 worktree
调度规则 (main 是调度器, 动态 DAG 调度, 见 references/scheduling.md): planning 末 main 静态算冲突 (两类自动依赖边: 写盘文件 glob 相交 write-files + 执行作用域相交 exec-scope; 加显式 depends-on) → 建 DAG → exec 阶段循环: 查 ready → 派 min(|ready|, 2-|running|) 个 trellis-implement 各执行 1 subtask (共享 task worktree, 并发上限 2, 完成即派下一个, 不空等) → 任一返回 (notification) 即更新态、查新 ready、立即派 → failed 走 failure-recovery → 全 done 转 trellis-check。trellis-implement 不调度不递归 (工具集无 Agent/Task, Recursion Guard; 每 subtask 文件 frontmatter 必填 write-files + exec-scope)。subtask 与 worktree 无绑定; 多 worktree 属 opt-in, 非自动, 非由 subtask 触发。
被路由加载 (非用户直接入口, 入口归 trellisx-flow), 符合任一即生效:
不触发: 用户直接喊"写 PRD / 规划任务" (路由进 flow 先判建 task) / 已 in_progress 在执行 / 单文件咨询 / 与编排无关问答。
每步先读对应 reference (写法规则) + 对应 example (填好的范例), 再写文档:
| 步骤 | 行动 | 写法 reference | 填好范例 |
|---|---|---|---|
| 1 | PRD 编排 — spec 加载门 (planning 必做, 非软约束; 本 skill 独家 owner, flow 不重复加载): 先 grep .trellis/spec/guides/index.md 按主题找相关 guide, 命中读全文注入 PRD 上下文 (约束/契约/验收基准); 无相关 spec 才跳过。被动可见: 本 gate 文本由 trellis 原生每轮注入 context (AI 每轮知 spec 存在 + index 路径, 不靠记忆)。诚实边界: relevant guide 检索归本步主动 grep (model 驱动, 非脚本全自动; 无独立 per-turn hook, config.yaml 仅 lifecycle 事件)。再出 deliverable 矩阵 + subtask 概览表 + mermaid 调度图 + 验收 + 范围边界。grill 硬门 1 (边问边写, 与 brainstorm 协同): PRD 编写过程 MUST 调 /trellisx-grill 用轴 A (目标) / B (产出) 当提问引擎 —— grill 出问 → brainstorm 逐问用户 → 答完即时更新 PRD → 循环至轴 A/B 双 ✓。禁写完整 PRD 才审 (本末倒置) | references/prd-orchestration.md | examples/prd.md |
| 2 | 为每个 subtask 建独立文件 .trellis/tasks/<task>/subtask/<id>-<slug>.md 含完整五要素 + dispatch prompt | references/subtask-file.md | examples/subtask/S2-jwt-utils.md examples/subtask/S3-jwt-middleware.md |
| 3 | design 编排 — 模块表 + 执行层标注 + 资源边界 + 契约 | references/design-orchestration.md | examples/design.md |
| 4 | implement 编排 — 有序 checklist + 验证命令 + review gate + rollback | references/implement-orchestration.md | examples/implement.md |
| 5 | parent / child 拆分 (1 task 含 ≥ 2 独立可验收 deliverable): task.py create --parent <dir> 建 child + parent 写 Child Task Map + 跨 child 验收标准 | references/task-tree.md | 同文件 §Child Task Map / §Parent task 内容 (命令 + 表格式范例) |
| 6 | jsonl 上下文清单 curate (为后续 dispatch 备料): 逐 subtask 写 implement.jsonl / check.jsonl 的 spec + research 条目 | references/jsonl-curation.md | 同文件 §Entry 格式 (字段定义 + JSON 行范例) |
轻量 task (恰好 1 deliverable 且 1 subtask) 只做步骤 1 + 2 (PRD + 单 subtask 文件)。其余 (≥ 2 deliverable 或 ≥ 2 subtask) 必须 6 步走完才能进入 task.py start。
硬停审批门 (planning → start 前, grill 硬门 2): 走完
references/selfcheck.md自检前 禁task.py start。多交付 task 未拆 subtask 文件 / 未出 mermaid 调度图 / PRD 仍是开放式 → 退回补齐, 不准放行。MUST 先调/trellisx-grill跑全轴需求确认 (硬门, 非可选): grill 弱点表交用户过, 用户确认"这就是我要的" + 弱点补齐后才放行 start。未跑 grill = 流程未完成, 禁 start。
范例集索引: examples/README.md (同一 OAuth2 登录场景贯穿全部文档)。
| # | 反模式 | 为什么禁 | 替代 |
|---|---|---|---|
| 1 | 开放式 PRD ("实现 X 功能") | 无 deliverable 矩阵 = dispatch 无据可拆 | 列 deliverable 矩阵 + 逐条验收 |
| 2 | 写完 PRD 才临时想怎么拆 | 编排理念没落文档 = 执行阶段重新推导 | 五要素 / 执行层 / 资源互斥就地内嵌 prd/design/implement |
| 3 | 多交付不建 subtask 文件 | dispatch prompt 无源 = sub-agent 缺六要素自包含 | 每 subtask 建独立文件 (步骤 2) |
| 4 | 共享 task 文件并发写 / 同 task 状态并行切换 | 写冲突 + 状态错乱 | 串行化 (立场: 串行优先) |
| 5 | 并行组不标依赖箭头 | 隐藏依赖 → 乱序执行 | mermaid 调度图显式标并行组 + 依赖 |
| 6 | 自检未过强行 task.py start | 带病进 in_progress, 返工成本翻倍 | 过 selfcheck gate 才放行 (上方 硬停审批门) |
| 7 | 执行中收到修正指令, main 自己直接改源码 / 口头通知 agent | 与在跑 agent 改动分叉 + 文档与执行脱节 | 先改 PRD 真值文档 → SendMessage 通知在跑 agent 就地纠偏 (references/progress-communication.md §中途修正路由) |
| 8 | exec 阶段 subtask 之间停下来问用户"先做哪个" | 顺序归 planning (本 skill 产调度图 + depends-on), exec 只跑调度循环 —— 问序 = planning 没做透 | 按 DAG 自动派 (scheduling.md §4); PRD 缺调度图 / depends-on → 退回 planning 补, 不在 exec 问 |
token 纪律: 本 skill 被 flow 路由自动触发, 12 references 全读会撑爆 token (多 skill session 旧 skill 被静默踢出, 无错误信息)。禁一次全读 —— 只读当前步骤对应的那 1-2 个 reference (见工作流表「写法 reference」列) + 对应 example。其余按需。轻量 task (1 deliverable/1 subtask) 仅读步骤 1+2 的 reference。
| 文件 | 何时读 |
|---|---|
references/prd-orchestration.md | 写 / 改 PRD 时 |
references/subtask-file.md | 创建 / 改 / 删 subtask 文件时 |
references/design-orchestration.md | 写 / 改 design 时 |
references/implement-orchestration.md | 写 / 改 implement 时 |
references/task-tree.md | 多 deliverable 拆 parent/child 时 |
references/jsonl-curation.md | dispatch 前最后一步 |
references/five-elements.md | 拆任何 subtask / checklist 项时 (基础参考) |
references/layer-selection.md | implement 标注执行层时 + trellis 复杂度判定 coordinator |
references/shared-resources.md | 标注资源互斥 / 并行决策时 |
references/scheduling.md | exec 阶段动态 DAG 调度 (main 调度器 / 冲突判定 / 5 态 / 并发 2 / 完成即派) |
references/progress-communication.md | coordinator 回传进度时 (每 subtask 完成 / 阻塞); 执行中收到用户新指令做中途修正路由时 (§中途修正路由) |
references/task-lifecycle.md | 任务规划开始 / 阶段切换前 (planning → in_progress → check → sediment → stop) |
references/selfcheck.md | planning → start 前最终自检 |
| 触发 | 一线修复 | 仍失败兜底 |
|---|---|---|
| 不在 trellis active task / 无 planning 状态 | 提示先 task.py create + start 进 planning | 非 trellis 项目 → 提示 trellis init, 不强行编排 |
| deliverable 边界判不准 (该拆 child 还是单 task) | 按"是否独立可验收"判 (references/task-tree.md) | 仍不准 → AskUserQuestion 问用户, 禁自行替决 |
| subtask 资源是否互斥拿不准 | 查 references/shared-resources.md 判共享文件/状态 | 拿不准 → 默认串行 (串行优先立场), 不赌并行 |
| selfcheck 未过但想 start | 退回补齐缺项 (subtask 文件/调度图/验收) | 反复不过 → 缩小 MVP 范围重新拆, 不带病 start |
| reference 文件读不到 | 按 SKILL 主体规则就地编排 | 关键 reference 缺失 → 提示用户 skill 安装不全 |
trellisx-spec (任务收尾沉淀学习回 spec)