Cabin Crew Protocol

This repository defines the core data structures and protocols for the Cabin Crew ecosystem.

🛡️ Manifesto Compliant: This protocol strictly adheres to the AI Agent Manifesto. See Compliance Doc.

🚀 What Is CabinCrew?

CabinCrew is a protocol for secure automation in both developer and production environments.
It ensures that AI agents, engines, and LLMs interact with systems safely, deterministically, and with complete auditability.

Key capabilities:

• Flight-plan & take-off model for safe intent separation
• Preflight governance using OPA and ONNX
• Human approval workflows
• MCP Gateway to control agent tool access
• LLM Gateway for safe prompt handling and model routing
• Artifact-based workflow governance
• Plan-token integrity validation
• Tamper-evident audit event system
• Air-gapped compatible

CabinCrew is vendor-neutral and language-agnostic. Engines and orchestrators can be implemented in any environment.

---

📁 Repository Structure

cabincrew-protocol/
  spec/
    draft/
      overview.md
      architecture.md
      principles.md
      engine.md
      orchestrator.md
      orchestrator-preflight.md
      orchestrator-approval.md
      artifact.md
      plan-token.md
      mcp-gateway.md
      llm-gateway.md
      audit-event.md
      glossary.md

  schema/
    draft/
      engine.schema.json
      orchestrator.schema.json
      artifact.schema.json
      plan-token.schema.json
      mcp-gateway.schema.json
      llm-gateway.schema.json
      audit-event.schema.json

  examples/
    (to be populated)

  docs/
    overview.md
    architecture.md
    principles.md

  LICENSE
  CONTRIBUTING.md
  README.md

Specifications describe behavior and semantics.
Schemas describe structure and validation.

Both are needed for interoperability.

---

📘 Specification Overview

The protocol specification is in spec/draft/:

• overview.md — High-level introduction
• architecture.md — Component model and interactions
• principles.md — Normative design rules
• engine.md — Engine execution model
• orchestrator.md — Core workflow state machine
• orchestrator-preflight.md — Governance logic
• orchestrator-approval.md — Human-in-the-loop workflow
• artifact.md — Intent and evidence representation
• plan-token.md — Chain-of-custody guarantees
• mcp-gateway.md — Governance for agent tool calls
• llm-gateway.md — Governance for LLM interactions
• audit-event.md — Structured audit format
• glossary.md — Shared terminology

---

🧩 Schemas

Schemas conform to JSON Schema Draft-07.
They define the interface shapes for:

• Engines
• Orchestrator
• Gateways
• Artifacts
• Plan-tokens
• Audit events

Schemas are versioned separately from specifications.

---

🛠️ Implementations

Reference implementations (coming soon):

• Go Engine SDK
• Go Orchestrator
• MCP Gateway Proxy
• LLM Gateway Proxy
• CLI Tools
• Test Harness

If you want to help implement these, see CONTRIBUTING.md.

---

✔️ Goals of CabinCrew

• Deterministic automation
• Human safety guarantees
• Full auditability
• Seamless AI governance
• Extensibility for any industry
• Air-gapped and offline workflows
• Multi-agent and LLM-native compatibility

CabinCrew is designed to be the secure foundation for AI-driven automation systems.

---

🚨 Source of Truth

The contents of the src/ directory are the single source of truth for all protocol definitions. All other libraries (lib/) and schemas (schemas/) are auto-generated from these TypeScript files.

DO NOT edit files in lib/ or schemas/ manually. They will be overwritten.

---

---

🚀 Quick Start

For Library Users

Install the generated library for your language:

Python:

pip install cabincrew-protocol

Go:

go get cabincrew.dev/cabincrew-protocol/lib/go

TypeScript/Node.js:

npm install @cabincrew/protocol

For Contributors

# 1. Clone and install
git clone https://github.com/cabincrew-dev/cabincrew-protocol.git
cd cabincrew-protocol
npm install

# 2. Install Python generator (for Python library generation)
python3 -m venv venv
source venv/bin/activate
pip install -r requirements-dev.txt

# 3. Make changes to TypeScript source in src/

# 4. Regenerate all libraries
npm run generate        # JSON Schema
npm run generate:go     # Go
npm run generate:python # Python
npm run generate:nodejs # TypeScript

# 5. Run smoke tests
python3 tests/smoke_test_python.py
npx ts-node tests/smoke_test_nodejs.ts
GO111MODULE=off go run tests/smoke_test_go.go

---

Development

This repository includes tools to generate language-specific libraries and documentation.

Prerequisites

• Node.js 20+
• Go 1.21+ (for verifying Go output)
• Python 3.10+ (for verifying Python output)

Generating Code

Run the following commands to update all generated artifacts:

# 1. Install dependencies
npm install

# 2. Generate everything
npm run generate        # Generates JSON Schemas and MDX Docs
npm run generate:go     # Generates Go Library
npm run generate:nodejs # Generates Node.js Library
npm run generate:python # Generates Python Library (requires datamodel-code-generator)

Python Generation Prerequisites

The Python library uses datamodel-code-generator to generate Pydantic v2 models:

# Install development dependencies
pip install -r requirements-dev.txt

Smoke Tests

Smoke tests verify that generated libraries can be imported and used correctly:

# Python smoke test
python3 tests/smoke_test_python.py

# TypeScript/Node.js smoke test
npx ts-node tests/smoke_test_nodejs.ts

# Go smoke test
GO111MODULE=off go run tests/smoke_test_go.go

Each smoke test validates:

• Imports and module loading
• Type/enum value correctness
• Object instantiation
• JSON serialization/deserialization
• Validation (Python/Pydantic only)

Smoke tests run automatically in CI on every push and pull request.

Tools

Generation scripts are located in tools/.

• tools/generate-schema.ts: Uses typescript-json-schema to create JSON Schemas and MDX.
• tools/generate-go.ts: Generates Go bindings with quicktype
• tools/generate-nodejs.ts: Generates TypeScript bindings with quicktype
• tools/generate-python.ts: Generates Python Pydantic models with datamodel-code-generator

CI/CD

The .github/workflows/ci.yml pipeline ensures that all generated code is up-to-date with src/. If you change src/ but fail to run the generators and commit the results, the build will fail.

---

Protocol Version

CabinCrew is an open, deterministic, and governable workflow protocol designed for AI-assisted automation.
It provides a safe and auditable framework for orchestrating engines, enforcing policy, routing LLM interactions, and recording chain-of-custody events.

This repository contains the formal specification, schemas, and examples for implementers.

---

📄 License

Licensed under the Apache License 2.0.
See LICENSE for more details.

---

🙌 Contributing

We welcome specification updates, schema improvements, examples, and tooling contributions.
See CONTRIBUTING.md for the complete process.

---

📬 Contact

For questions, ideas, or proposals, open an Issue or Pull Request.
Formal proposals can be submitted via a CabinCrew Design Proposal (CDP).

---

Thank you for helping build the CabinCrew Protocol —
the safe, deterministic automation layer for the AI era.