Dev Agent OPC

Automatic Dev Agent from idea → spec → design → build → QA → ship
面向 OPC 与小型业务团队的精简自动化开发 Agent 工作流

中文 · English · 使用方式 · Usage

由 Kevin KE / laoke.ai 创建和维护，并与 Codex-5.5 协作完成。
Created and maintained by Kevin KE / laoke.ai, worked with Codex-5.5.

---

中文

Dev Agent OPC 是一套给 AI Coding Agent 使用的精简交付工作流。它把模糊想法推进到可验证输出：idea → spec → design → build → QA → ship。其中 QA 和 ship 默认可选，重点是先高效完成正确的 build 输出，再按需要增加质量证明和发布检查。

定位与价值

• 精简生命周期：Spec 合并 PRD/产品范围，Build 内部完成必要的轻量任务拆解，去掉默认 PDCA 支流。
• 不硬干：发现需求、设计、环境、权限或安全风险不足时，回到上一级 flow 或让用户决策。
• 设计更稳：Design 不强制草图或原型；先问用户是否有参考，没有则基于 Spec 评估设计方案。高保真实现才要求 AI 可读的正式设计资产。
• Build 优先：Build 先判断需求/spec 清晰度、功能架构、design 资源和环境需求，再进入 coding。
• QA 可选：功能/monkey/视觉 QA 可由项目开关或用户要求开启，避免每次都生成重文档。

使用方式

安装后，从主入口开始：

/dev agent

常见调用：

/dev agent 帮我把这个产品想法梳理成 PRD 和 SPEC，然后进入 build。
/dev agent 这是一个 UI 项目，先检查 design 是否足够支持高保真实现。
/dev agent next my-project
/dev agent flow build my-project
/dev agent flow qa my-project

bin/dev-flow 是唯一执行导航器。已有项目不要先通读 Markdown；先运行：

bin/dev-flow status <project-name>
bin/dev-flow next <project-name>

然后只读取 next 返回的 command、skill、references 和项目文件。

本地使用：

bin/dev-flow init <project-name> --type ui
bin/dev-flow status <project-name>
bin/dev-flow next <project-name>
bin/dev-flow autonomy <project-name>
bin/dev-flow delegate <project-name>
bin/dev-flow ui-polish <project-name>
bin/dev-flow phase <project-name> spec "Write PRD and SPEC"
bin/dev-flow phase <project-name> build "Build the first slice"

安装与更新

git clone https://github.com/KevinKE93/Dev_Agent_OPC.git
cd Dev_Agent_OPC

bin/dev-flow install codex --scope user
bin/dev-flow install claude-code --scope user

支持的 host：codex、claude-code、gemini、openclaw、opencode。

更新：

cd "/path/to/Dev_Agent_OPC"
git pull --ff-only
bin/dev-flow install codex --scope user
bin/dev-flow install claude-code --scope user

流程管控

• 主阶段：idea、spec、design、build、qa、ship。
• 目录边界：.dev-agent/ 存放 spec、design、tasks、reviews 等过程文件；项目根目录存放真实代码、配置和开发产物。
• 精简职责：产品/PRD 与 agent contract 归入 Spec；轻量计划和 proof-first 归入 Build；测试与 review 归入 QA/Ship。
• Idea 归因：idea brief 记录用户明确需求、agent 推断、产品决策和待确认项，避免后续 spec 混淆来源。
• Spec 门禁：UI 项目的 PRD 需覆盖 MVP、核心流程/IA、验收和非目标；SPEC 需覆盖技术栈、命令、数据/领域模型、测试、UI/design 适用性、隐私/安全和未决问题。
• 设计实现方式：正式设计交付以 design-artifacts 中的 HTML/CSS design package 合同为准，用高保真 HTML/CSS 和必要的 CSS/JS/Lottie 动效作为实现目标，提高还原度、验收效率和代码生成效率。
• 设计门禁：customer-facing UI 在 build 前运行 design-check；没有参考时需用户委托视觉方向或提供参考；logo、app icon、品牌 KV 和高质量位图素材必须有 Image Gen / GPT Image 来源。
• 环境边界：宿主机 SDK、模拟器、MCP、凭证和系统服务记录在 HOST_REQUIREMENTS.md，不混入项目 runtime。
• 自主循环：AUTONOMY_LOOP 默认给出 heartbeat 建议；遇到 blocker、高风险审批或最终阶段已验证时停止。
• Subagent 并行：SUBAGENTS 默认给出可并行任务包；host 支持时可把 explorer、worker、verifier 等侧线任务交给子 agent。
• UI 打磨预算：runtime visual pass 默认一次；P0/P1 阻塞当前任务，P2/P3 记录到 UI_DEBT.md 后继续推进。
• QA 开关：AUTOMATED_QA="required" 开启功能/monkey QA；VISUAL_QA="required" 开启视觉 QA。

