# Project Scaffolding and Maintenance System
**Version**: v2.139.0
**Status**: Production Ready
**Test Coverage**: >90%
## Table of Contents
1. [Overview](#overview)
2. [Quick Start](#quick-start)
3. [Agent Scaffolding](#agent-scaffolding)
4. [WASM Scaffolding](#wasm-scaffolding)
5. [Project Maintenance](#project-maintenance)
6. [Quality Gates](#quality-gates)
7. [Git Hooks](#git-hooks)
8. [CLI Reference](#cli-reference)
9. [MCP Integration](#mcp-integration)
10. [Testing Guide](#testing-guide)
---
## Overview
The PMAT Scaffolding and Maintenance System provides comprehensive project lifecycle support with extreme quality standards (Complexity <10, Coverage >80%, Mutation Testing).
### Key Features
- **Agent Scaffolding**: Create MCP-compliant agents in <5 minutes
- **WASM Scaffolding**: Generate WebAssembly projects with quality gates
- **Project Maintenance**: Automated roadmap and ticket management
- **Quality Gates**: Enforce code quality standards
- **Git Hooks**: Auto-validation on commit
- **Progress Indicators**: Visual feedback for long operations
- **Enhanced Errors**: Actionable suggestions for common problems
### Supported Templates
**Agent Templates**:
- `basic`: Simple MCP server
- `stateful`: Server with state management
- `hybrid`: Deterministic core + LLM wrapper
**WASM Frameworks**:
- `wasm-labs`: Full-featured WASM development
- `pure-wasm`: Minimal WASM setup
---
## Quick Start
### Install
```bash
cargo install pmat
```
### Create Your First Agent
```bash
# Create a basic agent
pmat scaffold agent --name my_agent --template basic
# Build and test
cd my_agent
cargo build
cargo test
# Run quality gates
pmat quality-gates
```
### Create Your First WASM Project
```bash
# Create WASM project
pmat scaffold wasm --name my_wasm --framework wasm-labs
# Build
cd my_wasm
make wasm-full
# Test locally
python3 -m http.server 8000
# Open http://localhost:8000
```
---
## Agent Scaffolding
### Basic Usage
```bash
# Simple agent
pmat scaffold agent --name my_agent --template basic
# With features
pmat scaffold agent --name my_agent \
--template stateful \
--features logging,metrics \
--quality extreme
# Dry run (preview only)
pmat scaffold agent --name my_agent --template basic --dry-run
# Interactive mode
pmat scaffold agent --interactive
```
### Templates
#### Basic Template
Simple MCP server for straightforward use cases.
```bash
pmat scaffold agent --name echo_agent --template basic
```
**Generated Structure**:
```
echo_agent/
├── src/
│ ├── main.rs
│ ├── server.rs
│ ├── handlers.rs
│ └── lib.rs
├── tests/
├── Cargo.toml
├── README.md
└── .pmat-gates.toml
```
**Features**:
- MCP protocol compliance
- Basic request/response handling
- Unit test scaffolding
- Quality gate configuration
#### Stateful Template
Agent with state management.
```bash
pmat scaffold agent --name data_agent --template stateful
```
**Additional Features**:
- State machine patterns
- Persistence layer
- Event sourcing support
- Transaction handling
#### Hybrid Template
Deterministic core with LLM wrapper.
```bash
pmat scaffold agent --name smart_agent \
--template hybrid \
--deterministic-core property-tests \
--probabilistic-wrapper gpt4
```
**Architecture**:
- Deterministic core (property-tested)
- LLM wrapper (probabilistic)
- Automatic fallback to deterministic
- Confidence threshold management
### Features
Add optional features to your agent:
```bash
pmat scaffold agent --name featured_agent \
--template basic \
--features logging,metrics,tracing
```
**Available Features**:
- `logging`: Structured logging with `tracing`
- `metrics`: Metrics collection with Prometheus
- `tracing`: Distributed tracing with OpenTelemetry
### Quality Levels
```bash
# Standard: Coverage ≥60%, Complexity ≤15
pmat scaffold agent --name prototype --quality standard
# Strict (default): Coverage ≥80%, Complexity ≤10
pmat scaffold agent --name production --quality strict
# Extreme: Coverage ≥85%, Mutation testing, Property tests
pmat scaffold agent --name critical --quality extreme
```
### Examples
```bash
# Simple echo agent
pmat scaffold agent --name echo_agent --template basic
# File system agent with logging
pmat scaffold agent --name fs_agent \
--template stateful \
--features logging,metrics
# Code assistant with extreme quality
pmat scaffold agent --name code_assistant \
--template hybrid \
--features logging,metrics,tracing \
--quality extreme
```
---
## WASM Scaffolding
### Basic Usage
```bash
# WasmLabs framework
pmat scaffold wasm --name my_wasm --framework wasm-labs
# PureWasm (minimal)
pmat scaffold wasm --name minimal_wasm --framework pure-wasm
# With features
pmat scaffold wasm --name full_wasm \
--framework wasm-labs \
--features logging,metrics \
--quality extreme
# Dry run
pmat scaffold wasm --name test_wasm --framework wasm-labs --dry-run
```
### Frameworks
#### WasmLabs Framework
Full-featured WASM development with quality gates.
```bash
pmat scaffold wasm --name advanced_wasm --framework wasm-labs
```
**Features**:
- Complete build toolchain
- Test infrastructure
- Quality gates (85%+ coverage)
- Makefile automation
- Local development server
**Generated Structure**:
```
advanced_wasm/
├── src/
│ └── lib.rs
├── tests/
├── Makefile
├── Cargo.toml
├── README.md
└── .pmat-gates.toml
```
#### PureWasm Framework
Minimal WASM setup for simple projects.
```bash
pmat scaffold wasm --name simple_wasm --framework pure-wasm
```
**Features**:
- Minimal dependencies
- Quick builds
- Basic testing
- Essential tooling only
### Development Workflow
```bash
# 1. Create project
pmat scaffold wasm --name my_wasm --framework wasm-labs
cd my_wasm
# 2. Build WASM
make wasm-full
# 3. Serve locally
python3 -m http.server 8000
# 4. Test
make test
# 5. Quality gates
pmat quality-gates
```
---
## Project Maintenance
### Roadmap Management
```bash
# Show roadmap health
pmat maintain roadmap
# Validate roadmap
pmat maintain roadmap --validate
# Fix checkbox status
pmat maintain roadmap --fix
# Custom paths
pmat maintain roadmap \
--roadmap-path ./docs/ROADMAP.md \
--tickets-dir ./docs/tickets
```
**Roadmap Health Report**:
```
📊 Roadmap Health Report
Sprint 20: UX Improvements
Total: 6 tickets
Complete: 6
Status: ✅ COMPLETE
Overall Health: 100%
```
### Project Health Checks
```bash
# Quick health check (build only, <10s)
pmat maintain health --quick
# Default (build check only)
pmat maintain health
# Full health check
pmat maintain health --all
# Individual checks
pmat maintain health --check-build --check-tests
# Custom timeout
pmat maintain health --check-build --check-coverage
```
**Health Report**:
```
✅ Project Health Report
✓ Build: Project builds successfully
✓ Tests: All tests passing (606 tests)
✓ Coverage: 84.2%
⚠ Complexity: 3 functions >10
⏭ SATD: Not checked
📊 Summary:
Total: 4
Passed: 3
Warned: 1
Failed: 0
⚠ Project has warnings
```
### Health Check Options
**Performance**:
- `--quick`: Build only (~10s)
- Default: Build only (~14s)
- `--all`: All checks (~10 minutes)
**Individual Checks**:
- `--check-build`: Cargo check
- `--check-tests`: Run test suite
- `--check-coverage`: Coverage with llvm-cov
- `--check-complexity`: Complexity analysis
- `--check-satd`: SATD detection
---
## Quality Gates
### Configuration
Generate default quality gate configuration:
```bash
# Initialize config
pmat quality-gate init
# Show current config
pmat quality-gate show
# Validate config
pmat quality-gate validate
```
**Generated `.pmat-gates.toml`**:
```toml
[quality]
max_complexity = 10
min_coverage = 80.0
max_satd = 0
[checks]
build = true
test = true
coverage = true
complexity = true
satd = true
[timeouts]
build = 120
test = 600
coverage = 300
```
### Running Quality Gates
```bash
# Run all gates
pmat quality-gate
# With custom config
pmat quality-gate --config .pmat-gates.toml
# JSON output
pmat quality-gate --json
# Specific project
pmat quality-gate --project-dir /path/to/project
```
### Quality Profiles
**Standard**:
- Coverage: ≥60%
- Complexity: ≤15
- Basic testing
**Strict** (Default):
- Coverage: ≥80%
- Complexity: ≤10
- Comprehensive testing
**Extreme**:
- Coverage: ≥85%
- Complexity: ≤8
- Mutation testing
- Property-based testing
---
## Git Hooks
### Installation
```bash
# Install hooks
pmat hooks install
# Install with dry-run
pmat hooks install --dry-run
# Check hook status
pmat hooks status
# Uninstall hooks
pmat hooks uninstall
```
### Available Hooks
**Pre-commit**:
- Run quality gates
- Validate roadmap
- Check code formatting
- Lint code
**Post-commit**:
- Update roadmap status
- Generate health report
- Track ticket progress
### Hook Configuration
Hooks respect `.pmat-gates.toml` configuration and can be bypassed:
```bash
# Bypass hooks temporarily
git commit --no-verify -m "WIP: Quick save"
# Normal commit with hooks
git commit -m "feat: Add new feature"
```
---
## CLI Reference
### Global Flags
```bash
# Verbose output
pmat --verbose <command>
# Quiet mode (errors only)
pmat --quiet <command>
# Color control
# Debug mode
pmat --debug <command>
```
### Scaffold Commands
```bash
# Agent scaffolding
pmat scaffold agent [OPTIONS]
--name <NAME> Agent name (required)
--template <TEMPLATE> Template type (required)
--features <FEATURES> Comma-separated features
--force Overwrite existing
--dry-run Preview only
--interactive Interactive mode
# WASM scaffolding
pmat scaffold wasm [OPTIONS]
--name <NAME> Project name (required)
--quality <LEVEL> Quality level
--output <PATH> Output directory
--force Overwrite existing
--dry-run Preview only
# List templates
pmat scaffold list-templates
```
### Maintain Commands
```bash
# Roadmap management
pmat maintain roadmap [OPTIONS]
--roadmap-path <PATH> Path to ROADMAP.md
--tickets-dir <PATH> Path to tickets directory
--validate Validate roadmap
--health Show health report
--fix Fix checkbox status
--dry-run Preview changes
# Health checks
pmat maintain health [OPTIONS]
--quick Quick mode (build only)
--all Run all checks
--check-build Check build
--check-tests Run tests
--check-coverage Check coverage
--check-complexity Check complexity
--check-satd Check SATD
### Hooks Commands
```bash
# Hook management
pmat hooks <SUBCOMMAND>
install Install git hooks
uninstall Remove git hooks
status Show hook status
--dry-run Preview only
```
### Quality Gate Commands
```bash
# Quality gates
pmat quality-gate [OPTIONS]
init Initialize config
show Show current config
validate Validate config
--config <PATH> Config file path
--report Generate report
--json JSON output
--project-dir <PATH> Project directory
```
---
## MCP Integration
The scaffolding and maintenance system is fully integrated with MCP (Model Context Protocol).
### MCP Server Mode
```bash
# Start MCP server
pmat agent mcp-server
# Use with Claude Code or other MCP clients
```
### Available MCP Tools
#### scaffold_agent
Create a new MCP agent.
**Input Schema**:
```json
{
"name": "my_agent",
"template": "basic",
"features": ["logging", "metrics"],
"quality": "strict",
"output": "./my_agent"
}
```
**Example**:
```json
{
"name": "execute_tool",
"arguments": {
"name": "scaffold_agent",
"arguments": {
"name": "my_agent",
"template": "basic"
}
}
}
```
#### scaffold_wasm
Create a new WASM project.
**Input Schema**:
```json
{
"name": "my_wasm",
"framework": "wasm-labs",
"features": ["logging"],
"quality": "extreme"
}
```
#### maintain_roadmap
Manage project roadmap.
**Input Schema**:
```json
{
"action": "health",
"roadmap_path": "./ROADMAP.md",
"tickets_dir": "./docs/tickets"
}
```
#### maintain_health
Check project health.
**Input Schema**:
```json
{
"mode": "quick",
"checks": ["build", "tests"]
}
```
### MCP Usage Example
From Claude Code or any MCP client:
```
User: "Create a new agent called data_processor with logging"
Claude: I'll create a new MCP agent for you.
[Calls scaffold_agent tool]
✓ Agent 'data_processor' created successfully
Location: ./data_processor
Next steps:
cd data_processor
cargo build
cargo test
```
---
## Testing Guide
### TDD with assert_cmd
All CLI commands are tested with `assert_cmd` for comprehensive coverage.
#### Testing Scaffold Agent
```rust
use assert_cmd::Command;
use predicates::prelude::*;
#[test]
fn test_scaffold_agent_dry_run() {
Command::cargo_bin("pmat")
.unwrap()
.args(&["scaffold", "agent",
"--name", "test_agent",
"--template", "basic",
"--dry-run"])
.assert()
.success()
.stderr(predicate::str::contains("Dry run"))
.stderr(predicate::str::contains("test_agent"));
}
#[test]
fn test_scaffold_agent_with_features() {
Command::cargo_bin("pmat")
.unwrap()
.args(&["scaffold", "agent",
"--name", "featured_agent",
"--template", "basic",
"--features", "logging,metrics"])
.assert()
.success();
}
#[test]
fn test_scaffold_agent_quality_levels() {
for quality in &["standard", "strict", "extreme"] {
Command::cargo_bin("pmat")
.unwrap()
.args(&["scaffold", "agent",
"--name", "quality_test",
"--template", "basic",
"--quality", quality,
"--dry-run"])
.assert()
.success();
}
}
```
#### Testing WASM Scaffold
```rust
#[test]
fn test_scaffold_wasm_frameworks() {
for framework in &["wasm-labs", "pure-wasm"] {
Command::cargo_bin("pmat")
.unwrap()
.args(&["scaffold", "wasm",
"--name", "test_wasm",
"--framework", framework,
"--dry-run"])
.assert()
.success();
}
}
#[test]
fn test_scaffold_wasm_invalid_framework() {
Command::cargo_bin("pmat")
.unwrap()
.args(&["scaffold", "wasm",
"--name", "test",
"--framework", "invalid",
"--dry-run"])
.assert()
.failure()
.stderr(predicate::str::contains("Unknown WASM framework"))
.stderr(predicate::str::contains("Suggestions"));
}
```
#### Testing Health Checks
```rust
#[test]
fn test_maintain_health_quick() {
Command::cargo_bin("pmat")
.unwrap()
.args(&["maintain", "health", "--quick"])
.assert()
.success()
.stderr(predicate::str::contains("Health Report"));
}
#[test]
fn test_maintain_health_individual_checks() {
Command::cargo_bin("pmat")
.unwrap()
.args(&["maintain", "health", "--check-build"])
.assert()
.success();
}
```
#### Testing Error Messages
```rust
#[test]
fn test_error_messages_are_helpful() {
Command::cargo_bin("pmat")
.unwrap()
.args(&["maintain", "roadmap"])
.current_dir(std::env::temp_dir())
.assert()
.failure()
.stderr(predicate::str::contains("ROADMAP.md"))
.stderr(predicate::str::contains("Suggestions"));
}
```
### Property-Based Testing
```rust
use proptest::prelude::*;
proptest! {
#[test]
fn test_scaffold_names_are_validated(
name in "[a-z_][a-z0-9_]{0,20}"
) {
Command::cargo_bin("pmat")
.unwrap()
.args(&["scaffold", "agent",
"--name", &name,
"--template", "basic",
"--dry-run"])
.assert()
.success();
}
}
```
### Integration Test Suite
Run all 27 integration tests:
```bash
# Run all CLI integration tests
cargo test --release cli_integration_tests::
# Run specific test
cargo test --release cli_integration_tests::test_scaffold_agent_dry_run
# Run with output
cargo test --release cli_integration_tests:: -- --nocapture
```
---
## Troubleshooting
### Common Issues
#### Directory Already Exists
**Error**:
```
ERROR: Directory already exists
Location: /path/to/my_agent
Suggestions:
- Use --force to overwrite existing directory
- Choose a different output directory with --output
- Remove the existing directory manually
```
**Solution**:
```bash
# Force overwrite
pmat scaffold agent --name my_agent --template basic --force
# Different location
pmat scaffold agent --name my_agent --template basic --output /different/path
```
#### ROADMAP.md Not Found
**Error**:
```
ERROR: Failed to read ROADMAP.md
Location: /current/dir/ROADMAP.md
Reason: File not found
Suggestions:
- Run 'pmat maintain roadmap' from project root
- Ensure you're in the correct directory
- Check if ROADMAP.md exists in your project
```
**Solution**:
```bash
# Run from project root
cd /path/to/project
pmat maintain roadmap
# Or specify path
pmat maintain roadmap --roadmap-path /path/to/ROADMAP.md
```
#### Health Check Timeout
**Error**: Health check takes too long.
**Solution**:
```bash
# Use quick mode
pmat maintain health --quick
# Or run specific checks only
pmat maintain health --check-build --check-tests
```
---
## Performance
### Benchmarks
| Agent scaffold (dry-run) | <1s | Preview generation |
| Agent scaffold (full) | ~5s | With git init |
| WASM scaffold (dry-run) | <1s | Preview generation |
| WASM scaffold (full) | ~10s | With build setup |
| Health check (quick) | <10s | Build only |
| Health check (default) | ~14s | Build check |
| Health check (all) | ~10min | Full suite |
| Roadmap health | <2s | Validation |
### Optimization Tips
1. **Use Quick Mode**: For fast feedback, use `--quick`
2. **Dry Run First**: Preview with `--dry-run` before creating
3. **Selective Checks**: Use individual flags for specific checks
4. **Quiet Mode**: Use `--quiet` for scripts and CI
---
## Best Practices
### Project Structure
Follow the generated structure:
```
my_project/
├── src/ # Source code
├── tests/ # Integration tests
├── docs/ # Documentation
│ ├── ROADMAP.md # Sprint tracking
│ └── tickets/ # Ticket details
├── Cargo.toml # Dependencies
├── README.md # Project overview
└── .pmat-gates.toml # Quality config
```
### Quality Standards
1. **Complexity**: Keep all functions <10 CC
2. **Coverage**: Maintain >80% test coverage
3. **SATD**: Zero tolerance for self-admitted technical debt
4. **Documentation**: Document all public APIs
### Git Workflow
1. **Commit Messages**: Use conventional commits
2. **Hooks**: Install git hooks for validation
3. **Roadmap**: Keep roadmap up to date
4. **Tickets**: Link all work to tickets
### Development Cycle
```bash
# 1. Create feature branch
git checkout -b feature/new-feature
# 2. Implement with TDD
cargo test --watch
# 3. Run quality gates
pmat quality-gate
# 4. Update roadmap
pmat maintain roadmap --fix
# 5. Commit with hooks
git commit -m "feat: Add new feature"
# 6. Health check
pmat maintain health --quick
```
---
## Additional Resources
- Sprint 16 Summary - Scaffolding Foundation (archived)
- Sprint 17 Summary - Maintenance Engine (archived)
- Sprint 18 Summary - Quality Gates (archived)
- [Sprint 19 Summary](../sprints/SPRINT-19-SUMMARY.md) - CLI Integration
- [Sprint 20 Summary](../sprints/SPRINT-20-SUMMARY.md) - UX Improvements
- [Dogfooding Results](../dogfooding/SPRINT-19-DOGFOODING-RESULTS.md)
- [Examples](../../examples/README.md)
---
## Support
For issues, questions, or contributions:
- GitHub Issues: https://github.com/paiml/paiml-mcp-agent-toolkit/issues
- Documentation: https://paiml.com/docs
- Examples: See `examples/` directory
---
**Version**: v2.139.0
**Last Updated**: 2025-10-06
**Status**: Production Ready