# flow-kit

**Repository Path**: tiankadefeng/flow-kit

## Basic Information

- **Project Name**: flow-kit
- **Description**: 融合了superpowers、OpenSpec、spec-kit、GSD、gstack...的可控Ai开发规范流程
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: rebuild-skill
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-08-11
- **Last Updated**: 2026-10-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# flow-kit

Artifact-first 的 AI 编程流程框架（可作为 Claude Code / DSH / Cursor 等环境的 skill 使用）。

**核心思想**：每个阶段产出一个 `.md` 工件，工件是后续阶段的唯一上下文来源。**多迭代并行**：多个迭代（change）可同时推进，每个迭代有独立状态，迭代间可声明依赖（R11）。

```
CHANGE → REQUIREMENT → DESIGN → [2a UI-DESIGN] → TASK → DEV → TEST → REVIEW → INTEGRATION → ARCHIVE
```

## 安装

把本仓库内容放到对应环境的 skill 目录（目录名保持 `flow-kit`）：

| 环境 | 路径 |
|---|---|
| Claude Code（全局） | `~/.claude/skills/flow-kit/` |
| Claude Code（项目） | `.claude/skills/flow-kit/` |
| Cursor | `.cursor/skills/flow-kit/` |
| Windsurf | `.windsurf/skills/flow-kit/` |
| DSH 等其它平台 | 按其 skill 目录约定放置 |

## 使用

一句话意图即可激活，自动路由到对应阶段：

- 「新需求：加个深色模式」→ 0-change（新建迭代，可声明依赖）
- 「继续上次」→ 选定迭代，按其 `STATE.md` 恢复
- 「执行任务」→ 列活跃迭代 → 选一个 → 取下一个可执行任务
- 「审查代码」→ 6-review
- 「跑 T03」→ 4-dev 执行指定任务
- 「健康检查」→ C-health-check
- 「登录报错了，帮我排查」→ D-bugfix
- 「把订单超时退款自驱跑到底」→ L-goal（循环工程，可选 · R13：给目标自动推进到归档，L2 人工决策 / L1 AI 自决）
- 更多场景见 `references/examples.md`

根因显而易见的小修（< 50 行）建议不走 flow-kit，直接改；需要排查的 bug（根因不明/间歇性/多假设）走 D-bugfix。

## 结构

```
SKILL.md                      # 入口：场景识别 + 路由表 + 阶段速查（瘦路由，≤ 260 行）
references/
  rules.md                    # 系统级硬规则 R1~R13 全文（单一事实来源，按编号查）
  prompts/                    # 各阶段 / 横向命令的详细步骤（0-7 + I/R/S/C/D 命令）
  protocols/                  # 按需加载的执行协议（schema-migration / destructive-change，4-dev 1.7/1.8 触发时读）
  templates/                  # 工件模板（CHANGE/REQUIREMENT/DESIGN/TASK/SUMMARY/CHANGE-SUMMARY/BUG/ITER-STATE...）
  reference/                  # 查表型知识（tech-stacks / ui-aesthetics / test-pyramid...）
  reference-query.md          # 各阶段加载清单（全读/查表/按需 + 瘦加载基线）+ grep 实操
  token-budget.md             # 整链路 token 成本参考（含执行模式对照）
  examples.md                 # 使用场景示例（含多迭代并行 / 子代理派发）
  glossary.md                 # 术语速查（按需加载）
  runtime-adapters/           # 可选运行时适配（Forge 门禁 / Subagent 派发）
scripts/
  check.sh                    # 自检：引用完整性 / 行数门禁 / frontmatter schema / 陈旧路径
  task-lint.sh                # 双模式：单 3-TASK.md 状态机校验；--iters 迭代级校验（依赖存在/无环/blocked/一致性）
```

多迭代状态模型（3.0）：根 `STATE.md` 只存项目级偏好；每个迭代自己的状态在 `.specs/<change-id>/STATE.md`（状态机 draft/active/blocked/archived/abandoned + `depends_on` 依赖声明）。依赖解锁以 `.specs/archive/` 目录存在性为真值，blocked 迭代仅可建 CHANGE，其余阶段阻塞。

## 设计约定

- **Token 分级**：REFERENCE 类文件禁止默认整读（首轮 ≤ 150 行），按节 grep；SPEC/TEMPLATE/PROMPT 可整读。
- **单一事实来源**：规则只在 `references/rules.md` 定义，SKILL.md 只留索引；改规则只改一处。
- **可选子代理派发（fail-open）**：支持 Agent tool 的宿主可启用 4-dev 子代理派发（R12），主会话只收一行 TASK-RESULT，不再累积任务原始输出；其余宿主行为不变，回退 inline / 手动开窗。
- **可选 Loop 循环（fail-open · 默认眠醒）**：给目标让 AI 自驱跑完整迭代直到归档（R13 / L-goal），一般决策 AI 自决（L1）、"非常重要"的决策才停问人（L2）；未触发时行为与未启用一致，可与 R12 叠加。
- **自检门禁**：改动后跑 `./scripts/check.sh` 验证。

## License

MIT