CEOinaBox

AI Department Hierarchy for OpenCode — by millsydotdev

CEOinaBox gives OpenCode a CEO agent that orchestrates work across 16+ specialist department agents. You talk to the CEO. The CEO handles everything else.

Installation

npm install @millsydotdev/ceoinabox

Then add to your opencode.json:

{
  "plugin": ["@millsydotdev/ceoinabox"]
}

OpenCode discovers and loads the plugin automatically on next startup.

Requirements

• OpenCode 1.17+ (required)
• Node.js 18+ (required)

Quick Start

1. Run opencode in your project directory
2. The CEO agent activates automatically — a sidebar panel shows project info and plugin status
3. Tell the CEO what you need — in plain language: "analyze this project", "build an API", "audit security", "fix the lint errors"
4. The CEO plans, delegates to department agents, reviews results, and reports back
5. Only use /ceo- commands for things the CEO can't do: answer agent questions, check plugin health, manage MCP servers

How It Works

You → CEO (your only interface)
       │
       ├── delegates to 16+ specialist agents
       │     ├── frontend-dev, backend-dev, devops, qa-engineer
       │     ├── security-engineer, designer, technical-writer
       │     ├── product-manager, project-manager, tech-lead
       │     └── data-ml-engineer, mobile-dev, sre, and more
       │
       ├── tracks progress with todowrite
       ├── runs 49 slash commands
       └── reports results back to you

You never talk to anyone but the CEO. All delegation, coordination, and reporting happens behind the scenes.

What You Get

• 1 CEO agent — your sole interface
• 16+ department agents — invisible to you, orchestrated by the CEO
• 10 explicit commands — /ceo-help, /ceo-mcp, /ceo-sync, /ceo-doctor, and more. Everything else: just tell the CEO what you need.
• 35 built-in engineering rules — loaded automatically as OpenCode references
• Skill system — discover, download, and optimize reusable skill packs
• MCP server management — search, install, configure, and enable MCP servers
• Startup intelligence panel — project info sidebar in the OpenCode TUI
• Self-contained — plugin state stays inside the plugin, your project root stays clean

Commands (10)

CEOinaBox keeps its command surface minimal. Most engineering tasks — analyze, build, test, audit, refactor, fix, format, generate — can be done by simply telling the CEO what you need.

Commands that require explicit invocation:

| Command | Purpose | |---------|---------| | /ceo-help | Quick reference | | /ceo-answer | Answer a question from a department agent | | /ceo-delegate | Explicitly delegate a task to an agent | | /ceo-doctor | Diagnose plugin health | | /ceo-heal | Heal failed agent tasks | | /ceo-init | Initialize CEOinaBox in a project | | /ceo-knowledge | Query company knowledge | | /ceo-mcp | Manage MCP servers | | /ceo-sync | Sync agents, commands, and rules | | /ceoinaBox | Set intensity level |

Everything else: just ask the CEO.

Built-in Rules (35)

CEOinaBox ships with 35 engineering rules loaded as OpenCode references:

• Code quality, style, and hygiene
• API design and architecture boundaries
• Testing patterns and standards
• Security, secrets management, and compliance
• Prompt injection defense and AI guardrails
• Concurrent work and delegation patterns
• Documentation and naming conventions
• Git, PR, and commit conventions
• Deployment, logging, and i18n standards
• State management and error handling

Project Structure

