Back to Details

kanban-codex-lane

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Kanban Codex Lane

Kanban Codex Lane

Overview

概述

This skill defines the lightweight Hermes+Codex dual-lane convention for Kanban workers. Hermes is always the task owner: it calls 
kanban_show
, decides whether Codex is appropriate, creates or selects an isolated workspace, starts and monitors Codex, reconciles any diff, runs verification, and writes the final 
kanban_complete
or 
kanban_block
handoff. Codex is an input lane only. Codex output is not a task completion signal, not a trusted reviewer, and not allowed to write durable Kanban state directly.
The convention exists so a Hermes worker can use Codex for bounded implementation help without changing the dispatcher. The dispatcher must still spawn Hermes workers. A worker may optionally spawn Codex inside its own run, then accept, partially accept, or reject the lane after independent review and tests.
本技能为看板工作者定义了轻量级的Hermes+Codex双通道约定。Hermes始终是任务的所有者：它调用
kanban_show
，判断是否适合使用Codex，创建或选择独立工作区，启动并监控Codex，协调差异，运行验证，并最终执行
kanban_complete
或
kanban_block
交接操作。Codex仅作为输入通道。Codex的输出不代表任务完成信号，不具备可信评审者身份，且不允许直接写入持久化看板状态。
这个约定的存在使得Hermes工作者可以在不改变调度器的前提下，使用Codex获得有限的实现协助。调度器仍需生成Hermes工作者。工作者可以选择在自身运行过程中生成Codex，之后在独立评审和测试后接受、部分接受或拒绝该通道的输出。

When to Use

使用场景

Use the Codex lane when all of these are true:
  • The Kanban task is a coding, refactor, documentation, test, or mechanical migration task with clear acceptance criteria.
  • A bounded diff can be evaluated by Hermes in one run.
  • The repo can be copied or checked out in an isolated git worktree/branch.
  • Hermes can run the relevant tests itself after Codex exits.
  • The prompt can state all safety constraints and files that must not change.
Do not use the Codex lane when any of these are true:
  • The task requires human judgment that is not already captured in the Kanban body.
  • The worker lacks repo access, Codex auth, or time to reconcile the result.
  • The change touches secrets, credential stores, private user data, or production order-entry systems.
  • A small direct edit is faster and safer than spawning another agent.
  • The task is research-only and should produce a written handoff rather than a diff.
  • The worker would be tempted to mark Done based only on Codex self-report.
当满足以下所有条件时，可使用Codex通道：
  • 看板任务是编码、重构、文档编写、测试或机械迁移任务，且具有明确的验收标准。
  • Hermes可在一次运行中评估有限范围内的差异。
  • 代码仓库可被复制或检出到独立的git工作树/分支中。
  • Hermes可在Codex退出后自行运行相关测试。
  • 提示词可明确所有安全约束以及禁止修改的文件。
当存在以下任一情况时，请勿使用Codex通道：
  • 任务需要看板内容中未涵盖的人工判断。
  • 工作者缺少仓库访问权限、Codex授权，或没有时间协调结果。
  • 修改涉及机密信息、凭证存储、私有用户数据或生产订单录入系统。
  • 直接进行小型编辑比生成另一个Agent更快、更安全。
  • 任务仅为研究性质，应生成书面交接文档而非代码差异。
  • 工作者可能仅根据Codex的自我报告就标记任务完成。

Ownership Rules

