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

Forge Project Cleanup Plan 3

Scope: Update the four project bot prompts (project-runner, project-thinker, project-worker, project-evaluator) for compliance with Knowledge documents, work-product communication, standard handoff packets, globally unique project names, and user-configurable human gates.

Spec: Forge Project Cleanup Spec Prior plan: Plan 2

Task 1 — Inventory current project bot prompt content

Spec §6 requires that each project bot’s prompt records and configuration align with canonical Forge project Knowledge and Guides. Before updating, we need a complete inventory of current prompt content.

  1. For each of the four project bots, read the full prompt content:
    • project-runner (prompt id: prm_cmq8aja9i000301mzab1ezdxf)
    • project-thinker (prompt id: prm_cmqmm7nc1000401p1bx5lgj0g)
    • project-worker (prompt id: prm_cmqmmf7vr000b01p15biyasvf)
    • project-evaluator (prompt id: prm_cmqmkjxc6000u01o6ddc7p9kn)
  2. Use the readPrompt tool (from the prompts tool group) with versions: true to get the current version and content for each.
  3. For each bot, record:
    • Current prompt text (full content)
    • Current version number
    • Any child prompts attached
    • References to Erik_Todo, Agent_Todo, WIP, flat-file todos, or other patterns being replaced
    • References to Knowledge documents (which ones are mentioned, are they current)
    • Handoff pattern descriptions
    • Human gate behavior descriptions
    • Project naming conventions
  4. Save the inventory as Forge_Project_Cleanup_References_Bot_Prompt_Inventory.md in the project’s References/ subdirectory with status draft.

Task 2 — Update project-runner prompt

Spec §4, §5, §6, §11, §12 define work-product communication rules, standard handoff packets, bot compliance, globally unique project names, and user-configurable human gates. The project-runner is the orchestration bot and must enforce all of these.

  1. Read the current project-runner prompt using readPrompt.
  2. Update the prompt to include or enforce the following:
    • Work-product communication (Spec §4): The Runner must instruct spawned agents that substantive reasoning, decisions, findings, and verification results live in durable work-products. Conversation messages contain only concise routing context: department, project, current phase, responsible bot/agent role, skill, relevant work-product path or artifact link, status, next action, user decision needed if any, and spawned job id when applicable.
    • Standard handoff packets (Spec §5): The Runner uses the standard handoff packet fields when spawning agents or reporting to the user: Department, Project, Current Phase, Responsible Bot/Agent Role, Skill, Work-Product Path or Link, Status, Next Action, User Decision Needed, Spawned Job ID, Run/Cost Evidence.
    • Phase ownership (Spec §5): The Runner reads the Phase file, routes to the correct role, and records human gates through todos rather than flat files. A phase agent owns only its own phase state. The Runner does not advance unrelated phases or rewrite another role’s phase status.
    • Blocked phases (Spec §5): Blocked phases are represented by both a Phase file value and a todo item linked to the persisted report or work-product. The todo item is routing state; the report is substantive evidence.
    • Globally unique project names (Spec §11): The Runner enforces the {Department}/{ProjectShortName} canonical identifier and {ProjectSlug} filesystem convention at project creation time. If a user proposes a name without the department, the Runner qualifies it or asks the user to confirm.
    • User-configurable human gates (Spec §12): At project creation, the Runner presents the gate options (Vision_Eval, Research, Spec_Eval, Plan_Eval, Execute_Eval, Verify, Extract_Eval) and records the selected gates in the Phase file’s human_gates frontmatter list. Default gates: Spec_Eval, Plan_Eval, Verify. When a human gate is reached in Autonomous Mode, the Runner creates a todo item and stops. In Interactive Mode, it asks the user directly.
    • todos tool group (Spec §2): The Runner uses todos tools for human and agent gates, not flat files. The canonical user list is found by TodoList.ownerId and TodoList.group === "user".
    • No WIP (Spec §3): The Runner does not instruct agents to create, read, or resume from WIP files. Recovery is from Phase, Execute_State, durable work-products, persisted conversation/job metadata, git status, and todo items.
  3. Use updateBotPrompts to save the updated prompt.
  4. Create a prompt-version artifact using the artifacts tool with type application/vnd.prompt-version, recording the prompt id, new version number, and name.
  5. Build, commit, push.

Task 3 — Update project-thinker prompt

