# kimi-stack-orchestrator

**Repository Path**: longyuanJason/kimi-stack-orchestrator

## Basic Information

- **Project Name**: kimi-stack-orchestrator
- **Description**: kimi cli命令提升，驾驭工程编排能力
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-04-28
- **Last Updated**: 2026-05-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# GSD Stack Orchestrator

<p align="right">
  <a href="./README.en.md">🇺🇸 English Version</a>
</p>

> GSD 为体，xdev 为用。面向 Code CLI 的 AI 驱动端到端开发工作流编排层。

---

## 简介

**GSD Stack Orchestrator** 是一套为 [Code CLI](https://ai.moonshot.cn) 设计的复合 skill 层，将 **xdev** 的自适应编排能力与 **GSD（Goal-Driven Development）** 的文档硬约束深度融合，实现 AI 主动驱动、文档约束校正、全流程自循环的智能化软件开发。

核心解决以下痛点：

- **skill 调用碎片化**：用户不再需要手动判断何时调用 `brainstorming`、`writing-plans`、`review`、`qa` 等 skill
- **流程一刀切**：改两行配置和开发新功能走不同的自适应路径
- **并行缺乏契约保障**：多 subagent 并行前自动冻结接口契约，防止冲突
- **文档约束弱执行**：AI 长会话中持续校验是否偏离 `docs/` 设计文档
- **缺少失败回路**：每个阶段有重试上限和明确的升级/降级路径
- **AI 跳步与自由发挥**：通过硬中断和意图识别协议，确保 AI 不擅自推进流程

---

## 架构

```
┌─────────────────────────────────────────────────────────────────┐
│                        用户入口层                                │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐ │
│  │  init   │  │full-dev │  │ design  │  │  impl   │  │ bugfix  │ │
│  │  初始化  │  │ 端到端  │  │ 设计阶段 │  │ 实现阶段 │  │ Bug修复 │ │
│  └─────────┘  └─────────┘  └─────────┘  └─────────┘  └─────────┘ │
│  ┌─────────────────────────────────────────────────────────┐  │
│  │ iterate — 小改动快速路径（范围门控）                      │  │
│  └─────────────────────────────────────────────────────────┘  │
├─────────────────────────────────────────────────────────────────┤
│                        核心协议层                              │
│  • Gatekeeper    — 文档检查、Hard Gate 执行、偏离检测          │
│  • Intent Guard  — 用户意图识别与技能路由协议                   │
│  • Tracker       — 进度标记硬约束（5 文档同步更新）              │
│  • Router        — 任务分级（S1/S2/S3）、流程分流                │
│  • Recovery      — 失败回路标准处理                            │
├─────────────────────────────────────────────────────────────────┤
│                        内部子模块                                │
│  • Planner       — 依赖图 + 接口契约冻结                       │
│  • Executor      — 按依赖图批次调度 subagent                   │
│  • Validator     — health / qa / 回归检测                      │
│  • Shipper       — 版本管理、PR 创建、经验沉淀                   │
├─────────────────────────────────────────────────────────────────┤
│                      gstack (决策层)                             │
│  office-hours    plan-eng-review    plan-design-review         │
│  health          qa                 ship                       │
│  investigate     review             freeze                     │
├─────────────────────────────────────────────────────────────────┤
│                    Superpowers (执行层)                        │
│  brainstorming          writing-plans                          │
│  test-driven-development   subagent-driven-development       │
│  systematic-debugging       dispatching-parallel-agents        │
└─────────────────────────────────────────────────────────────────┘
```

---

## 快速开始

### 一键安装

```bash
curl -fsSL https://gitee.com/junluoyu/stack-orchestrator/raw/master/install-stack.sh -o install-stack.sh
chmod +x install-stack.sh
./install-stack.sh
```

安装脚本会：
1. 在当前项目初始化 GSD 文档基础设施（`PROJECT.md`、`AGENTS.md`、`M001-ROADMAP.md` 等）
2. 从本仓库克隆完整 skill 集合到 `~/.ai/stack-orchestrator`
3. 创建软链接到 `~/.ai/skills/`，使 AI CLI 能够识别已安装的技能指令

---

## 复合技能一览

Claude Code 调用格式为 `/<skill-name>`；本项目的复合技能名称包含 `stack:` 前缀，因此应使用 `/stack:full-dev`、`/stack:init` 这类命令。

| 命令 | 描述 | 适用场景 |
|------|------|----------|
| `/stack:init` | 新项目初始化后主动需求澄清 | 从 0 开始的新项目，建立项目骨架和背景文档 |
| `/stack:full-dev <需求>` | 端到端完整开发（8 阶段流水线）| 全新功能开发，从需求到发布完整交付 |
| `/stack:design <需求>` | 仅做设计和规划（产出设计文档 + TDD 计划）| 设计先行，后续可交接给 `impl` 或人工实现 |
| `/stack:module-split <需求>` | 仅做模块拆分与索引同步 | 先拆模块、明确边界和依赖，不进入 API/DB/前端/任务拆解 |
| `/stack:impl` | 基于已有设计文档做实现 | `design` 阶段已完成，执行 TDD 编码 |
| `/stack:bugfix <描述>` | Bug 修复（S1/S2/S3 三级自适应路径）| 线上问题修复，按复杂度自动选择路径 |
| `/stack:iterate <描述>` | 小改动快速路径（范围门控）| 配置调整、文案修改、小优化 |

---

## 核心协议机制

### 1. Intent Guard Protocol — 意图识别协议

防止 AI 在理解不清用户意图时擅自推进流程。

**六类意图强制映射**：

| 类别 | 用户表达 | AI 行为 |
|------|----------|---------|
| **A. 流程推进** | 「继续」「下一步」「好」「OK」「行」 | 正常进入下一阶段 |
| **B. 内容修正** | 「修改」「调整」「改一下」「不对」 | 停留在当前步骤修改后重新确认 |
| **C. 精细化设计** | 「拆分」「细化」「设计一下表结构」 | 调用对应 skill，产出后回到当前步骤确认 |
| **D. 跨阶段跳转** | 「先实现这个」「进入 impl」「直接写代码」 | 执行 Gatekeeper 检查，完整则提示下一阶段，不完整则拦截 |
| **E. 暂停/退出** | 「暂停」「先这样」「算了」 | 暂停流程，更新状态，告知续接方式 |
| **X. 模糊** | 以上都不匹配 | 强制进入意图澄清回环，禁止调用工具 |

**硬中断规则**：每完成一个子步骤，AI 必须 **STOP**，等待用户明确回复后才继续。

### 2. Tracker Protocol — 进度标记硬约束

确保项目状态实时同步到 5 个核心文档：

| 文档 | 更新内容 |
|------|----------|
| `M001-ROADMAP.md` | 「当前阶段」「已完成」「进行中」「阻塞项」 |
| `docs/00-index.md` | 登记产出文档，状态从 6 项中选：📝需求澄清中/🎨设计中/✅设计已完成/🔨开发中/🧪测试中/🏁已完成 |
| `PROJECT.md` | design 阶段勾选已产出文档类型 `[x]` |
| `docs/07-tasks/Task Card` | 状态为「进行中」或「已完成」，追加进度记录 |
| `DECISIONS.md` | 架构决策或代码偏离设计文档时追加 ADR |

**仪式输出**（每个阶段结束必须展示）：
```markdown
📝 阶段 Tracker 执行中...
- [x] `M001-ROADMAP.md` 已更新（当前阶段：XXX）
- [x] `docs/00-index.md` 已登记
- [x] `PROJECT.md` 清单已勾选
- [ ] Task Card 状态更新
未勾选项必须说明原因和预计完成时间。
```

### 3. Gatekeeper Protocol — 门禁与偏差检测

**启动检查**（每个 skill 开始前）：
- `docs/00-index.md` 存在
- 功能点已登记
- `PROJECT.md` 设计文档清单状态
- 涉及数据库时，确认已调用对应数据库设计规范 skill
- `docs/07-tasks/` 中 Task Card 存在性

**偏差检测**（每个阶段结束后）：
- 扫描 `git diff --name-only`
- 对比 `docs/06-api/` 接口契约、`docs/05-database/schemas/` 表结构、`docs/04-frontend/features/` 前端设计
- 发现不符 → 输出偏差清单 → 暂停 → 提供路径 A（修正代码）或路径 B（更新文档并记录到 `DECISIONS.md`）

### 4. Recovery Protocol — 失败回路

| 阶段 | 上限 | 超限处理 |
|------|------|----------|
| 设计（需求澄清） | 3 轮无进展 | 🔴 暂停，请用户重新描述需求 |
| 审查 | 2 次重审 | 降级为仅 plan-eng-review |
| TDD（单任务） | 3 次 FAIL | 标记 `[TODO]`，询问继续或暂停 |
| health | 2 次 | 记录 tech debt 到 `DECISIONS.md` |
| QA | 2 次 | 降级手工验证 |
| ship | 2 次 | 🔴 暂停，请用户决策 |

---

## 工作流程详解

### `/stack:init` — 初始化并主动澄清

**阶段 0：自动初始化检测**
- 检查 `AGENTS.md`、`PROJECT.md`、`docs/00-index.md` 是否存在
- **若缺失** → AI **必须**直接执行初始化（执行 `init-project.sh` 或自行创建骨架）
- 自动执行 `git init` 和首次提交

**阶段 1：主动需求澄清（步进式确认）**
1. **技术栈偏好确认**（必做）：推荐 2-3 个主流方案，用户选择或自定义
2. **多端开发必问**：Web PC / H5 / 小程序 / App / 桌面端
3. **PC 端类型确认**：门户网站 vs 管理后台（后者会触发 `layout` 模块强制插入）
4. AI 主动提出 3-5 个关键问题
5. 步进式产出：背景文档 → 索引更新 → 确认 → 下一步

**阶段 2：编码规范引导**
- 强制读取 `KNOWLEDGE.md`
- 若不存在，主动询问是否生成标准规范

---

### `/stack:full-dev` — 端到端完整开发（8 阶段）

| 阶段 | 名称 | 关键动作 | 门禁/确认 |
|------|------|----------|-----------|
| 1 | 需求构思与设计 | 步进式产出 7 类文档 | 🔴 每步必须用户确认 |
| 1.5 | 架构设计与环境确认 | 前端/后端/数据库环境选项式确认 | 🔴 不可跳过 |
| 2 | 计划审查 | `plan-eng-review` + `plan-design-review`（并行）| 🔴 无 HIGH 未解决项 |
| 3 | TDD 实现计划 | Red-Green 配对拆分，写入 Task Card | 🟢 自动 |
| 4 | TDD 实现循环 | 逐模块、逐原子任务串行实现 | 🔴 逐条死循环确认 |
| 4.5 | 联调集成（条件触发）| Mock 替换 → 集成测试 | 🔴 全量通过 |
| 5+6 | 质量检查 & QA | `health` + `qa` 并行 | 🔴 health >= 7/10 |
| 7 | 发布 | `ship` skill | 🔴 2 次失败暂停 |
| 8 | 经验沉淀 | 条件触发 `learn` | 🟡 通知 |

**模块驱动步进设计（阶段 1.3）**：
- 禁止一次性生成所有模块设计
- 按依赖优先级（P1 → PN）逐个模块深度设计
- 每模块包含 7 个子步骤（A→B→C→D→E→F→G），每步硬中断等待确认

**子步骤硬中断规则**：
- A：模块职责 → STOP → 确认 → B
- B：接口契约 → STOP → 确认 → C
- C：前端设计 → STOP → 确认 → D
- D：数据库设计 → STOP → 确认 → E
- E：实现归属确认 → STOP → 确认 → F
- F：Task Card 拆分 → STOP → 确认 → G
- G：联动复查 → STOP → 确认 → 落盘

**联动复查（Cross-Reference Review）**：
- G1：页面功能 vs 模块职责
- G2：页面数据 vs 接口契约
- G3：页面数据 vs 数据库结构
- G4：新增路由 vs 全局导航（管理端项目强制）

---

### `/stack:design` — 仅设计阶段

`full-dev` 的前半段（阶段 1-3），产出设计文档和 TDD 实现计划后停止。

**强制门禁（Rule 1）**：
设计阶段结束前必须完成：
- [ ] `docs/01-background/` 已登记
- [ ] `docs/02-modules/` 模块设计完成（含联动复查报告）
- [ ] `docs/03-architecture/` 架构设计完成
- [ ] `docs/04-frontend/` 前端设计（如触发）
- [ ] `docs/05-database/` 数据库设计（如触发）
- [ ] `docs/06-api/` 接口契约完成
- [ ] `docs/07-tasks/` Task Card 完成
- [ ] **管理端布局检查**（🔴 若标记含 PC 管理端，`layout.md` 必须产出并确认）

**不完整禁止进入实现阶段**。

---

### `/stack:impl` — 仅实现阶段

`full-dev` 的后半段（阶段 4-8），读取 `design` 阶段产出的计划并执行 TDD 实现。

**设施依赖硬中断确认（4.1.5）**：
- 实现模块前 **必须** 检查设计文档中的设施信息（数据库连接、缓存、第三方接口、外部服务配置）
- 若缺失 → **STOP**，向用户发起问询
- **严禁 AI 自行决定使用 Mock**，必须用户明确回复「使用 Mock 数据」后方可生成

**原子任务实现（4.4）— 逐条死循环**：

```
Step 1: Red — 写失败测试
        git commit -m "test(atom-NNN): <desc> [Red]"
        Task Card: 🔴 Red 已完成
        
Step 2: Green — 写最小实现
        git commit -m "feat(atom-NNN): <desc> [Green]"
        Task Card: 🟢 Green 已完成
        
Step 3: 实现确认死循环
        等待用户明确回复：「实现确认OK」或「修改 xxx」
        通过后：git commit -m "feat(atom-NNN): <desc> [Confirmed]"
        Task Card: ✅ 已完成
```

**状态同步强制规则**：原子任务状态实时同步到 Task Card，严禁遗漏。

---

### `/stack:bugfix` — Bug 修复流程（S1/S2/S3）

| 级别 | 特征 | 路径 | 目标时长 |
|------|------|------|---------|
| **S1 快速** | 单行/配置/文案，仅 1 个文件 | 直接修复 → 测试 → git push | ≤ 15 min |
| **S2 标准** | 单模块逻辑错误，1-3 个文件 | 内联调查 → TDD → 全量测试 → ship | ≤ 35 min |
| **S3 深度** | 跨模块、间歇性、竞态，≥ 3 个文件 | git blame/bisect → investigate → TDD → health+qa → ship | ≤ 90 min |

**升级触发条件**：
- S1 修复后发现牵涉 > 1 个文件 → **升级 S2**
- S2 快速取证 5 min 后无法定位 → **升级 S3**
- S2 假设验证失败 → **升级 S3**

---

### `/stack:iterate` — 快速迭代流程

**范围门控（全部满足才使用 iterate）**：
- 代码行数 < 100 行改动
- 文件数量 ≤ 5 个
- 模块数量 ≤ 2 个
- 不引入新依赖
- 不改变公开 API

**命中任一升级到 full-dev**：
- 涉及金融计算/资金逻辑
- 涉及认证/权限/安全
- 涉及数据库 schema 变更
- 涉及第三方 API 集成
- 影响已发布 API 的行为
- 新增页面 / 视图 / 路由
- 新增组件且含 ≥ 2 个交互状态

---

## 管理端布局专项机制

若 `docs/01-background/README.md` 标记「含 PC 管理端」：

**强制插入 layout 模块**：
- 在模块拆分清单首行插入 `layout` / `shell` 模块
- 优先级 **P0**（高于所有业务模块）
- 职责：全局布局框架、导航菜单、路由外壳、面包屑、权限控制点

**布局文档 8 章节强制规范**：
1. 全局布局 ASCII 图
2. 导航菜单结构表
3. 路由结构表
4. 布局组件清单
5. 布局规格
6. 交互状态
7. 面包屑规则
8. 权限控制点

**业务页面禁令**：
- 禁止独立定义导航菜单、全局路由、面包屑
- 首行必须声明：「本页面基于全局布局框架渲染」
- 新增菜单/路由必须在 `layout.md` 中统一登记

---

## 底层技能底座

### gstack 决策层（30+ skills）

| skill | 用途 |
|-------|------|
| `office-hours` | YC 办公室时间，产品创意 brainstorm |
| `plan-ceo-review` | CEO 视角计划审查 |
| `plan-eng-review` | 工程经理视角架构审查 |
| `plan-design-review` | 设计师视角计划审查 |
| `plan-devex-review` | 开发者体验审查 |
| `review` | 合并前 PR 代码审查 |
| `qa` | 系统性 QA 测试并修复 |
| `health` | 代码质量健康度仪表盘 |
| `ship` | 发布工作流 |
| `browse` | 快速无头浏览器 |
| `investigate` | 系统性调试与根因调查 |
| `freeze` | 接口契约冻结 |

### Superpowers 执行层（14 skills）

| skill | 用途 |
|-------|------|
| `brainstorming` | 创意工作前的需求澄清 |
| `writing-plans` | 为复杂任务撰写实施计划 |
| `executing-plans` | 执行已撰写的实施计划 |
| `test-driven-development` | 测试驱动开发 |
| `subagent-driven-development` | 子代理驱动开发 |
| `systematic-debugging` | 系统性调试 |
| `dispatching-parallel-agents` | 并行派发多个独立子代理 |

---

## 仓库目录结构

```
.
├── install-stack.sh               # 一键安装脚本
├── README.md                      # 中文文档
├── README.en.md                   # 英文文档
├── LICENSE                        # MIT 许可证
└── skills/
    ├── gstack/                    # gstack 决策层技能（30+）
    ├── superpowers/               # Superpowers 执行层技能（14）
    ├── init-project/              # 项目初始化技能
    ├── mysql-db-design/           # MySQL 数据库设计规范
    ├── postgresql-db-design/      # PostgreSQL 数据库设计规范
    ├── oracle-db-design/          # Oracle 数据库设计规范
    ├── stack-orchestrator/        # Orchestrator 总入口 + 共享库
    ├── stack-init/                # 复合技能：初始化并主动澄清
    ├── stack-full-dev/            # 复合技能：端到端完整开发
    ├── stack-design/              # 复合技能：仅设计阶段
    ├── stack-impl/                # 复合技能：仅实现阶段
    ├── stack-bugfix/              # 复合技能：Bug 修复
    └── stack-iterate/             # 复合技能：快速迭代
```

---

## 核心设计原则

1. **文档是唯一真理源（Single Source of Truth）**
   所有代码变更必须与 `docs/` 中的设计文档一致。偏离时优先改代码，必要时改文档但必须记录到 `DECISIONS.md`。

2. **Orchestrator 优先**
   当用户提出开发需求时，AI 优先使用复合 skill（`full-dev`、`bugfix`、`iterate`），而非直接调用单一基础 skill。

3. **自适应而非一刀切**
   改两行配置和开发新功能不应该走同一套流程。Orchestrator 在执行前先评估复杂度，再决定投入多少资源。

4. **该并行时并行，该串行时串行**
   通过依赖图分析确定哪些任务可以并发，哪些必须顺序执行。并行前必须冻结接口契约。

5. **每个阶段有明确的失败回路**
   不是无限重试，而是有上限、有升级路径、有明确的用户决策点。

6. **硬中断与意图确认**
   AI 每完成一个子步骤必须 STOP，等待用户明确确认后才继续，禁止擅自推进。

7. **状态实时同步**
   通过 Tracker 协议，确保项目状态实时同步到 5 个核心文档，保证可追溯性。

---

## 如何更新

本仓库所有 skill 均为纯 Markdown 文件，更新时无需编译或重启：

```bash
cd ~/.ai/stack-orchestrator
git pull origin master
```

更新后 AI CLI 会自动读取最新的 skill 定义。

---

## 许可证

[MIT License](./LICENSE) — 自由开源，与 xdev 和 GSD Stack 生态保持一致。

---

<p align="center">
  Made with ❤️ for Code CLI
</p>