Ln 510 Quality Coordinator

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}.

Quality Coordinator

Sequential coordinator for code quality pipeline. Invokes workers (ln-511 → ln-512 → ln-513 → ln-514), runs inline agent review in parallel with Phases 5-8, merges all results, and returns quality_verdict.

Inputs

Resolution: Story Resolution Chain. Status filter: To Review

Purpose & Scope

• Invoke ln-511-code-quality-checker (metrics, MCP Ref, static analysis)
• Invoke ln-512-tech-debt-cleaner (auto-fix safe findings from ln-511)
• Run inline agent review (Codex + Gemini in parallel on cleaned code)
• Run Criteria Validation (Story dependencies, AC-Task Coverage, DB Creation Principle)
• Run linters from tech_stack.md
• Invoke ln-513-regression-checker (test suite after all changes)
• Invoke ln-514-test-log-analyzer (classify errors, assess log quality)
• Return quality_verdict + aggregated results
• Calculate quality_verdict per normalization matrix + references/gate_levels.md

When to Use

• Invoked by ln-500-story-quality-gate Phase 2
• All implementation tasks in Story status = Done

Workflow

Phase 0: Resolve Inputs

MANDATORY READ: Load shared/references/input_resolution_pattern.md

1. Resolve storyId: Run Story Resolution Chain per guide (status filter: [To Review]).

Phase 1: Discovery

1. Auto-discover team/config from docs/tasks/kanban_board.md
2. Load Story + task metadata from Linear (no full descriptions)
3. Collect git scope (sets changed_files[] for ln-511 via coordinator context): MANDATORY READ: Load shared/references/git_scope_detection.md Run algorithm from guide → build changed_files[]

Fast-track mode: When invoked with --fast-track flag (readiness 10/10), run Phase 2 with --skip-mcp-ref (metrics + static only, no MCP Ref), skip Phase 3 (ln-512), run Phase 4 with 1 agent minimum (reduced from 2). Run Phase 5 (criteria), Phase 6 (linters), Phase 7 (ln-513), Phase 8 (ln-514).

Phase 2: Code Quality (delegate to ln-511 — ALWAYS runs)

MANDATORY STEP: ln-511 invocation required in ALL modes. Full gate: ln-511 runs everything (metrics + MCP Ref + static analysis). Fast-track: ln-511 runs with --skip-mcp-ref (metrics + static analysis only — catches complexity, DRY, dead code without expensive MCP Ref calls).

1. Invoke ln-511-code-quality-checker via Skill tool
   • Full: ln-511 runs code metrics, MCP Ref validation (OPT/BP/PERF), static analysis
   • Fast-track: ln-511 runs code metrics + static analysis only (skips OPT-, BP-, PERF- MCP Ref checks)
   • Returns verdict (PASS/CONCERNS/ISSUES_FOUND) + code_quality_score + issues list
2. If ln-511 returns ISSUES_FOUND -> aggregate issues, continue (ln-500 decides action)

Invocation:

# Full gate:
Skill(skill: "ln-511-code-quality-checker", args: "{storyId}")
# Fast-track:
Skill(skill: "ln-511-code-quality-checker", args: "{storyId} --skip-mcp-ref")

Phase 3: Tech Debt Cleanup (delegate to ln-512 — SKIP if --fast-track)

MANDATORY STEP (full gate): ln-512 invocation required. Safe auto-fixes only (confidence >=90%). Fast-track: SKIP this phase.

1. Invoke ln-512-tech-debt-cleaner via Skill tool
   • ln-512 consumes findings from ln-511 output (passed via coordinator context)
   • Filters to auto-fixable categories (unused imports, dead code, deprecated aliases)
   • Applies safe fixes, verifies build integrity, creates commit
2. If ln-512 returns BUILD_FAILED -> all changes reverted, aggregate issue, continue

Invocation:

Skill(skill: "ln-512-tech-debt-cleaner", args: "{storyId}")

Phase 4: Agent Review Launch

MANDATORY STEP: Launches agents in background, results merged in Phase 9. Fast-track: Launch 1 agent only (most available). Results merged in Phase 9 as normal.

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

