Uvilo OS To Forge Spec

Research: Uvilo_OS_To_Forge_Research Plan Phase 1: Uvilo_OS_To_Forge_Plan_Phase_1 Plan Phase 2: Uvilo_OS_To_Forge_Plan_Phase_2

---

1. Goal

Rename and restructure the Uvilo OS repository to implement the Forge platform identity. The outcome is a cleaner, faster, more maintainable agent operating system with:

• A clear platform identity (Forge/) separate from product (Product/) and business departments
• System prompt optimized for LLM prompt caching (~83% token reduction vs. pre-refactoring)
• Consistent UPPERCASE naming for all internal infrastructure files
• Skill-level LESSONS.md files co-located with every SKILL.md
• Word-count budgets enforced across all always-loaded files
• Grep-based content discovery codified alongside glob-based name discovery
• LibreChat per-user memory enabled for personal context (Phase 2)

---

2. Target Repository Structure

uvilo-os/
├── Forge/                         # THE PLATFORM
│   ├── FORGE.md                   # Operating contract → inlined into Agent Instructions
│   ├── INDEX.md                   # Auto-generated directory listing
│   ├── README.md                  # Human-facing onboarding and access guide
│   ├── LESSONS.md                 # Universal rules (≤300 words, 4 entries)
│   ├── Knowledge/                 # INDEX.md, Constants.md, Tools/*.md
│   ├── Skills/                    # Cross-project skills (Deploy_Config, Artifacts, ...)
│   ├── Configs/                   # librechat.yaml, agent-sync.yaml, etc.
│   ├── Prompts/                   # MCP/Agent/Artifact instruction files
│   ├── Output/                    # One-off task workspace — Output_State.md, Output_History.md, Output_WIP.md
│   └── Projects/                  # Projects that BUILD the platform
│       ├── Sidebar_Reorg/
│       ├── Bash_Refactor/
│       ├── Libre_Agents/
│       ├── OpenRouter/
│       └── Uvilo_OS_To_Forge/     # This project
│       # ...and other platform projects
│
├── Product/                       # UVILO AI PRODUCT
│   └── Projects/                 # Product projects
│       ├── Taxonomy/
│       ├── Life_Domains/
│       ├── Onboarding_Quiz/
│       ├── Domain_Quiz/
│       ├── Uvilo_Method/
│       ├── Persistent_Memory/
│       └── Analytics/
│       # ...and other product projects
│
├── Finance/                       # BUSINESS DEPARTMENTS (unchanged)
├── Investors/
├── Marketing/
├── Operations/
├── Planning/
├── Technology/
└── Design/

Source folders being dissolved:

• Assistant/ → contents move to Forge/
• Uvilo_OS/ → setup docs → Forge/Knowledge/; prompts → Forge/Prompts/; AI Guide → Forge/Knowledge/
• Architecture/ → product projects move to Product/Projects/; platform projects move to Forge/Projects/

Onboarding content lives in Forge/README.md (human-facing access guide), not a separate Docs/ directory.

---

3. System Prompt Architecture

3.1 Three-Layer Pipeline

┌─────────────────────────────────────────────────────────┐
│  LAYER 1: CACHEABLE SYSTEM PROMPT                        │
│  MCP Server Instructions         ~270 words              │
│  + FORGE.md (inlined)          ~1,200 words              │
│  + Artifact pointer               ~50 words              │
│  + Artifact Instructions (med)   ~400 words              │
│  ─────────────────────────────────────────────────────── │
│  TOTAL                         ~1,920 words / ~2,500 tok │
│  Cached at ~10% cost per session                         │
├──────────── DYNAMIC BOUNDARY ────────────────────────────┤
│  LAYER 2: PER-SESSION DYNAMIC (loaded in PRE-WORK)       │
│  LESSONS.md + Knowledge/INDEX.md + State + History       │
│  + LibreChat memory injection                            │
│  ≈ 1,500–3,000 words / ~2,000–4,000 tokens              │
├──────────────────────────────────────────────────────────┤
│  LAYER 3: ON-DEMAND (loaded mid-session as needed)       │
│  Skills, Knowledge/Tools, project docs, grep results     │
│  ≈ 0–5,000 words (varies by task)                        │
└──────────────────────────────────────────────────────────┘

