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

Forge Project Workflow

Forge Project Workflow is a standardized lifecycle for projects — directed and supervised by people and executed by agents. It optimizes for agent context efficiency, clean separation between phases, and systematic knowledge extraction at project end so the system gets smarter over time.

1. Project Lifecycle

flowchart TD
    A[1. Create<br><small>Agent creates project folder</small>] --> B[2. Vision<br><small>User describes needs</small>]
    B --> B2[3. Vision_Eval<br><small>Project Evaluator validates Vision</small>]
    B2 -->|Findings| B
    B2 --> C[4. Research<br><small>Agent proposes solutions, user makes decisions</small>]
    C --> D[5. Spec<br><small>Agent creates Spec</small>]
    D --> D2[6. Spec_Eval<br><small>Project Evaluator validates Spec</small>]
    D2 -->|Findings| D
    D2 --> E[7. Plan<br><small>Agent breaks Spec into one or more Plans</small>]
    E --> E2[8. Plan_Eval<br><small>Project Evaluator validates Plans</small>]
    E2 -->|Findings| E
    E2 --> F[9. Execute<br><small>Agent executes one Plan</small>]
    F --> G[10. Execute_Eval<br><small>Project Evaluator evaluates execution</small>]
    G -->|Issues found| F
    G -->|Repeat for remaining Plans| F
    G --> I[11. Verify<br><small>Project Evaluator verifies final result against Spec</small>]
    I -->|Issues found → new Plan| F
    I --> J[12. Extract<br><small>Agent extracts knowledge, skills, and documentation</small>]
    J --> J2[13. Extract_Eval<br><small>Project Evaluator validates extraction</small>]
    J2 -->|Findings| J
    J2 --> K[14. Complete<br><small>Project is marked approved, published, or archived</small>]

Phase 1: Create

Create the project folder and initial files using the project-create skill. Minimum viable project: README.md, AGENTS.md, and {project}_Phase.md.

Phase 2: Vision

Capture the project’s Vision to realize or Problem to solve, give minimal necessary background, point-form requirements and verification criteria. Primarily human-written; the agent organizes and clarifies. See §4.4. README.md and AGENTS.md are updated.

Phase 3: Vision_Eval

A Project Evaluator validates Vision for clarity, testability, non-contradiction, and completeness. Results are persisted to {Project}_Vision_Eval.md. If findings exist, an auto-fix loop runs (up to 3 rounds) before escalating to the user. If the loop converges, the user reviews the final document for approval.

Phase 4: Research

Investigate implementation options and best practices. When multiple options exist, recommend the best with rationale. Present decision points clearly for user approval. All decisions must be approved before creating a Spec. See §4.5.

Phase 5: Spec

Convert approved decisions into a declarative description of the project’s ideal final state. The Spec describes what the system is, not how to build it. See §4.6.

Phase 6: Spec_Eval

A Project Evaluator validates the Spec against its Vision and Research — every Requirement is addressed, the Spec is self-contained, describes what not how, and preserves required content. Results are persisted to {Project}_Spec_Eval.md. If findings exist, an auto-fix loop runs (up to 3 rounds) before escalating to the user. If the loop converges, the user reviews the final document for approval.

Phase 7: Plan (one or more)

Break the Spec into one or more atomic Plans. Each Plan covers work implementable in a single focused agent session. Plans convert the declarative Spec into procedural steps. See §4.7.

Phase 8: Plan_Eval

A Project Evaluator validates Plans for self-containment, procedural correctness, ordering, and Spec coverage. Results are persisted to {Project}_Plan_Eval.md. If findings exist, an auto-fix loop runs (up to 3 rounds) before escalating to the user. If the loop converges, the user reviews the final Plans for approval.

Phase 9: Execute

When execution of a Plan begins, a matching Execute_State document is created with a todo list. The agent executes step by step: Checking off items in the Execute_State → Recording obstacles and solutions in the Learnings file. See §4.8, §4.9.

Phase 10: Execute_Eval

A fresh Project Evaluator (new session) evaluates whether the Plan was executed correctly by comparing the implementation to the Plan’s intent. Produces a list of defects, variances, and learnings. Results are persisted to {Project}_Execute_Eval_{N}.md. If issues are found and the disposition is fix, the project returns to Execute for the same Plan — there is no separate Fix phase. See §8.1.

