fix: improve taskflow skill usability

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>",
+		"若用户没有提供 `task-id`，先询问任务 ID",
+		"任务目录存在但 `taskflow.yaml` 缺失",
+		"这是预期状态，运行 `start --dry-run`",
+		"init <task-id>",
+		"start <task-id> --dry-run",
+		"start <task-id> --execute",
+		"open <task-id>",
+		"validate <task-id>",
+		"repo add <task-id>",
+		"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)
+		}
+	}
+}

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>/<task-id>`; `--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 <tasks-root> status <task-id>` for diagnosis and handoff.
+任务目录是 `<tasks-root>/<task-id>`，`--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 <tasks-root> status <task-id>
+```
+
+根据状态选择下一步：
+
+| 当前情况 | 下一步 |
+| --- | --- |
+| 任务目录不存在 | 确认仓库路径后运行 `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 <tasks-root> init <task-id> \
   --repo <first-name>=<absolute-path> \
-  [--repo <additional-name>=<absolute-path>]
+  --repo <additional-name>=<absolute-path>
+
+taskflow --tasks-root <tasks-root> start <task-id> --dry-run
 ```
 
-`init` is metadata-only. Before worktree creation, run:
+`init` 只写任务元数据，不创建分支或 worktree。dry-run 后报告仓库顺序、依赖顺序、fetch/worktree 计划和冲突；只有用户明确批准后才运行：
 
 ```bash
-taskflow --tasks-root <tasks-root> start <task-id> --dry-run
+taskflow --json --tasks-root <tasks-root> start <task-id> --execute
 ```
 
-Present repository order, configured dependencies, planned fetches/worktrees, and reported conflicts. Obtain explicit approval before:
+执行成功后再打开工具：
 
 ```bash
-taskflow --json --tasks-root <tasks-root> start <task-id> --execute
+taskflow --tasks-root <tasks-root> open <task-id>
+taskflow --tasks-root <tasks-root> open <task-id> --tool claude
+taskflow --tasks-root <tasks-root> open <task-id> --tool codex -- --model <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 <tasks-root> repo add <task-id> \
   --repo <name>=<absolute-path> \
   [--depends-on <existing-repo>] \
-  [--dry-run]
+  --dry-run
+```
 
+向用户说明将追加的仓库和依赖，并获得确认后去掉 `--dry-run` 执行。实际追加会修改 `taskflow.yaml` 和 `.taskflow/state.json`，但不会创建 worktree。追加成功后必须重新运行：
+
+```bash
 taskflow --tasks-root <tasks-root> start <task-id> --dry-run
 taskflow --tasks-root <tasks-root> start <task-id> --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 <tasks-root> open <task-id>
-taskflow --tasks-root <tasks-root> open <task-id> --tool claude
-taskflow --tasks-root <tasks-root> open <task-id> -- --model <model>
+taskflow --tasks-root <tasks-root> validate <task-id>
+taskflow --tasks-root <tasks-root> validate <task-id> --repo <name>
+taskflow --json --tasks-root <tasks-root> status <task-id>
 ```
 
-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 <tasks-root> validate <task-id>
-taskflow --json --tasks-root <tasks-root> status <task-id>
-```
+先保留状态文件和 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 <name>` 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；这些是独立且需要用户授权的流程。

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 判断当前任务阶段，并安全完成多仓库工作区的准备、启动或验证。"