所有权规则

  1. Hermes owns the Kanban lifecycle. Codex must never call 
    kanban_complete
    , 
    kanban_block
    , 
    kanban_create
    , gateway messaging, or any Hermes board CLI as a substitute for the worker.
  2. Hermes owns final acceptance. Treat Codex commits/diffs as untrusted patches until reviewed and verified.
  3. Hermes owns test execution. Codex may run tests, but those runs are advisory; repeat required verification from Hermes with the repo's canonical wrapper.
  4. Hermes owns safety. If Codex changes safety boundaries, risk gates, live trading behavior, or secrets handling, reject the lane even if tests pass.
  5. Hermes owns cleanup. Kill stuck Codex processes and remove temporary worktrees when they are no longer needed.
  1. Hermes掌控看板生命周期。Codex绝不能调用
    kanban_complete
    、
    kanban_block
    、
    kanban_create
    、网关消息传递或任何Hermes看板CLI来替代工作者执行操作。
  2. Hermes拥有最终验收权。在经过评审和验证前，需将Codex的提交/差异视为不可信补丁。
  3. Hermes负责测试执行。Codex可运行测试，但这些测试仅作参考；必须由Hermes使用仓库的标准封装器重复执行必要的验证。
  4. Hermes掌控安全。如果Codex修改了安全边界、风险闸门、实时交易行为或机密处理逻辑，即使测试通过，也需拒绝该通道的输出。
  5. Hermes负责清理工作。当不再需要时，终止卡住的Codex进程并移除临时工作树。

Required Worktree and Branch Pattern

工作树与分支模式要求

Never run Codex directly in a shared dirty checkout. Use a branch/worktree name that ties the lane to the Kanban task and keeps untrusted edits isolated.
Recommended variables:
bash
TASK_ID="${HERMES_KANBAN_TASK:-t_manual}"
REPO="/path/to/repo"
BASE="$(git -C "$REPO" rev-parse --abbrev-ref HEAD)"
SAFE_TASK="$(printf '%s' "$TASK_ID" | tr -cd '[:alnum:]_-')"
BRANCH="codex/${SAFE_TASK}/$(date -u +%Y%m%d%H%M%S)"
WORKTREE="/tmp/${SAFE_TASK}-codex-lane"
Create the isolated lane:
bash
git -C "$REPO" fetch --all --prune
git -C "$REPO" worktree add -b "$BRANCH" "$WORKTREE" "$BASE"
git -C "$WORKTREE" status --short --branch
If the current Kanban workspace is already an isolated git worktree created for this task, you may create a sibling Codex branch inside it only if 
git status --short
is clean except for intentional Hermes edits. Otherwise create a separate temporary worktree and cherry-pick or copy accepted commits back after reconciliation.
Cleanup after reconciliation:
bash
git -C "$REPO" worktree remove "$WORKTREE"
git -C "$REPO" branch -D "$BRANCH"  # only after accepted commits were copied/cherry-picked or intentionally rejected
Keep the worktree if it is needed as an artifact for review; record it in 
codex_lane.artifacts
and mention it in the handoff.
绝不能在共享的未清理检出目录中直接运行Codex。使用与看板任务关联的分支/工作树名称，将不可信编辑隔离。
推荐变量：
bash
TASK_ID="${HERMES_KANBAN_TASK:-t_manual}"
REPO="/path/to/repo"
BASE="$(git -C "$REPO" rev-parse --abbrev-ref HEAD)"
SAFE_TASK="$(printf '%s' "$TASK_ID" | tr -cd '[:alnum:]_-')"
BRANCH="codex/${SAFE_TASK}/$(date -u +%Y%m%d%H%M%S)"
WORKTREE="/tmp/${SAFE_TASK}-codex-lane"
创建独立通道：
bash
git -C "$REPO" fetch --all --prune
git -C "$REPO" worktree add -b "$BRANCH" "$WORKTREE" "$BASE"
git -C "$WORKTREE" status --short --branch
如果当前看板工作区已是为此任务创建的独立git工作树，且
git status --short
显示除了Hermes的有意编辑外均为干净状态，则可在其中创建同级Codex分支。否则，需创建单独的临时工作树，协调后将接受的提交合并或复制回去。
协调后的清理操作：
bash
git -C "$REPO" worktree remove "$WORKTREE"
git -C "$REPO" branch -D "$BRANCH"  # 仅在接受的提交已被复制/合并或明确拒绝后执行
如果工作树需要作为评审工件保留，则将其记录在
codex_lane.artifacts
中，并在交接时提及。

Codex Capability Checks

Codex能力检查

