lazygophers/trellisx-workspace

trellisx-workspace — .trellis/task.md 任务看板维护

trellis 原生有每任务 task.json, 但无跨任务总览。本 skill 维护 .trellis/task.md 作为人类可读的任务看板 —— 一个表格, 一行一个任务 (6 列: ID/名称/描述/状态/worktree/前置), 并保证它随 task 生命周期及时更新 (不是写一次就烂掉)。前置列承载 task 级 DAG —— 该 task 依赖哪些前置 task 先完成 (多个逗号分隔, 无依赖填 —), flow/go 据此排调度前后序。无活动详情块、无子任务树、无归档分区。

文件定位

• 路径: .trellis/task.md (仓库内, 随 git 版本化)
• 角色: 单表格任务看板, 每行一个 task (含已完成, 用状态列区分) + 两个脚本自动维护的 section: ## 依赖关系图 (DAG) (从前置列自动渲染的 mermaid 图, 无依赖边则不出段) + ## Worktree ↔ Task 映射 (一对多: 一行一 worktree, 同 task 可多行; 见 references/dimensions.md)
• 数据源: task.py list / 各 task 的 task.json —— task.md 是其人类可读投影, 冲突时以 task.json 为准
• 维护者 (按列分工, 不冲突):
  • ① trellis 生命周期 hook (trellisx-taskmd.py, 由 trellisx-apply 注入 config.yaml): 自动维护确定性列 (ID/名称/描述/状态基础态) + 前置列 (从 task.json depends_on 渲染) + create/start/archive 时 upsert + archive 时7 天清理。这是硬保障, 不靠 AI 记。
  • ② AI (本 skill): 细化状态列 (阶段: 实施中→检查中→收尾) + worktree 路径, 在阶段推进时更新; 设/改 task 依赖时 update <tid> --deps "a,b" (写回 task.json depends_on 真值源 + 前置列, 二者恒一致)。
  • hook upsert 时保留 AI 列, AI 更新时保留 hook 列 —— 同行不同列, 互不覆盖。冲突规则: 若 AI 已写细分 (实施中/检查中/收尾) 且 task 仍 in_progress, hook sync 不覆 AI 细分。前置列: task.json depends_on 非空时 hook sync 优先渲染, 否则保留 AI update --deps 写的值。
  • 项目未跑 apply (无 hook) 时, AI 全列维护 (含清理)。

维护时机 (及时更新, 不可滞后)

一律经 .trellis/scripts/trellisx-taskmd.py 脚本操作, 禁直接 Edit/Write task.md 文件 (settings.json permissions.deny + guard-taskmd.sh PreToolUse hook 双保险硬阻 —— 直接编辑会被 deny 拦 + hook exit 2 block; 保证格式一致 + hook/AI 列分工不打架)。

检查点 (每个生命周期节点后): create / start / 阶段推进 / archive 任一发生 → 立即 update 或 sync 对应行, 才算节点完成。task.md 落后于 task.json = 看板失效, 视为流程缺陷, 不准放任滞后到下一步。

硬停 — 删行前 (AI 手动 cleanup / del / clean): 三者均永久删除看板行, 属破坏性操作。执行前 MUST 经 AskUserQuestion 工具确认删除范围 (cleanup 列天数阈值 + 将删 tid; del 列目标 tid; clean 列将删的孤儿 tid), 用户批准后才删。禁默认静默删除, 禁用"建议清理"软措辞替代确认。(hook 触发的 archive 内 7 天清理是确定性流程, 不走此门。)

| 触发 | 命令 (脚本) | 谁执行 | | --- | --- | --- | | task.py create | taskmd.py sync create | hook (after_create) 自动 | | task.py start | taskmd.py sync start | hook (after_start) 自动 | | 阶段推进 (实施→检查→收尾) | taskmd.py update <tid> --status 检查中 | AI | | worktree 建好 (主表列) | taskmd.py update <tid> --worktree <路径> | AI | | 设/改 task 依赖 (前置列, task 级 DAG) | taskmd.py update <tid> --deps "<前置id>,..." (写回 task.json depends_on + 前置列; 无依赖不设, 留 —) | AI (规划出依赖时) | | worktree 创建 (subagent isolation / 手动 git worktree add) | taskmd.py map-add <worktree> <tid> [创建源] | WorktreeCreate hook 自动按当前活动 task 登记 (无活动 task → ?, 由 UserPromptSubmit 提醒补登) | | worktree 销毁 | taskmd.py map-remove <worktree> | hook (WorktreeRemove / archive) 自动 | | 查映射 / 查归属 | taskmd.py map-list / map-get <worktree> | AI / 用户 | | task.py archive | taskmd.py sync archive (含 7 天清理 + 清该 task 映射) | hook (after_archive) 自动 | | 查看看板 / 某任务 | taskmd.py show [tid] | AI / 用户 | | 格式校验 (结构自洽) | taskmd.py lint (主表 6 列 / 映射区 3 列 / 状态 / ID 不重复 / DAG 图 ↔ 前置列一致) | AI (FileChanged hook 自动提醒) | | 真值校验 (跨源一致) | taskmd.py check (每 task.json 有主表行 / 前置列 == task.json depends_on) | AI / pre-commit | | 手动清理 (超 N 天已完成行) | taskmd.py cleanup [--days N] | AI (先 AskUserQuestion 确认) | | 删单个 task 行 (误建/放弃) | taskmd.py del <tid> (删主表行 + 其映射, 不动 task.json) | AI (先 AskUserQuestion 确认) | | 对账删孤儿行 (task.json 已删的残留) | taskmd.py clean (删主表 + 映射孤儿, ? 保留) | AI (先 AskUserQuestion 确认) |

