Skip to content
Uvilo OS
published Visibility internal Owner erik@uvilo.com Approver _ Created _ Updated _

Project Spec

When to Use

When all Research decisions are approved and the project needs a Spec.

Inputs

  • Project path ({Dept}/Projects/{Project}/)
  • Vision document
  • Research document

Prerequisite

HARD GATE: Verify {Project}_Vision.md exists and contains R-numbered Requirements (R1, R2, …) and V-numbered Success Criteria (V1, V2, …). If the file is missing or lacks R-numbers/V-criteria, STOP and report: “Vision document is missing or not a valid Vision (no R-numbered requirements found). Create the Vision first.”

Context Boundary

Read only: Vision and Research. Plans and State do not exist yet.

Procedure

  1. Read Vision and Research documents
  2. Verify all decision points in Research are resolved. If there are pending decisions, let the user know and stop.
  3. Copy Forge/Forge_Project/Skills/Project_Create/templates/Spec_Template.md to {Project}_Spec.md in the project folder
  4. Update {Project}_Phase.md: set Phase: Spec_Started
  5. Write the Spec as a declarative description of the ideal final state, organized by major areas
  6. If there are procedural steps in Research that you want to refer to, put the minimum information required in a file in {Project}/References/ and link to it
  7. Validate: every Requirement is addressed, the Spec is self-contained, it describes what not how, and exact content from Research is linked via References/ not paraphrased
  8. Add sidebar entry by spawning the Page Manager bot via spawnAgent with { botGroup: 'forge', botHandle: 'page-manager' }
  9. Set document status to review
  10. Update {Project}_Phase.md: set Phase: Spec_Completed
  11. Build, commit, push
  12. Proceed directly to Spec_Eval — do not wait for user approval before evaluation. Spawn the Project Evaluator.
  13. After Spec_Eval converges (no findings, or all findings auto-resolved), present the final Spec to the user for approval
  14. Iterate on any remaining user feedback
  15. Set document status to approved
  16. Update README.md and AGENTS.md
  17. Build, commit, push

Rules

  • Declarative, not procedural — describes the target state and behaviors, not the steps to build them. Describing what a command/tool produces (inputs → outputs → guarantees) is behavioral description, not implementation procedure
  • Self-contained — a reader can understand the target system from the Spec alone and linked references
  • Exact content preserved — when Research or Vision specifies exact text (prompts, configs, messages), link to it via References/ rather than paraphrasing. A reader must never need to re-invent precise content from a description
  • May reference the Research document. Extract the exact needed content into the Spec or a References/ file — only what the Spec requires, nothing more
  • Updated retroactively when evaluation reveals necessary deviations (Spec is evergreen)
  • Can be repurposed as permanent documentation after project completion