agent-mvp

Files (2)

• SKILL.md
• openai.yaml · agents/

SKILL.md (first lines)

# agent-mvp — 双 agent × cc-code 驱动 MVP 执行编排器

> **纯执行器**：需求与契约**只读不产**——一切规划产物（prd / ux / design / project / data / api）由 `/cc-code:plan-mvp`（有前端时再接 `/cc-code:plan-uiux`）商讨定稿。本命令读定稿文档直接开发，**运行中零提问**：撞上需求 / 契约缺口的部分挂起、3 轮仍不过的项记账，其余阶段照跑，结尾一次交人（唯一出处 = `../cc-code/references/dev-qa-loop.md` §九）。
> **校准铁律**：每一个阶段完成后，**必须**先执行 `/cc-code:cc-code` 校准当前状态（重读 `Agent.md`/`status.md`，重锁坐标），确认无误后再进入下一阶段。未校准禁止推进。校准是机器自检，**静默进行，不以「请确认」的姿态打扰人**。
> **串行铁律**：严守 Dev → QA 顺序，禁止跳序。**主控是编排者，不扮演任何角色**：派哪个 agent 就是哪个角色，角色权限唯一出处 = `active/Agent.md` §三；主控的写权限见 `active/Agent.md` §一，⛔ 不写 `gates.md` 与 L1~L3 文件。
> **视觉门（按阶段判定）**：判据先读 `status.md`「风格：」并以它为准（`design.md` §0 只在 status 缺失时兜底）。本阶段涉及页面且风格未锁 → ⛔ 拒跑，提示走 `/cc-code:plan-uiux`；`已定未实现` → ⛔ 拒跑，提示走 `/cc-code:agent-uiux`；`无前端` / 纯后端阶段放行并在视觉段标「不适用」；老项目冷启动只豁免一次（判据唯一出处 = 下方「前置检查」第 7 条）。⛔ 本命令不派 uiux（风格归 `plan-uiux`，风格落地归 `agent-uiux`）。视觉规则与判词唯一出处 = `../cc-code/references/ui-gates.md`；循环协议唯一出处 = `../cc-code/references/dev-qa-loop.md`。
> **并行泳道（1.6.0）**：阶段之间串行；阶段内 `project.md` §九 写了泳道 → 按 `../cc-code/references/parallel-lanes.md`（本 skill 目录的同级，插件内单一出处） 同一角色多人并发，没写 → 单线程照旧。泳道内的运行时视觉检查只在汇合回归跑。

## 与规划命令的分工（两两配对，单一职责）

```
 plan-mvp（人参与）                       plan-uiux（有前端时）              agent-mvp（本命令，纯机器）
 商讨 → 逐点循环至通顺                        定方向 → 样板板 →「定了」              读定稿文档
 落盘 prd/ux/design/project/data/api  ──►    锁 design.md               ──►   Dev 编码 → QA 四层验收（≤3 轮回环）
                                                                                阶段全 PASS → agent-whole-qa 收口
```

