Project Execute

When to Use

A Plan is approved and ready for execution.

Inputs

• Project path: {Dept}/Projects/{Project}/
• Plan document: {Project}_Plan_{N}.md

Context Boundary

Read only the current Plan, Execute_State, and Changelog. Never read Vision, Research, Spec, or Execute_Eval reports. If the Plan is missing context, stop and escalate — that is a Plan authoring failure.

Procedure

1. Read the Plan document

2. Scaffold missing project documents by spawning the Page Manager bot via spawnAgent with { botGroup: 'forge', botHandle: 'page-manager' } — pass template, target path, and sidebar placement for each:

   • Execute_State: Execute_State_Template.md → {Project}_Execute_State_{N}.md, sidebar after Plan {N}
   • Learnings: Learnings_Template.md → {Project}_Learnings.md, sidebar after Execute_State
   • Changelog: Changelog_Template.md → {Project}_Changelog.md, sidebar after Learnings Skip any that already exist (file and sidebar entry both present). Then replace {variable} placeholders with their values and convert Plan tasks into Execute_State checkboxes.

3. Update {Project}_Phase.md: set Phase: Execute_{N}_Started

4. Build, commit, push

5. If a crash occurred (session interrupted), recover from the Phase file, current Execute_State, durable work-products, persisted conversation/AgentJob metadata, and git status

6. If Execute_State has checked tasks, continue with the next 🟨 (started), ✴️ (unverified), or ⬜ (empty) task

7. Execute one task and its subtasks in order:

   • Mark the task 🟨 (started) in Execute_State

   • Mark the first subtask 🟨 (started) in Execute_State

   • Execute the subtask’s procedural steps

   • Append each file touched to the Changes table in Changelog:

     • File: Filename (not full path) as a Markdown link to its page on the site (URL derived from file path per URL rule). For infrastructure files (README.md, AGENTS.md, SKILL.md, MEDIA.md), include the direct parent folder in the link text (e.g., Manage_Pages/SKILL.md). Deleted files shown as plain text without a link.
     • Action: Added / Modified / Deleted
     • Version: The 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

   • If an obstacle or unexpected decision occurs, add an entry to Learnings (L1, L2…)

   • If an obstacle that prevents you from implementing the subtask occurs, mark the subtask 🚫 (blocked) and move on to the next subtask

   • Once implemented, mark the subtask ✴️ (unverified)

   • Verify that the subtask was completed correctly

   • Mark the subtask ✅ (done) or leave it unverified if verification needs to be postponed

8. Once all subtasks within the one task are completed:

   • Mark the task 🚫, ✴️, or ✅ based on the lowest subtask status

   • Verify the Changes table in Changelog is complete and accurate for this task

   • Build, commit, push

   • Proceed to executing the next task

9. Once all tasks are completed, update {Project}_Phase.md: set Phase: Execute_{N}_Completed

10. Set Plan and Execute_State document status to review

11. Build, commit, push

Todo conventions

Prefix	Meaning
[ ] ⬜	Empty
[ ] 🟨	Started
[ ] ✴️	Unverified (completed but unverified)
[ ] 🚫	Blocked
[x] ✅	Done (completed and verified)

Rules

• Context boundary is sacred — never consult Vision, Research, or Spec during execution.
• Scope decisions belong to the project owner. Never declare a finding, gap, or concern “out of scope” without explicit user approval. Flag it as “Pending user decision” and escalate.
• Each execution produces its own numbered Execute_State document ({Project}_Execute_State_{N}.md where N matches the Plan number). One Execute_State per Plan — never combine tasks from multiple Plans into a single Execute_State file.
• Recovery state is reconstructed from the Phase file, current durable work-products, persisted evaluation or verification reports, Execute state files, saved conversation or AgentJob metadata, git status, and relevant todo items.
• Learnings entries must specify a Destination for where the insight should permanently live.
• Use References/ to capture structured information gained during execution (service IDs, API tokens, connection strings, etc.). Never bury these in Learnings — put them in a reference file so they survive the session.
• There is no separate Fix phase — failed Execute_Eval returns to Execute for the same Plan, with corrective tasks already in Execute_State.
• Learnings must be cleared after incorporation — nothing stays in the temporary file.
• If a fix is too large to be a patch, recommend creating a new Plan instead.