Code-role

Control one software milestone with explicit ownership, objective evidence, and independent evaluation.

用明确责任、客观证据和独立评估控制一个软件里程碑。

Code-role is a local operating system for reliable AI coding. It keeps Codex roles focused on observable milestone outcomes and prevents research, documents, code activity, tests written, or workflow ceremony from being mistaken for delivery.

Code-role 是一套面向可靠 AI 编程的本地工作机制。它让 Codex 角色始终围绕可观测的里程碑结果工作，并防止把调研、文档、代码活动、“写了测试”或流程动作误判成交付。

It provides two official operating profiles:

• Minimal Profile: four workstations, the smallest complete milestone-control unit.
• Full Profile: eight roles, separated professional ownership with versioned packet evidence and the same artifact-first dialogue control.

Code-role 是一个用于控制 Codex 编程交付的本地角色系统，正式提供两套配置：

• 四角色最小版： 能完整控制一个里程碑的最小单元。
• 八角色完整版： 专业职责进一步拆分，并保留版本化 packet 证据链。

Neither profile is deprecated. Choose one profile for each milestone according to complexity, risk, and audit needs.

两套配置都不是旧版。每个 milestone 根据复杂度、风险和审计要求选择其中一套。

60-Second Start / 60 秒启动

git clone https://github.com/Deepleaper/Code-role.git
cd Code-role
python3 scripts/init_loop_workflow.py "/absolute/path/to/your-project" \
  --project-name "Your Project"
python3 scripts/init_loop_workflow.py "/absolute/path/to/your-project" --check

Then open the generated code-role/role-instance-prompts/project-manager.md and define one complete Project OKR. Product Strategy defines the complete Product Contract, Engineering decomposes execution into STEP stages and builds the candidate, and Independent Evaluation evaluates only the complete runnable result.

然后打开生成的 code-role/role-instance-prompts/project-manager.md，定义完整项目 OKR。产品策略完成全局 Product Contract，工程自行拆分 STEP 并完成代码，独立评估只验收完整可运行候选物。

See the complete four-workstation walkthrough to inspect one milestone from PM Assignment through independent evaluation and closure.

查看四工位完整闭环示例，了解一个 milestone 如何从项目经理任务书、工程交付、独立评估一直走到关闭。

What Makes It Different / 核心差异

Principle	Code-role behavior
One accountable outcome	The Project Manager owns one accepted Objective and its binary KRs.
Outcome KRs only	Delivery KRs describe observable user, business, product, or runtime outcomes; process artifacts are methods or evidence.
One canonical Project OKR	Project Manager and user define one Objective and one KR set; every other role preserves and serves those same KRs.
Mandatory software order	Complete product contract -> complete engineering candidate -> independent evaluation.
Evidence before status	Unrun checks, missing evidence, and partial results remain 0.
Independent acceptance	Engineering produces candidate evidence; Independent Evaluation decides observed pass/fail.
One primary artifact	Every role has one required professional deliverable; annexes and packet metadata are optional.
Local control plane	Generated code-role/ files stay outside product runtime and target-project releases by default.

Real Project Cases / 真实项目案例

Code-role was shaped by two private, real-world AI engineering projects. The value of these cases is not that both milestones are complete. Neither case is presented as complete. The value is that Code-role kept strong partial results from becoming unsupported product claims.

Code-role 来自两个真实的私有 AI 工程项目。这两个案例的价值不是“都成功完成了”，我们也没有把它们包装成完成案例。真正的价值在于：即使已经取得大量局部成果，Code-role 仍然阻止团队把不完整证据扩大成产品结论。

Case	Evidence that looked strong	What still remained 0	Control value
DeepBrain memory runtime	1,750 unit tests, 142 frontend/runtime tests, S50 50/50, LongMemEval-S 499/500, and 100/100 grounded source joins	Fair comparator, representative raw benchmark reruns, repair proof, clean reproducibility, and production cost/SLO evidence	Independent Evaluation held the milestone and Reviewer route at 0 instead of turning a 73/100 partial result into “production ready.”
Leaper Agent enterprise runtime	A historical pre-code Hermes comparison baseline that looked professional but was not executable	Real task artifacts, isolated holdout, committed grader mechanism, concrete same-condition runtime, and canonical integrity evidence	The case exposed both an evidence defect and a role-order defect; the current model keeps acceptance requirements in Product, then routes Engineering, then post-candidate Evaluation.

Read the complete two-case launch story.

Why / 为什么

AI coding work drifts when progress is measured by activity instead of accepted product evidence. A polished document, a large diff, or a passing local command does not prove that the milestone is complete.

当 AI 编程以“做了多少事情”代替“是否获得已接受的产品证据”时，目标就会漂移。漂亮文档、大量代码或一条本地通过命令，都不能单独证明里程碑完成。

Code-role keeps four rules stable across both profiles:

