archived Visibility internal Owner erik@uvilo.com Approver erik@uvilo.com Created 2026-06-25 Updated 2026-06-25

Forge Project Cleanup Research

Charter Alignment

Research area: Forge Charter alignment with project flow
Related Vision requirement: R6 — Align project flow with Forge Charter
Sources reviewed:

Forge/Forge_Charter.md
Forge/Skills/Project_Flow/SKILL.md
Forge/Forge_Project_Workflow.md
Forge/Forge_Project_User_Guide.md
Forge/Forge_Agent_Architecture.md
Forge/Forge_Agent_Orchestration.md

Status key: ✅ Compliant · ⚠️ Partial · ❌ Violation

Alignment Matrix

Charter principle / guideline	Assessment	Current project-flow evidence	Gap / risk	Suggested correction
Forge is the single source of truth for organizational vision, plans, procedures, and agents.	⚠️ Partial	Project work-products and Forge knowledge docs are durable markdown; Bot configuration and prompt versions are centrally managed.	Current flow still splits source-of-truth state across durable work-products, flat-file `Erik_Todo` / `Agent_Todo`, WIP scratchpads, conversations, and possibly prompt database records. Bot prompts may drift from Knowledge.	Declare Knowledge + Skills + Bot prompt records + durable project work-products as the canonical source set; remove stale WIP state; migrate human/agent queues to the `todos` tool group; add bot-prompt compliance checks against canonical Knowledge.
Uvilo-specific information lives in department folders that plug into the Forge framework.	✅ Compliant	Department/project hierarchy is used consistently: `Forge/Projects/{Project}` and `Forge/Skills/*`.	No material gap found for project flow.	Keep project artifacts department-scoped and avoid embedding Uvilo-specific project assumptions in general Forge skills unless explicitly intended.
Human sovereignty: humans make decisions that matter; agents execute.	⚠️ Partial	Human gates exist after eval-converged phases; Research decisions require user approval before Spec; Runner escalates blocked states.	The current Research skill allows obvious solutions to be “marked as decided,” and auto-dispositions may make decisions if preference boundaries are unclear. Flat-file todo language can hide which human must decide.	Keep agent outputs as recommendations unless a decision is mechanical/no-op; require explicit owner/approver attribution for material Research decisions; log auto-dispositions as reversible informational items with rationale; route human decisions through `todos` with owner, artifact link, and requested decision.
Clarity: decisions are traceable from research through specification to outcome.	⚠️ Partial	Lifecycle has Vision → Research → Spec → Plan → Eval reports; evaluations are persisted.	WIP and conversation duplication can create parallel narratives. Specs show final decisions, but handoffs may contain substantive content not captured in work-products.	Require substantive reasoning and decisions to live in Research / Spec / Plan / Eval files; keep conversation handoffs to routing context and links; add eval checks for “no substantive work-product duplicated only in convo.”
Stewardship: consider customers, personnel, management, shareholders, and community.	⚠️ Partial	Project Vision and Spec can include stakeholder requirements, but current templates do not force stakeholder impact review.	Project flow may optimize implementation correctness without explicitly checking stakeholder trade-offs.	Add a lightweight stakeholder-impact prompt/checklist to Vision, Research, Spec, Verify, and relevant eval templates when project scope affects stakeholders.
Continuous improvement: processes research, implement, and improve themselves on an ongoing cycle.	✅ Compliant	Project lifecycle includes Extract, Extract_Eval, Forge Optimizer guidance, persisted reports, and this cleanup project itself.	The capability exists, but drift in WIP/todo docs shows enforcement is inconsistent.	Keep Extract and optimizer as mandatory review points for project-system changes; add scheduled audits for project skills, docs, and prompts.
Accessibility: power without complexity.	⚠️ Partial	User Guide explains the lifecycle and Project Runner abstracts phase dispatch.	Users are exposed to stale implementation details (`Erik_Todo`, WIP, paste instructions, 14 vs 15 phase wording) and must infer which agent to invoke.	Replace file-based todo instructions with `todos` UI/tool semantics; standardize user-facing phase count and names; include direct artifact links and minimal action text.
Goal: serve as the single source of truth for all organizational information.	⚠️ Partial	Durable markdown docs and project work-products support this.	Same source-of-truth split as above: flat-file queues, WIP, conversations, and prompt DB drift can contradict docs.	Define canonical status/state per artifact type; ensure each agent writes only its phase work-product and Phase state; use prompt/skill audits to eliminate drift.
Goal: structure the organization into departments with cross-functional links.	✅ Compliant	Department roots, `Projects/`, `Skills/`, and archived project structure are documented.	No material gap found.	Preserve department/function boundaries in project skills and sidebar generation.
Goal: automate research, implementation, and continuous improvement of organizational processes.	✅ Compliant	Project Thinker/Worker/Evaluator/Runner roles automate Research, Plan, Execute, Eval, Verify, Extract, and Complete.	No material gap in lifecycle shape; implementation docs are outdated in places.	Update stale execution details without changing the lifecycle shape.
Goal: run as many organizational functions as possible.	✅ Compliant	Project system runs project management and implementation workflows through agents.	No direct project-flow gap.	Keep project flow general enough to run non-code organizational projects, not only software changes.
Goal: provide an easy, repeatable process to plan, create, and manage initiatives.	⚠️ Partial	Standard lifecycle and Project Flow skill provide repeatability.	Documentation conflicts: User Guide says 14-phase sequence while Workflow labels 15 phases including Complete; WIP/todo details are obsolete.	Normalize lifecycle wording across Skill, Workflow, User Guide, bot prompts, and templates; remove stale WIP/todo references; make Project Flow the canonical dispatcher contract.
Goal: optimize organizational performance and success.	⚠️ Partial	Forge Optimizer and run summaries exist; context boundaries reduce waste.	Cost/run evidence is described as available/optional, not consistently mandatory in phase completion.	Require cost/token/run summary capture for spawned project-agent work or document why unavailable; use optimizer after significant Execute_Eval/Verify loops.
Scope: Forge is an orchestration and partial execution layer, not a replacement for specialized external systems.	✅ Compliant	Orchestration doc describes thin dispatcher; Worker uses external tools; Forge verifies outcomes.	No material gap.	Maintain clear boundary between orchestration, project work-products, and specialized execution tools.
Scope: integrate mature external tools rather than rebuild them.	⚠️ Partial	`spawnAgent`, MCP tools, Typesense, Postgres, Inngest, and Bot API integration are documented.	Todo/checklist is still documented as a flat-file minimal implementation despite the new `todos` tool group requirement.	Replace flat-file todo/checklist mechanism with exact `todos` group tool calls and document the mapping from prior `Erik_Todo` behaviors.
Scope: Forge handles specification, planning, and verification; specialized execution is delegated and checked.	✅ Compliant	Workflow separates Spec, Plan, Execute, Execute_Eval, Verify; Evaluator checks Worker outcomes.	No material gap.	Preserve fresh Evaluator context and durable eval reports.
Scope: Forge must publish outward according to organization-level visibility.	⚠️ Partial	Astro/Starlight docs, sidebar convention, and frontmatter visibility exist.	Sidebar/page maintenance depends on Page Manager and may drift; frontmatter conventions differ between template (`created`/`updated`) and Workflow (`lastUpdated`).	Use Page Manager for page/sidebar changes; standardize frontmatter fields; verify generated docs output during build.
Scope: designed for smaller AI-first organizations where human/agent boundaries evolve.	⚠️ Partial	Interactive vs autonomous Runner modes and auto-fix loops support changing human involvement.	WIP exists because older conversations could crash; current environment auto-saves conversations, so WIP locks in an outdated boundary.	Remove WIP as active workflow state; rely on durable work-products, Execute_State, persisted conversations, and todo items for recovery.
Requirement: provider independence; components must be replaceable through interfaces.	⚠️ Partial	Bot API, `spawnAgent`, and MCP-style tool discovery create interface boundaries.	Docs also encode uvilo-mono/Postgres/Typesense/Inngest specifics; old LibreChat-derived WIP/todo references remain.	Document provider-specific implementations behind stable interfaces; remove legacy runtime assumptions; keep prompts/skills using tool/interface names rather than vendor-specific behavior where possible.
Requirement: cost efficiency; token and infrastructure costs measured and optimized; agents carry only needed context.	⚠️ Partial	Project Flow and phase skills define context boundaries; Agent Architecture emphasizes on-demand skills and tool loading.	Handoffs may duplicate substantive work-product content; WIP and conversation copies increase state surface; run/cost summaries are not enforced in every phase.	Enforce concise handoff payloads with artifact links; remove WIP; require run/cost capture or explicit unavailable note in `{Project}_Runs.md` / reports.
Requirement: tool integration; connect with organization platforms/tools.	❌ Violation	Orchestration doc still says todo/checklist is flat-file `Agent_Todo.md`, `Erik_Todo.md`; Project Flow and User Guide instruct `Erik_Todo`.	Current project Vision says Erik_Todo must be replaced with new AI tools in the `todos` group; existing flow violates that target and weakens integration.	Inventory current `todos` tools, map old behaviors to exact tool calls, update Knowledge/Guides/Skills/Bot prompts, and remove active instructional references to `Erik_Todo` except historical context.
Requirement: multi-user with automatic merging, version control, and archival.	⚠️ Partial	Git-backed markdown supports version control; archived projects are documented.	Flat-file user/agent todos and per-user WIP scratchpads do not provide robust multi-user merging; concurrent research agents can overwrite unless append-safe patterns are used.	Use `todos` group for user-scoped tasks; use append-safe historical work-products; document merge/conflict handling and agent ownership of phase files.
Requirement: accountability; every project has an owner and approver.	⚠️ Partial	Frontmatter includes owner/approver; project docs use `owner: "erik@uvilo.com"`.	Templates allow blank approver; handoffs/todo items may not explicitly name responsible owner/approver.	Require owner and approver fields to be set or explicitly marked pending before human gates; include responsible user in todo metadata and report headers.
Requirement: transparency; every decision traceable; Research shows conclusions; Specs show final decisions; both preserved.	⚠️ Partial	Research, Spec, eval reports, and historical append-only semantics support traceability.	Conversation-only decisions, WIP notes, and prompt drift can escape Research/Spec.	Add strict work-product communication rules to project bots; update eval checklists to fail decisions not recorded in the proper artifact; use prompt-version artifacts for bot prompt changes.
Requirement: resilience; recover from agent errors/tool failures; state persists; work never lost to crashed conversation.	⚠️ Partial	Phase file, reports, git, persisted conversations, and AgentJob monitoring provide resilience.	WIP is now obsolete and can become an inconsistent second state store; docs still say agents resume from WIP.	Remove WIP from active flow; recovery should reconstruct from Phase, current work-product, Execute_State, persisted conversation/job metadata, and git status.
Requirement: evolvability; meta-process for improving Forge itself.	✅ Compliant	Project lifecycle includes Extract and Forge Optimizer; this cleanup project is an explicit meta-process.	No structural gap, but stale docs show audit cadence needs improvement.	Add periodic project-system drift audits across Knowledge, Skills, Guides, Prompts, and Bot configs.
Constraint: security is non-negotiable.	⚠️ Partial	Agent Architecture documents bot access control and least-privilege tools.	Project flow templates/evals do not require security review when a project touches sensitive data or privileged tooling.	Add security/access-control checkpoints to Vision/Spec/Plan/Eval templates for projects that touch sensitive data or tools.
Constraint: privacy serves the mission and is an organizational decision.	⚠️ Partial	User/conversation context has opt-in write policy; bot access is scoped.	Project flow does not surface privacy decisions explicitly in Research or Spec.	Add privacy-impact decision points where relevant and record organizational owner approval.
Constraint: simplicity of use, not of system.	⚠️ Partial	Project Runner hides orchestration; User Guide gives human instructions.	Users still see operational internals like `Erik_Todo`, WIP, and paste instructions instead of a clean todo/action interface.	Move user-facing gates to the `todos` system with concise action labels, artifact links, and hidden machine metadata.
Constraint: inspectability by humans; personnel can view skills and agent internals.	⚠️ Partial	Skills and Knowledge are markdown; Bot prompt versions can be reviewed via artifacts.	Bot prompt source of truth is in the database/admin UI and may not be discoverable from project docs; drift review is not mandatory.	Add Bot/prompt inventory links or prompt-version artifacts to project audits; ensure project bot prompts are reviewed alongside Knowledge and Skills.