Run these before spawning Codex. Missing Codex is a normal reason to skip the lane, not a task blocker if Hermes can do the task directly.
bash
command -v codex
codex --version
codex features list | grep -i goals || true
If 
/goal
support is required, enable or launch with the feature flag only after checking availability:
bash
codex features enable goals || true
codex --enable goals --version
Authentication can be via 
OPENAI_API_KEY
or the Codex CLI OAuth state (often 
~/.codex/auth.json
). Do not print token files. A missing 
OPENAI_API_KEY
is not proof that auth is unavailable.
在生成Codex前运行以下检查。缺少Codex是跳过该通道的正常理由，若Hermes可直接完成任务，则不构成任务阻塞。
bash
command -v codex
codex --version
codex features list | grep -i goals || true
如果需要
/goal
支持，仅在确认可用后启用或通过功能标志启动：
bash
codex features enable goals || true
codex --enable goals --version
认证可通过
OPENAI_API_KEY
或Codex CLI OAuth状态（通常为
~/.codex/auth.json
）完成。请勿打印令牌文件。缺少
OPENAI_API_KEY
并不代表认证不可用。

Mode Selection

模式选择

Use 
codex exec
for bounded one-shot edits where Codex should exit on its own:
python
terminal(
    command="codex exec --full-auto '$(cat /tmp/codex_prompt.md)'",
    workdir=WORKTREE,
    background=True,
    pty=True,
    notify_on_complete=True,
)
Use Codex 
/goal
only for broader multi-step work that benefits from durable objective tracking. Launch interactively in a PTY/tmux session or with 
codex --enable goals
if the feature is disabled by default. Keep the goal objective self-contained: repo path, task id, safety constraints, allowed scope, acceptance criteria, tests, and commit expectations.
Example 
/goal
objective text to paste into Codex:
text
/goal Work in this repository only: <WORKTREE>. Task: <TASK_ID> <TITLE>.
Hermes owns the Kanban lifecycle; do not call Hermes kanban tools or messaging.
Create small commits on branch <BRANCH>. Follow the PMB safety constraints in the prompt.
Run the requested verification commands and report exact outputs. Stop after producing a diff and summary.
Do not use 
--yolo
for prediction-market-bot or safety-sensitive repos. Prefer 
--full-auto
inside the isolated worktree, then rely on Hermes reconciliation.
对于有限范围的一次性编辑，使用
codex exec
，Codex应自行退出：
python
terminal(
    command="codex exec --full-auto '$(cat /tmp/codex_prompt.md)'",
    workdir=WORKTREE,
    background=True,
    pty=True,
    notify_on_complete=True,
)
仅当需要持久化目标跟踪的更广泛多步骤工作时，才使用Codex 
/goal
。在PTY/tmux会话中交互式启动，或如果该功能默认禁用，则使用
codex --enable goals
启动。保持目标独立包含：仓库路径、任务ID、安全约束、允许范围、验收标准、测试和提交预期。
示例粘贴到Codex中的
/goal
目标文本：
text
/goal 仅在此仓库中工作：<WORKTREE>。任务：<TASK_ID> <TITLE>。
Hermes掌控看板生命周期；请勿调用Hermes看板工具或发送消息。
在分支<BRANCH>上创建小型提交。遵循提示词中的PMB安全约束。
运行要求的验证命令并报告准确输出。生成差异和摘要后停止。
对于预测市场机器人（PMB）或安全敏感仓库，请勿使用
--yolo
。在独立工作树中优先使用
--full-auto
，之后依赖Hermes进行协调。

Prompt Construction

提示词构建

Use the linked template at 
templates/pmb-codex-lane-prompt.md
for prediction-market-bot work. For other repos, keep the same structure and replace the PMB-specific safety block with repo-specific invariants.
Every Codex prompt must include:
  • task_id
    , title, and full Kanban acceptance criteria.
  • Repo path, worktree path, branch name, and allowed file scope.
  • Explicit statement: Hermes owns Kanban lifecycle; Codex is an input lane only.
  • Required output: concise summary, files changed, commits, tests run, and known risks.
  • Prohibited actions: secrets access, external messaging, board mutation, unrelated refactors, dependency upgrades unless required.
  • Verification commands Codex may run and commands Hermes will run afterward.
