approved Visibility internal Owner erik@uvilo.com Approver _ Created 2026-07-18 Updated 2026-07-19

Knowledge Consistency Spec

The Forge agentic system’s Knowledge files, Bot system prompts, and Skills are fully consistent, current, and aligned with the Forge Charter. All deprecated content is removed, all references point to current systems, all statuses are correct, and charter principles are reflected in documentation and skills.

1. Skills: Currency and Accuracy

All Forge Skills reflect the current system state. No skill references deprecated files, outdated paths, obsolete tool names, or removed systems. No skill directs agents to read a skill when a bot spawn is the canonical routing mechanism. (Addresses R2, R3; findings 1.1-1.3, 2.1, 2.2, 2.4, 2.5, 3.5, 4.3, G3-1)

1.1 Orchestration Skill Renamed to “Agentic Prompts”

The Orchestration skill is renamed to Agentic_Prompts. The deprecation notice is removed. The skill’s description explains that its /references directory contains system prompts for OpenClaw and Clause Code that can be used as inspiration and information when building skills. The skill remains in the Available Skills list under its new name.

1.2 Update_Infrastructure Skill Reflects Current Practices

The Update_Infrastructure skill is updated to reflect current infrastructure practices. The “outdated” warning is removed. The skill references docs/deployment.md in the uvilo-mono repository (prodRepoRoot) and the uvilo-mono repo structure for current deployment, database branching, migration, and environment configuration procedures.

1.3 Forge_Chat_Prompt.md References Removed

No skill or knowledge file references Forge/Configs/Agents/Forge_Chat_Prompt.md. The file does not exist — the Forge Chat prompt lives in the Bot database. Specifically:

Forge_Optimizer skill: The prerequisite checking for Forge_Chat_Prompt.md is removed.
Create_Skill skill: Step 5 is updated to reference the Persistent Knowledge database prompt (where the Available Skills list resides) instead of the file path.
Forge_Agent_Orchestration.md: The reference to Forge_Chat_Prompt.md -> ## PROJECT ROUTING is removed or updated to reference the Bot database prompt.

1.4 LibreChat References Eliminated

No skill references librechat.yaml or LibreChat-era configuration. Specifically:

Linear_MCP and Suprsend_MCP skills: References to librechat.yaml are replaced with “Bot/MCP configuration” or “uvilo-mono Bot system.”
Vercel_MCP skill: The bypass secret is read from the VERCEL_PROTECTION_BYPASS environment variable via /proc/1/environ, consistent with Forge_Infrastructure.md and the Playwright_MCP skill. The old method of reading from /workspace/librechat/.secrets is removed.
MCP_Development skill: “LibreChat’s MCP client” is replaced with “uvilo-mono’s MCP client.”

1.5 Filesystem Paths Corrected

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
Forge/Skills/Git_Dashboard/SKILL.md
Forge/Skills/Home_Page/SKILL.md
Forge/Skills/Markdown_To_PDF/SKILL.md
Forge/Skills/Reindex_Typesense/SKILL.md

1.6 forge-discovery Tool Names Updated

The Forge_Agent_Orchestration.md discovery MCP tools table matches actual tool names:

Actual Tool Name	Description
`forge-discovery__list_departments`	Lists departments
`forge-discovery__list_dept_projects`	Lists projects in a department (not `list_projects`)
`forge-discovery__get_project`	Returns full project data including phase and files (consolidates former tools)
`forge-discovery__list_skills`	Lists skills
`forge-discovery__get_skill`	Returns full SKILL.md content (not `get_skill_details`)
`forge-discovery__find`	Search departments, projects, and skills by keyword

1.7 Eager vs Deferred Tool Guidance

Documentation does not assert which specific MCP tools are eager or deferred, as this classification can change — a tool can become eager by simply being mentioned in a system prompt. 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.

1.8 MongoDB References Removed

No skill or knowledge file references MongoDB or the mongodb skill. MongoDB has been completely removed from the system. The Forge_Optimizer skill’s reference to Forge/Skills/MongoDB/SKILL.md for connection details is removed.

1.9 MCP Skills (Linear, Suprsend, Vercel) — References Removed, Skills Retained

The Linear_MCP, Suprsend_MCP, and Vercel_MCP skills remain on disk but are not listed in the Available Skills list. References to these MCPs are removed from documentation. The skills are retained because they may contain repurposable knowledge for future MCP connections via Composio. Their frontmatter status remains draft.

1.10 Page Operations Routed via Page Manager Bot, Not Manage_Pages Skill

No skill or prompt directs an agent to read or invoke the Manage_Pages skill for sidebar entries, page creation, or page operations. Instead, skills and prompts instruct agents to add sidebar entries and perform page operations by spawning the Page Manager bot via spawnAgent with { botGroup: "forge", botHandle: "page-manager" }.