## 前置检查（启动时一次性）
1. 确认项目根存在 `.cc-code/`（否则提示先 `/cc-code:init`）。
2. **定稿体检**：`active/prd.md` 有 §1.5 验收断言主表，且 `ux.md` / `project.md` / `data.md` / `api.md` 齐备（有前端时另需 `design.md`，无前端须为「不适用（无前端）」）。缺任一 → ⛔ 拒跑，报「规划产物未定稿，请先走 `/cc-code:plan-mvp`」，**绝不现场补需求**。
3. 确认双 agent 可用：`dev` / `qa`（视觉层由 qa 执行；⛔ 本命令不派 uiux——风格未定回 `plan-uiux`，风格落地走 `agent-uiux`）。
4. 确认测试基建：读 `project.md` §六「测试基建契约」取测试根 / glob / 运行命令——**测试 / 构建 / 自检命令的唯一来源**，⛔ 本命令不自带命令。契约不存在或未填实 → ⛔ 拒跑，按 `dev-qa-loop.md` §九 出交人报告（下一步 `/cc-code:plan-feature`，补契约归 `architect`）；契约已填实但测试基建尚未落地 → 把「按契约搭测试基建」作为 Dev 阶段首个任务。
   同理读 `project.md` §七「日志契约」：选库 / 配置值未填实 → ⛔ 拒跑，同上出交人报告；契约已填实但门面与 requestId 入口未落地 → 把「按契约搭日志基建」并入 Dev 首个任务。
   **视觉契约五项**（缺任一 → ⛔ 拒跑，同上出交人报告，补契约归 `architect`；⛔ 不自带命令、不猜）：
   ① `ux.md` §1.1 前端形态表（按端一行）② `project.md` §一.1 前端组件库家族 / 各端组件库 / 主题入口 / 图标库 ③ `design.md` §0 状态行 ④ `project.md` §六 界面驱动工具 · 视觉测试位置 · 视觉门命令 · 基线目录 ⑤ `project.md` §六 视口集合 · 亮暗模式 · 性能门限 · 冒烟页。
   无前端项目：`design.md` §0 = 不适用（无前端）→ 视觉段整段标「不适用」，其余照跑。
5. **索引体检（静默）**：`codegraph status --json` 读三字段 —— `initialized:false` → 报一行（⛔ 不自动重建）；`pendingChanges` 非 0 → 静默 `codegraph sync`；`reindexRecommended:true` → 报一行建议。CLI 未装则静默跳过，全流程照跑（精准回归降级为全量）。⛔ 健康时一个字都不提。
6. 执行 `/cc-code:cc-code` 完成会话开启协议，锁定当前阶段与坐标。
7. **阶段来源与视觉门（按阶段判定）**：读 `project.md` §九（9.1 阶段 / 9.2 泳道）。首个阶段固定为「视觉地基」（主题入口 + 全局框架 + 组件陈列页，不上线路由；`design.md` §0 = 不适用（无前端）的项目不设视觉地基）。有阶段 → 按阶段逐段推进；无 → 整体作单阶段跑完。阶段内有两条以上泳道 → 先过并行协议的启用体检，过了并发跑、不过单线程跑（⛔ 不自行拆阶段 / 拆泳道，拆分是规划的职责）。
   开工前对**本阶段**判定视觉门。判据**先读 `status.md`「风格：」**（`design.md` §0 只在 status 缺失时兜底）：
   ```
   design.md §0 = 不适用（无前端）？
     ├─ 是 ──► 放行，本阶段视觉段整段「不适用（无前端）」（无前端项目不设视觉地基）
     └─ 否 ↓
   老项目冷启动豁免？（三条件同时满足，只用一次）
     ├─ 是 ──► 放行，范围仅存量未改页面；本阶段仍建主题与组件陈列页，⛔ 不再二次豁免
     │          ① design.md 缺失或为草稿
     │          ② status.md「风格：」当前是 `未锁`（从未锁过风格）
     │          ③ 项目刚跨插件版本升级
     │          三条件通过 → 本命令报告交回主控，由主控把 status「风格：」写成 `未锁（冷启动豁免）`
     │          （⛔ 本命令不写 status.md；发放后本阶段照常开工）
     └─ 否 ↓
   按 status.md「风格：」分流（status 缺失才读 design.md §0）：
     ├─ 已定未实现 /（status 缺失时）design.md §0 = 改版待实现
     │     → ⛔ 拒跑：「风格已定未实现，是落地活，请走 /cc-code:agent-uiux」
     ├─ 已锁 /（status 缺失时）design.md §0 = 已锁定
     │     → 放行（design.md §0 若仍写「改版待实现」属 uiux 尚未补写的滞后，以 status 为准）
     ├─ 无前端 → 放行，本阶段视觉段整段「不适用（无前端）」
     ├─ 未锁（冷启动豁免）→ 放行，范围仅存量未改页面（本阶段仍建主题与组件陈列页；⛔ 不再二次豁免）
     └─ 其余（未锁 / 草稿 / 缺失）↓
   本阶段是视觉地基？
     ├─ 是 ─────► ⛔ 拒跑：「视觉地基要按已锁定的设计规格搭，请先走 /cc-code:plan-uiux」
     └─ 否 ↓
   本阶段要动页面？（覆盖 ux.md §1.1 页面清单任一页）
     ├─ 是 ─────► ⛔ 拒跑：「本阶段要动页面但风格未定，请先走 /cc-code:plan-uiux」
     └─ 否（纯后端 / 无 UI）──► 放行，本阶段视觉段标「不适用」
   ```
   - 冷启动豁免阶段仍须建主题与组件陈列页；结算时主控把「补 `design.md` 并锁定（走 `plan-uiux`）」写进下一步，⛔ 第二次开工不再豁免。
   - 豁免只放行「开工视觉门」，⛔ 不放宽 `ui-gates.md` 的任何规则；本次范围内改过的页面照查。

