Orchestration 2 Research

---

1. include directive implementation in agent-sync.ts

R1

1.1 Finding

agent-sync.ts already has readPromptFile() which reads a file, strips frontmatter, and returns the content. This is the single injection point — includes can be resolved after frontmatter stripping and before the content is returned to the sync logic.

The codebase uses REPO_ROOT as the base path and readFileSync from fs. No external dependencies needed.

1.2 Options

A) Regex-based substitution in readPromptFile()

• Match <!-- include: (.+?) --> via regex
• For each match, read the file from REPO_ROOT/<path>, strip frontmatter, recursively resolve
• Replace directive with resolved content
• Pros: Simple, no new dependencies, fits existing code style
• Cons: Regex can be fragile if comment syntax varies

B) Markdown AST-based substitution

• Parse the markdown, walk the AST, find comment nodes
• Pros: Robust parsing
• Cons: Adds a dependency (remark/unified), overkill for a single comment pattern

1.3 Recommendation

Option A. The include syntax is intentionally simple — a single HTML comment with a path. Regex is sufficient and keeps the change minimal.

1.4 Decision

Option A. Implement regex-based substitution in readPromptFile().

---

2. Recursion and cycle detection

R2

2.1 Finding

Recursive includes are needed so that an included file can itself include other files (e.g., a config snippet that includes a shared constants file). The existing stripFrontmatter() is reusable for each nested file.

2.2 Options

A) Depth counter + visited set

• Pass depth (decrement from max) and visited: Set<string> through recursive calls
• Throw on depth ≤ 0 or revisited path
• Pros: Simple, deterministic
• Cons: None meaningful

B) Depth counter only (no cycle detection)

• Rely on depth limit to catch cycles
• Pros: Simpler
• Cons: A cycle within depth limit would duplicate content silently

2.3 Recommendation

Option A. Cycle detection is trivial to add and prevents silent content duplication.

2.4 Decision

Option A. Depth counter + visited set for cycle detection.

---

3. Context Hygiene budgets and agent categories (R3)

3.1 Finding

The current Context Hygiene budgets table has 4 rows (FORGE_CHAT.md, Skill SKILL.md, Project State.md, Project History.md). With 7 agent prompts now existing, the table needs to cover all of them. State.md and History.md are per-session files, not always-loaded context.

Current agent prompt word counts:

File	Words
FORGE_CHAT.md	1,346
TASK_RUNNER.md	524
PROJECT_RUNNER.md	428
PAGE_WORKER.md	310
PROJECT_THINKER.md	225
PROJECT_EVALUATOR.md	217
PROJECT_WORKER.md	212

3.2 Category-aware budgets

Categories inform budget defaults, inlining decisions, and which shared snippets to include. Budget applies to the agent’s own prompt content including inlined shared snippets, but excluding inlined skills. Inlining means using the <!-- include: --> directive.

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

Skill budget: Skill SKILL.md files have a budget of ≤ 500 words (procedure outline + pointer).

3.3 Decision

Option A. Category-aware budgets as defined above. Update Context Hygiene skill with this table and update /audit-context to count words in all agent prompt files and write results to Forge/Skills/Context_Hygiene/references/context_audit.md.

---

4. Documentation updates

R1

4.1 Finding

The following docs reference agent-sync or agent prompt composition:

• Forge/Forge_Agent_Orchestration.md — Agent CRUD API Notes section
• Forge/Skills/Orchestration/SKILL.md — references agent-sync and prompt configuration
• Forge/Skills/Update_Agents/SKILL.md — if it exists, documents the sync process

4.2 Options

Only one approach: add a subsection to each doc noting the include directive syntax and behavior. No alternatives.

4.3 Recommendation

Add to all three docs. Keep each note brief (2-3 sentences + syntax example).

4.4 Decision

Update all listed docs with include directive documentation.

---

5. Page Handler refactoring (R4)

5.1 Finding

