Skip to content

dongshuyan/compass-skills / skills/task-forest

task-forest

Verified

Maintains a repo-local task forest or task DAG for the current workspace. Use when the user asks to initialize or update a task forest, close a session, summarize evolving project work, align a request with a global goal, track progress/history/deviations/todos, save or apply a task proposal, or export the client-readable task-forest HTML. Do not use for executing the tracked tasks themselves or for generic HTML work.

references/html-visualization-contract.md

View on GitHub
# task-forest HTML 契约

## 目标

`exports/task-forest.html` 是 task-forest 唯一的 HTML 成品。它应当可以直接交给甲方、项目成员或第一次接触项目的人阅读,不依赖任务 list、JSON、内部编号说明或另一份 HTML。

页面回答四个问题:

1. 项目端到端要实现什么;
2. 已经完成了哪些功能;
3. 当前正在推进什么;
4. 这些工作之间是什么层级关系,项目如何演进到当前状态。

## 内容投影

只展示:

- `done`;
- `in_progress`;
- 为保持层级完整所必需的 `child_of` 祖先。

不展示未开始任务、待复核队列、阻塞队列、内部讨论、证据、偏差正文、执行提示、会话信息、文件路径或 proposal 内容。

每个可见任务必须使用自然语言表达,并至少具备:

- 可独立理解的标题;
- `summary` 或 `purpose`;
- 能说明交付内容的成果、要求、验收标准或完成指标之一(适用时)。

内部 ID 可以用于页面数据关联,但不能作为卡片的主要名称。页面不能要求读者先理解 `P04`、`P07` 等内部编号。

## 布局

- 使用从上到下阅读、从左到右展开层级的混合树布局。
- 根目标和一级任务使用较大的卡片;更深层子任务在右侧或下方分组展示。
- 页面使用浏览器正常纵向滚动,不依赖缩小整个画面才能阅读。
- 桌面、平板和手机都必须保持标题、层级连线和任务正文可读。
- 进行中的父任务应显示直接子任务总数、已完成数和正在推进数。
- 同级节点只有在整组 `display_order` 完整、合法且唯一时才按其展示;否则按相对父节点的阶段/模块/任务编号、创建时间和 ID 安全排序并给出警告。不得让部分显式值、边创建顺序或内部 ID 覆盖业务顺序。

## 交互

- 支持展开、收起、搜索和“已完成/正在推进”筛选。
- 点击任务打开详情,展示目的、成果、要求、验收标准和完成指标。
- 关闭详情后恢复到原触发任务,避免键盘焦点丢失。
- 所有交互只改变浏览器视图,不能写回任务图。

## 历史播放

- 支持上一步、下一步、播放、暂停、循环、速度和滑块。
- 每一帧说明新增节点、状态变化、进度变化及 `child_of` 层级变化。
- 0 个保存快照时展示当前状态并禁用无意义播放。
- 1 个保存快照时可以加入明确标记的合成起点;合成帧不能冒充真实快照。
- 多个快照默认展示当前状态;从末帧点击播放时从头开始。

## 安全和独立性

- HTML 必须离线可用,无外部脚本、字体、图片或网络请求。
- 内嵌 JSON 必须安全转义,任务文字只能作为文本显示。
- 页面不得包含 credential、cookie、token 或未授权私人信息。
- 导出成功表示结构和交互验证通过。对外交付前仍应人工阅读页面文案,确认任务名称和描述适合接收方。

## 固定输出

每次导出生成三个内部兼容 JSON 和一个 HTML:

```text
exports/task-forest.graph.json
exports/task-forest.todos.json
exports/task-forest.timeline.json
exports/task-forest.html
```

不生成第二份 HTML。若目录中存在旧的 `task-forest.audit.html`,导出时按精确文件名清理。

## 验收

从临时 workspace 验证:

- 0、1、多个保存快照;
- 多个根、至少四层父子关系和宽分支;
- `done`、`in_progress` 及必要祖先可见,其他状态不可见;
- 根目标、任务目的和验收文字无需外部文件即可理解;
- 历史播放、搜索、筛选、展开、详情和焦点恢复可用;
- 390px、1024px、1440px 视口可阅读并能正常纵向滚动;
- 控制台无异常,页面无外部请求;
- 导出前后 canonical task 数据不变;
- 旧审计 HTML 不存在。

运行:

```bash
python3 scripts/validate_task_forest_export.py --skill-dir /path/to/task-forest
```
add-product-e2e-evalpaperclipai/paperclipAdd or extend a Paperclip full-stack runner E2E workflow, fixture, matcher, or report evidence path for local or Daytona execution.Stars: 115kUpdated Claude CodeCodexVerifiedInstall
add-runner-evalpaperclipai/paperclipAdd or extend a Paperclip Runner protocol evaluation definition, roster, assertion, or report fixture with provenance and narrow validation.Stars: 115kUpdated Claude CodeCodexVerifiedInstall
diagnose-why-work-stoppedpaperclipai/paperclipCompatibility entry point for failed, stalled, looping, or over-recovered Paperclip work. Use fix-failed-paperclip-run for the full diagnosis, regression, repair, real verification, and green-PR workflow; honor an explicitly requested diagnosis-only scope.Stars: 115kUpdated Claude CodeCodexVerifiedInstall
fix-failed-paperclip-runpaperclipai/paperclipDiagnose and fix failed, stuck, slow, or incorrectly blocked Paperclip tasks and runs. Use with a task/run URL or failure report to trace the root cause, prove a regression red then green, check second-order effects, verify the real workflow, and deliver a PR with passing checks.Stars: 115kUpdated Claude CodeCodexVerifiedInstall