Focus Area Notes

Erik_Todo / todos

Charter principles involved: Human sovereignty, accessibility, tool integration, multi-user operation, resilience, transparency, and accountability.
Current state: Project_Flow/SKILL.md, Forge_Project_User_Guide.md, and Forge_Agent_Orchestration.md still document Erik_Todo.md / Agent_Todo.md flat-file workflows.
Alignment finding: ❌ Active violation against Tool Integration and ⚠️ partial alignment for Human Sovereignty and Accessibility. The system can still create human gates, but the implementation is stale for the uvilo-mono environment and does not use the current todos tool group.
Recommended correction: Replace active instructions with exact todos tool calls; retain the durable-work-product link requirement; encode responsible user, project, phase, status, artifact URL, and requested decision in the todo item; remove or mark legacy flat-file references as historical only.

WIP system

Charter principles involved: Resilience, clarity, cost efficiency, multi-user, simplicity, and single source of truth.
Current state: Forge_Project_Workflow.md, Forge_Project_User_Guide.md, and Forge_Agent_Architecture.md still define WIP as active crash-recovery state.
Alignment finding: ⚠️ Partial trending to ❌ for the new environment. WIP originally supported resilience, but now duplicates state because conversations persist on every step.
Recommended correction: Remove WIP from active templates, skills, prompts, sidebar convention, and agent memory docs. Use Phase + Execute_State + durable reports + persisted conversation/job history + git status for recovery.

