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

Knowledge Consistency Plan 1

Plan 1 — Choose_AI_Model Skill Creation

Project: Forge/Knowledge_Consistency Phase: Plan (7 Plans) Spec: Knowledge_Consistency_Spec.md

Overview

This Plan set breaks the approved Spec into seven executable Plans. Each Plan targets a cohesive artifact type and can be executed and evaluated independently. The partition was revised during Plan_Eval Round 1 auto-fix to resolve findings E1–E8: coverage gaps (E1, E7), inaccurate coverage claims (E2), ambiguous paths (E3, E8), checkbox usage (E4), missing context quotes (E5), and task ordering conflicts (E6).

  • Plan 1 — Choose_AI_Model skill creation (S7.1, S7.3 reference file creation). No prerequisites.
  • Plan 2 — Skill file content corrections (S1.1, S1.2, S1.3 skills, S1.4, S1.5 skills, S1.8, S7.2 skills, S7.3 skill quirk removal). Requires Plan 1.
  • Plan 3 — Manage_Pages to Page Manager routing in 14 skill files (S1.10 skills). No prerequisites.
  • Plan 4 — Knowledge file frontmatter corrections (S2.1, S2.2, S2.3, S2.4, S10.2). No prerequisites.
  • Plan 5 — Forge root knowledge file content corrections (S1.3/S1.6/S1.7/S4.3/S4.4 in Forge_Agent_Orchestration.md, S1.7/S4.2/S7.2/S7.3 in Forge_Infrastructure.md, S4.1/S4.2 in Forge_Agents_User_Guide.md, S1.5 in Forge_Setup.md, S8.2 in Forge_Agent_Architecture.md). Requires Plan 1.
  • Plan 6 — Forge_Project and documentation content corrections (S6.3, S3.1, S12 in Forge_Project docs, S12.3 in Project_Flow/SKILL.md, S1.10 doc edits, S10.1 README/AGENTS consolidation). No prerequisites.
  • Plan 7 — Bot prompts, Available Skills, and follow-ups (S3.1, S3.2, S3.3, S3.4, S5, S9.1, S9.2, S11.1, S11.2, S1.9, S1.10 bot prompts). Requires Plan 2.

Dependency Graph

Plan 1 ──→ Plan 2 ──→ Plan 7
   │
   └──→ Plan 5

Plan 3 (independent)
Plan 4 (independent)
Plan 6 (independent)
  • Plans 1, 3, 4, and 6 have no prerequisites and can start in parallel.
  • Plan 2 requires Plan 1 (model reference files must exist before extracting quirks from skills).
  • Plan 5 requires Plan 1 (use-case names from Choose_AI_Model skill needed for S7.2 replacements in knowledge files).
  • Plan 7 requires Plan 2 (skill rename must complete before updating Available Skills list).
  • Plans 4 and 5 both edit Forge root knowledge files but in different regions (frontmatter vs body content); git merges these without conflict if run in parallel.

Known Infrastructure Context

npm run build fails because package.json has no build script (it contains only dependencies, no scripts section). This is a known infrastructure issue, not a Plan content defect. Build/commit/push tasks in each Plan proceed with git add, git commit, and git push regardless of build failure.

Reference Documents (already exist)

The following Reference documents in Forge/Projects/Knowledge_Consistency/References/ provide specifications cited by the Spec. Plans reference them as context — they are not tasks to create.

  • References/Choose_AI_Model_Skill.md — exact specification for the Choose_AI_Model skill (S7.1)
  • References/Eager_Deferred_Guidance.md — standard for tool loading guidance (S1.7)
  • References/Terminology_Context.md — uvilo-mono vs forgentic usage rules (S4.2)
  • References/Changelog_Format.md — changelog format specification (S6.2)
  • References/Bot_Prompt_Inspectability.md — prompt inspection specification (S8.1)

Spec Coverage Matrix

Every Spec section is mapped to a Plan and Task. Sections S6.2 and S8.1 are covered by existing Reference documents (no implementation task required). Section S10.2 is implemented by the same task as S2.2.

