spec驱动开发vibe coding skill

在克隆的 Git 仓库中驱动完整的规格驱动开发生命周期（init→requirements→architecture→process_design→project_plan→coding→test→bugfix→code_review→release）。阶段门控、产物强制输出、多语言支持，内置 commit message 检查、代码门控与 LOGAF Checklist 评审，支持任意阶段 checkpoint 保存与 rollback 恢复，并实时发出结构化进度检查点。

# spec-driven-dev

适用于 Claude Code / OpenCode Runner 的阶段门控规格驱动开发工作流 Skill。
在 `init` 阶段克隆远程 Git 仓库，随后在该仓库内驱动每个生命周期阶段——强制产出产物、在迭代边界提交、并在 `release` 阶段推送至远端。内置 `code_review` 阶段，执行 commit message 合规校验、代码质量门控与 LOGAF Checklist 评审，所有 HIGH 级问题清零后方可进入 `release`。支持通过 `spec-driven-checkpoint` Skill 在任意阶段保存 checkpoint，并使用 `rollback {ckpt_id}` 恢复 Git 状态和 Agent 上下文。支持多语言项目，遵循 OpenSkills 渐进加载原则。

---

## 前置依赖

### 二进制工具

| 工具 | 用途 |
|------|------|
| `git` | 克隆、分支、提交、打标签、推送 |

### 环境变量

| 变量 | 是否必须 | 说明 |
|------|----------|------|
| `SPEC_DEV_GIT_TOKEN` | **必须** | HTTPS 认证用的个人访问令牌（PAT）或 OAuth2 Token。用于构造带认证的克隆 URL 并写入本地凭据助手。兼容 GitHub、GitLab、Bitbucket、Gitea 的 HTTPS 远端。 |
| `SPEC_DEV_GIT_USERNAME` | 否 | 写入 `user.name` 和凭据 URL 的 Git 用户名。未设置时默认为 `oauth2`（兼容 GitHub/GitLab Token 认证）。 |
| `SPEC_DEV_GIT_EMAIL` | 否 | 提交时使用的作者邮箱。未设置时默认为 `bot@spec-driven-dev`。 |

> **安全说明** — `SPEC_DEV_GIT_TOKEN` 仅通过 OpenClaw `skills.entries.*.env` 机制在运行时注入，**绝不写入任何产物文件、日志或迭代摘要**。凭据助手使用局限于当前 Agent 会话的本地 `~/.git-credentials` 存储。

---

## 快速开始

```
# 1 – 克隆远程仓库并初始化 US 目录
init-US042
git_remote: https://github.com/my-org/my-repo.git
us_content: |
  ## US042 – OAuth2 登录
  作为用户，我希望使用 Google 账号登录。
  ### 验收标准
  - [ ] Google OAuth2 重定向正常
  - [ ] 回调后签发 JWT
context: "Python 3.11 + FastAPI。数据库为 PostgreSQL 15，不新增依赖。"

# 2 – 链式执行各阶段（git_remote 在 init 后自动持久化到 current_iter.md）
requirements-US042
architecture-US042
process_design-US042
project_plan-US042
coding-US042
test-US042
bugfix-US042        # 仅当 test 阶段报告 HIGH 级失败时执行
code_review-US042   # 三层门控：commit message + 代码质量 + LOGAF Checklist
release-US042       # 仅当 code_review 裁决为 APPROVED 或 APPROVED_WITH_NOTES 时解锁
```

---

## 输入变量

| 变量 | 类型 | 是否必须 | 说明 |
|------|------|----------|------|
| `us_id` | string | **必须** | 用户故事 ID（如 `US042`）。从 `<stage>-<us_id>` 触发模式中自动捕获，映射至所有产物路径。 |
| `stage` | enum | **必须** | 生命周期阶段：`init` · `requirements` · `architecture` · `process_design` · `project_plan` · `coding` · `test` · `bugfix` · `code_review` · `release` |
| `git_remote` | string | `init` 阶段必须 | 远程 Git 仓库的 HTTPS URL。`init` 后存入 `current_iter.md`，后续阶段自动读取，无需重复传入。 |
| `us_content` | string | 否 | 用户故事完整文本。在阶段运行前写入 `requirements/US/{us_id}.md`。已存在时追加合并，除非 `force_overwrite: true`。 |
| `context` | string | 否 | 自由格式的补充上下文，逐字注入到本次产出的每个产物的 `### 补充上下文` 标题下。适用于 ADR 摘录、环境约束、Review 反馈等。 |
| `iter_id` | string | 否 | 当前迭代 ID（如 `iter_003`）。省略时自动从 `current_iter.md` 中检测；首次运行默认为 `iter_001`。 |
| `force_overwrite` | bool | 否 · 默认 `false` | 为 `true` 时覆盖已有产物文件，而非追加合并。 |
| `skip_skill_scan` | bool | 否 · 默认 `false` | 为 `true` 时跳过 `available_skills.xml` 扫描（适用于 Runner 已在外部完成 Skill 解析的场景）。 |

