From 814e5a8ae316cdbe4b4e566e244ba08895c3e6ac Mon Sep 17 00:00:00 2001 From: chenquan Date: Wed, 12 Aug 2026 09:07:48 +0800 Subject: [PATCH] fix: improve taskflow skill usability --- skills/skill_content_test.go | 65 ++++++++++++++++++ skills/taskflow/SKILL.md | 104 +++++++++++++++++++---------- skills/taskflow/agents/openai.yaml | 6 +- 3 files changed, 135 insertions(+), 40 deletions(-) create mode 100644 skills/skill_content_test.go diff --git a/skills/skill_content_test.go b/skills/skill_content_test.go new file mode 100644 index 0000000..a866835 --- /dev/null +++ b/skills/skill_content_test.go @@ -0,0 +1,65 @@ +package skills + +import ( + "strings" + "testing" +) + +func TestTaskflowSkillGuidesTheUserThroughTheLifecycle(t *testing.T) { + content, err := Files.ReadFile("taskflow/SKILL.md") + if err != nil { + t.Fatal(err) + } + + text := string(content) + for _, required := range []string{ + "status ", + "若用户没有提供 `task-id`，先询问任务 ID", + "任务目录存在但 `taskflow.yaml` 缺失", + "这是预期状态，运行 `start --dry-run`", + "init ", + "start --dry-run", + "start --execute", + "open ", + "validate ", + "repo add ", + "STATE_CONFLICT", + "WORKTREE_MISMATCH", + "SOURCE_LOCK_UNAVAILABLE", + "REPO_ADD_WRITE_FAILED", + "VALIDATION_*", + "--worktree", + } { + if !strings.Contains(text, required) { + t.Errorf("skill is missing %q", required) + } + } + + for _, forbidden := range []string{ + "inventory.json", + "contract owners", + "角色负责人", + } { + if strings.Contains(text, forbidden) { + t.Errorf("skill contains removed or unsupported guidance %q", forbidden) + } + } +} + +func TestTaskflowSkillMetadataMatchesTheGuidance(t *testing.T) { + content, err := Files.ReadFile("taskflow/agents/openai.yaml") + if err != nil { + t.Fatal(err) + } + + text := string(content) + for _, required := range []string{ + "Taskflow 工作区向导", + "向导式安全管理多仓库 AI 工作区", + "$taskflow", + } { + if !strings.Contains(text, required) { + t.Errorf("metadata is missing %q", required) + } + } +} diff --git a/skills/taskflow/SKILL.md b/skills/taskflow/SKILL.md index f6f79a7..4e12bc0 100644 --- a/skills/taskflow/SKILL.md +++ b/skills/taskflow/SKILL.md @@ -1,84 +1,114 @@ --- name: taskflow -description: Safely operate Taskflow multi-repository Git workspaces, including initialization, worktree planning and execution, built-in Codex or Claude launch, recovery, status, and configured validation. +description: 用 Taskflow 安全准备、启动和验证多 Git 仓库 AI 编程工作区。用户需要初始化任务、创建或恢复 worktree、追加仓库、打开 Codex/Claude、查看状态或运行项目检查时使用。 --- -# Taskflow +# Taskflow 使用向导 -Use `taskflow` as the authority for task workspace, fetch, worktree, repository-append, and built-in tool-launch operations. Do not replace these mutations with shell-composed Git or filesystem commands. +先判断任务当前阶段，再执行最小必要的一步。Taskflow 负责任务配置、fetch、worktree、仓库追加和 Codex/Claude 启动；不要用手写 Git 或文件系统命令替代这些操作。 -## Locate and inspect +## 先定位任务 -1. Resolve the task directory as `/`; `--tasks-root` defaults to the current directory. -2. Inspect `taskflow.yaml`, `.taskflow/state.json`, current status, and the latest validation report when relevant. Do not require or interpret `inventory.json`. -3. Prefer `taskflow --json --tasks-root status ` for diagnosis and handoff. +任务目录是 `/`，`--tasks-root` 默认当前目录。若用户没有提供 `task-id`，先询问任务 ID；若没有提供任务根目录，使用当前目录并告知用户，不能猜测其他任务。已有任务不要通过扫描目录或猜测名称来选择。 -Repository order is significant: the first repository is the Codex or Claude cwd. `depends_on` describes only start and validation order; do not infer repository roles, ownership, contracts, or delivery readiness. +有任务 ID 后，先运行只读诊断： -## Prepare a task +```bash +taskflow --json --tasks-root status +``` + +根据状态选择下一步： + +| 当前情况 | 下一步 | +| --- | --- | +| 任务目录不存在 | 确认仓库路径后运行 `init` | +| 任务目录存在但 `taskflow.yaml` 缺失 | 不要直接 `init`；确认这是空任务目录，或报告目录不是 Taskflow 任务 | +| `taskflow.yaml` 或 state 无法解析 | 停止，不覆盖文件；报告 `INVALID_CONFIGURATION` 或 `STATE_INCOMPATIBLE` | +| 已初始化，worktree 尚未创建 | 这是预期状态，运行 `start --dry-run` | +| dry-run 已给出计划 | 向用户说明计划并请求确认，再运行 `start --execute` | +| worktree 已启动 | 运行 `open` | +| 已完成编码 | 运行 `validate`，再运行 `status` | +| 需要新仓库 | 先用 `repo add --dry-run` 预览，确认后追加，再重新执行 start 流程 | + +initialized 阶段的 `status` 可能显示 worktree 不存在；在 `start --execute` 之前这是预期提示，不要把它当成 worktree 损坏。不要把 `status` 中的历史验证结果当成当前代码结论；配置发生变化时，`validationConfigStale: true` 需要新的 `validate` 消除。 + +## 新建并打开任务 -Initialize only from explicit local Git repositories: +仓库声明顺序必须稳定；第一个仓库是 `open` 的工作目录，后续仓库会作为 additional directories： ```bash taskflow --tasks-root init \ --repo = \ - [--repo =] + --repo = + +taskflow --tasks-root start --dry-run ``` -`init` is metadata-only. Before worktree creation, run: +`init` 只写任务元数据，不创建分支或 worktree。dry-run 后报告仓库顺序、依赖顺序、fetch/worktree 计划和冲突；只有用户明确批准后才运行： ```bash -taskflow --tasks-root start --dry-run +taskflow --json --tasks-root start --execute ``` -Present repository order, configured dependencies, planned fetches/worktrees, and reported conflicts. Obtain explicit approval before: +执行成功后再打开工具： ```bash -taskflow --json --tasks-root start --execute +taskflow --tasks-root open +taskflow --tasks-root open --tool claude +taskflow --tasks-root open --tool codex -- --model ``` -Never infer approval for execute mode. A configured `execution.fetch: true` authorizes the planned remote fetch. +`open` 默认启动 Codex；`--` 后的模型或权限参数原样透传。不要透传 `--worktree`，避免创建嵌套 worktree。 -## Add a repository +## 追加仓库 -Use the append-only command and repeat the dry-run/execute transition: +追加是 append-only：不会改变、删除或重排已有仓库，也不会立即创建 worktree。先预览： ```bash taskflow --tasks-root repo add \ --repo = \ [--depends-on ] \ - [--dry-run] + --dry-run +``` +向用户说明将追加的仓库和依赖，并获得确认后去掉 `--dry-run` 执行。实际追加会修改 `taskflow.yaml` 和 `.taskflow/state.json`，但不会创建 worktree。追加成功后必须重新运行： + +```bash taskflow --tasks-root start --dry-run taskflow --tasks-root start --execute ``` -`repo add` never changes or reorders existing repositories, never creates a worktree itself, and invalidates the current configuration match of any historical validation report. +`depends_on` 只表示 start 和 validate 的执行顺序，不表示仓库所有权、接口契约或交付完成度。 -## Open and verify +## 编码后验证 -Run `open` only after successful `start --execute`: +运行配置中的检查；需要限定仓库时，依赖闭包也会被验证： ```bash -taskflow --tasks-root open -taskflow --tasks-root open --tool claude -taskflow --tasks-root open -- --model +taskflow --tasks-root validate +taskflow --tasks-root validate --repo +taskflow --json --tasks-root status ``` -Codex is the default. Taskflow validates every configured worktree before launch and passes later repositories plus the task root as additional directories. Explicit model and permission arguments after `--` are forwarded unchanged. Never pass nested-worktree arguments. +报告验证是否成功、失败仓库、检查输出和是否存在配置漂移。不要把 Taskflow 的 `validate` 结果扩展解释为 pushed、PR 已创建或任务已完成。 -After implementation, run configured validation and report raw status facts: +## 失败时怎么处理 -```bash -taskflow --tasks-root validate -taskflow --json --tasks-root status -``` +先保留状态文件和 worktree，读取 JSON 结果中的 `code`、`repo` 和 `message`，再采取最小修复： + +- `INVALID_CONFIGURATION`、`STATE_INCOMPATIBLE`：检查任务目录、当前 schema 和 state；不要覆盖旧状态强行继续。 +- `WORKSPACE_NOT_STARTED`：先完成 `start --dry-run` 和获批的 `start --execute`。 +- `STATE_CONFLICT`：说明配置摘要与已持久化状态不一致；不要手改状态或删除 worktree。 +- `WORKTREE_MISMATCH`、`BRANCH_OCCUPIED`：检查 `git worktree list --porcelain` 和目标分支，确认冲突后再处理。 +- `START_FAILED`：查看失败仓库和持久化状态，修复外部原因后重试同一个 `start --execute`；Taskflow 支持恢复已完成动作。 +- `REPO_ADD_WRITE_FAILED`：确认任务锁和任务目录可写，先检查配置和 state 是否保持不变，再决定是否重试 `repo add`。 +- `REPO_ADD_PHASE_UNSUPPORTED`：当前 phase 不允许追加仓库，不要手改配置；先完成当前任务阶段或重新创建独立任务。 +- `SOURCE_LOCK_UNAVAILABLE`、`TASK_LOCKED`：报告锁的位置和占用情况，不删除锁文件；必要时请求用户授权后重试。 +- `TOOL_NOT_FOUND`：检查 `codex` 或 `claude` 是否在 `PATH` 中。 +- `VALIDATION_*`：报告失败仓库、检查名称、退出码、超时和 stderr；修复代码或环境后重新运行 `validate`，不要仅凭旧报告宣称通过。 -`validate --repo ` includes the repository's dependency closure. Treat `lastValidation` as historical evidence and `validationConfigStale` only as a configuration-digest comparison. +每次命令结束时只需给出：结果、是否发生修改、下一条安全命令或需要用户确认的事项。 -## Recovery and safety +## 边界 -- After a partial start, inspect status/state, fix the external cause, and rerun the same `start --execute`; do not delete state or worktrees to force recovery. -- Preserve state on `STATE_CONFLICT`, `STATE_INCOMPATIBLE`, lock, branch, or worktree diagnostics and propose the smallest non-destructive correction. -- Commit, pull, push, PR, merge, archive, release, and cleanup are separate user-authorized workflows outside Taskflow. -- After every command, report the concrete result and the smallest safe next command. +Taskflow 不自动执行 commit、pull、push、PR、merge、release、archive 或 worktree cleanup；这些是独立且需要用户授权的流程。 diff --git a/skills/taskflow/agents/openai.yaml b/skills/taskflow/agents/openai.yaml index 8ab965c..293d9f5 100644 --- a/skills/taskflow/agents/openai.yaml +++ b/skills/taskflow/agents/openai.yaml @@ -1,4 +1,4 @@ interface: - display_name: "Taskflow AI Workspace" - short_description: "Safely coordinate multi-repository AI workspaces" - default_prompt: "Use $taskflow to prepare, coordinate, and safely operate this multi-repository AI coding task." + display_name: "Taskflow 工作区向导" + short_description: "向导式安全管理多仓库 AI 工作区" + default_prompt: "使用 $taskflow 判断当前任务阶段，并安全完成多仓库工作区的准备、启动或验证。"