Genor's Project Orchestration

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

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

Data Directory

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

orchestrator-data/
├── models.json          — model inventory
├── session_log.md       — session history table
├── price_changes.log    — price tracking
├── MODEL_CATALOG.md     — generated catalog
├── projects/            — per-project session tracking
│   └── \x3Cname>/sessions.json
└── sessions/            — detailed session state files
    └── YYYY-MM-DD-HHMM-\x3Cproject>-\x3Ctask-slug>.md

Scripts

Conversational Triggers

• "onboard" → bash scripts/onboard.sh
• "start dashboard" → bash dashboard/serve.sh
• "onboard project X" → bash scripts/init-project.sh \x3Cpath> \x3Cname>
• "check prices" → bash scripts/check-prices.sh

Execution Workflow

Phase 0: Init

Understand the codebase (exec find . -name '*.ts' | head -50), search memory, research.

Phase 1: Plan

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

Phase 2: Execute

Phase 3: Verify

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

Phase 4: Manage

Update .planning/STATE.md and .planning/ROADMAP.md after every session.

Phase 5: Diagnose

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

Phase 6: Tool Fallbacks

Model Routing

See {baseDir}/ROUTING.md for the current routing table. See orchestrator-data/MODEL_CATALOG.md for full inventory.

Sub-Agent Protocol

Every spawned sub-agent MUST include:

IMPORTANT: Follow orchestration conventions:
- 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

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.md
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), .planning/ADRs/ (decisions), summary.

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

References