AI Docs Toolkit

AI Docs Toolkit is a documentation toolkit for AI-assisted software development.

It treats documentation as an engineering interface between humans, AI agents, code, tests and change management. The project is post-MVP and is hardening planning, validation, distribution and integration workflows.

Purpose

The toolkit is intended for projects where:

• AI agents participate in implementation;
• system knowledge must stay readable for humans and usable by automation;
• documentation should define constraints, expected behavior and validation rules;
• changes should be traceable across business rules, architecture, contracts, modules, acceptance criteria and code.

The core idea is that documentation should not be a secondary artifact created after implementation. It should guide implementation, validation and review.

Current Status

The published beta package includes:

• schema and structure validation for Markdown documents with YAML front matter;
• document graph output;
• impact analysis;
• context bundle output;
• an executable ai-docs CLI;
• optional local MCP runtime entrypoint.

Installation

Install the published beta package:

python -m pip install ai-docs-toolkit==0.1.0b25
ai-docs --version

For ephemeral execution with uvx:

uvx --from ai-docs-toolkit==0.1.0b25 ai-docs --version

For the optional local MCP runtime:

python -m pip install "ai-docs-toolkit[mcp]==0.1.0b25"
ai-docs-mcp --project-root .

After a stable release exists, package install commands can omit the beta version pin.

Beta 12 excludes Markdown documents under work_history.archive_root from ai-docs validate checks while retaining successfully parsed archive ids for active-document relationship resolution. Validation summaries include archived_documents_excluded. Set work_history.archive_root: null to retain the previous validate-all behavior.

Beta 13 updates toolkit-managed agent instructions so agents proactively report blocking decisions, safe non-blocking defaults and implementation proposals. Existing projects should follow the packaged .ai-docs/templates/release/decision-visibility-beta-13.md migration note.

Beta 14 adds explicit code-to-module ownership mapping for ai-docs impact --changed, plus --base REF support for clean CI checkouts. Existing projects should follow the packaged .ai-docs/templates/release/cascade-impact-beta-14.md migration note.

Beta 15 restores the toolkit update route alongside the cascade adoption route in the managed agent-profile skill index. Existing projects should follow the packaged .ai-docs/templates/release/routing-restoration-beta-15.md migration note.

Beta 16 adds explicit completed-task retirement after current knowledge is transferred to canonical documents. Existing projects should follow the packaged .ai-docs/templates/release/task-retirement-beta-16.md migration note.

Beta 17 reconciles incoming request storage under canonical ai-docs/requests/, packages the referenced incoming request model and adds safe migration guidance for records created under legacy docs/requests/. Existing projects should follow the packaged .ai-docs/templates/release/incoming-request-storage-beta-17.md migration note.

Beta 19 bounds doctor Markdown discovery to project documentation roots, skips symlinked files and tolerates entries removed during traversal. Existing projects should follow .ai-docs/templates/release/doctor-filesystem-traversal-beta-19.md.

Beta 20 adds stable JSON output for ai-docs doctor, exposes the same contract through the read-only ai_docs_doctor MCP tool and records managed-file provenance in .ai-docs/managed-files.json. Existing projects should follow .ai-docs/templates/release/doctor-json-provenance-beta-20.md and reconnect long-lived MCP processes after upgrading.

Beta 21 adds the toolkit-managed documentation-change-review skill and its normative reference contract. Existing projects should follow .ai-docs/templates/release/documentation-change-review-beta-21.md and review managed-file changes before refreshing the agent profile.

Beta 22 adds the toolkit-managed incoming-request-triage skill, its normative contract and safe composition with the existing request/planning lifecycle. Existing projects should follow .ai-docs/templates/release/incoming-request-triage-beta-22.md and review managed-file changes before refreshing the agent profile.

Beta 23 adds the toolkit-managed documentation-cascade-authoring skill and its normative contract for authorized, top-down documentation changes. Existing projects should follow .ai-docs/templates/release/documentation-cascade-authoring-beta-23.md and review managed-file changes before refreshing the agent profile.

Beta 24 moves the optional MCP runtime to the stable Python MCP SDK 2.x line with dependency range mcp>=2,<3. Existing MCP tool/resource names and stdio entrypoints remain unchanged. Consumers upgrading from beta 23 should reinstall the MCP extra and reconnect every long-lived MCP client before verification.

Beta 25 preserves printable Unicode characters when toolkit operations rewrite Markdown YAML front matter. Planning lifecycle commands, task registry updates and Azure DevOps write-back no longer replace readable non-ASCII text with \uXXXX escape sequences. No manual migration is required.

Quick Start

Bootstrap a repository for AI Docs Toolkit:

ai-docs init
ai-docs validate

For a documentation-only bootstrap without AGENTS.md:

ai-docs init --profile minimal

The command creates missing toolkit files and skips existing files by default. Use --force only when you explicitly want to overwrite toolkit-owned target files.

Validate a configured project:

ai-docs validate

Generate machine-readable validation output:

ai-docs validate --json

Build a document graph:

ai-docs graph --format json

Analyze impact for changed files:

ai-docs impact --changed

Prepare an agent context bundle for changed files:

ai-docs context --changed

Repository Bootstrap

Repository bootstrap is an explicit command. Package installation does not modify project files.

Default agent-oriented bootstrap:

ai-docs init

Minimal bootstrap:

ai-docs init --profile minimal

The source repository may be private or unavailable to agents in consuming projects. Package usage does not require access to repository-local documentation files.

AI Agent Instructions

The package includes an agent-readable instruction document for install, update, bootstrap, validation and context commands.

Give this short instruction to an agent that can inspect installed package resources:

Install `ai-docs-toolkit`, then configure this repository by following the packaged instructions in `ai_docs_toolkit/docs/agent-installation.md`.

After installation, an agent can locate it with:

python -c "from importlib import resources; print(resources.files('ai_docs_toolkit').joinpath('docs/agent-installation.md'))"

Operators can give the prompt from that document to an AI agent when asking it to install or update the toolkit in a consuming repository.

Development

Source checkout development install:

python -m pip install -e ".[dev]"
ai-docs --version
ai-docs validate

Current CI/source checkout install contract:

python -m pip install -e .
ai-docs validate --json

License

License is not selected yet.