Forge Document Structure
How files and folders are organized in a Forge repository: naming rules, hierarchy, sidebar structure, and required files.
Golden Rule
The sidebar hierarchy must mirror the filesystem hierarchy. The sidebar must contain a collapsed subgroup for each folder and a sidebar entry for each file. The order of files, however, is not alphabetical, but follows the convention README → AGENTS → Archived/ → Projects/ → Skills/ → Configs/ → Assets/ → Output/ → Function A/ → Function B/ → {etc} → Other Folders/ → Other Files. Not all folders contain all of those items.
Folder Types
| Folder | Contains | Where |
|---|---|---|
| Department | Everything for an area of the organization | Root |
| Function | Documentation and automation for a sub-division of a Department | Department or Function |
| Project | Vision, specs, and implementation of a project | Projects/ folder in each Department |
| Skill | Agent instructions for accomplishing a task | Skills/ folder in a Department or a Function |
Infrastructure Files
| File | Purpose | Where |
|---|---|---|
AGENTS.md | Canonical context file for both agents and humans — project description, related skills, documents, knowledge sources, and key principles | Department, Function, Project |
README.md | Optional human-oriented description and getting started. Eliminated where content overlaps with AGENTS.md (consolidate into AGENTS.md and remove README.md) | Department, Function, Project |
SKILL.md | Skill definition with related scripts and resources | Skill |
MEDIA.md | Auto-generated image galleries | Any folder |
Frontmatter Convention
All Forge markdown files use YAML frontmatter with these required fields, in this order:
| Field | Required | Description |
|---|---|---|
title | Yes | Document title |
visibility | Yes | internal or public |
status | Yes | published, draft, or archived |
owner | Yes | Owner email (e.g., erik@uvilo.com) |
approver | Yes | Approver email or empty string |
Date fields (created, updated, lastUpdated) are not used in frontmatter. Creation and modification dates are sourced from git history and filesystem metadata, eliminating manual maintenance burden and preventing stale or impossible date values.
Skill files (SKILL.md) use name, description, title, visibility, status, owner, and tags instead of title and approver — see any existing SKILL.md for the pattern.
File Naming
- All file names must be prefixed with the Department, Function, or Project name, except infrastructure files.
- All file names must be title case, spaces replaced by underscores, except infrastructure files MUST be uppercase.
Here are examples of an infrastructure file and a non-infrastructure file. Other files of the same type follow the same rules:
| File | Name on disk | Frontmatter title AND Heading 1 | Sidebar label |
|---|---|---|---|
| Infrastructure files | README.md | Forge README | README |
| Other files | My_Project_Spec.md | My Project Spec | Spec |
Example Department Folder Hierarchy
Example Department Sidebar Hierarchy
Departments
Departments hold everything for an area of the organization and they live in the project root. Canonical ordering of departments:
Forge → Organization → Product → Technology → Marketing → Planning → Operations → Finance → Investors
Projects
Projects live at {Department}/Projects/{Project}/ and follow the Forge Project Workflow lifecycle. Canonical order of projects in a Projects/ folder is alphabetical.
Canonical order of a Project’s files/folders in the sidebar (follows the project lifecycle — every document type must appear in this order, omitting any that don’t exist yet):
- README
- AGENTS
- Phase
- Vision
- Vision_Eval
- Research
- Spec
- Spec_Eval
- Plan 1 → Plan_Eval → Execute_State 1 → Execute_Eval 1
- Plan 2 → Execute_State 2 → Execute_Eval 2
- Plan N → Execute_State N → Execute_Eval N (repeat for each plan)
- Verification
- Extract_Eval
- Learnings
- Runs
- Changelog
- Audit_Results
- Resources/ (or References/)
- Other Folders/
- Other Files
Sidebar ordering rules:
- Items must follow the canonical lifecycle order above — never alphabetical
- Plan_Eval follows Plan 1 (it evaluates all plans before execution begins)
- Each Execute_State and Execute_Eval immediately follows its corresponding Plan
- Verification follows the last Execute_Eval
- Learnings, Runs, Changelog, and Audit_Results follow Verification in lifecycle order
- Non-standard project files (e.g., Ambiguities, Charter_Alignment) come after Changelog, before References/
- The sidebar label for README must be “README”, not the project name
Files and folders are created as they are needed. Once a project is completed, all of its knowledge and skills are extracted into Functions and Skills, and its files are marked approved. It may remain in the Projects/ folder for a while before it’s archived.
Functions
Functions are used to sub-divide departments into logical functions and they live at {Department}/{Function}/. They contain knowledge documents, user guides and skills to automate the Function.
Canonical order of a Function’s files/folders in the sidebar: README → AGENTS → Skills/ → Resources/ → (sub)Function A/ → (sub)Function B/ → {etc} → Other Folders/ → Other Files
Files and folders are created as they are needed. Functions within a department contain the single source of truth for Department knowledge and automation. They must be kept up to date as systems evolve and are only archived if they become obsolete.
Skills
Skills live at {Department}/Skills/{Skill}/ and {Department}/{Function}/Skills/{Skill}/ and {Department}/{Function}/{(sub)Function}/Skills/{Skill}/. Canonical order of skills in a Skills/ folder is alphabetical.
File-View Pages
Non-Markdown files (.ts, .json, .py, .sh, .csv, .html, etc.) are displayed via auto-generated file-view pages. Image files (.png, .jpg, .jpeg, .gif, .svg, .webp, .ico) are not displayed individually, but per-folder MEDIA.md gallery pages are auto-generated. Supported file types can be changed in Forge/Skills/Manage_Pages/view_folder_config.json.