Codex Factory — Engineering Reliability Framework for AI Coding Agents

An engineering reliability layer for AI coding agents. Turn AI-assisted development from a long, fragile chat into a controlled workflow with task routing, trusted context, native subagents, and independent verification.

V5 自动控制平面 · 当前发布状态 · 快速开始 · 历史验证记录 · Architecture · Limitations

New here? → V5 中文安装与使用指南 · V5 CLI · Legacy Getting Started (V4, historical)

体验新增三条主线： 在 packages/factory-cli 执行 npm run demo:tour，离线查看“结果对比澄清 → 纠错经验复用 → 假设驱动排错”的三个独立案例。无需模型调用，输出可读摘要和完整日志；不是一次真实项目交付。见实用导览与触发场景。

30-second pitch: Codex Factory is a local control plane for developers who use Codex or Codex-compatible runtimes to build non-trivial software projects. It adds structured planning, role-bound skills, source-bound memory, optional native multi-agent execution, optional GLM search, and a verification layer that treats real files, command exit codes, hashes, and receipts as evidence. No artifact = no PASS. Your project knowledge stays local.

V5 自动控制平面 (Preview)

V5 把用户记忆中的多 Agent、外接 Conversation Space、GLM 搜索和防假通过路径重新接成一个可安装的本地控制平面。用户只选择功能开关；启用多 Agent 后，由 Codex 主 Agent 自动拆分、派发常驻角色、按需生成临时 Agent、等待/纠偏、续跑验证波次，不要求用户手工开窗口或复制 prompt。

Windows 一次安装：

Set-Location C:\Codex_App_Factory
powershell -ExecutionPolicy Bypass -File .\packages\factory-cli\install.ps1 `
  -ProjectRoot C:\Projects\my-app `
  -MultiAgent `
  -Search none `
  -MaxThreads 4

factoryctl doctor --project C:\Projects\my-app --json

关键边界：

默认继承当前 Codex runtime，GPT 用户可直接使用；兼容 Codex runtime 中的 DeepSeek 用户需以 doctor 和小型真实任务验证工具兼容性。
多 Agent、GLM 搜索均为 opt-in；搜索 Key 只从 ZHIPUAI_API_KEY 或项目本地、已忽略的 .codex-factory/secrets.env 读取。
只有带来源绑定准入回执的 trusted_context、独立验证证据和物理仓库才可作为工作依据；哈希链只证明写入后未被篡改。前端压缩摘要和普通手工追加内容保留为不可信候选。
Memory Quality V5.1 会按任务和角色自动检索当前、未被替代、来源未漂移的项目知识，并把带条目 ID、来源 SHA-256 的限长摘录绑定进子 Agent Packet。
常驻角色现在只持久化 profile/分工，每个 assignment 都使用新的 fork_turns=none 执行实例；9 个领域 Skill 按 capability 动态路由。
项目级 Codex Hooks 会在真实 Subagent 生命周期中校验 spawn、绑定 Host 返回的 Agent ID、检查 handoff，并在压缩后要求重新加载外部权威上下文。首次或 Hook 变化后仍需按 Codex 安全规则在 /hooks 审阅信任。
当前 scope_guard 会检测漏报和波次级越界写入，但不能提供逐 Agent 作者归因，也不是 OS ACL 或独立 worktree。因此开启多 Agent 时 doctor 会诚实返回 READY_WITH_LIMITATIONS。
原生 Codex 支持昵称候选；Factory 的角色 icon 可用于自己的记录/仪表盘，但不能控制原生子 Agent 头像。

完整命令、各功能用法、知识库、API Key、安全关闭和故障排查见 V5 中文指南。

开发任务现在使用统一流程：tasks validate 只读检查任务输入，首次 plan 生成派发计划；主 Agent 登记原生执行与交接后，由 run continue 执行就绪的独立验收并返回下一波计划，直至交付或失败停止。结果直接包含已验收产物与回执引用，不额外生成审计报告。CLI 不自行启动 Agent，也不自动重试失败任务。见开发任务从启动到交付。

失败恢复使用 repair prepare → 确认修复 → repair create → run continue：先只读汇总失败证据、冻结约束和上游输入，并指向已有修复，再进入受限重新执行。prepare 不改变验收标准，也不把非零退出码直接解释为代码缺陷。见修复准备流程。

