Project Task Manager Skill

Release Notes

0.1.1

• Enables Focus and priority tracking by default so task lists preserve the current goal and nearest follow-up.
• Orders project-task-manager-list output by now, next, later, then P0 through P3.
• Validates focus and priority values, and warns when too many open tasks are marked as now.

一个可移植的 Codex 项目任务管理 skill，用来在不同项目中维护清晰、可追踪的任务清单。

它的核心思路是：skill 本身可以全局安装，但每个项目用自己的 .task-manager.json 配置任务文件放在哪里、状态有哪些、摘要怎么展示。

它解决什么问题

很多项目都会慢慢积累 TODO、排查记录、后续优化点。如果所有内容都塞进一个 todo.md，文件会越来越长，最后没人愿意看。

这个 skill 推荐把任务拆成两层：

• 摘要文件：只放简短任务列表，例如 docs/todo.md
• 详情文件：每个任务一个文件，例如 docs/tasks/runtime-data.md

这样你问 Codex：

还有什么任务没做？

Codex 可以先读摘要，给你一个简洁清单；只有你要细节时，才打开对应详情文件。

典型目录结构

默认初始化后会生成：

your-project/
  .task-manager.json
  docs/
    todo.md
    tasks/
      archive/

你也可以改成任意结构，例如：

your-project/
  .task-manager.json
  .tasks/
    index.md
    items/
    archive/

路径由 .task-manager.json 控制，不写死。

安装和使用

如果已经发布到 npm，可以直接用 npx：

npx -p codex-skill-project-task-manager project-task-manager-init

常用命令：

# 初始化当前项目的任务管理文件
npx -p codex-skill-project-task-manager project-task-manager-init

# 列出当前项目未完成任务
npx -p codex-skill-project-task-manager project-task-manager-list

# 校验配置、摘要文件、状态值和详情链接
npx -p codex-skill-project-task-manager project-task-manager-validate

默认命令等价于列出任务：

npx codex-skill-project-task-manager

发布包自检：

npm run validate

校验当前已经初始化的项目：

npm run validate:project

初始化示例

使用默认路径：

npx -p codex-skill-project-task-manager project-task-manager-init

使用自定义路径：

npx -p codex-skill-project-task-manager project-task-manager-init ^
  --summary=.tasks/index.md ^
  --task-dir=.tasks/items ^
  --archive-dir=.tasks/archive

使用英文工程状态：

npx -p codex-skill-project-task-manager project-task-manager-init ^
  --preset=engineering-en

配置文件

初始化后会在项目根目录生成 .task-manager.json：

{
  "version": 1,
  "summaryFile": "docs/todo.md",
  "taskDir": "docs/tasks",
  "archiveDir": "docs/tasks/archive",
  "statusPreset": "simple-cn",
  "statuses": ["未开始", "进行中", "部分完成", "已完成", "暂停"],
  "openStatuses": ["未开始", "进行中", "部分完成", "暂停"],
  "doneStatuses": ["已完成"],
  "summaryStyle": "table",
  "detailTemplate": "default-cn",
  "focusEnabled": true,
  "focusOrder": ["now", "next", "later"],
  "priorityEnabled": true,
  "priorityOrder": ["P0", "P1", "P2", "P3"],
  "ownersEnabled": false,
  "datesEnabled": false,
  "doneHandling": "keep",
  "taskIdStyle": "date-slug"
}

常用字段说明：

• summaryFile：任务摘要文件路径。
• taskDir：任务详情文件目录。
• archiveDir：归档任务目录。
• statuses：允许使用的状态。
• openStatuses：哪些状态算“未完成”。
• doneStatuses：哪些状态算“已完成”。
• summaryStyle：摘要展示风格，当前支持 table / grouped-list。
• focusEnabled：是否记录当前推进焦点，默认开启。
• focusOrder：焦点排序，默认 now > next > later。
• priorityEnabled：是否记录优先级，默认开启。
• priorityOrder：优先级排序，默认 P0 > P1 > P2 > P3。
• doneHandling：完成任务后保留在原地还是移动归档，支持 keep / move-to-archive。

更完整配置说明见 references/config-schema.md。

状态预设

simple-cn

适合中文项目的简单状态：

未开始 / 进行中 / 部分完成 / 已完成 / 暂停

kanban-cn

适合看板风格：

待办 / 准备中 / 进行中 / 阻塞 / 已完成 / 已归档

engineering-en

适合英文工程项目：

backlog / ready / doing / blocked / done / archived

摘要文件长什么样

默认 docs/todo.md 会保持短小：

# TODO

本文件只保留项目任务摘要。详细背景、处理记录和代码位置放在 `docs/tasks/`。

## 任务摘要

| 状态 | Focus | 优先级 | 任务 | 摘要 | 详情 |
| --- | --- | --- | --- | --- | --- |
| 未开始 | next | P1 | 示例任务 | 一句话说明任务。 | [example.md](tasks/example.md) |

默认会启用 Focus 和 优先级，列表输出会优先显示 now，再显示 next、later；同一焦点内按 P0 到 P3 排序。启用负责人或日期后，初始化脚本会在表格里追加对应列。使用 grouped-list 时，摘要会按状态分组：

## 任务摘要

### 未开始

- 暂无任务。

摘要文件不要写长篇背景。长内容应该放进详情文件。

详情文件长什么样

每个任务一个详情文件：

# 示例任务

## 状态

未开始

## 背景

为什么有这个任务。

## 当前判断

已经确认了什么，哪些还只是假设。

## 已处理

- 暂无。

## 后续任务

1. 下一步。

## 相关代码位置

- `path/to/file`

在 Codex 里怎么配合使用

把 skill 安装到用户目录后，所有项目都可以共享这个能力。每个项目只需要保留自己的 .task-manager.json 和任务文件。

常见对话方式：

初始化项目任务管理。

还有什么任务没做？

把刚才这个后续事项记录到项目任务里。

这个任务完成了，更新任务清单。

Codex 应该先读取 .task-manager.json，再按配置读写摘要和详情文件。

包内文件

project-task-manager/
  SKILL.md
  agents/openai.yaml
  references/
    config-schema.md
    task-format.md
  scripts/
    init_project_tasks.mjs
    list_tasks.mjs
    validate_project_tasks.mjs