Genor's Project Orchestration

Single source of truth for agentic development work, model orchestration, project management, and context automation.

Core Principles

1. Codebase First — Never touch code without understanding it first
2. Plan Before Act — update_plan for anything beyond one edit
3. Verify Before Claim — No completion claim without fresh evidence
4. Self-Review — Every output gets audited before delivery
5. Fail Gracefully — Every step has a fallback chain
6. Document Everything — Log sessions, decisions, architecture
7. Model-Routing Compliance — All LLM agents MUST consult project routing rules (free-only, disabled, per-project allowlist) before selecting a model or spawning a sub-agent.
8. Context First — Always call orchestrator_set_context before project work to enable automation hooks.

Data Directory

All user data lives in orchestrator-data/ (set ORCHESTRATOR_DATA_DIR to override).

orchestrator-data/
├── models.json             — model inventory
├── dashboard-config.json   — routing config (free-only, disabled, project allowlists)
├── session_log.md          — session history table
├── price_changes.log       — price tracking
├── MODEL_CATALOG.md        — generated catalog
├── logs/                   — structured JSONL logs
├── adrs/                   — architecture decision records
├── projects/               — per-project data (CONTEXT, STATE, ROADMAP, BACKLOG, RECOVERY, sessions)
│   └── <name>/
│       ├── CONTEXT.md
│       ├── KEY_FILES.md
│       ├── RECOVERY.md
│       ├── BACKLOG.json
│       ├── sessions.json
│       └── ...
└── sessions/               — detailed session state files

Architecture

The orchestrator has two components that work together:

Plugin (Tools + Hooks)

Runs inside OpenClaw's plugin system — no separate process needed. Provides:

Tools (12):

Hooks (8) — auto-registered, no manual calls:

Sidecar: Dashboard Web UI (PM2)

The dashboard is a standalone Python HTTP server running as a PM2 process:

Start: pm2 start {baseDir}/dashboard/server.py --name orchestration-dashboard --interpreter python3 -- 8766

Provides:

• Model inventory CRUD with sort, filter, search
• Routing config (free-only toggle, global disable, per-project allowlists)
• Session log viewer
• Config persistence to disk

The dashboard runs independently of the plugin — restarting it does NOT affect OpenClaw or any running sessions.

Project Context Automation

When orchestrator_set_context(project="my-project", task="fix-bug") is called:

1. Sets active context — all hooks use this for routing, logging, context injection
2. Returns context doc with location, File ToC, CONTEXT/STATE/ROADMAP summaries, open backlog tasks, recent ADRs, recent sessions, recovery doc availability
3. Auto-injects project state into the LLM's prompt every turn
4. Auto-logs when session ends (session_log.md, sessions.json, recovery doc)
5. Auto-routes models according to project allowlists

All data in orchestrator-data/ survives OpenClaw session wipes — it's on the filesystem, not in session storage.

Model Population

Models are automatically populated from OpenClaw's own gateway configuration. The script reads openclaw.json and extracts all configured model entries from providers, agent defaults, and routing chains. It merges into orchestrator-data/models.json, preserving all manually-curated fields (tier, speed_rating, capabilities, notes, research). Models in the catalog not found in the config are kept as-is (never deleted).

Auto-population runs nightly via cron. Manual edits (tier, speed, pricing, routing rules) are done through the Dashboard WebUI.

Model Routing

Routing Decision Table

MANDATORY: Check Configuration Before Every Routing Decision

Before selecting any model or spawning a sub-agent:

1. Read dashboard-config.json (or call GET /api/config)
2. Identify the current project name
3. Apply the filtering chain:
   • Global free-only: If free_only_mode: true, eliminate all paid models
   • Global disabled: Remove any model in disabled_models list
   • Per-project allowlist: If the project has a non-empty model_allowlist, ONLY those models are eligible
   • Per-project free-only: If the project has free_only: true, eliminate paid models from the allowlist
4. Only then select a model from the remaining eligible set
5. If no eligible model exists, report the conflict — do NOT silently use a banned model

CLI shortcut: bash scripts/check-models.sh my-project-name

Filtering Chain (applied in order)

1. Global free-only removes paid models (if enabled)
2. Global disabled removes blocked models
3. Per-project allowlist keeps only whitelisted (if set)
4. Per-project free-only removes paid from allowlist (if enabled)

API Endpoints (Dashboard WebUI Sidecar)

• GET /api/config — read config
• POST /api/config — update config
• GET /api/models — filtered model list
• GET /api/models?project=<name> — filtered for specific project
• GET /api/models?all=1 — full unfiltered list
• GET /api/models?id=<id> — single model with disabled flag
• POST /api/models — create or update model
• DELETE /api/models?id=<id> — delete model
• GET /api/status — quick status
• GET /api/all — everything

Sub-Agent Protocol

Step 0: Set Project Context (MANDATORY)

Call orchestrator_set_context(project="my-project", task="fix-bug") before spawning any sub-agent.

This enables auto-routing, auto-logging, context injection, and background maintenance.

Step 1: Check Model Routing Configuration

bash scripts/check-models.sh my-project-name

Injection Template

Every spawned sub-agent prompt MUST include:

IMPORTANT: Follow orchestration conventions:
- BEFORE selecting any model: read dashboard-config.json, apply routing filters for the project. Run: bash scripts/check-models.sh <project-name>
- Understand the codebase first (exec find as fallback)
- Plan before coding (update_plan or mental plan)
- Verify before claiming (build, test, screenshot)
- Self-review output before returning
- Use fallback chains when tools are unavailable

Execution Workflow

Phase 0: Init

Understand the codebase, search memory, research.

Phase 1: Plan

Call update_plan. Size the work: small (1-3 files), medium (3-8), large (8+ → decompose with workboard).

Phase 2: Execute

Phase 3: Verify

Build → Test → Lint → Screenshot (if UI). No claim without evidence.

Phase 4: Manage

Update CONTEXT.md, STATE.md, BACKLOG.json after every session.

Phase 5: Diagnose

Reproduce → Hypothesise (3-5 causes) → Instrument one variable → Fix → Regression test.

Phase 6: Tool Fallbacks

Scripts

Conversational Triggers

• "start dashboard" → bash dashboard/serve.sh or pm2 start ...
• "onboard project X" → bash scripts/init-project.sh <path> <name>
• "check prices" → bash scripts/check-prices.sh

Design Grilling

Before significant architectural work, conduct a structured interview:

1. One question at a time, wait for feedback
2. Challenge terms that conflict with existing context docs
3. Propose precise canonical terms for vague language
4. Stress-test with edge cases
5. Cross-reference with code; surface contradictions

Generate: CONTEXT.md (glossary), ADRs (decisions), summary.

ADR criteria (all three must be true): hard to reverse, surprising without context, real trade-off.

References