# 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-13

## 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. 检测收敛 → 自动停

---

## 设计原则

| 设计原则 | 实现 |
|---|---|
| **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/` 是否存在,有就跳过 spec-kit init
- 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 设计。

---

## 反馈 / 问题

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

---

## 协议

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