Forge Product Requirements

1. Product statement

Forge is a local-first engineering workspace where one developer coordinates their own work and work delegated to AI coding agents without losing awareness, judgement, or final approval.

The problem is no longer simply “can an AI write code?” The harder problem is using increasingly capable agents while still knowing what is happening, making the decisions that matter, learning from the work, and maintaining software quality.

Forge is the control plane around the work. It is not the coding model itself.

2. Product promise

The desired feeling is:

I am still engineering. AI is doing some work for me, and Forge is handling the machinery around that work.

Forge should answer these questions quickly:

• What work exists?
• What is ready to be worked on?
• What are agents doing right now?
• Where is my judgement required?
• What changed?
• Has the change been verified?
• What did reviewers object to?
• Why did we make this decision?
• Is this work safe to call Done?

3. Primary user

The first version is for one developer working on local Git repositories. Authentication, teams, hosted execution, and collaborative project-management features are not first-version requirements.

4. Core workflow

The core acceptance loop is:

create or choose a Task
        ↓
make it Ready
        ↓
start work
        ↓
agent or human implements in an isolated environment
        ↓
Needs You if a Decision requires human judgement
        ↓
continue work
        ↓
capture candidate revision
        ↓
run verification / optional AI review
        ↓
human Review
   ┌────┴─────┐
 approve   changes requested
   │            │
   ▼            └────────► Working again
 Done

Planning is optional and separate from the Task state machine. A Feature Plan may be revised and reviewed, then decomposed into Tasks. A Task may also have its own execution Plan.

5. Product principles

Work is primary

A Task is the unit of engineering work. Agent Runs, Turns, terminals, logs, worktrees, and reviews are records attached to the work, not the thing around which the product is organized.

Human judgement is first-class

Forge should surface moments where the developer needs to think, not merely show that an agent is alive. Decisions are durable product objects and the Needs You state is visible throughout the workspace.

Local first

Forge runs on the developer's machine, can operate without a hosted Forge account, uses local Git repositories, and keeps its core state locally.

Git remains code truth

Forge does not invent a parallel AI representation of source code. Candidate revisions, diffs, review validity, merging, and recovery are grounded in Git and the filesystem.

Agents stay agents

Forge configures an individual run and adapts its protocol where necessary. It does not rewrite repository-level or user-global agent configuration as a hidden side effect.

Explicit capability over pretending

A product feature is available only when the selected adapter strategy can actually guarantee it. Forge never silently downgrades to a weaker strategy while keeping the same UI promises.

Human review is mandatory by default

Agent completion does not equal Task completion. The normal path to Done requires human approval of the current candidate revision.

Fast return to context

Opening Forge after time away should make the important state legible quickly: what changed, what is blocked, what needs review, and what the agent claims it did.

6. Work hierarchy

Workspace
└── Project (one Git repository)
    ├── Feature
    │   ├── Task
    │   └── Task
    ├── Standalone Task
    ├── Plans
    ├── Decisions
    ├── Artifacts
    └── Project Knowledge

A Feature organizes related Tasks. It is intentionally lighter than a full project-management “epic” system.

7. Task lifecycle

Canonical Task states:

BACKLOG → READY → WORKING ⇄ NEEDS_YOU
                     │
                     ▼
                   REVIEW ⇄ WORKING
                     │
                     ▼
                    DONE

Optional archival is a later organizational concern, not a core engineering state.

Planning, verification, agent review, human review progress, process startup, and worktree setup are not additional Task statuses. They have their own records/lifecycles.

8. Planning

Forge supports two scopes using the same underlying Plan machinery:

• Feature Plan — proposes how a feature should be approached and may decompose into many Tasks plus simple dependency edges.
• Task Execution Plan — proposes how one Task should be implemented.

Plan content is immutable by revision. Feedback belongs to the revision that was reviewed. Rejection creates a later revision rather than rewriting the old one.

