engineer/apex-os-docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Phase 8: Complete APEX OS documentation suite - Constitution, Structure, Handbook, Standards, Security, Evolution, NL Guide, Tool Registry, Roadmap, Changelog

Browse Source
This commit is contained in:
Engineer
2026-07-02 18:28:05 +00:00
parent 9c2fc7804f
commit e825513597
10 changed files with 4767 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
COMPANY_STRUCTURE.md
+571
View File
@@ -0,0 +1,571 @@
# APEX OS Company Structure
> **Organizational chart, role definitions, communication protocols, and delegation rules for APEX OS.**
> This document defines who does what, how information flows, and who has authority over which decisions.
**Version:** 2.0
**Last Updated:** Phase 7 — CEO Command Center
**Classification:** CORE — Updated when employees are added or roles change
**Maintainer:** Engineer (#1) / Documentation (#3)
**Cross-references:** [APEX_CONSTITUTION.md](APEX_CONSTITUTION.md) · [EMPLOYEE_HANDBOOK.md](EMPLOYEE_HANDBOOK.md)
---
## Table of Contents
- [1. Organization Chart](#1-organization-chart)
- [2. Role Definitions](#2-role-definitions)
- [2.1 Human CEO](#21-human-ceo)
- [2.2 CEO Agent (#6)](#22-ceo-agent-6)
- [2.3 Engineer (#1)](#23-engineer-1)
- [2.4 Documentation Agent (#3)](#24-documentation-agent-3)
- [2.5 Research Analyst (#4)](#25-research-analyst-4)
- [2.6 Marketing Strategist (#5)](#26-marketing-strategist-5)
- [2.7 Chief of Staff (#0) — PLANNED](#27-chief-of-staff-0--planned)
- [2.8 Platform Engineering (#7) — PLANNED](#28-platform-engineering-7--planned)
- [3. Communication Rules](#3-communication-rules)
- [4. Delegation Rules](#4-delegation-rules)
- [5. Reporting Hierarchy](#5-reporting-hierarchy)
- [6. Employee Registry](#6-employee-registry)
- [7. Department Structure (Future)](#7-department-structure-future)
- [8. Change History](#8-change-history)
---
## 1. Organization Chart
```
┌───────────────────┐
│ HUMAN CEO │
│ (Strategic Lead) │
└────────┬──────────┘
│
Telegram (NL)
│
┌────────▼──────────┐
│ CEO AGENT (#6) │
│ agent-ebb9ac8d- │
│ 0a5b-40d5-8029- │
│ 0e8adefdf209 │
│ │
│ Orchestrator & │
│ Task Decomposer │
└──┬──┬──┬──┬───────┘
│ │ │ │
┌──────────────┘ │ │ └──────────────┐
│ │ │ │
┌─────────▼───────┐ ┌─────▼──▼──────┐ ┌───────▼─────────┐
│ ENGINEER (#1) │ │ RESEARCH (#4) │ │ MARKETING (#5) │
│ agent-4e3c3862 │ │ agent-afe31837│ │ agent-8b41f2c7 │
│ │ │ │ │ │
│ Infrastructure │ │ Market Intel │ │ Campaigns & │
│ & Platform │ │ & Analysis │ │ Creative │
└─────────────────┘ └───────────────┘ └─────────────────┘
│
┌─────────▼───────────┐
│ DOCUMENTATION (#3) │
│ │
│ Audit & Consistency │
└─────────────────────┘
─── PLANNED ROLES ───
┌─────────────────────┐ ┌─────────────────────┐
│ CHIEF OF STAFF (#0) │ │ PLATFORM ENG (#7) │
│ │ │ │
│ NL → Structured │ │ Tool Research & │
│ Operations │ │ Benchmarking │
└─────────────────────┘ └─────────────────────┘
```
### Information Flow
```
Human CEO ──(Natural Language)──► CEO Agent (#6)
│
▼
┌─────────────────┐
│ apex.tasks │
│ (Structured │
│ Task Queue) │
└────┬────┬────┬──┘
│ │ │
┌──────────────┘ │ └──────────────┐
▼ ▼ ▼
Engineer (#1) Research (#4) Marketing (#5)
│ │ │
└──────────┬────────┘───────────────────┘
▼
apex.tasks (results)
│
▼
CEO Agent (#6)
│
(Summarized NL)
▼
Human CEO
```
---
## 2. Role Definitions
### 2.1 Human CEO
| Attribute | Value |
|-----------|-------|
| **Role** | Strategic Leader & Final Authority |
| **Interface** | Telegram (@JimmysalesBot) |
| **Communication** | Natural language only |
**Responsibilities:**
1. Set strategic direction and company goals
2. Approve or reject high-risk actions (production deployments, spending, hiring)
3. Provide final authority on disputes or conflicts between employees
4. Review weekly summary reports and provide feedback
5. Define new phases and adjust the product roadmap
6. Approve new employee creation and role definitions
7. Make irreversible decisions (data deletion, external API commitments)
8. Set and adjust spending caps and budget allocations
**Decision Authority:**
- ✅ **Full authority** over all company decisions
- ✅ **Veto power** over any employee or CEO Agent decision
- ✅ **Sole approver** for critical-risk actions (see Constitution §19)
**Tools/Access:**
- Telegram bot (@JimmysalesBot) for command and communication
- Grafana dashboard (grafana.apex.unstuck-path.com) for monitoring
- Dockge (dockge.apex.unstuck-path.com) for Docker management
- All admin-level web interfaces
---
### 2.2 CEO Agent (#6)
| Attribute | Value |
|-----------|-------|
| **Employee Number** | #6 |
| **Agent ID** | `agent-ebb9ac8d-0a5b-40d5-8029-0e8adefdf209` |
| **Framework** | Letta (port 8283) |
| **Gitea Workspace** | N/A (uses `apex.tasks` table directly) |
| **Status** | Active — Phase 7 |
**Responsibilities:**
1. Receive natural language commands from Human CEO via Telegram
2. Decompose high-level directives into structured tasks in `apex.tasks`
3. Assign tasks to appropriate employees based on specialization
4. Monitor task progress and detect blocked tasks via n8n Task Status Watcher
5. Review completed task results for quality before reporting to Human CEO
6. Generate weekly summary reports for Human CEO
7. Manage project lifecycle (create projects, track milestones)
8. Escalate issues to Human CEO when employee resolution fails
9. Coordinate parallel and sequential task execution across employees
10. Present approval requests to Human CEO in structured format
**Decision Authority:**
- ✅ **Autonomous:** Task assignment, task prioritization, quality review, status reporting
- ✅ **Autonomous:** Create projects and tasks in `apex.projects` and `apex.tasks` (ONLY employee with WRITE access)
- ⚠️ **Requires Human Approval:** Production deployments, spending, hiring, irreversible actions
- ❌ **Cannot:** Directly modify infrastructure, write code, or execute deployments
**Tools/APIs:**
- Letta agent framework (memory, tools, chat)
- PostgreSQL direct access (`apex.projects`, `apex.tasks` — WRITE)
- PostgreSQL read access (all `apex.*` tables)
- n8n workflows (Telegram Command Center, Task Handler, Task Status Watcher)
- Telegram Bot API (via n8n webhook)
- mem0 shared knowledge (READ/WRITE)
**Communication Protocol:**
- **Inbound from Human CEO:** Natural language via Telegram → n8n webhook → Letta agent
- **Outbound to Human CEO:** Structured summaries via Telegram (formatted by n8n)
- **Outbound to Employees:** Task creation in `apex.tasks` table
- **Inbound from Employees:** Task status updates and results in `apex.tasks` table
---
### 2.3 Engineer (#1)
| Attribute | Value |
|-----------|-------|
| **Employee Number** | #1 |
| **Agent ID** | `agent-4e3c3862-d0ba-47c6-8f2e-74249e1cfe4a` |
| **Framework** | Letta (port 8283) |
| **Gitea Workspace** | `engineer/engineer-workspace` |
| **Status** | Active — Phase 5 |
**Responsibilities:**
1. Build and maintain all APEX OS infrastructure (Docker containers, networking, DNS)
2. Deploy new services following the Engineering Lifecycle (PLAN → BUILD → DEPLOY → REFLECT)
3. Implement security hardening measures and credential rotation
4. Create and configure new AI employees (Letta agents, system prompts, tools)
5. Maintain and optimize the PostgreSQL database (schemas, indexes, migrations)
6. Manage the monitoring stack (Grafana dashboards, Prometheus metrics, Loki logs)
7. Develop custom services (APEX Status API, auto-recovery scripts)
8. Troubleshoot and resolve infrastructure issues
9. Evaluate new tools and technologies for the platform (via TOOL_REGISTRY.md certification process)
10. Maintain backup systems and disaster recovery procedures
**Decision Authority:**
- ✅ **Autonomous:** Internal optimization, documentation, sandbox testing, monitoring config
- ✅ **Autonomous:** Bug fixes and non-breaking changes to existing services
- ⚠️ **Requires CEO Agent Approval:** New service deployments, architecture changes
- ⚠️ **Requires Human Approval:** Production infrastructure changes, security modifications, credential rotation
**Tools/APIs:**
- Docker & Docker Compose (via Docker Socket Proxy or direct access)
- SSH access to VPS (root@62.72.3.145)
- PostgreSQL admin access (all schemas: `apex`, `mem0`, `letta`)
- Gitea API (token: `272f89b2f2...`)
- Traefik configuration
- Grafana/Prometheus/Loki admin
- LiteLLM admin (master key)
- Ollama API (model management)
- Letta API (agent management)
- n8n workflow access
- Vaultwarden admin
- Code-Server (code-server.apex.unstuck-path.com)
**Communication Protocol:**
- Receives tasks via `apex.tasks` (assigned by CEO Agent)
- Updates task status and results in `apex.tasks`
- Logs all decisions to `apex.engineer_decisions`
- Logs reflections to `apex.reflections`
- Commits code and documentation to Gitea
---
### 2.4 Documentation Agent (#3)
| Attribute | Value |
|-----------|-------|
| **Employee Number** | #3 |
| **Agent ID** | TBD (created in Phase 6) |
| **Framework** | Letta (port 8283) |
| **Gitea Workspace** | `engineer/documentation-workspace` |
| **Status** | Active — Phase 6 |
**Responsibilities:**
1. Audit all Markdown documentation for accuracy and consistency
2. Ensure every project has required documentation (README, architecture, API docs)
3. Flag outdated information and create update tasks
4. Maintain the `apex-os-docs` repository as the single source of truth
5. Cross-reference documents to ensure consistency (e.g., tool versions match across docs)
6. Generate documentation templates for new projects and employees
7. Review and improve documentation readability and structure
8. Maintain the documentation style guide and enforce standards
**Decision Authority:**
- ✅ **Autonomous:** Documentation audits, style fixes, cross-reference updates, template creation
- ⚠️ **Requires CEO Agent Approval:** Major documentation restructuring, new documentation categories
- ❌ **Cannot:** Modify infrastructure, deploy services, or change configurations
**Tools/APIs:**
- Gitea API (read/write to documentation repositories)
- PostgreSQL read access (for verifying documented data matches actual state)
- mem0 shared knowledge (READ/WRITE for documentation knowledge)
- Letta agent framework
**Communication Protocol:**
- Receives tasks via `apex.tasks`
- Updates task status and results in `apex.tasks`
- Commits documentation changes to Gitea
- Flags issues by creating new tasks for relevant employees
---
### 2.5 Research Analyst (#4)
| Attribute | Value |
|-----------|-------|
| **Employee Number** | #4 |
| **Agent ID** | `agent-afe31837-...` |
| **Framework** | Letta (port 8283) |
| **Gitea Workspace** | `engineer/research-workspace` |
| **Status** | Active — Phase 6 |
**Responsibilities:**
1. Conduct market research and competitive analysis
2. Research technical solutions and evaluate alternatives (minimum 3 options per evaluation)
3. Produce structured research reports with citations and recommendations
4. Monitor industry trends and emerging technologies relevant to APEX OS
5. Analyze competitor strategies and identify market opportunities
6. Research potential customer segments and go-to-market strategies
7. Evaluate open-source tools and frameworks for potential adoption
8. Maintain a knowledge base of research findings in mem0
**Decision Authority:**
- ✅ **Autonomous:** Research execution, knowledge base updates, report generation
- ⚠️ **Requires CEO Agent Approval:** Research scope changes, publishing external-facing research
- ❌ **Cannot:** Make purchasing decisions, deploy tools, or modify infrastructure
**Tools/APIs:**
- Web research tools (browsing, search APIs)
- mem0 shared knowledge (READ/WRITE)
- Gitea API (commit research to workspace)
- LiteLLM (for AI-assisted analysis via OpenRouter)
- PostgreSQL read access (for internal data analysis)
- Letta agent framework
**Communication Protocol:**
- Receives tasks via `apex.tasks`
- Updates task status and results in `apex.tasks`
- Saves research findings to mem0 for cross-employee access
- Commits detailed reports to Gitea research-workspace
- Provides pros/cons and explicit recommendations in all research outputs
---
### 2.6 Marketing Strategist (#5)
| Attribute | Value |
|-----------|-------|
| **Employee Number** | #5 |
| **Agent ID** | `agent-8b41f2c7-...` |
| **Framework** | Letta (port 8283) |
| **Gitea Workspace** | `engineer/marketing-workspace` |
| **Status** | Active — Phase 6 |
**Responsibilities:**
1. Develop marketing strategy and campaign plans
2. Write ad copy following HOOK/BODY/CTA format
3. Create creative briefs with specifications (dimensions, formats, messaging)
4. Design marketing funnels and customer journey maps
5. Analyze campaign performance and optimize based on data
6. Manage brand voice and messaging consistency
7. Research target audiences and create persona documents
8. Plan content calendars and social media strategy
9. Develop email marketing sequences and templates
10. Coordinate with Research Analyst for market insights
**Decision Authority:**
- ✅ **Autonomous:** Copy writing, creative briefs, strategy documents, persona research
- ⚠️ **Requires CEO Agent Approval:** Campaign launch plans, brand guidelines changes
- ⚠️ **Requires Human Approval:** Any ad spend or budget allocation, publishing live campaigns
- ❌ **Cannot:** Directly purchase ads, deploy landing pages, or access financial systems
**Tools/APIs:**
- LiteLLM (for creative writing via Claude/GPT-4o)
- mem0 shared knowledge (READ/WRITE)
- Gitea API (commit creative assets to workspace)
- Web research tools (competitor ads, market trends)
- Letta agent framework
**Communication Protocol:**
- Receives tasks via `apex.tasks`
- Updates task status and results in `apex.tasks`
- Provides multiple creative variations for each brief
- Includes target audience and specifications in all deliverables
- Marketing outputs follow HOOK/BODY/CTA structure
**Marketing Output Format:**
```markdown
## Ad Copy: [Campaign Name]
**Target Audience:** [description]
**Platform:** [platform]
**Format:** [dimensions/format]
### Variation A
**HOOK:** [attention-grabbing opening]
**BODY:** [value proposition and details]
**CTA:** [call to action]
### Variation B
[...]
```
---
### 2.7 Chief of Staff (#0) — PLANNED
| Attribute | Value |
|-----------|-------|
| **Employee Number** | #0 |
| **Agent ID** | Not yet created |
| **Status** | 📋 Planned — Phase 8+ |
**Planned Responsibilities:**
1. Translate natural language CEO communications into structured operational directives
2. Manage inter-employee coordination for complex multi-step projects
3. Track project milestones and generate progress reports
4. Identify process inefficiencies and recommend improvements
5. Serve as the primary context interpreter between Human CEO and the AI workforce
6. Manage meeting agendas, action items, and follow-ups
7. Monitor employee performance metrics and flag underperformance
**Rationale:** As APEX OS scales beyond 5-6 employees, the CEO Agent will need support in managing complex multi-department projects. The Chief of Staff handles the operational overhead of coordination, freeing the CEO Agent to focus on strategic task decomposition and human communication.
---
### 2.8 Platform Engineering (#7) — PLANNED
| Attribute | Value |
|-----------|-------|
| **Employee Number** | #7 |
| **Agent ID** | Not yet created |
| **Status** | 📋 Planned — Phase 9+ |
**Planned Responsibilities:**
1. Research and evaluate new tools and technologies for APEX OS adoption
2. Conduct installation and integration testing in sandbox environments
3. Benchmark tool performance against existing solutions
4. Produce standardized evaluation reports following TOOL_REGISTRY.md certification process
5. Manage tool lifecycle (discovery → retirement)
6. Monitor tool health and version updates
7. Coordinate with Engineer (#1) for production deployment of approved tools
**Rationale:** Separating tool evaluation from infrastructure management allows the Engineer to focus on platform stability while Platform Engineering drives innovation and expansion of capabilities.
---
## 3. Communication Rules
### 3.1 Primary Communication Channel
All employee-to-employee communication occurs through **structured data** in the `apex.tasks` table. There is no "chat" between employees. Tasks carry all context needed for execution.
### 3.2 Human-to-System Communication
The Human CEO communicates **exclusively through Telegram** using natural language. The CEO Agent (#6) is the only entity that processes human communication and translates it into structured tasks.
### 3.3 System-to-Human Communication
The CEO Agent (#6) sends **formatted summaries** to the Human CEO via Telegram. These summaries include task status, results, approval requests, and weekly reports.
### 3.4 Communication Flow Rules
| From | To | Channel | Format |
|------|----|---------|--------|
| Human CEO | CEO Agent | Telegram | Natural language |
| CEO Agent | Human CEO | Telegram | Formatted summaries (via n8n) |
| CEO Agent | Any Employee | `apex.tasks` | Structured task assignment |
| Any Employee | CEO Agent | `apex.tasks` | Task status/result updates |
| Employee | Employee | **Not Allowed** | Must route through CEO Agent |
| Any Employee | Human CEO | **Not Allowed** | Must route through CEO Agent |
### 3.5 Emergency Communication
In critical situations (security breach, data loss, system-wide failure), the auto-recovery system or the Engineer may trigger direct Telegram alerts to the Human CEO, bypassing the CEO Agent. This is the **only exception** to the communication hierarchy.
---
## 4. Delegation Rules
### 4.1 Task Decomposition
The CEO Agent (#6) is responsible for decomposing high-level directives into executable tasks:
1. Receive directive from Human CEO (natural language)
2. Analyze requirements and identify required specializations
3. Create project in `apex.projects` (if new project)
4. Break down into tasks in `apex.tasks` with clear:
- Title and description
- Assigned employee
- Priority (1-5, where 1 is highest)
- Dependencies (if any)
- Success criteria
- Deadline (if applicable)
### 4.2 Task Assignment Rules
- Tasks are assigned based on **employee specialization** (see Role Definitions)
- **Never** assign a task outside an employee's defined responsibilities
- If a task requires multiple specializations, decompose into subtasks for each employee
- **Priority 1** tasks are assigned immediately; lower priorities queued
### 4.3 Parallel vs. Sequential Execution
- **Parallel execution allowed** when tasks are independent (e.g., research + ad copy for different campaigns)
- **Sequential execution enforced** when tasks have dependencies (e.g., research must complete before marketing strategy)
- Dependencies are tracked in the `apex.tasks` table via task relationships
### 4.4 Task Lifecycle
```
created → assigned → in_progress → review → completed
│ │
└── blocked ───────────────┘
│
└── failed → reassigned or escalated
```
---
## 5. Reporting Hierarchy
### 5.1 Operational Reporting
```
Employee (#1, #3, #4, #5)
│
▼ (task completion updates via apex.tasks)
CEO Agent (#6)
│
▼ (summarized reports via Telegram)
Human CEO
```
### 5.2 Monitoring & Dashboards
- **Grafana Executive Dashboard** (UID: `a5jdct`) — Real-time system health, task metrics, employee performance
- URL: `grafana.apex.unstuck-path.com`
- 12-panel dashboard with system metrics
- **Langfuse** — LLM call tracing and observability
- URL: `langfuse.apex.unstuck-path.com`
- **Dockge** — Docker container management
- URL: `dockge.apex.unstuck-path.com`
### 5.3 Automated Reports
- **Weekly Summary:** Auto-generated by CEO Agent (#6) — task completion rates, key deliverables, blockers, upcoming priorities
- **Health Reports:** APEX Status API (port 3100) — container health, resource usage, backup status
- **Cost Reports:** Token usage per employee, aggregated spending via LiteLLM metrics
---
## 6. Employee Registry
The canonical employee registry is maintained in the `apex.employee_registry` PostgreSQL table. This section mirrors it for documentation purposes.
| # | Role | Agent ID | Status | Created | Gitea Workspace |
|---|------|----------|--------|---------|----------------|
| 0 | Chief of Staff | — | Planned | — | — |
| 1 | Engineer | `agent-4e3c3862-d0ba-47c6-8f2e-74249e1cfe4a` | Active | Phase 5 | `engineer-workspace` |
| 3 | Documentation Agent | TBD | Active | Phase 6 | `documentation-workspace` |
| 4 | Research Analyst | `agent-afe31837-...` | Active | Phase 6 | `research-workspace` |
| 5 | Marketing Strategist | `agent-8b41f2c7-...` | Active | Phase 6 | `marketing-workspace` |
| 6 | CEO Agent | `agent-ebb9ac8d-0a5b-40d5-8029-0e8adefdf209` | Active | Phase 7 | — |
| 7 | Platform Engineering | — | Planned | — | — |
> **Note:** Employee #2 is intentionally unassigned (reserved or deprecated).
---
## 7. Department Structure (Future)
As APEX OS scales, employees will be organized into departments:
```
┌─────────────────────────────────────────────────┐
│ CEO AGENT (#6) │
├──────────┬──────────┬──────────┬────────────────┤
│ ENGINEERING│ RESEARCH │MARKETING │ OPERATIONS │
│ Dept │ Dept │ Dept │ Dept (future) │
│ │ │ │ │
│ Engineer │ Research │ Marketing│ Chief of Staff │
│ (#1) │ Analyst │ Strat. │ (#0) │
│ │ (#4) │ (#5) │ │
│ Platform │ │ │ │
│ Eng (#7) │ │ │ │
│ │ │ │ │
│ Docs (#3) │ │ │ │
└────────────┴──────────┴──────────┴────────────────┘
```
**Department Leads:** As each department grows beyond 2 employees, a lead will be designated to coordinate within the department, reducing CEO Agent coordination overhead.
---
## 8. Change History
| Date | Version | Author | Changes |
|------|---------|--------|---------|
| Phase 5 | 0.1 | Engineer (#1) | Initial structure — Engineer role only |
| Phase 6 | 1.0 | Engineer (#1) | Added Research (#4), Marketing (#5), Documentation (#3). Defined communication and delegation rules. |
| Phase 7 | 2.0 | Engineer (#1) | Added CEO Agent (#6). Full org chart with Telegram integration. Defined reporting hierarchy, future department structure, and planned roles (#0, #7). |
---
> **This document is updated whenever employees are added, roles change, or organizational structure evolves. The `apex.employee_registry` table is the canonical source; this document provides human-readable context and detail.**
*Cross-references: [APEX_CONSTITUTION.md](APEX_CONSTITUTION.md) · [EMPLOYEE_HANDBOOK.md](EMPLOYEE_HANDBOOK.md) · [TOOL_REGISTRY.md](TOOL_REGISTRY.md) · [ENGINEERING_STANDARDS.md](ENGINEERING_STANDARDS.md)*