Orchestration 2 Requirements

---

Vision

Agent prompt files should compose from shared source files (skills, configs, snippets) instead of duplicating content. An include directive in a prompt file is resolved at agent-sync time, inlining the referenced file’s content so the agent receives a fully assembled system prompt.

Requirements

R1: Include directive syntax

Agent prompt files support an <!-- include: path --> directive. The path is relative to the repo root. The directive is replaced with the file’s content (frontmatter stripped) during agent-sync.

R2: Recursive resolution

Includes are resolved recursively up to a maximum depth. A cycle detector prevents infinite loops. Missing files cause a sync error (fail loudly, not silently).

R3: Update Context Hygiene skill

Update the Context Hygiene skill to reflect the new agent landscape:

1. Budgets table — replace the current 4-row table with the category-aware table covering all agent prompt files. Budget applies to the agent’s own prompt content including inlined shared snippets, but excluding inlined skills.

2. Agent categories — define a table grouping agents by role (Chat, Runner, Worker, Thinker, Evaluator, Handler) with columns for Description, Narrow scope, Inlines skills, Includes env snippet, Agents, Word Budget, and Current Words.

3. Remove Project State.md and Project History.md from the budgets table. These are per-session files, not always-loaded context.

4. Update /audit-context procedure to:

   • Count words in all agent prompt files
   • Compare each count against its budget
   • Report: file path, word count, budget, status (✅ or ⚠️ OVER)
   • New step: Write results to Forge/Skills/Context_Hygiene/references/context_audit.md as a markdown table (overwrite each run)

R4: Refactor Page Handler prompt

Page_Handler_Prompt.md currently references Update_Sidebar as a runtime skill read. Since every Page Handler operation touches the sidebar, this read is redundant overhead. The prompt should be refactored to use the include system so sidebar rules are available without a runtime tool call.

R5: Shared snippets for agents

Multiple agent prompts duplicate the same environmental facts and universal rules. Two shared snippets should be created:

1. Shared environment snippet (Forge/Configs/Agents/Env_Snippet.md) — ~100 words covering environment facts and universal rules. Included by all agents. Replaces sidebar/URL rules with “spawn Page Handler” directive. Diagnosis rule includes searching the internet for existing solutions. Escalation rule increased to 3 failed attempts. Summarize rule removed.

2. Shared project snippet (Forge/Configs/Agents/Project_Snippet.md) — project lifecycle mental model for project agents (Project Worker, Project Thinker, Project Evaluator). Not needed by Project Runner (dispatches agents, doesn’t execute project work) or non-project agents.

R6: Determine which skills to inline per agent

Only inline Update_Sidebar into Page_Handler_Prompt.md for now. Update Forge Optimizer to detect skills that an agent uses in every invocation and auto-suggest inlining once the pattern emerges. Project_Flow is not inlined into spawned project agents because Project Runner provides full context at spawn time.

R7: Deprecate Forge/Skills/index.md

Forge/Skills/index.md is deprecated. All agents that need skill discovery have forge-discovery MCP tool configured. Remove index.md from always-loaded context in Context Hygiene skill.

R8: Agent prompt naming convention

Rename all agent prompt files to Title_Case_With_Underscores_Prompt.md convention. The _Prompt suffix distinguishes these from other configuration files and makes their purpose explicit.

Mapping:

• 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 (also renamed Worker → Handler)
• PROJECT_THINKER.md → Project_Thinker_Prompt.md
• PROJECT_EVALUATOR.md → Project_Evaluator_Prompt.md
• PROJECT_WORKER.md → Project_Worker_Prompt.md

Update all references in agent-sync.ts and documentation.

R9: Delete Create Page skill and rename Update Sidebar to Manage Pages

The Create Page skill’s logic has been merged into Update Sidebar. The combined skill manages both filesystem and sidebar hierarchies — creating, renaming, moving, and deleting pages and folders. The name “Update Sidebar” no longer reflects this scope.

• Delete Forge/Skills/Create_Page/ directory
• 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, and any documentation

Success Criteria

#	Criterion	Measured by
V1	Include directives are resolved and inlined before agent instructions are written to MongoDB	agent-sync resolves <!-- include: --> directives; output is fully assembled prompt
V2	Recursive includes work up to max depth; cycles and missing files produce clear errors	Test with nested include and invalid path
V3	Context Hygiene skill updated with category-aware budgets table; /audit-context produces context_audit.md	Audit command runs against all agent prompts; writes results table to references/
V4	Page_Handler_Prompt.md refactored to use includes; no runtime skill read for Manage_Pages	agent-sync resolves the include; Page Handler operates without reading the skill at runtime
V5	Shared environment and project snippets exist and are included by agents that need them	Snippet files are includable by multiple agent prompts; agents that exclude them still function correctly
V6	Manage_Pages inlined in Page_Handler_Prompt; Forge Optimizer updated to detect always-used skills	Page Handler operates without runtime skill read; Optimizer can detect usage patterns
V7	Forge/Skills/index.md deprecated and removed from always-loaded context	All agents that previously relied on index.md use forge-discovery for skill lookup instead
V8	All agent prompts renamed to Title_Case_With_Underscores_Prompt.md convention; all references updated	agent-sync.ts, documentation, and sidebar use new names; sync succeeds
V9	Create Page skill deleted; Update Sidebar renamed to Manage Pages; all references updated	Create_Page directory removed; Manage_Pages directory exists with combined logic; all references use new name

Out Of Scope

• Runtime include resolution (only at sync time)
• Conditional includes or template variables