Skip to content

martin1847/evolab / skills/cto-orchestration

cto-orchestration

Unverified

以 CTO/orchestrator 模式管理多 agent 软件交付。用户要求“你做 CTO/编排者”“派 omp/codex 去做”“goal 模式派发”、管理多会话开发或接入这套工作流时使用;“复盘/收口/retro/retrospective”“工作盘点/盘点候选/stocktake”也必须触发,盘点只提案不动工。新项目先用 repo-governance-bootstrap 建治理骨架。不用于单 agent 小任务、无需评审循环的局部改动或纯文档初始化。

FileKindSize
README.mdmarkdown5.3 KB
SKILL.mdskill md15.8 KB
references/agentctl/README.mdmarkdown26.8 KB
references/agentctl/agentctlexecutablescript57.6 KB
references/agentctl/codegraph-hooks.shexecutablescript2.5 KB
references/agentctl/cto-guard-agent.pyexecutablescript26.6 KB
references/agentctl/cto-guard-bash.pyexecutablescript150.5 KB
references/agentctl/cto-guard-edit.pyexecutablescript16.7 KB
references/agentctl/cto-guard-stop.pyexecutablescript7.6 KB
references/agentctl/duplexctl.pyexecutablescript239.5 KB
references/agentctl/guard-hooks.jsonconfig1.5 KB
references/agentctl/identity.pyexecutablescript113.5 KB
references/agentctl/post-checkout-codegraph.shscript18 B
references/agentctl/seat-census.pyscript10.8 KB
references/agentctl/watchctl.pyexecutablescript143.2 KB
references/agents-md-orchestration-section.mdmarkdown5.3 KB
references/decision-queue.mdmarkdown5.7 KB
references/dispatch-baseline.mdmarkdown3.7 KB
references/doc-lifecycle.pyexecutablescript9.2 KB
references/frontend-verify.mdmarkdown7.9 KB
references/goal-clauses.mdmarkdown8.0 KB
references/goal-preflight.pyexecutablescript40.9 KB
references/goal-template.mdmarkdown10.8 KB
references/implementation-discipline.mdmarkdown8.0 KB
references/measurement-protocol.mdmarkdown4.2 KB
references/onboarding-checklist.mdmarkdown3.2 KB
references/queue-freshness.pyexecutablescript3.8 KB
references/queue-hooks.jsonconfig617 B
references/retro-check.shexecutablescript28.2 KB
references/retro-hooks.jsonconfig2.2 KB
references/retro-reminder.shexecutablescript5.8 KB
references/retrospective.mdmarkdown7.7 KB
references/review-brief-preamble.mdmarkdown3.4 KB
references/review-dispatch.mdmarkdown14.4 KB
references/session-economics.pyexecutablescript18.2 KB
references/shock-in-the-loop.mdmarkdown3.8 KB
references/stocktake.mdmarkdown2.3 KB

references/frontend-verify.md

View on GitHub
# 前端验证规范(浏览器联调)

> 适用于任何前端 fix 的运行时验证。
> 核心原则:**前端改动,代码 review + 单测都不够,必须回浏览器看真实渲染**。

## 工具选型:浏览器 CLI 探路、Test 定型、curl 补 HTTP

> 三个词各指一物,**别用裸「CLI」**:`playwright-cli`(浏览器 CLI,驱真浏览器)·
> `@playwright/test`(断言真源)· `curl`(HTTP 直连,不经浏览器)。

