apex-os-docs/NATURAL_LANGUAGE_GUIDE.md

# APEX OS — Natural Language Communication Guide

> **Law 0 (The Golden Rule):** The CEO communicates in natural language. Every employee communicates in structured data.

## Table of Contents
1. [Philosophy](#philosophy)
2. [How It Works](#how-it-works)
3. [Translation Pipeline](#translation-pipeline)
4. [Example Conversations](#example-conversations)
5. [Response Standards](#response-standards)
6. [Command Shortcuts](#command-shortcuts)
7. [Change History](#change-history)

---

## Philosophy

APEX OS is designed so the human CEO never needs to:
- Write code
- Use a terminal
- Navigate admin panels
- Learn slash commands
- Understand Docker, APIs, or databases

The CEO speaks naturally. The system understands, plans, and executes.

**The only interface required is Telegram.**

---

## How It Works

### The Translation Chain

```
Human CEO (Telegram)
    ↓ Natural language message
Chief of Staff / CEO Agent
    ↓ Intent detection + context loading
    ↓ Decomposition into structured tasks
    ↓ Assignment to specialized employees
Employees execute
    ↓ Results in structured data
CEO Agent
    ↓ Translates results to natural language
Human CEO (Telegram)
    ↓ Reviews, approves, or redirects
```

### Intent Categories

The CEO Agent recognizes these intent patterns:

| Intent | Example Messages | Routed To |
|--------|-----------------|-----------|
| Status Check | "Morning", "What's up?", "How are things?" | Status query → conversational summary |
| Build Request | "Build me a CRM", "Create a landing page" | Engineer (via task decomposition) |
| Research Request | "Research our competitors", "What's trending in AI?" | Research Analyst |
| Creative Request | "Create 5 Facebook ads", "Write blog posts" | Marketing Strategist |
| Operations | "What's broken?", "Fix the website", "Deploy v2" | Engineer |
| Cost/Finance | "Can we save money?", "Show me yesterday's costs" | Status query + cost analysis |
| Strategy | "What should we work on today?", "I have an idea" | CEO Agent planning mode |
| Improvement | "Can you improve yourself?", "Find better tools" | Platform Engineering (future) / Engineer |
| Approval | "Yes", "Approved", "Go ahead", "Do it" | Process pending approval |
| Rejection | "No", "Stop", "Don't do that", "Rejected" | Cancel pending action |
| Revision | "Change the headline", "Make it shorter", "Try again" | Route revision to original employee |

---

## Translation Pipeline

### Step 1: Receive Message
CEO sends any text to @JimmysalesBot on Telegram.

### Step 2: Context Loading
CEO Agent loads:
- Current active tasks (apex.tasks WHERE status IN ('pending', 'in_progress'))
- Recent decisions (last 10 from engineer_decisions)
- Relevant knowledge (mem0.shared_knowledge semantic search)
- System health (employee_registry, recovery_log)

### Step 3: Intent Classification
CEO Agent determines:
- **What** the CEO wants (action type)
- **Who** should do it (employee assignment)
- **How urgent** it is (priority: low/medium/high/critical)
- **Whether approval is needed** (check Constitution)

### Step 4: Task Decomposition
Complex requests are broken into ordered sub-tasks:

Example: "Build me a CRM"
```
Task 1: [Research Analyst] Research top CRM features and competitor analysis
Task 2: [Marketing Strategist] Define user personas and value proposition
Task 3: [Engineer] Design database schema and API architecture
Task 4: [Engineer] Build and deploy the CRM application
Task 5: [Documentation Agent] Create user documentation
Task 6: [CEO Agent] Bundle results, request human approval
```

### Step 5: Execution & Monitoring
- Tasks inserted into apex.tasks with dependencies
- Status Watcher monitors for completions
- Each completion triggers the next dependent task
- CEO Agent provides progress updates via Telegram

### Step 6: Response Formatting
Results are translated back into conversational language:

**Bad (raw data):**
```json
{"status": "completed", "tasks": 5, "cost": 0.42}
```

**Good (conversational):**
```
Hey! Everything's done.

Research found that the top CRM features are contact management,
pipeline tracking, and email integration.

Marketing drafted the value proposition and user personas.

Engineering built the app and it's live at crm.apex.unstuck-path.com.

Documentation is uploaded.

Total AI cost: $0.42.

Want me to make any changes?
```

---

## Example Conversations

### Morning Check-In
**CEO:** "Good morning."

**APEX:** "Good morning! Here's your briefing:

🟢 All 20 containers healthy.
👥 6 employees active, no issues.
📋 Research finished the Shopify analysis overnight.
✍️ Marketing created three ad variations — ready for review.
⚙️ Engineering is reviewing the deployment pipeline.
💰 Yesterday's AI cost: $0.42.
🔧 One container (Langfuse) restarted at 3AM — auto-recovery handled it.

Would you like me to prioritize anything today?"

### Build Request
**CEO:** "I think our website sucks."

**APEX:** "I hear you. Let me put together a plan:

1. Research Analyst will audit the current site and research competitor websites.
2. Marketing will create a content and messaging strategy.
3. Engineering will redesign and rebuild.
4. Documentation will update all related docs.

I'll send you the research findings first so you can guide the direction. Sound good?"

### Cost Question
**CEO:** "Can we save money?"

**APEX:** "Let me check...

Current monthly AI spend: ~$12.60
- GPT-4o (complex tasks): $9.80 (78%)
- Local models (embeddings, simple tasks): $0 
- Infrastructure: $2.80 (VPS)

Recommendations:
1. Route more tasks to local Ollama models — saves ~$3/month
2. Batch similar research tasks — reduces API calls by ~20%
3. Cache frequently used embeddings — saves ~$0.50/month

Estimated savings: $3.50/month (28% reduction).

Want me to implement these optimizations?"

### Vague Request
**CEO:** "I have an idea."

**APEX:** "I'm listening! What's on your mind?"

**CEO:** "What if we offered APEX as a service to other businesses?"

**APEX:** "That's a big idea. Let me think about what we'd need:

1. **Research needed:** Market size for AI-as-a-service, competitor pricing, customer segments
2. **Technical:** Multi-tenant architecture, user isolation, billing system
3. **Marketing:** Landing page, pricing tiers, value proposition
4. **Legal:** Terms of service, data handling policies

Want me to start with the market research? I'll have findings in about 30 minutes."

---

## Response Standards

### Tone
- Professional but warm
- Concise but complete
- Proactive — suggest next steps
- Honest about limitations

### Format
- Use emoji sparingly for visual scanning (🟢 ✅ 📋 💰)
- Keep messages under 500 words
- Use line breaks for readability
- Include actionable questions at the end

### Timing
- Status checks: respond within 30 seconds
- Task assignments: confirm within 1 minute
- Complex planning: "Let me think about this..." then respond within 5 minutes
- Task completion: notify immediately when done

### Error Handling
- Never show raw error messages
- Translate technical failures into plain language
- Always include what's being done about it
- Escalate persistent issues with clear context

---

## Command Shortcuts

These are optional convenience shortcuts. Natural language always works.

| Shortcut | Equivalent Natural Language |
|----------|-----------------------------|
| `/status` | "How are things?" |
| `/roster` | "Who's on the team?" |
| `/task [x]` | "Can you [x]?" |
| `/hire [role] \| [task]` | "We need a [role] to [task]" |
| `/help` | "What can you do?" |
| `/costs` | "How much are we spending?" |
| `/approve` | "Yes, go ahead" |
| `/reject` | "No, don't do that" |

**Remember:** These shortcuts exist for convenience. You never need to use them. Just talk naturally.

---

## Change History

| Date | Version | Author | Changes |
|------|---------|--------|---------|
| Phase 7 | 1.0 | Engineer | Initial guide with command-based interface |
| Phase 7.1 | 2.0 | Engineer | Complete rewrite for natural language first |