# SHIP Protocol

**Success Heuristics for Intelligent Programming**

[![SHIP Score](https://img.shields.io/badge/SHIP_Score-95_(A+)-brightgreen?style=for-the-badge)](https://ship.vibeatlas.dev)
[![npm version](https://img.shields.io/npm/v/@vibeatlas/ship-protocol?style=for-the-badge)](https://www.npmjs.com/package/@vibeatlas/ship-protocol)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue?style=for-the-badge)](LICENSE)

---

## 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

```bash
npm install @vibeatlas/ship-protocol
```

### Basic Usage

```typescript
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

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

### Message Creators

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

### Type Guards

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

### Score Utilities

```typescript
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

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

---

## CLI Tool

```bash
# 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

```yaml
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 | ![Bronze](https://img.shields.io/badge/SHIP-Bronze-cd7f32) |
| Silver | Score 80+ for 14 days | ![Silver](https://img.shields.io/badge/SHIP-Silver-c0c0c0) |
| Gold | Score 90+ for 30 days | ![Gold](https://img.shields.io/badge/SHIP-Gold-ffd700) |
| Platinum | Score 95+ for 60 days | ![Platinum](https://img.shields.io/badge/SHIP-Platinum-e5e4e2) |

---

## 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](./spec/SHIP-v1.0-spec.md)

---

## Why "SHIP"?

- **S**uccess - Primary focus on task completion
- **H**euristics - Data-driven predictions
- **I**ntelligent - AI-aware optimization
- **P**rogramming - Built for developers

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

---

## Contributing

We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

---

## License

MIT License - see [LICENSE](LICENSE) for details.

---

## Links

- **Website**: [ship.vibeatlas.dev](https://ship.vibeatlas.dev)
- **Documentation**: [ship.vibeatlas.dev/docs](https://ship.vibeatlas.dev/docs)
- **GitHub**: [github.com/vibeatlas/ship-protocol](https://github.com/vibeatlas/ship-protocol)
- **npm**: [@vibeatlas/ship-protocol](https://www.npmjs.com/package/@vibeatlas/ship-protocol)

---

**Built with by [VibeAtlas](https://vibeatlas.dev)**