Forge AI

Inspiration

I have used tools such as GitHub Copilot, Codex, and Claude while working on software projects. They are very useful for generating code quickly, but I kept running into the same problem: after a few days, it becomes difficult to remember why a particular change was made, which requirement it belonged to, what context was given to the model, and whether the generated code was properly reviewed.

In a normal development team, a code change should be connected to a requirement, an implementation plan, review comments, test evidence, and finally a pull request. With AI coding tools, these steps often happen across separate chats, terminals, editors, and browser tabs.

That is what inspired Forge AI. I wanted to build a workflow where AI can help with engineering work, but every important decision remains visible, traceable, and under human control.

What it does

Forge AI takes a software requirement through a governed engineering workflow:

1. It reads the requirement and asks focused clarification questions when information is missing.
2. It inspects the repository and prepares an implementation plan based on actual project evidence.
3. The user reviews and explicitly approves the plan.
4. GPT-5.6 generates the implementation in an isolated Git worktree instead of modifying the active checkout.
5. Forge AI shows the complete file-by-file diff for human review.
6. After approval, it creates a manual verification plan.
7. The user records the verification results. Forge AI clearly labels these results as user-reported and never claims that it executed tests it did not run.
8. When verification passes, Forge AI prepares a delivery proposal containing the exact repository, base branch, changed files, commit message, delivery branch, and pull request content.
9. Only after another explicit approval does Forge AI create the commit, push a new non-force branch, and open a GitHub pull request.
10. Forge AI never automatically merges the pull request.

The workflow also supports a correction loop. When manual verification fails, Forge AI can analyse the failure, propose a correction, generate a new implementation revision, and link the replacement verification plan back to the original failure.

Throughout the process, Forge AI keeps a durable history of requirements, clarification answers, plans, revisions, model calls, token usage, estimated cost, verification results, approvals, and delivery attempts.

How we built it

Forge AI is built with a .NET 8 ASP.NET Core backend, a React and TypeScript frontend, SQLite for durable workflow state, Git worktrees for implementation isolation, and GitHub CLI integration for pull-request delivery.

GPT-5.6 is used at different stages with different reasoning levels:

• requirement clarification
• repository-grounded planning
• implementation generation
• verification-plan generation

The application uses structured request and response contracts rather than accepting free-form model output directly. Every model response is parsed, validated, associated with the correct task and repository revision, and stored with its provider metadata, token usage, and estimated cost.

Codex was also an important part of building Forge AI itself. I used it to implement and review individual slices of the product, including workflow persistence, implementation revisions, verification planning, the correction loop, GitHub delivery, safety checks, tests, and UI improvements.

The Git workflow was designed to be conservative:

• generated changes are created in an isolated worktree
• the user's active checkout must remain unchanged
• delivery always uses a new branch
• force-push is not allowed
• direct pushes to main are not allowed
• pull requests are created but never merged automatically
• uncertain external delivery states stop in a recovery state instead of blindly retrying

Challenges we ran into

The biggest challenge was not generating code. The difficult part was deciding when the system should trust a model response and when it should stop safely.

Model-generated plans can contain valid ideas but unexpected wording or structure. We had to build validators that reject unsafe claims, unknown paths, invented commands, invalid revision references, and unsupported verification evidence without blocking normal engineering language.

Another challenge was maintaining consistency across a long-running workflow. A plan, implementation revision, verification attempt, correction, and delivery proposal must all refer to the exact same requirement, repository state, and approved artifacts. A stale approval must never be reused after something changes.

GitHub delivery also required careful handling. A commit or push may succeed even when the application does not receive the expected final response. Forge AI therefore records each delivery phase and enters a recovery state when external mutation may have occurred. It does not create duplicate commits, branches, or pull requests just because a response was uncertain.

We also had to be very precise about trust labels. Forge AI distinguishes between:

• model-generated content
• actions actually executed by Forge
• manual results reported by the user
• proposed actions that have not yet happened

This was important because an engineering tool should never present a proposed test as a completed test.

Accomplishments that we're proud of

I am proud that Forge AI demonstrates a complete requirement-to-pull-request workflow rather than only generating a code snippet.

The project can:

• ask requirement clarifications
• inspect a real repository
• produce an evidence-grounded implementation plan
• generate code in isolation
• present a full diff for approval
• maintain multiple implementation revisions
• support failure analysis and correction
• create regression-linked verification plans
• record manual verification without overstating trust
• track model usage and estimated cost
• prepare a deterministic delivery proposal
• create a real GitHub commit, branch, and open pull request
• preserve the safety boundary that the pull request is not merged automatically

The most important accomplishment is traceability. A reviewer can understand not only what changed, but also why it changed, which requirement led to it, which model was involved, what the human approved, and what still requires human judgment.

What we learned

Building Forge AI changed how I think about AI-assisted software development.

I learned that model quality is only one part of the solution. A reliable engineering agent also needs workflow state, versioning, validation, idempotency, recovery, evidence, and clear trust boundaries.

I also learned that human approval should not be treated as one generic confirmation button. Requirement approval, plan approval, implementation approval, verification reporting, and delivery approval are different decisions and should remain separate.

Another lesson was that safe failure is often better than automatic recovery. When Forge AI cannot prove what happened in Git or GitHub, it stops and asks for reconciliation instead of repeating an external action.

Finally, I learned that AI coding becomes much more useful when model outputs are connected to normal engineering artifacts such as requirements, diffs, verification evidence, commits, branches, and pull requests.

What's next for Forge AI

The next step is to make Forge AI easier to use across larger repositories and development teams.

Planned improvements include:

• automated validation in disposable full-repository environments
• CI status and pull-request review integration
• configurable repository and GitHub Enterprise support
• richer correction cycles beyond one revision
• role-based approvals for teams
• better navigation across completed workflow stages
• reusable organization policies for commands, paths, models, and delivery rules
• integrations with issue trackers so requirements can start from an existing work item
• improved recovery tools for interrupted Git and GitHub operations
• dashboards for model usage, cost, review time, and delivery outcomes

The long-term goal is not to replace developers or reviewers. It is to give teams a safer and more accountable way to use AI throughout the software-development lifecycle.

Built With

• .net
• agents
• ai
• api
• asp.net
• automation
• code
• codex
• core
• developer
• engineering
• generation
• gpt-5.6
• human-in-the-loop
• openai
• requirements
• rest
• review
• software
• sqlite
• tools
• typescript