DocsWatch

Detect verifiable documentation drift in TypeScript repositories before stale setup instructions, commands, and links reach users.

DocsWatch is an Agent Skill backed by a deterministic TypeScript checker. It compares repository facts instead of asking a language model to judge whether documentation looks current. Every finding has a stable rule ID, source location, severity, and machine-readable evidence; the agent explains those results without inventing or dismissing inconsistencies.

npx skills add montasim/DocsWatch --skill docs-watch -g -y

Why DocsWatch?

Documentation often drifts when environment variables, package scripts, files, or headings change. General prose review can suggest improvements, but it cannot prove those relationships disagree. DocsWatch focuses on four checks whose inputs and outcomes are inspectable:

Rule	Verifiable inconsistency
DW001	A variable declared in .env.example is absent from configured Markdown documentation.
DW002	A package-manager command in Markdown references a script missing from configured package.json files.
DW003	A local Markdown or supported raw-HTML file reference is missing, incorrectly cased, unsafe, or otherwise unresolvable.
DW004	A same-file or cross-file Markdown fragment does not match a generated heading or explicit anchor.

The checker returns explicit passed, failed, not-applicable, or errored outcomes for enabled rules. An incomplete scan cannot be presented as a clean repository.

Install the skill

Prerequisites

• Node.js 20 or newer
• An AI coding agent that supports the open Agent Skills SKILL.md format
• A TypeScript repository to audit, unless requireTypeScript is disabled explicitly

Install from the public GitHub repository with the Skills CLI:

npx skills add montasim/DocsWatch --skill docs-watch -g -y

The skill directory contains its standalone checker and runtime dependencies in one generated file, so the audited repository does not need to install DocsWatch dependencies. Restart or refresh the agent after installation if it does not detect newly installed skills automatically.

The bundled agents/openai.yaml supplies Codex interface metadata. The portable workflow itself is defined by SKILL.md and does not depend on provider-specific tools.

Use DocsWatch

Ask the agent to use DocsWatch for an evidence-backed audit:

Use the docs-watch skill to audit this TypeScript repository for documentation drift.

The skill runs the bundled checker and returns one consolidated report with rule outcomes and exact diagnostics. It does not rewrite documentation unless you separately ask the agent to fix supported findings.

You can also run the released checker directly from a clone:

node skills/docs-watch/scripts/docs-watch.mjs check /path/to/typescript-repository --format pretty
node skills/docs-watch/scripts/docs-watch.mjs check /path/to/typescript-repository --format json

Exit codes form part of the CLI contract:

Code	Meaning
0	The scan completed without error-severity findings. Warning or info findings may still exist; inspect the result status and diagnostics.
1	The scan completed with one or more error-severity findings.
2	The scan was incomplete or untrustworthy because invocation, eligibility, configuration, discovery, or parsing failed.

JSON output uses schema version 1 and reports top-level passed, findings, or errored status. Treat a repository as clean only when status is passed and the diagnostics list is empty.

Configuration

DocsWatch optionally reads docs-watch.config.json from the audited repository root. Configuration is data-only and is never executed.

{
  "include": ["**/*.{md,markdown,mdown}"],
  "exclude": ["**/node_modules/**", "**/dist/**", "**/.git/**"],
  "envExampleFiles": [".env.example"],
  "packageFiles": ["package.json"],
  "directoryIndexFiles": ["README.md", "index.md"],
  "directoryLinks": "allow",
  "requireTypeScript": true,
  "rules": {
    "DW001": "error",
    "DW002": "error",
    "DW003": "error",
    "DW004": "error"
  }
}

See the configuration reference for field behavior, severities, eligibility overrides, and safe path constraints. See the finding reference when interpreting or fixing a diagnostic.

How it works

flowchart LR
    A[Repository files] --> B[Deterministic fact extraction]
    B --> C[Normalized Markdown, env, and script facts]
    C --> D[DW001–DW004 rules]
    D --> E[Evidence-backed diagnostics]
    E --> F[JSON or terminal output]
    F --> G[Agent explanation]

Loading

The editable TypeScript implementation lives in packages/core and packages/cli. npm run build:skill bundles that implementation into skills/docs-watch/scripts/docs-watch.mjs. Tests exercise both the source packages and the standalone artifact to prevent the shipped skill from drifting from its implementation.

Development

Clone and validate the project:

git clone https://github.com/montasim/DocsWatch.git
cd DocsWatch
npm ci
npm test
npm run typecheck
npm run check

Command	Purpose
npm run build:skill	Rebuild the standalone skill checker from TypeScript source.
npm test	Rebuild the checker and run the source and standalone test suite.
npm run typecheck	Type-check the TypeScript packages without emitting files.
npm run check	Run DocsWatch against this repository as a dogfood audit.

Project structure

packages/core/                 Fact extraction, configuration, rules, and result contracts
packages/cli/                  CLI parsing, output rendering, and exit behavior
skills/docs-watch/             Portable Agent Skill and generated standalone checker
skills/docs-watch/references/  Configuration and finding guidance
scripts/build-skill.mjs        Deterministic bundle builder
docs/decisions/                Architecture decisions

Status and limitations

DocsWatch 0.1.1 is a focused local checker for TypeScript repositories.

• It checks configured Markdown, example env files, and package manifests; it does not judge prose quality or rewrite documentation automatically.
• External links are not fetched or validated.
• Package-script comparison is repository-wide across configured package files; it does not infer ambiguous workspace intent.
• Endpoint, exported-function, CLI-flag, configuration-schema, GitHub Action, PR-comment, dashboard, and organization-policy checks remain outside this release.
• The scanner reads repository data and does not execute audited configuration or package scripts.

Documentation

• Implementation plan and product boundary
• Deterministic evidence decision
• Configuration reference
• Finding reference
• Contribution guide
• Security policy

Support and security

Use GitHub Issues for reproducible bugs and focused feature requests. Include the DocsWatch version, command, result status, rule ID, and a minimal repository fixture when practical. Read SUPPORT.md for support boundaries.

Report vulnerabilities privately according to SECURITY.md. Do not post credentials, private repository content, or undisclosed vulnerabilities in a public issue.

Contributing

Issues and pull requests are welcome. Read CONTRIBUTING.md for the local workflow, generated-artifact contract, and required checks. Participation is governed by the Code of Conduct.

Funding

Optional support through SupportKori helps maintain the deterministic rules, compatibility fixtures, and distribution workflow.

Author

Built and maintained by Montasim.

License

DocsWatch is available under the MIT License.