For PMB, include these mandatory safety constraints verbatim:
text
PMB safety constraints:
- live-SIM is paper-only; do not add or enable live REST order entry.
- Never use market orders.
- Do not add execution crossing or bypass price/risk checks.
- Do not fake passive fills, fills, PnL, order states, or reconciliation evidence.
- Do not weaken risk gates, limits, kill switches, or fail-closed behavior.
- Keep research/selection outside the C++ hot path unless explicitly requested.
- Do not read, print, write, or require secrets/tokens/credentials.
对于预测市场机器人（PMB）工作，使用链接模板
templates/pmb-codex-lane-prompt.md
。对于其他仓库，保持相同结构，将PMB特定的安全块替换为仓库特定的不变规则。
每个Codex提示词必须包含：
  • task_id
    、标题和完整的看板验收标准。
  • 仓库路径、工作树路径、分支名称和允许的文件范围。
  • 明确声明：Hermes掌控看板生命周期；Codex仅作为输入通道。
  • 要求的输出：简洁摘要、修改的文件、提交记录、运行的测试和已知风险。
  • 禁止的操作：访问机密、外部消息传递、修改看板状态、无关重构、非必要的依赖升级。
  • Codex可运行的验证命令以及Hermes后续将运行的命令。
对于PMB，需逐字包含以下强制安全约束：
text
PMB安全约束：
- live-SIM仅为模拟环境；请勿添加或启用实时REST订单录入功能。
- 绝不使用市价订单。
- 请勿添加执行交叉或绕过价格/风险检查。
- 请勿伪造被动成交、成交记录、盈亏（PnL）、订单状态或协调证据。
- 请勿弱化风险闸门、限制、终止开关或故障关闭行为。
- 除非明确要求，否则将研究/选择逻辑置于C++热路径之外。
- 请勿读取、打印、写入或要求机密/令牌/凭证。

Monitoring, Timeout, and Kill Behavior

监控、超时与终止行为

Start long Codex lanes in the background with PTY and completion notification:
python
result = terminal(
    command="codex exec --full-auto '$(cat /tmp/codex_prompt.md)'",
    workdir=WORKTREE,
    background=True,
    pty=True,
    notify_on_complete=True,
)
session_id = result["session_id"]
Monitor without interfering:
python
process(action="poll", session_id=session_id)
process(action="log", session_id=session_id, limit=200)
process(action="wait", session_id=session_id, timeout=300)
Send a Kanban heartbeat every few minutes for lanes longer than two minutes, e.g. 
kanban_heartbeat(note="Codex lane running in <WORKTREE>; waiting for tests/diff")
.
Kill conditions:
  • No useful output for the task's remaining runtime budget.
  • Codex requests secrets, production credentials, or external permissions.
  • Codex attempts to modify files outside the worktree.
  • Codex starts unrelated rewrites or dependency churn.
  • Codex is still running near the worker timeout and no safe partial artifact exists.
Kill command:
python
process(action="kill", session_id=session_id)
After kill, inspect 
git status --short
, preserve useful patches only if safe, and record 
codex_lane.result: timed_out
or 
rejected
with a concrete 
rejected_reason
.
在后台启动长时间运行的Codex通道，使用PTY并启用完成通知：
python
result = terminal(
    command="codex exec --full-auto '$(cat /tmp/codex_prompt.md)'",
    workdir=WORKTREE,
    background=True,
    pty=True,
    notify_on_complete=True,
)
session_id = result["session_id"]
在不干扰的情况下监控：
python
process(action="poll", session_id=session_id)
process(action="log", session_id=session_id, limit=200)
process(action="wait", session_id=session_id, timeout=300)
对于运行时间超过两分钟的通道，每隔几分钟发送一次看板心跳，例如
kanban_heartbeat(note="Codex通道在<WORKTREE>中运行；等待测试/差异结果")
。
终止条件：
  • 在任务剩余运行预算内未产生有用输出。
  • Codex请求机密、生产凭证或外部权限。
  • Codex尝试修改工作树之外的文件。
  • Codex开始无关的重写或依赖更新。
  • Codex在接近工作者超时时间仍在运行，且无安全的部分工件可用。
