Forge Project Flow

Forge Project Flow 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. Requirements<br><small>User describes needs</small>]
    B --> C[3. Research<br><small>Agent proposes solutions, user makes decisions</small>]
    C --> D[4. Spec<br><small>Agent creates Spec, user approves</small>]
    D --> E[5. Plan<br><small>Agent breaks Spec into one or more Plans</small>]
    E --> F[6. Implement<br><small>Agent implements one Plan</small>]
    F --> G[7. Evaluate<br><small>Another agent evaluates plan implementation, user approves fixes</small>]
    G --> H[8. Fix<br><small>Another agent implements fixes</small>]
    H -->|9. Repeat for remaining Plans| F
    H --> I[10. Check<br><small>Agent checks final result against Spec, user may requests changes</small>]
    I -->|Issues found -> new Plan| F
    I --> J[11. Extract<br><small>Agent extracts knowledge, skills, and documentation</small>]
    J --> K[12. 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: Requirements

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 §3.1. README.md and AGENTS.md are updated.

Phase 3: 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 §3.2.

Phase 4: 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 §3.3.

Phase 5: 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 §3.4.

Phase 6: Implement

When implementation of a Plan begins, a matching State document is created with a todo list. The agent implements step by step. 1) It checking off items in the State. 2) It appending steps taken, file paths touched, commands run, errors encountered in a WIP file which is an ephemeral scratchpad for crash recovery. 3) It records obstacles and solutions in the Learnings file. See §3.5, §3.6.

Phase 7: Evaluate

A fresh agent (new session) evaluates whether the Plan was implemented correctly by comparing the implementation to the Plan’s intent. Produces a list of defects, variances, and learnings to store. See §7.1.

Phase 8: Fix

Implements the fixes identified during evaluation. Defects are fixed and necessary variances are captured by updating the Requirements and/or Spec. Learnings entries are incorporated into permanent documents and the Learnings file is cleared.

Phase 9: Repeat

Repeat phases 6–8 for each remaining Plan. Later Plans may be revised based on evaluation of earlier Plans before implementation begins.

Phase 10: Check

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

Phase 11: Extract

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

Phase 12: Complete

Archive or publish the project. See §7.

---

2. Document Types

Document	Mutability	Purpose	Created in	Agent-loaded
Phase	Living	Project’s current phase and completion state	Create	All phases
Requirements	Evergreen	What to build and why	Requirements	Research, Spec, Plan, Check, Repeat
Research	Historical (append-only)	Options explored and decisions made	Research	Spec, Plan
Spec	Evergreen	Declarative description of ideal final state	Spec	Plan, Check, Repeat
Plan	Frozen once the next Plan’s implementation starts	Procedural steps for one phase	Plan	Implement
State	Living	Todo list and progress tracking	Implement	Implement, Evaluate
Learnings	Temporary	Obstacles and decisions during implementation	Implement	Evaluate
WIP	Ephemeral (gitignored)	Crash recovery scratchpad	Implement	Implement

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 implementation begins. During a Plan’s own Implement/Evaluate/Fix 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.
• Ephemeral — not committed to source control. Exists only during a session.

---

3. Document Definitions

3.1 README

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

3.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.

3.3 Phase

The Phase document tracks the project’s current phase. It is distinct from 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 or Completed
• Phases before Implement (Create through Plan) do not use cycle numbers
• Implement, Evaluate, and Fix use cycle numbers: Implement_{N}_Started, Evaluate_{N}_Started, Fix_{N}_Started
• N corresponds to the Plan number being implemented (Plan 1 → Implement_1, Plan 2 → Implement_2)
• Evaluate and Fix use the same N as the Implement they follow
• If Fix creates new work that requires re-evaluation, the cycle number increments: Evaluate_1_Completed → Fix_1_Completed → Evaluate_2_Started
• Phase detection in Project_Flow reads this document to determine the current phase
• Living — updated throughout the project lifecycle

# {Project} Phase

