Golden Flow Engine

Agent-neutral engine for building, validating, and running a project-specific Golden Pack. It gives Codex, OpenClaw, and other desktop Agents a deterministic foundation for understanding a repository, designing its own golden flows, collecting evidence, resuming long runs, and maintaining those flows with the product.

The Engine is not a hard-coded HTTP test runner and does not call any LLM. The host Agent reads the project and writes .golden-flow/; the Engine provides facts, safe tools, validation, and execution.

Quick start

python -m pip install -e ".[mcp]"
golden-flow inspect /path/to/project
golden-flow init /path/to/project
golden-flow validate /path/to/project
golden-flow plan /path/to/project
golden-flow run /path/to/project --mode strict

Background mode uses a project-local SQLite queue:

golden-flow job-start /path/to/project
golden-flow worker /path/to/project --once
golden-flow job-status /path/to/project JOB_ID

Run golden-flow-mcp to expose inspection, Pack management, planning, and asynchronous run tools over STDIO MCP. See AGENT_GUIDE.md for the fixed Agent workflow.

Related MCP server: agent-orchestrator

Built-in adapters

• file: project-root-limited reads, listing, hashes, and existence checks.

• shell: argv commands explicitly registered in policies/safety.yaml.

• http: requests and response evidence using the Python standard library.

• playwright: optional browser navigation, input, screenshots, and console errors.

• sql-observer: read-only SQLite observation; writes, pragmas, and multi-statements are rejected.

• minium: optional WeChat mini-program capability with protocol Mock mode for CI.

• command-bridge: one-JSON-in/one-JSON-out bridge for TypeScript, Java, Go, and custom tools.

The adapter protocol keeps capabilities, preflight, execution, evidence, safety checks, error classes, and resource closing independent from the Engine core.

中文说明

golden-flow-engine 是给 Codex、OpenClaw/龙虾及其他桌面 Agent 使用的“项目黄金流程构建与运行引擎”。它先对仓库做确定性只读扫描，再由宿主 Agent 根据文档、代码、页面、状态模型和数据真相源，为该项目编写 .golden-flow/。Engine 负责目录格式、依赖拓扑、工具安全、证据完整性、前台/后台执行、断点结果和错误分类，不预置任何真实产品业务，也不内置模型 API。

默认提交项目画像、主干/分支清单、Python Journey、工具声明、策略和 Fixture 规则；默认忽略账号、Token、SQLite 运行状态、截图、日志、报告、缓存和真实业务资料。

Status

v0.1.0 is an alpha release. The protocol and schema names are versioned, but APIs may evolve before v1. Real Minium acceptance remains a documented manual smoke test on Windows with WeChat DevTools; ordinary CI uses the protocol Mock.

MIT licensed. See SECURITY.md and CONTRIBUTING.md.