Page_Handler_Prompt.md currently references Update_Sidebar as a runtime skill read. Every Page Handler operation touches the sidebar — create, rename, move, delete all require a sidebar update. This makes the runtime read redundant overhead.

5.2 Options

A) Inline Update_Sidebar via include directive

• <!-- include: Forge/Skills/Update_Sidebar/SKILL.md --> in Page_Handler_Prompt.md
• Page Handler’s own prompt content shrinks to ~100 words (responsibility, rules, error handling)
• All sidebar procedure, slug generation rules, sidebar structure come from the inlined skill
• Pros: Self-contained, no runtime tool call, quick win for testing the include system
• Cons: Update_Sidebar SKILL.md is 776 words — adds to resolved prompt size

B) Keep runtime read

• Status quo
• Pros: No change
• Cons: Every operation pays the cost of a skill read

5.3 Recommendation

Option A. Page Handler is the ideal first candidate for the include system — narrow scope, every operation uses the same skill.

5.4 Decision

Option A. Inline Update_Sidebar via include directive. Renamed from PAGE_WORKER.md to Page_Handler_Prompt.md.

---

6. Shared snippets for agents (R5)

6.1 Finding

Multiple agent prompts duplicate the same environmental facts and universal rules. A shared snippet should be extractable and includable by agents that need it, avoiding duplication and drift. Additionally, project-related agents share common workflow rules.

6.2 Options

A) Extract distillates to snippet files

• Forge/Configs/Agents/Env_Snippet.md — ~100 words for environment + universal rules
• Forge/Configs/Agents/Project_Snippet.md — project workflow rules for project agents
• Included by relevant agents via <!-- include: --> directive

B) Per-agent duplication (status quo)

• Pros: Each agent is self-contained
• Cons: Drift, inconsistency, maintenance burden

6.3 Shared environment snippet

Included by: Project Worker, Project Thinker, Project Evaluator, Project Runner, Task Runner, Page Handler

Likely included by Forge Chat (TBD — if common knowledge belongs in all agents, Forge Chat should also source it from the snippet rather than duplicating)

## Environment
- Git: ErikDakoda/uvilo-os (private), canonical branch `dev`
- Don't merge into `main` unless explicitly asked
- Railway cloud — no local filesystem; shell via forge-bash only
- Deferred tools: most MCP tools are deferred; use ToolSearch to load on demand

## Universal Rules
- No `rm` — always use uvilo-trash for deletion
- For sidebar/URL concerns, spawn Page Handler instead of handling directly
- Diagnosis rule: verify most direct cause first; don't re-derive from scratch; search the internet for existing solutions
- Escalation rule: after 3 failed infrastructure attempts, stop and ask the user

6.4 Shared project snippet

Included by: Project Worker, Project Thinker, Project Evaluator

NOT included by: Project Runner (dispatches agents, doesn’t execute project work), Task Runner (not project-specific), Page Handler (not project-specific), Forge Chat (has all content natively)

### Project Lifecycle

Create → Requirements → Research → Spec → Plan → Implement → Evaluate → Fix → Verify → Extract → Complete

Projects have one or more Plans (Plan 1, Plan 2, etc). The Implement → Evaluate → Fix loop repeats within a plan until Evaluate passes, and then loops over the next Plan.

When Evaluate passes for all Plans → Verify project.

If Verify finds issues → new Plan → Implement → Evaluate → Fix loop. If Verify passes → Extract.

6.5 Decision

Option A. Create both shared environment snippet and shared project snippet as defined above.

---

7. Skills to inline per agent (R6)

7.1 Finding

Each agent has skills it uses in every invocation vs. skills it reads at runtime based on the task. Inlining the former eliminates overhead; inlining the latter would bloat prompts unnecessarily.

7.2 Options

A) Inline only always-needed skills

Initial mapping:

Agent	Inlined Skill	Rationale
Page Handler	Update_Sidebar	Used in every operation; eliminates runtime read

