Project Automation Spec
A fully reliable project automation workflow where projects move through all phases with formal evaluation steps, persisted report files, correct agent handoffs, human gates at the right moments, a complete User Guide, Forge Optimizer integration, globally unique project names, and an Agent Run Summary system.
1. Project Lifecycle & Phase Model
The project lifecycle is a 14-phase sequence:
Create → Vision → Vision_Eval → Research → Spec → Spec_Eval → Plan → Plan_Eval → Execute → Execute_Eval → Verify → Extract → Extract_Eval → Complete
Every content-producing phase is followed by an evaluation phase where appropriate. This ensures quality gates at each stage before proceeding.
Vision_Eval — After Vision is drafted. A Project Evaluator verifies clarity, testability, non-contradiction, and completeness. If findings exist, an auto-fix loop runs (up to 3 rounds) before escalating to the user.
Spec_Eval — After Spec is drafted. A Project Evaluator verifies that every Requirement is addressed, the Spec is self-contained, describes what not how, and preserves exact required content from Research via references. Auto-fix loop applies.
Plan_Eval — After Plans are drafted. A Project Evaluator verifies self-containment, procedural correctness, ordering, and Spec coverage. Auto-fix loop applies.
Execute_Eval — After Execute completes for a plan. A fresh Project Evaluator verifies implementation against the Plan. If findings exist, an auto-fix loop runs. Remaining issues escalate to the user for disposition.
Extract_Eval — After Extract completes. A Project Evaluator verifies that extraction is complete, correct, and leaves no stale project-only references. Auto-fix loop applies.
The lifecycle string appears identically in Project Flow, Project Snippet, and Forge_Chat_Prompt.
Phase naming convention:
| Status | Name | Meaning |
|---|---|---|
| Pending | {Phase}_Pending | Waiting for SRP agent to start |
| Started | {Phase}_Started | SRP agent in progress |
| Blocked | {Phase}_Blocked | SRP agent blocked; Runner escalates to Erik_Todo |
| Completed | {Phase}_Completed | SRP agent finished; Runner may start next phase |
2. Persisted Review and Evaluation Reports
Every review- or evaluation-producing phase writes to a durable markdown file. These files are the canonical artifacts for human review, Erik_Todo links, workflow audit evidence, Forge Optimizer context, and future model-selection foundations.
Required persisted artifacts:
{Project}_Vision_Eval.md{Project}_Spec_Eval.md{Project}_Plan_Eval.md{Project}_Execute_Eval_{N}.md— one file per plan; repeated eval runs append new dated sections{Project}_Verification.md— repeated verification runs append new dated sections{Project}_Extract_Eval.md{Project}_Audit_Results.md{Project}_Runs.md
Each report must include, at minimum:
- phase name
- run identifier or date section
- agent/session context when relevant
- checklist/findings summary
- pass/fail or disposition
- next-step instruction or return phase
The workflow may append to an existing report file when that phase naturally accumulates history; otherwise it creates a stable dedicated file.
3. Workflow Audit
After all structural changes are implemented, a verification audit confirms that no gaps remain. The audit covers lifecycle docs, project skills, agent prompts, snippets, templates, routing, report persistence, and human-gate behavior.
The audit produces Project_Automation_Audit_Results.md with:
- gaps found
- fixes applied
- remaining open issues, if any
4. Agent Handoffs
Agent handoffs use the Phase file as the single state signal. Project Runner reads the Phase file, determines the current phase, and dispatches the appropriate agent via forge-spawn.
Routing table:
| Phase | Agent |
|---|---|
| Vision | Project Thinker |
| Vision_Eval | Project Evaluator (fresh session) |
| Research | Project Thinker |
| Spec | Project Thinker |
| Spec_Eval | Project Evaluator (fresh session) |
| Plan | Project Thinker |
| Plan_Eval | Project Evaluator (fresh session) |
| Execute | Project Worker |
| Execute_Eval | Project Evaluator (fresh session) |
| Verify | Project Evaluator |
| Extract | Project Thinker |
| Extract_Eval | Project Evaluator (fresh session) |
Task Runner routes individual tasks to Worker, Thinker, Evaluator, or Page Manager based on task type.
When a phase is blocked, the project writes {Phase}_Blocked and Runner appends an Erik_Todo item that links to the document or report file requiring attention.
5. Human-in-the-Loop Gates
Human approval is required after eval-converged phases and at key decision gates. The system uses an auto-fix loop before escalating: Draft → Eval → auto-fix loop (up to 3 rounds) → user review only if the loop doesn’t converge.
Erik_Todo is the human inbox. Each item includes:
- project name
- what needs attention
- link to the exact document or report file to review
- current document/report status
Format:
Persisted report files are required so these review links always target durable artifacts.
Preference-Based Disposition
Runner accumulates user preference patterns from past dispositions and may auto-dispose findings when confident. Auto-dispositions are logged to Erik_Todo as informational items. Only genuine ambiguities or novel situations are escalated.
6. User Guide
A comprehensive guide exists for humans unfamiliar with Forge. It explains:
- overview
- getting started
- detailed phase descriptions
- agent roles
- human gates
- document and report reference
- monitoring and steering
The guide is produced during the project and extracted to Forge/Forge_Project_User_Guide.md.
7. Forge Optimizer Integration
Forge Optimizer is project-aware and manually invoked via /forge-optimizer. It can analyze a project’s conversations and use persisted report files and run summaries as supporting context.
Default analysis model is GLM 5.1. The user may select another model for higher-judgment analysis.
After each Execute_Eval completes, the workflow reminds the user that they can run the Optimizer for the project.
8. Agent Run Summary
For any project, {Project}_Runs.md records the agent conversations involved in the project’s lifecycle. This complements the evaluation and verification reports with runtime cost and usage data.
The AgentJob table has project TEXT and phase TEXT columns. Project Runner passes both when spawning an agent.
Per-conversation summary output includes:
- agent
- model
- task/message given
- duration
- token usage per turn and total
- cost
The document also computes total project cost.
9. Project Creation & Name Uniqueness
Project_Create must prevent name conflicts before any files are created.
The uniqueness check is global across the repository:
- all departments’
Projects/folders - all departments’
Archived/folders
A matching project name in any of those locations is a blocking conflict. The check must happen before copying templates, creating the project folder, or adding sidebar entries.
10. Model Selection System
Deferred. This iteration does not implement the full model-selection system. It does, however, preserve the required foundations for that future work: durable evaluation reports, project-level run tracking, stable review links, and project/phase metadata for agent runs.