# spec-kit-loop

**Repository Path**: wb04307201/spec-kit-loop

## Basic Information

- **Project Name**: spec-kit-loop
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-12
- **Last Updated**: 2026-07-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# spec-kit-loop

> **SDD 自循环开发工具** — 文档驱动的多 agent 编排,让 spec → plan → tasks → implement → test 自动推进,无需人工盯守。

`spec-kit-loop` 是一个 Python 工具,把"写文档"和"写代码"用多个 AI sub-agent 串成一个无人值守的循环。你只需要填一份 `INPUT.md`,loop 自动跑完所有阶段并产出可运行的代码 + 测试。

**English**: [README.md](README.md)

---

## 30 秒上手

```bash
# 1. 安装依赖
pip install pyyaml

# 2. 在你的项目目录里 init
cd /path/to/your-project
python /path/to/spec-kit-loop/wrapper.py init "做一个 TODO 应用,前端 React,后端 FastAPI"

# 3. 跑一轮(单次)
python /path/to/spec-kit-loop/wrapper.py

# 4. 完全无人值守(后台长驻 + 自动续跑)
python /path/to/spec-kit-loop/wrapper.py --watch

# 5. 看进度
python /path/to/spec-kit-loop/wrapper.py status
```

详见 [USAGE.md](USAGE.md)。

---

## 它做什么

`spec-kit-loop` 把软件开发拆成 6 个 phase,每个 phase 由一个专门的 sub-agent 负责:

```
constitution  →  spec  →  plan  →  tasks  →  implement  →  converged
   ↓              ↓       ↓        ↓           ↓
constitution-  spec-    plan-    task-     fullstack-    (auto-stop)
keeper        author   architect decomposer implementer
                                              ↻ qa-tester / bug-fixer
```

所有 sub-agent **只通过 state.json 沟通**(不通过对话)。wrapper 是调度器,负责:

1. 读 `.wbs/state.json` 看当前 phase
2. 派发对应的 sub-agent(调 `claude` CLI)
3. 等 sub-agent 返回 JSON 结果
4. 更新 state.json
5. 进入下一个 phase / 迭代
6. 检测收敛 → 自动停

---

## A/B/C 对抗性审查

`spec` / `plan` / `test-design` 三个 phase 各加一轮 **编写者(A) ↔ 审查者(B) ↔ 裁决者(C)** 的循环:

```
specify → [A 写 spec.md] → [B 找 issues] → [C 判收敛]
                ↑                                  ↓
                └──────── continue ────────── converged → plan
```

**收敛判据**(4 个机械信号 + 1 个 LLM 语义裁决):
1. 没有 blocker/major 残留
2. B 自报 `converged=true`
3. 最近 2 轮 issue 数不增长
4. 最近 N 轮持续递减(diminishing returns)

C 只在机械信号"灰色地带"才跑 LLM;常见 80% case 由 wrapper 用数学判据直接收敛。

**配置见** `loop_config.yaml` 的 `loop.review.*` 和 `loop.convergence.*`。
**关闭**: `loop.review.enabled: false` 退回旧行为(无 reviewer / 无 adjudicator)。
**issue ledger**: 所有 issue 落在 `.wbs/issues.json`,nit/minor 追加到 `.wbs/open_nits.md`。

---

## 设计原则

| 设计原则 | 实现 |
|---|---|
| **state.json 是唯一真相** | 所有 sub-agent 通过 `update_state(mutator)` 原子写 state.json(同进程锁 + 临时文件 rename) |
| **文档驱动** | 用户只填 `.wbs/INPUT.md`,wrapper 解析 `## 章节` 自动识别新需求 |
| **零 human gate** | 全自动推进,只在 `wait_human` 或 auto-stop 时停 |
| **智能 phase 重启** | `phase=converged` 时检测文档变化 → 自动重置到 `specify` |
| **收敛自动停止** | qa-tester 报告 PASS + 无未完成任务 + tasks 已勾选 → 自动 `phase=converged` + auto-stop |
| **跨平台 lock** | 基于文件系统 + 同进程锁,防多实例并发写 state.json |
| **rate-limit + 心跳** | 默认 5 min/轮,防烧 token;心跳检测卡死 |

---

## 仓库结构