发布日志

• v0.9：新增 HTML/CSS 设计稿实现方式作为正式设计交付标准，提升 UI 还原度、验收效率和代码生成效率；优化未初始化项目的目录创建，避免在项目根目录生成空的过程文件夹。
• v0.8：新项目默认把过程管理文件放在 .dev-agent/，开发产出的代码和项目文件保留在项目根目录；migrate 可迁移旧 .dev-flow / root-level 过程目录。
• v0.7：强化 idea/spec 工作流；idea brief 增加需求归因表；Spec 明确 PRD 与 SPEC 分工、产品域展开清单、外部参考吸收规则，并为 UI 项目增加最小 spec 覆盖门禁。
• v0.6：收敛为 idea → spec → design → build → QA → ship；Spec 合并 PRD 和 agent contract；Build 合并轻量计划与 proof-first；QA/Ship 默认可选；移除默认 PDCA 支流。
• v0.5：支持 native 安装，并可在对话中通过 /dev agent 直接调用 Dev Agent；稳定 ID 为 dev-agent，保留 /dev-agent 作为兼容别名。
• v0.4：增加 schema v4、可选 QA/Ship、正式设计资产按需门禁，以及 AGENT_CONTRACT。
• v0.3：增加宿主机环境合同、env-check、schema v3，以及 host SDK / project dependency / runtime artifact 的边界。

---

English

Dev Agent OPC is a lean delivery workflow for AI coding agents. It moves rough ideas into verifiable output through idea → spec → design → build → QA → ship. QA and ship are optional by default, so the workflow can reach correct build output quickly before adding heavier validation or launch work.

Positioning And Value

• Lean lifecycle: Spec folds in product/PRD scope, Build handles lightweight task slicing, and PDCA is no longer a default branch.
• Escalate instead of forcing: unclear requirements, weak design inputs, missing host permissions, unavailable SDKs, and high-risk decisions route back to the owning flow or the user.
• Cleaner design path: Design does not require sketches or prototypes. Ask for references first; if none exist, evaluate direction from the spec or ask for delegated visual direction.
• Build first: Build starts by checking requirement clarity, architecture, design readiness, and environment needs, then codes the smallest slice.
• Optional QA: functional, monkey, and visual QA run when the project or user requires them.

Usage

Installed entrypoint:

/dev agent

Examples:

/dev agent Turn this product idea into PRD + SPEC, then continue to build.
/dev agent This is a UI project. Check whether design is enough for high-fidelity implementation.
/dev agent next my-project
/dev agent flow build my-project
/dev agent flow qa my-project

bin/dev-flow is the only execution navigator. For an existing project, do not start by reading Markdown broadly. Run:

bin/dev-flow status <project-name>
bin/dev-flow next <project-name>

Then read only the command, skill, references, and project files named by next.

Local commands:

bin/dev-flow init <project-name> --type ui
bin/dev-flow status <project-name>
bin/dev-flow next <project-name>
bin/dev-flow autonomy <project-name>
bin/dev-flow delegate <project-name>
bin/dev-flow ui-polish <project-name>
bin/dev-flow phase <project-name> spec "Write PRD and SPEC"
bin/dev-flow phase <project-name> build "Build the first slice"

Install And Update

git clone https://github.com/KevinKE93/Dev_Agent_OPC.git
cd Dev_Agent_OPC

bin/dev-flow install codex --scope user
bin/dev-flow install claude-code --scope user

Supported hosts: codex, claude-code, gemini, openclaw, opencode.

Update:

cd "/path/to/Dev_Agent_OPC"
git pull --ff-only
bin/dev-flow install codex --scope user
bin/dev-flow install claude-code --scope user

Process Controls

• Primary phases: idea, spec, design, build, qa, ship.
• Directory boundary: .dev-agent/ stores process files such as specs, design, tasks, and reviews; the project root stores real code, config, and development output.
• Lean responsibilities: product/PRD and agent contracts live in Spec; micro-planning and proof-first checks live in Build; testing and review live in QA/Ship.
• Idea attribution: idea briefs record user-stated needs, agent inferences, product decisions, and open confirmations so later specs do not blur source boundaries.
• Spec gate: UI project PRDs must cover MVP, core flows/IA, acceptance, and non-goals; SPEC files must cover stack, commands, data/domain model, testing, UI/design applicability, privacy/security, and open questions.
• Design implementation format: formal design handoff follows the HTML/CSS design-package contract in design-artifacts; high-fidelity HTML/CSS plus CSS/JS/Lottie motion files are the preferred implementation target for better UI fidelity, review speed, and code-generation efficiency.
• Design gate: customer-facing UI runs design-check before build; missing references require user input or delegated visual direction; logo, app icon, brand KV, and high-quality bitmap assets require Image Gen / GPT Image provenance.
• Environment boundary: host SDKs, simulators, MCP servers, credentials, and services are recorded in HOST_REQUIREMENTS.md instead of project runtime output.
• Autonomy loop: AUTONOMY_LOOP suggests heartbeat continuation by default, and stops on blockers, high-risk approval, or verified final phases.
• Subagent parallelism: SUBAGENTS suggests optional task packets so host clients can delegate explorer, worker, and verifier work when supported.
• UI polish budget: runtime visual passes default to one; P0/P1 blocks the task, while P2/P3 goes to UI_DEBT.md and work advances.
• QA switches: AUTOMATED_QA="required" enables functional/monkey QA; VISUAL_QA="required" enables visual QA.

Release Notes

• v0.9: Adds HTML/CSS design packages as the formal design handoff format to improve UI fidelity, review efficiency, and code-generation efficiency; fixes directory creation for uninitialized projects so empty process folders are not created at the project root.
• v0.8: Defaults process-management files to .dev-agent/ while keeping development output and source files at the project root; migrate can move old .dev-flow and root-level process directories.
• v0.7: Strengthens the idea/spec workflow; adds requirement attribution to idea briefs; clarifies PRD/SPEC ownership, product-domain expansion, external-reference absorption, and minimum UI spec coverage gates.
• v0.6: Collapses the lifecycle to idea → spec → design → build → QA → ship; folds PRD and agent contracts into Spec; folds micro-planning and proof-first checks into Build; makes QA/Ship optional by default; removes the default PDCA branch.
• v0.5: Adds native installation and conversation-level invocation through /dev agent; the stable ID is dev-agent, with /dev-agent kept as a compatibility alias.
• v0.4: Adds schema v4, optional QA/Ship gates, demand-driven formal design assets, and AGENT_CONTRACT.
• v0.3: Adds the host environment contract, env-check, schema v3, and clear boundaries between host SDKs, project dependencies, and runtime artifacts.

---

License

MIT. See LICENSE.

Acknowledgements / 致谢

Based on and extending @AddyOsmani Agent Skills.