9. Agent work

Forge can supervise multiple coding-agent products through adapters. Each integration declares real capabilities. The first build uses a deterministic fake adapter; a real provider is introduced only after the contract is proven.

A Task can have many Agent Runs. A Run can have many Agent Turns. Neither is assumed to equal one OS process.

10. Human attention and Decisions

An agent that supports interactive escalation can raise a structured Decision through a Forge-controlled tool. A Decision includes the reason, context, options, and a recommendation when applicable.

Unresolved blocking Decisions move the Task into NEEDS_YOU. Resolution is durable and the agent may then resume.

Forge should eventually offer a global Decision Inbox because this is the primary way a developer supervises several delegated Tasks without watching several terminals.

11. Review and quality

A Review evaluates an exact candidate revision. If code changes afterward, the old Review becomes stale.

Verification works the same way: tests that passed against revision A do not prove revision B is valid.

Review should support:

• diff browsing;
• acceptance-criterion acknowledgement;
• deterministic verification results;
• inline and general comments;
• optional agent/AI review;
• mandatory human approval by default;
• request-changes → new work → new revision → review again.

The exact policy for whether a failed required verification blocks approval or only requires explicit acknowledgement remains an open product decision until we have used the loop.

12. Meaningful activity

Raw agent transcripts are always available for diagnosis, but the normal product should not require reading them.

Forge presents two evidence types separately:

• Facts — observed events such as files changed, commands run, verification exit/result, and process/protocol state.
• Claims — agent-authored statements such as intent, conclusions, and assumptions.

Forge does not invent a claim when none exists. If meaningful narration is unavailable, the UI honestly falls back to deterministic facts.

13. Project surfaces

The eventual product includes:

• Project home / attention summary
• Kanban
• List
• Tree
• Task workspace
• Plan workspace
• Review workspace
• Decision Inbox
• Activity view
• Raw Agent Run diagnostics
• Project Knowledge
• Settings / agent instances / strategies

The UI is built incrementally; a small Task workspace arrives before the full board.

14. Performance expectations

Forge is a local desktop tool and should feel local.

• Normal navigation should use current cached state immediately.
• Large histories are paged; the UI does not request an entire raw run history.
• Streaming deltas are coalesced and are not treated as permanent historical records.
• Reconnect replay is bounded; large gaps use a snapshot.
• React does not re-render once per historical token delta.
• Core concurrency is bounded and cancelable.
• No Redis, distributed queue, or external broker is required for the local first version.

15. Safety expectations

• Dirty or otherwise unrecoverable worktrees are never deleted automatically.
• Repository-defined setup/verification commands execute only after the project is trusted.
• Host tool gating is independent from how conversationally autonomous an agent is.
• Unknown safety classifications do not silently become “safe”.
• Process spawning goes through one controlled boundary using executable + argv rather than ad-hoc shell concatenation.
• Electron renderer remains sandboxed and cannot directly run arbitrary local commands.

16. MVP definition

The first meaningful MVP is not “all screens and all providers.” It is the complete high-quality work loop with one real provider:

1. Open a Project.
2. Create a Task with goal and acceptance criteria.
3. Make it Ready.
4. Start a supported agent.
5. Forge prepares an isolated worktree.
6. See bounded live activity.
7. The agent can request a Decision if supported.
8. Work produces a candidate revision.
9. Run verification.
10. Review the diff.
11. Request changes and have the agent revise.
12. Review the new revision.
13. Human approves.
14. Merge/complete intentionally.

If this loop feels natural, the foundation is working.

17. Explicitly not first-version goals

• team collaboration;
• hosted Forge backend;
• mobile app;
• agent swarms;
• arbitrary execution DAGs;
• proprietary coding model;
• marketplace/plugin ecosystem;
• automatic AI memory system;
• replacement for Jira/Linear;
• full IDE/editor;
• remote container fleet;
• complex model routing;
• learning analytics.