3.2 FORGE.md as Inlined Agent Instructions

• Source of truth: Forge/FORGE.md in the repo
• Deployment: /update-agents skill copies FORGE.md content into the LibreChat Agent Instructions field for multiple model variants
• Rationale: Prompt caching; eliminates the mandatory “read instructions.md” tool call at session start; consistent with Claude Code’s CLAUDE.md approach

3.3 Artifact Instructions

Location	Content	Size
Agent Instructions (appended)	Minimal pointer to Forge/Skills/Artifacts/SKILL.md	~50 words
LibreChat Artifact Instructions field	Medium-weight: directive syntax + type list	~400 words
Forge/Skills/Artifacts/SKILL.md	Full spec: all types, libraries, examples	≤500 words

Start with the medium-weight field override. Trim if artifact behavior is reliable; restore detail if not.

---

4. Naming Conventions

4.1 UPPERCASE Infrastructure Files

All files that agents read as part of their operating infrastructure use UPPERCASE names:

File	Purpose	Where
FORGE.md	Platform operating contract	Forge/FORGE.md
SKILL.md	Skill definition (thin pointer)	Per-skill folder
LESSONS.md	Operational learnings	Per-skill folder OR Forge/LESSONS.md
INDEX.md	Auto-generated file listing	Per-project (regenerable)
README.md	Human-written project description	Per-project (preserved)
AGENTS.md	Agent entry point for a project	Per-project (optional)

4.2 INDEX.md / README.md Split

File	Content	Who writes it	On generator regen
INDEX.md	Title + clickable file listing (folder tree)	Auto-generated	Fully replaced — no preservation
README.md	Title, parent/sub-projects, overview, operating guide	Human/agent written	Never touched by generator

The Sidebar Reorg generator is updated to produce INDEX.md instead of README.md. Any curated content from existing README.md files is preserved by migrating it before the generator runs.

4.3 Project Sidebar Naming and Order

Project files should appear in the sidebar using this exact naming and order, with no colons, hyphens, or other punctuation in the menu items:

1. Project INDEX
2. Project README
3. Project AGENTS (optional)
4. Project Requirements (optional)
5. Project Research
6. Project Spec
7. Project Plan (one or more)
8. Project State
9. Project History

Rules:

• Use the project name as the menu prefix (example: Uvilo OS To Forge Plan Phase 1)
• Plan files should be named as Project Plan <Qualifier> when needed (examples: Project Plan Phase 1, Project Plan Playwright)
• Do not use reversed forms such as Project Phase 1 Plan
• Project WIP should not be committed to source and should not appear in the sidebar
• If a file type is absent or optional, omit it without changing the relative order of the remaining items

4.4 AGENTS.md

Per-project agent entry point. Terse, technical, pointing to skills and key files. Follows the open agents.md standard. A root-level AGENTS.md at the repo root points to Forge/FORGE.md for tool auto-discovery (Cursor, Codex).

All projects should have an AGENTS.md. It should point to all project skills.

4.5 Project-Scoped Subdirectories

Projects may contain subdirectories beyond the standard State/History/WIP files:

Project_Name/
├── Skills/        # Project-specific skills (e.g., quiz authoring)
├── Scripts/       # Project-specific automation scripts
├── Schemas/       # Data schemas for the project
├── Output/        # Generated outputs (CSV, JSON, etc.)
├── Archive/       # Versioned snapshots (for versioned projects)
└── _temp/         # Disposable session scripts (trash after use)

