Kit Collaboration

How aiorg kits work together through shared context.

The Problem

Without collaboration, each kit works in isolation:

Each kit asks the same questions:
├── Idea OS: "What's your product?"
├── Marketing OS: "What's your product?"
├── PMF OS: "What's your product?"
└── Success OS: "What's your product?"

User explains the same context repeatedly.
No kit knows what other kits learned.

The Solution

Kits share context through a shared layer:

Kits share context through ~/.aiorg/:
├── Idea OS validates → writes to context.json
├── PMF OS reads context → knows about validation
├── Marketing OS reads context → knows about PMF score
└── All kits contribute learnings → everyone benefits

---

How It Works

Projects

A project is a named container for shared context. Multiple kit installations can belong to the same project.

Project "taskflow" might include:
├── Idea OS at ~/Desktop/idea-validation/
├── SaaS Dev Team at ~/Projects/taskflow-app/
├── Marketing OS at ~/Projects/taskflow-app/
└── PMF OS at ~/Projects/taskflow-app/

All share ~/.aiorg/projects/taskflow/context.json

The .aiorg File

A small file that links a folder to a project:

{
  "project": "taskflow"
}

Any kit in this folder knows: "I belong to project taskflow."

Shared Context (context.json)

Business context all kits can read:

{
  "business": {
    "name": "TaskFlow",
    "description": "Task management for freelancers",
    "stage": "launched"
  },
  "validation": {
    "ideaValidated": true,
    "ideaScore": 78,
    "targetCustomer": "Solo freelancers, designers",
    "valueProp": "AI-powered task prioritization"
  },
  "pmf": {
    "status": "searching",
    "score": null,
    "seanEllisScore": null
  }
}

---

Data Ownership

Each kit owns specific fields — they don't step on each other's toes.

Who Writes What

Who Reads What

Visual Flow

┌─────────────┐     writes      ┌──────────────────┐     reads      ┌──────────────┐
│  IDEA OS    │ ──────────────> │                  │ <───────────── │ MARKETING OS │
│  /pmf       │                 │   context.json   │                │ /setup       │
└─────────────┘                 │                  │                └──────────────┘
                                │  validation.*    │
┌─────────────┐     writes      │  pmf.*           │     reads      ┌──────────────┐
│  PMF OS     │ ──────────────> │  business.*      │ <───────────── │ SUCCESS OS   │
│  /pmf       │                 │  installedKits   │                │ session      │
└─────────────┘                 └──────────────────┘                └──────────────┘

---

Handoff Triggers

Kits automatically suggest the next step when appropriate:

Handoff Message Example

🎉 Milestone reached!

Your PMF score is 45% (threshold: 40%).
You've achieved Product-Market Fit!

Next step: Scale your user acquisition.

→ If you have Marketing OS: Run /scale
→ If you don't: https://aiorg.dev/kits/marketing-os

---

Practical Examples

Example 1: New Startup Journey

# Step 1: Validate idea
npx @aiorg/cli init idea-os ~/my-idea
# Project: my-startup (new)
# Runs /setup, /research, /pmf
# Writes validation.ideaScore = 78

# Step 2: Build product
npx @aiorg/cli init saas-starter ~/my-app
# Links to: my-startup
# Reads validation data
# "I see Idea OS validated your idea at 78!"

# Step 3: Find PMF
npx @aiorg/cli add pmf-os
# Links to: my-startup
# Reads validation.targetCustomer
# "Your target: Solo freelancers. Let's verify."

# Step 4: Scale
npx @aiorg/cli add marketing-os
# Links to: my-startup
# Reads pmf.status, validation.valueProp
# "PMF achieved! Here's your scale playbook."

Example 2: Checking Shared Context

npx @aiorg/cli status

TaskFlow - Project Status
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Stage: Launched
Idea Score: 78/100
PMF: Searching (not measured yet)

Installed kits:
├── idea-os at ~/Desktop/idea-validation
├── saas-starter at ~/Projects/taskflow-app
└── marketing-os at ~/Projects/taskflow-app

Recommended:
└── Add PMF OS to measure product-market fit

Example 3: Kit Greeting with Context

When you open Marketing OS:

Hey! I see you're working on TaskFlow.

Context from other kits:
├── Idea OS validated your idea (score: 78)
├── Target: Solo freelancers, designers
├── Value prop: AI-powered task prioritization

Since you're pre-PMF, I recommend:
→ /soft-launch - Careful user acquisition
→ /content - Build organic foundation

Run /setup to configure.

---

Project Learnings

Kits also share learnings:

{
  "whatWorks": [
    {
      "insight": "Freelancers prefer weekly view over daily",
      "source": "pmf-os/interview",
      "confidence": "high"
    },
    {
      "insight": "Email onboarding has 40% open rate",
      "source": "marketing-os/campaign",
      "confidence": "medium"
    }
  ],
  "whatDoesntWork": [
    {
      "insight": "Gamification didn't improve retention",
      "source": "pmf-os/experiment",
      "confidence": "high"
    }
  ],
  "magicNumber": {
    "metric": "3 tasks created in first hour",
    "retentionLift": "80% vs 15%",
    "source": "pmf-os/patterns"
  }
}

This means:

• Marketing OS knows which messaging resonated
• Success OS knows the magic number to drive toward
• All kits benefit from each other's experiments

---

Project Isolation

Projects are completely isolated from each other:

~/.aiorg/projects/
├── taskflow/           # Project 1
│   ├── context.json
│   └── learnings.json
│
└── another-startup/    # Project 2
    ├── context.json
    └── learnings.json

TaskFlow knows NOTHING about another-startup.

This is intentional:

• Different products have different contexts
• Users may work on competing ideas
• Agencies/freelancers serve multiple clients

---

Graceful Degradation

Kits work without shared context — they just ask more questions:

Shared context enhances, never blocks.

---

Tips

Link Projects Early

When adding the second kit to a project, always link to the same project name.

Check Status Often

npx @aiorg/cli status

See what context is available and what's missing.

Update Context Manually (Advanced)

# Edit shared context
nano ~/.aiorg/projects/my-startup/context.json

Useful if you validated your idea outside Idea OS.