The Manage_Pages skill remains on disk as procedural guidance composed into the Page Manager bot’s prompt via include directive. It is not read directly by agents at runtime.

Affected skill files (currently direct agents to “use the Manage_Pages skill” for sidebar/page work):

Forge/Skills/Create_Skill/SKILL.md
Forge/Forge_Project/Skills/Project_Vision/SKILL.md
Forge/Forge_Project/Skills/Project_Research/SKILL.md
Forge/Forge_Project/Skills/Project_Spec/SKILL.md
Forge/Forge_Project/Skills/Project_Plan/SKILL.md
Forge/Forge_Project/Skills/Project_Execute/SKILL.md
Forge/Forge_Project/Skills/Project_Execute_Eval/SKILL.md
Forge/Forge_Project/Skills/Project_Vision_Eval/SKILL.md
Forge/Forge_Project/Skills/Project_Spec_Eval/SKILL.md
Forge/Forge_Project/Skills/Project_Plan_Eval/SKILL.md
Forge/Forge_Project/Skills/Project_Extract/SKILL.md
Forge/Forge_Project/Skills/Project_Archive/SKILL.md
Forge/Forge_Project/Skills/Project_Complete/SKILL.md
Forge/Forge_Project/Skills/Project_Rename/SKILL.md

Affected bot system prompts (database records):

The following bot prompt records contain stale manage-pages skill page/sidebar routing language and must be updated to replace it with the canonical Page Manager spawn pattern — spawnAgent with { botGroup: "forge", botHandle: "page-manager" }:

Project Evaluator (prm_cmqmkjxc6000u01o6ddc7p9kn, handle project-evaluator) — Key Rules: currently directs agents to “use the manage-pages skill” for page creation, moving, deletion, frontmatter updates, and sidebar updates; must be updated to spawn the Page Manager bot via spawnAgent with { botGroup: "forge", botHandle: "page-manager" }
Project Worker (prm_cmqmmf7vr000b01p15biyasvf, handle project-worker) — Key Rules: currently directs agents to “use the manage-pages skill” for page creation, moving, deletion, frontmatter updates, and sidebar updates; must be updated to spawn the Page Manager bot via spawnAgent with { botGroup: "forge", botHandle: "page-manager" }

Affected documentation files:

Forge/README.md — “use the Manage Pages skill and Forge Document Structure”
Forge/Output/Admin_Panel_Plan.md — “per the manage-pages skill”

Not affected (legitimate references, out of scope):

Forge/Skills/Manage_Pages/SKILL.md and SKILL.raw.md — the skill itself
Page Manager bot prompt (prm_cmqmgkp1v000o01o6kc6b8t6m) — includes the skill via include directive
Forge Environment prompt (prm_cmq6n3s3k000201s302cnjg6o) — already instructs spawning the Page Manager bot
Task Runner (prm_cmqmmwka0000j01p100n9tzss) — routing table already routes page/frontmatter/sidebar work to the Page Manager bot, not to reading the Manage_Pages skill
Forge/Forge_Content_System.md and Forge/Forge_Document_Structure.md — references to build infrastructure files (generate_view_pages.ts, view_folder_config.json), not skill-reading instructions
Changelog format examples that mention Manage_Pages/SKILL.md as an example filename
Persistent Knowledge prompt (prm_cmq83857c000101mzrhmopc03) — lists “manage-pages” in Available Skills list (covered by S5)

(Identified at the G3 — Spec_Eval human gate, 2026-07-19.)

2. Knowledge Files: Status and Frontmatter

All Forge Knowledge files have status: published and complete frontmatter. (Addresses R4, R5; findings 3.1, 3.2, 4.1, 4.4)

2.1 Status: `approved` to `published`

Six root-level knowledge files have status changed from approved to published:

File	Current Status	Target Status
`Forge/Forge_Charter.md`	approved	published
`Forge/Forge_Agent_Architecture.md`	approved	published
`Forge/Forge_Content_System.md`	approved	published
`Forge/Forge_Document_Structure.md`	approved	published
`Forge/Forge_Infrastructure.md`	approved	published
`Forge/Forge_Setup.md`	approved	published

2.2 Frontmatter Convention: `created` and `updated` Removed

Knowledge files do not maintain created or updated fields in YAML frontmatter. Creation and modification dates are sourced from the filesystem and git history, eliminating manual maintenance burden. The frontmatter convention for knowledge files is:

Field	Required	Description
`title`	Yes	Document title
`visibility`	Yes	`internal` or `public`
`status`	Yes	`published`, `draft`, or `archived`
`owner`	Yes	Owner email (e.g., `erik@uvilo.com`)
`approver`	Yes	Approver handle or empty string

