Joko Orchestrator

---
name: joko-orchestrator
description: Use when deterministically coordinating autonomous planning and execution
  across available skills under strict guardrails.
domain: core
author: oyi77
license: Apache-2.0
subdomain: core-platform
tags:
- infrastructure
- joko
- memory
- orchestrator
- self-improvement
version: 1.0.0
category: core
---

persona:
  name: "Jeff Dean"
  title: "The Distributed Systems Legend - Master of Orchestration"
  expertise: ['Distributed Systems', 'Orchestration', 'Large-scale Computing', 'MapReduce']
  philosophy: "Scale is a feature, not a bug."
  credentials: ['Senior Fellow at Google', 'Created MapReduce and TensorFlow', "Led Google's infrastructure"]
  principles: ['Distribute workloads', 'Handle failures gracefully', 'Scale horizontally', 'Monitor everything']



# Autonomous Skill Orchestrator v2.0

## Overview

Deterministically coordinate autonomous planning and execution across available skills under strict guardrails. Inspired by oh-my-opencode's three-layer architecture.


## Anti-Rationalization Table

| Rationalization | Reality |
|---|---|
| "I'll figure it out as I go" | A structured approach saves time and reduces errors. Follow the workflow in this skill rather than improvising. |
| "I already know this topic" | Familiarity breeds shortcuts. Use the checklist to verify you haven't missed critical steps. |
| "This doesn't apply to my situation" | The patterns here generalize across contexts. Adapt, don't skip — the underlying principles hold. |
| "One more tool will fix it" | Adding complexity rarely solves process gaps. Master the core workflow first. |

## When to Use

**Trigger phrases:**
- "joko orchestrator"
- "When coordinating multiple skills for complex tasks"
- "When planning and executing multi-step workflows"
- "When you need strict guardrails for autonomous execution"


- When coordinating multiple skills for complex tasks
- When planning and executing multi-step workflows
- When you need strict guardrails for autonomous execution
- When managing context across long-running tasks

## When NOT to Use

- For simple, single-step tasks
- When strict coordination isn't needed

## Quick Reference

**Three-Layer Architecture:**
1. Planning Layer - Interview + Plan Generation
2. Execution Layer - Task Dispatch + Verification
3. Review Layer - Quality gates + Feedback

## Common Mistakes

- Skipping planning phase
- Not using guardrails
- Not coordinating skills properly

Traditional AI follows: user asks → AI responds. This fails for complex work because:
1. **Context overload**: Large tasks exceed context windows
2. **Cognitive drift**: AI loses track mid-task
3. **Verification gaps**: No systematic completeness check
4. **Human bottleneck**: Requires constant intervention

This skill solves these through **specialization and delegation**.

---

## Architecture

```
┌─────────────────────────────────────────────────────────┐
│  PLANNING LAYER (Interview + Plan Generation)          │
│  • Clarify intent through interview                     │
│  • Generate structured work plan                        │
│  • Review plan for gaps                                 │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│  ORCHESTRATION LAYER (Atlas - The Conductor)           │
│  • Read plan, delegate tasks                            │
│  • Accumulate wisdom across tasks                       │
│  • Verify results independently                         │
│  • NEVER write code directly — only delegate            │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│  EXECUTION LAYER (Sub-agents via sessions_spawn)       │
│  • Focused task execution                               │
│  • Return results + learnings                           │
│  • Isolated context per task                            │
└─────────────────────────────────────────────────────────┘
```

---

## Activation
This section covers activation for the joko-orchestrator skill.
Key operations include input validation, core processing, and output verification.
Refer to the skill overview for detailed usage instructions.


### Explicit Triggers
- "use autonomous-skill-orchestrator"
- "activate autonomous-skill-orchestrator"
- "start autonomous orchestration"
- "ulw" or "ultrawork" (magic keyword mode)

### Magic Word: `ultrawork` / `ulw`
Include `ultrawork` or `ulw` in any prompt to activate full orchestration mode automatically.
The agent figures out the rest — parallel agents, background tasks, deep exploration, and relentless execution until completion.

---

## Phase 1: Planning (Prometheus Mode)
This section covers phase 1: planning (prometheus mode) for the joko-orchestrator skill.
Key operations include input validation, core processing, and output verification.
Refer to the skill overview for detailed usage instructions.


### Step 1.1: Interview
Before planning, gather clarity through brief interview:

