Forge Project Cleanup Spec
The Forge project system is updated for the uvilo-mono environment as a durable, work-product-centered workflow. Active project instructions, prompts, skills, templates, workflow configuration, and user-facing guidance use the todos tool group for human and agent queues, no longer use WIP files, and remain aligned with canonical Forge Knowledge and the Forge Charter. Project names are globally unique and incorporate the department. Human gates are user-configurable per project.
1. Project System Scope and Canonical Source Set
The cleaned project system covers the active, non-archived Forge project workflow. Its canonical source set consists of published Forge Knowledge and Guides, project Skills and templates, project bot prompt records and bot configuration for project-runner, project-thinker, project-worker, and project-evaluator, workflow schedules or triggers that drive project phases, generated page/sidebar configuration for active project documentation, and durable project work-products in Forge/Projects/{Project}/.
Historical references in archived projects, completed audit history, and prior persisted evaluation reports are not active instructions. They may remain as history when they are clearly not used by the current workflow.
When canonical sources disagree, published Forge Knowledge and Guides are the default authority. Bot prompts, skills, templates, workflow config, and generated user-facing pages are aligned to the Knowledge unless a user-approved exception is recorded in a durable work-product.
2. todos Tool Group Replaces Flat-File Todo Workflows
The active project workflow uses the todos tool group instead of Erik_Todo.md, Agent_Todo.md, or any other flat-file todo queue.
The authoritative todos tools for the cleanup are:
| Tool | Target behavior in the project system |
|---|---|
createTodoList | Creates project, user, agent, or system todo lists when a durable queue/list is needed. |
findTodoLists | Finds existing todo lists through structured filters before creating or updating list state. |
searchTodoLists | Searches todo lists by text when the exact list id is unknown. |
readTodoList | Reads a todo list by id for inspection or evidence capture. |
updateTodoList | Updates list metadata or list-level state. |
trashTodoList | Soft-deletes or restores obsolete todo lists. |
createTodoItem | Creates human-decision, human-approval, blocked-phase, agent-follow-up, or informational todo items. |
findTodoItems | Finds existing todo items through structured filters before creating duplicates or updating state. |
searchTodoItems | Searches todo items by text when the exact item id is unknown. |
readTodoItem | Reads a todo item by id for inspection or evidence capture. |
updateTodoItem | Updates item state, ownership, metadata, body, or resolution information. |
trashTodoItem | Soft-deletes or restores obsolete todo items. |
The canonical user list can be found by TodoList.ownerId & TodoList.group === “user”.
Flat-file todo behaviors map to todos behavior as follows:
| Former behavior | Replacement behavior |
|---|---|
Append a blocked-phase or approval request to Erik_Todo.md. | Create or update a user-owned todo item with the project, phase, required decision/action, responsible owner, status, and durable work-product link (markdown-file). When the work-product is an eval, also link to the evaluated work-product. |
| Append an informational auto-disposition for Erik. | Create or update an informational user-owned todo item that records the disposition, rationale, affected work-product, and review path. Always provide markdown-file durable link. |
Append agent follow-up work to Agent_Todo.md. | Create or update an agent/system-owned todo item with project, phase, assigned bot or owner, required follow-up, status, and durable work-product link. |
| Use a flat-file checklist as a queue. | Use a todo list and todo items; list and item reads provide inspection evidence. |
| Mark a flat-file item done by editing markdown. | Update the corresponding todo item state and resolution metadata. |
| Remove stale flat-file todo content. | Trash or update obsolete todo items/lists while preserving durable project work-products and audit reports. |
Todo items created by project agents contain enough structured body content to make the requested action unambiguous: 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. Todo items do not duplicate substantive work-product content beyond what is needed to identify and route the action.
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.
3. WIP System Removed from Active Flow
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.
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.
Active WIP templates, WIP instructions in project Skills, WIP instructions in bot prompts, WIP references in user-facing Guides, WIP links in generated project pages/sidebar conventions, and active workflow WIP artifacts are removed or retired. Archived project history is excluded unless it is still referenced as an active instruction.
4. Durable Work-Product Communication
Project agents communicate substantive work through durable work-products. Vision, Research, Spec, Plans, Execute reports or changed files, Evals, Verification, Extract, Audit Results, Runs, and todo items are the persistent communication layer.
Conversation messages and spawned-agent messages contain concise routing context only. The standard routing context is: 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.
Substantive reasoning, requirements, decisions, findings, corrections, plan details, verification evidence, and approval records live in the appropriate work-product. A conversation may include substantive content only when asking a specific user decision question and only to the extent required for the user to choose.
Evaluation criteria for project phases include a work-product communication check. A phase does not pass evaluation when a material decision, finding, requirement, plan, or verification result exists only in a conversation body and is missing from the durable artifact.
5. Standard Handoff Packets and Phase Ownership
Every project handoff uses a standard packet with these fields:
| Field | Purpose |
|---|---|
| Department | Identifies the department root. |
| Project | Identifies the project folder. |
| Current Phase | Matches the current Phase: value in the project Phase file. |
| Responsible Bot / Agent Role | Identifies the bot or role receiving or completing the work. |
| Skill | Identifies the phase skill or project skill being used. |
| Work-Product Path or Link | Points to the canonical artifact for the phase or decision. |
| Status | States started, completed, blocked, evaluating, or decision-needed status. |
| Next Action | Describes the immediate routing step. |
| User Decision Needed | Records yes/no plus options when a human decision is required. |
| Spawned Job ID | Records spawned-agent job id when available. |
| Run / Cost Evidence | Links to the run summary or records that evidence is unavailable. |
The Phase file is the canonical state signal for lifecycle routing. A phase agent owns only its own phase state and writes only its phase values: {Phase}_Started, {Phase}_Completed, or {Phase}_Blocked. Agents do not advance unrelated phases or rewrite another role’s phase status. Runner orchestration reads the Phase file, routes to the correct role, and records human gates through todos rather than flat files.
Blocked phases are represented by both a Phase file value and a todo item linked to the persisted report or work-product that explains the block. The todo item is routing state; the report or work-product is the substantive evidence.
6. Project Bot Compliance with Knowledge
The project bot set consists of project-runner, project-thinker, project-worker, and project-evaluator. Each bot has inspectable prompt records and configuration that align with canonical Forge project Knowledge and Guides, especially the Forge Project Workflow and Forge Project User Guide.
Bot prompts express the same lifecycle, phase responsibilities, handoff rules, work-product communication rules, phase ownership rules, todo behavior, WIP removal, and evaluation expectations as the Knowledge. Discrepancies are resolved in favor of Knowledge unless a user-approved exception is recorded with rationale and an artifact link.
Prompt changes are inspectable by humans through prompt version records, prompt diff artifacts, or equivalent durable review evidence. The project system maintains an inventory of the active project bots, relevant prompt records, and the Knowledge documents each prompt is expected to satisfy.
7. Project Infrastructure Inventory and Verification Evidence
The cleaned system includes an inventory of every active project-system component:
- published project Knowledge and Guides;
- project Skills and skill templates;
- project work-product templates;
- project bot records, prompt records, and prompt versions;
- workflow schedules, Inngest functions, or phase triggers;
- todo lists/items used for human and agent gates;
- generated Astro/Starlight pages and sidebar entries for active project docs;
- lifecycle files, phase files, run logs, verification reports, and audit reports.
Verification evidence exists for each component type. Valid evidence includes file inspection results, search results showing removal of stale active references, prompt diff review, tool inventory or smoke-test output, generated site/sidebar inspection, lifecycle routing checks, build results, and documented manual checks where automated checks are unavailable.
The project records run and cost evidence for spawned project-agent work in the project Runs file or the relevant persisted report. If exact cost, token, or run metadata is unavailable, the report states that explicitly and records the available job/session context.
8. Lifecycle, Templates, Pages, and Sidebar Consistency
The active lifecycle remains the existing Forge project lifecycle from Create through Complete. The cleanup does not add new phases or new work-product types.
Project Skills, templates, Knowledge, Guides, prompts, workflow config, and generated pages use consistent phase names, phase ordering, work-product names, report names, and status values. User-facing documentation presents the lifecycle without obsolete WIP or flat-file todo implementation details.
Project page/sidebar output exposes active project work-products in a predictable location and omits retired WIP artifacts from active navigation. Page and sidebar changes are handled through the page-management workflow.
9. Forge Charter Alignment Controls
The project system contains a Charter alignment matrix for the active project workflow. The matrix records every relevant Forge Charter principle or constraint reviewed, the compliance status, the active evidence, any gap, and the correction or user decision that resolves the gap.
The cleaned workflow has no known unaddressed Charter violations. The workflow explicitly supports:
- stakeholder stewardship for customers, personnel, management, shareholders, and community when a project affects them;
- human sovereignty for material decisions;
- security and access-control review when a project touches sensitive data, privileged tools, or authorization boundaries;
- privacy-impact review when a project touches personal, customer, conversation, or organizationally sensitive data;
- accountability through non-empty or explicitly pending owner/approver fields and responsible todo ownership;
- transparency through durable Research, Spec, Plan, Eval, Verify, Extract, Audit, and Run evidence;
- prompt inspectability through prompt inventories and prompt-version review artifacts;
- cost efficiency through concise context boundaries, work-product links instead of duplicated content, and run/cost evidence capture.
10. Ambiguity and User Decision Handling
Ambiguities are not resolved by agent assumption. Each ambiguity is recorded in a durable work-product or persisted report with the affected area, decision needed, options considered, recommended option if any, responsible owner, status, and link to any related todo item.
Material decisions are routed to the user through the todos tool group with a link to the canonical work-product. Agent recommendations remain recommendations until the user decides, unless the decision is explicitly mechanical, reversible, and covered by a documented preference pattern.
No ambiguous project-system design decision is implemented without a recorded user decision or a recorded blocked status.
11. Globally Unique Project Names Incorporating Department
Project names must be globally unique across all departments. The project name incorporates the department so that the project can be identified unambiguously from its name alone.
The canonical/display project identifier is {Department}/{ProjectShortName}, where Department is the department folder name and ProjectShortName is a descriptive filesystem-friendly short name unique within that department. This mirrors the bot naming convention {group}/{handle}. For example, a cleanup project in the Forge department has canonical project identifier Forge/Project_Cleanup, not just Project_Cleanup.
Because / is a path separator, the canonical/display identifier is not used literally inside a single folder name or file name. Each project also has a filesystem-safe project slug, {ProjectSlug}, derived from the canonical identifier by replacing / with _ and preserving the remaining filesystem-safe characters. Example: Forge/Project_Cleanup has project slug Forge_Project_Cleanup.
The Project Create skill and the project-runner bot enforce this convention at project creation time. If a user proposes a name that does not include the department, the system qualifies it automatically or asks the user to confirm the {Department}/{ProjectShortName} canonical identifier and derived {ProjectSlug}.
The naming convention applies as follows:
- project identity, todo items, handoff packets, reports, and cross-references use the canonical/display project identifier
{Department}/{ProjectShortName}; - the project folder is
{Department}/Projects/{ProjectSlug}/; - the project Phase file is
{ProjectSlug}_Phase.md; - work-product file names use
{ProjectSlug}as the file-name prefix, for example{ProjectSlug}_Vision.md,{ProjectSlug}_Spec.md, and{ProjectSlug}_Execute_Eval_{N}.md.
When a template or work-product path uses {Project} inside a filesystem path or file name, it means the filesystem-safe {ProjectSlug}. Cross-department references use the full canonical project identifier, never the short name alone.
12. User-Configurable Human Gates
When a project is created, the user is asked which phases they want human gates after. The available gate points are:
| Gate Point | After Phase | Description |
|---|---|---|
| G1 | Vision_Eval | User reviews and approves the Vision before Research begins |
| G2 | Research | User reviews Research decisions before Spec is written |
| G3 | Spec_Eval | User reviews and approves the Spec before Planning begins |
| G4 | Plan_Eval | User reviews and approves Plans before Execution begins |
| G5 | Execute_Eval | User reviews execution results after each Execute_Eval cycle |
| G6 | Verify | User reviews verification results before Extract |
| G7 | Extract_Eval | User reviews extraction completeness before project is marked Complete |
The user’s selections are recorded in the existing project Phase file at {Department}/Projects/{ProjectSlug}/{ProjectSlug}_Phase.md; no separate human-gate work-product is added. The storage schema is a top-level YAML frontmatter list named human_gates:
human_gates contains zero or more of these exact gate-point values, each meaning “pause after this phase or eval completes”: Vision_Eval, Research, Spec_Eval, Plan_Eval, Execute_Eval, Verify, and Extract_Eval. The project-runner reads this Phase-file frontmatter list and routes accordingly: when a phase completes and that phase is listed in human_gates, the Runner pauses and creates a todo item for the user instead of automatically advancing.
The default human_gates value, written at project creation when the user does not specify preferences and used for legacy projects where the key is absent, is: G3 (Spec_Eval), G4 (Plan_Eval), G6 (Verify). These represent the minimum oversight points where user review is most valuable: approving the specification, approving plans before execution, and verifying the final result.
The Project Create skill and project-runner bot prompt are updated to:
- Present the gate options to the user at project creation time.
- Record the selected gates in the project configuration.
- Enforce the selected gates throughout the project lifecycle.
- Allow the user to modify their gate preferences at any time during the project.
When a human gate is reached and the Runner is in Autonomous Mode, the Runner creates a todo item for the user and stops — it does not proceed past the gate. When the Runner is in Interactive Mode, it asks the user directly.
13. Requirement Traceability
| Vision requirement | Spec coverage |
|---|---|
R1 — Replace Erik_Todo with todos group tools. | Sections 2, 5, 7, and 10 define the todos tool inventory, replacement behavior, handoff routing, evidence, and decision handling. |
| R2 — Remove WIP system. | Sections 3, 7, and 8 define WIP removal, recovery sources, inventory evidence, and page/sidebar cleanup. |
| R3 — Enforce work-product communication. | Sections 4, 5, 6, and 9 define durable communication, standard handoff packets, bot prompt compliance, and Charter-aligned transparency. |
| R4 — Verify all four project bots comply with Knowledge. | Section 6 defines bot compliance, prompt inspectability, discrepancy resolution, and inventory expectations. |
| R5 — Verify project system infrastructure. | Sections 7 and 8 define component inventory, evidence types, build/sidebar checks, lifecycle consistency, and run/cost evidence. |
| R6 — Align project flow with Forge Charter. | Section 9 defines the Charter alignment matrix and required controls for stewardship, security/privacy, accountability, inspectability, and cost evidence. |
| R7 — Flag ambiguities for user decision. | Section 10 defines ambiguity logging and todo-based user decision routing. |
| R8 — Globally unique project names incorporating department. | Section 11 defines the naming convention, enforcement at creation time, and cross-department reference rules. |
| R9 — User-configurable human gates. | Section 12 defines the available gate points, default gate set, recording mechanism, and enforcement by the Runner. |
14. Acceptance Criteria
The Spec is satisfied when active project Skills, Knowledge, Guides, bot prompts, templates, workflow configuration, generated pages/sidebar entries, and project files reflect the target state above; active references to flat-file todos and WIP recovery are absent; all four project bots match canonical Knowledge or have recorded user-approved exceptions; the project system inventory and verification evidence are complete; Charter alignment has no unaddressed gaps; every unresolved ambiguity is represented by a durable work-product entry and a todo item for the responsible user; project names follow the {Department}/{ProjectShortName} naming convention; and human gates are user-configurable with a documented default set and enforcement by the Runner.