PMAT Documentation

Welcome to the PMAT (Pragmatic AI MCP Agent Toolkit) documentation.

📚 Documentation Structure

Core Documentation

• SPECIFICATION.md - Complete system specification (source of truth)
• CLAUDE_CODE_AGENT.md - Claude Code Agent Mode user guide (v2.12.0)
• DISTRIBUTION_STATUS.md - Multi-ecosystem distribution status and automation
• DOCUMENTATION_STRUCTURE.md - Documentation organization guide

Active Documentation

Architecture & Design

• architecture/ - System architecture and design decisions
  • ARCHITECTURE.md - High-level architecture overview
  • decisions/ - Architecture Decision Records (ADRs)

Development

• execution/ - Sprint planning and execution
  • roadmap.md - Development roadmap with task tracking
  • quality-gates.md - Quality enforcement standards
  • velocity.json - Sprint velocity metrics

Features

• features/ - Feature documentation
  • README.md - Feature overview
  • SCAFFOLDING-AND-MAINTENANCE.md - 🆕 v2.139.0 Project Scaffolding & Maintenance System (Complete Guide)
  • claude-agent-sdk-guide.md - Claude Agent SDK Integration Guide
  • deep-wasm-usage.md - Deep WASM Pipeline Inspection (Phases 1-2.7 Complete)
  • mutation-testing.md - Mutation Testing with ML Prediction
  • Individual feature guides for each major capability

User Guides

• guides/ - User and integration guides
  • interfaces-overview.md - CLI, MCP, HTTP interfaces
  • refactor-auto-guide.md - Automated refactoring guide
  • github-actions-quality-gate.md - CI/CD integration

Dogfooding

• dogfooding/ - Real-world validation of PMAT features
  • README.md - Dogfooding overview and command reference
  • v2.139.0-INTEGRATION-SHOWCASE.md - 🆕 Complete v2.139.0 integration showcase
  • SPRINT-19-DOGFOODING-RESULTS.md - Sprint 19 findings

Operations

• operations/ - Operational documentation
  • configuration.md - Configuration guide
  • error-handling.md - Error handling patterns
  • telemetry.md - Monitoring and telemetry

Quality & Testing

• quality/ - Quality standards and metrics
  • standards.md - Code quality standards
• testing/ - Testing documentation
  • property-based.md - Property-based testing guide
  • integration.md - Integration testing
  • performance.md - Performance testing

Specifications

• specifications/ - Feature specifications
  • roadmap-todo-quality-gate-spec.md - Roadmap management spec
  • publish-mcp-registry.md - MCP Registry publishing specification

Release Information

• release-process.md - Release workflow and procedures
• release_notes/ - Recent release notes (v2.x+)
• /CHANGELOG.md - Complete version history

Development Planning

• todo/ - Future development specifications
  • Active specifications for upcoming features
  • archive/ - Completed or deprecated specs

Reference

• cli-reference.md - CLI command reference
• bugs/ - Known issues and bug reports
  • archived/ - Resolved issues

🗄️ Archived Documentation

Historical and deprecated documentation has been moved to the archive:

• archive/ - Archived documentation
  • ARCHIVE_INDEX.md - Archive navigation guide
  • pre-v2.0/ - Pre-2.0 version documentation
  • Historical release notes, implementation docs, and deprecated features

🚀 Quick Start

1. New Users: Start with SPECIFICATION.md for system overview
2. Developers: Check execution/roadmap.md for current tasks
3. Contributors: Review quality/standards.md for quality requirements
4. Integrators: See guides/interfaces-overview.md for API details

📖 Documentation Standards

All documentation follows these principles:

• Single Source of Truth: SPECIFICATION.md is the authoritative reference
• Version Synchronized: Documentation updates required with code changes
• Quality Enforced: Pre-commit hooks ensure documentation quality
• Toyota Way Aligned: Continuous improvement (Kaizen) approach

🔗 External Resources

• Repository: github.com/paiml/paiml-mcp-agent-toolkit
• Crates.io: crates.io/crates/pmat
• MCP Registry: registry.modelcontextprotocol.io (io.github.paiml/pmat-agent)
• Homepage: paiml.com

🎯 Featured Capabilities

Deep WASM Pipeline Inspection

Complete Rust/Ruchy → WebAssembly analysis pipeline with bidirectional tracing. Full Guide →

• ✅ Phase 1-2.7 Complete: WASM binary parsing, DWARF correlation, mutation testing, unified parser
• 🔬 WASM binary parser with zero-copy analysis (wasmparser)
• 🗺️ DWARF v5 bidirectional source mapping (gimli)
• 🧬 WASM mutation testing with 3 operators (180 tests passing)
• ⚡ Unified WASM parser with 40-50% performance improvement
• 🎭 Ruchy language support for actor systems
• 📋 Phase 3 scoped: Runtime analysis, profiling, security scanning

Mutation Testing Engine

Empirical mutation testing with actual test execution and optional ML prediction. Full Guide →

• ⚡ 20× faster than cargo-mutants with smart test filtering (v2.135.0)
• ✨ Properly formatted output using prettyplease (v2.136.0)
• 🔧 CRITICAL BUG FIXED: File corruption issue resolved (Issue #64, v2.136.0)
• 🧪 Real test execution with cargo test --lib on each mutant
• 🔀 6 mutation operators (AOR, ROR, COR, UOR, CRR, SDL)
• 🌐 Multi-language support (Rust, WASM/WAT)
• 🧠 Optional ML prediction with decision tree classifier (75-95% accuracy)
• 🚀 Distributed execution with work-stealing queue
• 📈 CI/CD learning and auto-training (50 sample threshold)

---

Last Updated: 2025-10-04 | Version: 2.121.0