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 2

Scope: Remove the WIP system from the active project workflow, update document type definitions, recovery instructions, templates, sidebar conventions, and page/sidebar output.

Spec: Forge Project Cleanup Spec Prior plan: Plan 1

Task 1 — Inventory all active WIP references

Spec §3 requires that the active project workflow has no WIP file requirement. Project agents do not create, update, resume from, or ask users to inspect WIP files as part of normal phase execution or recovery. This task finds every such reference.

  1. Search all non-archived markdown files under Forge/ for the string WIP (case-sensitive, as a standalone term, not part of words like “swagger”). Exclude .internal/, node_modules/, dist/, .generated/, and Archived/ directories. Use: grep -rn '\bWIP\b' Forge/ --include='*.md' | grep -v '.internal' | grep -v 'node_modules' | grep -v 'dist' | grep -v '.generated' | grep -v 'Archived/'
  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 create, write, append, resume from, or inspect a WIP file as part of the active workflow
    • Document type definition — defines WIP as a document type in the project system
    • Template — a WIP template file
    • Historical/artifact — an existing WIP file in a project folder, or a historical mention
  3. Also list all existing WIP files in the repo: find Forge/ -name '*WIP*' -type f | grep -v '.internal' | grep -v 'Archived/'
  4. Record the complete inventory in Forge_Project_Cleanup_References_WIP_Inventory.md in the project’s References/ subdirectory with status draft.

Task 2 — Update Forge Project Workflow: remove WIP document type and recovery instructions

Spec §3 states that recovery state is reconstructed from the Phase file, current durable work-product, persisted evaluation or verification reports, Execute state files, saved conversation or AgentJob metadata, git status, and relevant todo items. The Workflow document currently defines WIP as a document type (§3 table and §4.10) and instructs agents to use WIP for crash recovery.

  1. Read Forge/Forge_Project_Workflow.md in full.
  2. In the Document Types table (§3), remove the WIP row. The table should no longer list WIP as a document type.
  3. Remove section §4.10 (WIP document definition) entirely.
  4. In section §4.8 (Execute_State), remove any references to WIP as a companion document. The Execute_State section should stand alone.
  5. In section §4.9 (Learnings), remove any references to WIP.
  6. In the Agent Context Boundaries table (§6):
    • For the Execute row, remove WIP from “Must Read” and “Writes” columns. The Execute row becomes: Must Read = “Plan (current), Execute_State (current)”; Writes = “Work-products, Execute_State (current), Phase”.
    • For the Execute_Eval row, remove WIP from “Must NOT Read” column.
    • For other rows, remove any WIP references.
  7. In the sidebar convention (§10), remove item 16 (WIP) from the canonical order. Renumber subsequent items.
  8. Add a new subsection or paragraph explaining the recovery contract from Spec §3: “Recovery state is reconstructed from the Phase file, the current durable work-product, persisted evaluation or verification reports, Execute state files where applicable, saved conversation or AgentJob metadata, git status, and relevant todo items. These sources form the recovery contract for interrupted or failed work.”
  9. Update the lastUpdated frontmatter field.
  10. Build, commit, push.

Task 3 — Update project Skills that reference WIP

Spec §3 requires that active WIP instructions in project Skills be removed. The following Skills contain WIP references: Project_Execute/SKILL.md, Project_Plan/SKILL.md, Project_Plan_Eval/SKILL.md, Project_Verify/SKILL.md, Project_Complete/SKILL.md, Project_Archive/SKILL.md, Project_Extract_Eval/SKILL.md.

  1. For each Skill file identified in Task 1 that contains active instructional references to WIP:
    • Read the full SKILL.md.
    • Remove or replace each active instructional reference to WIP:
      • Where the Skill instructs creating a WIP file, remove that instruction.
      • Where the Skill instructs appending to WIP during execution, remove that instruction.
      • Where the Skill instructs resuming from WIP after a crash, replace with: “Recover from the Phase file, current Execute_State, durable work-products, persisted conversation/AgentJob metadata, and git status.”
      • Where the Skill instructs clearing WIP at session end, remove that instruction.
      • Where the Skill references WIP in the context boundary rules, remove the WIP reference.
    • Ensure the Skill still makes sense after WIP removal — no dangling references or incomplete instructions.
  2. After all Skills are updated, run a verification search: grep -rn '\bWIP\b' Forge/Skills/ --include='*.md' | grep -v '.internal' | grep -v 'Archived/'. The result should contain zero active instructional references to WIP in project Skills.
  3. Build, commit, push.