Phase 11: Repeat

Repeat phases 9–10 for each remaining Plan. Later Plans may be revised based on evaluation of earlier Plans before execution begins.

Phase 12: Verify

A fresh Project Evaluator verifies the complete implementation against Vision and Spec. If substantial issues are found, a new Plan is created and the project loops back to Execute. Otherwise, proceeds to Extract.

Phase 13: Extract

A fresh agent extracts knowledge and skills to their permanent locations. See §8.3.

Phase 14: Extract_Eval

A Project Evaluator validates that extraction is complete, correct, and leaves no stale project-only references. Results are persisted to {Project}_Extract_Eval.md. If findings exist, an auto-fix loop runs before escalating to the user.

Phase 15: Complete

Archive or publish the project. See §9.

2. Project Skills

The project lifecycle is implemented in a series of skills in Forge/Forge_Project/Skills/.

Every project skill follows this basic workflow, adapted to the phase’s needs:

Read → Create page from Template → Update Phase → Do Work → Set status to review → Update sidebar → Present to user → Repeat until approved → Set status to approved → Update Phase

Build, commit, push after every change.

Skill	Description
Project Flow	Detect current phase and dispatch to the correct skill
Project Create	Create the project folder and initial files
Project Vision	Capture the project’s vision, requirements, and success criteria
Project Research	Investigate implementation options and present decisions for approval
Project Spec	Convert approved decisions into a declarative spec
Project Vision Eval	Validate Vision for clarity, testability, non-contradiction, and completeness (Project Evaluator)
Project Spec Eval	Validate a Spec against its Vision and Research (Project Evaluator)
Project Plan	Break the spec into one or more implementable plans
Project Plan Eval	Validate Plans against Spec, Vision, and Research (Project Evaluator)
Project Execute	Execute a plan step by step, tracking progress in Execute_State; also handles re-execution after failed Execute_Eval
Project Execute Eval	Fresh Project Evaluator evaluates plan execution against the Plan’s intent
Project Verify	Final holistic review of the complete implementation
Project Extract	Extract knowledge and skills to permanent locations
Project Extract Eval	Fresh Project Evaluator evaluates extraction quality against permanent doc standards
Project Complete	Archive or publish the project
Project Rename	Rename a project or move it between departments
Project Delete	Delete a project from the repo and sidebar
Project Archive	Archive a completed project

2.1 Project System Component Set

The active project system is larger than the markdown project folder. When the workflow changes, verify and update every affected component category:

Forge Project Knowledge and Guides, especially Workflow, User Guide, Agent Orchestration, Agent Architecture, Document Structure, Infrastructure, README, and AGENTS.
Project Skills and Project Create templates in Forge/Forge_Project/Skills/.
Project bot prompts and shared prompts in the bot database for project-runner, project-thinker, project-worker, project-evaluator, and any routing bot that can dispatch project work.
Orchestration schedules and trigger prompts, including uvilo-mono orchestrator/src/schedules.ts and orchestrator/src/inngest.ts when they contain active workflow instructions.
Todo lists/items that represent human gates, blockers, agent follow-up, and informational auto-dispositions.
Generated documentation pages and sidebar output.
Durable project work-products, persisted reports, changelogs, and run/cost evidence.

Prompt records are part of the canonical source set even though they are not markdown files. When a prompt changes, record the prompt id and visible version or update timestamp in the project’s changelog, inventory, or eval report so a human can inspect the effective instruction set.

3. Document Types

