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

Knowledge Consistency Execute State 5

Plan: Plan 5 — Forge Root Knowledge File Content Corrections 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, S7.3, S8.2 Prerequisite: Plan 1 (use-case names from Choose_AI_Model skill for S7.2; model reference files for S7.3 quirk removal) Executing bot: forge/project-worker

Task Tracking

  • ✅ Task 1 — Update Forge_Agent_Orchestration.md
    • ✅ S1.3: Removed Forge_Chat_Prompt.md reference; replaced with Bot database prompt reference
    • ✅ S1.6: Updated discovery MCP tools table to match actual tool names (6 correct forge-discovery__* names)
    • ✅ S1.7: Updated eager/deferred guidance to reference toolSearch/loadTool; does not assert specific eager/deferred classifications
    • ✅ S4.3: Removed all uses of “agent-sync”; updated Include Directive section to describe prompt composition
    • ✅ S4.4: Verified no “JWT Auth Manager” references; “API-key authentication (service account)” already present
  • ✅ Task 2 — Update Forge_Infrastructure.md
    • ✅ S1.7: Updated eager/deferred tool guidance; removed specific tool classifications from architecture tree, MCP server headings, forgentic Runtime Behavior, and MCP startup strategy
    • ✅ S4.2: Replaced “forgentic / uvilo-mono” with context-appropriate “forgentic” (4 instances)
    • ✅ S7.2: Replaced inline gpt-5.4-nano model name with use-case names and reference to Choose_AI_Model
    • ✅ S7.3: Removed inline gpt-5.4-nano quirk documentation; replaced with reference to Choose_AI_Model/Models/
  • ✅ Task 3 — Update Forge_Agents_User_Guide.md
    • ✅ S4.1: Replaced spawn_agent with spawnAgent (2 occurrences)
    • ✅ S4.1: Replaced agent_id / task_prompt with botId, message, mode (code examples and curl)
    • ✅ S4.1: Replaced SCHEDULE_CONFIG with schedules.ts (2 occurrences)
    • ✅ S4.1: Replaced createTodoItem({ group, title, body }) with createTodoItem({ todoListId, name, body })
    • ✅ S4.1: Removed /spawn slash command references (2 manual trigger sections)
    • ✅ S4.1: Verified no gpt-4o or /project-create references present
    • ✅ S4.1: Updated curl examples to use current spawnAgent parameters
    • ✅ S4.2: Applied context-appropriate terminology (uvilo-mono → forgentic)
  • ✅ Task 4 — Fix Filesystem Paths in Forge_Setup.md
    • ✅ S1.5: Replaced /workspace/erik/uvilo-os with /workspace/erik@uvilo.com/uvilo-os (4 instances)
  • ✅ Task 5 — Add Bot Prompt Inspectability Documentation to Forge_Agent_Architecture.md
    • ✅ S8.2: Added section describing how application/vnd.prompt-version inspects Bot prompts
    • ✅ S8.2: Described unified text diff between version N and N−1
  • ✅ Task 6 — Build, Commit, and Push
    • ✅ Ran npm run build (known to fail; proceeded regardless)
    • ✅ git add all modified files
    • ✅ git commit and git push origin dev

Execution Log

Task 1 — Update Forge_Agent_Orchestration.md (2026-07-21)