[!IMPORTANT] 当前权威实现是 packages/factory-cli 中的 V5 Preview 源码，以及从该目录当前提交现场生成的 .tgz。dist/codex-factory-v4-capability-package.zip 的 ZIP、manifest 和 SHA 文本彼此不一致，已明确判定为无效历史制品，不能用于安装、发布或证明当前代码通过。详见旧制品告警。

新增的结果对比式澄清使用 clarify create → show → 用户选择 → choose → tasks validate/plan：主 Agent 用同一输入的不同预期结果帮助用户确认关键业务行为，选中的例子随任务进入实现和独立验收。CLI 负责记录与编译，不自行检测歧义或代替用户决定。见澄清流程与离线示例。

增量演进按三阶段推进：确认意图 → 从人工修正中提炼技能 → 改善修复与工作决策。第二阶段已支持 teach capture/draft/show/publish：从用户指定的单文件 Git 修改提炼有证据、适用条件和反例的候选 Skill，人工确认后发布到当前项目，不宣称模型训练或自动泛化。见路线图与教学流程。

第三阶段已支持 probe template/draft/show/observe：先声明两条候选原因及不同预测，再确认读取一个小型 JSON 诊断字段，为修复提供分支线索；不匹配时明确保留不确定性。它不自动运行实验、不证明根因、不消耗修复次数。源码目录执行 npm run demo:probe -- --observe-demo 可复跑离线闭环，见假设驱动排错说明。

流程衔接已补齐：teach apply 将一个已发布 Skill 附加到指定待执行任务，probe repair-plan 预览带诊断线索的任务，repair create --probe 直接接入原修复流程。原需求例子与验收合同保留，不再依赖手工复制证据；仍需正常审批，不自动判断技能适用性或启动 Agent。见任务衔接说明。

What is Codex Factory?

Codex Factory is an open engineering reliability framework for AI coding agents. It does not try to replace your coding agent or invent another model. Instead, it gives AI-assisted development the structure that real engineering work needs: clear task boundaries, specialist roles, trusted context, evidence capture, and independent verification.

Modern AI coding agents are powerful, but complex projects still expose predictable failure modes:

Generate code that looks right but has subtle bugs
Claim "done" with no evidence
Skip error states, loading states, and edge cases
Mix security concerns with UI concerns
Produce artifacts you cannot reproduce or verify

Codex Factory addresses this with a local control plane and verification pipeline — not by replacing the agent, but by surrounding it with the guardrails, evidence requirements, and reproducibility checks that professional software engineering demands.

A complex request can be decomposed into a task graph, routed to specialist profiles, executed through Codex native subagents when enabled, enriched with source-bound memory, and closed only after independent checks produce reproducible evidence.

Core Problem → Solution Map

Problem	Codex Factory Solution
Fake PASS — agent claims success, but nothing was verified	Physical artifact hashes, real command exit codes and an independent verifier
Missing artifacts — no stdout, no logs, no receipts	Immutable handoffs, verification receipts and evidence bundles
Weak evidence chain — "trust me, it works"	Hash-chained Context Space, admission receipts and source-bound evidence
Local results cannot be trusted — "works on my machine"	Current-commit Windows/Ubuntu CI matrix
Context compression pollution	External role-bound Context Packets; frontend summaries stay untrusted
No reproducibility	Locked dependencies, deterministic build and package-content audit

Current Release and Evidence Status

V5 Preview is the current maintained path. The repository does not treat a report from another commit, a hand-written manifest, or an Agent's statement as proof for the current checkout.

Item	Current status
Authoritative source	`packages/factory-cli`
Install guide	`docs/CONTROL_PLANE_V5_GUIDE.zh-CN.md`
Reproducible package candidate	Run `npm pack` in `packages/factory-cli`; use the `.tgz` generated from the commit being tested
Cross-platform CI definition	`factory-cli-v5.yml`, Node 24 on Windows and Ubuntu
Verified V5 code snapshot	Commit `14684e7`, CI run 34944225959: Windows 202 tests passed; Ubuntu 201 passed, 1 Windows-only test skipped; all three jobs passed; verified preview artifacts retained for 30 days
Legacy V4 ZIP	INVALID / archive only; see `LEGACY-ARTIFACTS-INVALID.md`
Historical PASS reports	Evidence for their recorded commit/run only; they do not automatically certify current HEAD or V5

