Shared Context

How aiorg kits share information across your project.

The Challenge

Without shared context:

Idea OS: "What's your product?"
Marketing OS: "What's your product?"
PMF OS: "What's your product?"
Success OS: "What's your product?"

You explain the same thing repeatedly. No kit learns from others.

The Solution

Kits share context through ~/.aiorg/:

~/.aiorg/projects/my-startup/
├── context.json      # Business context
└── learnings.json    # Discovered insights

---

Architecture

~/.aiorg/                              # Global (context only)
├── config.json                        # Your preferences
└── projects/
    ├── my-startup/                    # Project 1
    │   ├── context.json               # Shared business context
    │   └── learnings.json             # Project learnings
    │
    └── another-project/               # Project 2 (isolated)
        ├── context.json
        └── learnings.json


YOUR PROJECT FOLDER:                   # Kit data stays here
~/Projects/my-app/
├── .aiorg                             # Links to "my-startup"
├── .marketing-os/                     # Marketing OS data
├── .pmf-os/                           # PMF OS data
├── src/                               # Your code
└── CLAUDE.md

---

context.json

The shared business context:

{
  "version": "1.0.0",

  "business": {
    "name": "TaskFlow",
    "description": "Task management for freelancers",
    "stage": "launched",
    "launchDate": "2025-01-01"
  },

  "validation": {
    "ideaValidated": true,
    "ideaScore": 78,
    "targetCustomer": "Solo freelancers, designers",
    "valueProp": "AI-powered task prioritization",
    "validatedAt": "2025-01-05"
  },

  "pmf": {
    "status": "searching",
    "score": null,
    "seanEllisScore": null,
    "activationRate": null
  },

  "installedKits": ["idea-os", "marketing-os", "pmf-os"],
  "lastUpdated": "2025-01-10T12:00:00Z",
  "updatedBy": "idea-os"
}

Field Reference

---

learnings.json

Insights discovered during your journey:

{
  "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"
  }
}

All kits can read these learnings and adapt their recommendations.

---

Data Ownership

Each kit owns specific fields:

Who Writes What

Who Reads What

Rules

1. Kits only write their own fields — PMF OS never writes validation.*
2. Always update timestamps — Set lastUpdated and updatedBy
3. Graceful degradation — Kits work without shared context

---

The .aiorg File

A small file that links a folder to a project:

{
  "project": "my-startup"
}

This tells any kit: "You belong to project my-startup. Read context from ~/.aiorg/projects/my-startup/."

Multiple Folders, One Project

~/Desktop/idea-validation/
├── .aiorg                    # { "project": "my-startup" }
└── .idea-os/

~/Projects/my-app/
├── .aiorg                    # { "project": "my-startup" }
├── .marketing-os/
└── .pmf-os/

Both share ~/.aiorg/projects/my-startup/context.json

---

Project Isolation

Projects are completely isolated:

~/.aiorg/projects/
├── my-startup/           # Project 1
│   ├── context.json
│   └── learnings.json
│
└── client-project/       # Project 2
    ├── context.json
    └── learnings.json

my-startup knows NOTHING about client-project.

Why isolation?

• Different products need different context
• Agencies serve multiple clients
• You might work on competing ideas

---

How Kits Use Context

On Session Start

1. Kit checks for .aiorg file
   └── Reads project name

2. Kit reads context.json
   └── Understands stage, validation, PMF status

3. Kit greets with context:
   "Hey! I see you're working on TaskFlow.
    Idea OS validated at 78.
    Target: Solo freelancers.

    You're currently searching for PMF.
    Let's run /diagnose."

On Session End

1. Kit updates context.json with new data
   └── PMF OS writes pmf.* fields

2. Kit adds learnings to learnings.json
   └── Appends to whatWorks or whatDoesntWork

3. Kit suggests handoff if appropriate
   └── "PMF achieved! Consider Marketing OS."

---

Handoff Triggers

Kits recommend next steps automatically:

Example Handoff

🎉 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

---

Checking Context

View Project Status

npx @aiorg/cli status

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

Stage: Launched
Idea Score: 78/100
PMF: Searching

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

Edit Context (Advanced)

# View context
cat ~/.aiorg/projects/my-startup/context.json

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

Useful if you validated your idea outside Idea OS.

---

Without Shared Context

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

Shared context enhances, never blocks.