Spec §4, §5, §6 require that the Thinker communicates through durable work-products, uses standard handoff packets, and complies with Knowledge. The Thinker is responsible for Vision, Research, Spec, and Plan phases.

  1. Read the current project-thinker prompt using readPrompt.
  2. Update the prompt to include or enforce:
    • Work-product communication (Spec §4): The Thinker writes all substantive findings, decisions, requirements, and specifications to the appropriate durable work-product (Vision, Research, Spec, Plan). Conversation messages contain only concise routing context.
    • Standard handoff packets (Spec §5): When the Thinker completes a phase and hands off, it provides the standard handoff packet fields.
    • Phase ownership (Spec §5): The Thinker writes only its phase values to the Phase file: {Phase}_Started and {Phase}_Completed or {Phase}_Blocked.
    • todos tool group (Spec §2): When the Thinker needs a user decision (e.g., Research decision points), it creates a user-owned todo item with structured body content. When the Thinker needs to check whether a user decision has been made, it reads the todo item status.
    • No WIP (Spec §3): No WIP references in the Thinker’s instructions.
    • Globally unique project names (Spec §11): The Thinker uses the {Department}/{ProjectShortName} canonical identifier in all work-products and cross-references.
    • Human gates (Spec §12): The Thinker does not advance past a human gate; it completes its phase and the Runner handles gate enforcement.
    • Ambiguity handling (Spec §10): When the Thinker encounters an ambiguity, it records it in the durable work-product with affected area, decision needed, options considered, recommended option if any, responsible owner, status, and link to any related todo item. It does not resolve ambiguities by assumption.
  3. Use updateBotPrompts to save the updated prompt.
  4. Create a prompt-version artifact.
  5. Build, commit, push.

Task 4 — Update project-worker prompt

Spec §4, §5, §6 require that the Worker communicates through durable work-products, uses standard handoff packets, and complies with Knowledge. The Worker is responsible for Execute phases.

  1. Read the current project-worker prompt using readPrompt.
  2. Update the prompt to include or enforce:
    • Work-product communication (Spec §4): The Worker writes all implementation results, file changes, commands run, and errors encountered to the Execute_State and durable work-products. Conversation messages contain only concise routing context.
    • Standard handoff packets (Spec §5): When the Worker completes execution, it provides the standard handoff packet.
    • Phase ownership (Spec §5): The Worker writes only Execute_{N}_Started and Execute_{N}_Completed or Execute_{N}_Blocked to the Phase file.
    • todos tool group (Spec §2): When the Worker is blocked and needs a user decision, it creates a user-owned todo item. When it needs to flag follow-up work for another agent, it creates an agent/system-owned todo item.
    • No WIP (Spec §3): The Worker does not create, append to, or resume from WIP files. Recovery is from Execute_State, Phase, durable work-products, persisted conversation/job metadata, git status, and todo items.
    • Context boundary (Spec §4, Workflow §6): The Worker reads only the current Plan, Execute_State, and any referenced resources included in the Plan. It does NOT read Vision, Research, or Spec.
    • Run/cost evidence (Spec §5, §7): The Worker records available run/cost evidence in the Execute_State or project Runs file. If exact data is unavailable, it states that explicitly.
  3. Use updateBotPrompts to save the updated prompt.
  4. Create a prompt-version artifact.
  5. Build, commit, push.

Task 5 — Update project-evaluator prompt

Spec §4, §5, §6 require that the Evaluator communicates through durable work-products, uses standard handoff packets, and complies with Knowledge. The Evaluator is responsible for all Eval phases plus Verify.

  1. Read the current project-evaluator prompt using readPrompt.
  2. Update the prompt to include or enforce:
    • Work-product communication (Spec §4): The Evaluator writes all findings, verdicts, checklists, and item details to the durable eval report file. Conversation messages contain only concise routing context.
    • Standard handoff packets (Spec §5): When the Evaluator completes an evaluation, it provides the standard handoff packet.
    • Phase ownership (Spec §5): The Evaluator writes only its eval phase values to the Phase file.
    • todos tool group (Spec §2): When the Evaluator needs a user decision on a finding disposition, it creates a user-owned todo item. When it flags auto-fix results for review, it creates an informational todo item.
    • No WIP (Spec §3): No WIP references in the Evaluator’s instructions.
    • Work-product communication check (Spec §4): The Evaluator’s evaluation criteria include a check that no material decision, finding, requirement, plan, or verification result exists only in a conversation body and is missing from the durable artifact. A phase does not pass evaluation when this check fails.
    • Context boundary: The Evaluator reads only the documents specified in the Workflow §6 context boundary table for each eval phase.
    • Run/cost evidence (Spec §7): The Evaluator records available run/cost evidence in the eval report.
  3. Use updateBotPrompts to save the updated prompt.
  4. Create a prompt-version artifact.
  5. Build, commit, push.

Task 6 — Verify bot prompt compliance with Knowledge

Spec §6 acceptance criterion: audit shows zero unresolved discrepancies between the four project bot prompts and canonical Knowledge documents, or records explicit user-approved exceptions.

  1. For each of the four updated bot prompts, read the current prompt content.
  2. Read the canonical Knowledge documents: Forge/Forge_Project_Workflow.md, Forge/Forge_Project_User_Guide.md, Forge/Forge_Agent_Orchestration.md, Forge/Forge_Agent_Architecture.md.
  3. For each bot, compare the prompt against the Knowledge and record:
    • Every point where the prompt and Knowledge agree (compliance)
    • Every point where the prompt and Knowledge disagree (discrepancy)
    • Every point where the Knowledge requires something not mentioned in the prompt (gap)
  4. If discrepancies or gaps are found, fix the prompt to align with Knowledge (Knowledge is the default authority per Spec §6).
  5. If a discrepancy cannot be resolved in favor of Knowledge without user approval, record it as an ambiguity with a todo item for the user.
  6. Update the bot prompt inventory document with the compliance audit results.
  7. Build, commit, push.