Master Agent Protocol Reference

Overview

This document provides a reference for the Master Agent Protocol (MAP) used in cpm development and operational workflows. The protocol defines structured approaches for complex task orchestration, quality assurance, and systematic problem-solving.

Protocol Purpose

The Master Agent Protocol serves to:

1. Provide systematic approach to complex development tasks
2. Ensure consistent quality and thoroughness
3. Enable structured delegation and coordination
4. Maintain clear documentation and audit trails
5. Support reproducible operational procedures

Core Principles

1. Systematic Approach

Break complex tasks into manageable phases:

• Assessment
• Planning
• Execution
• Validation
• Documentation

2. Quality Focus

Maintain high standards through:

• Clear success criteria
• Validation checkpoints
• Error detection and recovery
• Documentation requirements

3. Structured Communication

Use consistent formats for:

• Task specifications
• Progress reporting
• Error handling
• Result documentation

Protocol Phases

Phase 0: INTAKE

Purpose: Receive and comprehend the task

Activities:

1. Parse user requirements
2. Identify scope and boundaries
3. Determine complexity level
4. Select execution strategy
5. Clarify ambiguities

Example:

Task: Implement neighbor discovery feature
Scope: Network scanning, TCP connectivity, database registration
Complexity: Medium (requires networking, concurrency, database)
Strategy: Incremental development with testing

Phase 1: ASSESS

Purpose: Understand current state

Activities:

1. Analyze existing codebase
2. Identify integration points
3. Document dependencies
4. Assess risks
5. Establish baselines

Example:

Assessment Results:
- Existing: Server management infrastructure
- Integration: internal/server/neighbor.go
- Dependencies: net package, database layer
- Risks: Network scanning performance, timeout handling
- Baseline: Current server registration mechanism

Phase 2: PLAN

Purpose: Design execution strategy

Activities:

1. Break down into tasks
2. Identify dependencies
3. Determine parallelization
4. Establish milestones
5. Define success criteria

Example:

Plan:
1. Implement network scanning (net.Dial)
2. Add concurrent connection testing
3. Create neighbor registration
4. Build discovery command
5. Add database integration
6. Write tests
Success Criteria:
- Scan /24 network in < 30 seconds
- Detect all reachable cpm servers
- 95%+ reliability

Phase 3: EXECUTE

Purpose: Perform the implementation

Activities:

1. Implement planned tasks
2. Monitor progress
3. Handle errors
4. Adjust as needed
5. Document changes

Pattern:

For each task:
  1. Implement core functionality
  2. Add error handling
  3. Write tests
  4. Document behavior
  5. Verify integration

Phase 4: VALIDATE

Purpose: Verify quality and completeness

Activities:

1. Run all tests
2. Check against requirements
3. Verify edge cases
4. Performance validation
5. Security review

Validation Checklist:

• All tests pass
• Requirements met
• Error handling complete
• Performance acceptable
• Security reviewed
• Documentation updated

Phase 5: REMEDIATE

Purpose: Fix identified issues

Activities:

1. Prioritize issues
2. Implement fixes
3. Re-validate
4. Iterate as needed
5. Document resolutions

Issue Priority:

1. Critical: Security, data loss
2. High: Core functionality broken
3. Medium: Performance, usability
4. Low: Minor improvements

Phase 6: DELIVER

Purpose: Finalize and present

Activities:

1. Final validation
2. Documentation completion
3. Result compilation
4. User communication
5. Artifact archival

Deliverables:

• Working code
• Tests
• Documentation
• Examples
• Migration notes (if applicable)

Phase 7: REFLECT

Purpose: Capture learnings

Activities:

1. What worked well
2. What could improve
3. Protocol updates
4. Knowledge capture
5. Best practices documentation

Quality Framework

Success Criteria

Define measurable criteria for each task:

accuracy:
  definition: "Correctness of implementation"
  threshold: 0.90
  measurement: "Test pass rate"

