企业官网建设流程全解析

get-shit-done 待办清单工作流 check-todos：从捕获到行动的全链路路由实战

【免费下载链接】get-shit-doneA light-weight and powerful meta-prompting, context engineering and spec-driven development system for Claude Code by TÂCHES.项目地址: https://gitcode.com/GitHub_Trending/getshi/get-shit-done

导读

check-todos是 get-shit-done（GSD）系统中负责"消化待办"的核心工作流：它把会话中随手捕获的零散任务（todo）统一列出、支持按领域（area）过滤、加载选中项的完整上下文，再结合项目路线图（ROADMAP）给出"立即开工 / 加入阶段计划 / 头脑风暴 / 放回清单"等行动路由。阅读本文后，你将掌握如何通过/gsd:capture --list进入待办浏览器、理解其底层gsd-sdk query init.todos的数据契约，以及待办从pending/迁往completed/并同步STATE.md与 git 提交的完整生命周期。

一、check-todos 在 GSD 系统中的定位

get-shit-done 的待办体系遵循"thought → capture → continue"的闭环：工作会话中冒出的想法不打断主线，先通过 add-todo 工作流（即/gsd-add-todo或/gsd:capture无参数形式）落盘为结构化待办文件，之后再由check-todos统一消费。二者互为上下游，目录约定一致：

• 待办文件存放在项目.planning/todos/pending/目录下，命名形如${date}-${slug}.md；
• 已完成待办迁往.planning/todos/completed/；
• 待办文件使用 YAML frontmatter 承载元数据（created、title、area、files），正文分为## Problem与## Solution两节，保证几周后由另一个 Claude/Agent 读取时依然具备足够的上下文。

check-todos的入口路由定义在 capture 命令 中：/gsd:capture --list把控制权交给 check-todos 工作流，--list之后剩余的参数字符串（可选的 area 过滤词）原样透传。也就是说，用户看到的入口是命令，但真正执行"列出→选择→加载→路由→执行"这一整套行为的是本工作流文档。

二、初始化：gsd-sdk query init.todos数据契约

工作流的第一步init_context不是直接扫目录，而是通过 SDK 查询接口读取结构化的待办上下文：

INIT=$(gsd-sdk query init.todos) if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi

这段脚本说明了两个事实：

1. gsd-sdk query init.todos是 get-shit-done SDK 暴露的查询指令（canonical 名init.todos，别名init todos），声明于 command-manifest.init.ts 的 init 家族清单中；
2. 当返回结果以@file:开头时，说明输出被落盘到临时文件（应对超长输出的场景），需要用cat读取后回填到变量。

从返回的 JSON 中，工作流需要提取四个关键字段：todo_count（待办总数）、todos（待办数组）、pending_dir（pending 目录路径，已转为相对项目的 posix 路径）。

从源码实现看，initTodos处理器位于 sdk/src/query/init.ts，其真实行为是：

• 以.planning/todos/pending/为根，readdirSync过滤出*.md文件；
• 用正则逐文件解析 frontmatter 中的created、title、area字段（area缺失时回退为general）；
• 若传入area参数，则跳过todoArea !== area的条目——area 过滤是在 init 阶段完成的，这正是后续list_todos步骤可以直接使用"已过滤的 todos 数组"的原因；
• 输出除todo_count/todos/pending_dir外，还附带completed_dir、area_filter、planning_exists、todos_dir_exists、pending_dir_exists以及commit_docs、date、timestamp等上下文，供后续步骤（如提交、文件名生成）复用。

这一设计意味着工作流文档无需关心底层文件解析细节，SDK 层已经完成了"扫描 + 解析 + 过滤 + 归一化"，工作流只需消费结构化结果——这是 GSD 将"过程性查询"下沉到 SDK 的典型模式。

三、空状态处理：没有待办时给出引导

当todo_count为 0 时，工作流不是简单退出，而是输出一个引导性提示，让用户明确下一步选项：

No pending todos. Todos are captured during work sessions with /gsd-add-todo. --- Would you like to: 1. Continue with current phase (/gsd:progress) 2. Add a todo now (/gsd-add-todo)

这里把两个高频后续动作直接摆出来：回到当前阶段查看进度（对应 progress 工作流，同样会展示 "Pending Todos" 计数），或立即捕获一个新的待办（对应 add-todo 工作流）。空状态的价值在于把"无事可做"转化为"明确的下一步入口"，避免会话悬空。

四、列出待办：编号列表 + 相对时间 + 领域过滤

