Back to Details

implement-issues

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Implement Issues

Implement Issues

Build open issues with agents, one pull request per issue. Each issue goes through the flow a person would take it through:
  1. a spec and plan, written by Superpowers from the issue;
  2. the build, done by Superpowers;
  3. a pull request and a code review;
except that no one answers questions along the way. Every decision an agent makes on the user's behalf lands in its pull request, where the user reviews it.
Two agents work on each issue. A planner writes the spec and plan. A build lead executes the plan and answers the review. When plan approval is on, the user reviews the spec and plan on a draft pull request before the build lead starts, and a later run picks up what they approved.
The built pull request opens as a draft. A second agent runs 
review-prs
on it, and the build lead answers that review with 
answer-pr-reviews
. The pull request is marked ready once the review is answered and the checks pass.
You are the dispatcher. Agents write in their own worktrees; you push each branch, open its pull request, and give the verdict on each agent's work. Nothing is marked ready until you have seen the checks pass yourself.
Superpowers owns the spec, the plan, and the build. This skill answers the questions Superpowers would ask a person — which execution mode, which model, how many fix rounds — from the user's settings. It never changes how Superpowers works inside.
This skill names actions — "dispatch an agent", "choose a model" — not tools. Use your platform's equivalents.
由 Agent 构建开放的 Issue，每个 Issue 对应一个 Pull Request。每个 Issue 都走完一个人通常会经历的流程：
  1. 由 Superpowers 根据 Issue 编写 spec 和 plan；
  2. 由 Superpowers 完成 build；
  3. 创建 Pull Request 并进行 Code Review；
唯一区别是，过程中没有人回答问题。Agent 代表用户作出的每个决定都会记录在其 Pull Request 中，供用户审阅。
每个 Issue 由两个 Agent 处理。Planner 编写 spec 和 plan；Build Lead 执行 plan 并回复 review。启用 Plan Approval 时，用户会在 Build Lead 开始前，于一个 draft Pull Request 中审阅 spec 和 plan；后续运行会接续处理用户已经批准的内容。
构建后的 Pull Request 以 draft 形式打开。第二个 Agent 对其运行 
review-prs
，Build Lead 则使用 
answer-pr-reviews
回复 review。Review 已回复且 checks 通过后，Pull Request 才会标记为 ready。
你是 dispatcher。Agent 在各自的 worktree 中工作；你负责 push 每个分支、打开其 Pull Request，并给出对每个 Agent 工作的结论。在亲自确认 checks 通过之前，任何内容都不会被标记为 ready。
Superpowers 负责 spec、plan 和 build。这个 skill 会根据用户的 settings，回答 Superpowers 本应向人提出的问题——采用哪种执行模式、使用哪个 model、进行多少轮修复。它绝不会改变 Superpowers 内部的运行方式。
这个 skill 指定的是动作——"dispatch an agent"、"choose a model"——而不是具体工具。请使用你所在平台的等价功能。

Requirements

Requirements

  • Superpowers (
    brainstorming
    , 
    writing-plans
    , 
    subagent-driven-development
    , 
    executing-plans
    , 
    finishing-a-development-branch
    , 
    verification-before-completion
    ), plus the 
    fetch-issues
    , 
    superpowers-issue-bridge
    , 
    review-prs
    , and 
    answer-pr-reviews
    skills. If one is missing, name it and stop.
  • A GitHub repository and 
    gh
    , with 
    gh auth status
    passing — pull requests and their reviews live there, wherever the issues live.
  • When the Review agent uses Codex: the Codex CLI, logged in, with 
    review-prs
    installed for Codex.
  • Superpowers（
    brainstorming
    、
    writing-plans
    、
    subagent-driven-development
    、
    executing-plans
    、
    finishing-a-development-branch
    、
    verification-before-completion
    ），以及 
    fetch-issues
    、
    superpowers-issue-bridge
    、
    review-prs
    和 
    answer-pr-reviews
    skills。如果缺少其中任何一个，请指出并停止。
  • 一个 GitHub repository 和 
    gh
    ，且 
    gh auth status
    必须通过——Pull Request 及其 review 存放在那里，无论 Issue 位于何处。
  • 当 Review Agent 使用 Codex 时：Codex CLI 必须已登录，并为 Codex 安装了 
    review-prs
    。

Settings

Settings