Document	Mutability	Purpose	Created in	Agent-loaded
Phase	Living	Project’s current phase and completion state	Create	All phases
Vision	Evergreen	What to build and why	Vision	Research, Spec, Plan, Verify, Repeat
Vision_Eval	Historical (append-only)	Vision quality evaluation	Vision_Eval	Spec
Research	Historical (append-only)	Options explored and decisions made	Research	Spec, Plan
Spec	Evergreen	Declarative description of ideal final state	Spec	Plan, Verify, Repeat
Spec_Eval	Historical (append-only)	Spec completeness and correctness evaluation	Spec_Eval	Plan
Plan	Frozen once the next Plan’s execution starts	Procedural steps for one phase	Plan	Execute
Plan_Eval	Historical (append-only)	Plan procedural evaluation	Plan_Eval	Execute
Execute_State	Living	Todo list and progress tracking	Execute	Execute, Execute_Eval
Execute_Eval	Historical (append-only)	Execution evaluation per Plan	Execute_Eval	Verify
Verification	Historical (append-only)	Final holistic review against Vision and Spec	Verify	Extract
Extract_Eval	Historical (append-only)	Extraction quality evaluation	Extract_Eval	Complete
Changelog	Living	Files added, modified, or deleted across all Plans	Execute	Verify, Execute_Eval, Extract, Complete
Runs	Historical (append-only)	Agent conversation metadata, token counts, and costs	Verify	Audit
Learnings	Temporary	Obstacles and decisions during execution	Execute	Execute_Eval

Mutability definitions:

Evergreen — retroactively updated to reflect the current truth. A reader sees the latest state, not the history of changes.
Historical — append-only. New information is added; existing content is never replaced. Records the journey, not just the destination.
Frozen — immutable once the next Plan’s execution begins. During a Plan’s own Execute/Execute_Eval cycle, the Plan can be updated to correct mistakes or outdated information.
Living — continuously updated during active work.
Temporary — exists during a phase, then cleared by incorporating entries into permanent documents.

4. Document Definitions

4.1 README

README.md is a human-facing description of the project and guide to how to work with it.

4.2 AGENTS

AGENTS.md is the agent-facing entry point to the project. It briefly describes the project and points to relevant skills, documents, and knowledge so that a new agent can easily work with the project.

4.3 Phase

The Phase document tracks the project’s current phase. It is distinct from Execute_State documents, which track the implementation progress of individual Plans.

Created in the Create phase alongside README and AGENTS
Updated at the start and completion of every phase
The value format is {PhaseName}_{Status} where Status is Started, Completed, Blocked, or Paused
Phases before Execute (Create through Plan_Eval) do not use cycle numbers
Execute and Execute_Eval use cycle numbers: Execute_{N}_Started, Execute_Eval_{N}_Started
Execute and Execute_Eval use the same N for the same Plan cycle
Phase detection in project-flow reads this document to determine the current phase
Living — updated throughout the project lifecycle

# {Project} Phase

Phase: Vision_Started

4.4 Vision

The Vision document captures the project’s purpose and success criteria.

Short and to the point — max 2 pages
Starts with either a Vision for something to build, or Problem for something to fix
Includes minimal necessary Background
Requirements are numbered R1, R2, R3, etc.
Verification Criteria are numbered V1, V2, V3, etc. matching Requirements 1:1
Out of Scope lists what is beyond the scope of this project
Scope boundaries are owner decisions — agents may recommend that something be deferred or excluded, but must not declare a finding, gap, concern, or requested change out of scope without explicit project-owner approval.
Once Plans exist, existing requirements must not be renumbered or removed
- Retired requirements are annotated: R3: [Not required]
- New requirements (if they surface) are appended at the end
Requirements are brief and problem-focused — they state what is needed, not how to get there
Undecided items are permitted — they are resolved during Research or implementation
The user is the primary author; the agent organizes, clarifies, and augments
Charter Considerations — the Vision must address any relevant charter principles. Not every project needs all four; the Vision_Eval evaluator judges relevance:
- Stewardship — does this project affect customers, personnel, management, shareholders, or community?
- Security — does this project touch sensitive data, privileged tooling, or access control?
- Privacy — does this project handle user data, personal information, or data sharing?
- Performance tracking — does this project involve agent execution, automation, or infrastructure where cost/token/run metadata matters? If any apply, the Vision must include a corresponding requirement. If none apply, the section can be omitted.

# {Project} Vision

---

## Vision (or Problem)

