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 1

Scope: Replace Erik_Todo and Agent_Todo flat-file workflows with the todos tool group across all active Forge Knowledge documents, Guides, and project Skills.

Spec: Forge Project Cleanup Spec Prior plan: None

Task 1 — Inventory all active Erik_Todo and Agent_Todo references

Spec §2 requires that active project Skills, Knowledge, Guides, bot prompts, templates, workflow config, and user-facing pages contain no instructions to write, append, poll, or maintain Erik_Todo.md or Agent_Todo.md as active workflow state. This task finds every such reference.

  1. Search all non-archived markdown files under Forge/ for the strings Erik_Todo, Agent_Todo, Erik_Todo.md, and Agent_Todo.md. Exclude .internal/, node_modules/, dist/, .generated/, and Archived/ directories.
  2. For each match, record: file path, line number, surrounding context (2 lines before and after), and whether the reference is instructional (tells an agent or user to read/write/append/poll the file) vs. historical (mentions it as a past practice or migration context).
  3. Also search for the flat-file todo output files themselves: Forge/Output/Erik_Todo.md and Forge/Output/Agent_Todo.md. Record their existence and content.
  4. Record the complete inventory in a References/ subdirectory of the project folder as Forge_Project_Cleanup_References_Todo_Inventory.md with status draft.

Task 2 — Update Forge Project Workflow Knowledge document

Spec §2 and §5 define the todos tool group replacement and standard handoff packets. The Forge Project Workflow (Forge/Forge_Project_Workflow.md) is the canonical Knowledge document for the project lifecycle and currently references Erik_Todo and flat-file todo patterns.

  1. Read Forge/Forge_Project_Workflow.md in full.
  2. Identify every section that references Erik_Todo, Agent_Todo, or flat-file todo/checklist patterns as active workflow instructions.
  3. Replace each active instructional reference with the corresponding todos tool group behavior from Spec §2. Specifically:
    • Where the document instructs agents to append to Erik_Todo.md for blocked phases or approval requests, replace with: “Create or update a user-owned todo item using createTodoItem or updateTodoItem with project, phase, required decision/action, responsible owner, status, and a durable work-product link (markdown-file artifact).”
    • Where the document instructs agents to append informational auto-dispositions, replace with: “Create or update an informational user-owned todo item that records the disposition, rationale, affected work-product, and review path. Always provide a markdown-file durable link.”
    • Where the document instructs agents to append follow-up work to Agent_Todo.md, replace with: “Create or update an agent/system-owned todo item using createTodoItem or updateTodoItem with project, phase, assigned bot or owner, required follow-up, status, and durable work-product link.”
    • Where the document instructs using a flat-file checklist as a queue, replace with: “Use a todo list and todo items; list and item reads provide inspection evidence.”
    • Where the document instructs marking a flat-file item done by editing markdown, replace with: “Update the corresponding todo item state and resolution metadata using updateTodoItem.”
    • Where the document instructs removing stale flat-file todo content, replace with: “Trash or update obsolete todo items/lists using trashTodoItem or trashTodoList while preserving durable project work-products and audit reports.”
  4. Add a new subsection under the relevant section that documents the todos tool inventory table from Spec §2 (the 12 tools: createTodoList, findTodoLists, searchTodoLists, readTodoList, updateTodoList, trashTodoList, createTodoItem, findTodoItems, searchTodoItems, readTodoItem, updateTodoItem, trashTodoItem).
  5. Add the flat-file-to-todos replacement mapping table from Spec §2.
  6. Ensure the handoff packet fields from Spec §5 are documented in the appropriate section (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).
  7. Update the lastUpdated frontmatter field to today’s date.
  8. Do NOT change the lifecycle phases, phase names, or document type definitions (those are addressed in Plan 2).
  9. Build, commit, push.

Task 3 — Update Forge Project User Guide

Spec §2 and §12 require that user-facing documentation present the lifecycle without obsolete flat-file todo implementation details and use todos tool semantics. The User Guide (Forge/Forge_Project_User_Guide.md) currently instructs users about Erik_Todo.

  1. Read Forge/Forge_Project_User_Guide.md in full.
  2. Replace every active instructional reference to Erik_Todo.md or Agent_Todo.md with the corresponding todos tool group behavior, using user-facing language (not tool-call syntax). For example:
    • “Your pending decisions appear as todo items assigned to you” instead of “Check Erik_Todo.md for pending items.”
    • “The project system creates a todo item for your review” instead of “An entry is appended to Erik_Todo.md.”
  3. Remove any instructions that tell users to manually edit Erik_Todo.md or Agent_Todo.md.
  4. Add a brief user-facing explanation of the todos system: how users receive todo items for decisions, how they can find their pending items, and how they mark items resolved.
  5. Ensure the human gates section reflects Spec §12: user-configurable gates at project creation, default gates (Spec_Eval, Plan_Eval, Verify), and how gates are enforced.
  6. Update the lastUpdated frontmatter field.
  7. Build, commit, push.