Three settings shape a run. 
docs/agents/delivery.md
in the repository holds the saved ones; its shape is 
assets/delivery.md
.
  • Effort — 
    low
    , 
    medium
    , or 
    high
    . Take it from the first of: the run's argument (
    /implement-issues low
    , "at medium effort"), the file's Effort line, or a question in Stage 2. It decides:
    lowmediumhigh
    Build mode, answering 
    writing-plans
    ' execution question    		one agent, with 
    executing-plans
    		per task, with 
    subagent-driven-development
    		per task, with 
    subagent-driven-development
    Fix rounds per task review—25
    review-prs
    code pass    		offoffon
    Your full checks after the review fixesCI is the evidence; run them only when the pull request has no CIyesyes
    finishing-a-development-branch
    's own suite run    		skipped when HEAD hasn't moved since Stage 5skipped when HEAD hasn't moved since Stage 5runs
    CI fix attempts123
    Plan revision rounds123
    At every effort, Superpowers' whole-branch review runs at the end of the build, you run the full checks before the first push, and nothing merges.
  • Plan approval — on or off; off when the file doesn't say.
  • Models, one per agent. Six agents work on an issue, and each sets the model of one or more seats:
    AgentSeatsDispatched by
    Plannerplanner, spec-checkyou
    Build leadbuild-leadyou
    Implementersimplementer, escalationSuperpowers, inside the build lead
    Task reviewerstask-reviewer, re-reviewer, final-reviewerSuperpowers, inside the build lead
    Review agentpr-revieweryou
    PR code reviewerpr-code-reviewer
    review-prs
    , inside the review agent
    Your session is the dispatcher; it has no setting.
    Values. Each value is a tier (
    cheap
    , 
    standard
    , 
    strong
    ) looked up in the file's Tiers table, 
    session
    , an exact model name, or — for Implementers — 
    by-task
    , which leaves the choice to 
    subagent-driven-development
    's own rules. Review agent may also take 
    codex:
    and a tier or a Codex model; see Codex as a reviewer, below.
    Presets. One word sets every agent left unset. Presets are tiers:
    Agentbudgetbalancedmax
    Plannerstrongstrongstrong
    Build leadstandardstandardstrong
    Implementerscheapstandardstrong
    Task reviewersstandardstandardstrong
    Review agentstandardstandardstrong
    PR code reviewerstandardstrongstrong
    Precedence. For each seat, the first of these that names it wins:
    1. a run override — from the request or from Stage 2;
    2. the seat's row in the file's Seats table;
    3. its agent's row in the Agents table;
    4. the Preset;
    5. the fallback below.
    A value resolves whole: provider and model come from the same level, never a provider from one and a model from another. A value with no 
    codex:
    prefix runs on the provider of whoever dispatches that agent — your session for the Planner, Build lead and Review agent; the build lead's provider for Implementers and Task reviewers; the review agent's for the PR code reviewer. A tier resolves in that provider's Tiers column.
    Escalation. Fix rounds 4–5 exist because an implementer got stuck. When the Implementers value came from a run override, the Agents row or the Preset, and the escalation seat isn't set on its own, escalation runs one tier above it on the same provider: 
    cheap
    → 
    standard
    , 
    standard
    → 
    strong
    , 
    strong
    stays. When that value is an exact model, 
    session
    or 
    by-task
    , or no Implementers value is set, escalation follows 
    subagent-driven-development
    's own rule.
    Codex as a reviewer. Only the Review agent may name 
    codex:
    . Codex reads and reports; it never writes, and you post its review (Stage 7). The PR code reviewer runs inside the review, so it follows the Review agent's provider. Any other agent that names 
    codex:
    stops the run in Stage 2: Codex is for reviews only. A model the parent's provider doesn't accept stops the run too — a Claude model on the PR code reviewer under a Codex review agent, for example.
    Fallback. A seat nothing above names falls back:
    SeatWhen not set
    planner, build-lead, pr-reviewersession model
    implementerasked in Stage 2
    spec-check, task-reviewer, re-reviewer, escalation, final-reviewerthat skill's own rule
    pr-code-reviewerthat skill's own rule
三个 settings 决定一次运行。已保存的 settings 位于 repository 中的 
docs/agents/delivery.md
；其结构见 
assets/delivery.md
。
  • Effort——
    low
    、
    medium
    或 
    high
    。按以下顺序取第一个明确给出的值：运行参数（
    /implement-issues low
    、"at medium effort"）、文件中的 Effort 行，或 Stage 2 中的提问。它决定：
    lowmediumhigh
    Build mode，回答 
    writing-plans
    的执行问题    		一个 Agent，使用 
    executing-plans
    		每个任务一个 Agent，使用 
    subagent-driven-development
    		每个任务一个 Agent，使用 
    subagent-driven-development
    每个任务 review 的修复轮次—25
    review-prs
    代码检查    		关闭关闭开启
    Review 修复后的完整 checksCI 是证据；仅在 Pull Request 没有 CI 时运行是是
    finishing-a-development-branch
    自身的 suite run    		如果 HEAD 自 Stage 5 以来没有移动，则跳过如果 HEAD 自 Stage 5 以来没有移动，则跳过运行
    CI 修复尝试次数123
    Plan 修订轮次123
    在所有 effort 下，Superpowers 的整分支 Code Review 都会在 build 结束时运行；你会在首次 push 前运行完整 checks；并且不会 merge 任何内容。
  • Plan Approval——on 或 off；如果文件中没有说明，则为 off。
  • Models，每个 Agent 一个。一个 Issue 涉及六个 Agent，每个 Agent 为一个或多个 seat 设置 model：
    AgentSeatsDispatched by
    Plannerplanner, spec-check你
    Build Leadbuild-lead你
    Implementersimplementer, escalationSuperpowers，在 Build Lead 内部
    Task Reviewerstask-reviewer, re-reviewer, final-reviewerSuperpowers，在 Build Lead 内部
    Review Agentpr-reviewer你
    PR Code Reviewerpr-code-reviewer
    review-prs
    ，在 Review Agent 内部
    你的 session 是 dispatcher；它没有对应的 setting。
    **Values。**每个值可以是一个 tier（
    cheap
    、
    standard
    、
    strong
    ），从文件中的 Tiers 表查得；也可以是 
    session
    、一个确切的 model 名称，或者是——对于 Implementers——
    by-task
    ，由 
    subagent-driven-development
    自身的规则决定选择。Review Agent 还可以使用 
    codex:
    加一个 tier 或一个 Codex model；参见下文“Codex as a reviewer”。
    **Presets。**一个单词会为所有尚未单独设置的 Agent 设置 model。Preset 是 tier：
    Agentbudgetbalancedmax
    Plannerstrongstrongstrong
    Build Leadstandardstandardstrong
    Implementerscheapstandardstrong
    Task Reviewersstandardstandardstrong
    Review Agentstandardstandardstrong
    PR Code Reviewerstandardstrongstrong
    **Precedence。**对于每个 seat，以下第一个明确指定它的值优先：
    1. 一次运行的 override——来自请求或 Stage 2；
    2. 文件 Seats 表中该 seat 所在的行；
    3. Agents 表中该 Agent 所在的行；
    4. Preset；
    5. 下方的 fallback。
    一个值会整体解析：provider 和 model 必须来自同一层级，绝不能混用一个层级的 provider 与另一个层级的 model。没有 
    codex:
    前缀的值，使用调度该 Agent 者的 provider——对于 Planner、Build Lead 和 Review Agent 是你的 session；对于 Implementers 和 Task Reviewers 是 Build Lead 的 provider；对于 PR Code Reviewer 是 Review Agent 的 provider。Tier 根据该 provider 的 Tiers 列进行解析。
    **Escalation。**第 4～5 轮修复的存在，是因为 Implementer 遇到了阻塞。当 Implementers 的值来自运行 override、Agents 行或 Preset，并且 escalation seat 本身未设置时，escalation 会在同一 provider 上使用高一个 tier 的 model：
    cheap
    → 
    standard
    ，
    standard
    → 
    strong
    ，
    strong
    保持不变。当该值是确切的 model、
    session
    或 
    by-task
    ，或者没有设置 Implementers 值时，escalation 遵循 
    subagent-driven-development
    自身的规则。
    **Codex as a reviewer。**只有 Review Agent 可以指定 
    codex:
    。Codex 负责读取和报告；它绝不写入代码，由你发布其 review（Stage 7）。PR Code Reviewer 在 review 内部运行，因此遵循 Review Agent 的 provider。任何其他 Agent 如果指定 
    codex:
    ，都会在 Stage 2 停止运行：Codex 仅用于 review。如果父级 provider 不接受某个 model，运行也会停止——例如，在 Codex Review Agent 下为 PR Code Reviewer 设置 Claude model。
    **Fallback。**如果上述规则都没有指定某个 seat，则使用：
    Seat未设置时的处理方式
    planner, build-lead, pr-reviewersession model
    implementer在 Stage 2 中询问
    spec-check, task-reviewer, re-reviewer, escalation, final-reviewer该 skill 自身的规则
    pr-code-reviewer该 skill 自身的规则

