ln-513-agent-reviewer

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Paths: File paths (
shared/
,
references/
,
../ln-*
) are relative to skills repo root. If not found at CWD, locate this SKILL.md directory and go up one level for repo root.

路径： 文件路径（
shared/
、
references/
、
../ln-*
）是相对于技能仓库根目录的。如果在当前工作目录（CWD）中未找到，请定位到本SKILL.md所在目录，然后向上一级即为仓库根目录。

Agent Reviewer (Code)

Agent代码审查器

Runs parallel external agent reviews on code implementation, critically verifies suggestions, returns filtered improvements.

针对代码实现运行并行外部Agent审查，严格验证建议，返回经过筛选的改进方案。

Purpose & Scope

目标与适用范围

Worker in ln-510 quality coordinator pipeline (invoked by ln-510 Phase 4)
Run codex-review + gemini-review as background tasks in parallel
Process results as they arrive (first-finished agent processed immediately)
Critically verify each suggestion; debate with agent if Claude disagrees
Return filtered, deduplicated, verified suggestions with confidence scoring
Health check + prompt execution in single invocation

ln-510质量协调流水线中的Worker（由ln-510第4阶段调用）
以后台任务形式并行运行codex-review和gemini-review
按结果到达顺序处理（先完成的Agent结果立即处理）
严格验证每条建议；若Claude持不同意见，则与Agent展开辩论
返回经过筛选、去重、验证且带有置信度评分的建议
单次调用中完成健康检查与提示词执行

When to Use

使用场景

Invoked by ln-510-quality-coordinator Phase 4 (Agent Review)
All implementation tasks in Story status = Done
Code quality (ln-511) and tech debt cleanup (ln-512) already completed

由ln-510-quality-coordinator第4阶段（Agent审查）调用
所有实现任务的Story状态为Done
已完成代码质量检查（ln-511）和技术债务清理（ln-512）

Inputs (from parent skill)

输入（来自父技能）

```
storyId
```
: Linear Story identifier (e.g., "PROJ-123")

```
storyId
```
：Linear Story标识符（例如："PROJ-123"）

Workflow

工作流程

MANDATORY READ: Load

shared/references/agent_delegation_pattern.md

for Reference Passing Pattern, Review Persistence Pattern, Agent Timeout Policy, and Debate Protocol (Challenge Round 1 + Follow-Up Round).

Health check:

python shared/agents/agent_runner.py --health-check

Filter output by
```
skill_groups
```
containing "513"

If 0 agents available -> return

{verdict: "SKIPPED", reason: "no agents available"}

Display:

"Agent Health: codex-review OK, gemini-review UNAVAILABLE"

(or similar)

Get references: Call Linear MCP
```
get_issue(storyId)
```
-> extract URL + identifier. Call
```
list_issues(filter: {parent: {id: storyId}, status: "Done"})
```
-> extract Done implementation Task URLs/identifiers (exclude label "tests").
- If project stores tasks locally (e.g.,
```
docs/tasks/
```
  ) -> use local file paths instead of Linear URLs.
Ensure .agent-review/:
- If
```
.agent-review/
```
  exists -> reuse as-is, do NOT recreate
```
.gitignore
```
- If
```
.agent-review/
```
  does NOT exist -> create it +
```
.agent-review/.gitignore
```
  (content:
```
*
```
  +
```
!.gitignore
```
  )
- Create
```
.agent-review/{agent}/
```
  subdirs only if they don't exist
- Do NOT add
```
.agent-review/
```
  to project root
```
.gitignore
```

Build prompt: Read template

shared/agents/prompt_templates/code_review.md

Replace

{story_ref}

with

- Linear: {url}

- File: {path}

Replace

{task_refs}

with bullet list:

- {identifier}: {url_or_path}

per task

Save to

.agent-review/{agent}/{identifier}_codereview_prompt.md

(one copy per agent — identical content)

Run agents (background, process-as-arrive):

a) Launch BOTH agents as background Bash tasks (run_in_background=true):

