Agent-Skills.md

Agent Skills: ln-820-dependency-optimization-coordinator

Upgrades dependencies across all detected package managers. Use when updating npm, NuGet, or pip packages project-wide.

UncategorizedID: levnikolaevich/claude-code-skills/ln-820-dependency-optimization-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/plugins/optimization-suite/skills/ln-820-dependency-optimization-coordinator

Skill Files

Browse the full folder contents for ln-820-dependency-optimization-coordinator.

Download Skill

Loading file tree…

plugins/optimization-suite/skills/ln-820-dependency-optimization-coordinator/SKILL.md

Skill Metadata

Name
ln-820-dependency-optimization-coordinator
Description
"Upgrades dependencies across all detected package managers. Use when updating npm, NuGet, or pip packages project-wide."

Paths: File paths (references/, ../ln-*) are relative to this skill directory.

ln-820-dependency-optimization-coordinator

Type: L2 Domain Coordinator Category: 8XX Optimization

Runtime-backed coordinator for cross-stack dependency upgrades. Detects package managers, delegates to one worker per manager, records machine-readable worker summaries, and emits a final coordinator summary.

Overview

| Aspect | Details | |--------|---------| | Input | Project path plus optional upgrade policy | | Output | Aggregated dependency upgrade report with per-worker results | | Workers | ln-821 (npm), ln-822 (nuget), ln-823 (pip) | | Runtime | .hex-skills/dependency/runtime/runs/{run_id}/ |

Workflow

Phases: Pre-flight -> Detect Package Managers -> Security Audit -> Delegate Upgrades -> Collect Results -> Verify Summary -> Report

Runtime Contract

MANDATORY READ: Load references/ci_tool_detection.md MANDATORY READ: Load references/coordinator_runtime_contract.md, references/dependency_runtime_contract.md, references/coordinator_summary_contract.md

Runtime CLI:

node references/scripts/dependency-runtime/cli.mjs start --identifier repo-deps --manifest-file <file>
node references/scripts/dependency-runtime/cli.mjs status --identifier repo-deps
node references/scripts/dependency-runtime/cli.mjs checkpoint --phase PHASE_3_DELEGATE_UPGRADES --payload '{...}'
node references/scripts/dependency-runtime/cli.mjs record-worker-result --payload '{...}'
node references/scripts/dependency-runtime/cli.mjs record-summary --payload '{...}'
node references/scripts/dependency-runtime/cli.mjs advance --to PHASE_4_COLLECT_RESULTS
node references/scripts/dependency-runtime/cli.mjs complete

Required state fields:

  • worker_plan
  • worker_results
  • child_runs
  • verification_passed
  • report_ready
  • summary_recorded

Domain checkpoints:

  • PHASE_1_DETECT_PACKAGE_MANAGERS: detected managers, indicator files, skipped managers
  • PHASE_2_SECURITY_AUDIT: per-manager audit verdicts, blocking findings, release-age policy
  • PHASE_3_DELEGATE_UPGRADES: one child_run per delegated worker with worker name, identifier, runId, and summaryArtifactPath
  • PHASE_4_COLLECT_RESULTS: recorded worker summaries plus unresolved failures or warnings
  • PHASE_5_VERIFY_SUMMARY: final report path, verification verdict, summary readiness

Guard rules:

  • do not advance from PHASE_3_DELEGATE_UPGRADES until every planned worker emitted a valid dependency-worker summary
  • do not complete until the final report checkpoint exists and the dependency-coordinator summary was recorded
  • consume worker JSON summaries only; never infer worker status from prose output

Phase 0: Pre-flight

Confirm the project is a valid candidate for dependency work before starting the runtime.

| Check | Method | Block if | |-------|--------|----------| | Manifest exists | Runtime start validation | Missing | | Project path exists | File inspection | Missing | | Upgrade policy provided | Manifest or defaults | No | | Existing active run for identifier | Runtime active pointer | Conflicting active run |

Default options:

| Option | Default | Meaning | |--------|---------|---------| | upgradeType | major | major, minor, or patch | | allowBreaking | true | allow major-version migrations | | minimumReleaseAge | 14 | skip very recent releases unless security requires them | | testAfterUpgrade | true | workers verify build/tests after changes |