Stage 1 — Build the queue

Stage 1 — Build the queue

  1. Get the open issues with 
    fetch-issues
    . If the user named issues ("#12 and #15"), keep only those.
  2. Read 
    docs/agents/issue-tracker.md
    for its Linking section — it decides what each pull request writes to close its issue. Read 
    docs/agents/delivery.md
    if it exists.
  3. Find each issue's open pull requests and branches (
    feat/42-*
    , 
    fix/42-*
    ). An open pull request whose body holds 
    <!-- implement-issues: plan -->
    is this skill's plan pull request:
    • labeled 
      plan-approved
      → build;
    • with unanswered review comments — an unresolved thread whose last comment doesn't end with 
      <!-- answer-pr-reviews -->
      → revise the plan;
    • otherwise → waiting on the user.
    Any other open pull request or branch for the issue → skip, and record why. No pull request and no branch → plan.
  4. An issue whose body references another queued issue depends on it: start it after that issue's pull request is marked ready, branched from that issue's branch instead of the base branch, and say so in its pull request. If that issue ends without a ready pull request, skip this one and record why.
  5. Find the base branch — the remote's default branch — and fetch it.
Print the queue — reference, title, branch, action (plan, revise the plan, build), dependency — then the waiting and skipped lists.
  1. 使用 
    fetch-issues
    获取开放的 Issues。如果用户指定了 Issues（例如 "#12 and #15"），则仅保留这些 Issues。
  2. 阅读 
    docs/agents/issue-tracker.md
    中的 Linking 部分——它决定每个 Pull Request 应写入什么内容来关闭对应 Issue。如果 
    docs/agents/delivery.md
    存在，也阅读它。
  3. 查找每个 Issue 的开放 Pull Requests 和 branches（
    feat/42-*
    、
    fix/42-*
    ）。正文包含 
    <!-- implement-issues: plan -->
    的开放 Pull Request 是这个 skill 的 Plan Pull Request：
    • 带有 
      plan-approved
      label → build；
    • 存在未回复的 review 评论——某个 unresolved thread 的最后一条评论未以 
      <!-- answer-pr-reviews -->
      结尾 → revise the plan；
    • 其他情况 → waiting，等待用户处理。
    该 Issue 的任何其他开放 Pull Request 或 branch → skip，并记录原因。既没有 Pull Request 也没有 branch → plan。
  4. 如果某个 Issue 的正文引用了队列中的另一个 Issue，则它依赖那个 Issue：必须等被依赖 Issue 的 Pull Request 标记为 ready 后才能开始；从该 Issue 的 branch 而非 base branch 创建，并在其 Pull Request 中说明这一点。如果被依赖的 Issue 最终没有产生 ready Pull Request，则跳过当前 Issue，并记录原因。
  5. 找到 base branch——remote 的 default branch——并 fetch 它。
打印队列——reference、title、branch、action（plan、revise the plan、build）、dependency——然后打印 waiting 和 skipped 列表。

Stage 2 — Settle the settings, then ask how to run

Stage 2 — Settle the settings, then ask how to run

Ask before dispatching anything.
  1. Settings. Print the effort and where it came from, plan approval, and the preset, if there is one. Then print one table of the six agents: each one's provider, model, and source — run, Seats, Agents, Preset, or fallback. List under an agent any of its seats that resolved differently. Mark Implementers "not used at this effort" at 
    low
    , Task reviewers "final review only" at 
    low
    , and PR code reviewer "not used at this effort" below 
    high
    , rather than leaving them out.
    Check every resolved model against what its provider accepts right now — for your platform, its dispatch's model options or spawn allowlist. One it doesn't accept stops the run: name the agent, the seat, the value, and where it came from. That includes an exact name from another platform, and a tier with no column for its provider.
    When the Review agent resolves to 
    codex:
    ,     check Codex before dispatching anything: 
    codex --version
    succeeds; 
    codex login status
    exits 0; 
    review-prs
    is installed for Codex — in the repository's 
    .agents/skills/
    , in 
    ~/.agents/skills/
    , or in 
    $CODEX_HOME/skills/
    (default 
    ~/.codex/skills/
    ); at high effort, when the code pass runs, Superpowers' 
    requesting-code-review
    is installed for Codex the same way and Codex's multi-agent feature is on (
    codex features
    ), so the code pass can run on its own model; and each distinct Codex model the review resolves to answers, with exit 0:
    bash
    codex exec --ephemeral -s read-only -m "<model>" "Reply with the single word OK."
    Any failure stops the run: name the agent, the value, and where it came from. A run with no Codex reviewer checks none of this. Run every check in this step — the Codex ones too — again on the final table, after the questions and overrides below and just before the user confirms, so an answer that turns Codex on is checked before any agent starts.
    Ask for what the file doesn't settle: the effort, when the run had no argument; plan approval, when the file has no line for it; and the models. With no 
    docs/agents/delivery.md
    , say once that the optional 
    setup-delivery
    skill saves these settings ahead of time, then ask the preset first — 
    budget
    , 
    balanced
    , 
    max
    , or "set each agent", which asks all six agents in one question. With a file that leaves the implementer unset, ask for it as before; that answer sets the implementer seat, not the Implementers agent, and doesn't trigger the escalation step-up. When a value resolves through a tier and there is no Tiers column for its provider — always the case with no file — ask for that provider's cheap, standard and strong models in one question, and include them in the save offer. Offer only the models your dispatch accepts, never a name remembered from elsewhere. If your platform can't set a model per dispatch, say so and use its default for every seat. Then ask whether to use these settings for the run, or override any of them for this run only.
    Overrides in words. A run override from the request maps to agents by this vocabulary only: "plans" → Planner; "builds" or "executes" → Implementers; "leads the build" → Build lead; "reviews tasks" → Task reviewers; "reviews" or "reviews the PR" → Review agent; "reviews the code" → PR code reviewer. Print the agents table with "run" as the source of each overridden row; the run starts only after the user confirms the printed table.
    When anything was asked, offer to save it to 
    docs/agents/delivery.md
    : show the file's diff, and write it only on the user's yes. A run's overrides are saved only when the user says so.
  2. Sequential or parallel? Sequential runs one issue at a time. Parallel runs up to N at once — ask for N, suggesting 3. Offer parallel only if your platform can run several dispatched agents at the same time. Either way, an issue holds its place from dispatch until it stops: waiting on plan approval, marked ready, or ended.
