npm package: @sanctiv/genesis
Description: Genesis - AI orchestration framework combining Spec-Kit (design) and execution engine. Transform concepts into production-ready code with Claude, Cursor, and GitHub Copilot integration.
Author: Mark Tiderman
Latest version: 2.0.0

# Genesis - AI Orchestration Framework

**Transform concepts into production-ready code in days, not weeks**

[![npm version](https://badge.fury.io/js/@sanctiv%2Fgenesis.svg)](https://www.npmjs.com/package/@sanctiv/genesis)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen)](https://nodejs.org)

---

## 🌟 What is Genesis?

Genesis is an **AI orchestration framework** that bridges the gap between concept and code through systematic specification (Spec-Kit) and intelligent execution (Skills).

**Built for:** Claude Code, Cursor, GitHub Copilot  
**Philosophy:** Single source of truth, Markdown-first, AI-native  
**Version:** 2.0.0

---

## 🎯 Why Genesis?

### The Problem

- AI agents reinvent the wheel with each session
- Knowledge scattered across docs, code, tribal wisdom
- Inconsistent workflows leading to unpredictable outcomes
- No systematic way to capture and share institutional knowledge

### The Solution

Genesis provides a **three-layer cognitive architecture** that transforms AI agents into a coordinated team:

```
┌─────────────────────────────────┐
│  Validators (Quality Gates)     │ ← Ensure excellence
├─────────────────────────────────┤
│  Skills (Executable Workflows)  │ ← Step-by-step procedures
├─────────────────────────────────┤
│  Instructions (Foundation)      │ ← Core principles
└─────────────────────────────────┘
```

---

## ⚡ Quick Start

### Installation

```bash
npm install @sanctiv/genesis

# Or globally
npm install -g @sanctiv/genesis
```

### Initialize Genesis

```bash
# Initialize in your project
genesis init

# Creates:
# - .genesis/ (single source of truth)
# - AGENTS.md (universal instructions)
# - CLAUDE.md (Claude Code memory)
# - Platform integration files
```

### First Steps

```bash
# View available skills
genesis list

# Start a work cycle
genesis skill work-cycle-protocol

# Apply a validator
genesis validate pb-and-j-clarity
```

---

## 🏗️ Architecture

### Single Source of Truth

**Everything lives in `.genesis/`** - platform files are generated:

```
.genesis/                    ← Single source of truth
├── config.json             ← System configuration
├── instructions/           ← Foundation principles
│   ├── vehicles-vs-values.md
│   ├── pb-and-j-principle.md
│   ├── ai-first-mindset.md
│   └── trust-but-verify.md
├── skills/                 ← Executable workflows
│   ├── work-cycle-protocol.md
│   ├── lighthouse-protocol.md
│   ├── git-workflow.md
│   └── ... (7 total)
├── validators/             ← Quality gates
│   ├── elons-5-rules.md
│   ├── pb-and-j-clarity.md
│   └── ... (4 total)
├── commands/               ← Slash commands
├── memory/                 ← Persistent context
├── plugins/                ← Extensions
└── mcp/                    ← Model Context Protocol

Generated (don't edit):
├── .claude/                ← Claude Code integration
├── .cursor/                ← Cursor integration
└── .github/                ← GitHub Copilot integration
```

---

## 📚 Core Principles

### 1. Vehicles < Values

**Vehicle:** The method (adaptable)  
**Value:** The goal (unchanging)  
**Rule:** Adapt methods, preserve goals

### 2. PB&J Principle

Every step executable by someone with ZERO prior knowledge.

### 3. Work Cycle Separation

Each work cycle = dedicated branch + commits + outcome.  
**Never mix** multiple work cycles!

### 4. AI-First Mindset

AI agents are colleagues, not tools. Design for autonomous execution.

---

## 🔄 Core Workflows

### Work Cycle Protocol (5-120 min)

1. Review existing issues
2. Create GitHub issue
3. Create feature branch
4. Execute with commits
5. Validate testing
6. Create PR
7. Capture learnings
8. Identify next priority

### Lighthouse Protocol (20-45 min)

1. Product Owner Analysis
2. 3 Technical Pathways
3. Decision Rationale
4. Creative Naming
5. User Story Formation
6. Documentation

---

## ✅ Quality Gates

### Elon's 5 Rules (IN ORDER)

1. Make requirements less dumb
2. Delete the part/process
3. Simplify & optimize
4. Accelerate cycle time
5. Automate

### Validators

- **PB&J Clarity** - Zero-knowledge accessibility
- **Industry Best Practice** - Standards alignment
- **Commander Intent** - Goal alignment

---

## 🎨 Spec-Kit Integration

Design phase commands:

```bash
genesis design covenant    # Define principles
genesis design spec        # Create specification
genesis design clarify     # Resolve ambiguities
genesis design plan        # Design architecture
genesis design tasks       # Generate tasks
genesis build              # Execute
```

---

## 🔌 Platform Integration

Works with:
- **Claude Code** - Via CLAUDE.md and .claude/
- **Cursor** - Via .cursor/rules and commands
- **GitHub Copilot** - Via .github/copilot-instructions.md

All generated from .genesis/ - edit once, use everywhere!

---

## 🛠️ Advanced Features

- **MCP Support** - Model Context Protocol integration
- **Custom Commands** - Slash command system
- **Plugin System** - Extend with custom functionality
- **Memory System** - Persistent context across sessions

---

## 📦 Package Information

**Package:** @sanctiv/genesis  
**Version:** 2.0.0  
**License:** MIT  
**Node.js:** >=18.0.0

**Breaking Changes from v1.x:**
- Complete rename: ai-sop → @sanctiv/genesis
- JSON → Markdown format
- New directory structure (.genesis/)
- Updated terminology

---

## 📖 Documentation

- **AGENTS.md** - Universal agent instructions
- **CLAUDE.md** - Claude Code memory
- **.genesis/README.md** - Architecture details
- **.genesis/skills/** - All workflows
- **.genesis/validators/** - Quality gates

---

## 🤝 Contributing

```bash
genesis init
cat AGENTS.md
genesis skill work-cycle-protocol
genesis validate pb-and-j-clarity
gh pr create
```

See CONTRIBUTING.md for complete guidelines.

---

## 🔗 Links

- GitHub: https://github.com/marktiderman/ai-sop
- NPM: https://www.npmjs.com/package/@sanctiv/genesis
- Issues: https://github.com/marktiderman/ai-sop/issues

---

## 📜 License

MIT License

---

<div align="center">

### 🎭 Made with Genesis

**"Where concepts transform into code, and AI agents become an orchestra."**

**⭐ Star • 📦 Install • 🤝 Contribute**

**Version 2.0.0** | **@sanctiv/genesis** | **October 2025**

</div>