published Visibility internal Owner erik@uvilo.com Approver _ Created _ Updated _

Forge Project User Guide

This is a comprehensive user guide to the Forge Project Workflow aimed at humans unfamiliar with the system. This guide should get you up and running quickly and easily.

1. Overview

Forge Projects is a project management and implementation system designed to turn ideas expressed as a brief list of requirements into fully researched, specified, planned, implemented, and verified documents, workflows, automations, and products. It’s what we will use to build strategic plans, marketing campaigns, presentations, autonomous agents, and even product features.

Forge automates the full lifecycle of a project — from identifying requirements through implementation, evaluation, and deployment. Agents handle the heavy lifting: drafting documents, running evaluations, executing plans, and verifying results. You provide direction at key decision points.

The Lifecycle

Every project follows the same 14-phase sequence:

Create — Create the project folder and a minimal set of required files
Vision — Define what needs to be built and why
Vision_Eval — Review the Vision document’s completeness and alignment with the process
Research — Take a deep dive to investigate best practices, implementation options, and identify decisions points
Spec — Describe the ideal final state in detail
Spec_Eval — Review the Spec for completeness and correctness, often using an AI model with different strengths
Plan — Break the Spec into a series of atomic, implementable Plans
Plan_Eval — Review the Plans for procedural correctness and completeness
Execute — Implement the tasks in a Plan
Execute_Eval — Evaluate whether the execution matches the Plan’s intent Repeat - Repeat the Execute/Execute_Eval loop for every Plan in the project
Verify — Verify the full project against the Vision and Spec
Extract — Move knowledge to permanent locations so all documentation and every agent skill is preserved after the project is archived
Extract_Eval — Review the extraction for completeness
Complete — Approve or archive the project

Every content-producing phase is followed by an evaluation phase that checks quality before proceeding. If an evaluation finds issues, the project loops back to the previous content-producing phase for revision, or calls on the human project owner to make decisions. For example:

If Vision_Eval finds issues → back to Vision
If Spec_Eval finds issues → back to Spec
If Plan_Eval finds issues → back to Plan
If Execute_Eval finds issues → back to Execute for the same Plan
If Extract_Eval finds issues → back to Extract

Projects can have multiple Plans (Plan 1, Plan 2, …). The Execute → Execute_Eval loop repeats within each Plan until Execute_Eval passes. After all Plans pass, the project moves to Verify. If Verify finds issues, a new Plan is created and the loop resumes. If Verify passes, the project moves to Extract and then Complete.

Auto-Fix Loop

Eval phases use an auto-fix loop before escalating to you: the Evaluator identifies findings, the Thinker fixes them, and the Evaluator re-evaluates. This iterates up to 3 rounds. You only see documents after the eval loop converges, not before. Only genuine ambiguities or trade-off decisions are escalated to you.

What Agents Do

Agents are specialized AI workers. Each phase is handled by the agent best suited for it:

Project Runner — Orchestrates phase transitions and agent dispatching — your project manager. Learns your preferences over time to make more dispositions autonomously.
Project Thinker — Does deep research, drafts Vision, Specs, and Plans; runs Extract
Project Worker — Executes Plans (implements tasks)
Project Evaluator — Evaluates all phases (Vision_Eval, Spec_Eval, Plan_Eval, Execute_Eval, Extract_Eval, Verify) — independent reviewer

You rarely interact with agents directly. The Project Runner constantly monitors projects and initiates phase transitions. When your input is needed, an item will be added to your todo list.

What You Do

Your primary role is review and approval at key gates — after the auto-fix loop has converged:

Write brief Vision and review them after Vision_Eval converges
Make Research decisions (which technologies, approaches, etc.)
Approve Specs and Plans after their respective _Eval phases converge
Decide what to do when evaluations find issues that the auto-fix loop couldn’t resolve
Review verification results

The system stops at these gates and will not proceed without your approval.

2. Getting Started

Creating a New Project

Tell the Forge Chat agent what you want to build. Use the /project-create command or describe the project in a conversation:

/project-create Build a notification system for the Uvilo platform

Forge will:

Qualify the project as {Department}/{ProjectShortName} and derive the filesystem slug {Department}_{ProjectShortName}
Ask which human gates you want, using Vision_Eval, Spec_Eval, Plan_Eval, and Verify by default
Check that the project identity is globally unique (across all departments, including Archived)
Create the project folder under the appropriate department’s Projects/ directory
Set up the initial README, AGENTS, and Phase documents, including the selected human_gates
Add a sidebar entry for the project when manual sidebar management is required

Working with an Existing Project

To pick up where you left off, reference the project by name:

Work on the Product/Taxonomy project