With the printed queue, the answers are the user's go-ahead for the whole run — for each issue: pushing its branch; opening a draft plan pull request and creating the 
plan-approved
label if it's missing; pushing plan revisions with replies to their comments; opening or converting the draft pull request; posting a review on it; pushing the fixes for that review with replies to its comments; pushing fixes for its failing CI checks; and marking it ready.
在 dispatch 任何 Agent 之前先询问。
  1. **Settings。**打印 effort 及其来源、Plan Approval，以及 Preset（如果存在）。然后打印一张包含六个 Agent 的表：每个 Agent 的 provider、model 和来源——run、Seats、Agents、Preset 或 fallback。如果某个 Agent 下的 seat 解析结果不同，应单独列出。在 low effort 下，将 Implementers 标为"not used at this effort"；在 low effort 下，将 Task Reviewers 标为"final review only"；在低于 high 的 effort 下，将 PR Code Reviewer 标为"not used at this effort"，而不是直接省略它们。
    将每个解析后的 model 与其 provider 当前接受的 model 进行核对——对照你所在平台的 model options 或 spawn allowlist。如果 provider 不接受该值，则停止运行：指出 Agent、seat、值以及值的来源。这也包括来自其他平台的确切名称，以及其 provider 没有对应列的 tier。
    **当 Review Agent 解析为 
    codex:
    时，**在 dispatch 任何 Agent 之前检查 Codex：
    codex --version
    成功；
    codex login status
    以 0 退出；已为 Codex 安装 
    review-prs
    ——位于 repository 的 
    .agents/skills/
    、
    ~/.agents/skills/
    或 
    $CODEX_HOME/skills/
    （默认为 
    ~/.codex/skills/
    ）；在 high effort 下，当代码检查运行时，Superpowers 的 
    requesting-code-review
    也必须以相同方式为 Codex 安装，并且 Codex 的 multi-agent feature 已开启（
    codex features
    ），以便代码检查能够使用自己的 model；此外，review 解析出的每个不同 Codex model 都必须能够以 0 退出并回复：
    bash
    codex exec --ephemeral -s read-only -m "<model>" "Reply with the single word OK."
    任何检查失败都要停止运行：指出 Agent、值以及值的来源。如果没有 Codex Reviewer，则不检查这些内容。完成下方的提问和 overrides 后，并在用户确认前的最终表格阶段，再次运行本步骤中的所有检查——包括 Codex 检查——这样一旦回答启用了 Codex，就会在任何 Agent 启动前完成检查。
    询问文件中没有确定的内容：运行参数中没有指定 effort 时询问 effort；文件中没有 Plan Approval 行时询问 Plan Approval；询问 models。如果没有 
    docs/agents/delivery.md
    ，只需说明一次可选的 
    setup-delivery
    skill 可以提前保存这些 settings，然后先询问 Preset——
    budget
    、
    balanced
    、
    max
    或 "set each agent"；选择后者时，在一个问题中询问全部六个 Agent。如果文件未设置 implementer，则像之前一样询问；该回答设置的是 implementer seat，而不是 Implementers Agent，并且不会触发 escalation 升档。当一个值通过 tier 解析，但对应 provider 没有 Tiers 列时——没有文件时始终如此——一次询问该 provider 的 cheap、standard 和 strong models，并将其纳入保存选项。只提供你的 dispatch 所接受的 models，绝不提供从其他地方记住的名称。如果你的平台无法为每次 dispatch 单独设置 model，请说明这一点，并对每个 seat 使用其默认 model。然后询问本次运行是否使用这些 settings，或者仅为本次运行覆盖其中某些设置。
    **使用文字指定 Overrides。**来自请求的运行 override 只能按以下词汇映射到 Agent："plans" → Planner；"builds" 或 "executes" → Implementers；"leads the build" → Build Lead；"reviews tasks" → Task Reviewers；"reviews" 或 "reviews the PR" → Review Agent；"reviews the code" → PR Code Reviewer。打印 Agent 表，并将被覆盖的行标为来源 "run"；只有用户确认打印出的表格后，运行才能开始。
    如果询问了任何内容，应主动提出将其保存到 
    docs/agents/delivery.md
    ：展示文件 diff，并且只有用户回答 yes 后才写入。某次运行的 overrides 只有在用户明确要求时才能保存。
  2. **Sequential 还是 Parallel？**Sequential 每次处理一个 Issue。Parallel 最多同时运行 N 个——请询问 N，并建议设为 3。只有当你的平台可以同时运行多个 dispatched Agent 时，才提供 Parallel 选项。无论采用哪种方式，一个 Issue 从 dispatch 开始直到停止都会保留自己的位置：等待 Plan Approval、标记为 ready，或结束。
