ai-delivery-workflow 0.2.2 → 0.4.0

package/skills/ai-delivery-orchestrate/assets/project-template/.workflow/tools/ui-acceptance/ui-acceptance.mjs

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+
+import path from "node:path";
+import { runUiAcceptanceCommand } from "./ui-acceptance-runtime.mjs";
+
+function usage() {
+  return [
+    "Usage:",
+    "  ui-acceptance <plan|verify> [project] --request <relative-yaml> [--results <relative-yaml>]",
+  ].join("\n");
+}
+
+function option(args, name) {
+  const index = args.indexOf(name);
+  if (index === -1) return undefined;
+  const value = args[index + 1];
+  if (!value || value.startsWith("--")) throw new Error(`Missing value for ${name}`);
+  return value;
+}
+
+try {
+  const args = process.argv.slice(2);
+  const action = args[0];
+  if (!action || action === "--help" || action === "help") {
+    process.stdout.write(`${usage()}\n`);
+  } else {
+    const projectArg = args[1] && !args[1].startsWith("--") ? args[1] : process.cwd();
+    const report = runUiAcceptanceCommand(path.resolve(projectArg), action, {
+      request: option(args, "--request"),
+      results: option(args, "--results"),
+    });
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+  }
+} catch (error) {
+  process.stderr.write(`ai-delivery-ui-acceptance: ${error.message}\n`);
+  process.exitCode = 1;
+}

package/skills/ai-delivery-orchestrate/assets/project-template/AGENTS.md

@@ -9,16 +9,39 @@
 - 代码引用必须包含 `repo_id`、`code_commit`、可选 `code_tag`、`source_path` 和 SHA-256。版本发布身份必须同时核验代码 Tag、工作流 Tag 和 Manifest checksum。
 - 根 `.gitattributes` 必须保持安装器写入的工作流 `eol=lf` 规则，避免跨平台 checkout 改变受控物料字节和 checksum；该规则不得扩展到嵌套代码仓。
 
+## 代码智能
+
+- 解析、定位或评估源码影响前，先从 `.workflow/config/workspace.yaml` 的 `code_repository.path` 解析代码仓库；CodeGraph MCP 可用且该代码仓已有索引时，优先调用 `codegraph_explore`，并把代码仓绝对路径作为 `projectPath`。
+- MCP 不可用但 CodeGraph CLI 与索引可用时，运行 `codegraph explore "<query>" --path <code-repository>`；定位结果必须回到具体源码和测试核对。
+- CodeGraph 不可用、未初始化、失败或不支持当前语言时，降级到 Semble，再使用 `rg` 和定点读取；外部代码智能工具缺失不阻断正式工作流。
+- `codegraph affected` 只生成推荐测试建议，不得据此缩减既有必跑测试或正式 Gate。
+- `.codegraph/` 是代码仓内本地可重建缓存，通过代码仓本地 Git exclude 保持未跟踪；它不属于正式状态、artifact registry、事件、checkpoint、安装清单或归档。Windows 与 WSL 共用 checkout 时使用不同的 `CODEGRAPH_DIR`。
+- Agent/MCP 全局安装由用户显式管理；工作流 `init`、`upgrade` 和 CodeGraph setup 只管理项目级工作流资产或代码仓索引。
+
+## Mock System
+
+- Prototype 或 UI Acceptance 需要协议场景时，先运行 `ai-delivery mock setup <workspace>` 与 `ai-delivery mock start <workspace>`；每个 mock 显式登记 External Dependency Mock（`external-dependency`）或 Product Backend Mock（`product-backend`）kind、owner、批准合同、replacement condition、operation/channel 和稳定 scenario identity，并保持两类 catalog 隔离。先审阅 `ai-delivery mock sync <workspace> --dry-run`，确认具名 scenario 和 dispatcher 输入，再运行 `ai-delivery mock sync <workspace>`。
+- 受管 UI 修改必须把每个实际 OpenAPI/AsyncAPI 定义导出到 `mock-admin-exports/`，并由 `mock-admin-export.yaml` 按 kind、Mock ID、protocol、相对路径和 SHA-256 绑定；freeze 必须对每个 active Review Scene 使用的导出 scenario 执行协议校验。禁止生产流量录制、生产凭据和未脱敏个人数据，显式导入仍须通过脱敏检查。每个 active Review Scene 在 `mock-scenario-mappings.csv` 中必须且只能映射一个确定性 scenario。
+- 先运行 `ai-delivery mock freeze <workspace> --experience <relative-directory> --scenario-pack mock-scenario-pack-request.yaml --dry-run`，让用户确认精确 candidate checksum，再冻结并在正式 artifact registry 登记不可变 Mock Scenario Pack。只有该登记 Pack 可供 Prototype revision 和 UI Acceptance 共用。
+- Product Backend Mock 只能驱动 UI 场景，不能证明真实产品后端功能或端到端验收；真实后端满足 replacement condition 后停用对应 mock。
+- Microcks 只绑定 loopback；数据库、日志、流量和端口状态可丢弃，不得进入正式状态、artifact registry、事件、checkpoint 或 Gate evidence。
+
 开始工作前：
 
 1. 只使用安装在 `.agents/skills/` 下的项目级 Skill，不得在全局安装或更新本工作流。
 1.1 用户说“开始”“继续”“下一步”“现在做到哪了”、直接描述需求或明确提出发布，都属于有效自然语言入口。AI 必须自主规划并调用所需 Skill 和项目内 CLI，不得要求用户输入 Skill 名称或执行工作流命令；只向用户询问业务事实、物料确认、人工 Gate 或外部副作用授权。
 2. 首次进入项目或重启会话时，先使用 `$ai-delivery-bootstrap`，并在项目根运行 `node .workflow/tools/bootstrap/bootstrap.mjs inspect` 只读识别状态。空项目进入需求发现，存量代码项目生成草稿上下文，中断任务进入 checkpoint 恢复，不一致状态停止并报告。
-2.1 已完成 `init` 且没有正式交付物和 task shard 时，先运行项目内 `bootstrap` 入口生成上下文，再以 `INIT-0001` 建立 `TASK-INIT-0001-00`（Bootstrap）和依赖它的 `TASK-INIT-0001-01`（产品发现）。首次业务问题之前必须已有合法任务身份；不得从聊天记忆临时编造下一任务。
-3. 修改代码或交付物前，先读取 Bootstrap 返回的 `runtime.next_action_owner`。仅当责任方为 `agent` 时，运行 `$ai-delivery-checkpoint-task recover --iteration-id <iteration-id>`，只继续返回的 `recommended_task_id`，并通过 `task-state.mjs activate` 激活任务。责任方为 `user` 时，只原样询问记录的单个业务问题，禁止 recover、activate、checkpoint、正式状态、物料或 Git 写入；责任方为 `external` 时，只报告等待条件。收到所需输入后，必须通过 `activate` 同时提供 `--next-action-owner agent` 和新的幂等 `--next-action`，由 CLI 在需要时从共享 shard 原子恢复本机 runtime 并转交责任方。
+2.1 已完成 `init` 且没有正式交付物和 task shard 时，先运行项目内 `bootstrap` 入口生成上下文，再以 `INIT-0001` 建立 `TASK-INIT-0001-00`（Bootstrap）和依赖它的 `TASK-INIT-0001-01`（Product Shaping）。首次业务问题之前必须已有合法任务身份；不得从聊天记忆临时编造下一任务。
+3. 修改代码或交付物前，先读取 Bootstrap 返回的 `runtime.next_action_owner`。仅当责任方为 `agent` 时，运行 `$ai-delivery-checkpoint-task recover --iteration-id <iteration-id>`，只继续返回的 `recommended_task_id`；先用 `task-state.mjs inspect --task-id <task-id>` 只读核对，再通过带 `--phase` 的 `activate` 激活任务。推荐状态为 `failed` 时必须使用 `activate --new-attempt --phase repair`。责任方为 `user` 时，只原样询问记录的单个业务问题，禁止 recover、activate、checkpoint、正式状态、物料或 Git 写入；责任方为 `external` 时，只报告等待条件。收到所需输入后，必须通过 `activate` 同时提供 `--next-action-owner agent` 和新的幂等 `--next-action`，由 CLI 在需要时从共享 shard 原子恢复本机 runtime 并转交责任方。
 4. 任务、checkpoint、恢复状态、活动任务标记和版本归档只能由 `.agents/skills/ai-delivery-checkpoint-task/scripts/task-state.mjs` 修改。
 5. 正式流程、物料和 Gate 状态只能由 `node .workflow/tools/state/state.mjs ...` 修改。禁止直接编辑 `.workflow/delivery/workflow-state.yaml`、`.workflow/delivery/artifact-registry.yaml` 和 `.workflow/delivery/state-events.jsonl`。
 5.1 研发 scope 使用 `iteration-started`，发布 scope 仅在用户明确发布后使用 `release-started`；两者可并行且不得互相重置。节点必须满足流程图前置条件、成功证据和当前尝试的强制 Gate。
+5.1.1 当前研发生产路线是 `development-seven-node`：`00-bootstrap -> 01-product-shaping -> 02-solution-design -> 03-delivery-readiness -> 04-implementation -> 05-candidate-assurance -> 06-version-closeout`。生产 Skill 只能为新任务、物料和正式 transition 使用这些研发节点 ID。`development-legacy-13` 仅提供只读兼容：`inspect`、`verify`、`rebuild` 和显式迁移可以读取历史状态；新任务、物料登记、transition、candidate、版本收尾和 Gate 写入全部拒绝。发布节点 `R00-release-request` 至 `R10-release-archive` 继续允许写入。
+5.1.2 Bootstrap 报告旧 schema、任务分组歧义或错误归档时，先运行发行包 `migrate --dry-run` 审阅 schema、分组、冲突、已验证 anchor 和文件变化。旧根布局会复制到 `.workflow/`，平铺 task 增加显式 attempts；分组歧义只能用绑定 dry-run source checksum、`human:` actor 和 rationale 的 `--decisions` 文件解除。结构迁移保持源字节、task lifecycle、scope、正式视图和旧事件字节不变；错误归档只通过带人工 actor、原因、RCA 与恢复 evidence 的独立 `repair --invalidate-archive` 前向事务失效，原归档不得改写。迁移后出现 schema 2 事务或迁移目标字节漂移即关闭回滚窗口。compact 与迁移分离：可信 anchor 建立后先运行 `ai-delivery compact <project> --dry-run` 审阅 coverage、root digest 和字节计划，只有人工明确要求才应用。
+5.1.3 Prototype 迁移的 dry-run 必须报告旧 set 中声明、有效和无效成员数量，并据此区分零成员、单成员和多成员；同一份 decisions 文件必须同时包含 `decisions` 与 `prototype_decisions`。完整性或 checksum 冲突只能修复源证据，人工决定不得覆盖；旧 member/set、关闭或归档记录、Gate 和事件保持原字节。迁移后的唯一 descriptor 状态为 `migration-pending-ux-ui`，必须先建立并校验完整的新 Prototype revision，再执行全新的 `UX-UI`；原型查看与审核统一由工作流管理器承担。
+5.2 Delivery Readiness 使用 `scope freeze` 冻结带 checksum 的 Slice、需求、验收、任务和物料集合并启用 `scope_contract_version: 1`。冻结后只有带明确人工批准和 `--supersedes` 的 `scope amend` 可以改变范围；预算超限仅用 `scope warn` 登记 `warn-only` 与 `reslice_performed: false`，不得自动重新切片或改变验收。历史 scope 未启用该字段时保持旧契约兼容。
+5.3 从 `inspect.derived_node_states` 读取 `pending | active | waiting | blocked | ready-to-complete | completed`，不得根据聊天或单一任务状态直接写正式节点状态。投影必须综合 task、最新 blocking finding、Gate、artifact、candidate、当前 scope manifest 和 completion receipt；受新契约治理的节点仅能从 `ready-to-complete` 完成，并写入绑定这些事实的 completion receipt。
+5.4 `draft/review-draft` 是 registry 外的可变 working file。提交、拒绝、批准、冻结、失败等语义决定使用新 artifact ID 登记为不可变 revision；后续决定通过 `--supersedes` 创建新 revision，不得用 `artifact status` 原地改写。`artifact status` 只兼容迁移升级前已登记的 draft。`artifact compact` 默认零写入；apply 必须先把 anchor 覆盖的 legacy shard 原字节写入 checksummed gzip bundle，并从包内完整 replay 到锚定 registry checksum，验证失败不得移除 loose history；成功后的模式是 `compacted-history`。`artifact prune` 同样默认零写入，只有显式 `--apply` 才能删除 artifact shard 并写 retention receipt；其模式是 `retained-history`，不得声称重审已删除字节。
 6. 状态脚本失败时必须停止并修复输入、revision 冲突或脚本问题，不得手工修改受控文件绕过失败。
 7. 每次状态变更前运行 `inspect` 获取当前 revision；每次节点交接、版本收尾、生产审批、部署和发布归档前运行 `verify`。
 8. 读取 `.workflow/standards/index.yaml`，只加载适用于当前任务且状态为 `approved` 的规范。
@@ -26,16 +49,19 @@
 10. 应用 `STD-ARTIFACT-PATH-001`：研发流程文档写入 `.workflow/`；计划版本产物写入 `.workflow/iterations/<version-id>/<node-id>/`；独立发布产物写入 `.workflow/releases/<release-id>/<release-node>/`；不得忽略整个 `.workflow/`。
 11. 应用 `STD-TEST-LOCATION-001`：应用测试使用代码仓库既有框架和原生测试位置，不写入 `.workflow/`；临时测试输出按代码仓库规则忽略，不得登记为正式交付物。
 12. 每个交付物记录实际应用的规范 ID 和版本。已登记物料发生变更时创建新 ID，并使用 `--supersedes` 关联旧版本，不得覆盖旧版本。
-13. 一个任务组开始前，将全部已知任务按 `sequence` 和 `depends_on` 登记为 `queued`。每个任务用 `next_action_owner: agent | user | external` 明确下一动作责任方；重复 evidence 必须保持唯一。激活推荐任务后，在有意义的里程碑写入 checkpoint，并在交还控制权前结束当前任务状态。
+13. 一个任务组开始前，将全部已知任务按 `sequence` 和 `depends_on` 登记为 `queued`，并用 `--scope`、`--acceptance`、`--responsibility` 固定逻辑契约。init 只允许 queued；只有 activate 能创建 attempt 并检查依赖，queued 必须 activate 后才能 checkpoint/finish。phase 状态由 task transition 推导且不得使用 `--phase-status` 覆盖。iteration、node、skill、goal、scope、责任、依赖和 acceptance 未变化时复用同一 task ID；相同契约不得换 ID，契约实质变化才创建新 task，并用 `--derived-from` 或 `--supersedes` 关联。进入 review phase 时 CLI 固定 `review_subject_baseline`；评审必须针对该对象完整收集全部反馈，期间不得修改代码，批准时若 Git 已变化则拒绝。随后通过 `--change-set-json` 提供批准人、理由、全部 open finding IDs、允许文件、预期证据、`review_axes` 和 `collection_decision`，CLI 自动固化代码修复基线、规范反馈集和 collection checksum。实现者在 repair/test/verification phase 集中应用同一个批准集；随后使用同一个 `change_set_id` 集中复审，把 finding 标为 resolved，并声明与批准后真实 Git 变化完全一致的 `changed_files`。评审、分诊、修复、测试等轮次记录为同一 task 的 phase/finding，finding 记录只追加；resolved 必须引用已有 open finding。task 级最新结论仍有 open blocking finding 时不得 completed。failed 不满足依赖但仍是待恢复工作，原契约重试必须显式使用 `activate --new-attempt --phase repair`。每个任务用 `next_action_owner: agent | user | external` 明确下一动作责任方；重复 evidence 必须保持唯一。激活推荐任务后，在有意义的里程碑写入 checkpoint，并在交还控制权前结束当前任务状态。
 13.1 `task-state.mjs` 会从权威 `.workflow/config/workspace.yaml` 解析嵌套代码仓并写入 `code_branch`、`code_commit`；不得从安装清单副本推断代码路径，也不得把工作流分支或工作流提交作为代码身份。`blockers` 只保存当前未解决阻塞，解除阻塞后必须通过脚本切换状态并清空当前列表。
 14. Hook 日志只用于脱敏审计和心跳，不得作为任务完成、Gate 批准或正式交付物的替代品，也不得修改正式或 runtime 状态。
-15. 研发流程在 `12-version-closeout` 结束。登记 `release-ready` 收尾物料、完成节点并验证不可变身份后，必须通过正式状态 CLI 的 `version-closed` 事件更新累计研发版本，再归档任务上下文；不得直接编辑状态文件，也不得因为版本完成而自动发布。
+14.1 任何正式前端修改必须先更新隔离 Prototype 并取得用户 Page approval，再冻结 checksummed `frontend-change-scope.yaml` 与 UI Mapping。首次写入每个 UI 路径前运行 `ai-delivery frontend-guard check-file <workspace> --path <path>`；合并、Candidate Assurance 和正式交接前从固定 refs 运行 `ai-delivery frontend-guard verify-diff <workspace> --base <base> --head <head>`，由 independent Git diff 复核。Hook 只做前置防误改，不能替代后者。文案、样式、响应式、无障碍、Page/route 增删和缺陷修复均无例外。
+14.2 UI-bearing candidate 必须在 `05-candidate-assurance` 内运行 `ai-delivery ui-acceptance plan` 和 `verify`，绑定 active attempt、immutable candidate、Prototype revision、Visual Standard、Page receipts、UI Mapping、Scenario Pack 与 pinned Playwright environment。UI Acceptance 不是新节点。Product Backend Mock 不得充当真实后端验收；candidate checksum 改变时返回 `04-implementation` 并创建新 attempt。
+15. 当前研发生产路线在 `06-version-closeout` 结束。登记 `release-ready` 收尾物料、完成节点并验证不可变身份后，必须通过正式状态 CLI 的 `version-closed` 事件更新累计研发版本，再归档任务上下文；不得直接编辑状态文件，也不得因为版本完成而自动发布。
 16. 后续计划版本必须从最新 `line/<product-id>` 开始；`main` 始终表示当前生产验证成功历史。
 17. 只有用户明确提出发布并选择截止版本时，才使用 `$ai-delivery-orchestrate-release`。系统必须计算从当前生产版本到目标版本的连续闭包。
 18. 同版本重新发布必须创建新 release ID，并重新执行环境快照、验证和生产审批。R09 只向 R10 交付已验证生产身份；R10 登记 `released` 归档物料并完成节点后，必须通过 `release-archived` 事件更新生产版本和 release ID。历史版本恢复通过旧镜像 digest，不创建 rollback 分支。
 19. 不得绕过流程 Gate、修改已批准基线、推断缺失批准，或在恢复后自动重放生产动作。
-20. 版本任务归档的权威位置是 `.workflow/control/archives/versions/<version-id>/`。归档完成后不得把对应任务或 checkpoint 留在活动集合，普通恢复不得加载归档详情。
-21. 需要人工浏览工作流和物料时，在项目根目录运行 `.\.workflow\tools\viewer\start.cmd`（Windows）或 `sh ./.workflow/tools/viewer/start.sh`（macOS/Linux）。查看器是可删除、可由 `init` 重装的只读工具，其缺失不影响工作流运行。
+20. 版本任务归档的权威位置是 `.workflow/control/archives/versions/<version-id>/`。归档前必须由正式状态 CLI 的 `snapshot references` 在最新可信 anchor 中投影目标 scope manifest、candidate、Gate decision 与 history anchor；任何缺失都必须在写归档前失败，不得产生 nullable formal reference。`version-manifest.json` 以相对路径和 checksum 引用 task summary、attempt receipt（checksum 覆盖 ref 指向的完整 attempt 值）和这些正式记录，不重复内嵌正式记录。归档完成后不得把对应任务或 checkpoint 留在活动集合，普通恢复不得加载归档详情。
+21. 需要人工管理工作流、查看物料或审核原型时，在项目根目录运行 `.\.workflow\tools\manager\start.cmd`（Windows）或 `sh ./.workflow/tools/manager/start.sh`（macOS/Linux）。工作流管理器是唯一受支持的项目控制界面；所有写操作仍必须经过其治理动作、并发校验、Receipt 和不可变 Event。
+21.1 读取、审核、配置或操作 Workflow Manager 时，先读取 `.workflow/tools/manager/AGENT-INTERFACE.md`，通过 `contracts` 资源发现动作 Schema，并遵循其中的并发、幂等、plan/apply、Receipt/Event、Outbox 和恢复流程。
 ## 项目级工作流自进化
 
 - 用户明确提出工作流意见或建议时，使用 `$ai-delivery-evolve-workflow` 记录脱敏反馈并返回反馈 ID；普通讨论和 AI 推测不得冒充用户反馈。

package/skills/ai-delivery-orchestrate/assets/project-template/gitignore.template

@@ -0,0 +1 @@
+.workflow/delivery/runtime/

package/skills/ai-delivery-orchestrate/assets/project-template/ref/ui/CONTRIBUTING.md

@@ -0,0 +1,25 @@
+# Contributing to Awesome Design MD
+
+Thanks for contributing.
+
+This repository is a curated collection of DESIGN.md files extracted from popular websites. Each file captures a site's complete visual language in a format any AI agent can read.
+
+## How to Contribute
+
+### Improve an Existing DESIGN.md
+
+If you notice issues with an existing file:
+
+1. **Open an issue first** to describe what you'd like to change and get feedback from maintainers
+2. Open the site's `DESIGN.md`
+3. Compare against the live site
+4. Fix incorrect hex values, missing tokens, or weak descriptions
+5. Update the `preview.html` and `preview-dark.html` if your changes affect displayed tokens
+6. Open a PR with before/after rationale
+
+
+We cannot accept DESIGN.md pull requests to maintain the quality of the existing collection.
+
+## License
+
+By contributing, you agree your contributions are provided under the repository license terms.

package/skills/ai-delivery-orchestrate/assets/project-template/ref/ui/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 VoltAgent
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/skills/ai-delivery-orchestrate/assets/project-template/ref/ui/README.md