python shared/agents/agent_runner.py --agent codex-review --prompt-file .agent-review/codex/{identifier}_codereview_prompt.md --output-file .agent-review/codex/{identifier}_codereview_result.md --cwd {cwd}

python shared/agents/agent_runner.py --agent gemini-review --prompt-file .agent-review/gemini/{identifier}_codereview_prompt.md --output-file .agent-review/gemini/{identifier}_codereview_result.md --cwd {cwd}

b) When first agent completes (background task notification):

Read its result file from

.agent-review/{agent}/{identifier}_codereview_result.md

Parse JSON between

<!-- AGENT_REVIEW_RESULT -->

<!-- END_AGENT_REVIEW_RESULT -->

markers

Parse

session_id

from runner JSON output; write

.agent-review/{agent}/{identifier}_session.json

{"agent": "...", "session_id": "...", "review_type": "codereview", "created_at": "..."}

Proceed to Step 6 (Critical Verification) for this agent's suggestions

c) When second agent completes:

Read its result file, parse suggestions
Run Step 6 for second batch
Merge verified suggestions from both agents

d) If an agent fails: log failure, continue with available results

Critical Verification + Debate (per Debate Protocol in
```
shared/references/agent_delegation_pattern.md
```
):
For EACH suggestion from agent results:

a) Claude Evaluation: Independently assess — is the issue real? Actionable? Conflicts with project patterns?

b) AGREE → accept as-is. DISAGREE/UNCERTAIN → initiate challenge.

c) Challenge + Follow-Up (with session resume): Follow Debate Protocol (Challenge Round 1 → Follow-Up Round if not resolved). Resume agent's review session for full context continuity:
- Read
```
session_id
```
  from
```
.agent-review/{agent}/{identifier}_session.json
```
- Run with
```
--resume-session {session_id}
```
  — agent continues in same session, preserving file analysis and reasoning
- If
```
session_resumed: false
```
  in result → log warning, result still valid (stateless fallback)
- ```
{review_type}
```
  = "Code Implementation"
- Challenge files:
```
.agent-review/{agent}/{identifier}_codereview_challenge_{N}_prompt.md
```
  /
```
_result.md
```
- Follow-up files:
```
.agent-review/{agent}/{identifier}_codereview_followup_{N}_prompt.md
```
  /
```
_result.md
```
d) Persist: all challenge and follow-up prompts/results in
```
.agent-review/{agent}/
```
Aggregate + Return: Collect ACCEPTED suggestions only (after verification + debate). Deduplicate by
```
(area, issue)
```
— keep higher confidence. Filter:
```
confidence >= 90
```
AND
```
impact_percent > 2
```
. Return JSON with suggestions + agent_stats + debate_log to parent skill. NO cleanup/deletion.

必读： 加载

shared/references/agent_delegation_pattern.md

以了解参考传递模式、审查持久化模式、Agent超时策略以及辩论协议（第1轮挑战 + 后续跟进轮次）。

健康检查：

python shared/agents/agent_runner.py --health-check

按包含"513"的
```
skill_groups
```
过滤输出

若可用Agent数量为0 → 返回

{verdict: "SKIPPED", reason: "no agents available"}

显示：

"Agent Health: codex-review OK, gemini-review UNAVAILABLE"

（或类似内容）

获取参考信息： 调用Linear MCP的
```
get_issue(storyId)
```
→ 提取URL和标识符。调用
```
list_issues(filter: {parent: {id: storyId}, status: "Done"})
```
→ 提取已完成的实现任务URL/标识符（排除带有"tests"标签的任务）。
- 若项目将任务存储在本地（例如：
```
docs/tasks/
```
  ）→ 使用本地文件路径而非Linear URL。
确保.agent-review/目录存在：
- 若
```
.agent-review/
```
  已存在 → 直接复用，不要重新创建
```
.gitignore
```
- 若
```
.agent-review/
```
  不存在 → 创建该目录及
```
.agent-review/.gitignore
```
  （内容为：
```
*
```
  +
```
!.gitignore
```
  ）
- 仅在子目录不存在时创建
```
.agent-review/{agent}/
```
  子目录