打印出的队列和用户的回答构成对整次运行的许可——针对每个 Issue：push 其 branch；打开 draft Plan Pull Request，并在缺少时创建 
plan-approved
label；push Plan 修订并回复其评论；打开或转换 draft Pull Request；在其上发布 review；push 该 review 的修复并回复其评论；push 其失败 CI checks 的修复；以及将其标记为 ready。

Stage 3 — Plan

Stage 3 — Plan

For each issue to plan, create its branch and worktree, then dispatch its planner:
  • Branch: 
    fix/<ref>-<slug>
    for an issue labeled as a bug, otherwise 
    feat/<ref>-<slug>
    . 
    <ref>
    is the issue's reference without 
    #
    (
    42
    , 
    PROJ-123
    ); 
    <slug>
    is the title lowercased, each run of characters outside 
    a-z0-9
    replaced by 
    -
    , trimmed to 40 characters.
  • Worktree: 
    .worktrees/<ref>-<slug>
    , created with git from the base branch, or from the dependency's branch. Keep 
    .worktrees/
    out of commits: if 
    git check-ignore -q .worktrees
    fails, add it to 
    .git/info/exclude
    .
    bash
    git worktree add -b "<branch>" ".worktrees/<ref>-<slug>" "origin/<base>"
  • Planner: fill in 
    assets/planner-brief.md
    with no plan pull request, and dispatch it as a background agent on the planner seat.
For each plan to revise, reuse the issue's worktree when it is clean; otherwise create one from the pushed branch (
git worktree add ".worktrees/<ref>-<slug>" "<branch>"
). Count the revision rounds already done — the conversation comments on the plan pull request that hold 
<!-- implement-issues: plan revision -->
. At the effort's cap, leave it waiting and record why. Otherwise dispatch a planner from 
assets/planner-brief.md
, naming the plan pull request.
When a planner reports:
  1. BLOCKED
    or 
    NEEDS_DESIGN_SESSION
    , or no commits on the branch: no pull request. Keep the worktree and record why.
  2. A revision: confirm it pushed and replied, then post a conversation comment on the plan pull request — `Plan revision <n> of <cap>. <!-- implement-issues: plan revision -->` — and leave it waiting.
  3. Plan approval on: push the branch and open a draft plan pull request — 
    gh pr create --draft
    , title 
    plan: <issue title> (<reference>)
    , body from 
    assets/plan-pr-body.md
    , base the base branch or the dependency's branch. Create the 
    plan-approved
    label first if 
    gh label list
    doesn't show it. Leave the issue waiting.
  4. Plan approval off: go straight to Stage 4 with the planner's spec and plan.
对于每个需要 plan 的 Issue，创建其 branch 和 worktree，然后 dispatch 其 Planner：
  • **Branch：**如果 Issue 被标记为 bug，则使用 
    fix/<ref>-<slug>
    ，否则使用 
    feat/<ref>-<slug>
    。
    <ref>
    是去掉 
    #
    的 Issue reference（例如 
    42
    、
    PROJ-123
    ）；
    <slug>
    是将 title 转为小写后，把每一段 
    a-z0-9
    之外的字符替换为 
    -
    ，并截取到 40 个字符。
  • Worktree：
    .worktrees/<ref>-<slug>
    ，使用 git 从 base branch 或依赖项的 branch 创建。不要将 
    .worktrees/
    提交进去：如果 
    git check-ignore -q .worktrees
    失败，将其添加到 
    .git/info/exclude
    。
    bash
    git worktree add -b "<branch>" ".worktrees/<ref>-<slug>" "origin/<base>"
  • **Planner：**使用没有 Plan Pull Request 的 
    assets/planner-brief.md
    填充内容，并以 background Agent 形式在 planner seat 上 dispatch。
对于每个需要 revise the plan 的 Issue，如果其 worktree 干净则直接复用；否则从已 push 的 branch 创建一个（
git worktree add ".worktrees/<ref>-<slug>" "<branch>"
）。统计已经完成的修订轮次——即 Plan Pull Request 的 conversation comments 中包含 
<!-- implement-issues: plan revision -->
的评论数量。达到当前 effort 的上限时，将其留在 waiting 状态并记录原因。否则，从 
assets/planner-brief.md
dispatch 一个 Planner，并指明 Plan Pull Request。
当 Planner 报告以下结果时：
  1. BLOCKED
    或 
    NEEDS_DESIGN_SESSION
    ，或者 branch 上没有 commits：不创建 Pull Request。保留 worktree 并记录原因。
  2. **一次修订：**确认其已 push 并回复后，在 Plan Pull Request 上发布一条 conversation comment——`Plan revision <n> of <cap>. <!-- implement-issues: plan revision -->`——并将其留在 waiting 状态。
  3. **Plan Approval on：**push branch 并打开一个 draft Plan Pull Request——
    gh pr create --draft
    ，title 为 
    plan: <issue title> (<reference>)
    ，body 来自 
    assets/plan-pr-body.md
    ，base 为 base branch 或依赖项的 branch。如果 
    gh label list
    没有显示 
    plan-approved
    ，则先创建该 label。将该 Issue 留在 waiting 状态。
  4. **Plan Approval off：**直接进入 Stage 4，使用 Planner 的 spec 和 plan。

Stage 4 — Build

Stage 4 — Build

For each issue to build, reuse its worktree when it is clean, or create one from the pushed branch. Fill in 
assets/build-brief.md
and dispatch it as a background agent on the build-lead seat. Sequential: one issue at a time. Parallel: up to N at once, starting the next as each one ends. Keep each build lead's identity; Stages 5 and 8 may message it.
对于每个需要 build 的 Issue，如果其 worktree 干净则复用，否则从已 push 的 branch 创建一个。使用 
assets/build-brief.md
填充内容，并以 background Agent 形式在 build-lead seat 上 dispatch。Sequential：每次一个 Issue。Parallel：最多同时 N 个，并在每个 Issue 结束时启动下一个。保持每个 Build Lead 的身份；Stage 5 和 Stage 8 可以向它发送消息。