Verify the current checkout before using or distributing it:

Set-Location C:\Codex_App_Factory\packages\factory-cli
npm ci
npm run typecheck
npm run eval:typecheck
npm test
npm run build
npm pack --dry-run
npm run test:package

A successful local run proves only that checkout on that machine. A current GitHub Actions run on both matrix platforms is required before making a cross-platform claim.

The recorded V5 run also passed build, package-content checks and actual offline tarball installation on both platforms, plus the Windows legacy compatibility regressions. The Windows teaching-root regression found in the preceding run was fixed in 768be48. The current results are bound to verified snapshot 14684e7; they do not establish live Agent performance gains, trusted Hook installation, or a public npm release. See the V5 preview handoff for installation and verification, and the release decision for remaining blockers.

V5 Quick Start

Prerequisites: Git, Node.js 24+, npm, and a Codex runtime that supports project-level customization.

git clone https://github.com/yueheng-rgb/codex-factory.git C:\Codex_App_Factory
Set-Location C:\Codex_App_Factory
powershell -ExecutionPolicy Bypass -File .\packages\factory-cli\install.ps1 `
  -ProjectRoot C:\Projects\my-app `
  -MultiAgent `
  -Search none `
  -MaxThreads 4

factoryctl doctor --project C:\Projects\my-app --json
factoryctl memory status --project C:\Projects\my-app --json

For optional GLM search, initialize with -Search glm and provide ZHIPUAI_API_KEY through the documented environment or ignored project secret file. Do not put an API key in Factory configuration or commit it.

Factory does not implement or certify a DeepSeek provider. It inherits the model/runtime selected in Codex. A developer whose Codex runtime is already compatible with DeepSeek can use Factory, but must verify model access, tool calls and a small real task in that runtime; selecting or writing a deepseek label is not proof of compatibility.

See the V5 Chinese guide for feature switches, multi-Agent dispatch, Context Space, skills, knowledge, search, verification, and uninstall steps.

Historical Verified Results (V3.4.2, commit-scoped)

The following records describe a historical GitHub Actions run. They are retained for traceability, not presented as current release certification.

Check	Recorded result
Snapshot Verifier	`15/15 PASS`, `SNAPSHOT_VERIFIED`
products-api Regression	`23/23 PASS`
Frozen Trunk Check	`3/3 OK`
Classification	`V3_4_2_REMOTE_ARTIFACT_VERIFIED_STRICT`

Recorded scope: run 29584799436, commit 6127376. These results do not prove the current HEAD, the V4 ZIP, or the V5 package. Re-run the current workflows and bind any claim to the resulting commit SHA and run ID.

Legacy V4 Compatibility Notes

