documentation-robotics 0.4.0

CLI tool for managing federated architecture data models

Documentation Robotics (dr) CLI Tool

A command-line tool for managing federated architecture data models across 11 layers using standard specifications (ArchiMate, OpenAPI, JSON Schema, OpenTelemetry) and custom extensions.

Part of Documentation Robotics - For project overview, motivation, and full context, see the main README.

Installation

pip install documentation-robotics

Quick Links

• Install & Quick Start - Get started in minutes
• Claude Code Integration - AI-powered modeling
• Export Formats - ArchiMate, OpenAPI, PlantUML, etc.
• The Specification - Full spec documentation
• Development - Contributing to the CLI

Specification Conformance

Implements: Documentation Robotics Specification v0.2.0 Conformance Level: Full (All 11 layers)

Run dr conformance to see detailed conformance information.

Status

Current Version: v0.4.0 Specification Version: v0.2.0

This release adds comprehensive link management and migration capabilities:

• Model CRUD - Model initialization, element management, validation
• Changeset Management - Isolated workspaces for exploring changes before committing (like Git branches)
• Link Management - 60+ cross-layer reference patterns with validation, discovery, and documentation
• Managed Upgrades - Automated migration between specification versions with dry-run preview
• Validation & Integrity - Cross-layer references, projection, dependency tracking, link validation
• Export - Export to ArchiMate, OpenAPI, JSON Schema, PlantUML, Markdown, GraphML

The Vision

The dr CLI makes it easy and efficient to create, manage, validate, and export models that conform to the Documentation Robotics Specification.

Key Goals:

• Easy & Efficient - Simple commands for complex modeling tasks
• Standards-Based - Leverage existing tooling ecosystems (ArchiMate, OpenAPI, etc.)
• AI-Friendly - Designed for both human and AI agent interaction
• Git-Friendly - All models are text-based and version-controllable
• Collaborative - Built for CI/CD, automation, and team workflows

With unified tooling around a federated data model, we help architects, developers, and AI agents better understand, communicate, and evolve complex software systems.

For the broader motivation and context, see The Need in the main README.

Features

Foundation

• Model initialization with 11-layer structure
• Element management (add, update, remove) across all layers
• Changeset management - Create isolated workspaces to explore, compare, and apply changes
• Query and search capabilities
• Basic validation (schema, naming, cross-references)
• Manifest tracking and statistics

Link Management & Validation

• Link Registry - Machine-readable catalog of 60+ cross-layer reference patterns
• Link Discovery - Automatic detection and graph building of all inter-layer connections
• Link Validation - Verify existence, type compatibility, cardinality, and format
• Link Documentation - Generate Markdown, HTML, and Mermaid diagrams
• Link Navigation - Query, filter, and trace paths between elements
• Strict Mode - CI/CD-ready validation treating warnings as errors
• CLI Commands: dr links types|registry|stats|docs|list|find|validate|trace
• Migration Tools: dr migrate for automated spec version upgrades

Validation & Integrity

• Cross-layer reference tracking and validation
• Element projection across layers
• Dependency tracking and tracing
• Semantic validation
• Circular dependency detection
• Link validation with comprehensive error reporting

Export

• Export to ArchiMate 3.2 XML
• Export to OpenAPI 3.0 specifications
• Export to JSON Schema Draft 7
• Generate PlantUML diagrams (component, class, deployment)
• Generate Markdown documentation
• Export to GraphML for visualization

Claude Code Integration

• Natural Language Modeling - Create architecture models using conversational language
• Automatic Code Extraction - Extract models from existing codebases (Python, TypeScript, Java, Go)
• Intelligent Validation - Auto-fix common issues with confidence scoring
• Documentation Generation - Generate comprehensive docs and diagrams automatically
• Slash Commands - Quick access to common workflows (/dr-model, /dr-ingest, /dr-validate, /dr-links)
• Specialized Agents (5 total) - Autonomous agents for complex tasks:
  • dr-helper - Expert guidance and education
  • dr-ideator - Collaborative architectural exploration with research
  • dr-extractor - Code extraction with changeset safety
  • dr-validator - Validation and auto-fixing
  • dr-documenter - Comprehensive documentation generation
• Customization - Templates for organization-specific commands and agents

Try it:

dr claude install              # Install Claude integration
claude                         # Open Claude Code
> /dr-model Add order management service

See Claude Code Integration Guide for details.

Installation

# From the cli directory
cd cli

# Install from source
pip install -e .

# Install with development dependencies
pip install -e ".[dev]"

Quick Start

Traditional CLI Usage

# Initialize a new model
dr init my-project

# Add a business service
dr add business service --name "Customer Management" \
  --description "Manages customer lifecycle"

# Find an element
dr find business.service.customer-management

# List all elements in a layer
dr list business

# Validate the model (with link checking)
dr validate --validate-links

# Strict validation for CI/CD
dr validate --validate-links --strict-links

# Link management
dr links types                    # List available link types
dr links validate                 # Validate all links
dr links trace elem-1 elem-2      # Find path between elements
dr links docs                     # Generate documentation

# Migrate to latest spec version
dr migrate                        # Check what's needed
dr migrate --dry-run              # Preview changes
dr migrate --apply                # Apply migration

# Search across layers
dr search --type service --name "Customer*"

# Project to other layers
dr project business.service.customer-management --to application,api