Forge reads the Phase file to determine the current state and resumes from there. If a phase is blocked, you’ll see a 🚫 item in your todo list.

Your Todo List

The project system uses a todos tool group to manage your pending items. When a phase needs your review or a blocker requires your attention, the Project Runner creates a todo item assigned to you. Each item includes the project name, what needs attention, and a link to the relevant artifact.

You can find your pending items by asking Forge:

What are my pending project items?

To resolve an item, tell Forge your decision in conversation — the system updates the todo item automatically.

3. Detailed Phase Descriptions

3.1 Create

What happens: The project folder is created with standard documents (README, AGENTS, Phase). The project identity is checked for global uniqueness. The Phase file records selected human gates in human_gates frontmatter.

Your involvement: Specify the department, project short name, owner, brief description, and human gate preference. If you do not specify gates, Forge uses the default gates: Vision_Eval, Spec_Eval, Plan_Eval, and Verify.

3.2 Vision

What happens: You enter a brief list of key requirements and the Project Thinker drafts the Vision document ({Project}_Vision.md), defining the project’s vision, requirements (R1, R2, …), success criteria (V1, V2, …), and scope boundaries. The draft then proceeds directly to Vision_Eval.

Your involvement: After Vision_Eval converges (auto-fix loop resolves issues), review the final Vision and approve.

Vision_Eval

What happens: A Project Evaluator evaluates the Vision for clarity, testability, non-contradiction, and completeness. If findings exist, an auto-fix loop runs (up to 3 rounds) — the Thinker fixes issues and the Evaluator re-evaluates. Results are saved to {Project}_Vision_Eval.md.

Your involvement: Only if the auto-fix loop cannot converge — review the remaining findings and decide how to proceed.

Research

What happens: A Project Thinker researches technologies, best practices, and trade-offs relevant to the project. Research decisions are documented.

Your involvement: Review and approve each research decision before the project proceeds.

Spec

What happens: A Project Thinker drafts the Specification document, defining what the project will produce (not how). The Spec addresses every Requirement and references Research findings. The draft then proceeds directly to Spec_Eval.

Your involvement: After Spec_Eval converges, review the final Spec and approve.

Spec_Eval

What happens: A Project Evaluator verifies that every Requirement is addressed, the Spec is self-contained, describes what not how, and preserves required content from Research. If findings exist, an auto-fix loop runs. Results are saved to {Project}_Spec_Eval.md.

Your involvement: Only if the auto-fix loop cannot converge.

Plan

What happens: A Project Thinker drafts one or more implementation Plans. Each Plan is a numbered, ordered sequence of tasks. The draft proceeds directly to Plan_Eval.

Your involvement: After Plan_Eval converges, review the final Plans and approve before implementation begins.

Plan_Eval

What happens: A Project Evaluator verifies self-containment, procedural correctness, ordering, and Spec coverage. If findings exist, an auto-fix loop runs. Results are saved to {Project}_Plan_Eval.md.

Your involvement: Only if the auto-fix loop cannot converge.

Execute

What happens: A Project Worker implements the tasks in the current Plan. State is tracked in {Project}_Execute_State_{N}.md. The Worker follows each task step by step.

Your involvement: None during execution. The Worker operates autonomously within the Plan’s scope.

Execute_Eval

What happens: A fresh Project Evaluator verifies the implementation against the Plan. If findings exist, an auto-fix loop runs first. Results are saved to {Project}_Execute_Eval_{N}.md — one file per Plan, with repeated runs appending new dated sections.

Your involvement: If the auto-fix loop cannot converge, review remaining findings. Decide whether to:

Fix — Fix the finding reported
Update — Don’t fix the implementation; update the Spec to match instead
Reject — I disagree with the finding; do nothing
Defer — Move this item to a later Plan

If Execute_Eval passes, the project proceeds to the next Plan. When all Plans pass, the project moves to Verify.

Verify

What happens: A Project Evaluator verifies the entire project — all Plans implemented, all Vision met, all documents consistent. Results are saved to {Project}_Verification.md with repeated runs appending new dated sections.

Your involvement: Review the verification report. If issues are found, a new Plan is created and the Execute → Execute_Eval loop resumes. If verification passes, the project proceeds to Extract.

Extract

What happens: A Project Thinker extracts any project-only artifacts (temporary documents, learnings) to their permanent locations. Temporary documents are cleaned up. The extraction proceeds directly to Extract_Eval.

Your involvement: None during extraction.

Extract_Eval

What happens: A Project Evaluator verifies that extraction is complete, correct, and leaves no stale project-only references. If findings exist, an auto-fix loop runs. Results are saved to {Project}_Extract_Eval.md.

