Orchestration 2 Spec
Agent prompt files compose from shared source files via an include directive resolved at agent-sync time, producing fully assembled system prompts. Agent prompts follow a uniform naming convention, shared snippets eliminate duplication, context budgets are category-aware, and skill consolidation removes dead and redundant artifacts.
Requirements: Orchestration 2 Requirements
Research: Orchestration 2 Research
1. Include Directive System
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), producing a fully assembled prompt written to MongoDB.
Resolution is recursive — included files may themselves contain include directives — up to a maximum depth of 10. A visited-set detects cycles; encountering a previously seen path produces a sync error. Missing files also produce a sync error. The system fails loudly rather than silently.
The resolution occurs inside readPromptFile(), after frontmatter stripping and before the content is returned to the sync logic. Implementation uses regex matching on <!-- include: (.+?) --> — no external dependencies.
Documentation for the include directive (syntax, behavior, examples) appears in:
Forge/Forge_Agent_Orchestration.mdForge/Skills/Orchestration/SKILL.mdForge/Skills/Update_Agents/SKILL.md(if it exists)
2. Agent Prompt Naming Convention
All agent prompt files follow Title_Case_With_Underscores_Prompt.md naming. The _Prompt suffix distinguishes prompt files from other configuration files.
| 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 |
All references in agent-sync.ts, documentation, and sidebar use the new names.
3. Shared Snippets
Two shared snippet files eliminate duplication across agent prompts. Snippets are included via the include directive and are not standalone prompt files.
3.1 Environment snippet
Forge/Configs/Agents/Env_Snippet.md — environment facts and universal rules. Exact content: Shared Snippets.
Included by: Project Worker, Project Thinker, Project Evaluator, Project Runner, Task Runner, Page Handler, Forge Chat.
3.2 Project snippet
Forge/Configs/Agents/Project_Snippet.md — project lifecycle mental model. Exact content: Shared Snippets.
Included by: Project Worker, Project Thinker, Project Evaluator.
NOT included by: Project Runner (dispatches agents, doesn’t execute project work), Task Runner, Page Handler, Forge Chat.
4. Context Hygiene
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.
| 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.
Project State.md and History.md are removed from the budgets table — they are per-session files, not always-loaded context.
The /audit-context procedure:
- Counts words in all agent prompt files
- Compares each count against its budget
- Reports: file path, word count, budget, status (✅ or ⚠️ OVER)
- Writes results to
Forge/Skills/Context_Hygiene/references/context_audit.mdas a markdown table (overwritten each run)
5. Page Handler
Page_Handler_Prompt.md includes Forge/Skills/Manage_Pages/SKILL.md via the include directive. The prompt’s own content is approximately 100 words (responsibility, rules, error handling). All sidebar procedure, slug generation rules, and sidebar structure come from the inlined skill. The Page Handler operates without a runtime skill read for sidebar management.
The role name is “Page Handler” (not “Page Worker”), reflecting the Handler category.
6. Skill Inlining Strategy
Only skills used in every invocation by an agent are inlined. Currently:
| Agent | Inlined Skill | Rationale |
|---|---|---|
| Page Handler | Manage_Pages | Used in every operation; eliminates runtime read |
Project_Flow is NOT inlined into project agents because Project Runner provides full context at spawn time.
Forge Optimizer detects skills that an agent uses in every invocation and auto-suggests inlining once the pattern emerges.
7. Skill Consolidation
7.1 Create Page skill — deleted
Forge/Skills/Create_Page/ is deleted. Its logic has been merged into the renamed Manage Pages skill.
7.2 Update Sidebar → Manage Pages
Forge/Skills/Update_Sidebar/ is renamed to Forge/Skills/Manage_Pages/. The combined skill manages both filesystem and sidebar hierarchies — creating, renaming, moving, and deleting pages and folders.
All references are updated: Page_Handler_Prompt.md include directive, Forge_Chat_Prompt.md, sidebar, commands reference, agent-sync.ts, and documentation.
7.3 Forge/Skills/index.md — deprecated
Forge/Skills/index.md is deprecated and removed from always-loaded context in the Context Hygiene skill. All agents that need skill discovery use the forge-discovery MCP tool instead.