@millsydotdev/ceoinabox/
├── index.js                       # Plugin entry point
├── scripts/
│   ├── index.js                   # Plugin setup, server, tui hooks
│   ├── infra/                     # Shared infrastructure (7 modules)
│   │   ├── logger.js              #   Unified logging with levels
│   │   ├── storage.js             #   Atomic file I/O, plugin-relative paths
│   │   ├── config.js              #   Central configuration with validation
│   │   ├── backup.js              #   Managed backups with retention policy
│   │   ├── errors.js              #   Error handling with safe() wrapper
│   │   ├── migration.js           #   One-time state migration
│   │   └── utils.js               #   Shared utilities (which, walkDir, etc.)
│   ├── tui-plugin.js              # TUI slot panels (sidebar)
│   ├── sync.js                    # Template sync to workspace
│   ├── project-detect.js          # Stack detection
│   ├── memory.js                  # Project memory
│   ├── agent-memory.js            # Per-agent persistent memory
│   ├── question-funnel.js         # Agent→CEO→User question routing
│   ├── healer.js                  # Self-healing for failed tasks
│   ├── mcp.js                     # MCP server lifecycle
│   ├── sync-version.js            # Version sync automation
│   ├── test-plugin.js             # Unit tests (41)
│   ├── test-integration.js        # Integration tests (47)
│   ├── test-infra.js              # Infrastructure tests (23)
│   ├── test-perf.js               # Performance benchmarks (15)
│   └── test-reliability.js        # Reliability/chaos tests (23)
├── agents/                        # Agent definition files (12 .md)
├── commands/                      # Command template files (49 .md)
├── rules/                         # Engineering rule files (35 .md)
├── skills/                        # Skill packs (19 directories)
├── templates/                     # Template files
│
├── CHANGELOG.md
├── CONTRIBUTING.md
├── SECURITY.md
├── LICENSE                        # MIT
└── package.json

Configuration

Plugin options are configured via opencode.json:

{
  "plugin": [
    "@millsydotdev/ceoinabox"
  ],
  "pluginConfig": {
    "@millsydotdev/ceoinabox": {
      "funnel_mode": "auto",
      "agents": {
        "blockchain-dev": false
      },
      "features": {
        "startup_summary": true,
        "session_persistence": true
      }
    }
  }
}

Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | funnel_mode | "auto" | "all" | "minimal" | "auto" | How agent questions reach you | | agents.* | boolean | true | Enable/disable specific department agents | | features.startup_summary | boolean | true | Show project summary on load | | features.session_persistence | boolean | true | Save/load session state |

Development

# Clone and install
git clone https://github.com/millsydotdev/CEOinaBox.git
cd CEOinaBox
npm install

# Run tests
npm test                    # Unit tests (41)
node scripts/test-integration.js   # Integration tests (47)
node scripts/test-infra.js         # Infrastructure tests (23)
node scripts/test-perf.js          # Performance benchmarks (15)
node scripts/test-reliability.js   # Reliability tests (23)

# Bump version (automatically syncs to all files)
npm version patch           # 1.3.x → 1.3.x+1
npm version minor           # 1.3.x → 1.4.0
npm version major           # 1.3.x → 2.0.0

# Publish (via CI/CD — push v* tag)
git push origin main --tags

Testing

The plugin has 149 automated tests across 5 suites:

| Suite | Tests | What It Covers | |-------|-------|----------------| | Unit | 41 | Config parsing, agent resolution, command registration, session paths | | Integration | 47 | MCP lifecycle, sync, clean, project detection, health, funnel, healer | | Infrastructure | 23 | Logger, storage (atomic writes), config, errors, regression tests | | Performance | 15 | Startup, storage, filesystem, concurrency benchmarks | | Reliability | 23 | Corrupted state, interrupted writes, missing files, lifecycle stress |

Self-Containment

CEOinaBox is fully self-contained:

• Plugin state → .ceostate/ inside the plugin directory
• Agent memories → inside the plugin, not your project
• Session state → inside the plugin
• Question funnel → inside the plugin
• Backups → managed with retention policy (max 5 per file, 30-day expiry)
• All file writes → atomic (temp+rename), crash-safe

The only thing created in your project is .opencode/ (OpenCode's workspace config directory) — only when you run /ceo-sync.

Marketplace Status

Release Candidate — suitable for public use.

| Criterion | Status | |-----------|--------| | Self-contained | ✅ All state inside plugin | | Atomic writes | ✅ Crash-safe on every write | | Shared infrastructure | ✅ 7 service modules | | Automated testing | ✅ 149 tests | | CI/CD | ✅ Quality gates on every push | | Documentation | ✅ README, CHANGELOG, CONTRIBUTING, SECURITY |

License

MIT — see LICENSE.

Built by millsydotdev for OpenCode.