Skip to content
Uvilo OS
published Visibility internal Owner erik@uvilo.com Approver _ Created _ Updated _

Project Plan Eval

When to Use

After writing Plans, before presenting for approval. Run by a Project Evaluator — not the same agent who wrote the Plans.

Inputs

  • Project path ({Dept}/Projects/{Project}/)
  • Vision document
  • Spec document
  • All Plan documents

Context Boundary

Read only: Vision, Spec, and all Plans. No Research, Execute_State, or Learnings. The Spec is the sole source of detailed requirements — Research is a historical document that should not be read by later phases.

Prerequisite

HARD GATE: If you are in the same session that wrote the Plans, STOP. Tell the user: “Plan evaluation requires an independent reviewer — please start a new conversation and run Plan Eval there.” Do NOT proceed with evaluation.

Phase Names

  • Start: Plan_Eval_Started
  • End: Plan_Eval_Completed

Checklist

  1. Self-contained — an implementing agent reading only the Plan and Execute_State could complete every task without consulting Vision or Spec. If a task forces the implementer to look elsewhere, that is a defect
  2. Procedural, not declarative — every task describes how to build, step by step, not what the target state is. Behavioral descriptions belong in the Spec
  3. Single session — each Plan covers work completable in one focused agent session. Flag if scope is too broad
  4. Spec coverage — taken together, all Plans cover every section and requirement in the Spec. No Spec section is unaccounted for
  5. No gaps or overlaps — no missing work between Plans and no redundant work across Plans
  6. Ordered — Plan sequence respects dependencies; each Plan’s prerequisites are satisfied by earlier Plans. Within each Plan, tasks are ordered with no forward references
  7. Task quality — every task has a context quote block referencing the Spec section, and procedural steps that are actionable and specific enough to execute without ambiguity
  8. No checkboxes — Plans do not contain checkboxes; that is the Execute_State’s role
  9. Planning scope rule — (a) When revising plan documents during planning, a Plan only prescribes edits to itself (and its matching Execute_State if it exists), plus Vision and Spec when changes there are required. No Plan directs creation, modification, or deletion of any other file. (b) Implementation plans that direct edits to files explicitly named in their tasks are correct and should not be flagged as a defect — the scope rule restricts planning-time revisions, not implementation-time edits
  10. Testable output — each Plan’s output can be verified before later Plans are implemented
  11. File structure — each Plan is a separate file named {Project}_Plan_{N}.md, with N sequential starting at 1. There is exactly one Plan per file. A single file containing multiple Plans (e.g., {Project}_Plan.md holding Plan 1, Plan 2, … together) is a defect, even if the content is otherwise correct. A single-plan project uses {Project}_Plan_1.md. Verify this first — if multiple Plans share one file, reject on file structure before evaluating content further

Procedure

  1. Read the Spec, Vision, and all Plan documents. Enumerate the {Project}_Plan_*.md files in the project folder: confirm each is a separate file named {Project}_Plan_{N}.md (N sequential from 1). If multiple Plans are combined into one file (e.g., a bare {Project}_Plan.md), raise checklist item 11 as a file-structure defect and stop content evaluation until corrected
  2. Update {Project}_Phase.md: set Phase: Plan_Eval_Started
  3. Build, commit, push
  4. Run each checklist item against each Plan individually and across all Plans collectively, marking ✅ or ⚠️ with a brief note
  5. Format findings using Forge/Forge_Project/Skills/Project_Create/templates/Plan_Eval_Template.md:
    • Replace variables with project values
    • No findings: Set Verdict to Approved, omit the Items table
    • Findings exist: Set Verdict to Rejected or Conditionally Approved, populate Items and Resolution Log
  6. Write findings to {Project}_Plan_Eval.md (create or overwrite)
  7. Add sidebar entry for the report by spawning the Page Manager bot via spawnAgent with { botGroup: 'forge', botHandle: 'page-manager' } (placed under the project’s documents group)
  8. Build, commit, push
  9. If findings exist — auto-fix loop:
    • Direct the Thinker to fix the specific findings in the Plan documents
    • Re-evaluate after fixes; iterate up to 3 rounds
    • Only escalate to the user when Thinker and Evaluator cannot converge (after 3 rounds, or when findings involve genuine ambiguity or trade-off decisions)
    • Update {Project}_Phase.md: set Phase: Plan_Started (return to Plan for revision), then back to Plan_Eval_Started when revision is complete If no findings (or auto-fix converged): Update {Project}_Phase.md: set Phase: Plan_Eval_Completed
  10. Update frontmatter status to approved in all Plan documents and the Plan_Eval report
  11. Build, commit, push

Rules

  • Flag only real issues — not theoretical ones. If a checklist item passes on its own terms, mark ✅ even if the pattern could be a problem in other contexts
  • The planning scope rule (item 9) distinguishes two cases: (a) during planning, Plans should only revise Plan+Execute_State documents (plus Vision/Spec if needed) — directing edits to other files is a defect; (b) during implementation, Plans that name specific files in their tasks are correct — the scope rule does not restrict implementation-time file edits
  • The report file is durable review history — it persists across reruns and is not deleted when the project returns to Plan
  • An independent reviewer must run this phase — never the same agent/session that wrote the Plans
  • The auto-fix loop should resolve most findings without user involvement. Only genuine ambiguities or creative decisions require human input