Your involvement: Only if the auto-fix loop cannot converge.

Complete

What happens: The project is finalized. Two outcomes are possible:

Approve — Project stays in Projects/ with status: approved. All documents preserved.
Archive — Project moves to Archived/ with status: archived.

Your involvement: Choose approve or archive.

4. Agent Roles

Agent	Responsibility	Used In
Project Runner	Detects completed phases, determines next steps, dispatches agents or escalates to you. Learns your preferences over time to auto-dispose findings.	All phase transitions
Task Runner	Reads the agent todo list and dispatches the right SRP agent for each task	Individual task dispatch
Project Thinker	Drafts Vision, Specs, Plans; runs Extract	Vision, Research, Spec, Plan, Extract
Project Worker	Executes Plan tasks — writes code, modifies files, runs builds	Execute
Project Evaluator	Evaluates all phases — Vision_Eval, Spec_Eval, Plan_Eval, Execute_Eval, Extract_Eval, Verify	All _Eval phases, Verify
Page Manager	Creates, renames, moves, and deletes pages and sidebar entries	Sidebar updates during project lifecycle

How Agents Hand Off

Agent handoffs use the Phase file as the single state signal. The Phase file ({Project}_Phase.md) contains the current phase and its status:

Status Suffix	Meaning
`_Started`	Agent is in progress
`_Blocked`	Agent is blocked; Runner escalates to your todo list
`_Completed`	Phase finished; Runner may start the next phase
`_Paused`	User paused the project; Runner skips it entirely until you resume

The Project Runner reads the Phase file, determines the current phase, and dispatches the appropriate agent. When a phase completes, the Runner checks whether the next phase requires human approval or can proceed automatically.

Interactive vs Autonomous Mode

Project Runner has two operating modes:

Mode	When	Your Experience
Interactive	You hand off from Forge Chat (e.g., “create a project”, “approve this phase”)	You’re present in the conversation. The Runner asks you questions and gets real-time approvals.
Autonomous	The hourly cron fires, or an agent spawns the Runner automatically	The Runner works in the background. When it hits a human gate, it writes an item to your todo list and stops.

Most of your project interactions happen in Interactive Mode — when you tell Forge Chat to do something with a project, the conversation transfers to Project Runner and you steer it directly. Autonomous Mode keeps projects moving between your visits by advancing phases that don’t need your input and flagging the ones that do.

5. Human Gates

The system stops at specific points and waits for your approval before proceeding.

When You’ll Be Asked

Human gates are user-configurable at project creation. The default gates are:

Gate	After Phase	What You Review
G1 (default)	Vision_Eval	Final Vision document
G3 (default)	Spec_Eval	Final Spec document
G4 (default)	Plan_Eval	Final Plans
G6 (default)	Verify	Verification findings

Additional available gates:

Gate	After Phase	What You Review
G2	Research	Technology/approach choices
G5	Execute_Eval	Execution evaluation findings
G7	Extract_Eval	Extraction completeness

When you create a project, you can specify which gates you want. If you don’t specify, the default set (G1, G3, G4, G6) is used. You can modify your gate preferences at any time during the project.

When a human gate is reached:

Interactive Mode: The Runner asks you directly in conversation
Autonomous Mode: The Runner creates a todo item for you and stops — it does not proceed past the gate

How Approval Works

When your approval is needed, the Project Runner creates a todo item for you with a link to the document or report that requires review:

Project: which project needs your attention
Phase: which phase is waiting
Action needed: what decision or review is required
Work-product link: direct link to the document or report to review

To approve, tell Forge in conversation:

Approve the Vision for Product/Taxonomy

Product/Taxonomy Vision looks good, proceed to Research

To request changes:

The Product/Taxonomy Spec is missing R3 — go back to Spec

Auto-Dispositions

When the Runner has established a clear pattern from your past dispositions (e.g., you always reject formatting nits), it may auto-dispose similar findings without asking you. These appear as informational todo items in your todo list, recording the disposition, rationale, and affected work-product.

Blocked State

When an agent encounters a problem it can’t resolve, the Phase file is set to {Phase}_Blocked. The Project Runner detects this and creates a todo item for you with details about the blocker and a link to the relevant work-product or report.

Paused State

You can pause a project at any time by telling Forge to pause it. The Phase file is set to {Phase}_Paused. The Project Runner skips paused projects entirely — no agents are dispatched, no staleness checks, no todo items are created. The project sits idle until you tell Forge to resume it, which sets the phase back to {Phase}_Started.

6. Document and Report Reference

Every project produces a set of standard documents and persisted evaluation reports. These are the canonical artifacts — they’re what you review, what agents reference, and what the Forge Optimizer uses. In filenames below, {Project} means the filesystem-safe project slug, such as Product_Taxonomy.