1. The Project Manager owns the milestone result.
2. Professional roles own professional conclusions.
3. Required completion evidence is objective and binary.
4. Implementation cannot approve itself; independent evaluation is required.

Code-role 在两套配置中都坚持四条规则：

1. 项目经理对里程碑结果负责。
2. 专业角色对专业结论负责。
3. 完成证据必须客观、可验证，并按二值判断。
4. 实现不能自我验收，必须经过独立评估。

Choose A Profile / 选择配置

Decision	Minimal Profile / 四角色最小版	Full Profile / 八角色完整版
Best for	Clear product direction, bounded engineering work, normal iteration speed	Complex or high-risk milestones, unresolved research/architecture, formal audit needs
适用场景	产品方向清楚、工程范围可控、需要快速迭代	复杂或高风险 milestone、研究和架构不确定、需要完整审计
Roles	4 workstations	8 separate roles
Control state	One milestone-board.md	Milestone contract, Orchestrator state, and accepted packet pointers
Handoff	One role-specific assignment and one short return	One role-specific assignment, professional packet, and short return
Evaluation	Independent Evaluation workstation	Test Evaluator plus final Reviewer audit
Process weight	Low	High

Use the Minimal Profile when four workstations can preserve professional quality without losing necessary context. Use the Full Profile when separating research, product, architecture, code context, evaluation, and audit reduces meaningful risk.

当四个工位足以保持专业质量且不会丢失必要上下文时，使用四角色最小版。当拆开研究、产品、架构、代码上下文、评估和审计能够实质降低风险时，使用八角色完整版。

Do not switch profiles silently in the middle of a milestone. A profile change requires an explicit Project Manager proposal and user acceptance.

同一 milestone 中不要静默切换配置。配置切换必须由项目经理明确提出，并由用户确认。

Minimal Profile / 四角色最小版

Workstation	Responsibility
Project Manager / 项目经理	Defines the complete Project Objective and KR-* set, controls global stages, accepts independent evidence, and closes the milestone
Product Strategy / 产品策略	Completes the Product Contract for every existing KR, including behavior, scope, thresholds, non-goals, and claim boundaries; it creates no second OKR
Engineering / 工程	Alone decomposes STEP-* stages, performs necessary research/architecture/context work, implements and verifies the complete runnable candidate
Independent Evaluation / 独立评估	After candidate readiness, records the executable SOP from accepted KR thresholds and independently runs the complete evaluation

Research is a capability inside Product Strategy and Engineering. Architecture and code-context mapping are Engineering modes. They are not mandatory stages.

研究属于产品策略和工程能力。架构与代码上下文映射属于工程工作模式，不是必须依次经过的阶段。

flowchart LR
    U["User accepts complete KR set"] --> PM["Project Manager"]
    PM --> P["Product Strategy: Product Contract for every KR"]
    P --> PM
    PM --> E["Engineering: STEP stages and complete candidate"]
    E --> PM
    PM --> V["Independent Evaluation: complete KR scope"]
    V --> PM
    PM -- "All KRs=1" --> H["Human close or release gate"]
    PM -- "Contract or candidate failed" --> P
    PM -- "Engineering defect" --> E

Loading

Software delivery uses a fixed dependency order: complete Product Contract, complete Engineering candidate, then Independent Evaluation. Project Manager and Product Strategy remain global; only Engineering decomposes STEP-1...STEP-N execution stages.

软件交付采用固定依赖顺序：完整 Product Contract、完整工程候选物、独立评估。项目经理和产品策略保持全局视角，只有工程拆分 STEP-1...STEP-N 执行阶段。

Initialize Minimal Profile / 初始化四角色最小版

python scripts/init_loop_workflow.py "/absolute/path/to/project" \
  --project-name "Project Name"

Update role rules while preserving the current milestone board and work attachments:

python scripts/init_loop_workflow.py "/absolute/path/to/project" \
  --project-name "Project Name" \
  --sync

Validate:

python scripts/init_loop_workflow.py "/absolute/path/to/project" --check

Minimal Profile documentation:

• Goal loop guide / 四角色说明
• Goal loop contract / 目标闭环协议
• Project Manager
• Product Strategy
• Engineering
• Independent Evaluation

Full Profile / 八角色完整版

Role	Responsibility
Workflow Orchestrator / 项目经理	Owns the single Project OKR, authoritative global stage, repair routing, evidence acceptance, and final closure
Researcher / 研究员	Produces the complete repository/frontier evidence base and KR coverage needed for the Product Contract
Product / PRD / 产品经理	Completes the Product Contract for every existing KR without creating another Objective or KR set
Architect / 架构师	Defines whole-product architecture contracts, boundaries, interfaces, data flow, and technical risks
Code Context / 上下文工程师	Maps the complete product/architecture contract to exact files, functions, fields, tests, artifacts, and implementation constraints
Implementer / 实现工程师	Alone decomposes STEP-*, changes project files, and produces the complete reproducible runnable candidate
Test Evaluator / 测试评估师	Starts after candidate readiness, records the executable SOP, and independently evaluates every KR
Reviewer / 复核审计	Audits KR/STEP traceability, mandatory stage order, evidence, and claims across all final role outputs

