# csv-todo-loop

> 在任意仓库中按 CSV TODO 清单闭环逐条处理：每条 todo 仅允许一次 `codebase-retrieval`（MCP/LSP）索引后再改代码；每条 todo 必须按项目文档指定的构建命令构建成功再 `git commit`；提交后回写 CSV 的 `status/notes/evidence/commit` 并继续下一条。启动时自动读取 `{repo_root}/AGENTS.md`（优先）或 `{repo_root}/CLAUDE.md` 作为项目规则输入上下文。

- Author: mci77777
- Repository: mci77777/SKILL-csv-todo-loop
- Version: 20260125115214
- Stars: 1
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/mci77777/SKILL-csv-todo-loop
- Web: https://mule.run/skillshub/@@mci77777/SKILL-csv-todo-loop~csv-todo-loop:20260125115214

---

---
name: csv-todo-loop
description: 在任意仓库中按 CSV TODO 清单闭环逐条处理：每条 todo 仅允许一次 `codebase-retrieval`（MCP/LSP）索引后再改代码；每条 todo 必须按项目文档指定的构建命令构建成功再 `git commit`；提交后回写 CSV 的 `status/notes/evidence/commit` 并继续下一条。启动时自动读取 `{repo_root}/AGENTS.md`（优先）或 `{repo_root}/CLAUDE.md` 作为项目规则输入上下文。
---

# CSV TODO 闭环执行

## 0) 项目规则加载（硬约束）

- 自动读取项目根目录的 `AGENTS.md`；若存在则**不再读取** `CLAUDE.md`（避免冲突）；否则读取 `CLAUDE.md`。
- 将读取到的内容作为本次执行的 SSOT：构建/架构规则、提交规范、目录约束、代码风格、工具链等。
- 未在项目文档中找到**明确的构建命令/架构规则**时：停止并向用户提问；禁止凭经验猜命令。

命令：

- 读取并输出规则（便于纳入上下文）：
  - `python "$CODEX_HOME/skills/csv-todo-loop/scripts/project_context.py" show`
  - 或：`python "$CODEX_HOME/skills/csv-todo-loop/scripts/project_context.py" --json`
- 解析构建命令候选（只输出候选与出处，不会替你做决定）：
  - `python "$CODEX_HOME/skills/csv-todo-loop/scripts/project_context.py" build-hints`
  - 可选包含 README：`python "$CODEX_HOME/skills/csv-todo-loop/scripts/project_context.py" build-hints --include-readme`

## 输入 CSV 的最低要求（KISS）

- 任意列都可；但必须能识别出：
  - `status` 列（大小写不敏感；如 `Status`/`status`）
  - “任务描述”列（优先匹配：`task`/`todo`/`description`/`action`/`Notes`）
- 可选列（若存在会被复用）：`mcp_scan_query`、`notes`、`evidence`、`commit`
- 若缺少上述可选列，脚本会追加这些列（SSOT 落在 CSV 自身）

## 单条 TODO 工作流（必须闭环）

1) **取下一条 todo**
   - `python "$CODEX_HOME/skills/csv-todo-loop/scripts/csv_todo.py" next <csv>`

2) **仅一次 MCP 索引（硬约束）**
   - 必须只调用一次 `codebase-retrieval`，并使用脚本输出的 `mcp_query`（或 CSV 的 `mcp_scan_query`）
   - 示例（注意路径必须用 Windows 盘符）：

```json
{
  "project_root_path": "X:/YourRepo",
  "query": "（从脚本输出复制）"
}
```

3) **同义实现扫描（不额外消耗 MCP 次数）**
   - 优先用 `ast-grep`；仅在确有需要时退回 `rg`
   - 目标：复用/合并同义实现到 SSOT；禁止引入影子状态

4) **最小改动实现（YAGNI→SSOT→KISS）**
   - 只完成该 todo 的验收闭环：触发/校验/状态落地/错误处理/可观测
   - 发现“最佳实践”冲突时：在当前 todo 内做最小简化，不另起“重构 todo”

5) **构建成功后再提交（硬约束）**
   - 构建命令必须来自项目文档（第 0 步），不要擅自决定
   - `python "$CODEX_HOME/skills/csv-todo-loop/scripts/todo_cycle.py" --csv <csv> --row <row> --build "<构建命令>" [--notes "<补充说明>"] [--msg "<commit subject>"]`

## 失败处理（仍然闭环）

- 构建失败：继续在当前 todo 修复，直到构建通过；禁止拆分成多个提交
- 无改动可提交：补充 `notes`（说明原因）并用 `skip` 或保留 `pending`（按团队约定）
  - `python "$CODEX_HOME/skills/csv-todo-loop/scripts/csv_todo.py" skip --csv <csv> --row <row> --notes "<原因>"`