Stage 5 — Verify each built issue

Stage 5 — Verify each built issue

When a build lead reports:
  1. A 
    BLOCKED
    or 
    NEEDS_DESIGN_SESSION
    report, or no new commits on the branch, means no pull request. Keep the worktree and record why.
  2. Check the work yourself inside its worktree: read 
    git log origin/<base>..HEAD
    and the diff, and run the project's test, lint, and typecheck commands (from 
    AGENTS.md
    or the project's manifest). Write each command's output to a log file under the worktree's git directory and read back its exit code, its summary, and the tail of any failure — not the whole log. An agent's "tests pass" is a claim, not evidence.
  3. If a check fails, send the same build lead one message with the failures, then verify again. Still failing: no pull request; record the failure.
当 Build Lead 报告以下结果时：
  1. 报告 
    BLOCKED
    或 
    NEEDS_DESIGN_SESSION
    ，或者 branch 上没有新的 commits，意味着不创建 Pull Request。保留 worktree 并记录原因。
  2. 亲自在其 worktree 中进行检查：阅读 
    git log origin/<base>..HEAD
    和 diff，并运行项目的 test、lint 和 typecheck 命令（来自 
    AGENTS.md
    或项目 manifest）。将每条命令的输出写入 worktree 的 git 目录下的日志文件，并读回其 exit code、summary 和任何失败的末尾部分——无需读取完整日志。Agent 所说的 "tests pass" 只是一个声明，不是证据。
  3. 如果某项检查失败，将失败信息通过一条消息发送给同一个 Build Lead，然后再次验证。如果仍然失败：不创建 Pull Request；记录失败原因。

Stage 6 — Open the draft pull request

Stage 6 — Open the draft pull request

Land each verified branch through 
finishing-a-development-branch
. Its menu is already answered — push and create a pull request, as a draft — so don't wait on it. Below high effort, Stage 5's check run is its Step 1 when HEAD hasn't moved since.
  • Title: Conventional Commit form ending with the issue's reference, for example 
    feat: confirm waitlist emails (#42)
    .
  • Body: fill in 
    assets/pr-body.md
    . Its link line comes from the tracker's Linking section. First judge each item the report left undone yourself: one no change to this repository can do is a follow-up, and follow-ups never make the work partial. With nothing else left undone, write the finishing reference (on GitHub, 
    Closes #42
    ); otherwise the partial reference (
    Relates to #42
    ) followed by what is left. A tracker whose Finishing PR is None has no finishing reference: write the partial reference, and say whether the work fully resolves the issue. This is 
    superpowers-issue-bridge
    's rule for unattended runs.
  • Base: the base branch, or the dependency's branch for a dependent issue.
  • An approved plan pull request is this issue's pull request: push to its branch, then give it the title and body above with 
    gh pr edit <number> --title <title> --body-file <file>
    . It stays a draft.
