Repo Maintenance Node

Node/TypeScript Repository Maintenance

Perform a comprehensive health sweep for Node.js and TypeScript repositories. Checks formatting, linting, type errors, dead code, dependency hygiene, cross-package consistency, and open Renovate PRs. Reads AGENTS.md (or CLAUDE.md) for repo-specific commands before running any checks.

Arguments

• --dry-run (optional): Report issues without making changes.
• --section <name> (optional): Run only a specific section. Valid values: formatting, dead-code, deps, renovate. If omitted, run all sections.

Target: $ARGUMENTS (defaults to all sections, applying fixes)

Execution Strategy

This skill is designed for parallel execution to minimize wall clock time. After Step 0 (configuration discovery), launch Agents A and B in parallel for the investigative workstreams. Once both complete, run Agent C (Code Quality) last so formatting/linting/type-check fixes apply on top of any changes from earlier steps. Only the dependency section has an additional internal ordering constraint (Renovate PRs must complete before filtering outdated deps).

flowchart TD
    S0["Step 0: Read config"] --> A["Agent A: Dead Code Detection"]
    S0 --> B["Agent B: Dependencies & Renovate"]

    B --> B1["B1: Renovate PRs (gh API)"]
    B --> B2["B2: Cross-package validation"]
    B --> B3["B3: Dedupe check"]
    B --> B5["B5: Peer dependency warnings"]
    B1 --> B4["B4: Outdated deps (filtered by B1)"]

    A --> C["Agent C: Code Quality (format + lint + typecheck)"]
    B2 --> C
    B3 --> C
    B4 --> C
    B5 --> C

    C --> F["Step Final: Merge results → Generate report"]

When launching parallel agents, pass them the discovered configuration from Step 0 (package manager, available scripts, monorepo status) so they don't need to re-read config files.

Process

0. Read Repo-Specific Configuration

Before running any checks, read the repository's configuration files to discover project-specific commands and conventions:

1. Read AGENTS.md (if it exists) for:
   • Lint / format / typecheck commands
   • Build commands
   • Test commands
   • Any repo-specific maintenance notes
2. Fall back to CLAUDE.md if AGENTS.md does not exist.
3. Read package.json (or the workspace root manifest) to identify:
   • Available scripts (lint, format, typecheck, etc.)
   • Package manager (pnpm, npm, yarn)
   • Whether this is a monorepo (look for workspaces field or pnpm-workspace.yaml)

Store discovered commands for use in subsequent steps. If a command is not found, skip the corresponding check and note it in the report.

Agent A: Dead Code Detection

Goal: Identify unused exports, imports, and files.

Launch this as a parallel Agent subagent.

Note: This section is complementary to deterministic tools like knip. If knip is configured in the repo, prefer running it. Otherwise, use heuristic detection.

1. Check for knip:

   # Look for knip in package.json scripts or devDependencies
   grep -q '"knip"' package.json && echo "knip available"

   If knip is available:

   pnpm knip            # or: npx knip

   If knip is not available, perform heuristic checks:

2. Heuristic dead code scan (when knip is unavailable):

   • Search for exported symbols that have no import references elsewhere:

     grep -rn "export \(const\|function\|class\|type\|interface\|enum\)" src/

   • For each export, check if it's imported anywhere else in the codebase.
   • Flag files with zero inbound imports (potential dead files).

3. Report findings as a list of potentially unused items. Do NOT auto-delete — dead code removal requires human review.

Agent B: Dependencies & Renovate

Goal: Surface Renovate PRs, check dependency health, and report outdated packages not already covered by Renovate.

Launch this as a parallel Agent subagent. Within this agent, run B1, B2, B3, and B5 in parallel, then run B4 after B1 completes (B4 needs the Renovate package list to filter outdated deps).

B1. Open Renovate PRs

1. List open PRs from Renovate:

   gh pr list --author "renovate[bot]" --state open --json number,title,url \
     --jq '.[] | "- #\(.number) \(.title) \(.url)"'

   If the above returns no results, also try:

   gh pr list --author "renovate" --state open --json number,title,url \
     --jq '.[] | "- #\(.number) \(.title) \(.url)"'

2. For each open Renovate PR, suggest running /renovate-review:

   Run `/renovate-review <PR-NUMBER>` to assess safety and effort.

3. Collect the package names covered by open Renovate PRs (parse the PR titles — Renovate titles typically follow Update <package> to <version> or Update dependency <package> to <version>). Store this set for use in B4.

4. If no open Renovate PRs are found, report that the repo is up to date with Renovate.

B2. Cross-Package Dependency Validation (Monorepos)

If this is a monorepo:

1. Check for version inconsistencies across packages:

   # For pnpm workspaces with catalogs
   cat pnpm-workspace.yaml
   
   # For npm/yarn workspaces, compare package.json files
   find . -name "package.json" -not -path "*/node_modules/*" \
     -exec grep -l '"dependencies"' {} \;

2. Flag any package that pins a different version of the same dependency than other packages in the workspace (unless the workspace uses a catalog or resolutions to centralize versions).

B3. Duplicate Dependencies in Lockfile

1. Check for duplicates:

   # pnpm
   pnpm dedupe --check   # or: pnpm dedupe (to fix)
   
   # npm
   npm dedupe --dry-run
   
   # yarn
   yarn dedupe --check

2. If --dry-run is not set and duplicates are found, run the dedup command and commit the result:

   pnpm dedupe
   git add pnpm-lock.yaml
   git commit -m "chore(deps): deduplicate lockfile"

B4. Outdated Dependencies (Not Covered by Renovate)

Depends on B1 — wait for Renovate PR list before running.

1. Run the package manager's outdated check:

   pnpm outdated         # or: npm outdated / yarn outdated

2. Filter out any packages that already have an open Renovate PR (from the set collected in B1). Only report dependencies that are outdated AND not already being handled by Renovate.

3. Categorize the remaining results:

   • Patch updates — safe to update
   • Minor updates — likely safe, review changelogs
   • Major updates — requires migration planning

4. Report a summary table of outdated dependencies by category.