Phase: Requirements_Started

3.4 Requirements

The Requirements 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 a numbered V1, V2, V3, etc. matching Requirements 1:1
• Out of Scope lists what is beyond the scope of this project
• 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

# {Project} Requirements

---

## 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.}

3.5 Research

With the Requirements locked down, it’s time to do some deep research and find solutions.

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}

...

3.6 Spec

Once all research is done and all decisions have been made, a Spec document is created.

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.}

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

---

## 1. {Major area}

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

## 2. {Major area}

...

3.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, State, and WIP — never Requirements, Research, or Spec
• May incorporate relevant content from Research when the Spec references it
• Does not contain checkboxes — that is the State document’s role
• Frozen once the next Plan’s implementation begins. During a Plan’s own Implement/Evaluate/Fix 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}

...

3.8 State(s)

A State document tracks the implementation progress of a particular Plan.

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

# {Project} State {N}

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

---

- [x] Task 1 — {title}
  - [x] {Subtask 1.1 title}
  - [x] {Subtask 1.2 title}
- [x] Task 2 — {title}
  - [ ] [BLOCKED] {Subtask 2.1 title}
- [x] Task 3 — {title}
  - [ ] [STARTED] {Subtask 3.1 title}
  - [ ] {Subtask 3.2 title}

3.9 Learnings

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

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

# {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}

...

3.10 WIP

The WIP file is an ephemeral scratchpad for crash recovery within a session.

• Gitignored — never committed
• Contains: steps taken, file paths touched, commands run, errors encountered - append only
• Cleared at every session end (see §6.2)
• If non-empty at session start → a crash likely occurred. The agent resumes from the recorded state
• Kept minimal — just enough to resume, not a detailed log
• Agents must remember to append to WIP during implementation of plans

# {Project} WIP

- {Step taken, file path touched, command run, or error encountered}
- {Append only — do not delete or reorder entries}

---

4. 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	Agent reads	Must NOT read	Agent creates/updates
Create	—	—	Folder, README, AGENTS, Phase
Requirements	User input	—	Requirements, README, AGENTS, Phase
Research	Requirements	—	Research, Phase
Spec	Requirements, Research	-	Spec, README, AGENTS, Phase
Plan	Requirements, Research, Spec	—	Plan(s), Phase
Implement	Plan (current), State (current), WIP	Requirements, Research, Spec	Work-products, State (current), WIP, Phase
Evaluate	Plan (current), State (current), Learnings	Research, WIP	Evaluation (inline), Phase
Fix	Evaluation (inline), Plan (current), State (current), Learnings, Requirements, Spec	—	State (current), Plan (current), Learnings, Requirements, Spec, Phase
Repeat	(per cycle: same as Implement, Evaluate, or Fix for the active Plan)	(same Must NOT read as the active step)	(same outputs as the active step)
Check	Requirements, Spec	Research, Plans, Learnings, WIP	Evaluation (inline), Plan (new - optional), Phase
Extract	Requirements, Spec	Research, Plan, State	README, AGENTS, Requirements, Spec, Skills, Guides, Phase
Complete	—	—	Front matter of all, Phase

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

---

5. Frontmatter Display

Every project document includes YAML frontmatter with the fields Status, Visibility, Owner, Approver, Created, and Updated (in that order). A custom MarkdownContent component override renders these fields as a styled metadata table above the page body automatically. Document authors must NOT duplicate these fields in the body — they are displayed from frontmatter alone.

Status values

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

---

6. Session Boundaries

Every agent conversation is a session. Sessions must be properly closed — whether work completed naturally or the user interrupted — so the next session can resume cleanly.

6.1 Start Session

1. Read Phase → current Plan → current State → WIP
2. If WIP is non-empty → prior session crashed; resume from WIP state
3. If WIP is empty → pick the next unchecked task from State

6.2 End Session (/end-session)

Every session ends with these steps, in order:

1. Update State — leave incomplete tasks as [STARTED]; add any newly discovered tasks or findings
2. Update Learnings — record obstacles, decisions, or open questions encountered this session
3. Clear WIP — reset to empty (crash recovery no longer needed)
4. Git commit & push — stage all changes, commit with message "{Project}: session checkpoint", push to dev
5. Output status message — All changes committed and pushed. To continue enter Continue {DEPT}/{PROJECT} project at {PHASE}

No session should end without completing all four steps. If the user interrupts mid-task, the agent performs these steps before stopping.

---

7. Evaluation Protocol

7.1 Evaluate (Plan Evaluation)

After a Plan is fully implemented, a fresh agent (new conversation with clean context) evaluates the work:

1. Read: current Plan, current State, Learnings
2. Review the implementation against the Plan
3. Produce a defect/variance report — each item is one of:
   • Defect — implementation doesn’t match the Plan’s intent
   • Variance — implementation differs from Plan for a reason
   • Learning — something from Learnings that needs to be stored in the right place
4. Present the report to the user for review
5. For each item, the user decides: fix, update, reject or defer
6. The agent:
   • fix: Adds corrective tasks to State and implements them
   • update: For accepted variances: update the current Plan to match reality. If a Learning explicitly calls for updating Requirements or Spec, update those too.
   • reject: Does nothing because the user rejects the assessment
   • defer: For deferred items: adds them as tasks for a future Plan
7. Note which Learnings entries need incorporation into permanent documents (per their Destination field). This work is done in Project_Fix.
8. If later Plans exist and are affected by changes, revise them
9. Mark the Plan’s section in State as Approved ✓

The current Plan can be updated during the Evaluate/Fix cycle. It is frozen once the next Plan’s implementation starts.

7.2 Check (Project Evaluation)

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

1. Read: Requirements, Spec
2. Make sure all Verification Criteria in Requirements is satisfied
3. Verify the implementation matches the Spec
4. Produce a findings report. Each item is one of:
   • Defect — implementation doesn’t match Spec or Requirements
   • Variance — implementation differs from Spec for a reason
   • Gap — something in Requirements/Spec wasn’t addressed
   • Change — user-requested modification that may affect Requirements, Spec, or implementation
5. Present the report to the user for review
6. For each item, the user decides: fix, update, reject, or defer
7. Process user decisions:
   • fix (minor): Implement directly — update State with new tasks, execute them
   • fix (substantial): Create a new Plan and loop back to Implement → Evaluate → Check
   • update: Update Requirements, Spec, and/or Plan retroactively to match reality
   • reject: Do nothing
   • defer: Record for future work outside this project
   • change: May require updating Requirements, Spec, or just implementation — assess scope and act accordingly

7.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

---

8. 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
Publish	Set status to published, keep in Projects/	Projects that remain part of ongoing processes
Archive	Move to Department/Archived/	One-time projects that performed a task

---

9. Sidebar Order Convention

Project files appear in the sidebar in this order:

1. README
2. AGENTS
3. Phase
4. Requirements
5. Research
6. Spec
7. Plan 1, State 1, Plan 2, State 2, etc.
8. Learnings
9. Any other files and folders in the folder

---

10. Document Templates

Template files will exist at Forge/Skills/Project_Create/templates/ for (same as is inline above):

• Phase_Template.md
• Requirements_Template.md
• Research_Template.md
• Spec_Template.md
• Plan_Template.md
• State_Template.md
• Learnings_Template.md
• WIP_Template.md

Templates encode the document structure shown in §3, including the header convention, numbering, and placeholder content with instructions.

---

11. FORGE.md Impact

Implementing this Spec requires updates to the WORK TRACKING section of FORGE.md:

• Replace “Starting a project session” steps to read Plan + State + WIP (not History)
• Remove History.md from the project file descriptions
• Add Learnings.md to the project file descriptions
• Add a reference to this document or its successor Knowledge file for the full lifecycle
• Update the “Ending a project session” steps to reference Learnings instead of History
• Keep History.md references for one-off tasks (Output/) which don’t use the full lifecycle