Keep each worktree after its pull request opens — review fixes happen there.
通过 
finishing-a-development-branch
完成每个已验证 branch 的收尾。它的 menu 已经回答完毕——push 并创建一个 draft Pull Request——因此不要等待它。在低于 high 的 effort 下，如果 HEAD 自 Stage 5 以来没有移动，Stage 5 的 check run 就是它的 Step 1。
  • **Title：**使用 Conventional Commit 格式，并以 Issue reference 结尾，例如 
    feat: confirm waitlist emails (#42)
    。
  • **Body：**填充 
    assets/pr-body.md
    。其 link line 来自 tracker 的 Linking 部分。首先自行判断报告中每个未完成项：如果 repository 内无需任何改动即可处理，则它属于 follow-up；follow-up 不会使工作变成部分完成。如果不存在其他未完成项，则写入 finishing reference（在 GitHub 上为 
    Closes #42
    ）；否则写入 partial reference（
    Relates to #42
    ），并说明还剩下什么。如果 tracker 的 Finishing PR 为 None，则没有 finishing reference：写入 partial reference，并说明该工作是否完整解决了 Issue。这是 
    superpowers-issue-bridge
    对无人值守运行的规则。
  • **Base：**base branch；对于依赖 Issue，则使用其依赖项的 branch。
  • 已批准的 Plan Pull Request就是该 Issue 的 Pull Request：push 到其 branch，然后使用上述 title 和 body 执行 
    gh pr edit <number> --title <title> --body-file <file>
    。它仍然是 draft。
每个 Pull Request 打开后都要保留其 worktree——review 修复将在其中进行。

Stage 7 — Review the pull request

Stage 7 — Review the pull request

Dispatch a new agent on the pr-reviewer seat — never the planner or the build lead — to run 
review-prs #<number>
on 
<owner/repo>
, telling it:
  • the user's go-ahead for this run covers posting the review;
  • below high effort, the code pass is off, because the build's whole-branch review already covered the code;
  • at high effort, the code pass's model: the PR code reviewer's resolved model, which comes first in 
    review-prs
    ' own order.
It posts its findings as comments on the pull request and reports the review's URL. A review changes nothing locally, so it can run while other issues build.
When the Review agent is on Codex, run the review yourself through the Codex CLI instead of dispatching an agent:
  1. Gather the context into 
    <worktree git dir>/implement-issues/review-<number>/
    : 
    pr.json
    from 
    gh pr view <number> --json number,url,title,body,baseRefName,headRefOid
    , 
    comments.json
    from 
    gh api --paginate repos/<owner>/<repo>/pulls/<number>/comments
    , and 
    issue.md
    with the linked intent issue's body, read with the tracker's Reading method — left out when the pull request links none. In the worktree, run 
    git fetch origin <base> pull/<number>/head
    .
  2. Fill in 
    assets/review-brief.md
    as 
    brief.md
    in that directory, with the code pass off below high effort and the PR code reviewer's resolved Codex model. Run, in the background:
    bash
    codex exec -C "<worktree>" -m "<Review agent's resolved Codex model>" -s read-only --json \
  -o "<context dir>/report.md" - < "<context dir>/brief.md"
  3. When it exits, 
    report.md
    must hold exactly one fenced 
    json
    block. Write it to 
    review.json
    in the same directory, set its 
    "event": "COMMENT"
    whatever it says, and check that its 
    commit_id
    is 
    pr.json
    's 
    headRefOid
    — a different commit posts nothing. Then post it: 
    gh api --method POST repos/<owner>/<repo>/pulls/<number>/reviews --input <context dir>/review.json
    . Read the review's URL from the response.
  4. No block, more than one, a non-zero exit, or a failed post: post nothing, leave the pull request a draft, and record why.
Read Codex's token counts from its 
--json
events for the report when they include them. Everything after the review is the same as for any review agent.
No review posted: leave the pull request a draft and record why. A review with no findings: go to Stage 8, step 3.
在 pr-reviewer seat 上 dispatch 一个新的 Agent——绝不能使用 Planner 或 Build Lead——让它对 
<owner/repo>
运行 
review-prs #<number>
，并告知它：
  • 用户对本次运行的许可涵盖发布 review；
  • 在低于 high 的 effort 下，代码检查关闭，因为 build 的整分支 review 已经覆盖了代码；
  • 在 high effort 下，提供 PR Code Reviewer 解析后的 model；该 model 首先由 
    review-prs
    自身的顺序决定。
它会将发现作为 comments 发布到 Pull Request 上，并报告 review 的 URL。Review 不会在本地修改任何内容，因此可以在其他 Issues build 时并行运行。
**当 Review Agent 位于 Codex 上时，**不要 dispatch Agent，而是亲自通过 Codex CLI 运行 review：
  1. 将上下文收集到 
    <worktree git dir>/implement-issues/review-<number>/
    ：
    pr.json
    来自 
    gh pr view <number> --json number,url,title,body,baseRefName,headRefOid
    ，
    comments.json
    来自 
    gh api --paginate repos/<owner>/<repo>/pulls/<number>/comments
    ，
    issue.md
    包含关联意图 Issue 的正文，并使用 tracker 的 Reading method 读取——如果 Pull Request 没有关联 Issue，则省略该文件。在 worktree 中运行 
    git fetch origin <base> pull/<number>/head
    。
  2. 使用 
    assets/review-brief.md
    填充该目录中的 
    brief.md
    ，在低于 high effort 时关闭代码检查，并提供 PR Code Reviewer 解析后的 Codex model。在后台运行：
    bash
    codex exec -C "<worktree>" -m "<Review agent's resolved Codex model>" -s read-only --json \
  -o "<context dir>/report.md" - < "<context dir>/brief.md"
  3. 退出后，
    report.md
    必须恰好包含一个 fenced 
    json
    block。将其写入同一目录中的 
    review.json
    ，无论其内容如何，都将其 
    "event": "COMMENT"
    ，并检查其 
    commit_id
    是否等于 
    pr.json
    中的 
    headRefOid
    ——如果 commit 不同，则不发布任何内容。然后发布它： 
    gh api --method POST repos/<owner>/<repo>/pulls/<number>/reviews --input <context dir>/review.json
    。 从响应中读取 review 的 URL。
  4. 如果没有 block、存在多个 block、退出码非零或发布失败：不发布任何内容，将 Pull Request 保留为 draft，并记录原因。
如果 report 的 
--json
events 包含 token counts，则读取 Codex 的 token 用量。Review 之后的所有步骤与使用其他 Review Agent 时完全相同。
没有发布 review：将 Pull Request 保留为 draft，并记录原因。Review 没有 findings：进入 Stage 8 的第 3 步。

Stage 8 — Answer the review and mark it ready

Stage 8 — Answer the review and mark it ready

  1. Message the build lead — or, if it can no longer be messaged, dispatch a new one on the build-lead seat into the same worktree — to run 
    answer-pr-reviews #<number>
    on 
    <owner/repo>
    in that worktree, telling it the user's go-ahead for this run covers pushing the fixes and replying to each comment.
  2. At medium and high effort, verify the pushed head with 
    verification-before-completion
    , running Stage 5's checks yourself. If one fails, send the build lead the failures once, then check again. At low effort, CI is the evidence for the review fixes; run Stage 5's checks only when the pull request has no CI.
  3. Wait for the pull request's CI checks on the pushed head — 
    gh pr checks <number> --watch
    . When it reports no checks, there is nothing to wait for. Passing locally is not passing CI: a check can fail only there, on a different runtime, a missing variable, or a step the project's local commands skip. When one fails, send the build lead the failing check's name and log (
    gh run view <run-id> --log-failed
    ), asking it to fix, commit, and push this branch — never force. Then run step 2 again and wait for CI again, up to the effort's CI fix attempts.
  4. Mark the pull request ready — 
    gh pr ready <number>
    — once the checks pass and every review comment has a reply. It stays a draft, and you record why, when the checks still fail or a finding that holds was left unfixed.
  1. 向 Build Lead 发送消息——如果已无法向它发送消息，则在同一个 worktree 中、build-lead seat 上 dispatch 一个新的 Agent——让它在 worktree 中对 
    <owner/repo>
    运行 
    answer-pr-reviews #<number>
    ，并告知它，用户对本次运行的许可涵盖 push 修复以及回复每条评论。
  2. 在 medium 和 high effort 下，使用 
    verification-before-completion
    验证已 push 的 HEAD，并亲自运行 Stage 5 的 checks。如果某项检查失败，将失败信息发送给 Build Lead 一次，然后再次检查。在 low effort 下，CI 是 review 修复的证据；仅在 Pull Request 没有 CI 时才运行 Stage 5 的 checks。
  3. 等待已 push HEAD 上的 Pull Request CI checks——
    gh pr checks <number> --watch
    。如果它报告没有 checks，则无需等待。本地通过不等于 CI 通过：某项检查可能只在 CI 中失败，原因包括不同的 runtime、缺少变量，或项目的本地命令跳过了某个步骤。如果某项检查失败，将失败 check 的名称和日志（
    gh run view <run-id> --log-failed
    ）发送给 Build Lead，要求它修复、commit 并 push 此 branch——绝不能 force push。然后再次执行第 2 步并重新等待 CI，最多尝试当前 effort 规定的 CI 修复次数。
  4. 只有当 checks 通过且每条 review comment 都已回复时，才将 Pull Request 标记为 ready——
    gh pr ready <number>
    。如果 checks 仍然失败，或存在未修复的实质性 finding，则将其保留为 draft，并记录原因。

Stage 9 — Report

Stage 9 — Report

One table: issue, branch, pull request URL or the reason there is none, state (waiting on plan approval, ready, or draft and why), checks result locally and in CI, review findings by severity with how many were fixed, and how many decisions the agents made. Above it, the run's effort and plan approval and the preset; under it, each agent with its provider and the model each of its seats ran on, with token use or time per agent where the provider reports them. Then list every issue waiting or skipped in Stage 1, and why.
A pull request with the partial reference leaves its issue open when it merges. For each one that left work undone, ask the user once, naming that work: does it fully resolve the issue? On yes, swap its link line for the finishing reference (
gh pr edit <number> --body-file <file>
) and keep what was left undone as follow-ups.
A tracker with no finishing reference — local markdown, or a Jira or Trello board that no integration closes — has no link line to swap. For each pull request that fully resolves its issue, including each yes above, give the user the tracker's Close-by-hand step to run once it merges.
输出一张表：Issue、branch、Pull Request URL 或没有 PR 的原因、状态（等待 Plan Approval、ready，或 draft 及其原因）、本地和 CI checks 结果、按严重程度划分的 review findings 及其修复数量，以及 Agents 作出的决策数量。在表格上方，列出本次运行的 effort、Plan Approval 和 Preset；在表格下方，列出每个 Agent 及其 provider，以及每个 seat 使用的 model，并在 provider 提供相应数据时列出 token 用量或耗时。然后列出 Stage 1 中所有 waiting 或 skipped 的 Issues 及其原因。
使用 partial reference 的 Pull Request 在 merge 后仍会让其 Issue 保持开放。对于每个仍有未完成工作的 Pull Request，只询问用户一次并明确指出这些工作：它是否完整解决了 Issue？如果回答 yes，将 link line 替换为 finishing reference（
gh pr edit <number> --body-file <file>
），并仍将未完成部分保留为 follow-ups。
对于没有 finishing reference 的 tracker——例如本地 Markdown，或没有 integration 可关闭 Issue 的 Jira 或 Trello board——没有需要替换的 link line。对于每个完整解决其 Issue 的 Pull Request，包括上面所有回答 yes 的 Pull Request，向用户提供 tracker 的 Close-by-hand 步骤，以便在 merge 后执行一次。

What NOT to do

What NOT to do

  • Don't merge, enable auto-merge, or approve a pull request — marking it ready hands it to the user, who accepts the work.
  • Don't let a Codex agent write — run it only with 
    -s read-only
    , and post its review yourself. Don't post a Codex review unless its reply holds exactly one fenced 
    json
    block.
  • Don't read a run override's wording any other way than Stage 2's vocabulary, and don't start before the user confirms the printed agents table.
  • Don't push the base branch, and never force-push.
  • Don't take an agent's report as proof — run the checks yourself before the first push, at every effort.
  • Don't open a pull request for an issue that already has one, other than converting its approved plan pull request.
  • Don't build from a plan pull request without the 
    plan-approved
    label, and don't add that label yourself — approval is the user's.
  • Don't offer or dispatch a model your platform's dispatch doesn't accept, and don't fall back to another model silently.
  • Don't write a model name into this skill or its assets; model names live only in 
    docs/agents/delivery.md
    , as the user's choice.
  • Don't save settings to 
    docs/agents/delivery.md
    without showing the diff and receiving a yes.
  • Don't write the finishing reference while work this repository could do is left undone, unless the user says in Stage 9 that the pull request fully resolves the issue. Don't write the partial reference for follow-ups alone.
  • Don't open a pull request whose Decisions section is missing or vague — it is the only place the user sees the choices an agent made for them.
  • Don't have the planner or the build lead review their own pull request.
  • Don't mark a pull request ready while a review comment is unanswered or the checks fail on the pushed head — locally or in CI.
  • 不要 merge、启用 auto-merge 或 approve Pull Request——标记为 ready 只是将其交给用户，由用户接受工作。
  • 不要让 Codex Agent 写入内容——仅使用 
    -s read-only
    运行它，并由你亲自发布其 review。如果 Codex 的回复不是恰好包含一个 fenced 
    json
    block，不要发布其 Codex review。
  • 除了 Stage 2 的词汇表之外，不要以其他任何方式解读运行 override 的措辞，并且不要在用户确认打印出的 Agent 表格之前开始运行。
  • 不要 push base branch，绝不要 force-push。
  • 不要把 Agent 的报告当作证据——在首次 push 前以及所有 effort 下，都要亲自运行 checks。
  • 不要为已有 Pull Request 的 Issue 再创建 Pull Request，转换已批准的 Plan Pull Request 除外。
  • 不要在没有 
    plan-approved
    label 的情况下从 Plan Pull Request 开始 build，也不要自行添加该 label——批准权属于用户。
  • 不要提供或 dispatch 平台 dispatch 不接受的 model，也不要悄悄回退到另一个 model。
  • 不要把 model 名称写入这个 skill 或其 assets；model 名称只能保存在 
    docs/agents/delivery.md
    中，由用户选择。
  • 不要在未展示 diff 且未获得用户 yes 的情况下，将 settings 保存到 
    docs/agents/delivery.md
    。
  • 不要在 repository 本可完成的 work 仍有未完成项时写入 finishing reference，除非用户在 Stage 9 中说明该 Pull Request 完整解决了 Issue。不要仅为 follow-ups 写入 partial reference。
  • 不要打开缺少 Decisions 部分或其内容含糊的 Pull Request——这是用户唯一能看到 Agent 代其所作选择的地方。
  • 不要让 Planner 或 Build Lead review 自己创建的 Pull Request。
  • 不要在仍有未回复的 review comment，或已 push HEAD 上的 checks——无论本地还是 CI——失败时，将 Pull Request 标记为 ready。