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

Knowledge Consistency Plan 5

Plan 5 — Forge Root Knowledge File Content Corrections

Scope: Correct content in Forge root knowledge files: update forge-discovery tool names, remove agent-sync terminology, remove JWT Auth Manager references, remove Forge_Chat_Prompt.md references, add eager/deferred tool guidance, update API names and terminology, replace hardcoded model names with use-case names, remove inline model quirks, fix filesystem paths, and add Bot prompt inspectability documentation.

Spec sections covered: S1.3 (Forge_Agent_Orchestration.md only), S1.5 (Forge_Setup.md only), S1.6, S1.7, S4.1, S4.2 (Forge_Infrastructure.md and Forge_Agents_User_Guide.md), S4.3, S4.4, S7.2 (Forge_Infrastructure.md only), S7.3 (Forge_Infrastructure.md only), S8.2.

Prerequisite: Plan 1 (use-case names from Choose_AI_Model skill needed for S7.2 replacements; model reference files needed for S7.3 quirk removal).

Task 1 — Update Forge_Agent_Orchestration.md

Spec S1.3: “Forge_Agent_Orchestration.md: The reference to Forge_Chat_Prompt.md -> ## PROJECT ROUTING is removed or updated to reference the Bot database prompt.” Spec S1.6: “The Forge_Agent_Orchestration.md discovery MCP tools table matches actual tool names.” The correct tool names are: forge-discovery__list_departments, forge-discovery__list_dept_projects, forge-discovery__get_project, forge-discovery__list_skills, forge-discovery__get_skill, forge-discovery__find. Spec S1.7: “Documentation does not assert which specific MCP tools are eager or deferred, as this classification can change. Documentation states that a tool may need to be loaded if it is deferred, and agents should use toolSearch / loadTool as needed. See References/Eager_Deferred_Guidance.md.” Spec S4.3: “The term ‘agent-sync’ is not used in documentation. The concept it described (syncing prompt files to the runtime) is no longer relevant — Bots and Prompts are modified in-place in the Bot database.” Spec S4.4: “Forge/Forge_Agent_Orchestration.md does not reference ‘JWT Auth Manager for session auth.’ The Orchestrator Service section describes ‘API-key authentication (service account)’ consistently.”

Steps

  1. Edit Forge/Forge_Agent_Orchestration.md.
  2. S1.3: Remove or update the reference to Forge_Chat_Prompt.md -> ## PROJECT ROUTING. Replace with a reference to the Bot database prompt.
  3. S1.6: Update the discovery MCP tools table to match the actual tool names: forge-discovery__list_departments (not list_departments if different), forge-discovery__list_dept_projects (not list_projects), forge-discovery__get_project (consolidates former tools), forge-discovery__list_skills, forge-discovery__get_skill (not get_skill_details), forge-discovery__find.
  4. S1.7: Update the eager vs deferred tool guidance to state that a tool may need to be loaded if it is deferred, and agents should use toolSearch / loadTool as needed. Do not assert which specific tools are eager or deferred. Reference References/Eager_Deferred_Guidance.md.
  5. S4.3: Remove all uses of the term “agent-sync.” Update the Include Directive section to describe prompt composition without referencing “agent-sync.”
  6. S4.4: Remove the reference to “JWT Auth Manager for session auth.” Update the Orchestrator Service section to describe “API-key authentication (service account)” consistently.

Verify

  • grep -r 'Forge_Chat_Prompt' Forge/Forge_Agent_Orchestration.md returns no matches
  • grep -r 'list_projects\|get_skill_details' Forge/Forge_Agent_Orchestration.md returns no matches (old tool names removed)
  • The discovery tools table lists: forge-discovery__list_departments, forge-discovery__list_dept_projects, forge-discovery__get_project, forge-discovery__list_skills, forge-discovery__get_skill, forge-discovery__find
  • grep -ri 'agent-sync' Forge/Forge_Agent_Orchestration.md returns no matches
  • grep -ri 'JWT Auth Manager' Forge/Forge_Agent_Orchestration.md returns no matches
  • The Orchestrator Service section describes “API-key authentication (service account)“

