Agent-Skills.md

Agent Skills: Quality Coordinator

Coordinates code quality checks: metrics, cleanup, agent review, regression, log analysis. Use when Story needs quality_verdict with aggregated results.

UncategorizedID: levnikolaevich/claude-code-skills/ln-510-quality-coordinator

Repository

levnikolaevich/claude-code-skills
levnikolaevichLicense: MIT
29647

Install this agent skill to your local

pnpm dlx add-skill https://github.com/levnikolaevich/claude-code-skills/tree/HEAD/skills-catalog/ln-510-quality-coordinator

Skill Files

Browse the full folder contents for ln-510-quality-coordinator.

Download Skill

Loading file tree…

skills-catalog/ln-510-quality-coordinator/SKILL.md

Skill Metadata

Name
ln-510-quality-coordinator
Description
"Coordinates code quality checks: metrics, cleanup, agent review, regression, log analysis. Use when Story needs quality_verdict with aggregated results."

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: 5XX Quality

Quality Coordinator

Runtime-backed quality coordinator. The runtime owns phase transitions, worker summary tracking, and deterministic resume while ln-510 still performs the same quality orchestration.

Inputs

| Input | Required | Source | Description | |-------|----------|--------|-------------| | storyId | Yes | args, git branch, kanban, user | Story to process |

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

Runtime Contract

MANDATORY READ: Load shared/references/coordinator_runtime_contract.md, shared/references/quality_runtime_contract.md, shared/references/quality_summary_contract.md, shared/references/review_runtime_contract.md

Runtime family: quality-runtime

Identifier:

  • Story ID

Phases:

  1. PHASE_0_CONFIG
  2. PHASE_1_DISCOVERY
  3. PHASE_2_CODE_QUALITY
  4. PHASE_3_CLEANUP
  5. PHASE_4_AGENT_REVIEW
  6. PHASE_5_CRITERIA
  7. PHASE_6_LINTERS
  8. PHASE_7_REGRESSION
  9. PHASE_8_LOG_ANALYSIS
  10. PHASE_9_FINALIZE
  11. PHASE_10_SELF_CHECK

Worker summary contract:

  • ln-511, ln-512, ln-513, ln-514 may receive summaryArtifactPath
  • each worker writes or returns quality-worker summary envelope
  • ln-510 consumes worker summaries, not free-text worker prose

When to Use

  • 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[]
  4. Index codebase graph (if available): IF hex-graph MCP server is available:
    • index_project(path=codebase_root) — builds/refreshes code graph for workers
    • Add graph_indexed: true to coordinator context for ln-511
    • Workers use graph tools (find_clones, find_hotspots, etc.) when graph_indexed=true

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 MANDATORY READ: Load shared/references/review_runtime_contract.md

4a) Start review runtime for ln-510 with: - mode=code - identifier={storyId} - expected_agents = ["codex", "gemini"] or single available agent in fast-track 4b) Run health check: - Read .hex-skills/environment_state.json → exclude disabled - Run node shared/agents/agent_runner.mjs --health-check --json - If 0 agents → checkpoint runtime with agents_skipped_reason, go to Phase 5 4c) Get references: get_issue(storyId) + list_issues(parent=storyId, status=Done) (exclude test tasks) 4d) Build per-agent prompt from review_base.md + modes/code.md 4e) Launch available agents with metadata files: node shared/agents/agent_runner.mjs --agent {name} --prompt-file .hex-skills/agent-review/{agent}/{id}_codereview_prompt.md --output-file .hex-skills/agent-review/{agent}/{id}_codereview_result.md --metadata-file .hex-skills/agent-review/{agent}/{id}_codereview_metadata.json --cwd {project_dir} 4f) Register each launched agent in review runtime with prompt/result/log/metadata paths 4g) Checkpoint runtime Phase 2-equivalent state, then continue to Phase 5-8 while agents work

Phase 5: Criteria Validation

MANDATORY READ: Load references/criteria_validation.md