---

## 触发条件

本 Skill 在以下情况激活：

1. **阶段命令模式** — 用户输入 `<stage>-<us_id>`，例如：
   - `init-US042`
   - `coding-US042`
   - `code_review-US042`
   - `release-FEAT_LOGIN`

2. **Checkpoint 命令** — 任意时刻均可触发：
   - `save_checkpoint-{us_id}` 或 `checkpoint-{us_id}` — 手动保存当前状态
   - `rollback {ckpt_id}` — 回滚到指定 checkpoint
   - `rollback {ckpt_id} --git-only` — 仅回滚 Git
   - `rollback {ckpt_id} --context-only` — 仅输出恢复 Prompt
   - `list_checkpoints-{us_id}` — 列出所有 checkpoint

3. **下一迭代意图** — 用户输入以下任意一种：
   - `{us_id}进行下一个迭代`
   - `next iteration {us_id}`
   - `start|begin|run|execute … sprint|iteration|milestone`

   → 自动从 `requirements/{us_id}/docs/iteration_summary/current_iter.md` 恢复上下文继续执行

---

## 路径常量

所有路径使用 `{us_id}`、`{iter_id}`、`{version}` 作为占位符。

```
requirements/US/{us_id}.md
requirements/{us_id}/docs/requirements.md
requirements/{us_id}/docs/architecture.md
requirements/{us_id}/docs/process_design.md
requirements/{us_id}/docs/project_plan.md
requirements/{us_id}/docs/tasks.json
requirements/{us_id}/docs/iteration_summary/current_iter.md
requirements/{us_id}/docs/iteration_summary/{iter_id}.md
requirements/{us_id}/docs/release_notes/{version}.md
requirements/{us_id}/docs/reports/test-{us_id}-report.md
requirements/{us_id}/docs/reports/review-{us_id}-{iter_id}.md
requirements/{us_id}/docs/checkpoints/index.md
requirements/{us_id}/docs/checkpoints/{ckpt_id}.md
auxiliary/coding_standards.md
auxiliary/gitflow_guide.md
auxiliary/skills/available_skills.xml
src/
tests/
config/
CHANGELOG.md
PROJECT_STATUS.md
.github/workflows/ci.yml
```

---

## 执行协议

每次调用**必须**按顺序执行以下六步协议。

### 第 0 步 — 发出 `stage_start` 检查点

```
[SKILL:spec-driven-dev] CHECKPOINT stage_start STATUS=OK  us_id={us_id}  stage={stage}
```

### 第 1 步 — 验证输入

1. 确认 `us_id` 和 `stage` 已存在。
2. 若提供了 `us_content`，写入（或合并）到 `requirements/US/{us_id}.md`。
3. 若提供了 `context`，在内存中保存，并在本次产出的每个产物中以 `### 补充上下文` 标题开头注入。
4. 解析 `iter_id`：
   - 若显式提供，直接使用。
   - 否则从 `current_iter.md` 中读取。
   - 若文件不存在，默认为 `iter_001`。
5. 解析 `git_remote`：
   - 若显式提供，使用并持久化到迭代摘要。
   - 否则从 `current_iter.md` 的 `git_remote:` 字段中读取。
   - 若仍不存在且当前阶段不是 `init`，发出警告后继续执行。

```
[SKILL:spec-driven-dev] CHECKPOINT inputs_validated STATUS=OK
```

### 第 2 步 — Skill 扫描（`skip_skill_scan: true` 时跳过）

1. 完整读取 `auxiliary/skills/available_skills.xml`。
2. 将可用 Skill 与当前阶段需求进行匹配。
3. 若找到匹配项，宣布：
   > "我将调用 Skill：`<n>` 来辅助本次任务。"
   随即完整加载 `auxiliary/skills/<n>/SKILL.md` 后再继续执行。
4. **禁止一次性加载所有 Skill** — 每次只按需加载一个（渐进披露原则）。

```
[SKILL:spec-driven-dev] CHECKPOINT skill_scan_done STATUS=OK  skills_loaded=[…]
```

### 第 3 步 — 执行阶段

严格按照下方**阶段定义**章节执行。
每写完一个强制输出文件后发出：

```
[SKILL:spec-driven-dev] CHECKPOINT artefacts_written STATUS=OK  files=[…]
```

