Validate Code

Validate Code

Run the codebase's full automated quality suite against your changes before committing. This prevents pre-commit hook failures, failed CI jobs, and wasted triage cycles.

When to Use This Skill

• After finishing implementation of any task — TypeScript, Python, Markdown, YAML, JSON
• Before invoking the submit-changes skill
• When asked to "validate", "check code quality", "run linting", or "verify changes are clean"
• Anytime you add new dependencies, exports, or files (Knip detects unused ones)

What lint-codebase Covers

The lint-codebase Nx target hangs every quality tool off dependsOn, so one invocation builds one task graph:

Validation Workflow

Step 1 — Auto-fix

Run lint-codebase in write mode to automatically fix all auto-fixable issues (formatting, linting, unused-code whitelist entries, sync checks):

pnpm exec nx affected --target=lint-codebase --configuration=write --base=main

For new/untracked files that nx affected won't detect, target the relevant project(s) directly:

pnpm exec nx run <project>:lint-codebase --configuration=write

Review the changes made. If any files were modified, inspect them to ensure the auto-fixes are correct.

Step 2 — Verify

Run lint-codebase in check mode to confirm no issues remain:

pnpm exec nx affected --target=lint-codebase --configuration=check --base=main

All checks must pass before proceeding. If any fail, triage each failure:

• Format/lint: Fix the reported violations manually, then re-run.
• Typecheck: Fix type errors — see write-typescript skill for patterns.
• Spell-check: Either fix the typo, or add the word to the appropriate dictionary in configuration/.cspell/.
• Knip (unused code): Remove the unused export/file/dependency, or add an exception in configuration/knip.config.ts.
• Fallow dead-code (unused code): The same finding from the other direction — knip runs once per workspace, fallow once over all of them. The two configurations are kept in step, so fix the code and both pass; if an exception is genuinely warranted, add it to configuration/fallow.config.jsonc and its counterpart in configuration/knip.config.ts, or the next run of the other tool reports what you just excused. Prefer overrides to ignorePatterns when suppressing a file: ignorePatterns also drops what that file imports out of the module graph, which makes reachable files read as dead.
• Sync checks: Run the failing synchronization's own write configuration (e.g., nx run synchronization:conventional-config:write), or nx run-many --targets=conformetry-generators,conventional-config,devcontainer-configuration,pull-request-template,skill-exclusions --configuration=write for every derivation at once.
• Check skill exclusions: Add the exclusion lines the failure names to configuration/.prettierignore, configuration/.codometerignore, and .gitattributes. This leaf has no write variant.

See triage-submission for detailed per-tool fix instructions.

Step 3 — Done

Once both write and check pass cleanly, code quality is confirmed. Proceed to commit or hand off.

Step 4 — Coverage Gate (when required)

lint-codebase does not enforce Vitest coverage thresholds. If the task, project, or CI requires a coverage target, run the coverage configuration explicitly after Step 3:

pnpm exec nx run <project>:vitest --configuration=coverage

If the threshold fails by a small margin, prioritize adding targeted tests for uncovered guard branches (if (!value), fallback paths, sparse/undefined handling) instead of broad test rewrites.

Step 5 — Type Coverage Gate (TypeScript projects with target)

If a touched TypeScript project defines a type-coverage target, treat it as a required gate and run it explicitly after Step 3.

pnpm exec nx run <project>:typecheck
pnpm exec nx run <project>:type-coverage

✅ Best practice: Run typecheck and type-coverage back-to-back for the same project while stabilizing changes to avoid late iteration loops.

Common Patterns

New TypeScript files added

# Target the specific project since affected may not pick up new files
pnpm exec nx run <project>:lint-codebase --configuration=write
pnpm exec nx run <project>:lint-codebase --configuration=check

Refactor-heavy test changes

# 1) Auto-fix + quality checks
pnpm exec nx run <project>:lint-codebase --configuration=write
pnpm exec nx run <project>:lint-codebase --configuration=check

# 2) Re-verify coverage gates explicitly
pnpm exec nx run <project>:vitest --configuration=coverage

# 3) If available, enforce type coverage gate too
pnpm exec nx run <project>:typecheck
pnpm exec nx run <project>:type-coverage

New skill added

A skill is one directory, .agents/skills/<skill-name>/SKILL.md. .claude/skills and .github/skills are symlinks to .agents/skills, so that one copy already serves both harnesses — there is no second copy to create and no table of contents to regenerate. AGENTS.md deliberately does not list the skills; agents are handed the installed set directly.

The only extra command applies to a skill installed from another repository, which skills update records in skills-lock.json:

# Regenerate the exclusion blocks that keep locked skills out of prettier,
# codometer, Linguist, cspell, and markdownlint
pnpm exec nx run synchronization:skill-exclusions:write

AGENTS.md edited

The types and scopes tables in AGENTS.md are generated between marker comments from configuration/conventional.config.cjs. Edit the config, never the table, then regenerate:

pnpm exec nx run synchronization:conventional-config:write
pnpm exec nx run synchronization:conventional-config:check

Everything outside those markers is hand-written and needs no synchronization run.

Resources

• triage-submission skill — Detailed per-tool fix instructions for pre-commit failures
• triage-deployment skill — Detailed per-tool fix instructions for CI failures
• write-typescript skill — TypeScript strict mode patterns