| Check | Description | Fail Action | |-------|-------------|-------------| | #1 Story Dependencies | No forward deps within Epic | [DEP-] issue | | #2 AC-Task Coverage | STRONG/WEAK/MISSING scoring | [COV-]/[BUG-] issue | | #3 DB Creation Principle | Schema scope matches Story | [DB-] issue |

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) Sync agent state via review runtime. Do not merge until every required agent is result_ready | dead | failed | skipped 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 .hex-skills/agent-review/review_history.md 9e) Checkpoint merge summary in review runtime

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)
    • Kill Codex process (--verify-dead {pid}) after each call
    • Parse → Architecture Gate (reject backward-compat shims) → AGREE/REJECT each suggestion → apply accepted
    • Quality-based exit: loop continues while MEDIUM/HIGH suggestions exist
    • Synchronous Codex calls may take 5-15 minutes per iteration — this is expected
  3. Display: "Iterative Refinement: {N} iterations, {total} suggestions, {applied} applied, exit: {reason}"
  4. Persist: .hex-skills/agent-review/refinement/, append to review_history.md
  5. Checkpoint refinement summary in review runtime

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:

| Component | Status | Maps To | Penalty | |-----------|--------|---------|---------| | quality_check | PASS | -- | 0 | | quality_check | CONCERNS | CONCERN | -10 | | quality_check | ISSUES_FOUND | FAIL | -20 | | criteria_validation | PASS | -- | 0 | | criteria_validation | CONCERNS | CONCERN | -10 | | criteria_validation | FAIL | FAIL | -20 | | linters | PASS | -- | 0 | | linters | FAIL | FAIL | -20 | | regression | PASS | -- | 0 | | regression | FAIL | FAIL | -20 | | tech_debt_cleanup | CLEANED | -- | 0 | | tech_debt_cleanup | NOTHING_TO_CLEAN | -- | 0 | | tech_debt_cleanup | BUILD_FAILED | FAIL | -20 | | tech_debt_cleanup | SKIPPED | ignored | 0 | | agent_review | CODE_ACCEPTABLE | -- | 0 | | agent_review | SUGGESTIONS (security/correctness) | CONCERN | -10 | | agent_review | SKIPPED | ignored | 0 | | log_analysis | CLEAN | -- | 0 | | log_analysis | WARNINGS_ONLY | -- | 0 | | log_analysis | REAL_BUGS_FOUND | FAIL | -20 | | log_analysis | SKIPPED / NO_LOG_SOURCES | ignored | 0 |

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

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

Runtime Summary Artifact

MANDATORY READ: Load shared/references/coordinator_summary_contract.md

Write .hex-skills/runtime-artifacts/runs/{run_id}/story-quality/{story_id}.json before finishing.

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)

| Phase | Worker | Context | |-------|--------|---------| | 2 | ln-511-code-quality-checker | Shared (Skill tool) — code metrics, MCP Ref, static analysis | | 3 | ln-512-tech-debt-cleaner | Shared (Skill tool) — auto-fix safe findings from ln-511 | | 4 | Inline agent review (Codex + Gemini) | Background — launched after ln-512, merged in Phase 9 | | 7 | ln-513-regression-checker | Shared (Skill tool) — full test suite after all changes | | 8 | ln-514-test-log-analyzer | Shared (Skill tool) — error classification + log quality after ln-513 |

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 normalized verdict

Critical Rules

  • Always calculate normalized 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 runtime started and Phase 4 launch checkpoint recorded
  • [ ] Agent review executed inline (or skipped if --fast-track), results merged in Phase 9
  • [ ] All Codex/Gemini processes verified dead after Phase 9 merge AND after each Phase 10 iteration (no orphaned processes)
  • [ ] 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)
  • [ ] Normalized verdict calculated + aggregated results returned
  • [ ] Story-quality summary artifact written to the shared location

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
  • Review runtime contract: shared/references/review_runtime_contract.md
  • Agent review memory: shared/references/agent_review_memory.md
  • Review templates: shared/agents/prompt_templates/review_base.md + modes/code.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

Quality Coordinator Skill | Agent Skills