Skip to content
Uvilo OS
archived Visibility internal Owner erik@uvilo.com Approver _ Created 2026-07-22 Updated 2026-07-25

Project Automation Plan 11

Scope: Redesign the project handoff and dispatch architecture from daily-poll to event-driven with an interactive mode, update all affected documents and agent configurations, and rewrite the User Guide to match.

Problem: The current architecture relies on a daily Project Runner poll to detect phase completions and dispatch the next agent. This creates up to 23 hours of idle latency between phases. Additionally, there is no mechanism for humans to interact with project-aware agents — Forge Chat is not project-aware, and SRP agents run under a service account with no human interaction. The User Guide (§2) incorrectly describes Forge Chat as the primary project worker.

Decisions made (user + Forge Chat, 2026-07-22):

  1. Agents hand off directly via spawn_agent when completing a phase (happy path — immediate)
  2. Project Runner runs hourly for reconciliation only (stalled/orphaned agents)
  3. No daily reconciliation — it serves no purpose
  4. Interactive mode uses LibreChat Agent Handoffs under the user’s account
  5. Autonomous mode uses spawn_agent under forge@uvilo.com
  6. Project Runner operates in both modes — no separate Project Orchestrator agent

Task 1 — Redesign Project Runner for dual-mode operation

Project Runner becomes the single project-aware agent, operating in two modes: Interactive (via Agent Handoffs from Forge Chat, under the user’s account) and Autonomous (via hourly cron or spawn_agent, under forge@uvilo.com). Same agent, same system prompt, same routing table.

  • Update Project Runner’s system prompt: project lifecycle phases, routing table, human gate points, when to use Agent Handoffs vs spawn_agent, when running interactively vs autonomously
  • Define the two invocation modes and how Project Runner detects which mode it’s in (conversational context from Forge Chat handoff vs triggered by cron/spawn_agent)
  • Tools: forge-discovery, uvilo-filesystem, forge-spawn (both modes)

Task 2 — Implement agent-to-agent handoff via spawn_agent

When an SRP agent completes a phase and no human gate is required, it must call spawn_agent to invoke the next agent in the routing table immediately — instead of writing _Completed and waiting for Project Runner.

  • Add handoff instructions to each SRP agent’s prompt: on phase completion, determine the next phase from the routing table, call spawn_agent with the appropriate agent_id and task prompt
  • If a human gate is required, write the user’s todo file and stop — do not spawn the next agent
  • The completing agent sets its own phase to _Completed before spawning — it never writes another phase’s status
  • Every SRP agent’s first procedural step: read the Phase file, confirm the current phase matches your role, write your phase to _Started. If the Phase file doesn’t match (e.g., you were spawned for Execute but the phase says Plan), stop and report
  • No agent ever writes a phase status other than its own

Task 3 — Redefine Project Runner to hourly reconciliation

Project Runner changes from daily dispatcher to hourly reconciler. It no longer handles happy-path dispatch — that’s done by completing agents. It only catches failures.

  • Update orchestrator/src/schedules.ts: change project_runner_daily cron from 0 6 * * * to 0 * * * * (hourly)
  • Update the task prompt: “Scan all active projects. For each project with Phase status _Started where the AgentJob is stale (no activity for 60 minutes), re-dispatch or escalate. For each project with Phase status _Completed where no next phase has been started, spawn the next agent. For each project with Phase status _Blocked, confirm the user’s todo entry exists.”
  • Update SCHEDULE_CONFIG key name from project_runner_daily to project_runner_hourly
  • Update orchestrator/src/inngest.ts function name and cron accordingly

Task 4 — Define the two-mode architecture in Orchestration Spec

Update the Orchestration Spec (§6, §10) and any related documents to reflect the two-mode architecture.

  • Add a new section defining Interactive Mode (Agent Handoffs, the user’s account) and Autonomous Mode (spawn_agent, forge@uvilo.com)
  • Update §6 (Project Runner): dual-mode agent — interactive entry point AND hourly reconciler; not just a cron dispatcher
  • Update §10 (Cron Scheduling): Project Runner schedule from daily to hourly, remove daily reconciliation references
  • Add routing table that specifies which phases are interactive vs autonomous
  • Remove any references to a separate Project Orchestrator agent

Task 5 — Rewrite the User Guide

§2 currently describes Forge Chat doing project work directly. Rewrite to reflect the two-mode architecture with Project Runner as the interactive entry point.

  • §2 (Getting Started): Creating a project and gathering requirements goes through Project Runner (via Forge Chat handoff), not Forge Chat directly
  • §4 (Agent Roles): Project Runner is the project-aware agent the user interacts with; clarify which agents the user interacts with vs which run autonomously
  • §4 (How Agents Hand Off): Rewrite — happy path is agent-to-agent via spawn_agent; reconciliation via hourly Project Runner; interactive work via Agent Handoffs from Forge Chat to Project Runner
  • §5 (Human Gates): Approvals handled by Project Runner (interactively), not Forge Chat
  • Ensure all references to “Forge Chat” doing project work are replaced with Project Runner

Task 6 — Update SRP agent prompts with handoff protocol

Each SRP agent’s prompt must include: the routing table, when to hand off via spawn_agent, when to stop and write the user’s todo file, and which phases are interactive vs autonomous.

  • Update Project Worker prompt: on Execute completion, spawn Project Evaluator; on _Blocked, write the user’s todo file and stop
  • Update Project Evaluator prompt: on Eval pass, if next phase is autonomous, spawn the next agent; if next phase requires human gate, write the user’s todo file and stop
  • Update Project Thinker prompt: on Vision/Spec/Plan drafting completion, spawn Project Evaluator; on Research completion, write the user’s todo file for decision and stop
  • Ensure all prompts reference the canonical routing table

Task 7 — Build, commit, push

All changes from Plan 11 must be built, committed, and pushed.

Run the build, stage all changes, commit with message Project Automation: Plan 11 — event-driven handoffs and interactive mode, and push to dev.