- 不要将
```
.agent-review/
```
  添加到项目根目录的
```
.gitignore
```
  中
构建提示词： 读取模板文件
```
shared/agents/prompt_templates/code_review.md
```
。
- 将
```
{story_ref}
```
  替换为
```
- Linear: {url}
```
  或
```
- File: {path}
```
- 将
```
{task_refs}
```
  替换为项目符号列表：每个任务对应
```
- {identifier}: {url_or_path}
```
- 将构建好的提示词保存到
```
.agent-review/{agent}/{identifier}_codereview_prompt.md
```
  （每个Agent一份，内容完全相同）

运行Agent（后台任务，按到达顺序处理）：

a) 以后台Bash任务形式启动两个Agent（run_in_background=true）：

python shared/agents/agent_runner.py --agent codex-review --prompt-file .agent-review/codex/{identifier}_codereview_prompt.md --output-file .agent-review/codex/{identifier}_codereview_result.md --cwd {cwd}

python shared/agents/agent_runner.py --agent gemini-review --prompt-file .agent-review/gemini/{identifier}_codereview_prompt.md --output-file .agent-review/gemini/{identifier}_codereview_result.md --cwd {cwd}

b) 当第一个Agent完成时（后台任务通知）：

从

.agent-review/{agent}/{identifier}_codereview_result.md

读取结果文件

解析

<!-- AGENT_REVIEW_RESULT -->

<!-- END_AGENT_REVIEW_RESULT -->

标记之间的JSON内容

从Runner的JSON输出中解析

session_id

，并写入

.agent-review/{agent}/{identifier}_session.json

：

{"agent": "...", "session_id": "...", "review_type": "codereview", "created_at": "..."}

针对该Agent的建议进入步骤6（严格验证）

c) 当第二个Agent完成时：

读取其结果文件，解析建议内容
对第二批建议执行步骤6
合并两个Agent的已验证建议

d) 若某个Agent执行失败：记录失败日志，继续处理可用结果

严格验证 + 辩论（遵循
```
shared/references/agent_delegation_pattern.md
```
中的辩论协议）：
针对Agent结果中的每条建议：

a) Claude评估： 独立评估——该问题是否真实存在？是否可操作？是否与项目模式冲突？

b) 同意 → 直接接受该建议。不同意/不确定 → 发起挑战。

c) 挑战 + 跟进（会话续接）： 遵循辩论协议（第1轮挑战 → 若未解决则进入跟进轮次）。续接Agent的审查会话以保持上下文连续性：
- 从
```
.agent-review/{agent}/{identifier}_session.json
```
  读取
```
session_id
```
- 使用
```
--resume-session {session_id}
```
  运行——Agent将在同一会话中继续，保留文件分析和推理过程
- 若结果中
```
session_resumed: false
```
  → 记录警告，结果仍然有效（无状态回退）
- ```
{review_type}
```
  = "Code Implementation"
- 挑战文件：
```
.agent-review/{agent}/{identifier}_codereview_challenge_{N}_prompt.md
```
  /
```
_result.md
```
- 跟进文件：
```
.agent-review/{agent}/{identifier}_codereview_followup_{N}_prompt.md
```
  /
```
_result.md
```
d) 持久化： 将所有挑战和跟进的提示词/结果存储在
```
.agent-review/{agent}/
```
目录中
聚合 + 返回： 仅收集已接受的建议（经过验证和辩论后）。按
```
(area, issue)
```
去重——保留置信度更高的建议。 过滤条件：
```
confidence >= 90
```
且
```
impact_percent > 2
```
。返回包含建议、agent_stats和debate_log的JSON给父技能。请勿清理/删除任何文件。

Output Format

输出格式

yaml

verdict: CODE_ACCEPTABLE | SUGGESTIONS | SKIPPED
suggestions:
  - area: "security | performance | architecture | correctness | best_practices"
    issue: "What is wrong"
    suggestion: "Specific fix"
    confidence: 95
    impact_percent: 15
    source: "codex-review"
    resolution: "accepted | accepted_after_debate | accepted_after_followup | rejected"
