Documentation

How Forged works

Forged helps founders move from a product idea to shipped software through one connected workflow:

Idea → Clarify → Plan → Build → Review → Ship → Improve

You describe what you want to build. Forged clarifies important product decisions, turns the idea into a structured plan, converts approved features into implementation-ready work, and coordinates AI agents to write and test the code.

You decide what moves forward at every stage.

Quick start

A typical workflow in Forged looks like this:

1. Create a project.
2. Connect one or more GitHub repositories.
3. Describe a feature or product idea.
4. Answer any clarification questions.
5. Review the generated plan.
6. Accept, defer, edit, or dismiss suggested features.
7. Start implementation for an accepted feature.
8. Review the resulting code changes and pull request.
9. Approve the change and take it live.
10. Use what you learn to plan the next improvement.

Projects and repositories

A project is the main workspace for a software product. It brings together the product's repositories, plans, features, implementation work, and relevant context.

You can connect repositories from Project Settings using the Forged GitHub App. Access is limited to repositories you explicitly authorize and can be revoked through GitHub.

Forged uses repository context to understand what already exists before recommending or implementing changes. This helps it avoid duplicating existing functionality, conflicting with established architecture, or producing plans that are disconnected from the actual product.

Planning and clarification use repository access to read relevant code and documentation. When implementation begins, individual jobs receive short-lived access scoped to the work they need to perform.

Planning an idea

Start on the Planning page and describe what you want to build in plain language.

Your idea can be brief, but it should explain the problem, intended user, and desired outcome where possible. You do not need to write a technical specification.

Before generating a full plan, Forged may ask focused questions about decisions that could materially change the result. These may cover:

• Who the feature is for
• What should be included in the first version
• What should remain outside the scope
• How permissions or roles should work
• What information needs to be stored
• Which workflows or integrations matter
• What outcome would make the feature successful

Forged uses your answers together with the existing product and repository context. When you are unsure, you can say so. Forged may later make a reasonable assumption when one is required to complete the plan, but that assumption should be identified rather than presented as your confirmed decision.

Reviewing the plan

Forged converts the clarified idea into a structured set of suggested features.

Each feature may include:

• A clear headline
• A description of what it does and why it matters
• Relevant user stories
• Implementation-ready tasks
• Dependencies on other features
• A relative size estimate

The plan is a proposal. It does not automatically commit you to building everything it contains.

For each suggested feature, you can:

• Accept it for implementation
• Edit it before accepting
• Defer it for later
• Dismiss it if it should not be pursued

Dependencies help show which features must be completed before others can work properly.

Feature sizing

Forged may estimate a feature as:

• S, Small: A localized change with limited impact
• M, Medium: Work involving multiple components, APIs, or moderate data changes
• L, Large: Cross-cutting work, a new subsystem, a major integration, or substantial uncertainty

Size represents relative complexity. It is not a delivery-time, price, or completion guarantee.

Large features may be easier to implement and review when divided into smaller phases.

Starting implementation

Once a feature is accepted, you can start implementation.

Forged converts the feature into concrete tasks and acceptance criteria. Acceptance criteria describe the observable conditions that should be true when a task is complete.

AI agents then work through the approved tasks inside isolated execution environments. Depending on the work, they may:

• Read relevant code and documentation
• Modify application code
• Add or update tests
• Run validation commands
• Address implementation errors
• Prepare commits
• Open a pull request

The agents work from the approved feature and its tasks. They are not intended to independently expand the product scope without your approval.

Acceptance criteria

Acceptance criteria give the implementation agents an objective definition of done.

A useful criterion describes a result that can be observed or tested, such as:

• A user with the correct role can access the new workflow
• An unauthorized user receives an appropriate error
• Submitted information is saved and appears after the page is refreshed
• Existing behavior continues to pass its tests

Acceptance criteria should describe the required outcome rather than repeat the implementation steps.

They are available during implementation so you can inspect what the agents are building toward. You do not need to approve every criterion individually.

Reviewing and shipping changes

When implementation is complete, Forged prepares the resulting code changes for review.

You can inspect the pull request, including:

• The files that changed
• The implementation approach
• Test results
• Any unresolved findings
• Whether the acceptance criteria were addressed

By default, completed agent work waits for review. Forged does not merge or deploy a change merely because an implementation job has finished.

Where an automated workflow has been explicitly configured, Forged can coordinate later steps after approval. Otherwise, the change remains in a pull request until you or your team decide to merge and deploy it.

Improving the product

A product continues to change after its first release.

Forged keeps the product's plans, decisions, features, tasks, repository context, and implementation history connected. This gives later work access to the context that shaped earlier decisions.

You can use customer feedback, product usage, bugs, support requests, new ideas, and technical constraints to create the next plan and improvement cycle.

The goal is for each new change to fit the product rather than begin as an isolated prompt.

Core concepts

• Project: A workspace for one software product and its connected context.
• Repository: A GitHub repository authorized for use within a Forged project.
• Idea: A plain-language description of something you want to build, change, or improve.
• Clarification: A focused conversation that resolves the most important ambiguities before planning begins.
• Plan: The structured output created from an idea, clarification decisions, product context, and repository analysis.
• Feature: One coherent unit of product functionality proposed within a plan.
• User story: A description of who needs a capability, what they need to do, and why it matters.
• Task: A concrete unit of implementation work required to build a feature.
• Acceptance criteria: Testable conditions that define when a task is complete.
• Pull request: The proposed code changes produced during implementation and submitted for review.

What you control

You decide:

• What enters planning
• How clarification questions are answered
• Which assumptions are acceptable
• Which features are accepted
• Which work is deferred or dismissed
• When implementation starts
• Whether a pull request is approved
• Whether merging and deployment remain manual or use an enabled automated workflow

Current limitations

Forged uses AI systems to help plan and implement software. Generated plans, code, tests, and recommendations may be incomplete, inaccurate, or unsuitable for a particular environment.

Repository context improves the quality of the result, but it does not replace founder or engineering review. You remain responsible for reviewing changes, testing the product, managing access, maintaining backups, monitoring live software, and deciding what should be deployed.

Some workflows may depend on the repositories, integrations, and deployment systems connected to a project.

Getting help

For product questions or support, contact support@tryforged.ai.

For security questions or vulnerability reports, contact security@tryforged.ai.