How Kits Work

Under the hood of aiorg kits.

Kit Philosophy

Before diving into architecture, understand what makes aiorg kits different from typical AI tools:

Interview Mode

Kits ask questions instead of guessing.

Traditional AI: "Based on your question, I assume you mean X..." aiorg kits: "Before I help, I need to understand: Are you dealing with A or B?"

When you ask something ambiguous, kits use Claude's native question UI to clarify:

"Users are leaving my product"

Before I diagnose, I need to understand:

○ Users leave BEFORE using core features (activation problem)
○ Users leave AFTER using the product for a while (retention problem)

This determines which analysis to run.

This prevents wasted effort on the wrong problem.

Educational Approach

Every output teaches the concept behind it.

Kits don't just show data — they explain what it means and why it matters.

ACTIVATION RATE: 23%

What this means: Out of every 100 users who sign up,
only 23 experience your product's core value.

Why it matters: Users who don't activate will never
come back, pay, or refer others.

Benchmark: 30-40% for B2B SaaS

You learn product/marketing/success thinking while getting the work done.

Stage-Aware Guidance

Different advice for different stages.

A company with 50 users needs different tactics than one with 5,000:

Kits detect your stage and adjust recommendations automatically.

Adaptive Education Levels

Explanations match your experience.

On first use, kits ask your familiarity with the domain:

You can change this anytime with /settings level [beginner|intermediate|expert].

---

Kit Architecture

Every kit contains four components that work together:

.claude/
├── commands/           # Procedures Claude executes
├── knowledge/          # Domain knowledge Claude reads
├── skills/             # Reusable capabilities
└── guides/             # Guides for YOU to read

---

Commands

Commands are procedures Claude executes.

Located in .claude/commands/. Each command is a markdown file that tells Claude exactly what to do.

Example: /setup Command

# /setup

Set up the project for first use.

## Steps

1. Check prerequisites (Node.js, Docker)
2. Install dependencies with pnpm
3. Create .env.local from template
4. Start local services
5. Verify everything works

## Prerequisites Check

Run these commands to verify:
- node --version (requires 20+)
- docker --version (requires Docker Desktop)

How It Works

When you type /setup in Claude Code:

1. Claude reads .claude/commands/setup.md
2. Follows the steps exactly
3. Uses tools (Bash, Read, Write) to execute
4. Reports progress and results

Command Patterns

---

Knowledge

Knowledge is information Claude reads to understand your domain.

Located in .claude/knowledge/. Claude reads these files at session start.

Example: Kit Ecosystem Knowledge

# Kit Ecosystem

## Which Kit for Which Problem

| Problem | Kit |
|---------|-----|
| "Is this worth building?" | Idea OS |
| "How do I get users?" | Marketing OS |
| "Users sign up but leave" | Product OS |
| "How do I keep users?" | Support Team |

How It Works

1. Claude loads knowledge files on session start
2. Uses them to answer questions accurately
3. References them when relevant

Knowledge vs Commands

---

Skills

Skills are reusable capabilities Claude can activate.

Located in .claude/skills/. Each skill gives Claude specialized expertise.

Example: Supabase Expert Skill

# Supabase Expert

## Activation

Activate when user asks about:
- Database queries
- RLS policies
- Migrations
- Supabase functions

## Knowledge

### RLS Best Practices
- Always use auth.uid() for user isolation
- Enable RLS on every table
- Test policies with different users

### Common Patterns
[Database patterns, query examples, etc.]

How It Works

1. Skills activate based on context
2. Claude gains specialized knowledge
3. Better answers for that domain

Built-in Skills

---

Guides

Guides are documentation for YOU, not Claude.

Located in .claude/guides/ or recipes/. These are meant for human reading.

Example: Recipe

# Add Google OAuth

Step-by-step guide to add Google authentication.

## Prerequisites
- Google Cloud Console account
- OAuth credentials created

## Steps

### 1. Create OAuth Credentials
Go to console.cloud.google.com...

### 2. Configure Supabase
In your Supabase dashboard...

### 3. Update Environment Variables
Add to .env.local...

How It Works

1. You run /recipes to browse guides
2. Select a guide to read
3. Follow the steps yourself (or ask Claude to help)

Guides vs Commands

---

CLAUDE.md

The main context file at the project root.

What It Contains

# Project Name

## Overview
What this project does.

## Tech Stack
- Framework: Next.js 15
- Database: Supabase
- Payments: Stripe

## Project Structure
Where things are located.

## Key Commands
Available slash commands.

## Development
How to run and build.

How It Works

1. Claude reads CLAUDE.md on every session start
2. Uses it to understand your project
3. References it when answering questions

Best Practices

• Keep it accurate and up-to-date
• Focus on what Claude needs to know
• Include project-specific conventions

---

Session Flow

When you start a Claude Code session:

1. Claude reads CLAUDE.md
   └── Understands project context

2. Claude reads .claude/knowledge/*
   └── Gains domain knowledge

3. Welcome hook runs (if configured)
   └── Greets you with context

4. You type a command or question
   │
   ├── Command (/setup)
   │   └── Claude reads .claude/commands/setup.md
   │       └── Executes the procedure
   │
   └── Question ("How do RLS policies work?")
       └── Claude uses knowledge + skills
           └── Provides informed answer

---

Kit Types

Templates (Bootstrap Mode)

Create new projects from scratch.

npx @aiorg/cli@latest init saas-starter ~/my-project

Includes:

• Full codebase (src/, supabase/, etc.)
• Claude configuration (.claude/, CLAUDE.md)
• Ready to run

Examples: SaaS Dev Team, Landing Page

Companion Tools (Inject Mode)

Add to existing projects.

cd ~/my-existing-project
npx @aiorg/cli@latest add marketing-os

Includes:

• Kit data folder (.marketing-os/)
• Claude configuration (merged)
• No code changes to your project

Examples: Marketing OS, Product OS, Support Team, QA Team

---

File Categories

During upgrades, files are handled differently:

This ensures:

• You get new features
• Your data is preserved
• Your customizations are respected

---

Creating Custom Commands

Add your own commands:

1. Create the File

# .claude/commands/my-command.md

2. Write the Command

# /my-command

Description of what this command does.

## Steps

1. First, do this
2. Then, do that
3. Finally, verify

## Notes

- Important consideration
- Another note

3. Use It

> /my-command

Claude reads your file and executes it.