```
spec-kit-loop/                          # 本仓库(独立)
├── wrapper.py                          # 主入口:init / status / reset / 跑一轮 / --watch
├── README.md                           # 英文文档
├── README.zh-CN.md                     # 本文件(中文)
├── USAGE.md                            # 完整使用手册(命令、配置、故障排查)
├── LICENSE                             # MIT
├── requirements.txt                    # 唯一外部依赖:PyYAML
├── spec_kit_loop/                      # Python 包(下划线,合法标识符)
│   ├── __init__.py                     # __version__
│   └── lib/                            # 核心模块(无外部项目依赖)
│       ├── state.py                    # state.json 原子读写 + schema 校验
│       ├── charter.py                  # 读 INPUT.md / DESIGN.md / TESTS.md(自动 fallback)
│       ├── dispatch.py                 # 决策下一个 sub-agent + 构造 prompt
│       ├── docwatcher.py               # SHA-256 文档变更检测
│       ├── input_parser.py             # 解析 INPUT.md 的 ## 章节
│       ├── backlog.py                  # 解析 BACKLOG.md 的 [ ]/[x] 标记
│       ├── config.py                   # 加载 + 合并 loop_config.yaml
│       ├── heartbeat.py                # 心跳文件 + 卡死检测
│       ├── lock.py                     # 文件锁(同进程 + 跨进程)
│       ├── rate_limit.py               # 限流(最小间隔 + 小时/天配额)
│       ├── log.py                      # 日志(console + 滚动文件)
│       ├── paths.py                    # 路径解析(WBS_ROOT 或 cwd)
│       ├── exceptions.py               # FatalError / RecoverableError
│       ├── subprocess.py               # 调 agent CLI(claude / codex)
│       ├── e2e.py                      # 单元测试编排(语言无关)
│       └── notify.py                   # 控制台 / Webhook / 邮件通知
├── templates/                          # init 时复制到目标项目 .wbs/
│   ├── state.json                      # state.json 模板(v2 schema)
│   ├── loop_config.yaml                # 配置模板(语言无关,注释里举了几个例子)
│   ├── PROJECT_CHARTER.md              # v1 多文档格式(已弃用,留作参考)
│   ├── TECH_REQUIREMENTS.md
│   ├── BACKLOG.md
│   └── NOTES.md
└── scheduler-setup.md                  # OS 调度器配置指南(cron / Task Scheduler)
```

---

## 安装

### 1. 装 Python 依赖

```bash
pip install -r spec-kit-loop/requirements.txt
```

### 2. 装 agent CLI(必须)

loop 默认调 `claude`(`@anthropic-ai/claude-code`):

```bash
npm install -g @anthropic-ai/claude-code
```

或改用其他 agent(需实现 `loop/lib/subprocess.py::invoke_codex()` 之类)。

### 3. 把 spec-kit-loop 加到 PATH(可选)

```bash
# Linux/macOS
ln -s /path/to/spec-kit-loop/wrapper.py ~/bin/sdd-loop

# Windows(管理员 PowerShell)
# 把 spec-kit-loop/ 所在目录加到 PATH
```

---

## 在你的项目里用

```bash
cd /path/to/your-project
python /path/to/spec-kit-loop/wrapper.py init "你的项目目标"
```

init 会:
1. 创建 `.wbs/` 目录
2. 复制 `templates/*` 到 `.wbs/`(可自由修改)
3. 生成 v2 schema 的 `state.json`,初始 `phase=constitution`
4. 生成 `loop_config.yaml`(可自由修改)
5. **自动跑第一轮** constitution-keeper

接下来:
- 手动跑下一轮:`python /path/to/spec-kit-loop/wrapper.py`
- 后台长驻:`python /path/to/spec-kit-loop/wrapper.py --watch`
- 看进度:`python /path/to/spec-kit-loop/wrapper.py status`
- 重置:`python /path/to/spec-kit-loop/wrapper.py reset`

详见 [USAGE.md](USAGE.md)。

---

## 语言 / 框架无关

loop **不绑定任何语言或框架**。所有技术栈相关的命令都在项目的 `.wbs/loop_config.yaml` 里配置:

```yaml
test:
  # Java Spring Boot
  backend_start_cmd: ./mvnw spring-boot:run
  backend_unit_cmd: ./mvnw test

  # 或 Go
  # backend_start_cmd: go run ./cmd/server
  # backend_unit_cmd: go test ./...

  # 或 Python FastAPI
  # backend_start_cmd: uvicorn main:app --reload
  # backend_unit_cmd: pytest

  # 前端任意
  frontend_start_cmd: npm run dev
  frontend_unit_cmd: npm test
```

loop 自带的 `lib/e2e.py` 支持解析 Maven / pytest / vitest / jest / go test / cargo test 输出。

---

## 平台支持

| OS | 状态 |
|---|---|
| Linux | ✅ 完整支持 |
| macOS | ✅ 完整支持 |
| Windows | ✅ 完整支持(`fcntl` 在 Windows 上自动降级) |

原子写 state.json 使用 `tempfile + os.replace`(Windows 兼容),带重试机制防 AV 扫描短暂锁定。

---

## 与 spec-kit 的关系

