Journal entry / AI / ML

OmniForge Labs: Building a Software Shop Around AI

It is surprisingly easy to give an AI team six names and a company charter. The harder question arrives a little later: who decides the work is actually finished, and what evidence do they have?

That question is the starting point for OmniForge Labs, an experiment in giving AI-assisted software development an operating structure. There are roles, stages, review gates, logs, and required artifacts. There is also a rather less glamorous concern: making sure “done” means something more useful than a confident paragraph at the end of a conversation.

The repository is now public, and the experimental v0.1 implementation is merged into main. It has a working local runner, a browser dashboard, a background worker, and a self-contained demo. The larger ambition is a coordinated software shop powered by AI roles. This first version establishes the process that those roles would have to work inside.

Explore OmniForge Labs on GitHub · Experimental v0.1 changes and validation

What to expect on screen

The interface is deliberately practical: create a ticket, inspect its stage, decide whether to approve the next step, and follow the evidence. Click an image to inspect it at full size.

Source-derived OmniForge dashboard preview with Create Ticket, Worker Loop, a paused ticket, and a delivered ticket.
Dashboard preview / create tickets, control the worker, and distinguish paused work from completed work.

A software shop needs more than job titles

The concept is a small software organization with six distinct responsibilities. Rowan manages delivery. Kade owns architecture. Nyx investigates technical options. Vega handles implementation. Quinn concentrates on testing. Ember thinks about packaging and release.

The names give the roles a little personality, but the useful part is the division of responsibility. A research recommendation, an implementation change, and a release decision should have different expected outputs. Giving all three to an undifferentiated assistant makes it too easy for the same stream of reasoning to propose a solution, implement it, and congratulate itself on passing inspection.

RoleHandleResponsibility
DeliveryRowanScope, stages, acceptance criteria
ArchitectureKadeDesign and technical boundaries
ResearchNyxOptions and technical risk
ImplementationVegaCode and execution
QAQuinnTests and evidence
ReleaseEmberPackaging and operational handoff

⚙ Engineering note / how the roles guide the work

The role charters give a person or external AI assistant a clear brief: what decisions to make, what work to produce, and what evidence to hand off. Rowan turns the request into scope and acceptance criteria; Kade and Nyx develop the design and investigate technical choices; Vega implements; Quinn defines and checks test evidence; Ember prepares delivery. The runner turns those handoffs into an executable workflow, running stage commands, checking required artifacts and assertions, pausing for approval, and recording the result.

Making work pass through a real process

OmniForge organizes a ticket into eight possible stages: intake, plan, design, research, implement, test, integrate, and deliver. A project manifest defines the commands for each configured stage. A separate gate configuration defines where execution pauses and where a failure should send the next attempt.

The point is to make progress inspectable. A stage needs its required Markdown artifact, its commands must succeed, and any configured assertions must pass. The runner can check for a file, verify JSON keys, or require a minimum number of entries in a JSON array. These are modest building blocks, but they move the workflow from “the assistant said it worked” toward checks that can be repeated.

Eight OmniForge stages, with approval before design, test and deliver commands. Each stage checks commands, evidence and assertions; passing advances the ticket, while failure records a retry destination.
From request to delivery / stage evidence, human review gates, and bounded retry routing.
StageEvidence fileDemo review gate
Intakeintake.md
Planplan.md
Designdesign.mdApproval required
Researchresearch.md
Implementimplementation.md
Testtest_report.mdApproval required
Integrateintegration_report.md
Deliverdelivery.mdApproval required

The eight-stage model is configurable: a project can omit stages. In that case, “delivered” means the configured pipeline passed. It does not mean every conceivable test ran, every document received expert review, or the resulting application is ready for every production environment.

🔧 Engineering note / the gate comes before the work

The demo pauses before executing design, test, and delivery commands. At the test gate, the reviewer can inspect implementation evidence before authorizing testing. At the delivery gate, test and integration evidence are available before packaging proceeds. The gate is permission to enter the next stage; it is not a claim that the upcoming stage has already passed.

Source-derived ticket page preview showing a test approval gate, run controls, history, and workspace document links.
Ticket review preview / a test gate awaiting approval, alongside run controls, history, and editable workspace documents.

An approval should have an expiration date