Work-product communication

Charter principles involved: Clarity, transparency, resilience, cost efficiency, inspectability, and single source of truth.
Current state: The workflow defines durable work-products, but current project Vision notes agents are not consistently communicating through them.
Alignment finding: ⚠️ Partial. The document model is strong, but enforcement across bot prompts and handoffs is incomplete.
Recommended correction: Standardize agent responses and handoffs to concise routing context only: project, phase, skill, work-product path/link, status, next step, and decision requested. Substantive findings belong in Vision, Research, Spec, Plans, and Eval/Verify/Extract reports.

Agent handoff patterns

Charter principles involved: Accountability, resilience, cost efficiency, human sovereignty, provider independence, and inspectability.
Current state: Handoffs use Phase files, spawnAgent, fresh evaluator sessions, and interactive/autonomous Runner modes. This is broadly aligned.
Alignment finding: ⚠️ Partial because todo handoffs are stale, some references use ambiguous agent handles (project-bot vs Project Runner), and handoff content can become conversation-heavy.
Recommended correction: Define a canonical handoff packet: department, project, current Phase value, responsible agent/bot handle, skill, work-product path/link, status, next action, user decision needed if any, and spawned job ID when applicable. Keep Phase as the state signal and work-products as the evidence source.

Recommendation

Treat the Charter alignment corrections as required constraints for the Spec phase of Forge_Project_Cleanup:

Replace Erik_Todo / Agent_Todo active workflows with the todos tool group while preserving artifact-linked human gates.
Remove WIP from active project flow and recovery instructions.
Enforce durable work-product communication in project bot prompts, skills, and eval criteria.
Standardize handoff packets and Phase-file ownership rules.
Add explicit checks for stakeholder stewardship, security/privacy where relevant, accountability fields, prompt inspectability, and run/cost evidence.

Decision

Approved by user for Spec input. The five correction constraints above are accepted as inputs to the Spec phase. Approval context: the Spec phase task instruction for Forge_Project_Cleanup on 2026-06-25 stated that Research approved these correction constraints as Spec inputs.