Forge Project Requirements
Vision
A standardized project lifecycle system for Forge — directed by people, executed by agents — that optimizes for agent context efficiency, clean phase separation, and systematic knowledge extraction so the system compounds intelligence over time.
Background
Forge projects currently lack a formal lifecycle. Agents lack clear context boundaries, projects have no evaluation protocol, and knowledge gained during implementation is lost when projects end. This project defines and implements the full lifecycle as described in the Forge Project Flow Spec.
Requirements
R1: Project Lifecycle Phases
The system must define and enforce the canonical project lifecycle: Create → Requirements → Research → Spec → Plan → Implement → Evaluate → Fix → Repeat → Check → Extract → Complete. Each phase has defined inputs, outputs, and agent context boundaries.
R2: Document Types and Mutability
Each phase must produce documents with defined mutability: Requirements (evergreen), Research (historical/append-only), Spec (evergreen), Plan (frozen), State (living), Learnings (temporary), WIP (ephemeral). Documents must follow the header convention (status table matching YAML front matter).
R3: Agent Context Boundaries
Each phase must restrict what the agent reads. The critical rule: during Implement, the agent reads only the current Plan, State, and WIP — never Requirements, Research, or Spec. Plans must be self-contained to satisfy this boundary.
R4: Evaluation Protocol
A fresh-agent evaluation must run after each Plan and after the full project. Evaluation produces a defect/variance report (defect, variance, gap, change, or learning). The user decides per item: fix, accept, reject, or defer. Accepted variances retroactively update Requirements/Spec. Learnings incorporation is done in Fix, not Evaluate. Plans are never modified.
R5: Knowledge Extraction
Upon project completion, knowledge and skills must be extracted to permanent locations (department Knowledge, Skills, Guides). No useful information may remain trapped inside the project folder.
R6: Project Completion
Projects must end in one of three states: Archive (moved to Department/Archived/), Publish (status set to published, kept in Projects/), or Approve (status set to approved, kept in Projects/).
R7: Skills for Every Phase
A Skill must exist for each lifecycle phase, plus Project_Archive and Project_Flow (14 skills total: 11 phases with dedicated skills — Repeat reuses Implement/Evaluate/Fix — plus Archive, Rename, and Flow). Each skill guides the agent through its phase’s procedures and enforces its document format and rules.
R8: Document Templates
Template files must exist at Forge/Skills/Project_Create/templates/ for each document type (8 templates: Phase, Requirements, Research, Spec, Plan, State, Learnings, WIP), encoding the structure, numbering, header convention, and placeholder content.
R9: FORGE.md Updates
The WORK TRACKING section of FORGE.md must be updated: replace History.md references for projects with Plan + State + WIP + Learnings; add reference to the Project Flow lifecycle; retain History.md for one-off tasks.
R10: Global Front Matter Convention
All project documents must use a consistent YAML front matter schema: Status, Visibility, Owner, Approver, Created, Updated — in that order.
Success Criteria
| # | Criterion | Measured by |
|---|---|---|
| V1 | Every lifecycle phase (Create through Complete) is defined with inputs, outputs, and context boundaries | Spec §1 and §4 are complete and internally consistent |
| V2 | All 8 document types have defined mutability, format, and templates | Templates exist and match §3 definitions |
| V3 | Implementation context boundary is enforced | Plan documents are self-contained; implementing agent never needs upstream docs |
| V4 | Evaluation protocol produces actionable reports | Fresh-agent evaluation yields categorized findings with user-driven disposition |
| V5 | Knowledge extraction leaves nothing useful in the project folder | Post-extraction audit finds no orphaned insights |
| V6 | All 14 project skills exist and are functional | Each skill can be invoked and produces compliant output |
| V7 | FORGE.md reflects the new project lifecycle | WORK TRACKING section references Plan/State/WIP/Learnings, not History |
| V8 | Front matter convention is consistent across all project documents | Every doc has the 6 required fields in the correct order |
Out Of Scope
- UI/dashboard for project lifecycle visualization
- Automated phase transitions without user approval
- Integration with external project management tools
- Multi-repo project support
- Version control or diffing of document changes over time