Spec SectionDescriptionPlanTask(s)
S1.1Orchestration to Agentic_Prompts renamePlan 2Task 1
S1.2Update_Infrastructure skill updatePlan 2Task 2
S1.3Forge_Chat_Prompt.md refs removed (skills: Forge_Optimizer, Create_Skill)Plan 2Task 3
S1.3Forge_Chat_Prompt.md refs removed (Forge_Agent_Orchestration.md)Plan 5Task 1
S1.4LibreChat refs eliminated (Linear_MCP, Suprsend_MCP, Vercel_MCP, MCP_Development)Plan 2Task 4
S1.5Path fixes (Git_Dashboard, Home_Page, Markdown_To_PDF, Reindex_Typesense)Plan 2Task 5
S1.5Path fixes (Forge_Setup.md)Plan 5Task 4
S1.6forge-discovery tool names (Forge_Agent_Orchestration.md)Plan 5Task 1
S1.7Eager vs Deferred guidance (Forge_Agent_Orchestration.md)Plan 5Task 1
S1.7Eager vs Deferred guidance (Forge_Infrastructure.md)Plan 5Task 2
S1.8MongoDB removal (Forge_Optimizer skill)Plan 2Task 6
S1.9MCP refs removed from documentationPlan 7Task 6
S1.10Page Manager routing (14 skill files)Plan 3Task 1
S1.10Page Manager routing (Forge/README.md, Admin_Panel_Plan.md)Plan 6Task 4
S1.10Page Manager routing (Project Evaluator, Project Worker prompts)Plan 7Tasks 2, 3
S2.1Status approved to published (6 files)Plan 4Task 1
S2.2Remove created/updated/lastUpdated (16 files)Plan 4Task 2
S2.3Add approver field (5 files)Plan 4Task 3
S2.4Forge_Project AGENTS.md frontmatterPlan 4Task 4
S3.1Default gates (Forge_Project_User_Guide.md, Forge_Project_Workflow.md)Plan 6Tasks 1, 2
S3.1Default gates (Project Runner prompt)Plan 7Task 1
S3.2Project Worker prompt typoPlan 7Task 2
S3.3Page Manager prompt tool namePlan 7Task 4
S3.4Project Worker prompt publishedPlan 7Task 2
S4.1API names (Forge_Agents_User_Guide.md)Plan 5Task 3
S4.2Terminology (Forge_Agents_User_Guide.md)Plan 5Task 3
S4.2Terminology (Forge_Infrastructure.md)Plan 5Task 2
S4.3agent-sync removed (Forge_Agent_Orchestration.md)Plan 5Task 1
S4.4JWT Auth Manager removed (Forge_Agent_Orchestration.md)Plan 5Task 1
S5Available Skills listPlan 7Task 5
S6.1Changelog replaces SummaryPlan 6Task 1 (via S6.3)
S6.2Changelog content formatReference doc (no task)
S6.3User Guide references ChangelogPlan 6Task 1
S7.1Choose_AI_Model skill creationPlan 1Task 1
S7.2Use-case names in skillsPlan 2Task 7
S7.2Use-case names in Forge_Infrastructure.mdPlan 5Task 2
S7.3Model reference files creationPlan 1Task 2
S7.3Model quirks removed from skillsPlan 2Task 8
S7.3Model quirks removed from Forge_Infrastructure.mdPlan 5Task 2
S8.1Prompt inspection specificationReference doc (no task)
S8.2Documentation updated (Forge_Agent_Architecture.md)Plan 5Task 5
S9.1Run/Cost evidence in handoff packetsPlan 7Task 7
S9.2Runs document during VerifyPlan 7Task 7
S10.1README/AGENTS consolidationPlan 6Task 5
S10.2Frontmatter date fieldsPlan 4Task 2 (same as S2.2)
S11.1git-changes artifact follow-up todoPlan 7Task 8
S11.2Convo tools usage fields follow-up todoPlan 7Task 8
S12.1Valid phase states (Forge_Project_User_Guide.md, Forge_Project_Workflow.md)Plan 6Tasks 1, 2
S12.1Valid phase states (Project Runner prompt)Plan 7Task 1
S12.2Phase ownership (Project Runner prompt)Plan 7Task 1
S12.3Pending removed (Forge_Project_User_Guide.md, Forge_Project_Workflow.md)Plan 6Tasks 1, 2
S12.3Pending removed (Project_Flow/SKILL.md)Plan 6Task 3
S12.3Pending removed (Project Runner prompt)Plan 7Task 1

Scope: Create the Choose_AI_Model skill with a use-case table and model reference files. This skill is the single source of truth for model selection and model-specific quirk documentation.

Spec sections covered: S7.1 (Choose_AI_Model skill creation), S7.3 (model reference file creation only — quirk removal from source files is in Plan 2 Task 8 and Plan 5 Task 2).

Prerequisite: None.

Task 1 — Create the Choose_AI_Model Skill

Spec S7.1: “A new skill Choose_AI_Model is created in Forge/Skills/. It contains: 1. Use Case Table — pithy use case names, recommended model for each, and brief notes. 2. Model Reference Files — per-model quirk documentation.” See also References/Choose_AI_Model_Skill.md for the exact specification.

Steps

  1. Create Forge/Skills/Choose_AI_Model/SKILL.md with frontmatter:

    ---
