Agent Skills: Multi-Agent Validator

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. If shared/ is missing, fetch files via WebFetch from https://raw.githubusercontent.com/levnikolaevich/claude-code-skills/master/skills/{path}.

Type: L2 Coordinator Category: 3XX Planning

Multi-Agent Validator

Validates Stories/Tasks (mode=story), implementation plans (mode=plan_review), or arbitrary context (mode=context) with deterministic runtime state, parallel external review, critical verification, and optional approval.

Inputs

| Input | Required | Source | Description | |-------|----------|--------|-------------| | storyId | mode=story | args, git branch, kanban, user | Story to process | | plan {file} | mode=plan_review | args or auto | Plan file to review. Auto-detected from .claude/plans/ if Read-Only Mode active and no args | | context | mode=context | conversation history, git diff | Review current discussion context + changed files |

Mode detection: "plan" or "plan {file}" or Read-Only Mode active with no args -> mode=plan_review. "context" -> mode=context. Anything else -> mode=story.

Terminology: mode=plan_review is the review target. Plan Mode / Read-Only Mode is the framework execution flag. They are independent.

Plan Mode compatibility: .hex-skills/agent-review/ remains git-ignored. Runtime state, prompts, results, logs, and materialized context files may be written there even in Plan Mode.

Resolution (mode=story): Story Resolution Chain. Status filter: Backlog

Purpose

• mode=story: validate Story + Tasks against 28 criteria, auto-fix structural issues, merge agent review, then approve (Backlog -> Todo) only after zero remaining blockers
• mode=plan_review: review plan against codebase, standards, and alternatives; apply accepted corrections
• mode=context: review architecture/documents/context materials; apply accepted corrections
• All modes: run deterministic agent review with runtime checkpoints, critical verification, and Codex refinement

Progress Tracking

Create TodoWrite items from phase headings below:

1. Each phase = one todo item
2. Phase 2 and Phase 6 MUST appear explicitly
3. Phase 9 checklist items must be marked as they are verified

Workflow

Phase 0: Config + Runtime Start

MANDATORY READ: Load shared/references/tools_config_guide.md, shared/references/storage_mode_detection.md, shared/references/input_resolution_pattern.md MANDATORY READ: Load shared/references/review_runtime_contract.md

1. Detect task_provider from tools config.
   • mode=plan_review: tools_config.md optional. If absent, use task_provider = "N/A".
   • mode=story | mode=context: tools_config.md required.
2. Resolve mode, identifier, and storage mode.
3. Build runtime manifest with:
   • storage_mode
   • story_ref | plan_ref | context_ref
   • expected_agents = ["codex", "gemini"]
   • artifact_paths for prompt/result/log/metadata roots
   • phase_policy (story: phase4/phase5/phase8 required; others: skipped_by_mode)
4. Save manifest to .hex-skills/agent-review/runtime/{identifier}_manifest.json
5. Start runtime:

node shared/scripts/review-runtime/cli.mjs start \
  --skill ln-310 \
  --mode {mode} \
  --identifier {identifier} \
  --manifest-file .hex-skills/agent-review/runtime/{identifier}_manifest.json

6. Write Phase 0 checkpoint after config + runtime start succeed.

Phase 1: Discovery & Materialization

