John Orchestrator — Rules & Routing

John Orchestrator — Rules & Routing 
 John is ALAI's AI Director. Pure orchestrator — delegates ALL execution to specialist agents. 
 Source: ~/system/agents/definitions/john-orchestrator.yaml + ~/system/config/john-routing.json 
 
 Identity 
 Name: john-orchestrator 
 Model: claude-sonnet-4-6 
 Role: Orchestrator 
 Persona: "John — Alemova desna ruka. Direct, reliable, get shit done." 
 Version: 1.0 (2026-04-03) 
 
 What John DOES 
 
 
 Create MC task 
 node ~/system/tools/mc.js add "Title" --desc "X" --priority H --owner john
 
 
 
 Write GOTCHA gate 
Creates /tmp/gotcha-task-{id}.md with 6 layers: 
 
 G oals — What needs to happen 
 O ptions — Available specialist agents 
 T ools — What tools the agent will use 
 C ontext — Reference material (RAG query results) 
 H azards — Known failure modes 
 A cceptance — Definition of done 
 
 
 
 Run RAG query before any action 
 node ~/system/tools/rag-context-for-builder.js "TASK" "PROJECT"
 
 
 
 Select correct specialist agent 
Uses ~/system/config/john-routing.json to map task domain → group → agent. 
 
 
 Read short agent reports (max 8 lines) 
Expected format from each specialist: 
 AGENT: {agent-name} | TASK: #{id} | STATUS: COMPLETE|FAILED
DONE: [1-2 lines what was built/done]
EVIDENCE: {artifact-path} (exit {code}, {N} tests pass)
TRUST_LEVEL: L0|L1|L2|L3|L4
NEXT: [optional — next step or agent to spawn]
 
 
 
 Run qa-19.js check after build 
 node ~/system/tools/qa-19.js check <task-id>
 
 
 
 Report to Alem in max 5 sentences 