loop 可以和 [spec-kit](https://github.com/github/spec-kit) 配合使用:

- loop init 时检测 `.specify/` 是否存在;wrapper 不碰 .specify/,spec-kit 由用户独立管理
- constitution-keeper sub-agent 写 `.specify/memory/constitution.md`
- spec-author sub-agent 写 `specs/<branch>/spec.md`
- plan-architect / task-decomposer 写对应的 `plan.md` / `tasks.md`

但 loop **不依赖** spec-kit —— 没装 spec-kit 也能独立工作。

---

## 限制 & 已知问题

- **rate-limit 默认 300s/轮**:首次跑完一轮要等 5 分钟才能跑下一轮。改 `.wbs/loop_config.yaml` 里的 `loop.rate_limit.min_interval_seconds` 调小(不推荐,< 60s 可能烧 token 太快)。
- **convergence 依赖 qa-tester 信号**:如果 qa-tester 输出不含 "PASS / converged / implement_done / feature-complete / nothing further" 等关键词,不会自动收敛。手动跑 `wrapper reset` 重来,或编辑 `state.json` 把 `phase` 改成 `converged`。
- **agent CLI 必须能调**:loop 默认调 `claude`,需要 PATH 里能直接 `claude --version` 跑通。
- **不支持并行多 feature**:v2 schema 是单项目单 feature 设计。

---

## 近期 bug 修复(post-0.8.2.dev0)

以下 bug 在 2026 年 7 月跑 `project-wbs` 参考项目时发现并修复。如果你在早于此 commit 的 tagged release 上跑,留意以下症状:

1. **"稳定 qa" 启发式过早触发 `phase=converged`** (`wrapper.py:_check_implement_convergence` 弱信号 C)。原逻辑若最近 3 次 qa-tester 都报 `qa pass` 即返回 `True`,即使 `specs/<branch>/tasks.md` 还有未勾选 `[ ]`。**修**:弱信号 C 额外要求 `not has_pending_in_tasks`(扫 `specs/<branch>/tasks.md` 找 `[ ]`)。**症状**:loop 宣布"完成"但还有 ~80% task 未做 → 静默丢失进度
2. **`detect_changes` 读错 key** (`spec_kit_loop/lib/docwatcher.py:detect_changes`)。原代码读 `state["doc_hashes"]`,但实际存放在 `state["loop"]["doc_hashes"]`,导致每个文档都视为"变了" → smart-restart 每次收敛都触发。**修**:双 fallback 取 `state.get("loop", {}).get("doc_hashes") or state.get("doc_hashes") or {}`。**症状**:每次 qa-tester PASS 后,loop 重置回 `specify`,清空 `completed_tasks`
3. **`smart-restart` 重置时 `completed_tasks: []`** (`wrapper.py:_check_smart_phase_restart`)。reset mutator 把 `current_iteration.completed_tasks` 清零,丢掉所有进度。**修**:保留前次 `completed_tasks / last_sub_agent / last_result / in_progress_tasks`;若已经为空(防御性),用 `loop.iteration_history` 里 `details` 起始的 `T\d{3}` 正则重建。**症状**:22+ 个 task 静默清零为 `[]`
4. **Trigger 2 只读 `.wbs/BACKLOG.md` (v1)** (`wrapper.py:_run_watch` should_run 检查)。v2 项目没有 BACKLOG.md — 他们的清单在 `specs/<branch>/tasks.md`。原代码看不到 `[ ]` → 不派 implementer → 静默 skip 死循环。**修**:BACKLOG.md 为空时,额外扫 `specs/<branch>/tasks.md` 的 `- [ ] TNNN`,且不在 `current_iteration.completed_tasks` 中。**症状**:loop 看起来活着(heartbeat 在跳)但没派 agent
5. **`wrapper.py` 缺 `debug` import** (watch loop 里 `NameError`)。`debug()` 在 "无变化/跳过" 分支被调用,但未从 `spec_kit_loop.lib.log` 导入,第一次无变化就立刻崩。**修**:把 `debug` 加进 `from spec_kit_loop.lib.log import ...` 那行。**症状**:wrapper 每次重启 ~30s 后就 `NameError: name 'debug' is not defined`,永远跑不完一轮

如果你的 release 命中以上症状,把对应 patch 应用到本地 `wrapper.py` / `docwatcher.py`,然后重启 `wrapper.py --watch` 即可。

---

## `--watch` 模式限制 (v2 已知边界)

- **`smart-restart` 仅在 `phase=converged` 时触发**:`phase=implement` 时往 `INPUT.md` 加章节只会记为 `pending`,等当前 task 列表跑完才处理。这是故意的 — 跑到一半重启会丢工作
- **`completed_tasks` 是 per-cycle 的**:smart-restart 重置到 `specify` 时,`completed_tasks` 会从前一次 `current_iteration` 保留(修复后)。但每个 cycle 的 task 是独立追踪的 — cycle N 完成的 task 不会自动带进 cycle N+1,除非 `task-decomposer` 重新 promote
- **收敛需要 unchecked 计数归零**:bug 1 修复后,loop 只在 "qa pass 信号 + `specs/<branch>/tasks.md` 无 `[ ]`" 同时满足才进入 `converged`。如果你的 `tasks.md` 不是 `- [ ]` / `- [x]` 标准格式,计数永远到不了 0

---

## 反馈 / 问题

1. 看 `loop.log`(在运行 wrapper 的项目根目录)
2. 看 `.wbs/agent-outputs/*.txt`(每次 sub-agent 调用的完整输出)
3. 跑 `wrapper status` 看当前 phase / idle 计数 / doc hash 状态

---

## 协议

[MIT](LICENSE) — 自由使用、修改、商用,只需保留版权声明。