How to use the orchestration layer to manage work across all HelloCollege projects.
SSH into hc-central and start (or attach to) the orchestrator Zellij session:
ssh hc-central
zellij attach orchestrator 2>/dev/null || zellij -s orchestrator
Then inside Zellij, start Claude with access to all projects:
cd /home/dev/ObVault && claude --add-dir /home/dev/hc-evidence --add-dir /home/dev/hc-portal --add-dir /home/dev/hc-knowledge-mcp
This gives you Opus with read/write access to every project, the specs, infrastructure docs, and credentials.
Just close your terminal or SSH connection. Zellij keeps the session alive. Come back later:
ssh hc-central
zellij attach orchestrator
Claude is exactly where you left it. If the Claude process itself died, resume it:
claude -c # continues most recent conversation
Tell the orchestrator what you need. It dispatches @researcher to gather context.
> We need to fix the AR page grey flash when switching months. It's been an issue since April.
The orchestrator will use @researcher to search git history, Linear, and the knowledge base before planning. You can also just say:
> @researcher look into the AR month-switching issue in hc-evidence
Once research is done, the orchestrator writes a plan:
> Write a plan for this. Create a Linear ticket.
The orchestrator:
specs/plans/evidence/DRAFT-fix-ar-flash.mdHEL-710-fix-ar-flash.mdReview the plan. Ask questions, request changes. This is your 10% — make it count. When you're satisfied:
> Plan approved. Execute it.
The orchestrator dispatches @executor. You don't need to do anything.
> Execute HEL-710
Behind the scenes, the orchestrator runs something like:
cd /home/dev/hc-evidence && claude -p "Follow plan at .../HEL-710..." --dangerously-skip-permissions --output-format json
While it runs, you can:
When the executor finishes, it returns a JSON result to the orchestrator.
The orchestrator dispatches @reviewer, then presents findings:
> Verify HEL-710
The reviewer:
specs/tests/evidence/HEL-710-verification.mdYou review the report. If it passes:
> HEL-710 passes. Deploy it.
If issues are found:
> The reviewer found that month ordering is wrong. Fix it and re-verify.
The orchestrator dispatches @executor again with the specific fix.
The orchestrator dispatches @deployer:
> Deploy HEL-710 to production
The deployer reads the project-specific deploy template and follows it (git push + Coolify rebuild for Evidence, git push + Vercel for Portal, etc.).
The orchestrator:
specs/archive/evidence/HEL-710-fix-ar-flash.mdThe orchestrator can manage multiple tickets simultaneously. The key rule: never run two executors in the same project at the same time (they'd create conflicting file changes).
This is the cleanest pattern. Evidence and Portal can run simultaneously because they're separate codebases.
> Plan HEL-711 for Evidence (fix the 404 on Service Delivery)
[Orchestrator writes plan, you approve]
> Execute HEL-711. While that runs, let's plan something for Portal.
[Executor starts running in hc-evidence directory]
> I need to fix the session timeout issue in hc-portal. Research and plan it.
[Orchestrator researches and writes HEL-712 plan while HEL-711 executes]
> Plan looks good. Execute HEL-712.
[Now HEL-711 (evidence) and HEL-712 (portal) are both running autonomously]
> Check on HEL-711.
[Orchestrator checks the result — it finished while you were planning HEL-712]
> Verify HEL-711. Then check HEL-712.
If both tickets are for the same project, execute them one at a time:
> Execute HEL-713 (evidence fix A)
[Wait for it to finish]
> It passed. Now execute HEL-714 (evidence fix B)
You CAN plan HEL-714 while HEL-713 executes — just don't start executing both.
Infrastructure work (server config, firewalls, DNS) runs on different servers than code work. These can run in parallel:
> Execute HEL-705 (security — enable UFW on hc-central).
> At the same time, execute HEL-710 (Evidence AR fix).
This is safe because @infra-mgr works via SSH on the server, while @executor works on the local codebase.
For a day with multiple tickets, plan everything first:
> Here are 3 things I need done today:
> 1. Fix the Evidence 404 on Service Delivery
> 2. Add a new growth report for enrollment forecasting
> 3. Update the MCP server to add a new ingest source type
>
> Research and plan all three.
[Orchestrator plans all three]
> Plans look good. Execute #1 (evidence) and #3 (mcp) in parallel. Hold #2 until #1 finishes.
If you're in the Zellij orchestrator session, just ask:
> What's the status of HEL-711?
Check specs/plans/{project}/HEL-xxx.md — the orchestrator updates the plan with progress notes.
Check specs/tests/{project}/ for verification reports.
The orchestrator updates ticket status as work progresses:
| What you say | What happens |
|---|---|
Research the X issue in Y project |
@researcher gathers context |
Plan a fix for X |
@planner writes plan + Linear ticket |
Execute HEL-xxx |
@executor runs autonomously |
Verify HEL-xxx |
@reviewer checks + Playwright |
Deploy HEL-xxx |
@deployer pushes to production |
Check on HEL-xxx |
Orchestrator reports status |
Execute HEL-A and HEL-B in parallel |
Two claude -p calls simultaneously |
What's running right now? |
Orchestrator checks active processes |
Show me the plan for HEL-xxx |
Reads plan from specs/ |
Update infra docs for X |
@infra-mgr reads servers, updates docs |
Plan is cheap, execution is expensive. Spend time on the plan. A bad plan wastes 30 min of autonomous execution.
Check the verification template. Before approving a plan, glance at specs/templates/{project}/verify-{project}.md to make sure the acceptance criteria cover what matters.
Obsidian is your window. You can read plans, verification reports, and infra docs from anywhere. The orchestrator writes everything to ObVault.
Linear is your team's window. Even if nobody else uses the orchestrator, the Linear tickets show what's happening, what's blocked, and what's done.
If an executor gets stuck, the orchestrator will report the failure. You can either adjust the plan and re-execute, or jump into the project's Zellij session to debug manually.
Disconnect freely. Zellij + session resume means nothing is lost. Go to lunch. Come back. zellij attach orchestrator.