Forge Vocabulary

Use these terms consistently in code, UI, documentation, and agent prompts.

Work hierarchy

Workspace — the local Forge installation/workspace that contains projects.

Project — one local Git repository. Multi-repository projects are not part of the first build.

Feature — a larger body of related engineering work containing Tasks. A Task may also stand alone.

Task — the unit of engineering work. Everything operational ultimately attaches to a Task. Avoid using job, ticket, or session as synonyms.

Acceptance Criterion — an observable condition used during review to decide whether a Task meets its goal.

Planning and review

Plan — a planning object scoped to a Feature or a single Task execution approach.

Plan Revision — an immutable version of a Plan's content.

Review — evaluation of one exact candidate code revision. Review can be human or agent-assisted, but human approval is mandatory by default.

Review Comment — feedback attached to a review, usually general or anchored to a diff location.

Verification — a deterministic check such as tests, lint, type checking, or a configured command. A verification result is valid only for the code revision it ran against.

Agent execution

Agent Driver — the integration family, for example Claude Code or Codex.

Agent Instance — one configured account/installation of a driver, for example “Personal Claude”. Two instances must not accidentally share mutable account/session state.

Adapter Strategy — one concrete protocol used to drive an agent, for example Codex app-server versus a weaker exec-json strategy. Capabilities belong to the strategy.

Capability — a semantic guarantee a strategy can actually provide. Capabilities gate product behavior; they are not decorative UI hints.

Agent Run — one supervised execution lifetime attached to a Task. A Run is not an OS process and may span multiple turns.

Agent Turn — one input → agent-work cycle inside a Run. A Run may contain many Turns.

Stopped Reason — why a Run stopped from Forge's point of view, distinct from raw process exit status.

Execution

Execution Environment — where work runs. The first implementation is a local Git worktree; future implementations may include Docker, SSH, or remote environments.

Worktree — the local Git worktree used to isolate a Task's changes.

Revision — an exact Git identity used to bind reviews and verification to the code they actually evaluated.

Operation — a durable record that Forge intends to perform an external side effect such as creating a worktree, starting an agent, running verification, or merging. Operations make retries and crash recovery explicit.

Human judgement

Decision — a recorded moment where human judgement is required. Avoid calling it merely a question.

Needs You — the Task state used while progress is blocked on a Decision.

Execution Mode — who authors implementation: human or agent.

Involvement Mode — how readily the agent is asked to stop and consult the human.

Escalation Policy — the policy controlling which situations become Decisions.

Escalation Tool — the Forge-injected tool through which a capable agent raises a Decision.

Gating Tier — host enforcement for tool capability classes. It is independent of Involvement Mode.

Activity and evidence

Raw Log — append-only retained protocol data written before parsing.

Agent Event — normalized structured event derived from raw provider data.

Fact — something Forge observed, such as a file write or exit/result event.

Claim — something the agent said, such as an intent, conclusion, or assumption.

Activity Item — user-facing progress derived from facts and agent-authored claims.

Assumptions Ledger — agent-authored choices the agent made without escalating, surfaced during review.

Realtime state

Connection Health — whether the client can communicate with the core.

Sync Health — whether the client's domain view is known to be current. A connected client can still be stale.