### 第 4 步 — 质量门控（仅 coding / test / bugfix 阶段）

按语言检测表运行静态检查和测试。

通过时：
```
[SKILL:spec-driven-dev] CHECKPOINT quality_gate_passed STATUS=OK
```
失败时：发出 `STATUS=FAIL`，汇总失败信息，并指示 Agent 进入 `bugfix` 阶段。
同一问题连续失败 5 次后，停止自动修复并请求人工介入。

### 第 5 步 — 写入迭代摘要

1. 递增 `iter_id`（如 `iter_003` → `iter_004`）。
2. 使用下方模板写入 `requirements/{us_id}/docs/iteration_summary/{iter_id}.md`。
3. 用相同内容覆盖 `requirements/{us_id}/docs/iteration_summary/current_iter.md`。
4. 更新 `PROJECT_STATUS.md`。

```
[SKILL:spec-driven-dev] CHECKPOINT iteration_summary_written STATUS=OK  iter_id={iter_id}
```

### 第 6 步 — 发出 `stage_done`

```
[SKILL:spec-driven-dev] CHECKPOINT stage_done STATUS=OK
<stage_done>
```

---

## 阶段定义

### `init`

**目的：** 从环境变量配置 Git 凭据、将远程仓库克隆到工作区、初始化 US 目录树，并将纯文本 `git_remote` URL 记录到迭代摘要，供后续所有阶段免密推拉使用。

**读取：** 无（从零启动）

**写入：**
- 克隆后的仓库（工作区根目录）
- `requirements/US/{us_id}.md`（脚手架或来自 `us_content`）
- 完整的 `requirements/{us_id}/docs/` 目录树
- `requirements/{us_id}/docs/iteration_summary/current_iter.md`（存根）
- `PROJECT_STATUS.md`（初始条目）

**凭据配置 — 按此顺序执行：**

```bash
# 1. 从环境变量解析运行时值
GIT_USER="${SPEC_DEV_GIT_USERNAME:-oauth2}"
GIT_EMAIL="${SPEC_DEV_GIT_EMAIL:-bot@spec-driven-dev}"
GIT_TOKEN="${SPEC_DEV_GIT_TOKEN}"        # 必填；metadata.requires.env 已做门控

# 2. 构造带认证的克隆 URL（Token 内嵌，绝不写入产物）
#    兼容：https://github.com/…  https://gitlab.com/…  https://bitbucket.org/…
REMOTE_HOST=$(echo "${git_remote}" | sed 's|https://||' | cut -d'/' -f1)
CLONE_URL="https://${GIT_USER}:${GIT_TOKEN}@${REMOTE_HOST}/$(echo "${git_remote}" | sed "s|https://${REMOTE_HOST}/||")"

# 3. 克隆
git clone "${CLONE_URL}" .

# 4. 设置提交身份
git config user.name  "${GIT_USER}"
git config user.email "${GIT_EMAIL}"

# 5. 持久化凭据，供本工作区后续 push/pull 静默认证
git config credential.helper store
printf "https://%s:%s@%s\n" "${GIT_USER}" "${GIT_TOKEN}" "${REMOTE_HOST}" \
  >> ~/.git-credentials
chmod 600 ~/.git-credentials
```

> **Token 绝不写入任何产物或日志。** 仅将不含凭据的裸 `git_remote` URL 存入 `current_iter.md`。

**关键指令：**
1. 在任何其他 git 操作前先执行凭据配置代码块。
2. 创建路径常量中尚不存在的所有子目录。
3. 若提供了 `us_content`，写入 `requirements/US/{us_id}.md`；否则写入含占位标题的 Markdown 脚手架。
4. 若提供了 `context`，在脚手架中注入 `### 补充上下文` 节。
5. 在 `current_iter.md` 的 `git_remote:` 字段中记录**纯文本** `git_remote` URL（不含 Token）。

---

### `requirements`

**读取：**
- `requirements/US/{us_id}.md`
- `auxiliary/coding_standards.md`

**写入：**
- `requirements/{us_id}/docs/requirements.md`

**关键指令：**
1. 识别功能范围与边界。
2. 挖掘非功能性需求（性能、安全、兼容性）。
3. 定义可量化的验收标准。
4. 注入 `context` 至 `### 补充上下文`。

---

### `architecture`

**读取：**
- `requirements/{us_id}/docs/requirements.md`
- `auxiliary/coding_standards.md`
- `auxiliary/gitflow_guide.md`

**写入：**
- `requirements/{us_id}/docs/architecture.md` — **必须包含 Mermaid 架构图**

**关键指令：**
1. 选择架构风格（微服务 / 模块化 / 单体）并说明理由。
2. 定义组件、职责与接口。