Task 2 — Update Forge_Infrastructure.md

Spec S1.7: “Documentation states that a tool may need to be loaded if it is deferred, and agents should use toolSearch / loadTool as needed.” Spec S4.2: “Documentation uses context-appropriate terminology: uvilo-mono — the monorepo (codebase, repository); forgentic — the app within uvilo-mono deployed on Railway (runtime environment). Where both names appeared together, they are simplified to the context-appropriate single term. See References/Terminology_Context.md.” Spec S7.2: “Knowledge files and skills refer to use-case names (e.g., ‘the indexing use case’), not specific model names (e.g., ‘gpt-5.4-nano’).” Spec S7.3: “Model-specific quirk documentation is moved from inline skill procedures into the Choose_AI_Model skill’s model reference files.” Affected file: Forge/Forge_Infrastructure.md (gpt-5.4-nano quirks).

Steps

  1. Edit Forge/Forge_Infrastructure.md.
  2. S1.7: Update eager vs deferred tool guidance consistent with References/Eager_Deferred_Guidance.md.
  3. S4.2: Replace context-inappropriate uses of “uvilo-mono” and “forgentic” with the context-appropriate single term. Where both names appeared together, simplify to the correct single term. Reference References/Terminology_Context.md.
  4. S7.2: Replace hardcoded model names (e.g., gpt-5.4-nano) with use-case names (e.g., “the indexing use case”) from the Choose_AI_Model skill’s Use Case Table.
  5. S7.3: Remove inline gpt-5.4-nano quirk documentation. Replace with a reference to Forge/Skills/Choose_AI_Model/Models/gpt-5.4-nano.md.

Verify

  • grep -ri 'agent-sync' Forge/Forge_Infrastructure.md returns no matches (if any existed)
  • The file uses context-appropriate terminology (uvilo-mono for codebase, forgentic for runtime)
  • grep -r 'gpt-5\.4-nano' Forge/Forge_Infrastructure.md returns no matches (replaced with use-case names)
  • grep -r 'max_completion_tokens' Forge/Forge_Infrastructure.md returns no matches (inline quirks removed)
  • The file references Forge/Skills/Choose_AI_Model/Models/gpt-5.4-nano.md for model quirks

Task 3 — Update Forge_Agents_User_Guide.md

Spec S4.1: “Forge/Forge_Agents_User_Guide.md uses current API names and patterns.” The old references (spawn_agent, agent_id/task_prompt, SCHEDULE_CONFIG, createTodoItem({ group, title, body }), /spawn command, /project-create command, gpt-4o model) are replaced with current references (spawnAgent, message/botId or botGroup+botHandle/mode, schedules.ts, createTodoItem({ todoListId, name, body }), removed slash commands, current model name or use-case reference). Spec S4.2: “Documentation uses context-appropriate terminology: uvilo-mono — the monorepo; forgentic — the app within uvilo-mono deployed on Railway.”

Steps

  1. Edit Forge/Forge_Agents_User_Guide.md.
  2. S4.1: Replace spawn_agent with spawnAgent.
  3. Replace agent_id / task_prompt parameters with message, botId or botGroup+botHandle, mode.
  4. Replace SCHEDULE_CONFIG with schedules.ts.
  5. Replace createTodoItem({ group, title, body }) with createTodoItem({ todoListId, name, body }).
  6. Remove references to /spawn command and /project-create command (no such slash commands exist).
  7. Replace gpt-4o model reference with the current model name or a use-case reference.
  8. Update curl examples to use current spawnAgent parameters.
  9. S4.2: Apply context-appropriate terminology (uvilo-mono vs forgentic) per References/Terminology_Context.md.