1. Resolve primary artifact:
   • story: resolve Story + child Tasks
   • plan_review: resolve plan file, or auto-detect latest .claude/plans/*.md
   • context: resolve identifier and materialize chat-derived context if needed
2. Load metadata:
   • linear: get_issue(storyId) + list_issues(parentId=storyId)
   • file: read story.md + task files
3. Materialize any non-project file paths into .hex-skills/agent-review/context/
4. Checkpoint Phase 1 with resolved refs and metadata summary.

Phase 2: Agent Launch

MANDATORY READ: Load shared/references/agent_review_workflow.md, shared/references/agent_delegation_pattern.md

1. Run health check:

node shared/agents/agent_runner.mjs --health-check --json

2. Exclude agents disabled in .hex-skills/environment_state.json.
3. If available_count = 0:
   • set agents_skipped_reason
   • checkpoint Phase 2 with health_check_done=true, agents_available=0
   • advance to Phase 3
4. Otherwise:
   • ensure .hex-skills/agent-review/{agent}/ exists
   • build per-agent prompt from review_base.md + modes/{story,context,plan_review}.md
   • save prompt to .hex-skills/agent-review/{agent}/{identifier}_{review_type}_prompt.md
5. Launch every available agent with explicit metadata file:

node shared/agents/agent_runner.mjs \
  --agent {name} \
  --prompt-file .hex-skills/agent-review/{agent}/{identifier}_{review_type}_prompt.md \
  --output-file .hex-skills/agent-review/{agent}/{identifier}_{review_type}_result.md \
  --metadata-file .hex-skills/agent-review/{agent}/{identifier}_{review_type}_metadata.json \
  --cwd {project_dir}

6. Register each launched agent in runtime:

node shared/scripts/review-runtime/cli.mjs register-agent \
  --skill ln-310 \
  --agent {name} \
  --prompt-file .hex-skills/agent-review/{agent}/{identifier}_{review_type}_prompt.md \
  --result-file .hex-skills/agent-review/{agent}/{identifier}_{review_type}_result.md \
  --log-file .hex-skills/agent-review/{agent}/{identifier}_{review_type}.log \
  --metadata-file .hex-skills/agent-review/{agent}/{identifier}_{review_type}_metadata.json

7. Checkpoint Phase 2 with health_check_done, agents_available, agents_required, optional agents_skipped_reason.

Phase 3: Research & Audit

MANDATORY READ: Load references/phase2_research_audit.md, shared/references/research_tool_fallback.md

Common work:

• MCP research for #5, #6, #21, #28
• Anti-hallucination verification per shared/references/epistemic_protocol.md

mode=story:

• pre-mortem analysis
• cross-reference analysis
• penalty points calculation across all 28 criteria
• save audit to .hex-skills/agent-review/{storyId}_phase3_audit.md

mode=plan_review | mode=context:

• MANDATORY READ: Load references/context_review_pipeline.md, references/mcp_ref_findings_template.md
• run applicability -> stack detection -> topics -> research -> compare/correct -> findings save

Checkpoint Phase 3 with audit/research summary.

Phase 4: Documentation (mode=story only)

MANDATORY READ: Load shared/references/documentation_creation.md, references/domain_patterns.md

1. Extract technical domains from Story title + Technical Notes + Implementation Tasks
2. Load pattern registry from references/domain_patterns.md
3. Scan Story content for pattern matches via keyword detection
4. For EACH detected pattern:
   • Check if doc already exists (Glob by pattern path from domain_patterns.md)
   • IF missing -> load template from shared/templates/{doc_type}_template.md
   • Research per shared/references/research_methodology.md + fallback chain
   • For doc_type=adr: answer the 5 ADR questions (per documentation_creation.md) internally before generation
   • Generate document (per documentation_creation.md rules: NO CODE, tables first, 300-500 words)
   • Save to docs/{type}s/{naming}.md
   • Add link to Story Technical Notes
5. Update runtime state with docs_checkpoint: { docs_created: [...paths], docs_skipped_reason: "..." }. If docs_created is empty, docs_skipped_reason is required (e.g., "no domain patterns matched"). Guard blocks Phase 4 -> Phase 5 without this.
6. Checkpoint Phase 4 with docs summary.

For mode=plan_review | mode=context, checkpoint Phase 4 as {"status":"skipped_by_mode"}.

Phase 4: Auto-Fix (mode=story only)

MANDATORY READ per group: Load the checklist as you execute each group.

| # | Group | Checklist | |---|-------|-----------| | 1 | Structural (#1-#4, #23-#24) | references/structural_validation.md | | 2 | Standards (#5) | references/standards_validation.md | | 3 | Solution (#6, #21, #28) | references/solution_validation.md | | 4 | Workflow (#7-#13) | references/workflow_validation.md | | 5 | Quality (#14-#15) | references/quality_validation.md | | 6 | Dependencies (#18-#19/#19b) | references/dependency_validation.md | | 7 | Cross-Reference (#25-#26) | references/cross_reference_validation.md | | 8 | Risk (#20) | references/risk_validation.md | | 9 | Pre-mortem (#27) | references/premortem_validation.md | | 10 | Verification (#22) | references/traceability_validation.md | | 11 | Traceability (#16-#17) | references/traceability_validation.md |

Rules:

• zero out penalty points only when the defect is actually repaired
• use FLAGGED only when human judgment is required and auto-fix cannot safely continue
• test strategy section may exist but remain empty
• max penalty = 113

Checkpoint Phase 4 with penalty before/after, flagged items, and coverage summary.

For mode=plan_review | mode=context, checkpoint Phase 4 as {"status":"skipped_by_mode"}.

Phase 5: Merge + Critical Verification

1. Sync every launched agent through runtime:

node shared/scripts/review-runtime/cli.mjs sync-agent --skill ln-310

2. Do not merge until all required agents are in result_ready | dead | failed | skipped.

   WAIT PATIENTLY. Codex typically takes 10-20 minutes. Do NOT skip or declare Codex failed because it runs longer than expected. If sync-agent shows the agent is still running — keep waiting. Only the Liveness Protocol determines failure, not elapsed time.

3. Parse available result files.
4. For each suggestion:
   • deduplicate against own findings + review history
   • verify independently
   • mark AGREE or REJECT Architecture Gate: Before applying, verify each AGREE'd suggestion: "Does this implement the correct architecture directly, without backward compatibility shims or legacy workarounds?" If a suggestion introduces unnecessary compat layers -> convert to REJECT.
5. Apply accepted suggestions:
   • story: patch Story/Tasks after re-reading Phase 4 output
   • context: patch target docs/context files
   • plan_review: prefer best ## Refined Plan, then apply remaining accepted patches
6. Save review summary to .hex-skills/agent-review/review_history.md
7. Checkpoint Phase 5 with merge_summary.

Phase 6: Iterative Refinement

MANDATORY READ: Load shared/agents/prompt_templates/iterative_refinement.md

1. Determine artifact:
   • story: Story + Tasks concatenation
   • plan_review: plan file
   • context: context docs
2. Run Codex refinement loop (max 5 iterations) if Codex was available in Phase 2. Each iteration uses a different review perspective (Generic → Dry-Run → New Dev → Adversarial → Final Sweep). Loop exits on 2 consecutive APPROVED or MAX_ITER.

   Synchronous Codex calls may take 5-15 minutes per iteration. This is expected. Do NOT abort or skip iterations because a call takes several minutes. The runner's hard timeout (30 min) is the only valid abort boundary.

   Architecture Gate per iteration: Before applying fixes from each refinement iteration, verify: "Does this fix implement the correct architecture directly, without backward compatibility shims or legacy workarounds?" Reject fixes that introduce unnecessary compat layers.

   Process cleanup per iteration: After each Codex call, extract pid from runner output and run --verify-dead {pid}. Codex processes accumulate on Windows if not killed. This is MANDATORY.

   Fresh session only: NEVER use --resume-session in refinement. Each iteration = new Codex session. Clean previous iteration's result + log files before launching. Phase 2 session data pollutes context window.

3. Skip only with machine-readable reason:
   • disabled
   • unavailable in health check
   • dead/failed after runtime sync

No quality-based skip criteria. Phase 7 skip is determined ONLY by Codex availability, never by penalty score, FLAGGED count, or agent agreement level. If Codex is available, Phase 7 MUST execute at least 1 iteration.

Repeat decision (iterations 2+): Continue if ANY suggestion has severity HIGH or any remaining_risk has severity >= MEDIUM. Otherwise stop (CONVERGED_LOW_IMPACT).

4. Persist prompts/results to .hex-skills/agent-review/refinement/
5. Checkpoint Phase 7 with iterations (int), exit_reason (one of: CONVERGED, CONVERGED_LOW_IMPACT, MAX_ITER, ERROR, SKIPPED), applied (int: total fixes applied).

Phase 8: Approve & Notify (mode=story only)

1. Set Story + Tasks to Todo; update kanban_board.md to APPROVED.
   • linear: save_issue({id, state: "Todo"})
   • file: edit **Status:** -> Todo
2. Retry status transition once if needed. If still failing -> verdict becomes NO_GO.
3. Write audit comment / file with penalty before/after, fixes, docs, and standards evidence.
4. If comment fails after status success -> warn, do not revert status.
5. Checkpoint Phase 8 with approval/status result.

For mode=plan_review | mode=context, checkpoint Phase 8 as {"status":"skipped_by_mode"}.

Phase 9: Runtime Self-Check

Build the final checklist from runtime state. This is a projection of machine-readable checkpoints, not a second source of truth.

Required checks:

• [ ] Phase 0 checkpoint exists
• [ ] Phase 1 checkpoint exists
• [ ] Phase 2 recorded health check and launch/skip result
• [ ] Phase 3 audit/research checkpoint exists
• [ ] Phase 4 documentation checkpoint exists (story mode: docs_created or docs_skipped_reason)
• [ ] Phase 5 checkpoint exists (story) or skipped_by_mode (plan_review/context)
• [ ] All required agents resolved before Phase 6 merge
• [ ] Phase 6 merge summary exists
• [ ] Phase 7 refinement: iterations >= 1 when Codex available, or SKIPPED with valid reason
• [ ] All Codex/Gemini processes verified dead (no orphaned agent processes)
• [ ] Phase 8 checkpoint exists (story) or skipped_by_mode
• [ ] Final verdict and user-facing output are ready

Write Phase 9 checkpoint with pass=true|false. Complete runtime only after pass=true.

Final Assessment Model

| Metric | Before | After | Meaning | |--------|--------|-------|---------| | Penalty Points | Raw audit total | Remaining after fixes | 0 = all fixed | | Readiness Score | 10 - (Before / 5) | 10 - (After / 5) | Quality confidence (1-10) | | Anti-Hallucination | — | VERIFIED / FLAGGED | Technical claims verified via MCP Ref/Context7 | | AC Coverage | — | N/N (target 100%) | Each AC mapped to >=1 Task | | Gate | — | GO / NO_GO | Final verdict |

Rules:

• GO: Penalty After = 0 and no FLAGGED
• NO_GO: Penalty After > 0 or any FLAGGED
• coverage: 100% = pass; 80-99% = -3 penalty; <80% = -5 penalty and NO_GO

Definition of Done

• [ ] Runtime manifest created and start executed successfully
• [ ] Discovery/materialization checkpointed
• [ ] Agent health check executed and recorded in runtime
• [ ] Every launched agent registered with prompt/result/log/metadata paths
• [ ] Research/Audit completed per mode and checkpointed
• [ ] Documentation created or skipped with reason, checkpointed
• [ ] Story auto-fix completed or non-story Phase 5 skipped by mode
• [ ] Agent results merged only after all required agents resolved
• [ ] Review summary saved to review_history.md
• [ ] Iterative Refinement: iterations >= 1 when Codex available, or SKIPPED with valid reason
• [ ] Story approval/status transition completed or non-story Phase 8 skipped by mode
• [ ] Phase 9 self-check passed and runtime completed

Phase 10: Meta-Analysis

MANDATORY READ: Load shared/references/meta_analysis_protocol.md

Skill type: review-coordinator (with agents). Run after Phase 9 completes. Output to chat using the review-coordinator — with agents format.

Template Loading

Templates: story_template.md, task_template_implementation.md

1. Check if docs/templates/{template}.md exists in target project
2. If not, copy shared/templates/{template}.md -> docs/templates/{template}.md
3. Use local copy for all validation

Reference Files

• Core config: shared/references/tools_config_guide.md, storage_mode_detection.md, input_resolution_pattern.md, plan_mode_pattern.md
• Runtime: shared/references/review_runtime_contract.md, shared/scripts/review-runtime/cli.mjs
• Validation criteria: references/phase2_research_audit.md, references/penalty_points.md
• Validation checklists: references/structural_validation.md, standards_validation.md, solution_validation.md, workflow_validation.md, quality_validation.md, dependency_validation.md, risk_validation.md, cross_reference_validation.md, premortem_validation.md, traceability_validation.md
• Agent review: shared/references/agent_review_workflow.md, agent_delegation_pattern.md, agent_review_memory.md
• Prompt templates: shared/agents/prompt_templates/review_base.md, modes/{story,context,plan_review}.md, iterative_refinement.md
• Research: shared/references/research_tool_fallback.md, references/context_review_pipeline.md, domain_patterns.md, mcp_ref_findings_template.md, shared/references/research_methodology.md

Version: 8.0.0 Last Updated: 2026-03-22