Skills within projects follow the same SKILL.md + LESSONS.md convention as platform skills. Scripts co-located with their skill (e.g., Skills/Life_Domains/scripts/) stay in the skill folder.

---

5. Memory Architecture

5.1 File-Based Memory (Shared / Team-Scoped)

File	Scope	Loaded when
Forge/FORGE.md	All users, all sessions	Always (system prompt — cacheable)
Forge/LESSONS.md	All users, all sessions	Always (PRE-WORK)
Forge/Knowledge/Tools/*.md	All users, relevant sessions	On demand
SKILL.md + LESSONS.md	All users, when skill is active	On demand
Project_State.md, Project_History.md	All users on that project	Per-project session start
Project_WIP.md (gitignored — local session scratchpad)	Per-user machine only	During active session; cleared at session end

5.2 LibreChat Per-User Memory (Phase 2)

memory:
  disabled: false
  personalize: true
  tokenLimit: 1500
  messageWindowSize: 5
  validKeys:
    - "user_preferences"   # communication style, verbosity
    - "user_context"       # role, department, active projects
    - "learned_facts"      # facts the user has shared about themselves
  agent:
    provider: "OpenRouter"
    model: "z-ai/glm-5-turbo"   # cheapest model; memory extraction is simple
    instructions: |
      Store only explicitly stated user preferences, current context, and facts
      the user shares about themselves. Do NOT store project state, task progress,
      or operational knowledge — those belong in project State and LESSONS.md files.

Not a substitute for file-based memory. File-based memory is shared team state. LibreChat memory is per-user personalization only.

5.3 Skill-Level LESSONS.md

• Every SKILL.md gets a co-located LESSONS.md in the same directory
• Both are read when the skill is activated
• Prune when >500 words: graduate stable learnings into the SKILL.md procedure
• Root Forge/LESSONS.md stays ≤300 words — universal rules only, no skill-specific content

---

6. Word-Count Budgets

Enforced in FORGE.md and monitored by the future /audit-context command.

File	Budget	Rationale
FORGE.md	≤ 1,500 words	Loaded every session; cached in system prompt
Root LESSONS.md	≤ 300 words	Loaded every session; universal rules only
Knowledge/INDEX.md	≤ 200 words	TOC — names and one-line descriptions only
Any single Knowledge/*.md	≤ 800 words	On demand; one topic per file
Skill SKILL.md	≤ 500 words	Thin pointer + procedure outline
Skill LESSONS.md	≤ 500 words	Compact when exceeded
Project State.md	≤ 1,500 words	Living todo list
Project History.md	≤ 1,500 words	Archive old sessions when exceeded
Project README.md	No hard budget	Human-facing; not loaded by agents by default

---

7. File Discovery Convention

Codified in FORGE.md under a “File Discovery” section:

# Find files by name:
search_files(pattern="**/*keyword*")

# Find files whose content contains a term:
run("grep -rl 'search term' /path/")

# Find matching lines in a known file:
run("grep -n 'search term' /path/to/file")

Use grep for: past decisions, cross-project concept search, finding references. Use glob for: project folders, State/History files, discovering skills by name.

---

8. Key Path Updates Required

When Assistant/ → Forge/ and instructions.md → FORGE.md, update references in:

File	What changes
Forge/Knowledge/Constants.md	All path constants pointing to Assistant/
.internal/content.config.ts	Collection root path
.internal/astro.config.mjs	Sidebar slugs for Assistant section
Forge/Configs/agent-sync.yaml	Source paths for agent variants
/update-agents skill	Copy source: Forge/FORGE.md not Assistant/instructions.md
Root AGENTS.md (new)	Points to Forge/FORGE.md

---

9. Out of Scope (This Project)

The following items are moved to other projects:

• HEARTBEAT.md / KAIROS scheduled daemon pattern (§9.3) moved to Agentic Execution project
• Typesense semantic search moved to TypeSense project
• Orchestrator moved to Agentic Execution project