npm package: @skene/skene
Description: Skene Growth Stack - One package, IDE-integrated, intelligence-enhanced. Install once, configure in your IDE, subscription adds intelligence value.
Author: Skene Technologies
Latest version: 1.0.0

# skene

The complete Skene stack - All 8 layers for deterministic AI orchestration and PLG.

## What is Skene?

Skene is an open-source framework for building **deterministic AI-powered applications** with **product-led growth** features built-in. Unlike traditional AI frameworks that produce unpredictable results, Skene guarantees:

✅ **Deterministic execution** - Same input = same output, every time
✅ **Full auditability** - Immutable audit trail with hash-chain verification
✅ **Human-in-the-loop** - Pause flows for human approval
✅ **Multi-tenant ready** - Built-in tenant isolation
✅ **PLG-native** - Billing, gamification, lifecycle tracking out-of-the-box
✅ **MCP-compatible** - Standard Model Context Protocol integration

## Installation

Install the complete stack:

```bash
npm install skene
```

Or install individual layers:

```bash
npm install @skene/foundation  # Layers 1-2: Core
npm install @skene/tools        # Layers 3-4: AI & Skills
npm install @skene/orchestration # Layer 5: Execution
npm install @skene/product      # Layers 6-7: PLG Features
npm install @skene/ui           # Layer 8: Smart Components
```

For codebase scanning (Layer 0):

```bash
npm install -g skene-growth
skene scan  # Generate growth manifest
```

## Quick Start

```typescript
import {
  StateMachine,
  FlowRunner,
  KeywordClassifier,
  BillingGateway,
  SmartEditor
} from 'skene';

// 1. Set up state machine (deterministic flows)
const machine = new StateMachine({
  initialState: 'draft',
  states: {
    draft: { allowedTools: ['edit', 'save'] },
    review: { allowedTools: ['approve', 'reject'] },
    published: { allowedTools: ['view'] }
  },
  transitions: [
    { from: 'draft', to: 'review', event: 'submit' },
    { from: 'review', to: 'published', event: 'approve' },
    { from: 'review', to: 'draft', event: 'reject' }
  ]
});

// 2. Add AI intent classification
const classifier = new KeywordClassifier({
  intents: [
    { id: 'edit_document', patterns: ['edit', 'modify', 'change'] },
    { id: 'publish', patterns: ['publish', 'share', 'release'] }
  ]
});

// 3. Execute flows with human-in-the-loop
const runner = new FlowRunner({
  stateMachine: machine,
  breakpoints: [
    {
      condition: (ctx) => ctx.needsApproval,
      handler: async (ctx) => await waitForApproval(ctx)
    }
  ]
});

await runner.execute({
  steps: [
    { action: 'edit_document', params: { content: '...' } },
    { action: 'submit_for_review' },
    // Flow pauses here for human approval
    { action: 'publish' }
  ]
});

// 4. Add PLG features
const billing = new BillingGateway({
  provider: 'stripe',
  apiKey: process.env.STRIPE_API_KEY
});

await billing.createSubscription({
  customerId: 'cus_123',
  planId: 'plan_pro'
});

// 5. Add smart UI
const editor = new SmartEditor({
  element: document.querySelector('#editor'),
  mode: 'document',
  aiAssistance: {
    enabled: true,
    provider: 'anthropic',
    model: 'claude-3-opus'
  }
});
```

## Architecture: 8 Layers

### Layer 0: Context Architecture
**Package:** `skene-growth` (separate CLI)

Scan your codebase to generate a growth manifest:

```bash
skene scan
# Outputs: growth-manifest.json
```

Identifies:
- Tech stack and patterns
- Growth opportunities (GTM gaps)
- Integration suggestions

### Layers 1-2: Foundation
**Package:** `@skene/foundation`

The bedrock of deterministic AI:

- **State Machine** - Deterministic state transitions
- **Audit Trail** - Immutable event log with hash-chain
- **Config Loader** - Type-safe configuration
- **Tenant Context** - Multi-tenant isolation

### Layers 3-4: Intent & Skills
**Package:** `@skene/tools`

