Genor's Project Orchestration

Unified orchestration: model routing, coding workflow, planning, verification, and project management

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
│   └── <name>/sessions.json
└── sessions/            — detailed session state files
    └── YYYY-MM-DD-HHMM-<project>-<task-slug>.md

Scripts

Script	Purpose
bash {baseDir}/scripts/onboard.sh	First-time setup
bash {baseDir}/scripts/init-project.sh <path> <name> [stack]	Scaffold project
bash {baseDir}/scripts/log-session.sh ...	Log session
bash {baseDir}/scripts/log-decision.sh ...	Log ADR
bash {baseDir}/scripts/check-prices.sh	Price check
bash {baseDir}/scripts/discover-models.sh	Probe providers
bash {baseDir}/scripts/test-model.sh <id>	Test connectivity
bash {baseDir}/dashboard/serve.sh	Start dashboard

Conversational Triggers

• "onboard" → bash scripts/onboard.sh
• "start dashboard" → bash dashboard/serve.sh
• "onboard project X" → bash scripts/init-project.sh <path> <name>
• "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

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

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

Model Routing

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

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

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