Phase 1: Detect Package Managers

Detect one worker target per package-manager family.

| Package Manager | Indicator Files | Worker | |-----------------|-----------------|--------| | npm | package.json + package-lock.json | ln-821 | | yarn | package.json + yarn.lock | ln-821 | | pnpm | package.json + pnpm-lock.yaml | ln-821 | | nuget | *.csproj or *.sln | ln-822 | | pip | requirements.txt | ln-823 | | poetry | pyproject.toml + poetry.lock | ln-823 | | pipenv | Pipfile + Pipfile.lock | ln-823 |

Checkpoint payload must include:

  • detected_managers
  • indicator_paths
  • worker_plan
  • skipped_reasons

Phase 2: Security Audit

Perform lightweight pre-flight security and freshness checks before delegating heavy upgrade work.

| Manager Family | Command | Block Condition | |----------------|---------|-----------------| | Node.js | npm audit --audit-level=high or manager equivalent | Critical vulnerability with no allowed override | | NuGet | dotnet list package --vulnerable | Critical vulnerability with no allowed override | | Python | pip-audit --json or manager equivalent | Critical vulnerability with no allowed override |

Release-age gate:

| Option | Default | Description | |--------|---------|-------------| | minimumReleaseAge | 14 days | Skip packages released too recently | | ignoreReleaseAge | false | Override for urgent security patches |

Checkpoint payload must include:

  • audit_results
  • blocking_findings
  • release_age_policy
  • managers_cleared_for_delegation

Phase 3: Delegate Upgrades

Delegate one child run per worker family. Child runs must be deterministic and artifact-driven.

Delegate using the concrete worker identities selected by the routing table below. Do not synthesize family placeholders or guessed skill IDs in prompts.

Delegation context:

| Field | Type | Description | |-------|------|-------------| | projectPath | string | Absolute path to target project | | packageManager | enum | npm, yarn, pnpm, nuget, pip, poetry, pipenv | | identifier | string | Stable worker identifier inside the run | | runId | string | Deterministic child run id | | summaryArtifactPath | string | Exact JSON path for the worker summary | | options | object | Upgrade policy, verification flags, safety flags |

Worker selection:

| Manager Family | Worker | Notes | |----------------|--------|-------| | npm, yarn, pnpm | ln-821-npm-upgrader | One child run per detected Node manager | | nuget | ln-822-nuget-upgrader | One child run for .NET | | pip, poetry, pipenv | ln-823-pip-upgrader | One child run per detected Python manager |

After launching each worker:

  1. Checkpoint child_run under PHASE_3_DELEGATE_UPGRADES.
  2. Wait for the emitted dependency-worker summary envelope.
  3. Record the worker summary with record-worker-result.

Phase 4: Collect Results

Aggregate validated worker summaries only.

Worker summary fields consumed by the coordinator:

| Field | Description | |-------|-------------| | producer_skill | worker identity (ln-821, ln-822, ln-823) | | summary_kind | must be dependency-worker | | identifier | stable worker identifier | | payload.status | completed, partial, or failed | | payload.upgrades | applied upgrades with before/after versions | | payload.warnings | non-blocking issues | | payload.verification | build/test verification result | | payload.artifact_path | worker-owned durable report path, if any |

Collection output:

  • worker_results
  • success_count
  • partial_count
  • failed_count
  • blocking_failures

Phase 5: Verify Summary

Prepare the final durable report and verify the coordinator can finish deterministically.

Verification checklist:

  • every planned worker produced one valid summary envelope
  • aggregate counts match recorded worker results
  • final report path exists or is ready to be written
  • report_ready and verification_passed are true before completion

Failure handling:

  1. Keep successful worker results intact.
  2. Mark failed workers explicitly in the coordinator report.
  3. Do not invent rollback actions beyond what workers already verified.

Phase 6: Report

Coordinator report schema:

| Field | Description | |-------|-------------| | package_managers | detected managers handled in this run | | workers_activated | delegated workers | | total_packages | packages analyzed across workers | | upgraded | successful upgrades | | skipped | already latest or policy-skipped packages | | failed | packages or worker runs that failed | | breaking_changes | major-version upgrades or migrations | | verification_passed | aggregate verification verdict | | per_worker[] | machine-readable worker result summaries | | warnings[] | cross-worker warnings |