One of the useful questions in preparing v0.1 was whether an approval still means anything after the underlying work changes. If someone approves a design, then the inputs or evidence are revised, retaining a simple “approved: true” flag can turn an intentional review into an accidental permanent exemption.

Approvals are now single-use and tied to a fingerprint of the project configuration, editable Markdown inputs, and Markdown evidence through the gate. Changed material requires another approval. Approving a paused ticket puts it back into the pending queue, so the worker can resume it instead of leaving an approved item parked indefinitely.

Each attempt gets a new run directory. A resumed attempt carries earlier evidence forward while preserving the preceding run. The dashboard exposes logs, artifacts, history, editable workspace documents, and comparisons between runs. The goal is to make “what changed?” and “why are we here?” answerable without reconstructing the entire conversation from memory.

Failure needs somewhere useful to go

A failed test should not simply produce another request to “try harder.” Sometimes the next step belongs in implementation. Sometimes integration reveals a design problem. Sometimes the requirements were unclear long before the first command ran.

OmniForge records a retry destination for a failed stage and can escalate that destination further upstream after repeated failures. The worker has a bounded automatic retry budget rather than circling the same broken ticket forever. Held, cancelled, unknown, running, delivered, and unapproved paused tickets are excluded from normal processing.

There is an important practical distinction here: rollback means workflow routing. It records where another attempt should start. It does not revert Git commits, undo a deployment, restore a database, or reverse arbitrary shell-command side effects. Those operations need their own explicit mechanisms.

A deliberately small demo

The portable example uses Python and a tiny deterministic output. It walks through the stages, creates a JSON result, checks its content, and packages a delivery ZIP. It does not need an LLM account, PHP, or another application checkout. That makes it possible to inspect the process itself before adding a more complicated project.

python -m venv .venv
# Activate the environment, then:
python -m pip install -r requirements.txt
python -m omniforge.runner.forge run --project demo --ticket DEMO-001 --auto
python -m omniforge.viewer.app

The dashboard opens at localhost:5055. For a first mechanical demonstration, --auto explicitly bypasses the gates and records that override. To exercise human review, omit it, inspect the evidence at each pause, and approve the current gate through the dashboard or CLI. The README includes the full setup and approval commands.

The dashboard is a local development tool. It uses loopback-only access and form-token protection, with debugging disabled. Project manifests execute trusted shell commands with the current user’s permissions, so they should be read before being run. This is not a hosted, authenticated team service or an execution sandbox.

Source-derived run evidence preview with an eight-stage PASS report and links to stage artifacts and logs.
Run evidence preview / the report and links to per-stage logs and artifacts. The displayed PASS entries illustrate a demo report.

What experimental v0.1 actually establishes

The release work included fixes for board-write concurrency, stale approvals, invalid state transitions, path handling, resume behavior, and CLI failure reporting. The local JSON board now uses process locking and atomic replacement. The example and documentation make the boundary between implemented behavior and future ambition explicit.

🔧 Release evidence / current test coverage

  • 144 pytest tests passed, including Flask route coverage.
  • 13 core validation checks passed, covering the demo, gates, changed evidence, concurrency, and failure handling.
  • Flask application import, route discovery, and Python compilation were verified.
  • Windows and Linux CI checks passed for the configured Python 3.10 and 3.12 matrix.

Where this fits with the other experiments

In Agentic RDE, the emphasis is durable engineering memory: keeping decisions and context from evaporating between sessions. OmniForge explores a related question from the delivery side: how work moves through defined responsibilities, how evidence accumulates, and where a human needs to make a decision.

That connection is conceptual at this stage. This post is not announcing a completed integration between the projects. The common thread is an interest in turning AI assistance into something that can be inspected, resumed, questioned, and improved across more than one impressive conversation.

A foundation worth putting in public

There is still work ahead: model and tool integration, a functioning GitHub Projects adapter, stronger evidence validation, and better recovery when a process crashes. The release does not hide those gaps. It gives them a defined place in the next phase.

For now, OmniForge is a small software shop with an operating manual, a working process, and some deliberately unfilled chairs. The interesting experiment is whether the eventual AI team can work within that structure while leaving enough evidence for the human to decide what deserves to move forward.

OmniForge Labs experimental v0.1 is available under the MIT license. Read the source, run the demo, and inspect the evidence.

Project / Generative AI Projects

Filed under / AI / ML · Generative AI · Python · Software Development

Leave a Reply