Core Project Documents

Document	Purpose	Created In
`{Project}_Phase.md`	Current phase and status	Create
`README.md`	Project overview and entry point	Create
`AGENTS.md`	Agent responsibilities for this project	Create
`{Project}_Vision.md`	Vision, requirements, success criteria	Vision
`{Project}_Research.md`	Technology research and decisions	Research
`{Project}_Spec.md`	What the project will produce	Spec
`{Project}_Plan_{N}.md`	Implementation plan (one per plan)	Plan
`{Project}_Execute_State_{N}.md`	Task tracking for plan N	Execute
`{Project}_Learnings.md`	Obstacles and decisions (cleared during evaluation)	Create
`{Project}_Changelog.md`	File change manifest across all Plans	Create

Persisted Evaluation Reports

Report	Purpose	Phase
`{Project}_Vision_Eval.md`	Vision quality check	Vision_Eval
`{Project}_Spec_Eval.md`	Spec completeness and correctness check	Spec_Eval
`{Project}_Plan_Eval.md`	Plan procedural check	Plan_Eval
`{Project}_Execute_Eval_{N}.md`	Implementation evaluation for Plan N	Execute_Eval
`{Project}_Verification.md`	Full project verification	Verify
`{Project}_Extract_Eval.md`	Extraction completeness check	Extract_Eval
`{Project}_Runs.md`	Agent run summary with costs	Any time
`{Project}_Optimizer_Report.md`	Project-level optimizer analysis	Extract_Eval (auto) or manual

Each report includes: phase name, run identifier or date section, agent/session context, checklist/findings summary, pass/fail disposition, and next-step instruction.

Where Documents Live

Project documents are located at {Department}/Projects/{ProjectSlug}/, where {ProjectSlug} is the filesystem-safe form of {Department}/{ProjectShortName}. For example, the canonical project Product/Taxonomy uses slug Product_Taxonomy:

Product/Projects/Product_Taxonomy/
├── README.md
├── AGENTS.md
├── Product_Taxonomy_Phase.md
├── Product_Taxonomy_Vision.md
├── Product_Taxonomy_Research.md
├── Product_Taxonomy_Spec.md
├── Product_Taxonomy_Plan_1.md
├── Product_Taxonomy_Execute_State_1.md
├── Product_Taxonomy_Execute_Eval_1.md
├── Product_Taxonomy_Verification.md
├── Product_Taxonomy_Learnings.md
└── Product_Taxonomy_Changelog.md

Completed projects that are archived move to {Department}/Archived/{ProjectSlug}/.

7. Monitoring and Steering

Checking Project Status

Ask Forge at any time:

What's the status of the Product/Taxonomy project?

Forge reads the Phase file and Execute_State document to give you a current snapshot.

You can also browse projects on the documentation site at https://os.uvilo.com — each project has a sidebar entry with links to all its documents and reports.

Steering a Project

To change direction mid-project:

Request revisions — “Go back to Spec for the Product/Taxonomy project, R2 is wrong”
Add a new Plan — After Verify finds issues, a new Plan is created automatically. You can also request one manually.
Pause a project — Tell Forge to stop work on a project. The Phase file retains its state for later resumption.
Cancel a project — Use /project-delete to remove the project entirely.

The Forge Optimizer

The Forge Optimizer runs automatically once after Extract_Eval passes (Verdict: Approved). It analyzes all project conversations and saves findings to {Project}_Optimizer_Report.md in the project folder — a durable workproduct file that accumulates a new ## Run — {date} section on each run.

You can also run it manually at any time:

/forge-optimizer --project Product_Taxonomy

The Optimizer reviews all agent conversations for the project, using persisted report files and run summaries as context. It produces actionable findings for skills and prompts. In project mode, the report is saved as a workproduct file in the project folder.

Default analysis model is GLM 5.1. You can specify a different model for higher-judgment analysis:

/forge-optimizer --project Product_Taxonomy --model gpt-4o

Agent Run Summary

To see all agent runs for a project — including which models were used, tasks given, durations, token usage, and costs — check {Project}_Runs.md. This document lists:

Per-conversation: agent, model, task/message, duration, token usage per turn and total, cost
Total project cost across all conversations

The run summary is generated by the Forge Optimizer’s generate-runs script.

Manual Agent Spawning

If you need to trigger an agent directly:

/spawn Project Worker — Implement Plan 3 of the Product/Taxonomy project

Available agents: Project Runner, Task Runner, Project Thinker, Project Worker, Project Evaluator, Page Manager.

See the Forge Agents User Guide for full details on agent spawning, scheduling, and architecture.