| 角色 | 工具 | 何时用 |
|---|---|---|
| **探索 / 定位 / 临时诊断** | `@playwright/cli`(命令 `playwright-cli`):`snapshot` 取 ref → `find` 搜大快照 → `generate-locator` 出 locator;`requests` / `console` 读联网与运行时 | 真浏览器且省 token——工具 schema 不进上下文,命令即证据可贴进 goal。看得到"渲染对不对"与**前端自己的联网 bug**(代理没配、请求 pending)。ref 定位比坐标/截图稳,坐标/vision 仅作 fallback。 |
| **断言真源 / 重复执行 / 部署后验收** | `@playwright/test` 的 `.spec.ts` | selector 与 oracle 稳定后落 spec;本地 build 与已部署环境**复用同一 spec**,只切 `use.baseURL`(按 `process.env` 分支)与 auth fixture(`auth.setup.ts` setup project + `dependencies` + `storageState`;凭据落 `playwright/.auth` 且 gitignore)。 |
| **后端 ground-truth** | `curl` + bearer token | 抓 SSE 逐事件时序(`curl -N`)、探 API、提 token、脚本化。**绕过前端网络层 → 验不了前端行为**,别拿它当渲染验证。 |
| **Playwright MCP(例外形态)** | 同一套工具的 MCP 前端 | 默认 headed、贵(工具 schema + 快照进上下文);只在要人眼盯或逐 tool 迭代时用。 |

**浏览器归属与登录态**:默认 Playwright 自起的浏览器,**登录态跟项目走、不用临时 profile**——
每角色一份 storageState(上表的 auth fixture),一个项目一个命名会话 `-s=<project>` 天然隔离、
并行不互污。**绝不抢主理人日常 Chrome/Edge 的 profile**;企业 SSO 等无法回放成 storageState 时 CDP attach 已在跑的专用实例,经主理人放行(一次性 override)——bash guard ⑨ DENY · agent guard P0a DENY。

## 重复型 E2E:交付物 = `.spec.ts`,不是自建 runner

同一验收第二次起不再手驱:selector 与 oracle 稳定后落 `@playwright/test` spec,负对照内建
(如"某个假 id 必须查无"),随项目入库、路径进该项目 AGENTS.md。**消费口径 = 进程退出码 + reporter
产物**(取代自建 node runner 的 `RESULT` 尾行约定;验收方只认退出码与 report,不认叙述)。

## 状态形状矩阵(E2E 只测新鲜快乐态 = 结构性漏测)<!-- trunk:状态形状矩阵 -->

全部 E2E 只用"刚登录的黄金账号"时,token 过期态(恢复代码缺失)与贫数据形状(oauth 用户缺
nickname/phone)永远走不到——**新鲜登录的测试走不到时间态与数据形状分支**。
铁律:鉴权/用户数据相关的前端验证,至少覆盖:

| 态 | 制造方法(Playwright 可脚本化) |
|---|---|
| 新鲜登录 | 常规流程 |
| **过期/老化会话** | 登录后删 access cookie(保留 refresh/UI 提示 cookie)再导航——断言自动恢复而非报错 |
| **贫数据账号** | mock 最小响应形状(仅必填字段)——断言空态占位而非崩溃/永久加载 |
| 未登录 | 断言引导登录而非通用错误 |
| **引擎×输入方式** | 桌面 chromium 鼠标 click 通过 ≠ 真机触摸可用——至少补一组 **webkit 引擎 + iPhone 设备描述符(hasTouch) + `page.tap`**(近似 WKWebView/微信);交互命中类改动(可点标签/弹层/浮层)此组必跑 |
| **非 owner 视角**(多主体轴,见主干 §3) | 运行前按产品合同**写死每个单元的 entitlement 与期望结果**,禁止跑完再在「可见/拒绝」间选 oracle:正向单元 = owner 建资源并真实授予第二账号角色/分享 → 断言**全链可见**;拒绝单元 = 未授权或跨租户账号 → 断言各接口**显式拒绝**而非静默消失(典型病形:各接口对同一资源用了不同可见性谓词——一处按分享判、一处只按租户收窄,非 owner 视角整块蒸发而 owner 视角全绿) |

staging 应养**常备测试账号矩阵**(手机号全字段户 / oauth 贫字段户 / 同租户第二身份户),不是一个黄金账号打天下。

