SHIP Protocol

Success Heuristics for Intelligent Programming

The Problem

70% of AI coding tasks fail. Current tools focus on tokens and cost, not outcomes.

• Trust in AI-generated code dropped from 43% to 33%
• 30.5% of AI suggestions contain errors
• 66% of developers frustrated by "almost right" code
• No universal metric for AI coding reliability

The Solution

SHIP Protocol provides a universal reliability score for AI-assisted development.

SHIP Score = (Confidence × 0.40) + (Focus × 0.30) + (Context × 0.20) + (Efficiency × 0.10)

One number (0-100) that tells you: Will this AI task succeed?

Quick Start

Installation

npm install @vibeatlas/ship-protocol

Basic Usage

import {
  createShipRequest,
  calculateShipScore,
  interpretShipScore,
  getShieldsIoBadgeUrl
} from '@vibeatlas/ship-protocol';

// Create a SHIP request
const request = createShipRequest({
  files: [
    {
      path: 'src/main.ts',
      content: '// your code here',
      language: 'typescript',
      size_bytes: 1024
    }
  ],
  prompt: 'Add error handling to the API endpoints'
});

// Calculate SHIP Score
const score = calculateShipScore(
  92,  // confidence
  88,  // focus
  85,  // context
  75   // efficiency
);

console.log(`SHIP Score: ${score.score} (${score.grade})`);
// Output: SHIP Score: 89 (A)

// Get interpretation
const interpretation = interpretShipScore(score.score);
console.log(interpretation.summary);
// Output: High reliability - Production ready

// Generate badge URL
const badgeUrl = getShieldsIoBadgeUrl(score.score, 'for-the-badge');

SHIP Score Explained

The Four Layers

| Layer | Weight | What It Measures | |-------|--------|------------------| | Confidence | 40% | Will the task succeed? Risk factors, historical patterns | | Focus | 30% | Is attention on the right code? Relevance, distraction filtering | | Context | 20% | Does the AI have what it needs? Coverage, completeness | | Efficiency | 10% | Resource usage - tokens, cost, CO2 |

Grade Scale

| Grade | Score | Meaning | |-------|-------|---------| | A+ | 95-100 | Exceptional - Ship with confidence | | A | 85-94 | High reliability - Production ready | | B | 70-84 | Good - Acceptable for most tasks | | C | 50-69 | Moderate - May require iteration | | D | 30-49 | Low - High risk of failure | | F | 0-29 | Unreliable - Do not proceed |

API Reference

Message Types

import type {
  IShipRequest,    // Request for assessment
  IShipResponse,   // Assessment result
  IShipFeedback,   // Outcome feedback
  IShipError,      // Error response
  IShipScore,      // Score breakdown
} from '@vibeatlas/ship-protocol';

Message Creators

import {
  createShipRequest,
  createShipResponse,
  createShipFeedback,
  createShipError,
} from '@vibeatlas/ship-protocol';

Type Guards

import {
  isShipRequest,
  isShipResponse,
  isShipFeedback,
  isShipError,
} from '@vibeatlas/ship-protocol';

Score Utilities

import {
  calculateShipScore,   // Calculate from layer scores
  getShipGrade,         // Get grade from score
  interpretShipScore,   // Human-readable interpretation
  quickShipScore,       // Quick calculation from params
} from '@vibeatlas/ship-protocol';

Badge Generation

import {
  generateBadgeUrl,
  generateBadgeMarkdown,
  getShipScoreBadgeUrl,
  getShieldsIoBadgeUrl,
} from '@vibeatlas/ship-protocol';

CLI Tool

# Install globally
npm install -g @vibeatlas/ship-cli

# Get SHIP Score
ship score

# Detailed report
ship report --format markdown

# CI check with threshold
ship check --min-score 70

GitHub Action

name: SHIP Score
on: [push, pull_request]

jobs:
  ship:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: vibeatlas/ship-action@v1
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          min-score: 70
          comment-on-pr: true

Certification

Projects maintaining high SHIP Scores can earn certification:

| Level | Requirement | Badge | |-------|-------------|-------| | Bronze | Score 70+ for 7 days | | | Silver | Score 80+ for 14 days | | | Gold | Score 90+ for 30 days | | | Platinum | Score 95+ for 60 days | |

Integration with AI Tools

SHIP Protocol works with all major AI coding tools:

• GitHub Copilot - Context optimization for inline completions
• Claude (Desktop & API) - MCP integration for context management
• Cursor - IDE-integrated reliability scoring
• ChatGPT - Context optimization for code tasks
• Any AI Tool - Universal protocol adoption

Specification

Full protocol specification: SHIP-v1.0-spec.md

Why "SHIP"?

• Success - Primary focus on task completion
• Heuristics - Data-driven predictions
• Intelligent - AI-aware optimization
• Programming - Built for developers

Also: "Ship it!" - The developer mantra for confident deployment.

Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

License

MIT License - see LICENSE for details.

Links

• Website: ship.vibeatlas.dev
• Documentation: ship.vibeatlas.dev/docs
• GitHub: github.com/vibeatlas/ship-protocol
• npm: @vibeatlas/ship-protocol

Built with by VibeAtlas