**Ask only what's needed:**
- What's the core objective?
- What are the boundaries (what's NOT in scope)?
- Any constraints or preferences?
- How do we know when it's done?

**Interview Style by Intent:**
| Intent | Focus | Example Questions |
|--------|-------|-------------------|
| **Refactoring** | Safety | "What tests verify current behavior?" |
| **Build New** | Patterns | "Follow existing conventions or deviate?" |
| **Debug/Fix** | Reproduction | "Steps to reproduce? Error messages?" |
| **Research** | Scope | "Depth vs breadth? Time constraints?" |

### Step 1.2: Plan Generation
After interview, generate structured plan:

```markdown
## Work Plan: [Title]
This section covers work plan: [title] for the joko-orchestrator skill.
Key operations include input validation, core processing, and output verification.
Refer to the skill overview for detailed usage instructions.


### Objective
[One sentence, frozen intent]

### Tasks
- [ ] Task 1: [Description]
  - Acceptance: [How to verify completion]
  - References: [Files, docs, skills needed]
  - Category: [quick|general|deep|creative]
  
- [ ] Task 2: ...

### Guardrails
- MUST: [Required constraints]
- MUST NOT: [Forbidden actions]

### Verification
[How to verify overall completion]
```

### Step 1.3: Plan Review (Self-Momus)
Before execution, validate:
- [ ] Each task has clear acceptance criteria
- [ ] References are concrete (not vague)
- [ ] No scope creep beyond objective
- [ ] Dependencies between tasks are explicit
- [ ] Guardrails are actionable

If any check fails, refine plan before proceeding.

---

## Phase 2: Orchestration (Atlas Mode)
1. Receive input and validate format
2. Route to appropriate handler based on input type
3. Execute core operation with monitoring
4. Transform output to expected format
5. Return results or trigger follow-up actions


### Conductor Rules
The orchestrator:
- ✅ CAN read files to understand context
- ✅ CAN run commands to verify results
- ✅ CAN search patterns with grep/glob
- ✅ CAN spawn sub-agents for work

The orchestrator:
- ❌ MUST NOT write/edit code directly
- ❌ MUST NOT trust sub-agent claims blindly
- ❌ MUST NOT skip verification

### Step 2.1: Task Delegation

Use `sessions_spawn` with category-appropriate configuration:

| Category | Use For | Model Hint | Timeout |
|----------|---------|------------|---------|
| `quick` | Trivial tasks, single file changes | fast model | 2-5 min |
| `general` | Standard implementation | default | 5-10 min |
| `deep` | Complex logic, architecture | thinking model | 10-20 min |
| `creative` | UI/UX, content generation | creative model | 5-10 min |
| `research` | Docs, codebase exploration | fast + broad | 5 min |

**Delegation Template:**
```
sessions_spawn(
  label: "task-{n}-{short-desc}",
  task: """
  ## Task
  {exact task from plan}
  
  ## Expected Outcome
  {acceptance criteria}
  
  ## Context
  {accumulated wisdom from previous tasks}
  
  ## Constraints
  - MUST: {guardrails}
  - MUST NOT: {forbidden actions}
  
  ## References
  {relevant files, docs}
  """,
  runTimeoutSeconds: {based on category}
)
```

### Step 2.2: Parallel Execution

Identify independent tasks (no file conflicts, no dependencies) and spawn them simultaneously:

```
# Tasks 2, 3, 4 have no dependencies
sessions_spawn(label="task-2", task="...")
sessions_spawn(label="task-3", task="...")
sessions_spawn(label="task-4", task="...")
# All run in parallel
```

### Step 2.3: Wisdom Accumulation

After each task completion, extract and record:

```markdown
## Wisdom Log
This section covers wisdom log for the joko-orchestrator skill.
Key operations include input validation, core processing, and output verification.
Refer to the skill overview for detailed usage instructions.


### Conventions Discovered
- [Pattern found in codebase]

### Successful Approaches
- [What worked]

### Gotchas
- [Pitfalls to avoid]

### Commands Used
- [Useful commands for similar tasks]
```

Store in: `memory/orchestrator-wisdom.md` (append-only during session)

Pass accumulated wisdom to ALL subsequent sub-agents.

### Step 2.4: Independent Verification

**NEVER trust sub-agent claims.** After each task:
1. Read actual changed files
2. Run tests/linting if applicable
3. Verify acceptance criteria independently
4. Cross-reference with plan requirements

If verification fails:
- Log the failure in wisdom
- Re-delegate with failure context
- Max 2 retries per task, then escalate to user

---

## Phase 3: Completion
This section covers phase 3: completion for the joko-orchestrator skill.
Key operations include input validation, core processing, and output verification.
Refer to the skill overview for detailed usage instructions.


### Step 3.1: Final Verification
- All tasks marked complete
- All acceptance criteria verified
- No unresolved issues in wisdom log

### Step 3.2: Summary Report
```markdown
## Orchestration Complete
1. Receive input and validate format
2. Route to appropriate handler based on input type
3. Execute core operation with monitoring
4. Transform output to expected format
5. Return results or trigger follow-up actions


### Completed Tasks
- [x] Task 1: {summary}
- [x] Task 2: {summary}

### Learnings
{key wisdom accumulated}

### Files Changed
{list of modified files}

### Next Steps (if any)
{recommendations}
```

---

## Safety Guardrails
This section covers safety guardrails for the joko-orchestrator skill.
Key operations include input validation, core processing, and output verification.
Refer to the skill overview for detailed usage instructions.


### Halt Conditions (Immediate Stop)
- User issues explicit stop command
- Irreversible destructive action detected
- Scope expansion beyond frozen intent
- 3+ consecutive task failures
- Sub-agent attempts to spawn further sub-agents (no recursion)

### Risk Classification
| Class | Description | Action |
|-------|-------------|--------|
| A | Irreversible, destructive, or unbounded | HALT immediately |
| B | Bounded, resolvable with clarification | Pause, ask user |
| C | Cosmetic, non-operative | Proceed with note |

### Forbidden Actions
- Creating new autonomous orchestrators
- Modifying this skill file
- Accessing credentials without explicit need
- External API calls not in original scope
- Recursive spawning (sub-agents spawning sub-agents)

---

## Stop Commands
User can stop at any time with:
- "stop"
- "halt"
- "cancel orchestration"
- "abort"

On stop: immediately terminate all spawned sessions, output summary of completed work, await new instructions.

---

## Memory Integration
- Connects with existing toolchain via standard interfaces
- Supports webhook-based event notifications
- Compatible with CI/CD pipelines for automated workflows
- Provides structured output for downstream consumption


### During Orchestration
- Append to `memory/orchestrator-wisdom.md` for learnings
- Reference existing memory files for context

### After Orchestration
- Update daily memory with orchestration summary
- Persist significant learnings to MEMORY.md if valuable

---

## Role Templates (Optional)

For complex multi-agent projects, assign named roles to clarify responsibilities. Inspired by the Olympic hierarchy:

| Role | Emoji | Responsibility | Maps To |
|------|-------|---------------|---------|
| **Zeus** | 👑 | Decision maker, holds master intent | Orchestrator (Atlas) |
| **Metis** | 🦉 | Research, fact-checking, feasibility | Research sub-agent |
| **Prometheus** | 🔥 | Planning, strategy synthesis | Planning Layer |
| **Atlas** | 🌍 | Task breakdown, coordination | Orchestration Layer |
| **Hephaestus** | 🔨 | One-off complex execution (code, deploy) | Execution sub-agent |
| **Sisyphus** | 🪨 | Repetitive maintenance, monitoring | Cron/process sub-agent |
| **Momus** | 🎭 | QA, audits against requirements | Review Layer |

**When to use roles:** Projects with 5+ tasks spanning research, implementation, and review.
**When to skip:** Simple 2-3 task orchestrations — just use the three-layer architecture directly.

**Role-based directory structure:**
```text
.orchestrator/
├── plans/       # Strategy docs (Prometheus)
├── research/    # Intelligence reports (Metis)
├── tasks/       # Task tickets (Atlas)
├── wisdom/      # Accumulated learnings
└── logs/        # Execution logs
```

---

## Example Usage

**Simple (magic word):**
```
ulw refactor the authentication module to use JWT
```

**Explicit activation:**
```
activate autonomous-skill-orchestrator

Build a REST API with user registration, login, and profile endpoints
```

**With constraints:**
```
use autonomous-skill-orchestrator
- Build payment integration with Stripe
- MUST: Use existing database patterns
- MUST NOT: Store card numbers locally
- Deadline: Complete core flow only
```

## Common Rationalizations

| Rationalization | Reality |
|---|---|
| "I'll do this later" | Explain why this excuse is wrong for this skill |
| "This is simple, skip steps" | Even simple tasks benefit from process |

## Red Flags

- Agent output is not validated against expected quality standards
- Prerequisites are not verified before task execution
- Watch for shortcuts and skipped steps

## Verification

After completing this skill, confirm:

- [ ] Output meets the defined quality and completeness requirements
- [ ] All prerequisites are verified and documented
- [ ] All required outputs generated
- [ ] Success criteria met

## Process

1. Analyze the task requirements
2. Apply domain expertise
3. Verify output quality