completeness:
  definition: "All requirements addressed"
  threshold: 0.85
  measurement: "Requirements coverage"

rigor:
  definition: "Thoroughness of implementation"
  threshold: 0.95
  measurement: "Edge cases handled, docs complete"

performance:
  definition: "Efficiency of solution"
  threshold: acceptable_range
  measurement: "Benchmarks, profiling"

Validation Gates

Pre-Implementation Gate:

• Requirements clear and documented
• Scope defined and approved
• Success criteria established
• Dependencies identified

Mid-Implementation Gate:

• Core functionality working
• Basic tests passing
• Integration validated
• No blocking issues

Pre-Delivery Gate:

• All tests passing
• Documentation complete
• Performance acceptable
• Security reviewed
• User acceptance

Error Handling Protocol

Error Classification

Recovery Strategy

1. Identify error type and severity
2. Document error context
3. Attempt automatic recovery (if safe)
4. If recovery fails:
   a. Escalate to user
   b. Provide options
   c. Document decision
5. Update procedures to prevent recurrence

Escalation Triggers

Escalate to user when:

• Ambiguous requirements
• Multiple valid approaches
• Resource constraints
• Security concerns
• User preference needed

Documentation Standards

Code Documentation

// Function documentation
// Purpose: Brief description of what function does
// Parameters:
//   - param1: Description
//   - param2: Description
// Returns:
//   - return1: Description
//   - error: Error conditions
// Example:
//   result, err := Function(param1, param2)
//   if err != nil {
//       // handle error
//   }

Task Documentation

# Task: [Name]

## Objective
What needs to be accomplished

## Context
Background information and constraints

## Approach
How it will be implemented

## Success Criteria
Measurable outcomes

## Results
What was accomplished

## Lessons Learned
Insights for future reference

Best Practices

Planning

1. Start with clear requirements
2. Break down complex tasks
3. Identify dependencies early
4. Establish checkpoints
5. Plan for validation

Implementation

1. Incremental development
2. Test as you go
3. Document while fresh
4. Handle errors gracefully
5. Review regularly

Communication

1. Clear, concise updates
2. Proactive problem reporting
3. Document decisions
4. Share learnings
5. Maintain audit trail

Quality Assurance

1. Define success criteria upfront
2. Validate continuously
3. Test edge cases
4. Review security implications
5. Document thoroughly

Application to cpm Development

Feature Development

1. ASSESS: Review codebase for integration points
2. PLAN: Design feature architecture
3. EXECUTE: Implement incrementally
4. VALIDATE: Test thoroughly
5. DELIVER: Document and deploy

Bug Fixes

1. ASSESS: Reproduce and diagnose issue
2. PLAN: Design fix approach
3. EXECUTE: Implement fix
4. VALIDATE: Verify resolution, check regressions
5. DELIVER: Deploy and document

Performance Optimization

1. ASSESS: Measure baseline performance
2. PLAN: Identify optimization opportunities
3. EXECUTE: Implement optimizations
4. VALIDATE: Measure improvements
5. DELIVER: Document gains

Integration with cpm Workflow

Development Workflow

# Assessment
cpm config show  # Understand current state
cpm list        # See existing repositories

# Implementation
# Make changes to code

# Validation
go test ./...     # Run tests
go vet ./...      # Static analysis

# Delivery
git commit -m "feat: description"
git push

Operational Workflow

# Assessment
cpm servers status        # Check server health
cpm neighbors discover    # Find peers

# Execution
cpm push myrepo          # Sync repositories
cpm neighbors sync repo  # Distribute to neighbors

# Validation
cpm list --remote server # Verify sync

Protocol Evolution

The Master Agent Protocol is a living document that evolves based on:

• Operational experience
• Identified improvements
• New capabilities
• Team feedback
• Industry best practices

Updates are versioned and documented in the protocol changelog.

See Also

• Architecture Overview
• API Reference
• Contributing Guidelines
• Development Best Practices