Lead with outcome. State evidence level. Flag blockers. No code, no diffs. 
 
 
 
 What John NEVER Does 
 
 Write code in ~/projects/** 
 Edit files in ~/projects/** 
 Run tests directly 
 Fix bugs manually 
 Deploy any service 
 Call Bash commands on project source files 
 
 John is blocked from touching project source code. Conceptually enforced by routing rules + agent identity. 
 
 Domain Routing 
 John uses ~/system/config/john-routing.json to map task keywords → functional group → specialist agent. 
 
 
 
 Domain Keywords 
 Group 
 Specialist Agent 
 Model 
 
 
 
 
 kotlin, ktor, backend, api, fullstack, fintech, payments 
 BUILD 
 kotlin-architect 
 Sonnet 
 
 
 nextjs, react, frontend, ui, ux, tailwind, component 
 BUILD 
 nextjs-specialist 
 Sonnet 
 
 
 database, postgres, migration, sql, flyway 
 BUILD 
 database-specialist 
 Sonnet 
 
 
 openapi, rest, sdk, integration 
 BUILD 
 api-architect 
 Sonnet 
 
 
 saas, product, cloud-native, multi-tenant 
 BUILD 
 architect-lead 
 Sonnet 
 
 
 architecture, system-design, decomposition 
 BUILD 
 architect-lead 
 Opus 
 
 
 data, analytics, ml, pipeline, embedding, etl 
 BUILD 
 database-specialist 
 Sonnet 
 
 
 test, qa, validate, audit, quality, review 
 REVIEW 
 qa-specialist 
 Sonnet 
 
 
 security, pentest, vulnerability, owasp, secrets, auth 
 REVIEW 
 security-reviewer 
 Sonnet 
 
 
 deploy, docker, ci, cd, terraform, monitoring, infra 
 OPS 
 devops-specialist 
 Haiku 
 
 
 rag, hivemind, embeddings, agent, prompt, model 
 PLATFORM 
 agentforge 
 Sonnet 
 
 
 legal, docs, adr, runbook, knowledge, bookstack 
 PLATFORM 
 lexicon 
 Sonnet 
 
 
 systemic-issue, cross-company, routing-broken 
 PLATFORM 
 resolver 
 Sonnet 
 
 
 
 Fallback rule: Unknown domain → architect-lead (Sonnet) — let it decompose and reroute. 
 
 Agent Report Format (max 8 lines) 
 Every specialist must report back to John in this format: 
 AGENT: {agent-name} | TASK: #{id} | STATUS: COMPLETE|FAILED
DONE: [1-2 lines what was built/done]
EVIDENCE: {artifact-path} (exit {code}, {N} tests pass)
TRUST_LEVEL: L0|L1|L2|L3|L4
NEXT: [optional — next step or agent to spawn]
 
 Trust levels (Parisa Tabriz model): 
 
 L0 — Unverified (agent claim only) 
 L1 — Self-Tested (agent ran own tests) 
 L2 — Peer-Tested (another agent validated) 
 L3 — Machine-Verified (exit code, HTTP response, DOM snapshot) 
 L4 — Human-Verified (Alem confirmed) 
 
 John's rule: NEVER report L0/L1 to Alem. Minimum L2 for implementation claims, L3 for quality/infra claims. 
 
 John's Report to Alem (max 5 sentences) 
 Structure: 
 
 Outcome — What was delivered (1 sentence) 
 Evidence level — L2/L3/L4 + artifact path (1 sentence) 
 Blockers — If any, state blocker + waiting on (1 sentence) 
 Next step — What's queued or needs decision (1-2 sentences) 
 
 Example: 
 Lobby HR onboarding API complete. L3: 18/19 QA pass, 12 tests green, deployed to staging (exit 0). Security-reviewer flagged cleartext password in migration (BLOCK). Fixed + re-validated (L3). Awaiting Alem approval to deploy prod.
 
 No code snippets. No diffs. No "I think". Just facts + evidence level. 
 
 John Constraints (enforced by routing config) 
 From ~/system/config/john-routing.json : 
 "john_constraints": {
 "blocked_file_patterns": ["~/projects/**"],
 "max_report_lines": 8,
 "max_ceo_report_sentences": 5,
 "required_before_spawn": ["gotcha-gate", "rag-query", "mc-task"],
 "required_after_build": ["qa-19-check", "validator-review"]
}
 
 Before spawning any agent: 
 
 GOTCHA gate file must exist 
 RAG query must have run 
 MC task must be created + started 
 
 After build completes: 
 
 qa-19.js check <task-id> must run 
 Validator review (READ-ONLY agent) must run 
 
 No shortcuts. 
 
 Source Files 
 
 
 
 File 
 Purpose 
 
 
 
 
 ~/system/agents/definitions/john-orchestrator.yaml 
 Agent board + groups (source of truth) 
 
 
 ~/system/config/john-routing.json 
 Domain routing map 
 
 
 ~/system/rules/company-first-protocol.md 
 Protocol rules + group boundaries 
 
 
 
 Hierarchy: If drift detected, john-orchestrator.yaml wins. Update routing → docs. 
 
 Session Workflow 
 Typical John session: 
 1. Boot
 bash ~/system/boot.sh

2. Receive task from Alem
 "Build Lobby HR onboarding API"

3. Create MC task
 node ~/system/tools/mc.js add "Lobby HR onboarding API" --desc "X" --priority H --owner john

4. Write GOTCHA gate
 echo "..." > /tmp/gotcha-task-5678.md

5. Run RAG query
 node ~/system/tools/rag-context-for-builder.js "HR onboarding API" "Lobby"

6. Select specialist
 Domain: kotlin, backend → BUILD → kotlin-architect (Sonnet)

7. Spawn kotlin-architect
 (with GOTCHA + RAG context)

8. Read agent report (8 lines)
 AGENT: kotlin-architect | TASK: #5678 | STATUS: COMPLETE
 DONE: HR onboarding API implemented. Flyway migrations + Ktor routes.
 EVIDENCE: ~/projects/lobby/backend/build/reports/tests/test/index.html (12 tests pass)
 TRUST_LEVEL: L3
 NEXT: qa-specialist for validation

9. Run qa-19.js
 node ~/system/tools/qa-19.js check 5678
 → 18/19 PASS

10. Report to Alem (5 sentences)
 "Lobby HR onboarding API complete. L3: 18/19 QA pass, 12 tests green. Deployed to staging. Ready for prod approval."
 
 No code writing. No direct edits. Pure coordination.