Completion sequence:

  1. Write the durable report.
  2. Checkpoint the report path and verification verdict.
  3. Record the dependency-coordinator summary envelope with record-summary.
  4. Complete runtime only after the report checkpoint and coordinator summary exist.

Configuration

Options:
  upgradeType: major          # major | minor | patch
  allowBreaking: true
  minimumReleaseAge: 14
  auditLevel: high            # none | low | moderate | high | critical
  testAfterUpgrade: true
  buildAfterUpgrade: true
  rollbackOnFailure: true
  skipDev: false
  skipOptional: true

Error Handling

Recoverable:

| Error | Recovery | |-------|----------| | Peer dependency conflict | Keep worker result as partial, continue collecting | | Build failure in one worker | Preserve failure, continue other workers | | Network timeout | Worker retries locally, then reports failure |

Fatal:

| Error | Action | |-------|--------| | No package managers found | Finish with empty-result report | | Runtime validation failure | Pause run and require intervention | | Missing worker summary for planned child run | Do not advance from collection |

References

TodoWrite format (mandatory):

- Detect package managers (in_progress)
- Delegate ln-821-npm-upgrader child runs (pending)
- Delegate ln-822-nuget-upgrader child runs (pending)
- Delegate ln-823-pip-upgrader child runs (pending)
- Aggregate dependency-worker summaries (pending)

Worker Invocation (MANDATORY)

Host Skill Invocation: Skill(skill: "...", args: "...") is mandatory delegation.

  • Claude: call the Skill tool exactly as shown.
  • Codex: if no Skill tool exists, locate the named skill in available skills, read its SKILL.md, treat args as $ARGUMENTS, execute that skill workflow, then return here with its result/artifact.
  • Do not inline worker logic or mark the worker complete without executing the target skill.

| Phase | Worker | Context | |-------|--------|---------| | 3 | ln-821-npm-upgrader | Isolated child run with packageManager, runId, and exact summaryArtifactPath | | 3 | ln-822-nuget-upgrader | Isolated child run with packageManager, runId, and exact summaryArtifactPath | | 3 | ln-823-pip-upgrader | Isolated child run with packageManager, runId, and exact summaryArtifactPath |

All workers: start the child runtime, checkpoint the child_run metadata, then invoke the worker skill explicitly and consume the emitted dependency-worker summary envelope via record-worker-result.

# One invocation per detected package manager (sequential per family):
node references/scripts/dependency-runtime/cli.mjs start --skill {worker} --identifier {packageManager} --manifest-file {workerManifestPath} --run-id {childRunId} --summary-artifact-path {childSummaryArtifactPath}
node references/scripts/optimization-runtime/cli.mjs checkpoint --phase PHASE_3_DELEGATE --payload '{"child_run":{"worker":"{worker}","run_id":"{childRunId}","summary_artifact_path":"{childSummaryArtifactPath}","package_manager":"{packageManager}"}}'
Skill(skill: "{worker}", args: "{packageManager} --run-id {childRunId} --summary-artifact-path {childSummaryArtifactPath}")
Read {childSummaryArtifactPath}
node references/scripts/optimization-runtime/cli.mjs record-worker-result --payload-file {childSummaryArtifactPath}

Worker token substitution: {worker} is one of ln-821-npm-upgrader, ln-822-nuget-upgrader, ln-823-pip-upgrader.

Definition of Done

  • [ ] Runtime started with a validated manifest and stable identifier
  • [ ] Package managers detected from project indicators
  • [ ] Pre-flight security and release-age checks completed
  • [ ] One child run delegated per planned worker family
  • [ ] Every child run emitted a valid dependency-worker summary
  • [ ] Coordinator report aggregates per-worker upgrades, warnings, and verification results
  • [ ] Final dependency-coordinator summary recorded before completion

Phase 7: Meta-Analysis

Optional reference: load references/meta_analysis_protocol.md only when the user asks for post-run meta-analysis or protocol-formatted run reflection.

Skill type: optimization-coordinator. When requested, run after all phases complete. Output to chat using the optimization-coordinator format.

Version: 1.1.0 Last Updated: 2026-01-10