The root runtime/*.ps1, V4 onboarding text and historical outputs remain for compatibility and audit work. They are not the recommended installation path and must not override a failing V5 check.

A V4 provider selection was configuration metadata; it did not by itself implement a DeepSeek API provider, endpoint, authentication path or tool-use compatibility.
The V4 ZIP in dist/ is invalid because its physical bytes do not match the adjacent release metadata. Keep it only as an audit sample.
Historical PASS, VERIFIED and expected test-count text is commit-scoped. It is not an expected result that a modified checkout may copy without rerunning the commands.
New users should use V5 factoryctl; legacy PowerShell commands are for migration or historical diagnosis.

Legacy Complex Project Workflow (V4.1, historical)

This section records the earlier intended workflow. It is not evidence that the current checkout completed these steps.

From requirement to verified execution plan in one command:

# 1. Write your requirement (or use existing docs)
# 2. Run the task decomposition engine
pwsh -File runtime/task-decomposition-engine.ps1 `
  -Requirement ./my-project-requirement.md `
  -OutputDir ./output/my-project

# 3. Review the generated plans
#    - task_graph.json       (tasks + dependencies)
#    - worker_plan.json      (agent assignments)
#    - validation_plan.json  (verification per task)
#    - agent_execution_plan.json (execution order)

What Happens

Step	Engine Action
Project Type Detection	Keywords → `admin-system`, `ecommerce`, `saas`, etc.
Risk Classification	P0 (auth/payment) → P3 (docs/styles) with required gates
Task Decomposition	Requirement → 8-12 ordered task nodes
Skill Pack Matching	Auto-match enabled packs to project type
Knowledge Referencing	Evidence pack citations with source_file + source_hash
Search Strategy	Provider-aware: respects `search_provider=none` default
Validation Plan	Every task has ≥1 method: test, artifact, review, static_check
Worker Plan	Main Agent + Integrator + Workers with file boundaries

No artifact = no PASS. Every task must produce verifiable output. Search defaults to none. GLM is optional. GPT/Claude can use native search.

Architecture

Codex Factory
├── packages/factory-cli/             # Current V5 Preview control plane
│   ├── src/                          # CLI, orchestration, context, knowledge, evidence
│   ├── tests/                        # Current automated contracts
│   ├── install.ps1                   # Windows source installer
│   └── package.json                  # Node 24 package definition
├── docs/CONTROL_PLANE_V5_GUIDE.zh-CN.md
├── .github/workflows/
│   ├── factory-cli-v5.yml            # Current Node 24 Windows + Ubuntu checks
│   └── codex-factory-ci.yml          # Historical V3/V4 testbed workflow
├── runtime/                          # Legacy PowerShell compatibility/audit path
├── outputs/                          # Historical, commit-scoped reports
└── dist/                             # Legacy archives; V4 ZIP is explicitly invalid

Verification Flow

Current commit SHA
       │
       ├── Windows / Node 24 ── npm ci ─ typecheck ─ test ─ build ─ pack dry-run
       │
       └── Ubuntu / Node 24 ─── npm ci ─ typecheck ─ test ─ build ─ pack dry-run
                                      │
                                      └── claim is bound to this run + commit only

Limitations / Non-Claims

This project is an engineering reliability framework, not a commercial product. Please read:

❌ Not a production cloud platform — no SaaS, no multi-tenant, no payment system
❌ Not a replacement for senior engineers — it augments, not replaces, human judgment
❌ No real corporate identity — receipts use self-declared automated signatures
❌ Not a security audit tool — secret scans are pattern-based, not exhaustive
❌ No Factory-provided DeepSeek provider — Factory inherits the user's Codex runtime
❌ No published V5 registry release yet — 5.0.0-preview.1 is installed from source or a locally generated .tgz
❌ No trust inheritance from old reports — historical PASS records certify only their recorded inputs and commit
❌ No fake production approval — "VERIFIED" means the framework''s own checks passed
✅ Honest about limitations — current claims require reproducible evidence from the current checkout
✅ Cross-platform CI definition — V5 checks are defined for Windows and Ubuntu; inspect the current run before claiming success
✅ Open source — MIT licensed, community contributions welcome

Roadmap

Phase	Focus
V5 Preview (current)	Harden control-plane contracts, legacy fail-closed migration, user installation
V5 release candidate	Current-run cross-platform evidence and consumable release packaging
Later	Stronger per-Agent isolation/provenance and broader runtime compatibility testing

中文简介

Codex Factory 是一个面向 AI 编程助手的本地工程可靠性框架。

它的核心不是"生成代码"，而是解决一个关键问题： AI 说"做完了"——你怎么知道它真的做对了？

通过任务图拆分、角色化 Agent、来源绑定记忆、可选外部搜索、上下文证据账本、独立验收和 CI 制品溯源等机制， Codex Factory 让 AI 编码从"一段长对话里的黑盒生成"变成"可拆分、可追踪、可复验"的工程流程。

V3.4.2 曾在记录的 commit 6127376、run 29584799436 上取得严格远程验证结果；这是历史证据，不等于当前 HEAD、V4 ZIP 或 V5 已自动通过。当前版本请使用 packages/factory-cli，并以当前提交的本地命令和 Node 24 Windows/Ubuntu CI 结果为准。

License

MIT License — see LICENSE file.

Contributing

This is a personal engineering project. Issues, discussions, and PRs are welcome. For major changes, please open an issue first to discuss.

Built with Codex. Verified by Codex. Trusted through evidence.

codex-factory

Links

README