<div align="center">
  <img src="assets/logo.png" alt="logo" width="280" />
  <h1>OpenCode Orchestrator</h1>

  <p><b>Next-Gen Autonomous Mastery: Powered by HPFA™ & MSVP™</b></p>
  <p><i>Redefining Scalability with Fractal Swarm Intelligence and Multi-Stage Integrity</i></p>

  [![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
  [![npm](https://img.shields.io/npm/v/opencode-orchestrator.svg)](https://www.npmjs.com/package/opencode-orchestrator)
  [![Tests](https://img.shields.io/badge/tests-216%20passed-brightgreen.svg)]()
</div>

---

## ⚡ Quick Start

```bash
npm install -g opencode-orchestrator
```

Then in OpenCode, launch your mission:
```bash
/task "Architect and Build a Diablo-like Web Game"
```

### 🌌 **The End of Sequential Limits. The Era of Fractal Mastery.**

Where traditional agents hit a sequential wall, we deploy a fractal swarm. OpenCode Orchestrator is the world's most advanced autonomous engineering platform—a **Titan-Class Execution Engine** designed to conquer missions that break conventional AI. 

By fusing **Fractal Swarm Intelligence (HPFA™)** with **Continuous Multi-Stage Verification Pipeline (MSVP™)**, it delivers a level of scale, velocity, and architectural absolute previously considered impossible. Welcome to the final form of autonomous development. No bottlenecks. No limits. Only pure execution.


## 💎 The Four Pillars of Excellence

We’ve combined industrial-grade reliability with cutting-edge parallel intelligence to redefine what’s possible in AI coding.

*   **⚡ Velocity**: Parallelize up to 50 concurrent sessions. What takes hours for others is finished in minutes through **Cognitive Elasticity**.
*   **🧬 Scale**: **Fractal Delegation** allows workers to recursively spawn their own sub-agents. No task is too big for a system that can replicate its own intelligence.
*   **🛡️ Safety**: Our **MSVP (Multi-Stage Verification Pipeline)** reviews every line of code in parallel "Shadow Sessions" before it ever touches your build.
*   **♾️ Trust**: **Iron-Clad Reliability** via Write-Ahead Logging (WAL). Even after a crash, the system replays its history to resume exactly where it was.

---

## ⭐ Core Philosophy

```
┌───────────────────────────────────────────────────┐
│  🔍 EXPLORE → 📝 LEARN → 🔄 ADAPT → ⚡ ACT         │
│  Scan        Document    Adjust      Execute      │
└───────────────────────────────────────────────────┘
```


## 🚀 The Agents

| Agent | Role | What It Does |
|:------|:-----|:-------------|
| 🎯 **Commander** | Orchestrator | Leads the task, delegates work to other agents, ensures completion |
| 📋 **Planner** | Researcher | Analyzes the project, creates the plan, documents findings |
| 🔨 **Worker** | Implementer | Writes code, modifies files, follows the project's patterns |
| ✅ **Reviewer** | Verifier | Tests changes, checks for errors, confirms quality |



## 📖 Principles

| Principle | What It Means |
|:----------|:--------------|
| 🔍 **Never Assume** | Always check the actual code and config files first |
| 📝 **Document Everything** | Record patterns and findings for future tasks |
| 📚 **Verify with Evidence** | Run tests, cite sources, complete with proof |
| 🔄 **Adapt to the Project** | Match the project's existing style and patterns |
| 🤝 **Specialized Roles** | Each agent has a clear, focused responsibility |


## 🏛️ Hyper-Parallel Architecture: HPFA & MSVP

The orchestrator eliminates the linear reasoning bottleneck of conventional AI agents by shifting from sequential execution to a **Distributed Runtime Unit** paradigm.

### 🧬 **HPFA™ (Hyper-Parallel Fractal Architecture)**
HPFA defines a recursive problem-solving model that decomposes massive codebases into atomic task units through a fractal hierarchy.
*   **Fractal Delegation**: Workers are instantiated as autonomous controllers with localized `TaskLauncher` contexts. This enables recursive spawning of sub-agents up to 8 levels deep, mapping complex architectural hierarchies into a parallel execution grid.
*   **Cognitive Concurrency Control**: A dedicated state-machine manages up to 50 concurrent sessions. It monitors success/failure trajectories to dynamically scale concurrency slots, ensuring maximum throughput while maintaining strict rate-limit compliance.

### 🛡️ **MSVP™ (Multi-Stage Verification Pipeline)**
MSVP ensures continuous integration integrity by decoupling verification from the implementation lifecycle, treating code review as a parallel background-thread.
*   **Shadow Review Pipeline**: Upon every file-write operation, a parallel reviewer session is instantly snapshotted (Unit-level Verification). This zero-latency audit identifies defects the millisecond they are introduced, without blocking the primary implementation thread.
*   **Global Barrier-Sync Protocol**: Implements a synchronized verification gate. The system enforces a blocking "Barrier" that requires consistency across all distributed units before transitioning to the final Master Review (E2E Integration) and Mission Sealing.

```
              /task "Build Diablo Game"
                           │
           ╔═══════════════════════════════════════╗
           ║     🎯 COMMANDER — Orchestrator       ║
           ║        (Main Session - Single)        ║
           ╚═══════════════════╤═══════════════════╝
                               │
    ══════════════════════════▼══════════════════════════
    ║          🚀 PHASE 0: DISCOVERY SWARM (Parallel)    ║
    ═════════════════════════════════════════════════════
    │               │               │               │
    ▼ Scout         ▼ Scout         ▼ Scout         ▼ Scout
 [Structure]      [Stack]         [Docs]          [Infra]
    └───────────────┬───────────────┬───────────────┘
                    │ Consolidate & Sync
           ┌────────▼───────────────────┐
           │      📋 PLANNER — Create Plan         │
           │    → Outputs: Architectural Grid      │
           └───────────────────┬───────────────────┘
                               │
    ══════════════════════════╧══════════════════════════
    ║            🔥 HPFA PARALLEL GRID (MSVP)           ║
    ══════════════════════════════════════════════════════
    │               │               │               │
    ▼               ▼               ▼               ▼
┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐
│🔨 WORKER │    │🔨 WORKER │    │🔨 WORKER │    │🔨 WORKER │  <-- Fractal Spawning
│ Module A │    │ Module B │    │ Module C │    │ Module D │
└────┬─────┘    └────┬─────┘    └────┬─────┘    └────┬─────┘
     │ ⚡ Instant    │ ⚡ Instant    │ ⚡ Instant    │ ⚡ Instant
     ▼ Review       ▼ Review       ▼ Review       ▼ Review
┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐
│✅ REVIEWR│    │✅ REVIEWR│    │✅ REVIEWR│    │✅ REVIEWR│  <-- Stage 1: Unit
│ (Unit-A) │    │ (Unit-B) │    │ (Unit-C) │    │ (Unit-D) │      Verification
└────┬─────┘    └────┬─────┘    └────┬─────┘    └────┬─────┘
     │               │               │               │
    ═▼═══════════════▼═══════════════▼═══════════════▼════
    ║                ⏳ SYNC BARRIER                     ║
    ══════════════════════════════════════════════════════
                               │
           ┌───────────────────▼───────────────────┐
           │      ✅ MASTER REVIEWER — Final Pass  │
           │         (Cross-module Integration)    │
           │    → Stage 2: E2E & System Integrity  │
           └───────────────────┬───────────────────┘
                               │
                     ┌─────────┴─────────┐
                     │   Seal Conditions │
                     │   Verified?       │
                     └─────────┬─────────┘
                         No ↙     ↘ Yes
                     ♻️ LOOP    🎖️ MISSION
                    (Adaptive)   SEALED
```

### Execution Model (MSVP)

| Phase | Agent | Parallelism | Verification Level |
|:------|:------|:------------|:-------------------|
| 1️⃣ Plan | Planner | **Single** | Static Analysis |
| 2️⃣ Implement | Workers | **HPFA Parallel** | Direct Coding |
| 3️⃣ Unit Pass | Reviewers | **Shadow Parallel** | **1차 리뷰**: Unit Tests (Async) |
| 4️⃣ Final Sync | Barrier | **Blocking** | All Units Verified |
| 5️⃣ Integration | Master Reviewer | **Single** | **2차 리뷰**: Full E2E & Sync |

## Features

| Feature | What It Does |
|:---------|:-------------|
| 🚀 **MSVP™ Pipeline** | Zero-latency unit reviews triggered the millisecond code is written |
| 🧬 **Fractal Spawning** | Workers recursively spawn sub-agents for infinite structural depth |
| ⚡ **50 Parallel Tasks** | Titan-class density—run massive swarms without breaking a sweat |
| 🔄 **Non-Stop Recovery** | WAL-powered cognitive persistence; resumes instantly after any crash |
| 🔥 **Multi-File Ops** | Massive parallel edits with cross-file context integrity |
| 🛡️ **Self-Scaling** | Dynamic AI-driven concurrency management based on success velocity |
| 🩹 **Memory Integrity** | 100% reclamation; engineered for sessions with 10k+ iterations |
| 🏗️ **Clean-Code Engine**| Enforces industrial modularity and clean architectural patterns |

---


## Error Handling

| Error | What Happens |
|:------|:-------------|
| 💥 Tool crash | Inject recovery prompt and retry |
| 🚦 Rate limit hit | Wait and retry with exponential backoff |
| 📦 Context overflow | Compact the context automatically |
| ⏱️ Session timeout | Resume from the last checkpoint |
| 🔨 Build failure | Fix the issue and retry |


---

## 🎹 Developer's Words

> "We are not just building a tool; we are building an autonomous engineer that can evolve with the project. HPFA and MSVP are the heart of this evolution—turning AI from a chatbot into a high-performance execution engine."
> 
> [Read the full Developer's Note →](docs/DEVELOPERS_NOTE.md)


## 📄 License

MIT License. [LICENSE](LICENSE)