Task 4 — Update Forge Agent Orchestration document

Spec §2 and §4 require that agent orchestration instructions use todos tools instead of flat-file todos and that agents communicate through durable work-products. The Orchestration document (Forge/Forge_Agent_Orchestration.md) currently documents Erik_Todo and Agent_Todo as active workflow mechanisms.

  1. Read Forge/Forge_Agent_Orchestration.md in full.
  2. Replace every active instructional reference to Erik_Todo.md or Agent_Todo.md with the corresponding todos tool group behavior from Spec §2.
  3. Update any sections that describe how agents communicate with users or other agents to reflect Spec §4: agents communicate substantive work through durable work-products; conversation messages contain concise routing context only (department, project, current phase, responsible bot/agent role, skill, relevant work-product path or artifact link, status, next action, user decision needed if any, spawned job id when applicable).
  4. Update the lastUpdated frontmatter field.
  5. Build, commit, push.

Task 5 — Update Forge Agents User Guide

The Agents User Guide (Forge/Forge_Agents_User_Guide.md) references Erik_Todo and must be updated to reflect the todos tool group.

  1. Read Forge/Forge_Agents_User_Guide.md in full.
  2. Replace every active instructional reference to Erik_Todo.md or Agent_Todo.md with the corresponding todos tool group behavior.
  3. Update the lastUpdated frontmatter field.
  4. Build, commit, push.

Task 6 — Update project Skills that reference Erik_Todo or Agent_Todo

Spec §2 requires that active project Skills contain no instructions to write, append, poll, or maintain Erik_Todo.md or Agent_Todo.md. The following Skills contain such references: Project_Flow/SKILL.md, Project_Verify/SKILL.md, Project_Execute_Eval/SKILL.md, Project_Extract_Eval/SKILL.md.

  1. For each Skill file identified in Task 1 that contains active instructional references to Erik_Todo or Agent_Todo:
    • Read the full SKILL.md.
    • Replace each active instructional reference with the corresponding todos tool group behavior from Spec §2, using the exact tool names (createTodoItem, updateTodoItem, findTodoItems, etc.).
    • Where the Skill instructs creating a human gate or approval request via flat file, replace with createTodoItem with the structured body content required by Spec §2 (department, project, phase, requesting bot or agent role, responsible human or agent owner, requested action or decision, options when a decision is needed, status, due/priority if known, and a link/path to the canonical work-product or persisted report).
    • Where the Skill instructs checking or polling a flat file for user decisions, replace with findTodoItems or readTodoItem to check the status of the relevant todo item.
    • Where the Skill instructs marking a flat-file item done, replace with updateTodoItem to set the item state to resolved.
  2. After all Skills are updated, run a verification search: grep -rl 'Erik_Todo\|Agent_Todo' Forge/Skills/ --include='*.md' | grep -v Archived | grep -v .internal. The result should contain zero active instructional references (only historical mentions if any).
  3. Build, commit, push.

Task 7 — Retire flat-file todo output files

Spec §2 requires that flat-file todo behaviors be replaced. The output files Forge/Output/Erik_Todo.md and Forge/Output/Agent_Todo.md are the actual flat-file queues that must be retired.

  1. Read Forge/Output/Erik_Todo.md and Forge/Output/Agent_Todo.md to understand their current content.
  2. If either file contains actionable items that have not been migrated to the todos system, create corresponding todo items using createTodoItem for each remaining actionable item before retiring the file.
  3. Trash both files using the forge-filesystem trash tool (not bash rm).
  4. Verify the files are removed from the directory listing.
  5. Build, commit, push.

Task 8 — Verify no remaining active Erik_Todo or Agent_Todo references

Spec §2 acceptance criterion: active project Skills, Knowledge, Guides, bot prompts, templates, workflow configuration, generated pages/sidebar entries, and project files contain no instructions to write, append, poll, or maintain Erik_Todo.md or Agent_Todo.md as active workflow state.

  1. Run a comprehensive search across all non-archived files in Forge/: 
    grep -rn 'Erik_Todo\|Agent_Todo' Forge/ --include='*.md' | grep -v '.internal' | grep -v 'node_modules' | grep -v 'dist' | grep -v '.generated' | grep -v 'Archived/'
  2. For each remaining match, classify it as:
    • Instructional — tells an agent or user to read/write/append/poll the file → must be fixed
    • Historical/migration context — mentions it as a past practice or migration source → acceptable if clearly not an active instruction
    • This project’s own documents — the Forge_Project_Cleanup project itself references Erik_Todo as the thing being replaced → acceptable
  3. Fix any remaining instructional references found.
  4. Record the verification results in the project’s References/Forge_Project_Cleanup_References_Todo_Inventory.md, updating it to include the final verification pass.
  5. Build, commit, push.