The created, updated, and lastUpdated fields are removed from the frontmatter convention. Existing files with these fields have them removed during execution.

2.3 Missing Frontmatter Fields Added

All knowledge files have complete frontmatter per the convention above. Specifically, the following files have missing approver fields added:

Forge/Forge_Agent_Architecture.md
Forge/Forge_Content_System.md
Forge/Forge_Infrastructure.md
Forge/Forge_Setup.md
Forge/AGENTS.md

2.4 Forge_Project AGENTS.md Frontmatter Added

Forge/Forge_Project/AGENTS.md has complete frontmatter (title, visibility, status, owner, approver).

3. Bot Prompts: Consistency and Publication

All forge-group Bot system prompts are consistent with each other and with documentation, and all are published. (Addresses R4, R5; findings 3.3, 3.7, 3.8, 4.2)

3.1 Default Human Gates Aligned

The default human gates are consistent across all sources:

Source	Default Gates
`Forge_Project_Workflow.md` S13.2	`Vision_Eval`, `Spec_Eval`, `Plan_Eval`, `Verify`
`Forge_Project_User_Guide.md` S5	`Vision_Eval`, `Spec_Eval`, `Plan_Eval`, `Verify`
Project Runner bot prompt	`Vision_Eval`, `Spec_Eval`, `Plan_Eval`, `Verify`

Vision_Eval is included as a default gate in the Workflow and User Guide docs.

3.2 Project Worker Bot Prompt Typo Fixed

The Project Worker bot prompt’s Standard Handoff Packet table reads Work-Product Path or Link (matching all other bot prompts), not Work-Product Link (double space).

3.3 Page Manager Bot Prompt Tool Name Fixed

The Page Manager bot prompt references forge-filesystem (the correct MCP server name), not uvilo-filesystem.

3.4 Project Worker Bot Prompt Published

The Project Worker bot prompt (prm_cmqmmf7vr000b01p15biyasvf) has publishedAt set to a timestamp — it is no longer a draft.

4. Documentation: APIs, Tools, and Terminology

All Forge documentation references current APIs, tool names, and terminology. (Addresses R3; findings 2.3, 2.6, 2.7, 2.8)

4.1 API Names Updated in Forge_Agents_User_Guide.md

Forge/Forge_Agents_User_Guide.md uses current API names and patterns:

Old Reference	Current Reference
`spawn_agent`	`spawnAgent`
`agent_id` / `task_prompt`	`message`, `botId` or `botGroup`+`botHandle`, `mode`
`SCHEDULE_CONFIG`	`schedules.ts`
`createTodoItem({ group, title, body })`	`createTodoItem({ todoListId, name, body })`
`/spawn` command	Removed (no such slash command exists)
`/project-create` command	Removed (no such slash command exists)
`gpt-4o` model	Current model name or use-case reference

Curl examples use current spawnAgent parameters.

4.2 Terminology: uvilo-mono vs forgentic

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.

4.3 “agent-sync” Terminology Removed

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. The Forge_Agent_Orchestration.md Include Directive section describes prompt composition without referencing “agent-sync.”

4.4 JWT Auth Manager Reference Removed

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.

5. Available Skills List

The Available Skills list in the Persistent Knowledge prompt matches the actual skills on disk. (Addresses R4; findings 3.5, 3.6)

5.1 Skills Added

The following skills are added to the Available Skills list:

artifacts-markdown (Artifacts_Markdown)
audit-context (Audit_Context)
start-astro-dev (Start_Astro_Dev)
test-tools (Test_Tools)

5.2 Skills Removed

The following skills are removed from the Available Skills list:

orchestration — renamed to agentic-prompts (see S1.1)
mongodb — does not exist (see S1.8)

5.3 Skills Renamed

orchestration to agentic-prompts (see S1.1)

5.4 Final Skills List

The Available Skills list includes all published skills with folders in Forge/Skills/, excluding Linear_MCP, Suprsend_MCP, and Vercel_MCP (retained on disk but not listed — see S1.9).

6. Changelog Convention

The project Changelog replaces the Summary as the file change manifest. (Addresses R4; finding 3.4)

6.1 Changelog Replaces Summary

{Project}_Summary.md is not used. The file change manifest is {Project}_Changelog.md, consistent with Forge_Project_Workflow.md.

6.2 Changelog Content

The Changelog lists all files and database records modified across all Plans:

Files: commit hash before changes, list of files changed, commit hash after changes
Database records: model, ID, name (when available), new version (when available)

See References/Changelog_Format.md for the exact format.

6.3 User Guide Updated

Forge_Project_User_Guide.md references {Project}_Changelog.md (not {Project}_Summary.md) as the document created in the Create phase.

7. Charter: Provider Independence

Model references in skills and documentation use use-case names, not hardcoded model names. (Addresses R6; finding 5.1)

