RIPP

Build fast. Ship safely. Regenerate always.

Getting Started with RIPP

Getting Started with RIPP

This guide will help you create your first RIPP packet in under 10 minutes.

RIPP is designed to feel familiar if you’ve worked with user stories, API specs, or technical design documents. The difference is that RIPP brings all of these into one structured, validated format that preserves intent from concept to production.

New to RIPP? Start by understanding what RIPP is (and is not): RIPP Category Documentation

If you’re coming from Agile: Think of RIPP as the detailed specification that follows your user story. The user story defines “what” and “why” at a high level; RIPP adds “how,” “who can,” “what if,” and “how to verify.”

If you’re building with AI assistance: RIPP is the contract you write before prompting an AI to generate code. It ensures the generated implementation has clear boundaries, security requirements, and failure handling.

What You’ll Need

What You’ll Need

Optional (but recommended):

Quick Start: Initialize RIPP in Your Repository

The fastest way to get started is with the RIPP CLI:

# Install RIPP CLI
npm install -g ripp-cli

# Initialize RIPP in your repository
ripp init

This creates:

What you get:

Now skip to Step 4 to create your first RIPP packet.

Manual Setup (Without CLI)

If you prefer to set up manually:

  1. Create a directory for RIPP packets (e.g., ripp/ or specs/)
  2. Choose your naming convention (e.g., *.ripp.yaml)
  3. Set up your text editor with the RIPP schema (optional, see Tooling)

Two Paths to RIPP

Path 1: Spec-First (Traditional)

Write a RIPP packet BEFORE writing any code:

  1. Draft RIPP packet describing the feature
  2. Review with your team
  3. Approve the specification
  4. Implement code to match the RIPP spec
  5. Validate against acceptance tests

Best for: New features with clear requirements, high-risk features, team collaboration

Path 2: Prototype-First (AI-Assisted)

Start with a rapid prototype and extract the specification:

  1. Build a working prototype (AI-generated or rapid development)
  2. Run RIPP extraction to generate a draft specification
  3. Review the draft, fill gaps, resolve conflicts
  4. Approve the refined RIPP packet
  5. Rebuild for production using RIPP as the contract

Best for: Rapid exploration, AI-assisted development, validating ideas quickly

Learn more: See From Prototype to Production for the complete prototype extraction workflow.

Step 1: Understand the Basics

A RIPP packet is a structured specification for a single feature or API. It includes:

For higher-risk features, you can add API contracts, permissions, failure modes, audit events, NFRs, and acceptance tests.

Step 2: Choose Your RIPP Level

RIPP defines three conformance levels. Choose based on your feature’s risk and complexity:

Level When to Use Required Sections
Level 1 Simple features, internal tools, low risk Purpose, UX Flow, Data Contracts
Level 2 Production features, customer-facing APIs Level 1 + API Contracts, Permissions, Failure Modes
Level 3 High-risk features (payments, auth, PII, multi-tenant) Level 2 + Audit Events, NFRs, Acceptance Tests

Start with Level 1. You can always upgrade to Level 2 or 3 later.

Step 3: Copy the Template

Download or copy the RIPP template:

curl -O https://raw.githubusercontent.com/Dylan-Natter/ripp-protocol/main/templates/feature-packet.ripp.template.yaml

Or create a new file my-feature.ripp.yaml and paste the template.

Step 4: Fill Out the Metadata

Start by filling out the basic metadata:

ripp_version: '1.0'
packet_id: 'user-profile-update'
title: 'User Profile Update Feature'
created: '2025-12-13'
updated: '2025-12-13'
status: 'draft'
level: 1

Tips:

Step 5: Define the Purpose

Why does this feature exist? What problem does it solve?

purpose:
  problem: 'Users cannot update their profile information after registration'
  solution: 'Provide a profile editing form with server-side validation'
  value: 'Improves user experience and data accuracy'

Optional: Add out_of_scope, assumptions, and references if helpful.

Step 6: Document the UX Flow

How do users interact with this feature? List each step:

ux_flow:
  - step: 1
    actor: 'User'
    action: 'Navigates to profile settings page'
    trigger: "Clicks 'Edit Profile' button"
  - step: 2
    actor: 'User'
    action: 'Updates name and email fields'
    result: 'Form shows real-time validation'
  - step: 3
    actor: 'User'
    action: 'Submits form'
    trigger: "Clicks 'Save Changes'"
  - step: 4
    actor: 'System'
    action: 'Validates and saves changes'
    result: 'User sees success message'

Tips:

Step 7: Define Data Contracts

What data does this feature accept and return?

data_contracts:
  inputs:
    - name: 'ProfileUpdateRequest'
      fields:
        - name: 'name'
          type: 'string'
          required: true
          description: "User's display name"
        - name: 'email'
          type: 'string'
          required: true
          description: "User's email address"
          format: 'email'
  outputs:
    - name: 'ProfileUpdateResponse'
      fields:
        - name: 'user_id'
          type: 'string'
          required: true
          description: 'UUID of the user'
        - name: 'updated_at'
          type: 'string'
          required: true
          description: 'Timestamp of last update'

Tips:

Step 8: Validate Your Packet

Install the RIPP CLI:

npm install -g ripp-cli

Validate your packet:

ripp validate my-feature.ripp.yaml

If validation passes, you’ll see:

✓ my-feature.ripp.yaml is valid (Level 1)

If there are errors, the validator will tell you what’s missing or incorrect.

Step 9: Review and Approve

  1. Commit your RIPP packet to version control
  2. Share it with your team for review
  3. Make any requested changes
  4. Update the status to approved:
status: 'approved'
updated: '2025-12-13'

Step 10: Implement the Feature

Now you can write code. The RIPP packet is your spec. As you implement:

When done, update the status:

status: 'implemented'

Next Steps

Add Level 2 sections if your feature is customer-facing:

Add Level 3 sections for high-risk features:

Common Patterns

For APIs

Use Level 2. Define API contracts with endpoints, methods, and error codes.

For Multi-Tenant Features

Use Level 3. Document tenant isolation in permissions and failure modes.

For Payment Features

Use Level 3. Include audit events for compliance and NFRs for PCI requirements.

For Internal Tools

Use Level 1. Keep it simple unless there are security concerns.

Tips for Success

  1. Write the RIPP packet first, before any code
  2. Review as a team — catch issues early
  3. Keep it accurate — update the packet if implementation deviates
  4. Validate in CI — automate RIPP validation in your pipeline
  5. Version with code — commit RIPP packets alongside source code

Working with Prototypes

From Prototype to RIPP

If you’ve already built a working prototype (especially with AI assistance), you can extract a RIPP specification:

Conceptual workflow (RIPP Extractor tooling is conceptual, not yet fully implemented):

# Generate draft RIPP from prototype (future tooling)
ripp extract --code ./src --input ./README.md --output feature.ripp.yaml

# Review the generated draft
cat feature.ripp.yaml

# Fill in gaps and resolve conflicts
# (Edit the file to add missing permissions, failure modes, etc.)

# Validate the refined packet
ripp validate feature.ripp.yaml

# Approve and use as production specification

What Gets Extracted

From your prototype code:

From your inputs (README, prompts, notes):

What You Must Add

Extraction cannot infer:

These must be specified explicitly before production.

Evidence and Confidence

Generated RIPP packets include optional metadata showing:

Review these carefully and resolve before approving.

When to Use Prototype-First

✅ Good fit:

❌ Not ideal:

Learn more: From Prototype to Production: RIPP as an Intent Compiler

Need Help?

Ready to build with clarity? Create your first RIPP packet today.