# Trellisx Workspace

> 📋 维护 `.trellis/task.md` 任务看板 —— trellis 缺的跨任务总览。**一个表格, 一行一个任务**, 列为 id/名称/描述/状态/worktree/前置 (6 列; 状态列承载生命周期阶段: 规划中/实施中/检查中/收尾/已完成/已归档; 前置列=该 task 依赖的前置 task ID, 承载 task 级 DAG, 仅有依赖者标, 无依赖填 —)。在 task create/start/阶段切换/archive/设依赖 后**及时更新**对应行; 并**自动清理超 7 天的已完成行**防膨胀。保持看板与 task.json 实时一致

- Skill: `lazygophers/trellisx-workspace` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add lazygophers/trellisx-workspace`
- Raw SKILL.md: https://api.skillmd.com/api/skills/lazygophers/trellisx-workspace/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: lazygophers (https://skillmd.com/u/lazygophers)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/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
- 看板文案 + 状态枚举固定中文 (状态: 规划中/实施中/检查中/收尾/已完成/已归档)