Developer Tools

The Task Runner

Every project accumulates its own dialect of development commands. Python projects might use uv run pytest for tests and uv run ruff check for linting. TypeScript projects might use pnpm test and pnpm run lint. When both languages coexist in the same repository, you end up juggling two sets of invocations, two sets of flags, and two mental models. The WSD task runner eliminates this friction.

The task runner is wsd.py, a unified command-line interface that sits at the root of your project. If you installed via pipx, the wsd command has been set up globally on your system, which will invoke the wsd.py in your current working directory. You can then run regular developer commands as wsd test, wsd lint, wsd format, and the runner figures out the rest. It examines your project’s configuration files (pyproject.toml for Python, package.json for Node.js) and routes each command to the appropriate language-specific tool. A Python project’s wsd test runs pytest. A TypeScript project’s wsd test runs jest (or whichever test framework your package.json scripts define). A project with both languages runs both test suites sequentially.

This auto-detection extends to package managers as well. The runner identifies your Node.js package manager from its lock file — pnpm, npm, yarn, or bun — and uses it for all Node.js commands. You never need to tell it which tools you are using.

The commands follow a naming convention that makes their behavior predictable without consulting documentation. The suffixed form always flips the default behavior of the base command: wsd lint is read-only, so wsd lint:fix adds mutation; wsd format mutates files, so wsd format:check removes mutation. The base commands in the table below indicate which are read-only and which modify files.

Here are the commands you will use most often:

wsd test              # Run the test suite
wsd lint              # Check for linting issues (read-only)
wsd lint:fix          # Fix linting issues automatically
wsd format            # Format code files
wsd format:check      # Check formatting without changes (read-only)
wsd type              # Run type checking
wsd validate          # Run lint + type + format:check together

In a multi-language project, each of these commands runs for every detected language. wsd lint runs ruff over your Python directories and eslint over your TypeScript code. If either check fails, execution stops immediately — the fail-fast behavior ensures that problems are caught regardless of which language introduced them.

Python commands that target specific directories — linting, formatting, type checking, security scanning — read their directory configuration from [tool.wsd] in pyproject.toml. Node.js commands delegate to your package.json scripts and need no additional WSD configuration. The /wsd:setup skill configures all of this during initial project setup.

The task runner has zero external dependencies of its own and uses only Python’s standard library. For the complete command reference, including build, development server, dependency management, and security scanning commands, see dev/wsd/Task-Runner-Guide.md in your WSD installation.

Health Checks

The health check system is WSD’s comprehensive code quality validator. Where individual commands like wsd lint or wsd type check a single dimension of quality, wsd health runs all of them in sequence and produces a unified report. It is what the Health-Inspector agent runs during the QA gauntlet, and it is the command you will use most often to verify that your project is in good shape before committing.

The health check covers seven quality dimensions:

1. Build Integrity — Can the project compile or build successfully?
2. Type Safety — Are types correct according to the language’s type system?
3. Security Analysis — Are there code-level security vulnerabilities?
4. Dependency Safety — Do installed packages have known CVEs?
5. Documentation Quality — Is code well-documented (dataclass fields, public methods)?
6. Code Quality — Does code follow linting and style rules?
7. Code Formatting — Is code consistently formatted?

Both Python and Node.js have health check implementations that cover all seven dimensions with language-appropriate tooling. In a multi-language project, wsd health runs both health checks sequentially.

The system supports three modes:

wsd health              # Standard check (uses cached state for speed)
wsd health:clean        # Clears caches first (deterministic results)
wsd health:aggressive   # Applies unsafe auto-fixes (review changes carefully)

The standard mode is fastest because it reuses cached type-checking state from previous runs. The clean mode clears those caches before running, producing deterministic results that do not depend on prior state — this is the mode recommended before commits and in CI/CD pipelines. The aggressive mode goes further by applying auto-fixes that may change code behavior, which is useful for cleaning up a messy codebase but should always be followed by careful review.

When the check completes, it produces a summary table:

============================================================
HEALTH CHECK SUMMARY
============================================================
Check                Status          Details
------------------------------------------------------------
Build Validation     ✅ PASSED
Type Checking        ✅ PASSED
Security Scan        ✅ PASSED
Dependency Audit     ✅ PASSED
Doc Completeness     ✅ PASSED
Linting              ✅ PASSED
Code Formatting      ✅ PASSED
============================================================

Each check reports one of four statuses: PASSED, FAILED (with details about what went wrong), WARNING (passed with caveats), or SKIPPED (not applicable for this project type). A SKIPPED status is not a failure — it simply means that check does not apply. A JavaScript project will show “Build Validation: SKIPPED — JavaScript project” because there is no compilation step, and that is perfectly normal.

All checks run regardless of individual failures — the system does not stop at the first problem. This gives you a complete picture of everything that needs attention rather than forcing you to fix issues one at a time. The overall exit code is zero only when every applicable check passes, making the health check suitable for integration into CI/CD pipelines and pre-commit hooks.

For detailed information about the specific tools used for each language, configuration options, and troubleshooting, see dev/wsd/Health-Check-Guide.md in your WSD installation.

Code Documentation

WSD generates two types of documentation from your source code, each serving a different audience.

API documentation is generated by standard tools (pdoc for Python, TypeDoc for TypeScript, JSDoc for JavaScript) and produces human-readable HTML output in dev/reports/. These are the reference pages a developer consults when they need to understand a function’s parameters, a class’s interface, or a module’s exports.

Code maps are generated by WSD’s own scripts and produce AI-oriented markdown summaries in docs/reports/. These are concise structural overviews of your codebase (module hierarchies, class definitions, function signatures) formatted for consumption by AI agents during context loading. Agent integration with code maps is still maturing, but the reports are available as context you can reference directly or feed into prompts when you need a structural overview of your codebase.

Both types are generated through a single command:

wsd docs:update       # Update documentation (incremental)
wsd docs:full         # Full documentation rebuild

The incremental update is the common choice; it regenerates only what has changed. The full rebuild regenerates everything from scratch, which is useful after significant refactoring or when you suspect the incremental output has drifted.

For the complete documentation generation reference, including configuration options and output directory structure, see dev/wsd/Code-Doc-Guide.md in your WSD installation.