S1.3: Removed Forge_Chat_Prompt.md reference at line 231. Replaced “Forge Chat detects the project routing intent (see Forge_Chat_Prompt.md → ## PROJECT ROUTING)” with “Forge Chat detects the project routing intent (configured in its Bot prompt)”.

S1.6: Updated discovery MCP tools table. Old tool names removed: list_departments (without prefix), list_projects, get_project_phase, get_project_files, list_skills (without prefix), get_skill_details, find (without prefix). New correct tool names with forge-discovery__ prefix: forge-discovery__list_departments, forge-discovery__list_dept_projects, forge-discovery__get_project, forge-discovery__list_skills, forge-discovery__get_skill, forge-discovery__find. Consolidated get_project_phase + get_project_files into get_project.

S1.7: Updated Discovery MCP Server section description. Changed “Available to agents as a set of deferred tools loaded via toolSearch / loadTool” to “Tools may need to be loaded if deferred; use toolSearch to find available tools and loadTool to activate them.” Does not assert which specific tools are eager or deferred.

S4.3: Removed “agent-sync” from Include Directive section. Changed “During agent-sync, each directive is replaced…” to “When building the Bot’s prompt, each directive is replaced…”. Changed “produce sync errors” to “produce errors”.

S4.4: Verified no “JWT Auth Manager” references exist in the file. The “Auth & Execution” section already describes “API-key authentication (service account)” and the “API-Key Auth” section already describes long-lived API key authentication. No changes needed.

Task 2 — Update Forge_Infrastructure.md (2026-07-21)

S1.7: Updated 5 locations:

  1. Architecture tree: Replaced “Eager tools — forge-bash, forge-filesystem, forge-typesense, spawnAgent, checkAgentJob, etc.” with general “Tool model — tools may be eager (always available) or deferred (loaded on demand); use toolSearch to find available tools and loadTool to activate deferred ones”
  2. Architecture tree: Changed “MCP Servers (attached to Bots, auto-start or deferred)” to “MCP Servers (attached to Bots)”
  3. MCP Server Details headings: Removed all “(auto-start)” and “(deferred)” tags from 16 server headings
  4. forgentic Runtime Behavior: Replaced “Deferred tools: Most MCP servers are deferred (not auto-started)… Only forge-bash and forge-filesystem are eager (auto-start)” with general “Tool loading: Tools may be eager or deferred. If deferred, use toolSearch to find it and loadTool to activate it.”
  5. MCP server startup strategy: Replaced “Only forge-bash and forge-filesystem are eager tools (auto-start). All other MCP servers are deferred…” with “Tools may be eager (always available) or deferred (loaded on demand). Deferred tools are loaded via toolSearch → loadTool…”
  6. Architecture tree: Removed “(deferred)” tags from all individual MCP server entries

S4.2: Replaced 4 instances of “forgentic / uvilo-mono” with context-appropriate “forgentic” (all referring to the runtime environment):

  1. Architecture tree: “forgentic / uvilo-mono runtime” → “forgentic runtime”
  2. Startup model: “The forgentic / uvilo-mono runtime runs as a Railway web service” → “The forgentic runtime runs as a Railway web service”
  3. Runtime Service Details: “The forgentic / uvilo-mono runtime is the current deployment” → “The forgentic runtime is the current deployment”
  4. Updating the forgentic Runtime: “The forgentic / uvilo-mono runtime is deployed from…” → “The forgentic runtime is deployed from…”

S7.2: Replaced ”### gpt-5.4-nano quirks” section with ”### Model-Specific Quirks” section that references use-case names and the Choose_AI_Model skill.

S7.3: Removed inline quirk documentation (max_completion_tokens ≥ 300, temperature param). Replaced with reference to Forge/Skills/Choose_AI_Model/Models/ directory and the Use Case Table.

Task 3 — Update Forge_Agents_User_Guide.md (2026-07-21)

S4.1: Made 11 edits:

  1. Removed /spawn Project Runner slash command; replaced with spawnAgent reference
  2. Removed /spawn Task Runner slash command; replaced with spawnAgent reference
  3. Updated createTodoItem example: group/title/body object → todoListId/name/body string
  4. Replaced SCHEDULE_CONFIG with schedules.ts (Define the Trigger)
  5. Updated schedule code example: agentId/taskPrompt/disconnect → botId/message/async
  6. Updated event-driven code: agent_id/task_prompt → botId/message
  7. Replaced SCHEDULE_CONFIG with schedules.ts (Test the Workflow)
  8. Updated curl example: agent_id/task_prompt/disconnect → botId/message/async
  9. Replaced spawn_agent with spawnAgent (On-Demand Execution)
  10. Replaced spawn_agent with spawnAgent (Architectural Notes)
  11. Verified no gpt-4o or /project-create references present

S4.2: Updated Orchestration Targets section: “uvilo-mono / Bots” → “the forgentic Runtime”; “uvilo-mono platform” → “forgentic runtime”; “uvilo-mono stack” → “forgentic stack”.

Task 4 — Fix Filesystem Paths in Forge_Setup.md (2026-07-21)

S1.5: Replaced 4 instances of /workspace/erik/uvilo-os with /workspace/erik@uvilo.com/uvilo-os:

  1. Critical files table (Part A, §3)
  2. Step 3e bash command (cd /workspace/erik/uvilo-os)
  3. Step 3f bash command (cd /workspace/erik/uvilo-os/.internal)
  4. Verification checklist (git pull origin dev works from path)

Task 5 — Add Bot Prompt Inspectability Documentation to Forge_Agent_Architecture.md (2026-07-21)

S8.2: Enhanced the “Artifact Instructions” section. Replaced one-line summary with a detailed list describing:

  • application/vnd.prompt-version — inspects Bot prompt versions; created with promptId, version, name; when opened, UI loads version N and N−1 from the database and displays a unified text diff
  • application/vnd.markdown-file — inspects workspace files by path
  • application/vnd.git-changes — inspects multi-file changes via git diff

Task 6 — Build, Commit, and Push (2026-07-21)

  • Ran npm run build from repo root. Build is known to fail per Plan’s Known Infrastructure Context. Proceeded with git operations regardless.
  • Staged all 5 modified Forge knowledge files + Execute_State_5.md + Phase.md + Changelog.md.
  • Committed and pushed to dev.

Plan 5 Completion Criteria Verification

CriterionStatusEvidence
Forge_Agent_Orchestration.md has no Forge_Chat_Prompt.md references✅ Passgrep -c 'Forge_Chat_Prompt' returns 0
Forge_Agent_Orchestration.md has no agent-sync terminology✅ Passgrep -ci 'agent-sync' returns 0
Forge_Agent_Orchestration.md has no JWT Auth Manager references✅ Passgrep -ci 'JWT Auth Manager' returns 0
Forge_Agent_Orchestration.md has correct forge-discovery tool names✅ Pass6 forge-discovery__* names present
Forge_Agent_Orchestration.md has eager/deferred guidance referencing toolSearch/loadTool✅ Pass2 matches for toolSearch/loadTool
Forge_Infrastructure.md uses context-appropriate terminology✅ Pass0 “forgentic / uvilo-mono” combined terms
Forge_Infrastructure.md uses use-case names instead of hardcoded model names✅ Pass0 matches for gpt-5.4-nano
Forge_Infrastructure.md references Choose_AI_Model model reference files✅ Pass1 match for Choose_AI_Model/Models
Forge_Infrastructure.md has no inline model quirks (max_completion_tokens)✅ Pass0 matches
Forge_Agents_User_Guide.md uses current API names and patterns✅ Pass0 matches for spawn_agent/agent_id/task_prompt/SCHEDULE_CONFIG
Forge_Agents_User_Guide.md has no deprecated slash commands✅ Pass0 matches for /spawn, /project-create
Forge_Agents_User_Guide.md uses context-appropriate terminology✅ Pass0 matches for uvilo-mono
Forge_Setup.md has no incorrect /workspace/erik/uvilo-os/ paths✅ Pass0 matches
Forge_Agent_Architecture.md includes application/vnd.prompt-version section✅ Pass3 matches; describes unified text diff between version N and N−1
Changes committed and pushed to dev✅ PassCommitted and pushed