原则: task.md 落后于 task.json = 看板失效。hook 自动管确定性列, AI 在阶段推进时 update 状态细分 + worktree。 无 hook 的项目 (未跑 apply): AI 用 sync create/start/archive 手动触发同步 + cleanup 清理。

用法

1. 查看 — python3 .trellis/scripts/trellisx-taskmd.py show [tid]。
2. 细化状态 + worktree (阶段推进) — python3 .trellis/scripts/trellisx-taskmd.py update <tid> --status <检查中|收尾|实施中> --worktree <W>。
3. 确定性列 + 清理 — 由 hook 的 sync 自动 (apply 已注册 config.yaml hooks); 无 hook 时 AI 显式调 sync / cleanup。
4. worktree↔task 映射 (一对多) — map-add <worktree> <tid> [创建源] 登记 (按规范化 abspath upsert, 同 task 可多 worktree 各占一行) / map-remove <worktree> 移除 / map-get <worktree> 查 (命中→打印 tid 退 0, 无→退 1) / map-list 列全部。WorktreeCreate hook 创建时按当前活动 task 自动登记 (无活动 task → ?), UserPromptSubmit hook 对 ?/缺登记提醒补全, WorktreeRemove/archive 自动清。
5. 规范校验 — lint 校验 task.md 结构自洽 (主表 6 列 / 映射区 3 列 / 状态值合法 / ID 不重复 / DAG 图 ↔ 前置列一致); check 校验 task.md ↔ task.json 跨源真值 (前置列 == depends_on / 每 task.json 有主表行); FileChanged hook 在 task.md 变更时自动跑 lint, 不合规 → 提醒修 (可跑 fix 机械修复)。手动: python3 .trellis/scripts/trellisx-taskmd.py lint|check。

脚本是 task.md 唯一写入口。脚本不存在 (项目未跑 apply 复制脚本) → 提示用户先 /trellisx-apply, 或按 references/ 模板临时手维护。

参考集

| 文件 | 用途 | | --- | --- | | references/task-md-template.md | task.md 单表格模板 (一行一任务) | | references/dimensions.md | 表格各列字段定义、取值、来源、更新时机 | | references/maintenance.md | 幂等更新算法 (按 id 定位表行, 从 task.json 同步, 不堆叠) |

失败模式 (触发 → 一线修复 → 仍失败兜底)

与下方「反例黑名单」区别: 黑名单是不要做什么, 本表是 skill 跑起来卡壳时怎么办。

| 触发 | 一线修复 | 仍失败兜底 | | --- | --- | --- | | hook 与 AI 同行争列 (状态/前置被互覆) | 按列分工规则: AI 细分 (实施中/检查中/收尾) 不被 hook 覆, 前置列以 task.json depends_on 为准 | 仍打架 → check 对账后以 task.json 真值 sync 重建该行, 禁手改 | | check 报跨源不一致 (前置列 ≠ depends_on / task.json 无对应主表行) | 跑 taskmd.py fix 机械修复 + 缺行 sync 补 | fix 修不动 (结构性冲突) → 以 task.json 为准手动 update --deps 校正, 禁反向回填 task.json | | map-add 无当前活动 task (登记为 ?) | 待 UserPromptSubmit 提醒时 map-add <worktree> <tid> 补登真实归属 | 归属仍不明 → 保留 ? 占位不臆测, 标「待确认」, 禁瞎绑 task | | lint 不合规 (列数/状态值/DAG↔前置漂移) | 跑 taskmd.py fix 机械修复 | fix 后仍 fail → 报具体行给用户, 禁带病 commit 看板 | | 脚本不存在 (项目未跑 apply) | 提示用户先 /trellisx-apply 复制脚本 | 用户暂不跑 → 按 references/ 模板临时手维护, 标「apply 后转脚本管」 |

反例黑名单 (禁做)

| # | 反模式 | 为什么禁 | 替代 | | --- | --- | --- | --- | | 1 | 手改 task.md 文件 (绕过脚本) | hook/AI 列分工被打乱 + 格式漂移; 且 settings.json deny + PreToolUse hook 双保险硬阻, 直接编辑必被拦 | 一律经 trellisx-taskmd.py (show/update/sync/cleanup/map-) | | 2 | 节点完成不同步看板 | task.md 落后 task.json = 看板失效 | 每个生命周期节点后立即 update/sync (见 检查点) | | 3 | 拿 task.md 当真值源改它再回填 task.json | 投影反向污染真值 | task.json 是真值, 冲突时以它重建 task.md | | 4 | AI 覆盖 hook 维护的确定性列 (ID/名称/描述/状态基础态) | 同行列分工冲突, 互相覆盖 | AI 只细化状态 (阶段: 检查中/收尾) + worktree, 保留 hook 列 (ID/名称/描述/状态基础态) | | 5 | 加活动详情块 / 子任务树 / 归档分区 (DAG 图段 + 映射区除外) | 偏离"一表一行一任务"单表设计 | 单表格 + 两个脚本维护段: ## 依赖关系图 (DAG) (自动渲染) + ## Worktree ↔ Task 映射 (map- 维护) | | 6 | 脚本缺失时硬编看板格式 | 无脚本手维护易格式不一 | 提示用户先 /trellisx-apply 复制脚本, 或按 references/ 模板临时维护 |

边界

• 只维护 .trellis/task.md, 不改 task.json / 源码
• 与 trellis 原生不冲突: task.json 是真值, task.md 是投影; 二者不一致时以 task.json 重建 task.md
• 看板文案 + 状态枚举固定中文 (状态: 规划中/实施中/检查中/收尾/已完成/已归档)