From holistic-linting
Guides Claude Code orchestrators to delegate linting, formatting, root-cause resolution, and architecture reviews to specialized agents without running linters themselves.
How this skill is triggered — by the user, by Claude, or both
Slash command
/holistic-linting:holistic-linting-orchestratorThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
This skill provides orchestrator-specific workflows for delegating linting and resolution tasks to specialized agents.
This skill provides orchestrator-specific workflows for delegating linting and resolution tasks to specialized agents.
Use this skill when you are an orchestrator (interactive Claude Code CLI) after completing implementation work. This skill guides delegation patterns for linting, quality checks, and architectural review.
Do NOT use this skill if you are a sub-agent executing a delegated task. Sub-agents should follow the linter-specific resolution workflows in the holistic-linting-resolver skill.
CRITICAL PRINCIPLE: Orchestrators delegate work to agents. Orchestrators do NOT run formatting commands, linting commands, or quality checks themselves. The agent does ALL work (formatting, linting, resolution). The orchestrator only delegates tasks and reads reports to determine if more work is needed.
WHY THIS MATTERS:
The orchestrator MUST follow this delegation-first workflow:
Step 1: Delegate to linting-root-cause-resolver immediately
Delegate linting resolution WITHOUT running any linting commands first:
Agent(
agent="holistic-linting:linting-root-cause-resolver",
prompt="Format, lint, and resolve any issues in <file_path>"
)
What to delegate immediately, without pre-gathering data:
Reason: The agent follows systematic root-cause analysis workflows. It autonomously:
.claude/reports/ and .claude/artifacts/Multiple Files Modified:
Launch concurrent agents (one per file) WITHOUT pre-gathering linting data:
Agent(subagent_type="holistic-linting:linting-root-cause-resolver", prompt="Format, lint, and resolve any issues in src/auth.py")
Agent(subagent_type="holistic-linting:linting-root-cause-resolver", prompt="Format, lint, and resolve any issues in src/api.py")
Agent(subagent_type="holistic-linting:linting-root-cause-resolver", prompt="Format, lint, and resolve any issues in tests/test_auth.py")
Reason for concurrency: Independent file resolutions proceed in parallel, reducing total time.
Step 2: Read resolution reports — check for UNRESOLVED items before proceeding
After all linting agents complete, read each resolution report:
Read(".claude/reports/linting-resolution-[timestamp].md")
For each report, check these sections in order:
**UNRESOLVED items:** — if nonzero, surface each item to the user NOW (see below)## Pre-Existing Issues Recorded — acknowledge what was found and where it was recorded**Issues after resolution:** 0 — confirm all touched files are cleanIf UNRESOLVED items exist:
Present each UNRESOLVED item to the user with the constraint documented by the resolver. Ask for one of three decisions:
The task is NOT complete while UNRESOLVED items remain without a user decision. This is a hard gate.
If all issues resolved and zero UNRESOLVED items: proceed to Step 3.
Step 3: Delegate to post-linting-architecture-reviewer
After confirming zero UNRESOLVED items (or user decisions on each), delegate architectural review:
Agent(
agent="post-linting-architecture-reviewer",
prompt="Review linting resolution for <file_path>"
)
What the reviewer does:
Step 4: Read reviewer report
The orchestrator reads the review report to determine if additional work is needed:
ls -la .claude/reports/architectural-review-*.md
Read the most recent review report:
Read(".claude/reports/architectural-review-[timestamp].md")
Orchestrator's role: Read reports and decide next steps. Do NOT run linting commands to verify agent's work.
Step 5: If issues found, delegate back to linting agent
If architectural review identifies problems with resolution:
Agent(
agent="holistic-linting:linting-root-cause-resolver",
prompt="Address issues found in architectural review: .claude/reports/architectural-review-[timestamp].md
Issues identified:
- [Summary of finding 1]
- [Summary of finding 2]
Review report contains detailed context and proposed solutions."
)
Step 6: Repeat review if needed
After re-resolution, delegate to reviewer again:
Agent(
agent="post-linting-architecture-reviewer",
prompt="Review updated linting resolution for <file_path>"
)
Continue workflow until architectural review reports clean results.
flowchart TD
Start([Implementation complete]) --> Step1[Step 1: Delegate to linting-root-cause-resolver\nagent formats, lints, resolves, records pre-existing issues]
Step1 --> Step2[Step 2: Read resolution report\ncheck UNRESOLVED items and pre-existing issues]
Step2 --> Q1{UNRESOLVED items?}
Q1 -->|Yes| User[Present to user — get decision\nsuppress / restructure / accept as backlog]
User --> Q2{User decision made?}
Q2 -->|Suppress| Resolver2[Delegate back to resolver\nwith explicit user-approved config change]
Q2 -->|Restructure| Resolver2
Q2 -->|Accept as backlog| Record[Record in tracking system\nthen continue]
Resolver2 --> Step2
Record --> Q1
Q1 -->|None| Step3[Step 3: Delegate to post-linting-architecture-reviewer]
Step3 --> Step4[Step 4: Read architectural review report]
Step4 --> Q3{Issues found?}
Q3 -->|Yes| Step5[Step 5: Delegate back to resolver with review context]
Step5 --> Step3
Q3 -->|No| Done([Task complete])
Key Principle: Orchestrator delegates immediately and reads reports. Agent does ALL actionable work. Orchestrator does NOT run commands or gather linting data.
Pre-gathering linting data before delegating — wastes orchestrator context and duplicates agent work:
# Wrong:
Bash("ruff check src/auth.py")
Agent(subagent_type="holistic-linting:linting-root-cause-resolver", prompt="Fix these errors: [pasted errors]")
# Correct:
Agent(subagent_type="holistic-linting:linting-root-cause-resolver", prompt="Format, lint, and resolve any issues in src/auth.py")
Skipping the UNRESOLVED check — allows incomplete resolutions to reach the architecture reviewer:
# Wrong:
# Agent completes → immediately delegate to reviewer
# Correct:
# Agent completes → read resolution report → check UNRESOLVED items → then delegate to reviewer
Dismissing pre-existing issues — every detected problem gets recorded:
# Wrong:
# "The resolver found issues in other files — pre-existing, not our concern."
# Correct:
# Read the Pre-Existing Issues Recorded section of the resolution report.
# Confirm each issue was classified and recorded.
# If the tracking system was created fresh, acknowledge it.
Verifying agent's work by running linters — read reports instead:
# Wrong:
Bash("ruff check src/auth.py") # After agent completed
# Correct:
Read(".claude/reports/linting-resolution-[timestamp].md")
# Report shows agent already verified with before/after linter output
npx claudepluginhub jamie-bitflight/claude_skills --plugin holistic-lintingAutomates format-lint-resolve pipelines for code editing tasks. Discovers linters from pyproject.toml/.pre-commit-config.yaml/package.json, fixes ruff/mypy/bandit issues, ensures quality before completion.
Orchestrates sub-agents with WHERE-WHAT-WHY context patterns and scientific method alignment. For task delegation, sub-agent prompts, multi-agent workflows, specialist coordination.
Enforces orchestrator discipline in Claude Code multi-agent workflows via PreToolUse hooks gating file reads, diagnostic commands, and bash misuse to prevent context waste.