## 生命周期总览

```
启动校准 → 视觉门判定（按阶段，先读 status「风格：」）
                 ├─ 已定未实现                    → 拒跑 → /cc-code:agent-uiux
                 ├─ 涉及页面且风格未锁            → 拒跑 → /cc-code:plan-uiux
                 ├─ 无前端 / 纯后端阶段           → 标「不适用」放行
                 └─ 已锁（或冷启动豁免本次）      → 通过 ↓
①Dev（视觉地基阶段：主题 + 全局框架 + 陈列页）→ 校准
                 ↓
②QA 四层（逻辑 / 接口 / 交互 / 视觉）→ 校准
                 │
       ┌─────────┴──────────┐
       ▼                    ▼
 FAIL→回Dev(≤3)        PASS→阶段结算（qa 冻结本阶段新页基线）→ 校准
       │                    ▼
3轮仍FAIL→记账照常结算  还有阶段? →回①
                            ▼
                     全PASS（挂起项除外）→ 确认陈列页未上线 + 基线齐全 → MVP收口 → 结尾交人报告
```

> 阶段内有泳道时，①Dev / ②QA 两段各自变成「同角色多人并发 + 栅栏」，FAIL 只退回没过的泳道，阶段末多一次汇合回归；**运行时视觉检查只在汇合回归跑** —— 全部细则见并行协议，本节不复述。

## 阶段执行规范

每阶段严格按「读 / 做 / 跑 / 输出 / 写」执行，完成即校准。

