Skip to content
Uvilo OS
approved Visibility internal Owner erik@uvilo.com Approver _ Created 2026-07-25 Updated 2026-07-25

Orchestration 2 Plan 3

Scope: Update Context Hygiene skill with category-aware budgets, deprecate Forge/Skills/index.md, update Forge Optimizer to detect always-used skills, and update documentation for the include directive system.

Prerequisite: Plan 2 is completed (all prompts renamed and refactored, skills consolidated).

Task 1 — Rewrite Context Hygiene skill

Spec §4: The Context Hygiene skill uses category-aware budgets covering all agent prompt files. Budget applies to the agent’s own prompt content including inlined shared snippets, but excluding inlined skills.

Replace the content of Forge/Skills/Context_Hygiene/SKILL.md with:

---
name: context-hygiene
description: Use when auditing context budgets or compacting files
title: "Context Hygiene"
visibility: internal
status: published
owner: "erik@uvilo.com"
tags: [context, budget, compaction, command]
---

# Context Hygiene

Keep always-loaded and per-session files within their word-count budgets.
Flag overages and compact when needed.

## Budgets

| Category | Description | Narrow scope | Inlines skills | Includes env snippet | Agents | Word Budget |
|----------|-------------|-------------|----------------|---------------------|--------|-------------|
| Chat | General-purpose, full context | No | No | Yes | Forge Chat | ≤ 1,500 |
| Runner | Dispatches other agents | No | No | Yes | Project Runner, Task Runner | ≤ 700 |
| Worker | Executes project skills | Yes | Yes | Yes | Project Worker | ≤ 300 |
| Thinker | Plans, designs, reasons | Yes | Yes | Yes | Project Thinker | ≤ 300 |
| Evaluator | Reviews against intent | Yes | Yes | Yes | Project Evaluator | ≤ 300 |
| Handler | Executes one narrow domain | Very | Yes (1–2) | Yes | Page Handler | ≤ 300 |

**Skill `SKILL.md` budget:** ≤ 500 words.

Budget applies to the agent's own prompt content including inlined shared snippets, but excluding inlined skills.

## `/audit-context`

Count words in all agent prompt files and compare against budgets.

**Procedure:**

1. Count words in all agent prompt files:
   - `Forge/Configs/Agents/Forge_Chat_Prompt.md`
   - `Forge/Configs/Agents/Task_Runner_Prompt.md`
   - `Forge/Configs/Agents/Project_Runner_Prompt.md`
   - `Forge/Configs/Agents/Page_Handler_Prompt.md`
   - `Forge/Configs/Agents/Project_Thinker_Prompt.md`
   - `Forge/Configs/Agents/Project_Evaluator_Prompt.md`
   - `Forge/Configs/Agents/Project_Worker_Prompt.md`
2. Compare each count against its category budget
3. Report: file path, word count, budget, status (✅ or ⚠️ OVER)
4. Write results to `Forge/Skills/Context_Hygiene/references/context_audit.md` as a markdown table (overwrite each run)

**Shell command:**

```bash
wc -w Forge/Configs/Agents/*_Prompt.md

Compaction Procedures

Skill SKILL.md compaction

When a skill SKILL.md exceeds 500 words:

  1. Review the procedure and rules
  2. Move deep reference material into references/ files
  3. Keep SKILL.md as procedure outline + pointer (≤ 500 words)
  4. Preserve YAML frontmatter

Create the references directory if it doesn't exist:

```bash
mkdir -p /workspace/erik/uvilo-os/Forge/Skills/Context_Hygiene/references

Task 2 — Deprecate Forge/Skills/index.md

Spec §7.3: Forge/Skills/index.md is deprecated and removed from always-loaded context. All agents that need skill discovery use the forge-discovery MCP tool.

  1. Remove the reference to index.md from the Context Hygiene skill (already done in Task 1 — the rewritten skill no longer lists Forge/Skills/index.md as an always-loaded file)
  2. Do NOT delete Forge/Skills/index.md — just remove it from the “always-loaded” tracking. The file still exists but is no longer loaded every session.
  3. Remove the reference to Forge/Skills/index.md from the /audit-context procedure (already done in Task 1)

Task 3 — Update Forge Agent Orchestration documentation

Spec §1 (docs): Documentation for the include directive appears in Forge/Forge_Agent_Orchestration.md.

Add a new subsection to Forge/Forge_Agent_Orchestration.md under the Agent CRUD API Notes section (or as a new section before it), titled Include Directive:

### Include Directive

Agent prompt files support `<!-- include: path -->` directives, where `path` is relative to the repo root. During agent-sync, each directive is replaced with the referenced file's content (frontmatter stripped). Includes are resolved recursively up to depth 10; cycles and missing files produce sync errors.

Example:


This allows shared snippets and skills to be composed into agent prompts without runtime tool calls.

Also update the Agent Types section: rename “Page Worker” → “Page Handler” throughout.

Task 4 — Update Orchestration skill documentation

Add a brief note to Forge/Skills/Orchestration/SKILL.md about the include directive:

Add after the Agent CRUD API Notes section:

## Include Directive

Agent prompt files support `<!-- include: path -->` directives resolved at agent-sync time. See Forge Agent Orchestration docs for details. When editing agent prompts, use includes for shared snippets and always-needed skills rather than duplicating content.

Also rename “Page Worker” → “Page Handler” in any references.

Task 5 — Update Update Agents skill documentation

Update Forge/Skills/Update_Agents/SKILL.md to document the include directive:

Add after the What the script does section:

### Include directives

Agent prompt files support `<!-- include: path -->` directives. The sync script resolves these recursively before writing the assembled prompt to MongoDB. If you add an include directive to a prompt file, the next sync will resolve it automatically. Missing files or cycles produce sync errors.

Also update all references to old prompt file names (FORGE_CHAT.md → Forge_Chat_Prompt.md, etc.) and “Page Worker” → “Page Handler”.

Task 6 — Update Forge Optimizer extraction prompt

Spec §6: Forge Optimizer should detect skills that an agent uses in every invocation and auto-suggest inlining.

Update Forge/Skills/Forge_Optimizer/references/extraction_prompt.md to add a new finding type for inlining opportunities.

Add a new row to the Finding types table:

| `inlining opportunity` | Agent uses a skill in every invocation via runtime read | Suggest inlining the skill via `<!-- include: -->` directive in the agent's prompt file |

Add a new bullet under “Rules for findings”:

- **Inline detection:** If an agent reads a skill file via `get_skill_details` or filesystem read in every transcript, flag it as an `inlining opportunity` and suggest adding `<!-- include: {path} -->` to the agent's prompt file.

Task 7 — Verify and commit

  1. Run /audit-context procedure manually — count words in all 7 agent prompt files, compare against budgets, write results to Forge/Skills/Context_Hygiene/references/context_audit.md

  2. Run agent-sync dry-run to confirm no errors:

npx tsx /workspace/erik/uvilo-os/orchestrator/src/agent-sync.ts --dry-run
  1. Run agent-sync live to verify assembled prompts in production:
npx tsx /workspace/erik/uvilo-os/orchestrator/src/agent-sync.ts

  1. Build to verify: cd /workspace/erik/uvilo-os/.internal && pnpm run build

  2. Stage all changes, commit with message Orchestration_2: Plan 3 — context hygiene + documentation + optimizer, push to dev