agent_stats:
  - name: "codex-review"
    duration_s: 12.4
    suggestion_count: 3
    accepted_count: 2
    challenged_count: 1
    followup_count: 1
    status: "success | failed | timeout"
debate_log:
  - suggestion_summary: "N+1 query in UserRepository.GetAll()"
    agent: "gemini-review"
    rounds:
      - round: 1
        claude_position: "Query uses Include() which resolves N+1"
        agent_decision: "WITHDRAW"
        resolution: "rejected"
    final_resolution: "rejected"

yaml

verdict: CODE_ACCEPTABLE | SUGGESTIONS | SKIPPED
suggestions:
  - area: "security | performance | architecture | correctness | best_practices"
    issue: "问题描述"
    suggestion: "具体修复方案"
    confidence: 95
    impact_percent: 15
    source: "codex-review"
    resolution: "accepted | accepted_after_debate | accepted_after_followup | rejected"
agent_stats:
  - name: "codex-review"
    duration_s: 12.4
    suggestion_count: 3
    accepted_count: 2
    challenged_count: 1
    followup_count: 1
    status: "success | failed | timeout"
debate_log:
  - suggestion_summary: "UserRepository.GetAll()中存在N+1查询"
    agent: "gemini-review"
    rounds:
      - round: 1
        claude_position: "查询使用了Include()，可解决N+1问题"
        agent_decision: "WITHDRAW"
        resolution: "rejected"
    final_resolution: "rejected"

Fallback Rules

回退规则

Condition	Action
Both agents succeed	Aggregate verified suggestions from both
One agent fails	Use successful agent's verified suggestions, log failure
Both agents fail	Return `{verdict: "SKIPPED", reason: "agents failed"}`
Parent skill (ln-510)	Falls back to Self-Review (native Claude)

条件	操作
两个Agent均成功	聚合两个Agent的已验证建议
一个Agent失败	使用成功Agent的已验证建议，记录失败日志
两个Agent均失败	返回 `{verdict: "SKIPPED", reason: "agents failed"}`
父技能（ln-510）	回退到自审查（原生Claude）

Verdict Escalation

结论升级

Findings with
```
area=security
```
or
```
area=correctness
```
-> parent skill can escalate PASS -> CONCERNS
This skill returns raw verified suggestions; escalation decision is made by ln-510

若发现结果的
```
area=security
```
或
```
area=correctness
```
→ 父技能可将结论从PASS升级为CONCERNS
本技能仅返回原始已验证建议；升级决策由ln-510做出

Critical Rules

关键规则

Read-only review — agents must NOT modify project files (enforced by prompt CRITICAL CONSTRAINTS)
Same prompt to all agents (identical input for fair comparison)
JSON output schema required from agents (via
```
--json
```
/
```
--output-format json
```
)
Log all attempts for user visibility (agent name, duration, suggestion count)
Persist prompts, results, and challenge artifacts in
```
.agent-review/{agent}/
```
— do NOT delete
Ensure
```
.agent-review/.gitignore
```
exists before creating files (only create if
```
.agent-review/
```
is new)
MANDATORY INVOCATION: Parent skills MUST invoke this skill. Returns SKIPPED gracefully if agents unavailable. Parent must NOT pre-check and skip.
NO TIMEOUT KILL — WAIT FOR RESPONSE: Do NOT kill agent background tasks. WAIT until agent completes and delivers its response — do NOT proceed without it, do NOT use TaskStop. Agents are instructed to respond within 10 minutes via prompt constraint, but the hard behavior is: wait for completion or crash. Only a hard crash (non-zero exit code, connection error) is treated as failure. TaskStop is FORBIDDEN for agent tasks.
CRITICAL VERIFICATION: Do NOT trust agent suggestions blindly. Claude MUST independently verify each suggestion and debate if disagreeing. Accept only after verification.