Task 4 — Update Forge Agent Architecture and other Knowledge documents

Spec §3 and §8 require removal of WIP from active flow and consistency across all Knowledge documents. Forge/Forge_Agent_Architecture.md and Forge/Forge_Document_Structure.md contain WIP references.

  1. Read Forge/Forge_Agent_Architecture.md in full.
  2. Remove or replace every active instructional reference to WIP:
    • Where the document describes WIP as a crash-recovery mechanism, replace with the recovery contract from Spec §3 (Phase file, durable work-products, Execute_State, persisted conversation/AgentJob metadata, git status, todo items).
    • Where the document instructs agents to use WIP, remove that instruction.
  3. Read Forge/Forge_Document_Structure.md in full.
  4. Remove any WIP references from the document structure definitions.
  5. Update lastUpdated frontmatter fields.
  6. Build, commit, push.

Task 5 — Remove WIP template and retire active WIP files

Spec §3 requires that active WIP templates, WIP instructions, and active WIP artifacts be removed or retired. The WIP template exists at Forge/Skills/Project_Create/templates/WIP_Template.md.

  1. Trash Forge/Skills/Project_Create/templates/WIP_Template.md using the forge-filesystem trash tool.
  2. For each active WIP file found in Task 1 (e.g., Forge/Projects/Container_Base_Image/Container_Base_Image_WIP.md, Forge/Projects/Container_Base_Image/Container_Base_Image_WIP_2.md, Forge/Output/Output_WIP.md):
    • Read the file to understand its content.
    • If the file contains actionable state that should be preserved, migrate the relevant information to the appropriate durable work-product (Execute_State, Phase file, or todo items).
    • Trash the WIP file using the forge-filesystem trash tool.
  3. Verify the WIP template and active WIP files are removed from directory listings.
  4. Build, commit, push.

Task 6 — Update sidebar convention and page output

Spec §8 requires that project page/sidebar output exposes active project work-products in a predictable location and omits retired WIP artifacts from active navigation.

  1. Check the current sidebar configuration for any WIP-related entries. Search: grep -rn 'WIP' .internal/ --include='*.yml' --include='*.yaml' --include='*.json' | head -20 (this is build output, so only check to understand what the generated sidebar looks like).
  2. If the sidebar configuration or page generation logic (in Skills or templates) includes WIP entries, remove them.
  3. Run cd .internal && pnpm run build to verify the build still passes after WIP removal.
  4. Record the build result as evidence.
  5. Build, commit, push.

Task 7 — Verify no remaining active WIP references

Spec §3 acceptance criterion: active project Skills, Knowledge, Guides, bot prompts, templates, workflow configuration, generated pages/sidebar entries, and project files contain no instructions to create, update, resume from, or ask users to inspect WIP files as part of normal phase execution or recovery.

  1. Run a comprehensive search across all non-archived files in Forge/: 
    grep -rn '\bWIP\b' 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 create/write/append/resume/inspect a WIP file → must be fixed
    • Historical/migration context — mentions WIP as a past practice → acceptable if clearly not an active instruction
    • This project’s own documents — the Forge_Project_Cleanup project itself references WIP as the thing being removed → acceptable
  3. Fix any remaining instructional references found.
  4. Update the WIP inventory document with the final verification results.
  5. Build, commit, push.