4a) Health Check (per shared workflow "Step: Health Check"): - Read docs/environment_state.json → exclude agents with disabled: true - Run node shared/agents/agent_runner.mjs --health-check for remaining agents - If 0 agents → agent review SKIPPED, go to Phase 5 4b) Get references: get_issue(storyId) + list_issues(parent=storyId, status=Done) (exclude test tasks) 4c) Build prompt: Assemble from shared/agents/prompt_templates/review_base.md + modes/code.md (per shared workflow "Step: Build Prompt"), replace {story_ref}, {task_refs}. Save to .agent-review/{identifier}_codereview_prompt.md 4d) Launch BOTH agents as background tasks. agents_launched = true Exact command (per agent_delegation_pattern.md): node shared/agents/agent_runner.mjs --agent {name} --prompt-file .agent-review/{agent}/{id}_codereview_prompt.md --output-file .agent-review/{agent}/{id}_codereview_result.md --cwd {project_dir} → Continue to Phase 5 (Criteria Validation), Phase 6 (Linters), Phase 7 (Regression), Phase 8 (Log Analysis) while agents work

Phase 5: Criteria Validation

MANDATORY READ: Load references/criteria_validation.md

Phase 6: Linters

MANDATORY READ: shared/references/ci_tool_detection.md (Discovery Hierarchy + Command Registry)

1. Detect lint/typecheck commands per ci_tool_detection.md discovery hierarchy
2. Run all detected checks (timeouts per guide: 2min linters, 5min typecheck)
3. If any check fails -> aggregate issues, continue

Phase 7: Regression Tests (delegate to ln-513)

1. Invoke ln-513-regression-checker via Skill tool
   • Runs full test suite, reports PASS/FAIL
   • Runs AFTER ln-512 changes to verify nothing broke
2. If regression FAIL -> aggregate issues, continue

Invocation:

Skill(skill: "ln-513-regression-checker", args: "{storyId}")

Phase 8: Test Log Analysis (delegate to ln-514 — runs after ln-513)

1. Invoke ln-514-test-log-analyzer via Skill tool with context instructions
   • Only Real Bugs affect quality verdict; log quality issues are informational
2. If ln-514 returns REAL_BUGS_FOUND -> aggregate issues, continue
3. If ln-514 returns NO_LOG_SOURCES -> status ignored, continue
4. Post ln-514 report as Linear comment on story

Invocation:

Skill(skill: "ln-514-test-log-analyzer", args: "review logs since test run start, expected errors from negative test cases")

Phase 9: Agent Merge (runs after Phase 8, when agent results arrive — SKIP if agents SKIPPED)

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

9a) Wait for agent results — read result files as they arrive (process-as-arrive pattern) 9b) Critical Verification per shared workflow — Claude evaluates each suggestion on merits 9c) Merge accepted suggestions into issues list (SEC-, PERF-, MNT-, ARCH-, BP-, OPT-) - If area=security or area=correctness → escalate aggregate to CONCERNS 9d) Save review summary to .agent-review/review_history.md

Phase 10: Iterative Refinement (MANDATORY when Codex available — SKIP if agents SKIPPED)

PROTOCOL RULE: Valid skip: (1) Codex unavailable in Phase 4 health check, (2) agents SKIPPED. If skipped → log "Iterative Refinement: SKIPPED".

Execute per shared/references/agent_review_workflow.md "Step: Iterative Refinement".

1. Artifact: Changed files from Story scope (post-Phase 9 merge state)
2. Loop (max 5 iterations): Build prompt → send to Codex (foreground) → parse → AGREE/REJECT each suggestion → apply accepted → repeat until APPROVED or max
3. Display: "Iterative Refinement: {N} iterations, {total} suggestions, {applied} applied, exit: {reason}"
4. Persist: .agent-review/refinement/, append to review_history.md

Phase 11: Calculate Verdict + Return Results

MANDATORY READ: Load references/gate_levels.md

Step 11.1: Normalize Component Results

Map each component status to FAIL/CONCERN/ignored using this matrix:

Step 11.2: Calculate Quality Verdict

fail_count = count of components mapped to FAIL
concern_count = count of components mapped to CONCERN
quality_score = 100 - (20 * fail_count) - (10 * concern_count)

# Fast-fail override: any FAIL -> verdict is FAIL regardless of score
IF fail_count > 0:
  quality_verdict = FAIL
ELSE IF quality_score >= 90:
  quality_verdict = PASS
ELSE IF quality_score >= 70:
  quality_verdict = CONCERNS