{One to two paragraphs describing the project's purpose and motivation.}

## Background (optional)

{Minimal background information if necessary.}

---

## Requirements

### R1: {Short title}

{Description — what is needed and why. 2-5 sentences. No solutions.}

### R2: {Short title}

{Description.}

## Success Criteria

| #  | Criterion | Measured by |
|----|-----------|-------------|
| V1 | Root cause identified and documented | R1 deliverable exists and is specific |
| V2 | Another criterion | Another success condition or metric |

---

## Out Of Scope

{Point form list of what this project explicitly does NOT cover.}

## Charter Considerations (optional)

Review the following charter principles. If any apply to this project, add a corresponding requirement above. If none apply, omit this section.

- **Stewardship** — Does this project affect customers, personnel, management, shareholders, or community?
- **Security** — Does this project touch sensitive data, privileged tooling, or access control?
- **Privacy** — Does this project handle user data, personal information, or data sharing?
- **Performance tracking** — Does this project involve agent execution, automation, or infrastructure where cost/token/run metadata matters?

4.5 Research

The Research document records the investigation of implementation options and the decisions made.

Historical — existing sections are never replaced. When decisions change, append a dated revision note.
Decision points are explicitly marked and easy for the user to review and respond to
Each decision records who decided (which user or agent) and when
The user must approve all decision points before a Spec is created

# {Project} Research

---

## 1. {Topic}

{R1: Related Requirement}

### 1.1 Finding

{Description of the research and its findings.}

### 1.2 Options

{Description of options considered with pros/cons.}

### 1.3 Recommendation

{Recommended option and rationale.}

### 1.4 Decision

{Selected option — may differ from recommendation.}

**Decided by:** @{name} — {date}

{Superseding decision — if any.}

**Decided by:** @{name} — {date}

---

## 2. {Topic}

...

4.6 Spec

The Spec describes the ideal final state of the project.

Declarative, not procedural — describes what the system is, not the steps to build it
Self-contained — a reader can understand the target system from the Spec alone
Can be repurposed as permanent documentation after the project completes
May reference specific Research sections when procedural rationale is important
Updated retroactively when evaluation reveals necessary deviations

# {Project} Spec

{1-2 sentence summary of the target state.}

**Vision:** [{Project} Vision]({link})
**Research:** [{Project} Research]({link})

---

## 1. {Major area}

{Declarative description of the target state for this area.}

## 2. {Major area}

...

4.7 Plan(s)

Plans convert the declarative Spec into procedural steps to be implementable by an agent.

Break the Spec into one or more atomic Plans, each one implementable in a single focused agent session
One or more per project, numbered sequentially: Plan_1, Plan_2, etc. Even a single plan is Plan_1
Each Plan must be implementable in a single focused agent session
Self-contained: includes all context the implementing agent needs. The implementing agent reads only the Plan and Execute_State — never Vision, Research, or Spec
May incorporate relevant content from Research when the Spec references it
Does not contain checkboxes — that is the Execute_State document’s role
Each Plan must include a final task to create its own numbered Execute_State document ({Project}_Execute_State_{N}.md where N matches the Plan number), using the Execute_State template
Frozen once the next Plan’s execution begins. During a Plan’s own Execute/Execute_Eval cycle, the Plan can be updated to correct mistakes or outdated information.
Later Plans are tentative — they may be revised based on evaluation of earlier Plans, but only before their implementation begins

# {Project} Plan {N}

**Scope:** {what this plan covers}
**Spec:** [{Project} Spec]({link})
**Prior plan:** {link to prior plan, or "None"}

---

## Task 1 — {Title}

> {Brief context — why this task exists, what it achieves.}

{Procedural steps in prose or bullet points. Include enough context
that the implementing agent never needs to consult external documents.}

---

## Task 2 — {Title}

...

4.8 Execute_State(s)

An Execute_State document tracks the implementation progress of a particular Plan.

One Execute_State per Plan, named {Project}_Execute_State_{N}.md where N matches the Plan number
In the sidebar, each Execute_State follows its corresponding Plan: Plan 1 → Execute_State 1 → Plan 2 → Execute_State 2, etc.
Todo list is created from the current Plan when implementation begins
Uses the checkbox conventions defined in the system prompt

# {Project} Execute State {N}

**Related plan:** [{Project} Plan {N}]({link})

---

- [ ] ✅ Task 1 — {title}
  - [ ] ✅ {Subtask 1.1 title}
  - [ ] ✅ {Subtask 1.2 title}
- [ ] ✴️ Task 2 — {title}
  - [ ] ✅ {Subtask 2.1 title}
  - [ ] ✴️ {Subtask 2.1 title}
- [ ] 🟨 Task 3 — {title}
  - [ ] 🟨 {Subtask 3.1 title}
  - [ ] ⬜ {Subtask 3.1 title}

4.9 Learnings

The Learnings document captures obstacles, workarounds, and unexpected decisions made during implementation that weren’t anticipated by the Plan.

Temporary — cleared during re-execution by incorporating each entry into the appropriate permanent document (Vision, Spec, Knowledge, or Skills)
One entry per obstacle or decision
Learnings that don’t belong in any permanent document are discarded during re-execution

# {Project} Learnings

## L1: {Short title}

**Context:** {what was being attempted}
**Obstacle:** {what went wrong or was unexpected}
**Resolution:** {what was done and why}
**Destination:** {where this should be incorporated — or "discard"}

## L2: {Short title}

...

4.10 Runs

The Runs document records agent conversation metadata for the project — which agents ran, which models they used, how long they ran, token counts, and costs.

Historical — append-only. New runs are added; existing entries are never replaced.
Created during the Verify phase (or earlier if run metadata is available)
Generated by the Forge Optimizer generate-runs.ts script when database environment variables are available
When the script cannot run (missing env vars), record available evidence manually: phase range, agent roles, dates, and any available evidence sources

# {Project} Runs

Agent conversations for this project.

## Summary

| # | Phase | Agent | Model | Task | Duration | Input | Output | Total | Cost |
|---|-------|-------|-------|------|----------|--------|--------|-------|------|

- **#** — Sequential run number within the project.
- **Phase** — Lifecycle phase when this run occurred.
- **Agent** — Agent role (e.g., Project Thinker, Project Worker, Project Evaluator).
- **Model** — Model used (e.g., `gpt-5.4`, `glm-5.1`).
- **Task** — Brief description of what the agent was asked to do.
- **Duration** — Wall-clock time of the conversation.
- **Input** — Input tokens (user messages).
- **Output** — Output tokens (assistant messages).
- **Total** — Total tokens (input + output).
- **Cost** — Estimated cost in USD.

**Project total:** ${total_cost}

4.11 Changelog

The Changelog document tracks every file added, modified, or deleted across all Plans, providing a complete audit trail of what changed and when.

Living — continuously updated during execution and verification
Created during the Execute phase (lazily, when the first file is touched)
Each row records the file, action, version identifier, plan, and task
The Version column records the commit id (short hash, e.g., a1b2c3d) for files committed to git, or the prompt version id (e.g., prm_abc123 v5) for prompts modified in the database
Used by Execute_Eval, Verify, Extract, and Complete to understand what changed

# {Project} Changelog

Files added, modified, or deleted across all Plans.

| File | Action | Version | Plan | Task |
|------|--------|---------|:----:|------|

- **File** — Filename (not full path) as a Markdown link to its page on the site.
- **Action** — Added / Modified / Deleted.
- **Version** — Commit id (short hash) or prompt version id that introduced this change.
- **Plan** — Plan number.
- **Task** — `Task N` as a Markdown link to the task heading anchor in the Plan file.

4.12 Recovery Contract

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. Agents do not create or rely on separate crash-recovery scratchpads.

5. Project Subdirectories

Projects may contain specialized subdirectories:

Project_Name/
├── References/    # Project-specific reference documents
├── Output/        # Generated outputs
└── _temp/         # Disposable session scripts

6. Agent Context Boundaries

Each phase restricts what the agent reads. This minimizes context consumption and prevents the implementing agent from being influenced by upstream deliberation.

Phase	Must Read	Must NOT Read	Writes
Create	—	—	Folder, README, AGENTS, Phase
Vision	User input	—	Vision, README, AGENTS, Phase
Vision_Eval	Vision	—	Vision_Eval report, Phase
Research	Vision	—	Research, Phase
Spec	Vision, Research	—	Spec, README, AGENTS, Phase
Spec_Eval	Vision, Research, Spec	—	Spec_Eval report, Phase
Plan	Vision, Research, Spec	—	Plan(s), Phase
Plan_Eval	Vision, Research, Spec, Plan(s)	—	Plan_Eval report, Phase
Execute	Plan (current), Execute_State (current), Changelog	Vision, Research, Spec	Work-products, Execute_State (current), Changelog, Phase
Execute_Eval	Plan (current), Execute_State (current), Execute_Eval report, Learnings, Changelog	Research	Execute_Eval report, Phase
Repeat	(per cycle: same as Execute or Execute_Eval for the active Plan)	(same Must NOT read as the active step)	(same outputs as the active step)
Verify	Vision, Spec, Changelog	Research, Plans, Learnings	Verification report, Runs, Plan (new — optional), Phase
Extract	Vision, Spec, Changelog	Research, Plan, Execute_State	README, AGENTS, Vision, Spec, Skills, Guides, Phase
Extract_Eval	Vision, Spec, Changelog, extracted permanent docs	Research, Plan, Execute_State	Extract_Eval report, Phase
Complete	Changelog	—	Front matter of all, Phase

The execution boundary is the critical rule. Plans must contain everything the executing agent needs. If a Plan is missing context, that is a Plan authoring failure — fix the Plan before execution, don’t break the boundary.

7. Document Header Convention

Every project document includes a human-readable metadata block below the H1 heading. This makes ownership, status, and navigation visible without reading YAML frontmatter — so it must match it.

# {Project} {DocType}

Status values

Status	Meaning
`draft`	Initial creation, not yet reviewed
`review`	Ready for review
`approved`	Reviewed and accepted
`published`	Contents available for use as knowledge
`archived`	Project complete, moved to Archived/

8. Evaluation Protocol

8.1 Execute_Eval (Plan Evaluation)

After a Plan is fully executed, a fresh Project Evaluator (new conversation with clean context) evaluates the work:

Read: current Plan, current Execute_State, Learnings
Review the execution against the Plan
Format the evaluation using the Execute_Eval_Template.md from Forge/Forge_Project/Skills/Project_Create/templates/. Write findings to the per-plan report file {Project}_Execute_Eval_{N}.md. If the file already exists, append the new run as a new section with a date header. Each item is one of:
- Defect — execution doesn’t match the Plan’s intent
- Gap — the Plan specified something that wasn’t implemented
- Variance — execution differs from Plan for a reason
- Learning — something from Learnings that needs to be stored in the right place
- All items start as 🔴 Open; progress through 🟡 In progress; end at 🟢 Resolved
Auto-fix loop: If findings exist, the Evaluator attempts to resolve them automatically (up to 3 rounds) before escalating to the user. Only genuine ambiguities or trade-off decisions are escalated.
If the auto-fix loop converges, present the final result to the user for approval. For each remaining item, the user decides: fix, update, reject, or defer
Process dispositions and update item statuses in the Execute_Eval report:
- fix: Returns to project-execute for the same Plan → item remains 🔴 Open with Disposition Fix
- update: Don’t fix the implementation; update the Spec to match instead. Update the Spec retroactively to match reality → item 🟡 In progress → 🟢 Resolved when done.
- reject: I disagree with the finding; do nothing. Item → 🟢 Resolved (no action)
- defer: Add as tasks for a future Plan → item → 🟢 Resolved (deferred)
Note which Learnings entries need incorporation into permanent documents (per their Destination field). This work is done during re-execution in project-execute.
If later Plans exist and are affected by changes, revise them
Update the Execute_Eval report after each iteration (statuses and Resolution Log)
The Plan is approved when all evaluation items are 🟢 Resolved
If any items have Disposition Fix, the project returns to Execute for the same Plan — there is no separate Fix phase

The current Plan can be updated during the Execute/Execute_Eval cycle. It is frozen once the next Plan’s execution starts.

8.2 Verify (Project Evaluation)

After all Plans are executed and evaluated, a final evaluation ensures completeness:

Read: Vision, Spec
Make sure all Verification Criteria in Vision is satisfied
Verify the execution matches the Spec
Produce a findings report formatted using the Verification_Template.md from Forge/Forge_Project/Skills/Project_Create/templates/. Write findings to {Project}_Verification.md. If the file already exists, append as a new section with a date header. Each item is one of:
- Defect — execution doesn’t match Spec or Vision
- Variance — execution differs from Spec for a reason
- Gap — something in Vision/Spec wasn’t addressed
- Change — user-requested modification that may affect Vision, Spec, or implementation
Present the report to the user for review
For each item, the user decides: fix, update, reject, or defer
Process user decisions:
- fix (minor): Implement directly — update Execute_State with new tasks, execute them
- fix (substantial): Create a new Plan and loop back to Execute → Execute_Eval → Verify
- update: Don’t fix the implementation; update the Spec to match instead. Update Vision, Spec, and/or Plan retroactively to match reality
- reject: I disagree with the finding; do nothing
- defer: Record for future work outside this project
- change: May require updating Vision, Spec, or just execution — assess scope and act accordingly

8.3 Extract (Knowledge Extraction)

Extract knowledge and skills to permanent locations when appropriate:

System documentation → department root-level Knowledge files
Reusable procedures → department Skills/ folder
Configuration knowledge → Infrastructure or system docs
Sometimes: copy the Spec with edits as permanent documentation
Sometimes: fold insights into existing documents

No useful information should remain trapped inside the project folder after extraction.

9. Project Completion

Outcome	Action	When to use
Approve	Set status to `approved`, keep in Projects/	Projects that are complete but not yet ready for publication or archiving
Archive	Move to `Department/Archived/`	One-time projects that performed a task

Archive after extraction is typical; approve (leave the folder in Projects/) is fine if you want it handy.

Canonical order of project files/folders in the sidebar (follows the project lifecycle — every document type must appear in this order, omitting any that don’t exist yet):

README
AGENTS
Phase
Vision
Vision_Eval
Research
Spec
Spec_Eval
Plan 1 → Plan_Eval → Execute_State 1 → Execute_Eval 1
Plan 2 → Execute_State 2 → Execute_Eval 2
Plan N → Execute_State N → Execute_Eval N (repeat for each plan)
Verification
Extract_Eval
Learnings
Runs
Changelog
Audit_Results
Resources/ (or References/)
Other Folders/
Other Files

Sidebar ordering rules:

Items must follow the canonical lifecycle order above — never alphabetical
Plan_Eval follows Plan 1 (it evaluates all plans before execution begins)
Each Execute_State and Execute_Eval immediately follows its corresponding Plan
Verification follows the last Execute_Eval
Learnings, Runs, Changelog, and Audit_Results follow Verification in lifecycle order
Non-standard project files (e.g., Ambiguities, Charter_Alignment) come after Changelog, before References/
The sidebar label for README must be “README”, not the project name

Each sidebar entry’s label must match the file’s frontmatter title minus the project name. The frontmatter title must match the file name with underscores replaced by spaces and the file extension removed. The sidebar must reflect the exact folder hierarchy but in the canonical order.

11. Todos Tool Group

The project system uses the todos tool group for human and agent queues. Flat-file todo workflows (Erik_Todo.md, Agent_Todo.md) are retired.

11.1 Todos Tool Inventory

Tool	Purpose
`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".

11.2 Flat-File to Todos Replacement Mapping

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, project owner, status, and durable work-product link (markdown-file artifact)
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 present the work-product as a markdown-file artifact
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 must use the standard human-gate body template. The body is Markdown rendered in a todo card — every field must be on its own line with double newlines between fields so they render as separate paragraphs, not a single blob.

11.3 Human-Gate Todo Body Template

**Project:** {Department}/{ProjectShortName}

**Phase:** {Phase} Completed

**Action needed:** {One sentence describing what the human must decide or do.}

- **Approve** — {What happens on approval}
- **Request changes** — {What happens on rejection}

Record your verdict in the work-product, then update this todo item.

```artifact
identifier: {artifact-id}
title: {Work-product Title}
type: application/vnd.markdown-file
display: panel
---
{Department}/Projects/{ProjectSlug}/{WorkProductFile}.md


Rules:
- Use **bold labels** with Title Case for every field
- **Double newlines** between every field — never single newlines (they collapse into one paragraph in Markdown)
- Do NOT include `Department` — it is already part of the Project identifier (`Forge/Project_Cleanup`)
- Do NOT include `Project owner` — the todo is already assigned to that person's list
- Do NOT include: `requesting_bot_or_role`, `review_url`, `agent_paste_instruction`, `run_cost_evidence`, `status`, or `priority` — these are metadata or noise, not decision content
- **Embed the work-product as an artifact block inside the todo body** — the user must be able to open it directly from the todo item, not from a separate chat message
- Do NOT include raw URLs, repo paths, or paste instructions in the todo body
- The user records their verdict in the work-product; the system picks it up from there
- Todo items do not duplicate substantive work-product content beyond what is needed to identify and route the action

---

## 12. Standard Handoff Packets

Every project handoff uses a standard packet with these fields:

| Field | Purpose |
|-------|---------|
| Department | Identifies the department root |
| Project | Canonical/display identifier `{Department}/{ProjectShortName}` |
| 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.

**Paused phases:** The user may set a phase to `{Phase}_Paused` to pause a project. When a phase is `_Paused`, the Runner skips the project entirely — no dispatch, no staleness check, no todo, no escalation. The user resumes by changing the phase back to `{Phase}_Started`. Pausing is user-initiated; agents do not set `_Paused`.

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.

### 12.1 Scope Decisions and Ambiguities

Scope decisions belong to the project owner. Agents may identify that a finding appears outside the approved Vision or Spec, but they must not silently discard it or mark it out of scope on their own.

When scope is unclear, record the ambiguity in the durable work-product or persisted report with the affected area, decision needed, options considered, recommended option if any, responsible owner, status, and related todo item when one is created. Until the owner decides, label it `Pending user decision`, not `Out of scope`.

---

## 13. Project Identity and Human Gates

### 13.1 Project Identity

Project names are globally unique across departments. User-facing project identity uses the canonical/display identifier `{Department}/{ProjectShortName}`, mirroring bot names such as `{group}/{handle}`. Example: `Forge/Project_Cleanup`.

Because `/` is a path separator, project folders and filenames use a filesystem-safe slug derived from the canonical identifier by replacing `/` with `_`: `{Department}_{ProjectShortName}`. Example: `Forge_Project_Cleanup`.

- Canonical/display identifier: `{Department}/{ProjectShortName}`
- Filesystem slug: `{Department}_{ProjectShortName}`
- Project folder: `{Department}/Projects/{ProjectSlug}/`
- Phase file: `{ProjectSlug}_Phase.md`
- Work-product files: `{ProjectSlug}_{DocumentType}.md`

Handoff packets, todo items, reports, and cross-department references use the canonical/display identifier. File paths use the filesystem slug. Project creation checks active and archived project folders across all departments before creating a new slug.

### 13.2 User-Configurable Human Gates

Human gates pause after the named phase or eval completes and before the next phase begins. At project creation, the user is asked which gates they want. Available gate keys:

| Gate | After Phase | Description |
|------|-------------|-------------|
| G1 | `Vision_Eval` | User reviews and approves the Vision before Research begins |
| G2 | `Research` | User reviews Research decisions before Spec begins |
| G3 | `Spec_Eval` | User reviews and approves the Spec before Plan begins |
| G4 | `Plan_Eval` | User reviews and approves Plans before Execute begins |
| G5 | `Execute_Eval` | User reviews execution results after each Execute_Eval cycle |
| G6 | `Verify` | User reviews verification results before Extract begins |
| G7 | `Extract_Eval` | User reviews extraction completeness before Complete |

The default gates are `Vision_Eval`, `Spec_Eval`, `Plan_Eval`, and `Verify`.

Selections are recorded in Phase-file frontmatter:

```yaml
human_gates:
  - Vision_Eval
  - Spec_Eval
  - Plan_Eval
  - Verify

When a completed phase’s gate key is in human_gates, the Runner pauses. In Interactive Mode, it asks the user directly. In Autonomous Mode, it creates a user-owned todo item with the project, completed phase, requested approval/decision, options, status, and durable work-product link, then stops. The Runner does not start the next phase until approval is recorded.

14. Frontmatter Convention

All Forge markdown files use YAML frontmatter with required fields: title, visibility, status, owner, and approver. Date fields (created, updated, lastUpdated) are not used — creation and modification dates are sourced from git history and filesystem metadata. See Forge Document Structure for the full frontmatter convention.

This matches the Document Header Convention (§7) and ensures consistency between machine-readable front matter and human-readable headers.