Skills
skills/levnikolaevich/claude-code-skills/ln-310-multi-agent-validator

ln-310-multi-agent-validator

SKILL.md

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.

Multi-Agent Validator

Validates Stories/Tasks (mode=story), implementation plans (mode=plan_review), or arbitrary context (mode=context) with parallel multi-agent review and critical verification.

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 = review mode (evaluating a plan document). "Plan Mode" / "Read-Only Mode" = execution flag (framework-level, applies to ALL modes). These are independent concepts.

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

Purpose

  • mode=story: Validate Story + Tasks (28 criteria), auto-fix, agent review, approve (Backlog→Todo)
  • mode=plan_review: Review plans against codebase. Auto-detects in Read-Only Mode. Review with corrections
  • mode=context: Review documents/architecture via agents + MCP Ref. Review with corrections
  • All modes: Parallel agents (Codex + Gemini), merge, verify, debate, apply

Progress Tracking

Create TodoWrite items from Phase headings below:

  1. Each phase = todo item. Mark in_progress → completed
  2. Phase 2 and Phase 5 MUST appear as explicit items (CRITICAL — DO NOT SKIP)
  3. Phase 7: mark each [ ] → [x] as you go

Workflow

Phase 0: Tools Config

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

Extract: task_provider = Task Management → Provider (linear | file).

  • mode=plan_review: tools_config.md is optional — task_provider not used. If absent: task_provider = "N/A", proceed silently.
  • mode=story | mode=context: tools_config.md required.

Initialize: agents_launched = UNSET. MUST be set to true or SKIPPED in Phase 2.

PROTOCOL RULE: Any reasoning that "this task is too small/simple to require agents" is a PROTOCOL VIOLATION. Task scope does NOT change the agent launch requirement.

Phase 1: Discovery & Loading

Step 1: Resolve storyId per input_resolution_pattern.md

Step 2: Load metadata: Story ID/title/status/labels, child Task IDs/titles/status/labels

  • IF task_provider = linear: get_issue(storyId) + list_issues(parentId=storyId)
  • IF task_provider = file: Read story.md + Glob("docs/tasks/epics/*/stories/*/tasks/*.md")
  • Auto-discover: Team ID (docs/tasks/kanban_board.md), project docs (CLAUDE.md), epic from Story.project

Phase 2: Agent Launch (CRITICAL — DO NOT SKIP)

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

CRITICAL: Agent launch is NOT optional. Executes for ALL modes. The ONLY valid skip: health check returned 0 agents. An Explore agent or ad-hoc research is NOT a substitute. Set agents_launched = true | SKIPPED before proceeding.