# Trace dependencies
dr trace application.service.customer-service

# Export to various formats
dr export --format archimate
dr export --format openapi
dr export --format plantuml
dr export --format markdown
dr export --format all

AI-Powered Usage with Claude Code

# Install Claude Code integration
dr claude install

# Start Claude Code
claude

# Then use natural language:
> Create an architecture model for an e-commerce platform with:
> - Business services for orders, payments, and inventory
> - Application services that realize each business service
> - REST API operations
> - Security controls (OAuth2, rate limiting)
> - Monitoring metrics (availability, latency)

# Or use slash commands:
> /dr-model Add order management service
> /dr-ingest ./src/api --layers business,application,api
> /dr-validate --fix
> /dr-project business→application

# Extract from existing code:
> Please analyze my FastAPI application in ./src and create an architecture model

See Claude Code Integration Guide for full details.

Architecture Model Structure

The dr tool manages models with 11 layers as defined in the Documentation Robotics Specification. For a complete overview of all layers and their relationships, see The 11 Layers in the main README.

1. Motivation - Stakeholders, goals, requirements, principles (spec)
2. Business - Business services, processes, actors, roles (spec)
3. Security - Authentication, authorization, policies, threats (spec)
4. Application - Application services, components, interfaces (spec)
5. Technology - Infrastructure, nodes, devices, networks (spec)
6. API - REST APIs, operations, endpoints (OpenAPI) (spec)
7. Data Model - Entities, relationships (JSON Schema) (spec)
8. Data Store - Databases, tables, columns, constraints (spec)
9. UX - Screens, layouts, components, states (spec)
10. Navigation - Routes, guards, transitions, menus (spec)
11. APM/Observability - Traces, logs, metrics (OpenTelemetry) (spec)

For detailed layer specifications, see spec/layers/

Project Structure

project/
├── .dr/                                # Tool configuration and schemas
│   ├── schemas/                       # JSON Schema definitions for each layer
│   ├── examples/                      # Example elements
│   └── README.md                      # Model documentation
├── documentation-robotics/             # Main project directory
│   ├── model/                         # The canonical architecture model
│   │   ├── manifest.yaml              # Model metadata and registry
│   │   ├── 01_motivation/             # Motivation layer elements
│   │   ├── 02_business/               # Business layer elements
│   │   └── ...                       # Other layers
│   ├── specs/                         # Generated/exported specifications
│   │   ├── archimate/                 # ArchiMate XML exports
│   │   ├── openapi/                   # OpenAPI 3.0 specs
│   │   ├── schemas/                   # JSON Schema files
│   │   ├── diagrams/                  # PlantUML diagrams
│   │   └── docs/                      # Markdown documentation
│   └── projection-rules.yaml          # Cross-layer projection rules
└── dr.config.yaml                     # Configuration

Design Philosophy

• Files are the API - The model is stored as YAML/JSON files that can be directly manipulated
• CLI provides convenience - The dr tool offers validation, projection, and export functionality
• Standards-first - Leverage existing standards wherever possible (ArchiMate, OpenAPI, JSON Schema)
• AI-native design - Designed for easy use by both humans and AI agents (Claude Code, etc.)
• Git-friendly - All model files are text-based and version-controllable
• Federated approach - Each layer uses optimal standards, integrated via ArchiMate spine
• Cross-layer traceability - Track relationships from business goals through to observability

Documentation

User Guides

• Claude Code Integration Guide - Complete guide to AI-powered modeling
• Getting Started - Basic DR usage
• Validation Guide - Model validation and quality

Claude Code Integration

• Integration Guide - How to use DR with Claude Code
• Design Document - Architecture and rationale
• Workflow Examples - 10 complete workflows
• Custom Command Template
• Custom Agent Template
• Testing Guide - Integration testing procedures
• Changelog - What's new in Claude integration

CLI Documentation

• CLI Requirements
• Quick Start Guide
• Implementation Summary

Specification Documentation

• Specification Overview
• Core Concepts
• Layer Specifications
• Conformance Requirements
• Implementation Guides

Export Formats

Format	Command	Output	Tool Compatibility
ArchiMate	dr export --format archimate	.archimate XML	Archi, Enterprise Architect
OpenAPI	dr export --format openapi	.yaml specs	Swagger Editor, Postman
JSON Schema	dr export --format schema	.schema.json	Any JSON Schema validator
PlantUML	dr export --format plantuml	.puml diagrams	PlantUML, online renderers
Markdown	dr export --format markdown	.md docs	Any Markdown viewer
GraphML	dr export --format graphml	.graphml	yEd, Gephi, Cytoscape

Development

# Run tests
pytest

# Run tests with coverage
pytest --cov=documentation_robotics --cov-report=html

# Run specific test suites
pytest tests/unit/
pytest tests/integration/

# Type checking
mypy src/documentation_robotics/

# Linting
ruff check src/
black --check src/

# Format code
black src/

License

MIT License - see LICENSE file for details.

Version

Current: v0.4.0 (Feature Complete + Link Management + Claude Agents)

• Phase 1 (Core): v0.1.0
• Phase 2 (Validation): v0.2.0
• Phase 3 (Export): v0.3.0
• Phase 3 Patches: v0.3.1, v0.3.2, v0.3.3
• Phase 4 (Link Management + Claude Agents): v0.4.0