MSP Technical Specification

Technical Specification

This document provides the complete technical specification for implementing the MSP protocol. Whether you're building a minimal version or integrating with the full stack, these specifications ensure compatibility and consistency.

Session Lifecycle

State Machine Definition

stateDiagram-v2
    [*] --> Idle
    Idle --> Active: start
    Active --> Active: update/decide
    Active --> Ending: end
    Ending --> Complete: finalize
    Complete --> [*]
    
    Active --> Crashed: timeout/error
    Crashed --> Recovered: recover
    Recovered --> Active: continue

Lifecycle States

1. IDLE State

No active session. System ready to start.

{
  "state": "IDLE",
  "lastSession": "msp-2025-07-15-173042",
  "canStart": true
}

2. ACTIVE State

Session in progress. Accepting updates.

{
  "state": "ACTIVE",
  "sessionId": "msp-2025-07-16-093042",
  "startTime": "2025-07-16T09:30:42Z",
  "progress": 25,
  "updates": 7,
  "lastUpdate": "2025-07-16T10:45:23Z"
}

3. ENDING State

Session finalization in progress.

{
  "state": "ENDING",
  "sessionId": "msp-2025-07-16-093042",
  "operations": ["neo4j_sync", "obsidian_save", "linear_update"],
  "progress": "2/3"
}

4. COMPLETE State

Session successfully ended.

{
  "state": "COMPLETE",
  "sessionId": "msp-2025-07-16-093042",
  "duration": "3h 27m",
  "progressDelta": 15,
  "summary": "Implemented authentication"
}

5. CRASHED State

Abnormal termination detected.

{
  "state": "CRASHED",
  "sessionId": "msp-2025-07-16-093042",
  "crashTime": "2025-07-16T11:15:00Z",
  "lastKnownGood": "2025-07-16T11:10:00Z",
  "recoverable": true
}

State Transitions

From State	Command	To State	Conditions
IDLE	`start`	ACTIVE	No crashed sessions
ACTIVE	`update`	ACTIVE	Valid session
ACTIVE	`decide`	ACTIVE	Valid session
ACTIVE	`end`	ENDING	Updates saved
ENDING	`finalize`	COMPLETE	All syncs complete
ACTIVE	`timeout`	CRASHED	>4h without update
CRASHED	`recover`	ACTIVE	Valid recovery data

State Structure

Core State Schema

interface MSPState {
  version: "1.0";
  session: SessionState;
  project: ProjectState;
  cache: CacheState;
  config: Configuration;
}

interface SessionState {
  id: string;              // "msp-YYYY-MM-DD-HHMMSS"
  status: SessionStatus;   // IDLE | ACTIVE | ENDING | COMPLETE | CRASHED
  startTime: ISO8601;      
  endTime?: ISO8601;
  user: string;
  project: string;
  progress: ProgressState;
  updates: Update[];
  decisions: Decision[];
  blockers: Blocker[];
  artifacts: Artifact[];
}

interface ProgressState {
  start: number;           // 0-100
  current: number;         // 0-100
  target: number;          // 0-100
  milestones: Milestone[];
}

Data Models

Session Model

interface Session {
  id: string;
  user: string;
  project: string;
  startTime: Date;
  endTime?: Date;
  duration?: number;       // minutes
  progress: {
    start: number;
    end: number;
    delta: number;
  };
  epic?: string;
  summary?: string;
  tags: string[];
}

Update Model

interface Update {
  id: string;
  sessionId: string;
  timestamp: Date;
  message: string;
  progress?: number;
  type: "progress" | "note" | "blocker" | "milestone";
  metadata?: Record<string, any>;
}

Decision Model

interface Decision {
  id: string;
  sessionId: string;
  timestamp: Date;
  title: string;
  choice: string;
  rationale: string;
  alternatives: string[];
  impact: "low" | "medium" | "high";
  category: string;
  relatedDecisions: string[];
}

Blocker Model

interface Blocker {
  id: string;
  sessionId: string;
  timestamp: Date;
  description: string;
  severity: "low" | "medium" | "high" | "critical";
  status: "active" | "resolved" | "deferred";
  resolution?: string;
  resolvedAt?: Date;
  relatedTo: string[];
}

Storage Specifications

File-Based Storage (Default)

.msp/
├── state.json          # Current state
├── config.json         # User configuration
├── sessions/           # Session history
│   ├── 2025-07-15/
│   │   └── session-173042.json
│   └── 2025-07-16/
│       └── session-093042.json
└── cache/              # Temporary data

Neo4j Schema

// Node Labels
(:Session {id, user, project, startTime, endTime, status})
(:Update {id, message, timestamp, progress})
(:Decision {id, title, choice, rationale, timestamp})
(:Blocker {id, description, severity, status})
(:Entity {id, name, type, createdAt})
(:ProjectState {name, progress, phase, lastUpdate})