The Full Profile uses the same single Project Objective, shared KR set, step mapping, and stage order while separating research, architecture, code context, implementation, evaluation, and audit ownership. Versioned packet metadata and annexes remain optional audit support.

八角色完整版以结果和证据为核心。每个专业角色使用独立对话，消费明确的权威输入，并产出一份必需的主交付物交由项目经理审阅。版本化 packet 元数据和附件只是可选的审计支持。

Use one configured Codex role instance per role. Do not run the Full Profile by switching roles inside one conversation.

每个角色分别配置一个独立角色实例，不要在一个对话中切换身份来运行八角色完整版。

flowchart LR
    PM0["PM: KR gate"]
    R["Researcher"]
    P["Product / PRD"]
    A["Architect"]
    C["Code Context"]
    I["Implementer"]
    T["Test Evaluator"]
    V["Reviewer"]
    PM1["PM: research gate"]
    PM2["PM: KR gate"]
    PM3["PM: architecture gate"]
    PM4["PM: context gate"]
    PM5["PM: candidate gate"]
    PM6["PM: evaluation gate"]
    PM7["PM: closure gate"]
    PM0 --> R --> PM1 --> P --> PM2 --> A --> PM3 --> C --> PM4 --> I --> PM5 --> T --> PM6 --> V --> PM7

Loading

The diagram shows control returning to Project Manager after every professional role. Supporting roles may be skipped when a complete accepted artifact already exists, but Test Evaluator can never precede the Implementer candidate and Reviewer can never precede independent evaluation.

流程图表示每个专业角色完成后都返回项目经理检查。完整软件交付不能跳过 Product / PRD、Implementer 或候选物完成后的 Test Evaluator；Researcher、Architect、Code Context、Reviewer 只有在已有完整已接受产物或里程碑不需要时才可省略。

Initialize Full Profile / 初始化八角色完整版

Preview:

python scripts/init_project_workflow.py \
  --target "/absolute/path/to/project" \
  --project-name "Project Name" \
  --initial-milestone workflow-bootstrap \
  --initial-chain full-chain

Write:

python scripts/init_project_workflow.py \
  --target "/absolute/path/to/project" \
  --project-name "Project Name" \
  --initial-milestone workflow-bootstrap \
  --initial-chain full-chain \
  --write

Full Profile documentation:

• Eight-role workflow / 八角色工作流
• Role configuration guide
• Milestone contract
• Role completion contract
• Evaluation SOP
• Project bootstrap
• Role instance setup
• Project practices
• Optional state index
• Git operation policy

Shared Completion Standard / 共同完成标准

• 0 means the required result has not been independently proven.
• 1 means every frozen pass condition has acceptable evidence.
• An unrun required check is 0.
• A residual item becomes a new accepted requirement, an explicit non-goal, or remains unresolved at 0.
• Evaluation and review gates are binary. partial_pass and pass_with_residual_risk are invalid gate states.
• Only Project Manager updates milestone status.
• Only the user accepts Objective/KR changes, evaluation-threshold changes, budget expansion, and irreversible release actions.

Local Project Boundary / 本地项目边界

Generated target-project code-role/ directories are local role-control assistance:

• not product runtime content;
• not part of customer delivery bundles;
• not included in release artifacts;
• not committed to the target project by default.

Both initializers add code-role/ to the target repository's local .git/info/exclude when a Git repository already exists. They do not change the tracked .gitignore.

如果目标目录已经是 Git 仓库，两套初始化器都会把 code-role/ 写入本地 .git/info/exclude，不会修改仓库跟踪的 .gitignore。

Product Documentation / 产品文档

• English PRD
• 中文产品需求对齐稿
• One Project OKR standard / 单一项目 OKR 规范
• 中文 HTML 说明与初始化指南
• v0.4.0 release: less process, stronger outcomes / v0.4.0 发布说明
• Minimal target example
• Complete goal-loop walkthrough / 完整目标闭环示例
• Real project cases / 真实项目案例

Community / 社区

• Ask implementation questions or share a real workflow in GitHub Discussions.
• Report reproducible problems through GitHub Issues.
• See the public Roadmap, Changelog, and Contributing Guide.

If Code-role makes an AI coding milestone more predictable, star the repository and share the evidence from your first completed loop. Real project feedback is more valuable than generic promotion.

如果 Code-role 让你的 AI 编程里程碑变得更可控，欢迎 Star，并分享第一个真实闭环的证据。真实项目反馈比泛泛宣传更有价值。

Development / 开发

python -m pytest

Code-role is released under the MIT License.