name: Choose_AI_Model
description: "Choose the appropriate AI model for a task based on use-case, cost, and capability requirements"
tags: ["ai", "model", "selection"]
---

  2. The SKILL.md body must contain a Use Case Table with three columns: Use Case (pithy, memorable name), Recommended Model (current model), and Notes (brief rationale and quirks). Include at minimum the following use cases:

    Use CaseRecommended ModelNotes
    forge-routerglm-5.2Lightweight routing/classification; cost-efficient
    forge-thinkergpt-5.4Deep reasoning/planning; large context
    forge-executorgpt-5.4Code generation/execution
    forge-evaluatorgpt-5.5Evaluation/review; highest capability
    forge-indexinggpt-5.4-nanoIndexing/embedding generation; fast, cheap

  3. Include a Decision Procedure section: identify use case, check constraints (cost, latency, context window, reasoning depth), select model from table, verify availability.

  4. Include a Convention section stating: “In 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’). When a model is swapped, only this skill’s table needs updating.” This implements S7.2’s convention for the skill itself.

  5. Spawn the Page Manager bot via spawnAgent with { botGroup: "forge", botHandle: "page-manager" } to add a sidebar entry for Forge/Skills/Choose_AI_Model/SKILL.md in the Skills section of the Forge sidebar. The sidebar is a live filesystem index — when a file is created, the sidebar is updated immediately in the same task.

Verify

  • Forge/Skills/Choose_AI_Model/SKILL.md exists with name: Choose_AI_Model in frontmatter
  • The SKILL.md contains a use-case table with at least 5 use cases
  • The SKILL.md contains a decision procedure section
  • The SKILL.md contains the use-case-name convention section
  • Sidebar contains an entry for Choose_AI_Model pointing to Forge/Skills/Choose_AI_Model/SKILL.md

Task 2 — Create Model Reference Files

Spec S7.3: “Model-specific quirk documentation is moved from inline skill procedures into the Choose_AI_Model skill’s model reference files.” This task creates the reference files. The removal of inline quirks from the source files is in Plan 2 Task 8 (skills) and Plan 5 Task 2 (Forge_Infrastructure.md). Affected source files: Forge/Skills/Forge_Optimizer/SKILL.md, Forge/Forge_Infrastructure.md, Forge/Skills/Reindex_Typesense/SKILL.md, Forge/Skills/Typesense_MCP/SKILL.md.

Steps

  1. Create Forge/Skills/Choose_AI_Model/Models/ subfolder.

  2. Create Forge/Skills/Choose_AI_Model/Models/gpt-5.4-nano.md with: model name, provider, context window, cost per 1M tokens (use available documentation). Document the following quirks (sourced from inline documentation in the affected files): requires max_completion_tokens >= 300; does NOT accept temperature parameter. List recommended use cases: forge-indexing, lightweight classification, forge-router (light).

  3. Create Forge/Skills/Choose_AI_Model/Models/gpt-4o-mini.md with: model name, provider, context window, cost per 1M tokens. Document the quirk: used for AI-generated file summaries at index time (from Typesense_MCP/SKILL.md). List recommended use cases: forge-indexing (legacy/alternative).

  4. Create Forge/Skills/Choose_AI_Model/Models/glm-5.2.md with: model name, provider, context window, cost per 1M tokens. Document strengths: cost-efficient for routing/classification. List recommended use cases: forge-router.

  5. Create Forge/Skills/Choose_AI_Model/Models/gpt-5.4.md with: model name, provider, context window, cost per 1M tokens. Document strengths: deep reasoning, large context. List recommended use cases: forge-thinker, forge-executor.

  6. Create Forge/Skills/Choose_AI_Model/Models/gpt-5.5.md with: model name, provider, context window, cost per 1M tokens. Document strengths: highest capability for evaluation/review. List recommended use cases: forge-evaluator.

Verify

  • Forge/Skills/Choose_AI_Model/Models/ contains at least 5 model reference files
  • gpt-5.4-nano.md documents the max_completion_tokens >= 300 quirk and the temperature parameter rejection
  • Each model file documents recommended use cases

Task 3 — Build, Commit, and Push

Spec S7.1, S7.3: This Plan creates the Choose_AI_Model skill and model reference files. 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 (/workspace/erik@uvilo.com/uvilo-os). This is known to fail because package.json has no build script. Proceed regardless.
  2. git add all new files: Forge/Skills/Choose_AI_Model/SKILL.md, Forge/Skills/Choose_AI_Model/Models/gpt-5.4-nano.md, Forge/Skills/Choose_AI_Model/Models/gpt-4o-mini.md, Forge/Skills/Choose_AI_Model/Models/glm-5.2.md, Forge/Skills/Choose_AI_Model/Models/gpt-5.4.md, Forge/Skills/Choose_AI_Model/Models/gpt-5.5.md, and any sidebar changes.
  3. git commit -m "Plan 1: Create Choose_AI_Model skill with use-case table and model reference files"
  4. git push origin dev

Verify

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

Plan 1 Completion Criteria

  • Forge/Skills/Choose_AI_Model/SKILL.md exists with name: Choose_AI_Model frontmatter, a use-case table with at least 5 entries, a decision procedure, and the use-case-name convention
  • Forge/Skills/Choose_AI_Model/Models/ contains at least 5 model reference files, including gpt-5.4-nano.md with the max_completion_tokens and temperature quirks
  • Sidebar entry exists for the Choose_AI_Model skill (added in Task 1)
  • Changes committed and pushed to dev

Dependencies

  • Requires: None
  • Blocks: Plan 2 (model reference files needed for S7.3 quirk extraction), Plan 5 (use-case names needed for S7.2 replacements in knowledge files)