Help us improve
Share bugs, ideas, or general feedback.
From spectra
[DEPRECATED] codex-only 強化版。新 session 請依規模選擇:小型 PR 用 `/pr-review-cycle`(Claude-only,4 subagent 平行);中大型或高風險 PR 用 `/pr-review-cycle-mob`(mob review by multiple frontier-model agents,自動 偵測 codex / gemini / 本地 open-weights,≥2 家可用即啟動 debate + aggregate)。 本 skill 內容保留供既有 session / muscle memory 不中斷。 觸發情境:「跑 PR cycle + codex」「pr-review-cycle-codex」「PR 流程加 cross-model review」「cross model review」「jira sync」「spectra archive」
npx claudepluginhub howie/yibi-stack --plugin spectraHow this skill is triggered — by the user, by Claude, or both
Slash command
/spectra:pr-review-cycle-codexThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
> **[DEPRECATED]** 本 skill 為 codex-only 強化版的早期設計。新 session 請依規模選擇:
Guides Next.js Cache Components and Partial Prerendering (PPR): 'use cache' directives, cacheLife(), cacheTag(), revalidateTag() for caching, invalidation, static/dynamic optimization. Auto-activates on cacheComponents: true.
Processes PDFs: extracts text/tables/images, merges/splits/rotates pages, adds watermarks, creates/fills forms, encrypts/decrypts, OCRs scans. Activates on PDF mentions or output requests.
Share bugs, ideas, or general feedback.
[DEPRECATED] 本 skill 為 codex-only 強化版的早期設計。新 session 請依規模選擇:
- 小型 PR / 快速合併 →
/pr-review-cycle(Claude-only,4 subagent 平行)- 中大型或高風險 PR →
/pr-review-cycle-mob(mob review,自動偵測 codex / gemini / open-weights,≥2 家啟動 debate)本檔案內容保留是為了不中斷既有 muscle memory,未來會移除。
延伸 /pr-review-cycle,在合併前追加 OpenAI Codex 的獨立 review + adversarial challenge,
以 cross-model 第二意見補強 Claude 系 reviewer 可能集體錯過的盲點。
Step 1–6 與 /pr-review-cycle 完全相同;本 skill 新增 Step 7–8,將 merge 移至 Step 9,收尾 Spectra Archive + Jira Sync 為 Step 10。
/pr-review-cycle-codex
/pr-review-cycle-codex #<PR number> ← 已有 PR 時直接跳 Step 2
Steps 1–6 可能需要 20–40 分鐘,請先執行以下確認,任一不符就停止並修正後再開始:
# bash call 1:確認 binary
which codex 2>/dev/null && echo "PREREQ: BINARY_OK" || echo "PREREQ: NOT_FOUND -- stop here"
# bash call 2(BINARY_OK 後執行):確認 API key(無 key 時 exit 0,不阻斷流程)
env | grep -qE '^(CODEX_API_KEY|OPENAI_API_KEY)=.' && echo "AUTH: KEY_SET" || true
# bash call 3(call 2 無輸出時執行):確認 auth.json(預設路徑 ~/.codex;自訂 CODEX_HOME 見 FAQ)
test -f ~/.codex/auth.json && echo "AUTH: FILE_EXISTS" || echo "AUTH: NOT_AUTHED"
| 輸出 | 處理 |
|---|---|
PREREQ: NOT_FOUND | npm install -g @openai/codex;或退回 /pr-review-cycle |
AUTH: NOT_AUTHED | codex login(或設 $OPENAI_API_KEY) |
AUTH: FILE_EXISTS | 繼續,但 auth.json 存在不代表 token 有效;若 Step 7 報 auth 錯誤,執行 codex login 更新 |
PREREQ: BINARY_OK + AUTH: KEY_SET 或 FILE_EXISTS | 繼續 Step 1 |
/pr-review-cycle 執行完全照 /pr-review-cycle 的 Step 1–6 執行,不重複描述。
{{pr_number}} 為 Step 1 建立 PR 後取得的 PR 編號,後續步驟均使用此值。
| Step | 內容 |
|---|---|
| 1 | 建立 PR(commit + push + gh pr create) |
| 2 | Simplify(/simplify,作為獨立 commit) |
| 3 | Parallel review(4 個 Claude agent) |
| 4 | Fix(Critical → Important) |
| 5 | Re-review |
| 6 | CI Check(gh pr checks {{pr_number}} --watch) |
CI 全綠後才進 Step 7。
CI 全綠後,選擇以下其中一條路徑執行 cross-model review:
| 路徑 | 指令 | 適用情境 |
|---|---|---|
| A:Codex Review + Challenge(原有流程) | Skill(skill="codex", args="review") | 本地 codex CLI 可用、需要 adversarial challenge |
| B:claude ultrareview(新選項) | claude ultrareview {{pr_number}} | codex 不可用、CI 非互動式環境、需要雲端並行 multi-agent review |
路徑 B:claude ultrareview
claude ultrareview {{pr_number}}
注意:
claude ultrareview為付費功能(billed),執行前確認使用者已授權計費。 選擇路徑 B 後,跳過 Step 7 / Step 8,直接進 Step 9(Merge)。 ultrareview 輸出已包含 review findings;Critical findings 處理方式與 Step 7 GATE: FAIL 相同。
選擇路徑 A 繼續以下 Step 7。
觸發方式:Skill(skill="codex", args="review")(codex skill 以 args 做 mode 偵測)
Codex 會對 PR 的完整 branch diff 做 review,輸出包含 [P1](Critical)/ [P2](Important)
分級的 findings,末尾顯示 PASS/FAIL gate,並輸出一行 Recommendation: 摘要。
若 codex skill 本身失敗(auth / binary 錯誤):展示錯誤訊息給使用者 → 回到「前置需求」 重新確認 → 不可視為 GATE: PASS 繼續前進。
若 codex skill 因 flag 衝突失敗(錯誤訊息含 [PROMPT] cannot be used with --base):
codex review 的 --base 與 positional [PROMPT] 互斥。直接執行 fallback:
codex review --base {{base_branch}} -c 'model_reasoning_effort="high"'
codex review 不支援 -C flag,從正確 cwd 執行即可。--base 已足夠讓 codex 找到 diff,不需要額外 prompt。輸出格式與 Skill 觸發相同,[P1]/[P2] gate 判定不變。
解讀 gate 結果:
GATE: PASS → 向使用者展示 Recommendation: 行與 cross-model analysis(哪些是 Claude
沒抓到、Codex 抓到的),然後進 Step 8。
GATE: FAIL(N critical findings):
[P1] finding,附 codex 的說明與 Recommendation: 行[P1]Codex 修正後不必重跑 Step 3 / Step 5(修正範圍由 Codex finding 界定); 若修正涉及 3 個以上新檔案,則回 Step 5 重跑 Claude review。
Circuit breaker:若重試達 3 次仍 GATE: FAIL,停止自動重試,向使用者呈現持續出現的
[P1] findings,詢問:「誤判、還是需要更多修改時間、還是退回重新設計 PR?」等待明確指示後才繼續。
誤判處理(使用者聲明 finding 不成立):
觸發方式:Skill(skill="codex", args="challenge")
Codex 以「破壞者」視角嘗試找出 race condition、security hole、資源洩漏、資料靜默損毀等問題。
此模式無形式化 gate,輸出含 [codex thinking] 推理行與最終散文分析 + Recommendation: 行;
agent 分類 findings 時以最終散文為準,忽略 [codex thinking] 推理行。
若 codex skill 的 --json streaming 無輸出:改用 Write tool 寫 prompt 再 stdin 傳入的 fallback(去掉 --json flag):
用 Write tool 把 prompt 寫到 /tmp/codex-challenge-prompt.txt:
Review the git diff against {{base_branch}} and find adversarial problems.
Run git diff {{base_branch}}...HEAD to see the diff.
Find edge cases, race conditions, security holes, resource leaks, silent data corruption.
Be adversarial. No compliments.
WT=$(git rev-parse --show-toplevel)
codex exec -C "$WT" -s read-only -c 'model_reasoning_effort="high"' < /tmp/codex-challenge-prompt.txt 2>&1
rm -f /tmp/codex-challenge-prompt.txt
Agent 分級 findings:
| 嚴重度 | 特徵 | 處置 |
|---|---|---|
| Critical | race condition、security hole、auth bypass、silent data corruption | 強烈建議修;使用者以明確語句(「knowingly ship」「已知悉、接受風險」等)拒絕才放行 |
| Important / Minor | edge case、資源管理、效能問題 | 列入 PR description 留紀錄,不阻擋 merge |
若使用者給出模糊回應(「之後再修」「先這樣」),不構成明確拒絕,需再次確認: 「這個 Critical finding 我會記錄為 knowingly shipped。請確認:你理解此風險並接受在此次 PR 中不修正?」
把完整 challenge 輸出貼到 PR comment:
用 Write tool 把 challenge 輸出寫入 /tmp/codex-challenge-report.md,格式如下:
## Codex Challenge Report
<challenge 完整輸出>
---
*Generated by /pr-review-cycle-codex Step 8*
gh pr comment {{pr_number}} --body-file /tmp/codex-challenge-report.md
rm -f /tmp/codex-challenge-report.md
若使用者拒絕修 Critical finding,在 PR description 補上 Known Issues 段落:
CURRENT_BODY=$(gh pr view {{pr_number}} --json body -q .body 2>/dev/null)
if [ -z "$CURRENT_BODY" ]; then
echo "ERROR:gh pr view 失敗,無法讀取 PR description。請手動在 PR 補上 Known Issues。"
else
TMPFILE=$(mktemp)
printf '%s\n\n---\n## Codex Challenge -- Known Issues\n- <finding 摘要>:knowingly shipped -- <使用者提供的原因>\n' \
"$CURRENT_BODY" > "$TMPFILE"
gh pr edit {{pr_number}} --body-file "$TMPFILE"
rm -f "$TMPFILE"
fi
Pre-merge 確認:版本 bump
執行 gh pr merge 之前,先暫停並向使用者確認:
此次變更是否需要 bump 版本?
- 需要 → 請先執行
/bump-version(會在 feature branch 上 commit 版本檔 + CHANGELOG + git tag + push)。 完成後回到 Step 6 CI Check(gh pr checks {{pr_number}} --watch,新 commit 觸發新一輪 CI),等待全綠後再回到本步驟繼續 merge。 注意:--squashmerge 後 git tag 指向 feature branch HEAD 而非 main 的 merge commit;如需 tag 指向 main,merge 後在 main 上重新 tag。- 不需要 → 確認後繼續 merge。
- 不確定 → 簡述本次變更性質,由 agent 依下方準則建議 bump 類型,等使用者確認後再執行
/bump-version或繼續 merge。
判斷準則(agent 提交使用者裁決前可先評估):
| 變更性質 | 建議 |
|---|---|
| 純內部重構、測試、CI 設定 | 通常不需要 bump |
| Bug fix、文件修正、效能調整、相容性修正 | patch |
| 新功能、新 API(向後相容) | minor |
| Breaking change(API 不相容) | major |
(判斷準則僅供快速評估,完整定義見 /bump-version Step 1)
使用者明確回應「不需要」或「已執行 /bump-version」後,才執行下一步 gh pr merge。
若使用者回應「已執行 /bump-version」,先確認 bump commit 已推送至遠端:
git fetch
git log --oneline -3 '@{upstream}'
確認近 3 筆 commit 中有一筆訊息符合 chore(release): v* 格式後再繼續;若未找到,提示使用者完成 /bump-version Step 4(push)後再回來。
從該 commit message 提取版本號(如 v1.2.3),再精確確認該版本 tag 已推送至遠端(commit push 與 tag push 是獨立操作,tag 可能靜默未推):
git ls-remote --tags origin 'refs/tags/v<TAG_VERSION>'
(例:git ls-remote --tags origin 'refs/tags/v1.2.3')
確認輸出包含精確版本 tag,而非僅有舊版 tag;若輸出為空,提示使用者執行 git push --tags。
若目標 repo 有 tag-triggered CI/CD(如 GitHub Release 自動發布):git tag 在 merge 之前就已推送,可能觸發生產部署流程。評估風險後再決定是否繼續;或改為 merge 後在 main 上重新 tag。
所有 codex 問題處理完後,squash merge 並驗證結果:
# bash call 1:執行 merge
gh pr merge {{pr_number}} --squash --delete-branch
# bash call 2:取得結果(讀輸出判斷 state 是否為 MERGED,並記下 merge commit SHA)
gh pr view {{pr_number}} --json state,mergeCommit -q '{state: .state, sha: .mergeCommit.oid}'
確認 state 為 MERGED 後,記下 sha 作為 {{merge_commit_sha}},回報給使用者。
PR merge 完成後,同步 spec 狀態與 Jira ticket,結束此開發循環。兩個小節均為選用——無 spectra change 或無 Jira issue 時直接跳過。
若本次開發循環確定未建立 spectra change,直接跳過 Step 10a。
否則,列出進行中的 change,確認是否有對應此 PR 的項目(change 名稱通常與 feature branch 名稱相近):
spectra list
若指令失敗,停止並回報錯誤給使用者,不要繼續。
若有對應 change,在執行前回報將要 archive 的 change 名稱,等待使用者確認(archive 是不可逆操作):
找到疑似對應的 spectra change:
{{change_name}}。確認執行 archive?
確認後執行:
spectra archive {{change_name}} --yes
若指令以非零退出碼結束,停止並回報錯誤給使用者。
若 validation 有 Critical 錯誤,以 spectra analyze {{change_name}} 確認問題,修正後再 archive;或由使用者明確指示才加 --no-validate 略過(agent 不可自行決定略過)。
偵測 Jira Issue Key:
merge 後 branch 已被 --delete-branch 刪除,改從 PR title / body 提取:
gh pr view {{pr_number}} --json title,body -q '.title + " " + (.body // "")'
若指令本身以非零退出碼失敗,停止並回報錯誤,詢問使用者手動提供 key。
若指令成功但輸出中無符合 [A-Z]{2,}-[0-9]+ 格式的字串(如 ABC-123),詢問使用者提供 key,或跳過 Step 10b。
取得 transitions(序列),再並行執行 transition + comment:
先呼叫 mcp__claude_ai_Atlassian__getTransitionsForJiraIssue(issueId:{{jira_issue_key}})取得 transition 清單。若呼叫失敗,停止並回報錯誤給使用者。
選擇語意最接近「已完成開發並合併」的選項(常見:Done、Merged、Released、Closed)。若不確定,詢問使用者確認後再執行。
確認 transition 後,以下兩個 MCP 呼叫可同時送出(無相依性);任一失敗均須回報,不得靜默繼續:
mcp__claude_ai_Atlassian__transitionJiraIssue:將 {{jira_issue_key}} 移至選定狀態mcp__claude_ai_Atlassian__addCommentToJiraIssue:新增以下格式 comment:PR #{{pr_number}} 已 squash merge 至 main。
Merge commit:{{merge_commit_sha}}
Codex review:GATE PASS(Step 7);Challenge report 已附於 PR comment(Step 8)。
若 Step 10a 有 archive spectra change,comment 一併附上:
Spectra change `{{change_name}}` 已 archive,spec 狀態已更新為完成。
完成後,向使用者回報:Spectra archive 狀態(已 archive / 已跳過)、Jira ticket 狀態(已 transition 至 {{selected_state}} + comment 已寫入 / 已跳過 / 失敗原因)。
下一步建議:跑
/pr-retro收尾這個 session(agent 會從 PR context 推論 5 題草稿給你校準,寫入專屬 retro tag 不污染 handover-back)。
| 問題 | 處理方式 |
|---|---|
| codex 安裝或認證問題 | 見「前置需求」表格 |
設定了自訂 CODEX_HOME,bash call 3 回報 NOT_AUTHED | bash call 3 固定查 ~/.codex/auth.json;請在 terminal 手動確認實際路徑後再繼續 |
codex review 報 [PROMPT] cannot be used with --base | --base 與 positional prompt 互斥;移除 prompt 字串,只用 codex review --base <branch> 見 Step 7 |
| codex review 跑到錯誤的 repo | codex review 不支援 -C flag;確保從 git repo 根目錄執行(AP3 Sub-class A) |
codex challenge --json 模式無輸出 | 改用 stdin fallback(不加 --json),見 Step 8 |
| codex review timeout(>5 分鐘) | 重試一次;持續失敗查 ~/.codex/logs/ |
| codex challenge timeout(>10 分鐘) | 重試一次;持續失敗查 ~/.codex/logs/ |
| codex review FAIL 但確認是誤判 | 在 PR description 記錄理由 + reviewer 確認,agent 不可自行 override |
| codex review 連續 3 次 FAIL | 觸發 circuit breaker,停止重試,詢問使用者:誤判 / 需更多時間 / 退回重新設計 |
| codex review PASS 但 challenge 找到 Critical | 依 Step 8 分級處置;Critical 需使用者明確拒絕才能 knowingly ship |
codex 跑去讀 .claude/skills/ 噪音檔案 | codex skill 內建 filesystem boundary 防護;若仍發生,建議重跑 |
| 想跳過 challenge 只跑 review | 用 /pr-review-cycle;本 skill 是「全套 cross-model 強化」入口,不提供半套選項 |
| codex 無法使用、想用 claude ultrareview | 在 Step 6.5 選擇路徑 B,執行 claude ultrareview {{pr_number}};路徑 B 跳過 Step 7/8 |
| claude ultrareview 報計費錯誤 | ultrareview 為付費功能,確認帳戶已授權後重試 |
| Step 1–6 遇到問題 | 參照 /pr-review-cycle 的常見問題表(完全共用) |
| spectra archive validation 失敗 | spectra analyze {{change_name}} 查看 Critical 錯誤,修正後再 archive;--no-validate 需使用者明確指示才使用 |
| Jira key 無法從 branch / PR 偵測 | 詢問使用者提供 key(格式:PROJECT-123),或確認此 PR 無對應 Jira issue 後跳過 |
| Jira transition 選項不確定 | 呼叫 getTransitionsForJiraIssue 列出所有選項後詢問使用者確認 |
| Jira MCP 需認證 | Atlassian MCP 需要 OAuth;若工具回傳 auth 錯誤,提示使用者在 claude.ai 完成授權 |
| 使用者跳過 bump 但事後需要版本標記 | 建立 release branch,在上面跑 /bump-version,再開 PR merge 進 main(CI 通過 + 確認 CHANGELOG 正確即可合併,不需跑完整 review cycle;若 main 已有新 commit,CHANGELOG 可能含多餘項目,需人工確認) |