### ① Dev 段（agent: dev）
| 项 | 内容 |
| --- | --- |
| 读 | 派单明确列出 `.cc-code/references/INDEX.md`（经验索引，命中主题才打开；规则见 `Agent.md` §四第 7 条）；本阶段涉及页面时读 `design.md` 全文件（生成主题与画页面的唯一视觉依据）、`ux.md` §1.1 + 本阶段页章、`project.md` §一.1（家族 / 主题入口 / 图标库） |
| 做 | 按规格实现代码 + 四层测试；遵循 project.md 约定；实现细节缺信息可自行决定并写进报告。有页面时：按 `design.md` 生成各端主题（**生成物禁手改**），页面只引用主题数值、只用 §一.1 登记的一个家族与一套图标，⛔ 不在主题入口外写色值 / 圆角 / 阴影 / 字号字面量 |
| 视觉地基（首阶段） | 写主题入口 + 全局框架 + 组件陈列页（项目内**不上线**路由，逐项呈现 `design.md` §八 全部状态）；组件陈列页不进导航、不进生产公开路由、不进 sitemap |
| 挂起 | 需求或契约（prd / ux / design / api / data）有缺口或冲突 → 挂起该部分及依赖它的部分，不动，在报告「挂起」里用业务语言写（技术细节另列），其余照做；主控按 `dev-qa-loop.md` §九 记进挂起清单，后续阶段照跑、挂起清单随任务单转给 dev（依赖挂起项的部分一并挂起），⛔ 运行中不问主人。视觉规格矛盾（`design.md` 内部或与 `ux.md` 布局相抵）同样挂起，改规格归 `uiux`（`plan-uiux`），⛔ dev 不自改数值 |
| 跑 | Agent(dev) → 自检：按 `project.md` §六 测试基建契约登记的命令，依次跑代码规范检查、类型检查、单测、e2e、视觉门（有哪些跑哪些；视觉门只跑不改，⛔ 不写基线） |
| 输出 | 业务代码 + 测试（落 `project.md` §六 声明的测试根）+ 完成报告（文件清单 + 自检 pass/fail + 主题再生成清单 + 组件陈列页影响 + 「采纳经验」一行，格式见 `Agent.md` §四第 7 条） |
| ⭐ 完成后 | **算精准回归面**：`codegraph affected <本段改动的源文件...>` → 得测试文件清单，传给 ②QA 段。契约里登记的非常规命名测试，按 `project.md` §六 登记的 glob 补跑，合并去重后即「本段回归范围」 |
| ✅ 完成后 | 执行 `/cc-code:cc-code` 校准 |

> **`affected` 空结果处置**（不做前置检测，出问题当场报一行即可）：
> 返回空 → 报「affected 未匹配到测试，本段回归用全量」+ 按序自查 ① 测试代码是否被 `.gitignore` 屏蔽（codegraph 不索引被 ignore 的文件）② 测试是否 import 了被测源码（纯 HTTP 打接口的脚本无 import 边，天然追不到）③ 命名是否需 `--filter`。CLI 未装 → 静默用全量，不报。

### ② QA 段（agent: qa，灰盒）
| 项 | 内容 |
| --- | --- |
| 范围 | `src/` 只读本阶段改动；`design.md` 只读（视觉唯一尺子）；读写权限以 `Agent.md` §三 为准 |
| 做 | 建验收断言清单；为每条断言写三层测试 + 视觉层测试（尺子 = `design.md` + `ui-gates.md`）；完整跑一遍（不抽样）。视觉地基阶段按 `ui-gates`「锁定前 · 复核」查主题入口 + 全局框架 + 组件陈列页，并**首次冻结截图基线**；后续阶段按「开发后」查本次受影响页面 × 声明视口 × 亮暗 × 五态 |
| 跑 | Agent(qa) → ① 段传来的 `affected` 回归范围优先（拿不到则全量）；视觉门命令取自 `project.md` §六（机器检查写成测试运行器测试，界面驱动工具只做探索取证）；性能只在全量验收与部署用 Lighthouse 命令行 |
| 输出 | QA 报告（Verdict + 断言追溯矩阵 + Critical Failures 清单 + V 段视觉结果 + 回归范围来源标注）；人判 VS 整理成合集板交主人，不卡流程 |
| 写 | `gates.md`（qa 唯一写者，主控不代写）；补测落测试根；视觉测试与截图基线落 `project.md` §六 登记的视觉测试位置与基线目录（**基线 qa 独占、入 git**）；逐轮报告与合集板落 `.cc-code/docs/qa/` |
| ✅ 完成后 | 执行 `/cc-code:cc-code` 校准 |

> 需求永远只来自 `prd.md` / `ux.md` / `design.md` / `api.md`，⛔ 不拿代码当尺子；qa 用 codegraph 的权限见 Agent.md codegraph 权限矩阵。

**四层测试矩阵：**

| 层 | 断言类型 | 工具与命令 |
| --- | --- | --- |
| 逻辑 | 纯函数/规则/边界 | 取自 `project.md` §六 |

From weiyi88/cc-code, MIT.

More from weiyi88/cc-code