Project_Flow is NOT inlined into project agents (Project Worker, Project Thinker, Project Evaluator) because these agents are spawned by Project Runner with full context passed at spawn time. The skill would be redundant.

B) Manual mapping per agent

• Evaluate each agent individually
• Pros: Tailored decisions
• Cons: Ad-hoc, no system for detecting patterns

7.3 Recommendation

Start with Option A for Page_Handler_Prompt.md only. Additionally, update Forge Optimizer to detect skills that an agent uses in every invocation and auto-suggest inlining once the pattern emerges.

7.4 Decision

Only inline Update_Sidebar in Page_Handler_Prompt.md. Update Forge Optimizer to detect always-used skills and suggest inlining. Project_Flow is not needed for spawned project agents — Project Runner provides full context at spawn time. Shared project snippet covers general project rules.

---

8. Forge/Skills/index.md deprecation (R7)

8.1 Finding

Forge/Skills/index.md is currently listed as an always-loaded file in the Context Hygiene skill. The forge-discovery MCP tool now provides runtime skill discovery via list_skills, find, and get_skill_details.

8.2 Options

A) Deprecate index.md

• Pros: Removes always-loaded context; forge-discovery is more complete and up-to-date
• Cons: Agents that don’t have forge-discovery configured would lose skill discovery

B) Keep index.md as fallback

• Pros: Safety net
• Cons: Redundant content loaded every session

8.3 Recommendation

Deprecate index.md. All agents that need skill discovery have forge-discovery configured.

8.4 Decision

Deprecate Forge/Skills/index.md. Remove from always-loaded context in Context Hygiene skill.

---

9. Agent prompt naming convention (R8)

9.1 Finding

Agent prompt files currently use ALL_CAPS_WITH_UNDERSCORES.md naming (e.g., FORGE_CHAT.md, PAGE_WORKER.md). This is inconsistent with the Title_Case_With_Underscores convention used elsewhere in Uvilo OS for non-infrastructure files. Agent prompts are configuration files, not infrastructure.

9.2 Naming convention

Agent prompt files use: Title_Case_With_Underscores_Prompt.md

The _Prompt suffix distinguishes these from other configuration files and makes their purpose explicit.

9.3 Mapping

Current Name	New Name
FORGE_CHAT.md	Forge_Chat_Prompt.md
TASK_RUNNER.md	Task_Runner_Prompt.md
PROJECT_RUNNER.md	Project_Runner_Prompt.md
PAGE_WORKER.md	Page_Handler_Prompt.md
PROJECT_THINKER.md	Project_Thinker_Prompt.md
PROJECT_EVALUATOR.md	Project_Evaluator_Prompt.md
PROJECT_WORKER.md	Project_Worker_Prompt.md

Note: PAGE_WORKER also gets renamed to Page_Handler to reflect its category (Handler, not Worker).

9.4 Decision

Adopt the Title_Case_With_Underscores_Prompt.md naming convention for all agent prompt files. Rename existing files according to the mapping above. Update all references in agent-sync.ts and documentation.

---

10. Delete Create Page skill and rename Update Sidebar to Manage Pages (R9)

10.1 Finding

The Create Page skill’s logic was merged into Update Sidebar because page creation always requires a sidebar update. The combined skill now manages both the filesystem and sidebar hierarchies — creating, renaming, moving, and deleting pages and folders. The name “Update Sidebar” no longer accurately describes this broader scope.

10.2 Recommendation

• Delete Forge/Skills/Create_Page/ (logic already merged into Update Sidebar)
• Rename Forge/Skills/Update_Sidebar/ → Forge/Skills/Manage_Pages/
• Update all references: Page_Handler_Prompt.md include directive, FORGE_CHAT.md, sidebar, commands reference, agent-sync.ts

10.3 Decision

Delete Create Page skill. Rename Update Sidebar to Manage Pages. Update all references.