Phase 8: Complete APEX OS documentation suite - Constitution, Structure, Handbook, Standards, Security, Evolution, NL Guide, Tool Registry, Roadmap, Changelog
This commit is contained in:
@@ -0,0 +1,254 @@
|
||||
# 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 |
|
||||
Reference in New Issue
Block a user