ELSE:
  quality_verdict = FAIL

Step 11.3: Return Results

quality_verdict: PASS | CONCERNS | FAIL
quality_score: {0-100}
fail_count: {N}
concern_count: {N}
ignored_components: [tech_debt_cleanup, agent_review]  # only if SKIPPED
quality_check: PASS | CONCERNS | ISSUES_FOUND
code_quality_score: {0-100}
agent_review: CODE_ACCEPTABLE | SUGGESTIONS | SKIPPED
criteria_validation: PASS | CONCERNS | FAIL
linters: PASS | FAIL
tech_debt_cleanup: CLEANED | NOTHING_TO_CLEAN | BUILD_FAILED | SKIPPED
regression: PASS | FAIL
log_analysis: CLEAN | WARNINGS_ONLY | REAL_BUGS_FOUND | SKIPPED
issues:
  - {id: "SEC-001", severity: high, finding: "...", source: "ln-511"}
  - {id: "OPT-001", severity: medium, finding: "...", source: "agent-review"}
  - {id: "DEP-001", severity: medium, finding: "...", source: "criteria"}
  - {id: "LINT-001", severity: low, finding: "...", source: "linters"}

TodoWrite format (mandatory):

- Invoke ln-511-code-quality-checker (in_progress)
- Invoke ln-512-tech-debt-cleaner (pending)
- Launch agent review (background) (pending)
- Criteria Validation (Story deps, AC coverage, DB schema) (pending)
- Run linters from tech_stack.md (pending)
- Invoke ln-513-regression-checker (pending)
- Invoke ln-514-test-log-analyzer (pending)
- Merge agent review results (pending)
- Calculate quality_verdict + return results (pending)

Worker Invocation (MANDATORY)

All workers: Invoke via Skill tool — workers see coordinator context. Agent review runs inline (no Skill delegation).

Anti-Patterns:

• Running mypy, ruff, pytest directly instead of invoking ln-511/ln-513
• Skipping agent health check or not launching agents in Phase 4
• Auto-fixing code directly instead of invoking ln-512
• Marking steps as completed without invoking the actual skill
• Skipping verdict calculation or returning raw results without quality_verdict

Critical Rules

• Always calculate quality_verdict per normalization matrix + gate_levels.md. Final gate_verdict is ln-500's responsibility (includes tests, NFR, waivers)
• Single source of truth: rely on Linear metadata for tasks
• Language preservation in comments (EN/RU)
• Do not create tasks or change statuses; ln-500 decides next actions

Definition of Done

• ln-511 invoked (ALWAYS — full or --skip-mcp-ref in fast-track), code quality score returned
• ln-512 invoked (or skipped if --fast-track), tech debt cleanup results returned
• Agent review executed inline (or skipped if --fast-track), results merged in Phase 9
• Agent process trees verified dead after results collection (Phase 9)
• Criteria Validation completed (3 checks)
• Linters executed
• ln-513 invoked, regression results returned
• ln-514 invoked, log analysis results returned (or SKIPPED/NO_LOG_SOURCES)
• Iterative Refinement executed or SKIPPED (Phase 10)
• quality_verdict calculated + aggregated results returned

Phase 12: Meta-Analysis

MANDATORY READ: Load shared/references/meta_analysis_protocol.md

Skill type: review-coordinator (with agents). Run after all phases complete. Output to chat using the review-coordinator — with agents format.

Reference Files

• Criteria Validation: references/criteria_validation.md
• Gate levels: references/gate_levels.md
• Workers: ../ln-511-code-quality-checker/SKILL.md, ../ln-512-tech-debt-cleaner/SKILL.md, ../ln-513-regression-checker/SKILL.md, ../ln-514-test-log-analyzer/SKILL.md
• Agent review workflow: shared/references/agent_review_workflow.md
• Agent delegation pattern: shared/references/agent_delegation_pattern.md
• Agent review memory: shared/references/agent_review_memory.md
• Review templates: shared/agents/prompt_templates/review_base.md + modes/code.md
• Caller: ../ln-500-story-quality-gate/SKILL.md
• Test planning (separate coordinator): ../ln-520-test-planner/SKILL.md
• Tech stack/linters: docs/project/tech_stack.md

Version: 7.0.0 Last Updated: 2026-02-09