Uvilo OS Spec

archived Visibility internal Owner erik@uvilo.com Approver _ Created _ Updated _

1. Purpose

This document is the definitive specification for the uvilo-os repository — the single source of truth for Uvilo as a company. It covers repository structure, naming conventions, project folder layout, editing workflow, branching model, infrastructure, and the agentic execution system that allows AI agents to autonomously implement projects across multiple sessions.

This spec was derived from the Requirements and Research documents in this folder.

2. What Uvilo OS Is

uvilo-os is the corporate operating system of Uvilo. It contains:

Company vision, mission, values, and strategy
Product architecture, specs, prompts, and outputs
Process documentation and automation scripts
Skills used by AI agents to perform work
Operational learnings accumulated over time
The assistant infrastructure used to manage and evolve all of the above

It is designed to be readable and editable by humans and AI agents alike, version-controlled via Git, and publishable as one or more websites. AI agents can autonomously implement large projects across multiple sessions, with each session picking up where the last left off.

3. Repository Name and Location

Repository name: uvilo-os
GitHub organization: Uvilo
Local working root: uvilo-os/ (currently synced via Google Drive)
Canonical branch: dev (in the short term)

4. Top-Level Structure

uvilo-os/
├── Forge/          # AI assistant infrastructure (skills, lessons, knowledge, configs)
├── Architecture/       # Product architecture (quizzes, taxonomy, onboarding, methodology)
├── Content/            # Content projects (copy, articles, in-app text)
├── Design/             # Design projects (UI, brand, visual assets)
├── Finance/            # Financial planning and reporting
├── Investors/          # Investor relations, pitch materials, updates
├── Marketing/          # Marketing campaigns, SEO, growth
├── Operations/         # Internal processes, HR, legal, compliance
├── Planning/           # Strategic planning, OKRs, roadmaps
└── Technology/         # Engineering, infrastructure, integrations

Each top-level folder is a department. Departments contain projects inside Department/Projects/. Projects are the unit of work.

5. Naming Conventions

General rule

All folder and file names use Title_Case_With_Underscores — each word capitalized, joined by underscores (e.g. Onboarding_Quiz_Spec.md, Extract_Persistent_Memory_Prompt.md).

Ampersands and other punctuation are preserved as-is (e.g. Process_&_Docs_System).