list_todos步骤直接消费 init 阶段返回的todos数组，将其渲染为带编号的列表：

Pending Todos: 1. Add auth token refresh (api, 2d ago) 2. Fix modal z-index issue (ui, 1d ago) 3. Refactor database connection pool (database, 5h ago) --- Reply with a number to view details, or: - `/gsd:capture --list [area]` to filter by area - `q` to exit

要点包括：

• 编号即选择器：用户直接回复数字即可进入下一步；
• 相对时间：根据 frontmatter 中的created时间戳换算成 "2d ago / 1h ago" 这类人类可读的龄期，方便一眼看出哪些待办搁置最久；
• 领域标签：每行末尾的(api, ui, database)是area字段，帮助用户按模块快速定位；
• 过滤入口：/gsd:capture --list api只展示area: api的待办（对应文档中的parse_filter步骤，/gsd:capture --list显示全部）。过滤能力由 init 层initTodos(args[0])的 area 参数驱动，工作流本身无需二次过滤。

需要说明的是，area的推断发生在捕获阶段而非查询阶段——add-todo 工作流会按文件路径模式（src/api/*→api、src/components/*→ui、tests/*→testing、docs/*→docs、.planning/*→planning、scripts/*、bin/*→tooling，无文件或不明则归general）自动推断领域，并在查重时复用已有待办的 area，保证标签体系的一致性。

五、选择与上下文加载：让后续 Agent "零猜测"

handle_selection步骤等待用户输入数字：合法输入则进入加载流程，非法输入则提示Invalid selection. Reply with a number (1-[N]) or q to exit.。

load_context步骤的核心要求是完整读取选中待办文件，并结构化展示：

## [title] **Area:** [area] **Created:** [date] ([relative time] ago) **Files:** [list or "None"] ### Problem [problem section content] ### Solution [solution section content]

如果 frontmatter 的files字段包含条目（通常是文件路径:行号形式，由捕获时从会话上下文中提取），还需逐一读取并简要总结每个文件——这一步保证了路由到"立即开工"时，Agent 不需要重新摸索代码位置。

六、路线图匹配：待办与阶段计划的关联判断

check_roadmap步骤检查项目根目录是否存在.planning/ROADMAP.md，若存在则做两类匹配：

1. 领域匹配：待办的area是否对应某个即将到来的阶段；
2. 文件重叠匹配：待办的files是否与某个阶段的 scope 存在重叠。

任何匹配结果都会记录在案，直接决定后续行动选项的措辞——这是 GSD 把"随手捕获的碎片"与"宏观路线图"衔接起来的关键机制：一个关于认证模块的待办若能匹配到 Roadmap 中规划中的 Auth 阶段，它就不再是无归属的孤儿任务，而成为阶段计划的有力输入。

七、行动路由：AskUserQuestion 与 text mode 双通道

offer_actions步骤根据是否命中路线图提供两套行动选项。

命中路线图阶段时：

header: "Action" question: "This todo relates to Phase [N]: [name]. What would you like to do?" options: - "Work on it now" → move to done, start working - "Add to phase plan" → include when planning Phase [N] - "Brainstorm approach" → think through before deciding - "Put it back" → return to list

未命中路线图时：

header: "Action" question: "What would you like to do with this todo?" options: - "Work on it now" → move to done, start working - "Create a phase" → /gsd-add-phase with this scope - "Brainstorm approach" → think through before deciding - "Put it back" → return to list

两条路径的差异体现了意图：命中路线图时优先"融入既有计划"，未命中时则开放"新建阶段"的能力（对应 phase 命令 中的 add-phase 路由）。

关键兼容机制——text mode：工作流文档明确要求，当配置workflow.text_mode: true或--text出现在$ARGUMENTS中时，设置TEXT_MODE=true，并把所有AskUserQuestion调用替换为纯文本编号列表、等待用户输入编号。原因很实在：AskUserQuestion是 Claude Code 特有的交互工具，在 OpenAI Codex、Gemini CLI 等非 Claude 运行时中不可用。从配置模型看，text_mode是 SDK config.ts 中WorkflowConfig的布尔字段之一（与其他 workflow.* 开关并列），支持按项目持久化（例如gsd-sdk query config-set workflow.text_mode true）。这条约定在 GSD 全部工作流中统一执行，是跨运行时可用性的基石。

八、动作执行与状态同步

execute_action步骤按四种选择执行：

Work on it now（立即开工）——这是唯一会"消费"待办的动作：

mv ".planning/todos/pending/[filename]" ".planning/todos/completed/"

随后更新 STATE.md 的待办计数，把 Problem/Solution 上下文呈现给用户，并开始工作或询问如何推进。注意这里用的是mv移动文件，语义上待办从 pending 流转到 completed。

Add to phase plan（加入阶段计划）——在阶段规划笔记中记录该待办引用，保持 pending 状态，返回列表或退出。

Create a phase（新建阶段）——展示/gsd-add-phase [description from todo]，保持 pending，由用户在新会话中执行命令（体现"待办清单是载体、执行者是用户主导"的设计）。

Brainstorm approach（头脑风暴）——保持 pending，开启关于问题与方案的讨论。

Put it back（放回清单）——直接回到list_todos步骤重新选择。

任何改变待办数量的动作之后，update_state步骤要求重新运行init todos获取最新计数，然后更新.planning/STATE.md中的### Pending Todos小节（如果存在）。这与 STATE.md 模板的设计一脉相承：Pending Todos节位于## Accumulated Context之下，内容就是"从.planning/todos/pending/捕获的想法"的摘要，保持精简（数量多时只显示计数并指向/gsd:capture --list），参见 state 模板。STATE.md 的定位是"读一次就知道我们在哪"的短时记忆，因此更新必须及时且轻量。

九、git 提交：文档变更纳入版本管理

最后一步git_commit在待办被移入done/时执行提交：

git rm --cached .planning/todos/pending/[filename] 2>/dev/null || true gsd-sdk query commit "docs: start work on todo - [title]" --files .planning/todos/completed/[filename] .planning/STATE.md

• 第一行用git rm --cached把原 pending 文件从索引中移除（2>/dev/null || true容忍文件本就不在索引中的情况）；
• 第二行通过 SDK 的commit查询指令提交completed/下的新文件与更新过的STATE.md，提交信息统一为docs: start work on todo - [title]；
• 该工具会自动尊重commit_docs配置与 gitignore——若项目配置commit_docs: false（该字段在 init.todos 返回的 JSON 中可直接读到，也是 config.ts 中planning.commit_docs的配置项），则跳过提交，避免对不希望自动提交的仓库产生副作用。

提交后向用户确认：Committed: docs: start work on todo - [title]。这一设计把"待办生命周期"完整纳入 git 历史，任何一次"开始处理某待办"的决策都留有痕迹，配合 GSD 其他工作流（如 progress 的 forensic 审计会检查未提交变更）构成可审计的项目状态体系。

十、成功标准：check-todos 的验收清单

工作流文档在<success_criteria>中给出了自身完成的验收标准，这也是判断"待办浏览是否正确执行"的检查表：

• 所有 pending 待办均已列出，含 title、area、age（相对时间）；
• 若指定了 area 过滤，过滤已生效；
• 选中待办的完整上下文已加载（Problem / Solution / Files）；
• 已检查路线图并识别阶段匹配；
• 已提供恰当的行动选项；
• 已执行用户选择的动作；
• 待办数量变化后 STATE.md 已同步更新；
• 待办移入 done/ 后变更已提交 git。

这套标准同时充当质量门禁：任何一步缺失都意味着工作流没有跑完，可被其他校验工具（如 progress 工作流 的 Pending Todos 区块、forensic 审计的 Check 5 "blocking operational todos"）反向发现。

总结：一条可复用的"碎片任务消化流水线"

check-todos 工作流展示了一个完整的待办消费模式：SDK 查询接口提供结构化数据（init.todos）→ 空状态引导 → 编号列表 + 相对时间 + 领域过滤 → 全量上下文加载 → 路线图匹配 → 四选一行动路由 → 状态同步 → git 提交。它不依赖固定的 UI 组件（AskUserQuestion 仅对 Claude 运行时启用，text mode 保证了跨运行时兼容），全部状态落在.planning/todos/与STATE.md这些纯文本文件上，任何 Agent 或人类都可以直接读取和介入。对于想要在自己的工作流系统中实现"捕获-审查-路由-执行"闭环的开发者，这个工作流从数据契约（init.todos 的字段设计）、目录约定（pending/completed 流转）到交互设计（空状态、编号选择、行动路由）都是一份高密度、可直接参照的范本。

【免费下载链接】get-shit-doneA light-weight and powerful meta-prompting, context engineering and spec-driven development system for Claude Code by TÂCHES.项目地址: https://gitcode.com/GitHub_Trending/getshi/get-shit-done