终止命令：
python
process(action="kill", session_id=session_id)
终止后，检查
git status --short
，仅在安全的情况下保留有用补丁，并记录
codex_lane.result: timed_out
或
rejected
，同时提供具体的
rejected_reason
。

Reconciliation Checklist

协调检查清单

Hermes must perform this checklist before accepting any Codex lane result:
  • git -C <WORKTREE> status --short --branch
    shows only expected files.
  • git -C <WORKTREE> diff --stat
    and 
    git diff
    were reviewed by Hermes.
  • No secrets, credentials, generated caches, unrelated data, or local artifacts are included.
  • PMB safety constraints were preserved: no live REST order entry, no market orders, no execution crossing, no fake passive fills/PnL, no risk-gate weakening, no secrets.
  • Codex commits are small enough to cherry-pick or squash cleanly.
  • Hermes ran the canonical tests itself, using 
    scripts/run_tests.sh
    for Hermes Agent or the repo's documented wrapper for other repos.
  • Any Codex-run tests are listed separately from Hermes-run tests.
  • Accepted commits/diffs were applied to the Hermes-owned workspace/branch.
  • Rejected or partial work has a concrete reason and artifact path if useful.
Acceptance outcomes:
  • accepted
    : Codex diff/commits were reviewed, applied, and verified.
  • partial
    : Some Codex work was accepted after edits or cherry-picks; rejected parts are documented.
  • rejected
    : No Codex changes were accepted; reason is documented.
  • timed_out
    : Codex exceeded the lane budget; useful artifacts may or may not exist.
Hermes在接受任何Codex通道结果前必须执行以下检查：
  • git -C <WORKTREE> status --short --branch
    仅显示预期文件。
  • Hermes已评审
    git -C <WORKTREE> diff --stat
    和
    git diff
    结果。
  • 未包含机密、凭证、生成的缓存、无关数据或本地工件。
  • 保留了PMB安全约束：无实时REST订单录入、无市价订单、无执行交叉、无伪造被动成交/盈亏、无风险闸门弱化、无机密信息。
  • Codex提交足够小，可干净地合并或压缩。
  • Hermes已自行运行标准测试，对于Hermes Agent使用
    scripts/run_tests.sh
    ，对于其他仓库使用其文档中说明的封装器。
  • Codex运行的测试与Hermes运行的测试分别列出。
  • 已将接受的提交/差异应用到Hermes掌控的工作区/分支。
  • 拒绝或部分接受的工作有具体理由，若有用则记录工件路径。
验收结果：
  • accepted
    ：Codex的差异/提交已被评审、应用并验证。
  • partial
    ：部分Codex工作在编辑或合并后被接受；拒绝部分已记录。
  • rejected
    ：未接受任何Codex修改；理由已记录。
  • timed_out
    ：Codex超出通道预算；可能存在有用工件，也可能不存在。

kanban_complete Metadata Schema

kanban_complete元数据 Schema

