goal-loop

把原型编译成 AI coding agent 能稳定执行的建站规格。

goal-loop 是一个面向 Claude Code 和 Codex 的 skill。它不直接替 agent 写代码，而是先把原型、模糊需求和设计意图，整理成一份结构化 build spec：统一设计契约、拆分 worker task、定义 handoff 格式，并用客观浏览器验收决定是否完成。

适合你，如果你已经在用 Claude Code / Codex，并且想把原型、HTML demo 或线上页面稳定还原成可运行网站。

• 不跑偏：先锁定 token、组件和文件结构，再开始分工。
• 能并行：把页面拆成 scoped workers，减少上下文漂移和互相踩文件。
• 会自检：用 build、DOM、token、console、响应式和截图证据验收，不靠“看起来不错”。

一句话

普通 prompt 是“让 AI 试着建一个站”。 goal-loop 是“先生成一份 AI 能长期遵守的施工图，再让 agent 按图施工，并反复验收”。

Prototype -> goal-loop spec -> task graph -> scoped workers -> validation -> site

为什么需要它

直接让 AI 根据原型建站，常见问题不是“不会写代码”，而是跑久之后失控：

• 不同组件各自发明颜色、间距、圆角；
• 多个 worker 重复造共享组件，甚至互相覆盖文件；
• 页面看似完成，但 console、响应式、关键 DOM、设计 token 没有检查；
• agent 用主观视觉判断收工，缺少可复查的完成证据。

goal-loop 把这些风险变成流程约束：

直接交给 AI	使用 goal-loop
先写代码，边做边猜设计系统	先抽取契约，再落地共享 token 和组件
worker 边界模糊，容易互相踩文件	每个 task 有依赖、write scope 和 handoff
“看起来不错”就结束	build + browser validation + screenshot evidence
失败原因混在一起	按 T0 / worker / assembly / validation 归因回修

它会生成什么

一份 goal-loop spec 通常包含：

1. 目标与范围：原型来源、技术栈、完成定义。
2. 契约：设计 token、组件清单、目录结构、worker 返回格式。
3. 任务编排：T0 主线程任务、组件/区块 worker、依赖层级、写入范围。
4. 验收循环：每个任务的客观检查、MAX_ATTEMPTS、失败上报格式。
5. 执行机制：Claude Code 或 Codex 的具体调度方式。

在 Codex 侧，还可以进一步生成：

• goal-loop.taskgraph.json
• worker-prompts/*.md
• RUNBOOK.md
• PROGRESS.md
• DRAFT_PR.md
• scripts/validate-browser.mjs
• browser-checks.example.json

已验证样例

示例	证明什么	入口
Tala dashboard	复杂仪表盘可按 spec 还原；loop 抓到并修复移动端缺陷	验证报告
Nova landing page	同一套中立 spec 可迁移到 Codex；多 worker 并行构建通过验收	回归报告
PulseOps full chain	从原型 intake 到 spec、task graph、worker fan-out、build/browser validation 的完整链路	完整验证

更多示例入口见 examples/README.md。

安装到 Claude Code

cp -R adapters/claude-code ~/.claude/skills/goal-loop

然后在 Claude Code 里使用：

/goal-loop <prototype.html or URL>

预期输出：

• <project>-spec.md 建站规格；
• 契约、任务分解、验收循环和执行机制章节；
• 一份可以交给 Claude Code 或 Codex 执行的 build spec。

在 Codex 中使用

如果已经有一份 goal-loop spec，可以生成 Codex 执行产物：

node adapters/codex/scripts/goal-loop-codex.mjs prepare \
  --spec examples/nova/nova-spec.md \
  --out artifacts/nova

Codex 随后按 runbook 执行：

1. 先建立可见执行层：工作分支、Draft PR、PROGRESS.md 和首个小步 commit。
2. 主线程实现 T0 工程壳、共享 token、基础组件和验证脚本。
3. 按依赖层分发 worker prompts。
4. 检查 JSON handoff 和 deviations。
5. 组装页面。
6. 运行 build 和 browser validation。

可见执行默认强制

所有 goal-loop Codex 执行都必须使用三层进度可见性：

• Draft PR：作为用户随时查看 diff、CI 和讨论的外部容器。
• PROGRESS.md：作为当前阶段、任务状态、最新验证、最新 commit、阻塞项和下一步的实时状态板。
• 小步 commit：在 T0、worker handoff、组装、验证修复、完成或 blocked report 等稳定边界提交。

如果无法创建 Draft PR（例如没有 remote、GitHub CLI 未登录或权限不足），执行不能静默继续；必须维护 DRAFT_PR.md fallback，并在 PROGRESS.md 里记录原因。

验收标准

一个站点不能因为“看起来差不多”就算完成。goal-loop 要求使用新鲜的、可复查的验证证据：

• build / typecheck 命令退出码为 0；
• 页面加载后没有 console error 和 page error；
• 关键文案能在 DOM 中断言存在；
• root token 值与 spec 一致；
• 关键 computed style 与契约一致；
• 1200、768、320px 视口没有横向溢出；
• 输出截图证据，方便人工复核。

如果在 MAX_ATTEMPTS 内仍无法通过，agent 应写 blocked report，而不是宣称完成。

仓库内容

core/                 agent-neutral 的三层方法论
adapters/claude-code/ 可安装的 Claude Code skill
adapters/codex/       Codex skill、task graph 生成器、浏览器验收脚本
examples/             真实样例、回归构建和验证记录
tests/                task graph / prepare 脚本测试
outputs/              README 使用的营销视觉图

MVP 边界

当前最适合：

• 静态 HTML 原型；
• 无需登录即可访问的公开 URL；
• 单页 landing page、dashboard、marketing tool；
• React/Vite 输出，并配合浏览器验收。

暂不承诺：

• 登录后的复杂产品；
• 后端/API 集成；
• 支付流程；
• CMS/admin 系统；
• 一键生产部署。

English Brief

goal-loop turns a prototype into a structured build spec for Claude Code and Codex. It helps AI coding agents avoid long-run drift by enforcing a shared design contract, scoped worker tasks, JSON handoffs, and objective browser validation.

Core loop:

Prototype -> spec -> task graph -> workers -> validation -> site

Install for Claude Code:

cp -R adapters/claude-code ~/.claude/skills/goal-loop

Prepare Codex artifacts from an existing spec:

node adapters/codex/scripts/goal-loop-codex.mjs prepare \
  --spec examples/nova/nova-spec.md \
  --out artifacts/nova

License

暂未选择 license。