## 联调铁律

1. a11y/DOM 快照优先定位(canvas UI 退回截图);2. console/network 读运行时,别从截图猜;3. 每次改完回浏览器验运行时(HMR 后重 snapshot);交互/状态修复须以正常操作走通受影响步骤及相关下一步,绕过正常交互约束的操作仅作诊断。

## 交付闭环:三段绿 ≠ 真用户能看到(`代验路径≠真路径` 的前端实例)

mock 契约 + 后端 SSE 帧 + 本地 dev 渲染**都过,也不等于真用户能看到**。完整闭环:
改代码 → **本地 localhost E2E(部署前门,必过)** → **运维发布** → **登已发布的真应用跑真实一轮**
(真浏览器,非 mock / 非本地 dev)→ 成功**截图** → 才更新任务系统状态。

- **部署前先在 localhost E2E(必过门,别直接发布)**:用**真 build 连真后端**(不是 §联调铁律3 那种
  vite HMR dev 渲染——那只是迭代时的快照)跑一遍真实用户路径。理由:**部署慢且贵,bug 在本地抓一次
  比"发布→ReOpen→再发布"省一整轮**。本地起服务+API base 覆盖的项目特定坑写进项目 `AGENTS.md`
  (见下「本地起前端」)。localhost E2E 绿是**发布前置条件、非验收**。
- **发布后再登真应用跑真实一轮**才是验收门。**别拿"代验路径"当"真路径"验收**——真实路径常和你
  mock / 甚至 localhost 的那条不是同一条(部署环境的 build config / 路由 / 鉴权 / 通道可能不同)。
通用原则见 SKILL.md §3「验证诚实」。

## E2E 验收委派给浏览器子 agent(不是编排者亲手刨)

"登真应用跑真实一轮"是验收,不占编排者主上下文(SKILL §0 不自己跑长 E2E)。编排者只出**派发包**:
登录/导航配方 + 每条 **PASS 判据** + **凭证接入文件的绝对路径**(它在治理根,子 agent 的 cwd 在
worktree/子仓里搜不到;别指望它自己找、别 symlink 进仓库)。子 agent 隔离上下文里 OBSERVE,回
**PASS/FAIL/BLOCKED + 证据**,**只读、不动 git/状态**。多分钟慢流与重复点击类尤其该派。
**真路径没在真应用验过前不标「可测试」**;「数据缺 / 够不着」是合法 BLOCKED,别逼它猜 PASS。

**两种模式别混**:上面是**验收探针**(判据已知,答 PASS/FAIL)。另一种是**探索器**——判据未知,
让它自己找问题;人设 / 派发 brief / 筛选规则 / 输出契约 / 两轮法的机制本体在独立伴随 skill `frontend-explorer`,此处不复制。

## 本地起前端:坑项目特定 → 写进该项目 AGENTS.md

每个前端项目本地起服务的坑差别很大,不在此固化。项目 `AGENTS.md` 建一节写清四件事:后端代理目标与
控制它的 env(未设常请求 pending 挂死)、运行时配置注入点与临时覆盖法、登录是否多步(密码提交 ≠ 登录成功)、
测试运行器怪癖(如 `watch` 模式撞 `EMFILE` → 单跑兜底)。
唯一跨项目手法:要临时改硬编码的运行时配置又不污染工作树,在页面加载前用 `page.addInitScript`
(`playwright-cli run-code` 或 spec 里直接调)把配置对象 `Object.defineProperty(..., {writable:false})`
锁住,让页面自身的注入脚本覆盖失败;加载后求值的 `evaluate` 抢不到页面注入之前。

## 新项目接入

把「联调铁律」与「工具选型」写进该前端项目 `AGENTS.md`("前端联调/浏览器运行时验证规约"节),
并钉死 `@playwright/cli`(仍在 0.x,命令面会漂)与 `@playwright/test` 的版本。
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall