面向 Codex 与 Claude Code 的轻量原生插件工作流：
Design 讨论与记录 → 独立 Design Review → 最终审阅 → 授权 Act 或确认无需实施 → Review / 归档
它解决三个常见问题：意图和边界尚未清楚就开始实现；实施遇到歧义时 agent 静默替用户选择；声明、文件或测试存在，却没有接入真实生产调用链。
$agent-workflow-kit:design：唯一显式入口；调查真实仓库、持续记录 Design，并在候选 Ready 后派独立只读 subagent 审查成品。探索结论可以在用户确认后以无需实施归档，不强迫制造代码改动。$agent-workflow-kit:act：用户在最终 Design 的合并审阅门禁中无保留接受后，携带当前design.md的确切路径直接进入；该授权在同一工作流的 Act↔Design 修订中持续有效，复审通过后自动恢复原 Act，不再请求实施授权。首次授权前，脱离门禁语境的普通实现请求或泛化“继续”不得触发 Act。$agent-workflow-kit:review：简单改动由一个 reviewer 完成；两个以上独立高影响主张先并行核验，再由一个 reviewer 在同一工作区整合真实调用链与最终结论。
工作流不得按任务特征自动启动；只有用户显式调用 $agent-workflow-kit:design 才进入，此后自动推进，不增加 Plan 或同义实施确认。
Claude Code 的交互式命令使用 /agent-workflow-kit:design 等同名 namespaced skill。没有 $workflow-* 兼容入口，也没有 kit 自建的 doctor；宿主环境分别使用 codex doctor 与 claude doctor。
Codex：
codex plugin marketplace add Redwarx008/agent-workflow-kit --ref main
codex plugin add agent-workflow-kit@agent-workflow-kitClaude Code：
claude plugin marketplace add Redwarx008/agent-workflow-kit
claude plugin install agent-workflow-kit@agent-workflow-kit插件安装进入宿主版本化 cache。安装、升级或修改插件后，请开启一个新 task/session，避免旧上下文继续使用先前 skill。
更新：
codex plugin marketplace upgrade agent-workflow-kit
codex plugin add agent-workflow-kit@agent-workflow-kit
claude plugin marketplace update agent-workflow-kit
claude plugin update agent-workflow-kit@agent-workflow-kit标准安装、升级、禁用和卸载由宿主原生命令负责；本仓库不复制平台包管理器。
如果项目里仍有手工复制的旧 $workflow-* skills，请先人工确认这些目录没有用户修改，再自行删除。插件不会扫描、认领或清理消费项目文件。
安装插件即可提供工作流入口；无需把本仓库的 AGENTS.md 复制到消费项目。目标项目自己的规则和用户明确要求始终优先。
Design 开始前会运行 bundled preflight：在 Git 项目的 repo-local .git/info/exclude 中幂等确保 /workflow/ 被忽略，然后才允许创建记录。design.md 是总览与入口；小改在其中完成，多领域设计使用 areas/<area-name>.md。Act 和 Review 按 Design 文档契约读取，归档时移动整个变更目录。所有 Design 文件保持本地，工具临时状态进入 workflow/.local/，不会要求修改项目的 tracked .gitignore。
Act 把实施交给 worker 角色，Design 与 Act 的审查都交给 reviewer 角色；角色缺失时工作流停止并报告，不退回主会话自行实施或审查。插件不内置角色定义，模型与推理强度由用户在宿主配置中决定：
| 宿主 | 位置 | 示例字段 |
|---|---|---|
| Codex | ~/.codex/agents/worker.toml、reviewer.toml |
model、model_reasoning_effort、sandbox_mode |
| Claude Code | ~/.claude/agents/worker.md、reviewer.md（或项目 .claude/agents/） |
frontmatter 的 model、effort、disallowedTools |
worker 需要写权限且不得再委托；reviewer 只读且不得再委托。探索仍使用宿主的只读探索子代理，不要求指定角色。
仓库只维护直接保护插件契约与 bundled 工具安全边界的检查：
npm ci
npm test
npm run check
npm run test:visual
npm run test:visual:powershellnpm test 覆盖 manifest/skill 契约和 Design preflight；npm run check 只检查当前仓库，不探测宿主 CLI、cache 或消费项目。Visual Companion 保留独立的鉴权、文件边界和进程生命周期回归。真实插件安装与升级使用宿主原生命令，发布时另开 fresh task 做针对性 smoke test。
design skill 包含一个 MIT 派生的本地浏览器 Visual Companion。它只在视觉问题真正受益且用户同意后启动；浏览器展示和记录选择，终端对话仍负责最终确认和授权。
cd .agents/skills/design/scripts/visual-companion
npm --prefix tests ci
npm test
npm run test:powershell它派生自 obra/superpowers v6.1.1，保留上游 MIT 许可证与来源记录。
- 事实由 agent 从真实项目和适用参考实现调查，无法从证据推导的取舍才交给用户。
- 当前代码、配置或资源样本、可复现估算、外部事实与目标设计保持清晰边界。
- Design 自然地一次处理一个真实决定；具体代码目标同时展示带来源的当前代码和紧凑目标示意，受影响的结构关系用必要的树或图说明。
- Design 只保存用户所选交付范围的最小充分最终结果；Act 自行安排不改变设计的机械执行顺序。
- 实施中的材料冲突或实质选择必须停下询问，不能用默认值、fallback 或替代验证绕过。
- 独立 Review 从最终 Design 反查真实生产路径和一般规则；长期知识只按目标项目自己的门槛沉淀。
进一步说明见 工作流哲学、验证策略、独立 Review、会话记忆 和 参考实现取舍。
- Design 编排：design/SKILL.md；详细流程与内容契约位于其
references/。 - Act 编排：act/SKILL.md；执行、疑问、worktree、验证与收尾规则位于其
references/。 - Review 编排：review/SKILL.md；唯一详细审查规则为 review-contract.md。
运行时行为以上述 skill 源为准。README 与 docs/ 只解释用法和设计理由，不建立额外门禁。
仓库主体使用 MIT License。Visual Companion 的上游版权和许可证位于其 bundled source 目录。