matrix-pattern/examples/context-passing-example.md

Matrix Pattern System MCP Server - Advanced pattern management and synchronization

# Context Passing Example for Matrix MCP Server

This example demonstrates how the Matrix MCP Server now passes context from source agents to spawned Claude instances.

## How It Works

When an AI model calls the MCP's `matrix_create_cell` tool, the `content` field now serves dual purpose:

1. **Context/Instructions**: The content is passed as context/instructions to a spawned Claude agent
2. **Task Definition**: The spawned agent uses this context to generate the actual cell content

## Example MCP Request

```json
{
  "method": "matrix_create_cell",
  "params": {
    "cellId": {
      "row": "api-design",
      "column": "specification"
    },
    "data": {
      "content": "Design a RESTful API for a user management system with the following requirements:\n- User registration and authentication\n- Profile management\n- Role-based access control\n- Password reset functionality\n- Session management\n\nProvide the API specification in OpenAPI 3.0 format with detailed endpoint descriptions, request/response schemas, and security definitions.",
      "metadata": {
        "sourceAgent": {
          "id": "architect-001",
          "type": "system-architect",
          "timestamp": "2024-01-15T10:30:00Z"
        },
        "priority": "high",
        "tags": ["api", "authentication", "user-management"]
      }
    }
  }
}
```

## What Happens Internally

### 1. MCP Receives Request
The Matrix MCP Server receives the create cell request with the context as the `content` field.

### 2. Context Passed to Agent
The server calls `executeAgentForOperation` with:
```javascript
{
  cellId: { row: "api-design", column: "specification" },
  additionalContext: "Design a RESTful API...", // The full context from content
  task: "Design a RESTful API...", // Same context as the task
  sourceAgentMetadata: { /* metadata from source */ }
}
```

### 3. Agent Builds Prompt
The agent manager builds a comprehensive prompt including:
- Agent type and specialization
- Matrix Pattern context (row/column position)
- The provided context/instructions
- Expected output format

### 4. Claude CLI Spawned
A Claude instance is spawned with the full context using:
```bash
claude -p "@/tmp/execution-prompt.md" --dangerously-skip-permissions
```

### 5. Agent Generates Content
The Claude agent processes the context and generates the actual cell content (e.g., the OpenAPI specification).

### 6. Cell Created with Generated Content
The cell is created with:
- **content**: The generated API specification (not the original context)
- **metadata.sourceContext**: The original context/prompt for traceability
- **metadata.generatedByAgent**: true
- **metadata.agent_execution**: Execution details

## Example Response

```json
{
  "content": [
    {
      "type": "text",
      "text": "Successfully created cell api-design:specification (generated by agent)"
    }
  ]
}
```

## Cell Contents After Creation

```json
{
  "id": {
    "row": "api-design",
    "column": "specification"
  },
  "content": "openapi: 3.0.0\ninfo:\n  title: User Management API\n  version: 1.0.0\n  description: RESTful API for user management with authentication and RBAC\n\npaths:\n  /api/v1/auth/register:\n    post:\n      summary: Register new user\n      ...[full OpenAPI specification generated by agent]...",
  "metadata": {
    "created": "2024-01-15T10:31:45.123Z",
    "version": 1,
    "row": "api-design",
    "column": "specification",
    "sourceContext": "Design a RESTful API for a user management system...",
    "generatedByAgent": true,
    "agent_execution": {
      "executionId": "abc-123-def",
      "status": "completed",
      "timestamp": "2024-01-15T10:31:45.000Z",
      "agentType": "api-architect"
    },
    "sourceAgent": {
      "id": "architect-001",
      "type": "system-architect",
      "timestamp": "2024-01-15T10:30:00Z"
    }
  }
}
```

## Benefits

1. **Context Preservation**: The original context is preserved in metadata for traceability
2. **Agent Specialization**: Different agent types can process the same context differently
3. **Separation of Concerns**: Source agents provide context, specialized agents generate content
4. **Audit Trail**: Full execution history and metadata is maintained

## Usage from Source Agent

When a source AI model (e.g., another Claude instance) wants to create a cell with generated content:

```javascript
// In the source agent's code
const result = await mcp.call('matrix_create_cell', {
  cellId: { row: 'design', column: 'api' },
  data: {
    content: `Based on our discussion about ${projectName}, create an API specification that includes:
      - Authentication endpoints
      - User management
      - Data validation
      - Error handling
      The API should follow RESTful principles and use JWT for authentication.`,
    metadata: {
      sourceAgent: {
        id: agentId,
        type: 'architect'
      }
    }
  }
});
```

The Matrix Pattern system will:
1. Receive this context
2. Spawn a specialized Claude agent
3. Pass the context as instructions
4. Generate the actual API specification
5. Store it in the cell
6. Return confirmation to the source agent