Document titles (in frontmatter title: and # H1) use normal spaces and capitalization — the filename and title do not need to match exactly.

Project-name prefix

All documents at a project’s root level are prefixed with the project name: {Project_Name}_{Document_Type}.md (e.g. Onboarding_Quiz_Spec.md, Taxonomy_Research.md). This ensures files are identifiable when open alongside files from other projects.

Exceptions

File type	Convention	Example
Scripts (`.ts` or `.sh` written for this repo)	`lowercase_with_underscores`	`generate-toc.ts`, `release.sh`
Schemas (Zod v3, `.ts`)	PascalCase + `Schema` suffix	`OnboardingQuizSchema.ts`, `AnalyzeLifeDomainQuizSchema.ts`
Codebase `.ts` files (non-schema, copied from app source)	PascalCase preserved	`UploadQuizSchema.ts`
`SKILL.md`	Always uppercase filename	`SKILL.md`
`.pdf` / `.docx`	Natural names, spaces preserved	`The Uvilo Method.pdf`
`Project_Name_History.md`	Project prefix + `_History`	`Uvilo_OS_History.md`
`Project_Name_WIP.md`	Project prefix + `_WIP`	`Uvilo_OS_WIP.md`

6. Project Folder Structure

Every project follows this standard layout. Subfolders and optional files are created only when needed — not by default:

Department/
└── Projects/
    └── Project_Name/
        ├── Project_Name_State.md          # Living progress doc — todo list, output summary
        ├── Project_Name_History.md          # Compressed summaries of each completed session
        ├── Project_Name_WIP.md              # Running detailed log during active session (scratchpad)
        ├── Project_Name_Requirements.md   # What the project must do; constraints; success criteria
        ├── Project_Name_Research.md       # Options evaluated; rationale; rejected approaches
        ├── Project_Name_Spec.md           # Definitive design — derived from Research
        ├── Project_Name_Plan.md           # Implementation plan — derived from Spec (one or more)
        ├── Project_Name_History.md        # Historical narrative of the project (optional)
        ├── Lessons.md                     # Operational learnings (create when first lesson arises)
        ├── Prompts/                       # (create when first prompt is added)
        │   └── Prompt_Name_Prompt.md
        ├── Schemas/                       # (create when first schema is added; Zod schemas in .ts)
        │   └── SchemaNameSchema.ts
        ├── Scripts/                       # (create when first script is added)
        │   └── script_name.ts / .sh
        ├── Skills/                        # (create when first skill is added)
        │   └── Skill_Name/
        │       └── SKILL.md
        ├── Output/                        # (create when first output is produced)
        │   └── descriptive_name.ext
        ├── Test_Runs/                     # (create when test/sample runs need to be kept)
        │   └── Name_v1.json
        └── Archive/                       # (create when first item is archived)
            └── <previous versions>

Document progression

Projects follow a natural document progression:

Requirements — written first; defines scope, constraints, success criteria
Research — pre-spec document; evaluates options, records rejected approaches with references, justifies the chosen solution; keeps the Spec free of abandoned ideas
Spec — clean definitive design derived from Research; the reference during execution
Plan — implementation plan derived from a Spec; breaks the Spec into actionable tasks with ordering and dependencies. A Spec may have one or more Plans. Plans drive the State document’s task lists. Simple projects where the Spec is small enough to execute directly may skip Plans entirely.

Not every project needs all four. Simple projects may start directly at Spec. The progression exists to capture reasoning, not to create paperwork.

Project state files

Each project maintains up to three files for cross-session continuity. These allow any agent to resume work from any prior session without reading the full conversation history.

`Project_Name_State.md` — Primary state document

The State document is a living markdown file that tracks project progress. It is the primary source of truth for what has been done and what remains. Both humans and agents read and update it.

Structure:

# Uvilo OS Spec

## Status

In Progress

## Output Summary

- `File_Name.ext` — what it is
- Other deliverables listed here

## Todo

### Section Name

- [x] Completed task
- [ ] [STARTED] Task that is in progress — optional notes after dash
- [ ] Task not yet started
- [ ] [BLOCKED] Task waiting on something — reason for block

Todo item conventions:

Checkbox	Prefix	Meaning
`- [ ]`	(none)	Not started
`- [ ] [STARTED]`	`[STARTED]`	In progress — an agent has begun work on this
`- [x]`	(none)	Done
`- [ ] [BLOCKED]`	`[BLOCKED]`	Waiting on a dependency or external input

The prefix tags [STARTED] and [BLOCKED] appear immediately after the checkbox, before the task title. When a started task is completed, remove the [STARTED] prefix and check the box. Sub-items use standard markdown nesting (2-space indent).

`Project_Name_History.md` — Cross-session memory

A compressed summary of each completed session, written by the agent at the end of each session (or by the crash-recovery process). Provides context for the next agent without requiring it to read the full working log.

## Session 2026-03-10 14:00 — 14:45
**Model**: claude-sonnet-4
**Tokens**: ~45,000
**Summary**: Created taxonomy entries for Business, Caregiving, School,
Parenting domains. Fixed semicolon delimiter issue in CSV.
**State changes**: Marked "Create taxonomy entries" done. Started "Generate TaxonomyMap entries."

## Session 2026-03-11 09:00 — (in progress)
**Model**: claude-sonnet-4
**Summary**: Generating TaxonomyMap entries for new domains.
Business and Caregiving complete.

`Project_Name_WIP.md` — Running scratchpad

A detailed operational log written during a session — file paths edited, commands run, errors encountered, decisions made. This is the raw material from which the session summary is distilled. It gets long and messy, and that is expected. Its primary purpose is crash recovery: if a session is interrupted, the next agent can see exactly where things were left.

The working log is cleared or archived at the start of each new session.

Output folder

The Output/ folder holds artifacts produced by the project — generated files, published documents, analysis results. Output files use descriptive names; versioning is handled by Git.

Output/
├── Taxonomy.csv
├── The_Uvilo_Method.md
└── onb_general.json

7. Skills

Where skills live

Skills are co-located with the project they serve:

Product/Projects/Taxonomy/Skills/taxonomy_builder/SKILL.md
Product/Projects/Onboarding_Quiz/Skills/quiz_evaluator/SKILL.md

Skills that are genuinely cross-project (e.g. general markdown processing) live in Forge/Skills/.

Cross-project skills

Skill	Location	Purpose
`Create_New_Version`	`Forge/Skills/Create_New_Version/SKILL.md`	Cut a new version of a versioned project — archives current files and increments `version` in frontmatter

What a SKILL.md contains

SKILL.md files are thin pointers, not self-contained knowledge bases. A skill tells an agent where to find the information it needs — it does not duplicate it:

# Skill: Taxonomy Builder

## Purpose
Build and extend the Uvilo taxonomy.

## When to use
- Adding new taxonomy items or domains
- Validating taxonomy structure
- Generating TaxonomyMap entries

## Key files
- Spec: `Architecture/Taxonomy/Spec.md`
- Schema: `Architecture/Taxonomy/Schemas/TaxonomySchema.ts`
- Scripts: `Architecture/Taxonomy/Scripts/validate_taxonomy.py`

## Notes
See Lessons.md in this folder for known gotchas.

Skills are LLM-agnostic. They contain no Claude-specific syntax or assumptions.

8. Lessons

Where lessons live

Operational learnings are co-located with the project they belong to, in Lessons.md:

Product/Projects/Taxonomy/Lessons.md
Product/Projects/Onboarding_Quiz/Lessons.md

Cross-project lessons (tool behavior, general workflow discoveries) live in Forge/Lessons.md.

What belongs in Lessons.md

Workarounds discovered through trial and error
Correct syntax or commands found after failures
Tool behavior that differs from expectations
Corrections from the user that change how work is done

What does not belong:

Obvious or standard behavior
Information already captured in the Spec
Raw debug logs

9. Document Frontmatter

All markdown documents include YAML frontmatter:

---
title: "Document Title"
visibility: internal        # internal | public
status: archived
owner: "erik@uvilo.com"
tags: [product, onboarding]
last_reviewed: 2026-03-07
version: 1                  # optional — only for versioned projects
---

Field	Values	Purpose
`title`	String	Human-readable title; used in site navigation
`visibility`	`internal` / `public`	Controls which published site includes this doc
`status`	`draft` / `review` / `approved`	Tracks maturity; does not affect publishing
`owner`	`email`	Accountable person for this document
`tags`	Array	Used for filtering and search
`last_reviewed`	ISO date	When the content was last verified as current
`version`	Integer	Optional. Only used for projects with explicit versioned releases (e.g. published methodology, API schemas, quiz formats consumed by external systems). Omit entirely for projects that do not version.

10. The Assistant Folder

Forge/ contains the infrastructure for AI agents operating on uvilo-os. It is self-contained and does not duplicate content from other folders.

Forge/
├── instructions.md         # Agent operating contract (tool use, project system, constants)
├── Lessons.md              # Cross-project operational learnings
├── Knowledge/              # Stable cross-project reference (index + domain files)
│   └── uvilo.md
├── Skills/                 # Cross-project skills only
│   └── Skill_Name/
│       └── SKILL.md
└── Configs/                # Infrastructure configuration files
    ├── librechat.yaml
    ├── Dockerfile.librechat
    └── startup.sh

The agent operating instructions are documented in Forge/instructions.md.

11. Editing Workflow

All editing — by humans and AI agents — happens through browser-based interfaces hosted on Railway. No local (on the user’s machine) tooling, Git clients, or filesystem access is required.

Editing surfaces

Surface	Use case
LibreChat	AI-driven editing, generation, iterative refinement, autonomous project execution
TinaCMS (local mode)	Manual WYSIWYG edits, review, small corrections

Both surfaces read and write to the same per-user working directory on Railway. A user can switch between them freely within a session.

Session workflow

Start session — LibreChat creates a branch (e.g. work/erik/taxonomy-spec-2026-03-07) and ensures the working directory is current (git pull)
Edit freely — via LibreChat chat, or TinaCMS browser UI; files may be incomplete or inconsistent mid-session; no commits happen automatically
End session — user tells LibreChat to commit; LibreChat runs git commit, pushes the branch, and opens a draft Pull Request against main
Review and merge — PR is reviewed (via GitHub UI or LibreChat); merged when approved; main is updated; CI rebuilds published sites

Branch naming

Scenario	Pattern	Description
Working session	`work/<user>/<topic>-<date>`	A human-led session (with or without AI assistance)
AI agent task	`agent/<task>-<date>`	An autonomous agent run initiated programmatically
Hotfix / small edit	`fix/<user>/<topic>`	Small targeted correction outside a full working session

Neither agents nor humans ever commit directly to main.

Stale branches (no activity for 30 days) are deleted automatically via GitHub Actions.

12. Agentic Execution System

The agentic execution system — architecture, session workflow, crash recovery, human-in-the-loop mode, and model flexibility — is now maintained as its own project.

→ See Agentic Execution Spec for the full specification.

13. Infrastructure

Component	Role
GitHub (`uvilo-os` repo)	Canonical source of truth; version history
Vercel	Hosts the internal documentation site; preview deployments from `dev` branch
Railway persistent volumes	Per-user working directories (Git clones) for LibreChat
MCP servers	Filesystem + Git access for LibreChat editing
LibreChat Agents API	Programmatic interface for the orchestrator to invoke agents
Orchestrator	Python script on Railway that chains agent sessions across projects
GitHub Actions	CI/CD: builds site on merge to `main`; stale branch cleanup
Astro Starlight	Generates the documentation site (in `.internal/` subfolder)
Pagefind	Client-side full-text search (ships with Starlight)
Typesense (future)	Server-side semantic search for AI RAG

Published site

The internal documentation site is built from the repository using Astro Starlight and deployed to Vercel. Access is restricted to Uvilo team members via Vercel Authentication.

Internal site — all documents; deployed to Vercel behind Vercel Authentication
Custom domain: os.uvilo.com (points to dev branch preview deployments)
Starlight project: .internal/ subfolder (hidden from repo root)
Starlight plugins:
- starlight-theme-nova — modern theme with custom colors and fonts
- starlight-giscus — GitHub Discussions comments on every page
- starlight-llms-txt — generates /llms.txt, /llms-full.txt, /llms-small.txt
- starlight-auto-sidebar — sidebar group customization
- astro-mermaid — mermaid diagram rendering in markdown code blocks
- astro-vtbot/viewTransitions — browser-native cross-document view transitions
Custom markdown plugins (.internal/src/plugins/):
- remark-resolve-relative-links.mjs — rewrites relative .md links to Starlight route URLs
- rehype-external-links.mjs — adds target="_blank" rel="noopener noreferrer" to external links
Dependency pinning: All dependencies in package.json use exact versions (no ^ or ~ ranges)
Custom component overrides: Pagination.astro — composes giscus Comments + Nova Pagination
Public site — postponed until content is ready for external visibility

14. GitHub Repository

URL: https://github.com/ErikDakoda/uvilo-os (private)
Default branch: main
Working branch: dev — all daily work happens here; pushes trigger Vercel previews
Branch protection on main: require PR, no direct pushes
Initial commit: 2026-03-07 — Uvilo OS restructure complete

GitHub is the source of truth. The Google Drive folder remains as a working copy synced via git.

The current workflow uses dev as the primary branch. main is dormant and will be fast-forwarded to dev occasionally. When the team grows, main will become the review/approval gate with PRs from dev.

Requirements — what this system must do
Research — options evaluated; approach selected; agentic execution research
Infrastructure Plan — Railway deployment, MCP servers, volume setup
State — living progress tracker