// Relationships
(Session)-[:HAS_UPDATE]->(Update)
(Session)-[:MADE_DECISION]->(Decision)
(Session)-[:ENCOUNTERED]->(Blocker)
(Session)-[:CREATED]->(Entity)
(Decision)-[:RESOLVED]->(Blocker)
(Session)-[:CONTINUES]->(Session)

Integration Specifications

Linear Integration

# Session to Linear mapping
mutation CreateSessionComment {
  commentCreate(input: {
    issueId: $issueId
    body: $sessionSummary
  }) {
    comment { id }
  }
}

# Progress updates
mutation UpdateIssue {
  issueUpdate(id: $issueId, input: {
    description: $updatedDescription
    estimate: $remainingPoints
  }) {
    issue { id }
  }
}

Obsidian Structure

vault/
├── Daily Notes/
│   └── 2025-07-16.md      # Session summaries
├── Decisions/
│   └── 2025-07-16-auth.md # Decision records
├── Sessions/
│   └── msp-2025-07-16-093042.md
└── Projects/
    └── MSP/
        └── Progress.md     # Progress tracking

Protocol Operations

START Operation

interface StartOperation {
  command: "start";
  params?: {
    project?: string;
    epic?: string;
    target?: string;
    continue?: string;  // Previous session ID
  };
  validates: {
    noActiveSession: boolean;
    projectExists: boolean;
    userAuthorized: boolean;
  };
  creates: {
    session: Session;
    stateFile: string;
    neo4jNode: boolean;
    obsidianNote: boolean;
  };
}

UPDATE Operation

interface UpdateOperation {
  command: "update";
  params: {
    message: string;
    progress?: number;
    type?: UpdateType;
    tags?: string[];
  };
  validates: {
    activeSession: boolean;
    progressRange: [0, 100];
    messageLength: [1, 500];
  };
  creates: {
    update: Update;
    neo4jRelation: boolean;
    linearComment?: boolean;
  };
}

DECIDE Operation

interface DecideOperation {
  command: "decide";
  params: {
    title: string;
    choice: string;
    rationale: string;
    alternatives?: string[];
    impact?: Impact;
  };
  validates: {
    activeSession: boolean;
    uniqueTitle: boolean;
  };
  creates: {
    decision: Decision;
    neo4jNode: boolean;
    obsidianNote: boolean;
    linearLabel?: boolean;
  };
}

END Operation

interface EndOperation {
  command: "end";
  params?: {
    summary?: string;
    nextSteps?: string[];
  };
  validates: {
    activeSession: boolean;
    minDuration: 60; // seconds
  };
  updates: {
    session: SessionComplete;
    progress: ProgressDelta;
    neo4j: boolean;
    obsidian: boolean;
    linear: boolean;
  };
}

Error Handling

Error Codes

enum MSPError {
  // Session Errors (1xxx)
  SESSION_ALREADY_ACTIVE = 1001,
  NO_ACTIVE_SESSION = 1002,
  SESSION_CORRUPTED = 1003,
  SESSION_TIMEOUT = 1004,
  
  // State Errors (2xxx)
  STATE_FILE_MISSING = 2001,
  STATE_PARSE_ERROR = 2002,
  STATE_VERSION_MISMATCH = 2003,
  
  // Integration Errors (3xxx)
  NEO4J_CONNECTION_FAILED = 3001,
  OBSIDIAN_VAULT_NOT_FOUND = 3002,
  LINEAR_AUTH_FAILED = 3003,
  
  // Validation Errors (4xxx)
  INVALID_PROGRESS = 4001,
  INVALID_COMMAND = 4002,
  MISSING_REQUIRED_PARAM = 4003
}

Recovery Procedures

# Automatic recovery
.\msp.ps1 recover

# Manual recovery
.\msp.ps1 recover --session "msp-2025-07-16-093042"

# Force new session
.\msp.ps1 start --force

Performance Specifications

Response Times

Command execution: < 100ms
State persistence: < 50ms
Neo4j query: < 500ms
Full context export: < 2s

Resource Limits

Max session updates: 10,000
Max concurrent sessions: 1
State file size: < 10MB
Cache retention: 7 days

Security Considerations

Data Protection

Local state files: User permissions only
Neo4j credentials: Environment variables
Linear tokens: Secure storage
No sensitive data in logs

Audit Trail

{
  "operation": "decide",
  "timestamp": "2025-07-16T10:30:00Z",
  "user": "developer",
  "sessionId": "msp-2025-07-16-093042",
  "checksum": "sha256:abcd1234..."
}

Keywords: MSP technical specification, session lifecycle, state structure, protocol operations, MSP implementation guide, context engineering specification

For AI Understanding: This technical specification defines the complete implementation requirements for MSP, including session state machine with 5 states (IDLE, ACTIVE, ENDING, COMPLETE, CRASHED), comprehensive data models for sessions/updates/decisions/blockers, storage schemas for both file and Neo4j backends, and detailed protocol operations (START, UPDATE, DECIDE, END) with validation rules.

Previous: Why MSP is Different | Next: Setup Guide →

Menu