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

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:

## 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:

## 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

## 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:

.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