Include this object under 
metadata.codex_lane
for every task where the lane was considered. If Codex was not used, set 
used: false
and explain why in 
rejected_reason
or a sibling 
notes
field.
json
{
  "codex_lane": {
    "used": true,
    "mode": "exec | goal | skipped",
    "worktree": "/absolute/path/to/codex/worktree",
    "branch": "codex/t_caa69668/20260508100000",
    "command": "codex exec --full-auto ...",
    "result": "accepted | rejected | partial | timed_out",
    "accepted_commits": ["<sha1>", "<sha2>"],
    "rejected_reason": "empty when fully accepted; otherwise concrete reason",
    "tests_run": [
      {"command": "scripts/run_tests.sh tests/tools/test_x.py", "exit_code": 0, "owner": "hermes"},
      {"command": "codex-reported: npm test", "exit_code": 0, "owner": "codex"}
    ],
    "artifacts": ["/absolute/path/to/log-or-patch"]
  }
}
For tasks that intentionally skip Codex:
json
{
  "codex_lane": {
    "used": false,
    "mode": "skipped",
    "worktree": null,
    "branch": null,
    "command": null,
    "result": "rejected",
    "accepted_commits": [],
    "rejected_reason": "Direct Hermes edit was smaller and safer than spawning Codex.",
    "tests_run": [],
    "artifacts": []
  }
}
对于每个考虑使用该通道的任务，需在
metadata.codex_lane
下包含以下对象。若未使用Codex，设置
used: false
并在
rejected_reason
或同级
notes
字段中说明原因。
json
{
  "codex_lane": {
    "used": true,
    "mode": "exec | goal | skipped",
    "worktree": "/absolute/path/to/codex/worktree",
    "branch": "codex/t_caa69668/20260508100000",
    "command": "codex exec --full-auto ...",
    "result": "accepted | rejected | partial | timed_out",
    "accepted_commits": ["<sha1>", "<sha2>"],
    "rejected_reason": "完全接受时为空；否则为具体理由",
    "tests_run": [
      {"command": "scripts/run_tests.sh tests/tools/test_x.py", "exit_code": 0, "owner": "hermes"},
      {"command": "codex-reported: npm test", "exit_code": 0, "owner": "codex"}
    ],
    "artifacts": ["/absolute/path/to/log-or-patch"]
  }
}
对于有意跳过Codex的任务：
json
{
  "codex_lane": {
    "used": false,
    "mode": "skipped",
    "worktree": null,
    "branch": null,
    "command": null,
    "result": "rejected",
    "accepted_commits": [],
    "rejected_reason": "直接使用Hermes编辑比生成Codex更快捷、更安全。",
    "tests_run": [],
    "artifacts": []
  }
}

Common Pitfalls

常见陷阱

  1. Treating Codex self-report as verification. Always inspect the diff and rerun tests from Hermes.
  2. Running Codex in the user's dirty main checkout. Always isolate in a worktree/branch.
  3. Letting Codex own Kanban. Codex may summarize progress, but Hermes writes board state.
  4. Forgetting PMB safety invariants in the prompt. Missing safety text is a lane setup failure.
  5. Using 
    /goal
    for quick edits. Prefer 
    codex exec
    unless durable multi-step continuation is needed.
  6. Killing a stuck lane without recording why. 
    rejected_reason
    must explain the decision.
  7. Accepting broad unrelated cleanup because tests pass. Reject or cherry-pick only the scoped changes.
  1. 将Codex的自我报告视为验证。始终检查差异并由Hermes重新运行测试。
  2. 在用户未清理的主检出目录中运行Codex。始终隔离到工作树/分支中。
  3. 让Codex掌控看板。Codex可总结进度，但看板状态需由Hermes写入。
  4. 在提示词中遗漏PMB安全不变规则。缺少安全文本属于通道设置失败。
  5. 为快速编辑使用
    /goal
    。除非需要持久化的多步骤延续，否则优先使用
    codex exec
    。
  6. 终止卡住的通道但未记录原因。
    rejected_reason
    必须解释决策依据。
  7. 因测试通过而接受广泛的无关清理操作。拒绝或仅合并范围内的修改。

Verification Checklist

验证检查清单

  • Codex was skipped or started only after 
    command -v codex
    , 
    codex --version
    , and optional goals feature checks.
  • Codex ran only in an isolated worktree/branch.
  • Prompt included task scope, ownership rules, PMB safety constraints when applicable, and verification commands.
  • Hermes reviewed 
    git diff
    and safety-sensitive files.
  • Hermes ran canonical tests independently.
  • kanban_complete.metadata.codex_lane
    follows the schema above.
  • Temporary processes and unnecessary worktrees were cleaned up.
  • 仅在执行
    command -v codex
    、
    codex --version
    及可选的目标功能检查后，才跳过或启动Codex。
  • Codex仅在独立工作树/分支中运行。
  • 提示词包含任务范围、所有权规则、适用时的PMB安全约束以及验证命令。
  • Hermes已评审
    git diff
    和安全敏感文件。
  • Hermes已独立运行标准测试。
  • kanban_complete.metadata.codex_lane
    遵循上述Schema。
  • 已清理临时进程和不必要的工作树。