Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
38 commits
Select commit Hold shift + click to select a range
0e98b7a
feat: validate remote todo configuration
hkwuks Nov 16, 2026
0025359
feat: read configured remote issue sources
hkwuks Nov 16, 2026
f4a6189
feat: export explicit remote todo snapshots
hkwuks Nov 16, 2026
e78badf
feat: read numeric json fields when requested
hkwuks Nov 16, 2026
c854332
feat: track remote issue creation recovery
hkwuks Nov 16, 2026
73c082c
fix: serialize remote issue creation by source
hkwuks Nov 16, 2026
105dff1
feat: edit remote issue fields with recovery
hkwuks Nov 16, 2026
bbcf4cc
feat: check json string array membership
hkwuks Nov 16, 2026
544158f
feat: update remote issue lifecycle labels
hkwuks Nov 16, 2026
9a75450
feat: manage remote issue labels
hkwuks Nov 16, 2026
11ffdd8
feat: link remote issues to task records
hkwuks Nov 16, 2026
8c9c6f9
feat: synchronize linked task state to issues
hkwuks Nov 16, 2026
90afa0f
feat: synchronize issue state during task archival
hkwuks Nov 16, 2026
0245ab1
fix: protect local remote todo recovery records
hkwuks Nov 16, 2026
d2d38ef
fix: preserve task phases in remote labels
hkwuks Nov 16, 2026
c6372a4
test: run remote todo checks in host smoke suites
hkwuks Nov 16, 2026
18fc44d
feat: configure remote todo sources
hkwuks Nov 16, 2026
d0bac03
feat: migrate local todos with recovery records
hkwuks Nov 16, 2026
ac3f509
fix: carry local todo state into migrated issues
hkwuks Nov 16, 2026
8674838
feat: combine local and remote todo lists
hkwuks Nov 16, 2026
25dc500
feat: copy remote issues locally and detach tasks
hkwuks Nov 16, 2026
6642b5f
feat: promote remote issues into taskflow tasks
hkwuks Nov 16, 2026
f13d971
feat: guide task intake by todo backend
hkwuks Nov 16, 2026
a6ec2ff
fix: respect selected todo backend during intake
hkwuks Nov 16, 2026
60509a5
test: cover archived issue detachment
hkwuks Nov 16, 2026
e66db85
fix: harden remote todo stages and task roots
hkwuks Nov 16, 2026
4e97d5c
fix: reject promotion of detached tasks
hkwuks Nov 16, 2026
2149dc2
docs: describe remote issue todo workflow
hkwuks Nov 16, 2026
be47903
feat: check remote migration identity before creation
hkwuks Nov 16, 2026
5887518
feat: reconnect detached issue todos safely
hkwuks Nov 16, 2026
14dcd97
fix: preserve todo association history across switches
hkwuks Nov 16, 2026
c0dca5c
docs: record remote todo pull request review
hkwuks Nov 16, 2026
a47f1d6
docs: inventory remote todo hook scripts
hkwuks Nov 16, 2026
4e1b09f
fix: encode utf8 issue labels as unsigned bytes
hkwuks Nov 16, 2026
7018a6d
docs: record remote todo cross-platform checks
hkwuks Nov 16, 2026
249ed31
docs: record snapshot privacy finding
hkwuks Nov 16, 2026
d633a3e
fix: restrict issue snapshots to safe metadata
hkwuks Nov 16, 2026
5409dae
docs: archive accepted remote issue todo task
hkwuks Nov 16, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -22,3 +22,7 @@ TaskFlowDocs/**/sessions.md
# and re-include the routing record itself.
TaskFlowDocs/repository-docs/*
!TaskFlowDocs/repository-docs/index.md

# Remote Todo recovery records are clone-local and may identify private repositories.
TaskFlowDocs/.remote-todo-operations/
TaskFlowDocs/.remote-todo-updates/
29 changes: 26 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -109,6 +109,29 @@ flowchart TD

TaskFlow guides the Agent to consider useful capabilities at each phase; it does not select a particular tool. Plan Review happens before approval and is separate from the review of the implemented result. Hooks assist where the host supports them, and their coverage differs by host; see [runtime.md](skills/taskflow/references/runtime.md) for the event map and limitations.

## Optional remote Issue Todos

A project defaults to local `TaskFlowDocs/todo.md`. To use Issues as the Todo record, configure one or more GitHub or GitLab repositories (including self-hosted instances) and select remote mode. Run these commands from the project repository in Bash; replace the example plugin path with your installed TaskFlow location:

```bash
TASKFLOW_PLUGIN_ROOT="/path/to/installed/TaskFlow" # replace with the installed plugin path
bash "$TASKFLOW_PLUGIN_ROOT/hooks/remote-todo" connect work github github.com owner/repo
bash "$TASKFLOW_PLUGIN_ROOT/hooks/remote-todo" connect lab gitlab git.example.org group/project
bash "$TASKFLOW_PLUGIN_ROOT/hooks/remote-todo" mode-set remote
bash "$TASKFLOW_PLUGIN_ROOT/hooks/remote-todo" list
```

The host's `gh` or `glab` must already be installed and authenticated for each host; credentials are not written to the project. Remote access happens only when requested. `list` retains local items and identifies incomplete sources. In remote mode, an explicit `bash "$TASKFLOW_PLUGIN_ROOT/hooks/task" intake <goal> --local` still creates one local item.

Use `remote-todo create`, `edit`, `label`, `stage`, and `promote` to work with a selected Issue. `migrate-to-remote <todo-id> <alias>` keeps the original local entry; `migrate-to-local <alias> <number> --detach` copies content locally and disconnects an existing association without changing the Issue. `snapshot <new-file>` saves optional historical metadata: source order, Issue numbers, states and update times. Titles, bodies and labels are omitted; the metadata may still reveal activity and become stale. Source numbers refer to configuration order at export time, so retain that order separately if it may change.

To reconnect an unpromoted local copy to its original Issue, use `reattach-todo <todo-id> <alias> --remote-authoritative` after reconciling differences. The local copy remains on disk and the remote Issue becomes authoritative; this does not update the Issue.

For a detached active task, `reattach-task <task-id>` reconnects the original Issue only when its stage matches the local task and it is not linked to another task. Reconcile any differences first; earlier local copies and detach records are retained.

Migration checks a stable Todo marker across all Issues in the selected repository before creation. Do not migrate the same Todo simultaneously from multiple worktrees or machines: the check and creation are not atomic. Editing or removing the marker outside TaskFlow can defeat later checks.

A remote write can succeed even when its response is lost. Inspect the operation ID before retrying; `resolve`, `resolve-absent --checked`, and `ack-update --checked` are explicit recovery operations. GitHub and GitLab cannot generally guarantee atomic conditional Issue edits, so concurrent changes can still race. Local recovery files must be Git-excluded; run `bash "$TASKFLOW_PLUGIN_ROOT/hooks/install-git-hygiene"` if prompted. See [runtime details](skills/taskflow/references/runtime.md#remote-todo-backend).
## Repository documents

`TaskFlowDocs/repository-docs/index.md` is the authoritative routing and check record for repository rules, repository guidance, and scoped personal rules. Repository-owned documents stay authoritative at their conventional source locations.
Expand All @@ -121,7 +144,7 @@ For fork, remote, or pull-request work, TaskFlow records the configured remotes,

TaskFlow never writes a task document in the base working tree: each task runs on its own short-lived branch and its own working tree, created before the first task document rather than before the first edit. `CONTRIBUTING.md` states the branch rule; the Skill states the worktree rule.

Because every task appends to the one `TaskFlowDocs/todo.md`, TaskFlow ships a Git merge driver for it, installed per clone by `hooks/session-start`. Two branches that each added an entry, or that changed different entries, merge without a human; the same entry changed differently on both sides is still left as a real conflict. Todo IDs are derived from the goal rather than from a counter, so two branches cut from the same base cannot allocate the same ID. Merging a pull request in a hosting web UI runs server-side and does not use the driver, so that path falls back to an ordinary content conflict.
Because local tasks and promoted remote tasks may share `TaskFlowDocs/todo.md`, TaskFlow ships a Git merge driver for it, installed per clone by `hooks/session-start`. Two branches that each added an entry, or that changed different entries, merge without a human; the same entry changed differently on both sides is still left as a real conflict. Todo IDs are derived from the goal rather than from a counter, so two branches cut from the same base cannot allocate the same ID. Merging a pull request in a hosting web UI runs server-side and does not use the driver, so that path falls back to an ordinary content conflict.

Before creating or updating a pull request, TaskFlow reads the applicable `.github/pull_request_template.md`, satisfies every required item, records the field mapping and verification in `plan.md`, and blocks PR mutation when a required item is missing or ambiguous.

Expand All @@ -131,7 +154,7 @@ Any user correction or addition to an approved task is classified before documen

## Todo intake

TaskFlow applies automatically only to repository development requests: features, fixes, refactors, tests, and configuration/build/CI changes. A release is the exception — it runs `RELEASE.md` directly on the base checkout, with no Todo item, task directory, branch, or PRD/Plan, and its record is the `CHANGELOG.md` section and the GitHub Release body. Read-only explanation, translation, status, research, review, and diagnosis do not create Todo or task documents; a later implementation request starts the workflow then. Explicitly invoking `$taskflow` opts planning or research into the workflow. For applicable requests, `TaskFlowDocs/todo.md` is the mandatory first record. An item moves from `inbox` to `clarified`, then is promoted into a task directory with `prd.md`, optional `spec.md`, and `plan.md`; it enters `in_progress` after approval and closes as `done` or `cancelled`.
TaskFlow applies automatically only to repository development requests: features, fixes, refactors, tests, and configuration/build/CI changes. A release is the exception — it runs `RELEASE.md` directly on the base checkout, with no Todo item, task directory, branch, or PRD/Plan, and its record is the `CHANGELOG.md` section and the GitHub Release body. Read-only explanation, translation, status, research, review, and diagnosis do not create Todo or task documents; a later implementation request starts the workflow then. Explicitly invoking `$taskflow` opts planning or research into the workflow. For applicable requests, record the request first in the selected Todo backend: local `TaskFlowDocs/todo.md` by default, or an explicitly configured remote Issue repository. An item moves from `inbox` to `clarified`, then is promoted into a task directory with `prd.md`, optional `spec.md`, and `plan.md`; it enters `in_progress` after approval and closes as `done` or `cancelled`.

After verification, TaskFlow moves the whole task directory to `TaskFlowDocs/achieved/<task-id>/`, updates the Todo item's task path and status to `done`, and verifies the active path is absent. If later work belongs to that achieved deliverable, it retrieves the directory to the active root, records the Todo source and reopen reason, creates a new Task version, and returns to approval before changing implementation. Achieved tasks are read-only; their `old/vN/` history is read only when the current documents or a version summary require it.

Expand Down Expand Up @@ -426,7 +449,7 @@ Once installed, tell your Agent:
Use $taskflow to plan, execute, verify, and archive this task.
```

Then: add ideas to `TaskFlowDocs/todo.md`; promote clarified items into `prd.md`, `spec.md` (when needed), and `plan.md`; review the task documents, record approval, then implement one planned step at a time using its checklist.
Then: add ideas to the selected local Todo or remote Issue repository; promote clarified items into `prd.md`, `spec.md` (when needed), and `plan.md`; review the task documents, record approval, then implement one planned step at a time using its checklist.

> [!TIP]
> A small, obvious one-file change can still be a direct change with minimal verification. TaskFlow does not create documents merely to satisfy a process.
Expand Down
29 changes: 26 additions & 3 deletions README.zh-CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -76,6 +76,29 @@ flowchart TD

TaskFlow 引导 Agent 在每个阶段考虑有帮助的能力,但不替它选择具体工具。计划审核发生在用户批准之前,与实施完成后的成果评审分开。Hook 仅在宿主支持时辅助执行,各宿主覆盖范围不同;事件映射和限制见 [runtime.md](skills/taskflow/references/runtime.md)。

## 可选的远端 Issue 待办

项目默认使用本地 `TaskFlowDocs/todo.md`。如需把 Issue 用作待办记录,可配置一个或多个 GitHub、GitLab 仓库(包括自托管实例),并选择远程模式。请在项目仓库的 Bash 中运行,并把示例路径改为实际安装的 TaskFlow 目录:

```bash
TASKFLOW_PLUGIN_ROOT="/path/to/installed/TaskFlow" # replace with the installed plugin path
bash "$TASKFLOW_PLUGIN_ROOT/hooks/remote-todo" connect work github github.com owner/repo
bash "$TASKFLOW_PLUGIN_ROOT/hooks/remote-todo" connect lab gitlab git.example.org group/project
bash "$TASKFLOW_PLUGIN_ROOT/hooks/remote-todo" mode-set remote
bash "$TASKFLOW_PLUGIN_ROOT/hooks/remote-todo" list
```

所选宿主须已安装并登录对应的 `gh` 或 `glab`;项目配置不保存凭据。只有显式操作才会访问远端。`list` 会保留本地条目并提示不完整的来源;在远程默认模式下,仍可用 `bash "$TASKFLOW_PLUGIN_ROOT/hooks/task" intake <goal> --local` 显式创建单条本地待办。

使用 `remote-todo create`、`edit`、`label`、`stage` 和 `promote` 操作选定 Issue。`migrate-to-remote <todo-id> <alias>` 保留原本地条目;`migrate-to-local <alias> <number> --detach` 将内容复制到本地并解除已有关系,不修改远端 Issue。`snapshot <new-file>` 可保存历史元数据:来源顺序、Issue 编号、状态和更新时间;不包含标题、正文或标签。元数据仍可能透露活动情况,也可能过期。来源序号对应导出时的配置顺序;如顺序可能变动,请另行保留当时的顺序。

未提升的本地副本可在核对差异后使用 `reattach-todo <todo-id> <alias> --remote-authoritative` 重新关联原 Issue。本地副本保留,远端 Issue 成为主记录,此操作不修改远端。

已解除关联的活动任务可以用 `reattach-task <task-id>` 重新连接原 Issue;仅当远端阶段与本地一致且 Issue 未关联其他任务时才会连接。请先核对并解决差异;原本地副本和解除关联记录会保留。

迁移前会检查目标仓库全部 Issue 中的稳定 Todo 标记。不要在多个工作区或机器上同时迁移同一条 Todo:检查与创建并非原子操作。在 TaskFlow 外编辑或删除标记会削弱后续去重。

远端写入超时不代表一定失败,重试前须核对操作 ID;`resolve`、`resolve-absent --checked` 和 `ack-update --checked` 用于显式恢复。GitHub 和 GitLab 通常不能保证 Issue 的原子条件更新,并发修改仍可能发生竞态。本地恢复记录必须被 Git 排除,收到提示时运行 `bash "$TASKFLOW_PLUGIN_ROOT/hooks/install-git-hygiene"`。具体命令、隐私和平台限制见[运行时说明](skills/taskflow/references/runtime.md#remote-todo-backend)。
## 仓库文档

`TaskFlowDocs/repository-docs/index.md` 是仓库规则、仓库指引和有范围个人规则的权威路由与检查记录;具体规则内容仍以惯用位置上的源文档为准。
Expand All @@ -88,7 +111,7 @@ TaskFlow 引导 Agent 在每个阶段考虑有帮助的能力,但不替它选

TaskFlow 从不在 base 工作区里写任务文档:每个任务使用独立短生命周期分支与独立工作区,且在工作区的建立是在**第一份任务文档之前**,而不是第一次改动之前。分支规则写在 `CONTRIBUTING.md`,worktree 规则写在 Skill 中。

由于所有任务都追加同一个 `TaskFlowDocs/todo.md`,TaskFlow 为它内置了 Git 合并驱动,由 `hooks/session-start` 按克隆安装。两个分支各自新增条目、或修改不同条目时无需人工介入;同一条目两侧改法不同仍会保留为真实冲突。Todo ID 由目标内容派生而非递增计数,因此同一基点切出的两个分支不会分到同一个 ID。在托管平台网页端合并 PR 时由服务端执行,不会使用该驱动,这条路径仍退化为普通内容冲突。
由于本地任务和已提升的远端任务可能共用 `TaskFlowDocs/todo.md`,TaskFlow 为它内置了 Git 合并驱动,由 `hooks/session-start` 按克隆安装。两个分支各自新增条目、或修改不同条目时无需人工介入;同一条目两侧改法不同仍会保留为真实冲突。Todo ID 由目标内容派生而非递增计数,因此同一基点切出的两个分支不会分到同一个 ID。在托管平台网页端合并 PR 时由服务端执行,不会使用该驱动,这条路径仍退化为普通内容冲突。

创建或更新 Pull Request 前,TaskFlow 必须读取适用的 `.github/pull_request_template.md`,完成每个必填项,在 `plan.md` 中记录字段映射和验证结果;必填项缺失或有歧义时禁止修改 PR。

Expand All @@ -98,7 +121,7 @@ TaskFlow 从不在 base 工作区里写任务文档:每个任务使用独立

## Todo 收件箱

TaskFlow 只自动用于仓库开发需求:功能、Bug 修复、重构、测试、配置/构建/CI 变更。**发布是例外**——它直接在 base 检出上执行 `RELEASE.md`,不创建 Todo 条目、任务目录、分支,也不写 PRD/Plan;它的记录是 `CHANGELOG.md` 段落与 GitHub Release 正文。只读解释、翻译、状态查询、研究、审查和诊断不会创建 Todo 或任务文档;若之后要求实施,再从该实施请求开始进入流程。用户显式调用 `$taskflow` 时,规划或研究也会进入流程。对于适用请求,`TaskFlowDocs/todo.md` 是强制首条记录;条目按 `inbox → clarified → promoted → in_progress → done/cancelled` 演进,提升后创建 `prd.md`、按需创建 `spec.md` 和 `plan.md`,批准后才进入实施。
TaskFlow 只自动用于仓库开发需求:功能、Bug 修复、重构、测试、配置/构建/CI 变更。**发布是例外**——它直接在 base 检出上执行 `RELEASE.md`,不创建 Todo 条目、任务目录、分支,也不写 PRD/Plan;它的记录是 `CHANGELOG.md` 段落与 GitHub Release 正文。只读解释、翻译、状态查询、研究、审查和诊断不会创建 Todo 或任务文档;若之后要求实施,再从该实施请求开始进入流程。用户显式调用 `$taskflow` 时,规划或研究也会进入流程。对于适用请求,应先记录到所选 Todo 存储:默认是本地 `TaskFlowDocs/todo.md`,也可显式配置远端 Issue 仓库;条目按 `inbox → clarified → promoted → in_progress → done/cancelled` 演进,提升后创建 `prd.md`、按需创建 `spec.md` 和 `plan.md`,批准后才进入实施。

验证通过后,TaskFlow 将整个任务目录移入 `TaskFlowDocs/achieved/<task-id>/`,同步 Todo 的任务路径和 `done` 状态,并确认活动路径已不存在。已归档任务只读;其 `old/vN/` 历史仅在当前文档或版本摘要需要时才读取。之后若新工作属于该已完成交付物,先将目录取回活动根目录,记录 Todo 来源与重新打开原因,创建新的 Task version,并在修改实现前重新经过批准门禁。

Expand Down Expand Up @@ -376,7 +399,7 @@ dsh plugin --profile web add <仓库根目录>
使用 $taskflow 规划、执行、验证并归档这个任务。
```

然后把想法记录到 `TaskFlowDocs/todo.md`;澄清后的条目再提升为 `prd.md`、按需的 `spec.md` 和 `plan.md`;审阅任务文档并记录批准,再按每个步骤的 checklist 实施和记录验证结果。
然后把想法记录到所选本地 Todo 或远端 Issue 仓库;澄清后的条目再提升为 `prd.md`、按需的 `spec.md` 和 `plan.md`;审阅任务文档并记录批准,再按每个步骤的 checklist 实施和记录验证结果。

> [!TIP]
> 边界清晰的简单单文件修改可以直接完成并做最小验证,不必为了流程创建空文档。
Expand Down
Loading
Loading