# 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

```bash
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:

```bash
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](AGENT_GUIDE.md) for the fixed Agent workflow.

## 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](SECURITY.md) and [CONTRIBUTING.md](CONTRIBUTING.md).