Forge Project Plan 2 — Definition Phase Skills

Scope: Create the Phase template and the 4 skills for the definition phases: Requirements, Research, Spec, and Plan (Project_Create_Plan). All skills must create and update the Phase document. Spec: Forge Project Spec Prior plan: Plan 1 — Templates & Foundation

---

Task 1 — Create the Phase_Template.md and Update Project_Create Skill

The Phase document tracks the project’s current phase (Spec §3.3). It must be created alongside README and AGENTS in Create, and updated by every project skill at phase transitions.

1. Create Forge/Skills/Project_Create/templates/Phase_Template.md with the structure defined in Spec §3.3:
   • YAML frontmatter (6 required fields)
   • H1 with project title
   • Human-readable header table mirroring frontmatter
   • Phase: CreateStarted as the initial value
2. Update Forge/Skills/Project_Create/SKILL.md:
   • Add Step 3a: Create {Project}_Phase.md from Phase_Template.md between README and AGENTS creation
   • Add sidebar entry for Phase.md
   • Update Rules section to mention Phase.md as a minimum viable project file alongside README and AGENTS
3. Update Forge/Skills/Project_Flow/SKILL.md:
   • Replace the document-existence-based Phase Detection table with Phase-document-based detection
   • The Phase value {PhaseName}_Started / {PhaseName}_Completed directly indicates the current phase
   • Example: Phase: RequirementsCompleted → next action is Research; Phase: ResearchStarted → continue Research
   • Add rule: always read the Phase document first to determine the current phase
4. Add sidebar entry for Phase_Template in .internal/astro.config.mjs
5. Run cd .internal && npm run build to verify
6. Commit

---

Task 2 — Create the Project_Requirements Skill

Requirements skill. Guides the agent through organizing user input into the Requirements document format.

Create Forge/Skills/Project_Requirements/SKILL.md with:

• When to Use: When a project exists (Create complete) and needs its Requirements defined.
• Inputs: Project path, user-provided vision/problem statement and requirements
• Procedure:
  1. Read the user’s input (vision/problem, requirements, constraints)
  2. Copy Forge/Skills/Project_Create/templates/Requirements_Template.md to {Dept}/Projects/{Project}/{Project}_Requirements.md
  3. Fill in the template: Vision or Problem section, Background (if needed), numbered Requirements (R1, R2…), Success Criteria table (V1, V2… — one per requirement), Out of Scope
  4. Present the draft to the user for review and iterate
  5. Update README.md and AGENTS.md to reference the Requirements doc
  6. Update {Project}_Phase.md: set Phase: RequirementsStarted at the start, Phase: RequirementsCompleted when done
  7. Add sidebar entry, build, commit
• Rules:
  • The user is the primary author; the agent organizes, clarifies, and augments
  • Requirements are brief and problem-focused — state what is needed, not how
  • Undecided items are permitted — they are resolved during Research
  • Each Requirement gets a matching Verification Criterion
  • Once Plans exist, existing requirements must not be renumbered or removed — retired requirements are annotated [Not required], new ones appended

---

Task 3 — Create the Project_Research Skill

Research skill. Investigates implementation options, presents decision points, and records findings.

Create Forge/Skills/Project_Research/SKILL.md with:

• When to Use: When Requirements are approved and implementation options need to be investigated.
• Inputs: Project path, Requirements document
• Procedure:
  1. Read the Requirements document
  2. Copy Forge/Skills/Project_Create/templates/Research_Template.md to {Dept}/Projects/{Project}/{Project}_Research.md
  3. For each requirement or group of related requirements that need investigation:
     • Research implementation options (web search, docs, existing codebase)
     • Document findings, options with pros/cons, and a recommendation
     • Mark the Decision subsection as pending user approval
  4. Present all decision points to the user for review
  5. Record user decisions with “Decided by: @name — date” attribution
  6. All decisions must be approved before proceeding to Spec phase
  7. Update {Project}_Phase.md: set Phase: ResearchStarted at the start, Phase: ResearchCompleted when done
  8. Add sidebar entry, build, commit
• Rules:
  • Research is historical/append-only — never replace existing sections
  • When decisions change, append a dated revision note
  • Decision points must be clearly marked and easy to review
  • Each decision records who decided and when
  • If a requirement has an obvious solution with no alternatives, document it briefly and mark as decided

---

Task 4 — Create the Project_Spec Skill

Spec skill. Converts approved Research decisions into a declarative Spec document.

Create Forge/Skills/Project_Spec/SKILL.md with:

• When to Use: When all Research decisions are approved and the project needs a Spec.
• Inputs: Project path, Requirements document, Research document
• Procedure:
  1. Read Requirements and Research documents
  2. Verify all decision points in Research are resolved (no pending decisions)
  3. Copy Forge/Skills/Project_Create/templates/Spec_Template.md to {Dept}/Projects/{Project}/{Project}_Spec.md
  4. Write the Spec as a declarative description of the ideal final state, organized by major areas
  5. Validate: every Requirement is addressed, the Spec is self-contained (a reader can understand the target system from it alone), it describes what not how
  6. Present to user for approval
  7. Update {Project}_Phase.md: set Phase: SpecStarted at the start, Phase: SpecCompleted when done
  8. Update README.md and AGENTS.md
  9. Add sidebar entry, build, commit
• Rules:
  • 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
  • May reference specific Research sections when procedural rationale is important
  • Updated retroactively when evaluation reveals necessary deviations (it’s evergreen)
  • Can be repurposed as permanent documentation after project completion

---

Task 5 — Create the Project_Create_Plan Skill

Plan skill (Project_Create_Plan). Breaks the Spec into one or more atomic Plans, each implementable in a single agent session.

Create Forge/Skills/Project_Create_Plan/SKILL.md with:

• When to Use: When a Spec is approved and needs to be broken into implementable Plans.
• Inputs: Project path, Requirements document, Research document, Spec document
• Procedure:
  1. Read Requirements, Research, and Spec
  2. Identify natural breakpoints — the Spec should decompose into units that can each be completed in a single focused agent session
  3. For each Plan:
     • Copy Forge/Skills/Project_Create/templates/Plan_Template.md to {Dept}/Projects/{Project}/{Project}_Plan_{Qualifier}.md
     • Name by phase or feature: Plan_Spec, Plan_Authentication, etc.
     • Write Tasks with enough context that the implementing agent never needs to consult Requirements, Research, or Spec (the self-containment rule)
     • Include any relevant content from Research that the Spec references
  4. Validate self-containment: for each Plan, verify an agent could implement it with only the Plan, State, and WIP
  5. Present Plans to user for approval
  6. Update {Project}_Phase.md: set Phase: PlanStarted at the start, Phase: PlanCompleted when done
  7. Add sidebar entries, build, commit
• Rules:
  • Each Plan must be implementable in a single focused agent session
  • Plans are self-contained: the implementing agent reads only Plan + State + WIP
  • Plans do not contain checkboxes — that’s the State’s role
  • Plans are frozen once implementation begins — corrections produce new State tasks, not Plan edits
  • Later Plans are tentative and may be revised based on evaluation of earlier Plans

---

Task 6 — Sidebar and Index Registration

Register all 4 new skills plus the Phase template.

1. Add Project_Requirements, Project_Research, Project_Spec, Project_Create_Plan to Forge/Skills/index.md
2. Add all 4 to the Skills List in Forge/Configs/FORGE.md (alphabetical order)
3. Add sidebar entries in .internal/astro.config.mjs for the 4 skills and the Phase template
4. Run cd .internal && npm run build to verify
5. Commit all files together