BLOCKING GATE: If you find yourself reasoning about skipping agents due to task simplicity, small scope, or "already reviewed" — STOP. Return to the start of Phase 2. The ONLY valid exit without launching is: health_check returned 0 agents.

  1. Health Check (all modes): Read docs/environment_state.json → exclude disabled. Run python shared/agents/agent_runner.py --health-check. 0 available → agents_launched = SKIPPED
  2. Prepare references:
    • mode=story: Story/Task URLs (linear) or file paths (file)
    • mode=context: resolve identifier (default: review_YYYYMMDD_HHMMSS), materialize context if from chat → .agent-review/context/{id}_context.md
    • mode=plan_review: auto-detect plan (Glob .claude/plans/*.md, most recent by mtime). No plan → error
  3. Build prompt: Assemble from shared/agents/prompt_templates/review_base.md + modes/{mode}.md (per shared workflow "Step: Build Prompt"). Replace mode-specific placeholders. Save to .agent-review/{id}_{mode}review_prompt.md
  4. Launch BOTH agents as background tasks. agents_launched = true

Prompt persistence: Save prompt to .agent-review/ before launching agents. Agents are always launched as Bash background tasks — they are external OS processes and are not affected by Claude Code plan mode.

Parallelism: Agents run in background through Phases 3-4. Results merged in Phase 5.

Phase 3: Research & Audit

PREREQUISITE: Phase 2 completed. If health check was never run → go back to Phase 2.

mode=story:

MANDATORY READ: Load references/phase2_research_audit.md — full procedure: domain extraction, ln-002 delegation, MCP research, Anti-Hallucination, Pre-mortem, Penalty Points (28 criteria).

Display: Penalty Points table (criterion, severity, points, description) + Total + Fix Plan. Save audit to .agent-review/{storyId}_phase3_audit.md (penalty table + pre-mortem + cross-reference findings).

  • Plan Mode: Show results → WAIT for approval
  • Normal Mode: Proceed to Phase 4

mode=plan_review / mode=context:

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

While agents run in background:

  1. Load Review Memory — per shared workflow
  2. Applicability Check — scan for technology decision signals. No signals → skip MCP Ref, go to Phase 5
  3. Stack Detection — query_prefix from: conversation context > docs/tools_config.md > indicator files
  4. Extract Topics (3-5) — technology decisions, score by weight
  5. MCP Ref Research — per research_tool_fallback.md chain. Query: "{query_prefix} {topic} RFC standard best practices {year}"
  6. Compare & Correct — max 5 corrections, cite RFC/standard. Apply directly: mode=plan_review → edit plan file, mode=context → edit reviewed documents. Inline rationale "(per {RFC}: ...)"
  7. Save Findings → .agent-review/context/{id}_mcp_ref_findings.md (per references/mcp_ref_findings_template.md)

Then proceed to Phase 5.

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) — template, AC, Architecture, Assumptions references/structural_validation.md
2 Standards (#5) — RFC/OWASP (before YAGNI/KISS) references/standards_validation.md
3 Solution (#6, #21, #28) — library versions, alternatives, feature utilization references/solution_validation.md
4 Workflow (#7-#13) — test strategy, docs, size, YAGNI, KISS references/workflow_validation.md
5 Quality (#14-#15) — documentation, hardcoded values references/quality_validation.md
6 Dependencies (#18-#19/#19b) — no forward deps, parallel groups references/dependency_validation.md
7 Cross-Reference (#25-#26) — AC overlap, task duplication references/cross_reference_validation.md
8 Risk (#20) — implementation risk analysis references/risk_validation.md
9 Pre-mortem (#27) — Tiger/Paper Tiger/Elephant references/premortem_validation.md
10 Verification (#22) — AC verify methods references/traceability_validation.md
11 Traceability (#16-#17) — Story-Task alignment, AC coverage (LAST) references/traceability_validation.md

Zero out penalty points as structural fixes applied (section added, format corrected, placeholder inserted). FLAGGED if auto-fix impossible (human judgment required) → penalty stays, user resolves. Test Strategy section: exist but empty. Maximum Penalty: 113 points.

Phase 5: Merge + Critical Verification (MANDATORY — DO NOT SKIP)

PREREQUISITE: Phase 2 MUST have completed. If agents_launched not set → STOP, go back to Phase 2. An Explore agent is NOT a substitute.

MANDATORY READ: Load shared/references/agent_review_workflow.md (Critical Verification + Debate), shared/references/agent_review_memory.md

  1. Wait for agent results — process-as-arrive
  2. Parse agent suggestions from both result files
  3. MERGE Claude's findings + Agent suggestions. Re-read lines modified in Phase 4 (agents saw pre-fix state)
  4. For EACH suggestion: dedup (own findings + history) → evaluate → AGREE (accept) or DISAGREE (debate per shared workflow)
  5. Apply accepted — mode=story: Story/Tasks, mode=plan_review: plan file, mode=context: documents
  6. Save review summary → .agent-review/review_history.md
  • SKIPPED verdict (0 agents) → proceed unchanged
  • Display: "Agent Review: codex ({accepted}/{total}), gemini ({accepted}/{total}), {N} applied"

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

mode=context/plan_review: Skip. Return advisory output. Done.

  • Step 1 (critical): Set Story + Tasks to Todo; update kanban_board.md APPROVED
    • linear: save_issue({id, state: "Todo"}) for each
    • file: Edit **Status:** → Todo in story.md + task files
    • MUST succeed before Step 2. If fails → retry once → escalate as NO-GO
  • Step 2 (audit): Summary comment — Penalty Points (Before→After=0), Auto-Fixes, Docs Created, Standards Evidence
    • linear: save_comment({issueId, body})
    • file: Write to docs/tasks/epics/.../comments/{ISO-timestamp}.md
    • If comment fails after Step 1 succeeded → WARN, do not revert status
  • Display tabular output (Before/After scores)

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

GO: Penalty After = 0 AND no FLAGGED. NO-GO: Penalty After > 0 OR any FLAGGED (auto-fix impossible → penalty stays, user resolves).

Coverage thresholds: 100% = no penalty. 80-99% = -3 penalty. <80% = -5 penalty, NO-GO.

Phase 7: Workflow Completion Self-Check (MANDATORY — DO NOT SKIP)

Mark each [x] when verified. ALL must be checked. If ANY unchecked → go back to failed phase. Display checklist to terminal before final results.

All modes:

  • tools_config loaded, task_provider extracted (Phase 0)
  • Metadata loaded — not skimmed (Phase 1)
  • agent_runner.py --health-check executed (Phase 2)
  • Agents launched as background tasks OR SKIPPED: 0 agents (Phase 2)

    ⛔ If unchecked AND environment_state.json showed ≥1 available agent → CRITICAL VIOLATION. Do NOT return results. Return to Phase 2.

  • Prompt file saved to .agent-review/ OR passed inline in Plan Mode (Phase 2)
  • Agent results read and parsed OR SKIPPED (Phase 5)
  • Critical Verification + Debate executed OR SKIPPED (Phase 5)
  • Review summary saved to review_history.md OR SKIPPED (Phase 5)

mode=story additional:

  • MCP Ref research executed (Phase 3)
  • Penalty Points calculated, 28 criteria (Phase 3)
  • Auto-fix executed, all 11 groups (Phase 4)
  • Penalty After = 0, Readiness Score = 10 (Phase 4)
  • Anti-Hallucination: VERIFIED (Phase 3)
  • AC Coverage: 100% (Phase 4)
  • Story + Tasks → Todo, kanban updated, comment posted (Phase 6)

mode=context / mode=plan_review additional:

  • MCP Ref research executed OR N/A (Phase 3)
  • Corrections applied to artifacts OR none needed (Phase 3)

Phase 7: Meta-Analysis

MANDATORY READ: Load shared/references/meta_analysis_protocol.md

Skill type: review-coordinator (with agents). Run after Phase 7 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, replace {{TEAM_ID}}, {{DOCS_PATH}}
  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
  • Validation criteria: references/phase2_research_audit.md (28 criteria + auto-fix), references/penalty_points.md
  • Validation checklists: references/structural_validation.md (#1-4, #23-24), standards_validation.md (#5), solution_validation.md (#6, #21, #28), workflow_validation.md (#7-13), quality_validation.md (#14-15), dependency_validation.md (#18-19), risk_validation.md (#20), cross_reference_validation.md (#25-26), premortem_validation.md (#27), traceability_validation.md (#16-17, #22)
  • Templates: shared/templates/story_template.md, task_template_implementation.md; local: docs/templates/
  • Agent review: shared/references/agent_review_workflow.md, agent_delegation_pattern.md, agent_review_memory.md; prompts: shared/agents/prompt_templates/review_base.md + modes/{story,context,plan_review}.md; challenge: challenge_review.md
  • Research: shared/references/research_tool_fallback.md, references/context_review_pipeline.md, domain_patterns.md, mcp_ref_findings_template.md
  • Other: shared/templates/linear_integration.md, shared/references/ac_validation_rules.md

Version: 7.0.0 Last Updated: 2026-02-03

Weekly Installs
26
Repository
levnikolaevich/…e-skills
GitHub Stars
202
First Seen
6 days ago
Security Audits
Gen Agent Trust HubPass
SocketFail
SnykWarn
Installed on
gemini-cli26
github-copilot26
codex26
kimi-cli26
amp26
cline26