只读审查——Agent不得修改项目文件（通过提示词中的关键约束强制执行）
所有Agent使用相同的提示词（输入完全一致，确保公平对比）
要求Agent返回JSON格式输出（通过
```
--json
```
/
```
--output-format json
```
参数）
记录所有尝试操作，以便用户查看（Agent名称、耗时、建议数量）
持久化所有提示词、结果和挑战相关文件到
```
.agent-review/{agent}/
```
——请勿删除
确保在创建文件前
```
.agent-review/.gitignore
```
已存在（仅在
```
.agent-review/
```
为新目录时创建）
强制调用要求： 父技能必须调用本技能。若Agent不可用，将优雅返回SKIPPED。父技能不得预先检查并跳过调用。
禁止超时终止——等待响应： 不得终止Agent的后台任务。必须等待Agent完成并返回响应——不得在无响应的情况下继续，不得使用TaskStop。提示词约束中已要求Agent在10分钟内响应，但硬性规则是：等待完成或崩溃。仅当出现硬崩溃（非零退出码、连接错误）时才视为失败。禁止对Agent任务使用TaskStop。
严格验证： 不得盲目信任Agent的建议。Claude必须独立验证每条建议，若有不同意见则展开辩论。仅在验证通过后接受建议。

Definition of Done

完成标准

Health check executed; available agents identified (or SKIPPED returned if none)
Story + Done implementation Tasks fetched from Linear (or local files)
```
.agent-review/
```
directory ensured (reused if exists, created with
```
.gitignore
```
if new) with per-agent subdirs
Prompt built from template with story/task references, saved per agent
All available agents launched as background tasks; raw results saved to
```
.agent-review/{agent}/
```
Each suggestion critically verified by Claude; challenges executed for disagreements
Follow-up rounds executed for suggestions rejected after Round 1 (DEFEND+weak / MODIFY+disagree)
Challenge and follow-up prompts/results persisted alongside review artifacts
Suggestions aggregated, deduplicated by (area, issue), filtered (confidence >= 90, impact > 2%)

Session files persisted in

.agent-review/{agent}/{identifier}_session.json

for debate resume

JSON result returned to parent skill with verdict, suggestions list, agent_stats, and debate_log

已执行健康检查；已识别可用Agent（若无可用Agent则返回SKIPPED）
已从Linear（或本地文件）获取Story及已完成的实现任务
已确保
```
.agent-review/
```
目录存在（若已存在则复用，若为新目录则创建并添加
```
.gitignore
```
），且包含每个Agent的子目录
已基于模板构建包含Story/任务参考信息的提示词，并为每个Agent保存一份
已启动所有可用Agent作为后台任务；原始结果已保存到
```
.agent-review/{agent}/
```
Claude已严格验证每条建议；对有分歧的建议已发起挑战
对第1轮挑战后被拒绝的建议（DEFEND+weak / MODIFY+disagree）已执行跟进轮次
挑战和跟进的提示词/结果已与审查文件一起持久化
已聚合建议，按
```
(area, issue)
```
去重，且已过滤（置信度≥90，影响>2%）
会话文件已持久化到
```
.agent-review/{agent}/{identifier}_session.json
```
，用于辩论续接
已向父技能返回包含结论、建议列表、agent_stats和debate_log的JSON结果

Reference Files

参考文件

Agent delegation pattern:

shared/references/agent_delegation_pattern.md

Prompt template (review):

shared/agents/prompt_templates/code_review.md

Prompt template (challenge):

shared/agents/prompt_templates/challenge_review.md

Agent registry:
```
shared/agents/agent_registry.json
```
Agent runner:
```
shared/agents/agent_runner.py
```

Challenge schema:

shared/agents/schemas/challenge_review_schema.json

Version: 2.0.0 Last Updated: 2026-02-11

Agent委托模式：

shared/references/agent_delegation_pattern.md

审查提示词模板：

shared/agents/prompt_templates/code_review.md

挑战提示词模板：

shared/agents/prompt_templates/challenge_review.md

Agent注册表：
```
shared/agents/agent_registry.json
```
Agent运行器：
```
shared/agents/agent_runner.py
```

挑战 schema：

shared/agents/schemas/challenge_review_schema.json

版本： 2.0.0 最后更新日期： 2026-02-11