7.1 Choose_AI_Model Skill

A new skill Choose_AI_Model is created in Forge/Skills/. It contains:

Use Case Table — pithy use case names, recommended model for each, and brief notes
Model Reference Files — per-model quirk documentation

See References/Choose_AI_Model_Skill.md for the exact specification.

7.2 Use-Case References in Documentation

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 the Choose_AI_Model skill’s table needs updating.

7.3 Model Quirks Moved to Reference Files

Model-specific quirk documentation is moved from inline skill procedures into the Choose_AI_Model skill’s model reference files. Affected files:

Forge/Skills/Forge_Optimizer/SKILL.md
Forge/Forge_Infrastructure.md
Forge/Skills/Reindex_Typesense/SKILL.md
Forge/Skills/Typesense_MCP/SKILL.md

8. Charter: Inspectability by Humans

Bot system prompts are inspectable by humans using artifact types. (Addresses R6; finding 5.2)

8.1 Prompt Inspection via application/vnd.prompt-version

Documentation describes 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. When opened, the UI loads version N and N-1 from the database and displays a unified text diff.

See References/Bot_Prompt_Inspectability.md for the exact specification.

8.2 Documentation Updated

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.

9. Charter: Transparency

Run/cost evidence is consistently tracked and reported. (Addresses R6; finding 5.3)

9.1 Run/Cost Evidence in Handoff Packets

All bot handoff packets include Run/Cost Evidence. When exact evidence is available, it links to the run summary. When exact evidence is unavailable, the packet states “exact evidence is unavailable” as a consistent fallback.

9.2 Runs Document During Verify

The Runs document ({Project}_Runs.md) is generated during the Verify phase even when exact data is unavailable, recording available context.

10. Open Design Decisions

The following design decisions are recommended in this Spec and require Plan-phase confirmation.

10.1 README.md and AGENTS.md Redundancy (from finding 4.1)

Recommendation: Evaluate each README.md and AGENTS.md pair in Forge folders. Where content overlaps, consolidate into AGENTS.md (which has richer structure: related skills, documents, knowledge sources) and eliminate README.md. For project folders, AGENTS.md serves as the canonical context file for both agents and humans.

Rationale: Maintaining two files with overlapping content in every folder creates unnecessary maintenance. AGENTS.md already contains the project description, canonical identifier, related skills, documents, and knowledge sources — making README.md redundant in most cases.

Status: Recommended. The Plan phase evaluates the value of each file and decides whether to consolidate or eliminate.

10.2 Frontmatter Date Fields (from finding 3.2)

Recommendation: Remove created, updated, and lastUpdated from the frontmatter convention. Use filesystem and git metadata as the source of truth for creation and modification dates.

Rationale: Manual date maintenance is error-prone (as demonstrated by the impossible created-after-updated dates in finding 3.2). Git provides accurate, automatic date tracking.

Status: Recommended. The Plan phase confirms this convention and updates the frontmatter standard documentation.

11. Follow-up Action Items

The following items are outside the scope of this project’s Execute phase (they involve platform code changes) and are tracked as todo items for future work.

11.1 git-changes Artifact Enhancement (from finding 5.2)

Todo: Modify the application/vnd.git-changes artifact type to accept two commit hashes as parameters, displaying the diff between them. This makes git-changes useful for comparing arbitrary commits, not just changes vs upstream.

11.2 Convo Tools Usage Fields (from finding 5.3)

Todo: Update the conversation tools to include usage fields (token counts, model used, cost data) so that Run/Cost evidence can be automatically captured in handoff packets.

12. Phase States: “Pending” Removed

Pending is not a valid project phase state. The only valid phase states are Started, Completed, and Blocked. All references to Pending as a phase state are removed. (Addresses R4; finding G3-2, identified at the Spec_Eval human gate, 2026-07-19.)

12.1 Valid Phase States

The valid Phase: value statuses are Started, Completed, Blocked, and Paused (added 2026-07-23). There is no Pending state. The authoritative definition in Forge/Forge_Project/Forge_Project_Workflow.md reflects this:

A phase agent owns only its own phase state and writes only its phase values: {Phase}_Started, {Phase}_Completed, or {Phase}_Blocked.

12.2 Phase Ownership: Each Agent Sets Its Own State

Every project skill/agent is responsible for setting its own phase to _Started at the beginning of its work and to _Completed once the work is done. The Project Runner does not pre-set a phase to a “Pending” value awaiting agent start; it dispatches the responsible agent, which sets _Started itself on beginning and _Completed on finishing. A phase is _Blocked only when the owning agent cannot proceed and escalates.

12.3 “Pending” Phase-State References Removed

No Phase: value is ever _Pending, and no documentation or prompt lists Pending among the valid phase states.