Genor Orchestrator Skill

Unified orchestration: plugin-driven model routing, session hooks, project context automation, sidecar dashboard

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).

text

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

Tool	Purpose
orchestrator_set_context	MANDATORY before project work — sets project + task, returns context doc with location, ToC, backlog, ADRs, recent sessions
orchestrator_clear_context	Clears active project context, disables auto-routing/logging
orchestrator_get_status	Quick overview: model counts, sessions, projects, current context
orchestrator_get_models	List models with filters (status, provider, search, project routing)
orchestrator_check_models	Check eligible models for a project (routing filter inspection)
orchestrator_auto_populate	Auto-populate models from OpenClaw gateway config
orchestrator_log_session	Log a session (auto-logged by hooks, use for manual/retro entries)
orchestrator_log_decision	Log an architecture decision (creates auto-numbered ADR)
orchestrator_get_logs	Query structured JSONL logs
orchestrator_sync_project	Sync project from disk (generates CONTEXT.md, KEY_FILES.md)
orchestrator_get_project_docs	List all orchestrator-managed documents for a project

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

Hook	Automates
session_start	Track start time, reset sub-agent depth
session_end	Auto-log session to session_log.md, sessions.json, generate recovery doc
subagent_spawned/ended	Track sub-agent tree depth for context injection
before_model_resolve	Apply project routing filters (free-only, disabled, allowlists)
before_prompt_build	Inject project context into prompts (tasks, location, recent sessions)
agent_end	Observe session state
gateway_stop	Clean up maintenance timers

Sidecar: Dashboard Web UI (PM2)

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

Start: pm2 start ./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

Task Type	Primary	Fallback 1	Fallback 2
Heavy coding	Best available	ACP agent	Fast cloud
Quick edits	Fast cloud	Free tier	Local
Research	Best reasoning	Free tier	Local
Vision	Cloud vision	Local	Describe
Planning / design	Best reasoning	Free tier	Fast cloud
Docs / summaries	Free tier	Fast cloud	Local

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

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

Injection Template

Every spawned sub-agent prompt MUST include:

text

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

Scenario	Primary	Fallback
Single-line edit	edit tool	exec sed
Multi-file change	ACP coding agent	Manual edit
Research	Sub-agent	Web search
Debugging	Phase 5 protocol	Mental trace
Testing	Test framework	Manual
Browser testing	Browser tool	curl

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

Tool	Fallback chain
Codebase discovery	exec find → exec ls -R → read key files
update_plan	mental plan → STATE.md note
ACP coding agent	CLI variant → sub-agent → manual edit
edit tool	exec sed → write full file
Build	tsc --noEmit → node --check
Test	specific test file → manual
Vision	cloud → local → describe
Memory search	lcm_grep → exec grep

Scripts

Script	Purpose
bash/scripts/onboard.sh	First-time setup
bash/scripts/init-project.sh <path> <name>	Scaffold project
bash/scripts/log-session.sh ...	Log session (legacy, plugin hooks preferred)
bash/scripts/log-decision.sh ...	Log ADR (legacy, plugin tool preferred)
bash/scripts/check-prices.sh	Price check
bash/scripts/discover-models.sh	Probe providers
bash/scripts/test-model.sh <id>	Test connectivity
bash/dashboard/serve.sh	Start dashboard
bash/scripts/check-models.sh [project]	MANDATORY: Check eligible models before routing
python3 ./scripts/auto-populate-models.py	Auto-populate models from OpenClaw gateway config
bash/scripts/run-model-discovery.sh	Wrapper for cron-based auto-population

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

Resource	Path
Full documentation	./references/README.md
Onboarding guide	./references/ONBOARDING.md
Execution reference	./references/EXECUTION.md
Debugging guide	./references/DEBUGGING.md
Fallback tables	./references/FALLBACKS.md
Routing table	./ROUTING.md
Model catalog	orchestrator-data/MODEL_CATALOG.md
Dashboard	http://localhost:8766 (when running)