12. Required Skills

A Skill is required for every phase of the Project Flow.

Phase	Skill	Purpose
General	Project_Flow	Briefly describe the overall project flow and detect the current phase by reading the Phase document.
Create	Project_Create	Scaffold project folder, README.md, AGENTS.md, Phase.md. Referenced in §1 but doesn’t exist yet.
Requirements	Project_Requirements	Guide the agent through organizing user input into the Requirements format. Enforce structure (Vision/Problem, numbered requirements, verification criteria, out of scope).
Research	Project_Research	Investigate options, present decision points, record findings in the Research document format. Enforce historical (append-only) discipline.
Spec	Project_Spec	Convert approved Research decisions into a declarative Spec. Validate that it’s self-contained and covers all Requirements.
Plan	Project_Plan	Break Spec into atomic Plans. Validate each Plan is self-contained (the implementing agent reads only Plan + State + WIP). Enforce the context boundary rule.
Implement	Project_Implement	Execute a Plan step-by-step: create State from Plan, implement tasks, record Learnings, maintain WIP. This is the core execution skill.
Evaluate	Project_Evaluate	Fresh-agent evaluation protocol: read Plan + State + Learnings, produce defect/variance report comparing implementation to Plan intent, process user decisions.
Fix	Project_Fix	Fixing is implementation work triggered by evaluation. The evaluation report becomes new State tasks.
Repeat	—	No separate skill; reuse Implement, Evaluate, and Fix for each remaining Plan.
Check	Project_Check	Final evaluation: verify all Verification Criteria, check Spec compliance, create corrective Plan if needed.
Extract	Project_Extract	Identify extractable knowledge/skills from the project, write them to permanent locations (department Knowledge, Skills, Guides), ensure nothing useful is trapped in the project folder.
Complete	Project_Complete	Archive, publish, or approve the project per §7. Move to Archived/, set status to published, or set status to approved. Clean up WIP, finalize all document statuses.
General	Project_Archive	Archive or unarchive a project after completion. Uses Project_Complete for archiving; provides unarchive procedure.
General	Project_Rename	Change the name of the project or move it to another department, which means renaming all files and reviewing their contents for necessary updates

---

13. Global Front Matter Convention

All YAML front matter across the project system must use these fields in this order:

Field	Format	Required
Status	draft, review, approved, published, archived	Yes
Visibility	internal, public, private	Yes
Owner	email	Yes
Approver	email	Yes (may be empty string)
Created	YYYY-MM-DD	Yes
Updated	YYYY-MM-DD	Yes

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

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: Requirements

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 §3.1. README.md and AGENTS.md are updated.

Phase 3: 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 §3.2.

Phase 4: 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 §3.3.

Phase 5: 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 §3.4.

Phase 6: Implement

When implementation of a Plan begins, a matching State document is created with a todo list. The agent implements step by step. 1) It checking off items in the State. 2) It appending steps taken, file paths touched, commands run, errors encountered in a WIP file which is an ephemeral scratchpad for crash recovery. 3) It records obstacles and solutions in the Learnings file. See §3.5, §3.6.

Phase 7: Evaluate

A fresh agent (new session) evaluates whether the Plan was implemented correctly by comparing the implementation to the Plan’s intent. Produces a list of defects, variances, and learnings to store. See §7.1.

Phase 8: Fix

Implements the fixes identified during evaluation. Defects are fixed and necessary variances are captured by updating the Requirements and/or Spec. Learnings entries are incorporated into permanent documents and the Learnings file is cleared.

Phase 9: Repeat

Repeat phases 6–8 for each remaining Plan. Later Plans may be revised based on evaluation of earlier Plans before implementation begins.

Phase 10: Check

A fresh agent verifies the complete implementation against Requirements and Spec and makes minor fixes or creates another Plan if necessary.

Phase 11: Extract

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

Phase 12: Complete

Archive or publish the project. See §7.

---