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. It provides versioned CLI and MCP tools, reusable agent instructions and project-owned documentation 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 stable 0.1.0 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 stable release:

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

For ephemeral execution with uvx:

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

For the optional local MCP runtime:

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

For the latest stable release, use python -m pip install --upgrade ai-docs-toolkit without an exact version pin.

Stable 0.1.0

This release completes the 0.1.0 beta series. Small edits and short bounded work can use sufficient session context; task records remain available when durable continuation, handoff or project policy requires them. Agent instructions are in English and were reviewed for compactness. Existing assignments carry across technical steps, and significant work includes a proportionate retrospective.

Context excludes archived history by default, supports an optional body budget and configurable traversal depth, and explains selection, exclusions and gaps. The budget is off by default; required documents remain whole on overflow. Strict JSON consumers must accept the added context metadata. CLI/MCP names and existing task/document ids are preserved.

When upgrading from 0.1.0b25, review ai-docs init --dry-run and ai-docs init --check, resolve modified managed files, then run ai-docs init. Existing AGENTS.md, config and local policy require a deliberate merge where applicable; keep project checks and restart MCP clients. Validate the project and inspect representative context output. See the packaged ai_docs_toolkit/docs/agent-installation.md, “Integrated Consumer Migration”, for commands, preservation rules and rollback. No bulk task/schema migration is required.

Compatibility was checked with five synthetic consumer profiles. Agent behavior was observed on one runtime; these checks do not establish universal performance improvements or real consumer pilot coverage.

Earlier Beta Changes

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.