AI-powered understanding and action:

- **Intent Classifier** - Classify user requests
- **Objective Router** - Route to appropriate handlers
- **Skill Registry** - Register and discover capabilities
- **Tool Permissions** - State-based access control

### Layer 5: Orchestration
**Package:** `@skene/orchestration`

Execute complex flows:

- **Flow Runner** - Multi-step flow execution
- **Breakpoint** - Human-in-the-loop pausing
- **Sidecar Daemon** - Background processing
- **MCP Client/Server** - Model Context Protocol integration

### Layers 6-7: Product Infrastructure
**Package:** `@skene/product`

Product-led growth features:

- **Billing Gateway** - Stripe, Paddle integration
- **Gamification** - XP, levels, achievements
- **Lifecycle Tracker** - User stage monitoring
- **Trigger Engine** - Behavioral automation

### Layer 8: AI & UX
**Package:** `@skene/ui`

Smart user interfaces:

- **Smart Editor** - Tiptap + AI assistance
- **Adaptive Renderer** - Platform-agnostic UI
- **RAG Pipeline** - Retrieval-Augmented Generation
- **Audit Visualizer** - Timeline with hash verification

## Use Cases

### AI Agents
```typescript
// Deterministic AI agent with full audit trail
const agent = new FlowRunner({ stateMachine });
await agent.execute(taskFlow);
```

### SaaS Products
```typescript
// Complete PLG infrastructure
import { BillingGateway, Gamification, LifecycleTracker } from 'skene';
```

### Workflow Automation
```typescript
// Multi-step workflows with HITL approval
const workflow = new FlowRunner({
  breakpoints: [approvalBreakpoint]
});
```

### Multi-Tenant Apps
```typescript
// Built-in tenant isolation
const context = new TenantContext({ tenantId: 'acme-corp' });
```

## Why Skene?

**Compared to LangChain/LlamaIndex:**
- ✅ Deterministic (no randomness in execution)
- ✅ Auditable (immutable event history)
- ✅ Multi-tenant (built-in isolation)
- ✅ HITL (human approval workflows)

**Compared to Temporal/Inngest:**
- ✅ AI-native (intent classification, RAG, smart UI)
- ✅ PLG-native (billing, gamification, lifecycle)
- ✅ Lighter weight (no separate infrastructure)

**Compared to building from scratch:**
- ✅ 10x faster (pre-built components)
- ✅ Battle-tested (production-ready patterns)
- ✅ Open source (MIT license, no lock-in)

## Examples

See [examples directory](./examples):
- `todo-app-with-skene` - Simple state machine + audit trail
- `saas-billing-starter` - Complete SaaS template
- `ai-email-assistant` - Email automation with HITL
- `workflow-orchestrator` - Multi-step business processes

## Documentation

- **Getting Started:** [docs.skene.dev/getting-started](https://docs.skene.dev/getting-started)
- **Architecture Guide:** [docs.skene.dev/architecture](https://docs.skene.dev/architecture)
- **API Reference:** [docs.skene.dev/api](https://docs.skene.dev/api)
- **Examples:** [github.com/SkeneTechnologies/skene-flow/examples](https://github.com/SkeneTechnologies/skene-flow/tree/main/examples)

## Community

- **GitHub:** [github.com/SkeneTechnologies/skene-flow](https://github.com/SkeneTechnologies/skene-flow)
- **Discord:** [skene.dev/discord](https://skene.dev/discord)
- **Twitter:** [@skenedev](https://twitter.com/skenedev)
- **Issues:** [github.com/SkeneTechnologies/skene-flow/issues](https://github.com/SkeneTechnologies/skene-flow/issues)

## Contributing

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

## License

MIT © Skene Technologies

Open source, commercial-friendly, no restrictions.

## Roadmap

- ✅ v1.0: Core 8-layer architecture (current)
- 🔜 v1.1: VS Code extension, more integrations
- 🔜 v1.2: Real-time collaboration, WebSocket support
- 🔜 v2.0: Distributed orchestration, multi-region

---

**Built with ❤️ by [Skene Technologies](https://skene.dev)**