Verify

  • grep -r 'spawn_agent\|agent_id\|task_prompt\|SCHEDULE_CONFIG\|/spawn\|/project-create\|gpt-4o' Forge/Forge_Agents_User_Guide.md returns no matches
  • Curl examples use spawnAgent with current parameters
  • The file uses context-appropriate terminology

Task 4 — Fix Filesystem Paths in Forge_Setup.md

Spec S1.5: “No file references the incorrect path /workspace/erik/uvilo-os/. All hardcoded paths are replaced with either the correct /workspace/erik@uvilo.com/uvilo-os/ or the [[orgRepoRoot]] template variable where appropriate. Affected files: Forge/Forge_Setup.md.”

Steps

  1. Edit Forge/Forge_Setup.md.
  2. Replace /workspace/erik/uvilo-os/ with /workspace/erik@uvilo.com/uvilo-os/ or [[orgRepoRoot]] as appropriate.

Verify

  • grep -r '/workspace/erik/uvilo-os/' Forge/Forge_Setup.md returns no matches

Task 5 — Add Bot Prompt Inspectability Documentation to Forge_Agent_Architecture.md

Spec S8.2: “Forge/Forge_Agent_Architecture.md (or an appropriate knowledge file) includes a section on how humans can inspect Bot prompts using the application/vnd.prompt-version artifact type.” See also S8.1 and References/Bot_Prompt_Inspectability.md for the exact specification.

Steps

  1. Edit Forge/Forge_Agent_Architecture.md.
  2. Add a section describing how application/vnd.prompt-version is used to inspect Bot prompts — the same way application/vnd.markdown-file inspects files and application/vnd.git-changes inspects multi-file changes.
  3. Describe that when opened, the UI loads version N and N-1 from the database and displays a unified text diff.
  4. Reference References/Bot_Prompt_Inspectability.md for the exact specification.

Verify

  • grep -r 'application/vnd.prompt-version' Forge/Forge_Agent_Architecture.md returns a match
  • The section describes the unified text diff between version N and N-1

Task 6 — Build, Commit, and Push

Spec S1.3, S1.5, S1.6, S1.7, S4.1–S4.4, S7.2, S7.3, S8.2: This Plan implements Forge root knowledge file content corrections. After all tasks are complete, commit and push the changes. Per Known Infrastructure Context, npm run build is expected to fail; proceed with git operations regardless.

Steps

  1. Run npm run build from the repo root. This is known to fail. Proceed regardless.
  2. git add all modified files: Forge/Forge_Agent_Orchestration.md, Forge/Forge_Infrastructure.md, Forge/Forge_Agents_User_Guide.md, Forge/Forge_Setup.md, Forge/Forge_Agent_Architecture.md.
  3. git commit -m "Plan 5: Forge root knowledge file content corrections (S1.3, S1.5-S1.7, S4.1-S4.4, S7.2, S7.3, S8.2)"
  4. git push origin dev

Verify

  • All modified files are committed and pushed to dev
  • git log --oneline -1 shows the commit

Plan 5 Completion Criteria

  • Forge_Agent_Orchestration.md has no Forge_Chat_Prompt.md references, no agent-sync terminology, no JWT Auth Manager references, correct forge-discovery tool names, and eager/deferred guidance referencing toolSearch/loadTool
  • Forge_Infrastructure.md uses context-appropriate terminology, use-case names instead of hardcoded model names, and references Choose_AI_Model model reference files instead of inline quirks
  • Forge_Agents_User_Guide.md uses current API names and patterns, no deprecated slash commands, and context-appropriate terminology
  • Forge_Setup.md has no incorrect /workspace/erik/uvilo-os/ paths
  • Forge_Agent_Architecture.md includes a section on Bot prompt inspectability via application/vnd.prompt-version
  • Changes committed and pushed to dev

Dependencies

  • Requires: Plan 1 (use-case names from Choose_AI_Model skill for S7.2; model reference files for S7.3 quirk removal)
  • Blocks: None