@@ -0,0 +1,250 @@
+
+<a href="https://github.com/VoltAgent/voltagent">
+     <img width="1500"  alt="claude-skills" src="https://cdn.voltagent.dev/awesome-repo/logo.json.svg" />
+</a>
+
+
+<br/>
+<br/>
+
+<div align="center">
+    <strong>Curated collection of DESIGN.md analysis by developer focused websites.</strong>
+    <br />
+    <br />
+
+</div>
+
+<div align="center">
+
+[![Awesome](https://awesome.re/badge.svg)](https://awesome.re)
+![DESIGN.md Count](https://img.shields.io/badge/DESIGN.md%20count-73-10b981?style=classic)
+[![Last Update](https://img.shields.io/github/last-commit/VoltAgent/awesome-design-md?label=Last%20update&style=classic)](https://github.com/VoltAgent/awesome-design-md)
+[![Discord](https://img.shields.io/discord/1361559153780195478.svg?label=&logo=discord&logoColor=ffffff&color=7389D8&labelColor=6A7EC2)](https://s.voltagent.dev/discord)
+
+</div>
+</div>
+
+# Awesome DESIGN.md
+
+Copy a DESIGN.md into your project, tell your AI agent “build me a page that looks like this,” and generate high-quality UI that stays visually consistent with the design language.
+
+Built with real design depth — including analyzed patterns, tokens, and rules — for high-quality UI generation, not surface-level outputs.
+
+
+## What is DESIGN.md?
+
+[DESIGN.md](https://stitch.withgoogle.com/docs/design-md/overview/) is a new concept introduced by Google Stitch. A plain-text design system document that AI agents read to generate consistent UI.
+
+It's just a markdown file. No Figma exports, no JSON schemas, no special tooling. Drop it into your project root and any AI coding agent or Google Stitch instantly understands how your UI should look. Markdown is the format LLMs read best, so there's nothing to parse or configure.
+
+| File | Who reads it | What it defines |
+|------|-------------|-----------------|
+| `AGENTS.md` | Coding agents | How to build the project |
+| `DESIGN.md` | Design agents | How the project should look and feel |
+
+**This repo provides ready-to-use DESIGN.md files** extracted from real websites. 
+
+## Request a DESIGN.md
+
+You can [request a DESIGN.md](https://getdesign.md/request) for specific website, including private requests delivered exclusively to you.
+
+## AI Design + Build Ecosystem Tools
+
+
+<br/>
+
+You ship products with AI, but every launch still dies quietly because nobody posts about it. [EveryFeed](https://everyfeed.ai/) plugs your AI assistant into a social workspace that drafts, schedules, and publishes across 35+ channels — no agency, no marketing hire.
+
+<a href="https://everyfeed.ai/">
+<img src="https://cdn.voltagent.dev/awesome-repo/everyfeed-social.png" alt="everyfeed"  /><br/>
+</a>
+
+<br/>
+<br/>
+
+Stop building from a blank page. [LaunchKit](https://launchkit.getdesign.md/) gives your AI coding assistant a complete, working product to start from — websites, startups, and web apps that are clickable on day one.
+
+<a href="https://launchkit.getdesign.md/">
+<img src="https://cdn.voltagent.dev/awesome-repo/new-launchkit.png" alt="launchkit"  /><br/>
+</a>
+
+<br/>
+
+<div align="center">
+
+<table>
+<tr>
+<td align="center" width="100%">
+
+<h4>👉 Feature your product alongside the developers, designers, and vibecoders shipping UI with AI coding agents and web builders.</h4>
+
+<sub>Ranked #150 globally on GitHub. A community resource used by developers, designers, and vibecoders.</sub>
+
+<a href="https://sponsors.voltagent.dev/#awesome-design-md"><img src="https://img.shields.io/badge/📩_Become_a_Sponsor-Contact_Us-blue?style=for-the-badge&logoColor=white" alt="Become a Sponsor" /></a>
+
+
+</td>
+</tr>
+</table>
+
+</div>
+
+
+
+
+
+
+## Collection
+
+### AI & LLM Platforms
+
+- [**Claude**](https://getdesign.md/claude/design-md) - Anthropic's AI assistant. Warm terracotta accent, clean editorial layout
+- [**Cohere**](https://getdesign.md/cohere/design-md) - Enterprise AI platform. Vibrant gradients, data-rich dashboard aesthetic
+- [**ElevenLabs**](https://getdesign.md/elevenlabs/design-md) - AI voice platform. Dark cinematic UI, audio-waveform aesthetics
+- [**Minimax**](https://getdesign.md/minimax/design-md) - AI model provider. Bold dark interface with neon accents
+- [**Mistral AI**](https://getdesign.md/mistral.ai/design-md) - Open-weight LLM provider. French-engineered minimalism, purple-toned
+- [**Ollama**](https://getdesign.md/ollama/design-md) - Run LLMs locally. Terminal-first, monochrome simplicity
+- [**OpenCode AI**](https://getdesign.md/opencode.ai/design-md) - AI coding platform. Developer-centric dark theme
+- [**Replicate**](https://getdesign.md/replicate/design-md) - Run ML models via API. Clean white canvas, code-forward
+- [**Runway**](https://getdesign.md/runwayml/design-md) - AI creative-tools platform with an editorial film-festival aesthetic — cinematic dark heroes, paper-white reading bands, single proprietary sans, and pure black pill CTAs.
+- [**Together AI**](https://getdesign.md/together.ai/design-md) - Open-source AI infrastructure. Technical, blueprint-style design
+- [**VoltAgent**](https://getdesign.md/voltagent/design-md) - AI agent framework. Void-black canvas, emerald accent, terminal-native
+- [**xAI**](https://getdesign.md/x.ai/design-md) - Elon Musk's AI lab. Stark monochrome, futuristic minimalism
+
+### Developer Tools & IDEs
+
+- [**Cursor**](https://getdesign.md/cursor/design-md) - AI-first code editor. Sleek dark interface, gradient accents
+- [**Expo**](https://getdesign.md/expo/design-md) - React Native platform. Dark theme, tight letter-spacing, code-centric
+- [**Lovable**](https://getdesign.md/lovable/design-md) - AI full-stack builder. Playful gradients, friendly dev aesthetic
+- [**Raycast**](https://getdesign.md/raycast/design-md) - Productivity launcher. Sleek dark chrome, vibrant gradient accents
+- [**Superhuman**](https://getdesign.md/superhuman/design-md) - Fast email client. Premium dark UI, keyboard-first, purple glow
+- [**Vercel**](https://getdesign.md/vercel/design-md) - Frontend deployment platform. Black and white precision, Geist font
+- [**Warp**](https://getdesign.md/warp/design-md) - Modern terminal. Dark IDE-like interface, block-based command UI
+
+### Backend, Database & DevOps
+
+- [**ClickHouse**](https://getdesign.md/clickhouse/design-md) - Fast analytics database. Yellow-accented, technical documentation style
+- [**Composio**](https://getdesign.md/composio/design-md) - Tool integration platform. Modern dark with colorful integration icons
+- [**HashiCorp**](https://getdesign.md/hashicorp/design-md) - Infrastructure automation. Enterprise-clean, black and white
+- [**MongoDB**](https://getdesign.md/mongodb/design-md) - Document database. Green leaf branding, developer documentation focus
+- [**PostHog**](https://getdesign.md/posthog/design-md) - Product analytics. Playful hedgehog branding, developer-friendly dark UI
+- [**Sanity**](https://getdesign.md/sanity/design-md) - Headless content platform with a dark-first editorial marketing surface — 112px display type, IBM Plex Mono technical eyebrows, and a single coral-red accent reserved for the highest-priority CTA.
+- [**Sentry**](https://getdesign.md/sentry/design-md) - Error monitoring. Dark dashboard, data-dense, pink-purple accent
+- [**Supabase**](https://getdesign.md/supabase/design-md) - Open-source Firebase alternative. Dark emerald theme, code-first
+
+### Productivity & SaaS
+
+- [**Cal.com**](https://getdesign.md/cal/design-md) - Open-source scheduling. Clean neutral UI, developer-oriented simplicity
+- [**Intercom**](https://getdesign.md/intercom/design-md) - Customer messaging. Friendly blue palette, conversational UI patterns
+- [**Linear**](https://getdesign.md/linear.app/design-md) - Project management for engineers. Ultra-minimal, precise, purple accent
+- [**Mintlify**](https://getdesign.md/mintlify/design-md) - Documentation platform. Clean, green-accented, reading-optimized
+- [**Notion**](https://getdesign.md/notion/design-md) - All-in-one workspace. Warm minimalism, serif headings, soft surfaces
+- [**Resend**](https://getdesign.md/resend/design-md) - Email API for developers. Minimal dark theme, monospace accents
+- [**Zapier**](https://getdesign.md/zapier/design-md) - Automation platform. Warm orange, friendly illustration-driven
+
+### Design & Creative Tools
+
+- [**Airtable**](https://getdesign.md/airtable/design-md) - Spreadsheet-database hybrid. Colorful, friendly, structured data aesthetic
+- [**Clay**](https://getdesign.md/clay/design-md) - Creative agency. Organic shapes, soft gradients, art-directed layout
+- [**Figma**](https://getdesign.md/figma/design-md) - Collaborative design tool. Vibrant multi-color, playful yet professional
+- [**Framer**](https://getdesign.md/framer/design-md) - Website builder. Bold black and blue, motion-first, design-forward
+- [**Miro**](https://getdesign.md/miro/design-md) - Visual collaboration. Bright yellow accent, infinite canvas aesthetic
+- [**Webflow**](https://getdesign.md/webflow/design-md) - Visual web builder. Blue-accented, polished marketing site aesthetic
+
+### Fintech & Crypto
+
+- [**Binance**](https://getdesign.md/binance/design-md) - Crypto exchange. Bold Binance Yellow on monochrome, trading-floor urgency
+- [**Coinbase**](https://getdesign.md/coinbase/design-md) - Crypto exchange. Clean blue identity, trust-focused, institutional feel
+- [**Kraken**](https://getdesign.md/kraken/design-md) - Crypto trading platform. Purple-accented dark UI, data-dense dashboards
+- [**Mastercard**](https://getdesign.md/mastercard/design-md) - Global payments network. Warm cream canvas, orbital pill shapes, editorial warmth
+- [**Revolut**](https://getdesign.md/revolut/design-md) - Digital banking. Sleek dark interface, gradient cards, fintech precision
+- [**Stripe**](https://getdesign.md/stripe/design-md) - Payment infrastructure. Signature purple gradients, weight-300 elegance
+- [**Wise**](https://getdesign.md/wise/design-md) - International money transfer. Bright green accent, friendly and clear
+
+### E-commerce & Retail
+
+- [**Airbnb**](https://getdesign.md/airbnb/design-md) - Travel marketplace. Warm coral accent, photography-driven, rounded UI
+- [**Meta**](https://getdesign.md/meta/design-md) - Tech retail store. Photography-first, binary light/dark surfaces, Meta Blue CTAs
+- [**Nike**](https://getdesign.md/nike/design-md) - Athletic retail. Monochrome UI, massive uppercase Futura, full-bleed photography
+- [**Shopify**](https://getdesign.md/shopify/design-md) - E-commerce platform. Dark-first cinematic, neon green accent, ultra-light display type
+- [**Starbucks**](https://getdesign.md/starbucks/design-md) - Coffee retail flagship. Four-tier earth-green system, warm cream canvas, proprietary SoDoSans typography
+
+### Media & Consumer Tech
+
+- [**Apple**](https://getdesign.md/apple/design-md) - Consumer electronics. Premium white space, SF Pro, cinematic imagery
+- [**HP**](https://getdesign.md/hp/design-md) - PC and printer maker. Pure white canvas, HP Electric Blue signal CTA, geometric Forma DJR Micro, blue chevron decorations
+- [**IBM**](https://getdesign.md/ibm/design-md) - Enterprise technology. Carbon design system, structured blue palette
+- [**NVIDIA**](https://getdesign.md/nvidia/design-md) - GPU computing. Green-black energy, technical power aesthetic
+- [**Pinterest**](https://getdesign.md/pinterest/design-md) - Visual discovery platform. Red accent, masonry grid, image-first
+- [**PlayStation**](https://getdesign.md/playstation/design-md) - Gaming console retail. Three-surface channel layout, cyan hover-scale interaction
+- [**SpaceX**](https://getdesign.md/spacex/design-md) - Space technology. Stark black and white, full-bleed imagery, futuristic
+- [**Spotify**](https://getdesign.md/spotify/design-md) - Music streaming. Vibrant green on dark, bold type, album-art-driven
+- [**The Verge**](https://getdesign.md/theverge/design-md) - Tech editorial media. Acid-mint and ultraviolet accents, Manuka display type
+- [**Uber**](https://getdesign.md/uber/design-md) - Mobility platform. Bold black and white, tight type, urban energy
+- [**Vodafone**](https://getdesign.md/vodafone/design-md) - Global telecom brand. Monumental uppercase display, Vodafone Red chapter bands
+- [**WIRED**](https://getdesign.md/wired/design-md) - Tech magazine. Paper-white broadsheet density, custom serif, ink-blue links
+
+### Automotive
+
+- [**BMW**](https://getdesign.md/bmw/design-md) - Luxury automotive. Dark premium surfaces, precise German engineering aesthetic
+- [**BMW M**](https://getdesign.md/bmw-m/design-md) - Performance automotive. Motorsport-inspired contrast, M color accents, precision-driven layout
+- [**Bugatti**](https://getdesign.md/bugatti/design-md) - Luxury hypercar. Cinema-black canvas, monochrome austerity, monumental display type
+- [**Ferrari**](https://getdesign.md/ferrari/design-md) - Luxury automotive. Chiaroscuro black-white editorial, Ferrari Red with extreme sparseness
+- [**Lamborghini**](https://getdesign.md/lamborghini/design-md) - Luxury automotive. True black cathedral, gold accent, LamboType custom Neo-Grotesk
+- [**Renault**](https://getdesign.md/renault/design-md) - French automotive. Vivid aurora gradients, NouvelR proprietary typeface, zero-radius buttons
+- [**Tesla**](https://getdesign.md/tesla/design-md) - Electric vehicles. Radical subtraction, cinematic full-viewport photography, Universal Sans
+
+### Retro Web · DESIGN.md Nostalgia
+
+A Saturday series — DESIGN.md files extracted from the web of the 1990s. Drop one in and tell your AI agent to build a period-accurate vintage UI.
+
+- [**Dell (1996)**](https://getdesign.md/dell-1996/design-md) - Catalog-era enterprise web. Literal black page frame, flat color-block "ribbon cards", chunky Helvetica-Black titles over Times Roman body, and hand-cut GIF stickers (NEW! bursts, award seals, beveled product photos).
+- [**Nintendo.com (2001)**](https://getdesign.md/nintendo-2001/design-md) - Y2K "console chrome" web. Brushed-periwinkle beveled metal panels, a halftone-dotted carbon nav glowing amber, outlined Arial-Black box-art wordmarks over circuit-board hero fields, and a pixel Mario welcome bubble.
+
+
+## What's Inside Each DESIGN.md
+
+Every file follows the [Stitch DESIGN.md format](https://stitch.withgoogle.com/docs/design-md/specification/) with extended sections:
+
+| # | Section | What it captures |
+|---|---------|-----------------|
+| 1 | Visual Theme & Atmosphere | Mood, density, design philosophy |
+| 2 | Color Palette & Roles | Semantic name + hex + functional role |
+| 3 | Typography Rules | Font families, full hierarchy table |
+| 4 | Component Stylings | Buttons, cards, inputs, navigation with states |
+| 5 | Layout Principles | Spacing scale, grid, whitespace philosophy |
+| 6 | Depth & Elevation | Shadow system, surface hierarchy |
+| 7 | Do's and Don'ts | Design guardrails and anti-patterns |
+| 8 | Responsive Behavior | Breakpoints, touch targets, collapsing strategy |
+| 9 | Agent Prompt Guide | Quick color reference, ready-to-use prompts |
+
+Each site includes:
+
+| File | Purpose |
+|------|---------|
+| `DESIGN.md` | The design system (what agents read) |
+| `preview.html` | Visual catalog showing color swatches, type scale, buttons, cards |
+| `preview-dark.html` | Same catalog with dark surfaces |
+
+### How to Use
+
+
+1. Copy a site's `DESIGN.md` into your project root
+2. Tell your AI agent to use it.
+
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+- **Improve existing files**: Fix wrong colors, missing tokens, weak descriptions
+- **Report issues**: Let us know if something looks off
+
+Before opening a PR, please [open an issue](https://github.com/VoltAgent/awesome-design-md/issues) first to discuss your idea and get feedback from maintainers.
+
+
+## License
+
+MIT License - see [LICENSE](LICENSE)
+
+This repository is a curated collection of design system documents extracted from public websites. All DESIGN.md files are provided "as is" without warranty. The extracted design tokens represent publicly visible CSS values. We do not claim ownership of any site's visual identity. These documents exist to help AI agents generate consistent UI.

package/skills/ai-delivery-orchestrate/assets/project-template/ref/ui/UPSTREAM.yaml

@@ -0,0 +1,19 @@
+schema_version: 1
+library_id: AWESOME-DESIGN-MD-2026-08-10
+name: awesome-design-md
+source_repository: https://github.com/VoltAgent/awesome-design-md
+source_commit: 8147538b4226ae41e2487a9179e3bcc1f68e8554
+source_readme_sha256: cc7d7e77d4a46f1843cef38d8e4dbcea5c06e16440a8dfa9c3d87ff8f396b6c0
+license: MIT
+license_ref: LICENSE
+license_sha256: 6d4bdc9a9cf30e7beb593475fdcdbf29f981ea6bd7923f202866145409f87b44
+imported_at: 2026-08-10
+imported_paths:
+  - README.md
+  - CONTRIBUTING.md
+  - design-md/
+omitted_upstream_paths:
+  - .github/
+  - .gitignore
+local_additions:
+  - UPSTREAM.yaml