Domain Model

The purpose of this document is to make the important objects and their ownership obvious before database tables or UI components push us into accidental design.

Aggregate map

Workspace
└── Project
    ├── Feature
    │   └── Task
    ├── Task
    │   ├── AcceptanceCriteria
    │   ├── Plans (task-scoped)
    │   ├── AgentRuns
    │   │   └── AgentTurns
    │   ├── Worktree / ExecutionEnvironment binding
    │   ├── Decisions
    │   ├── Verifications
    │   └── Reviews
    ├── Plans (feature-scoped)
    └── ProjectKnowledge / Artifacts (later)

This is a conceptual map, not a demand that each object is a separate aggregate root in the strict DDD sense. We will keep transactions small and define ownership where real concurrency requires it.

Project

Represents one Git repository known to Forge.

Important identity is immutable and independent of repository display name. Store the canonical local repository path and default/base branch information, but always re-check relevant Git facts when an operation requires them because external tools can change the repository outside Forge.

Feature

A light grouping of Tasks with a goal and optional Plan. Features help Tree/List/Kanban views and preserve feature-level engineering context. They are not required for standalone Tasks.

Task

The central unit of work.

Typical fields/concepts:

• immutable ID;
• Project ID;
• optional Feature ID;
• title;
• goal/description;
• Task status;
• execution mode;
• involvement mode;
• preferred Agent Instance / Strategy when agent-authored;
• timestamps;
• acceptance criteria.

Task does not contain mutable blobs for every subordinate workflow. Reviews, Runs, Plans, Decisions, and Verification are separate records.

Task invariants

Examples of rules the domain should own:

• a Task cannot start from DONE;
• a Task cannot enter DONE simply because an agent stopped;
• NEEDS_YOU represents unresolved blocking human judgement;
• requesting changes from a current review returns the Task to WORKING;
• approval applies to the current candidate revision only;
• dependency readiness is computed rather than encoded as arbitrary status mutation.

Acceptance Criterion

A small explicit statement that can be acknowledged during review. Keep criteria separate rows/objects so review can record how they were considered.

Plan and Plan Revision

A Plan is an identity and lifecycle; Plan Revision contains immutable Markdown/content.

A Feature Plan can be decomposed into proposed Tasks. A Task Execution Plan guides one Task. Both use the same revision/review machinery.

Never overwrite the reviewed content and pretend the old review still describes it.

Agent Driver, Instance, and Strategy

These solve different identity problems:

Driver:   Claude Code
Instance: Personal Claude Code account/configuration
Strategy: streaming/control-protocol integration

Capabilities belong to the Strategy, because the same product may expose richer and weaker execution surfaces.

Agent Run

Represents a supervised provider execution lifetime attached to a Task. It may have external provider/session identity assigned after startup.

A Run records its policy snapshot and chosen Agent Instance/Strategy so history remains understandable even if settings change later.

Run completion classification comes from provider semantics, not merely an OS exit code.

Agent Turn

Represents one instruction/input → provider work cycle inside a Run. This lets Forge distinguish a long-lived conversation/session from individual work cycles and follow-up review passes.

Turn completion and post-turn operations such as diff/revision capture are separate milestones.

Execution Environment

Represents the place work executes. The first implementation is a local Git worktree. It owns environment preparation concerns, while the Agent Adapter owns provider protocol concerns.

Worktree

A persistent record for the local worktree lifecycle. The filesystem path uses immutable IDs rather than titles. Cleanup is permitted only when recoverability conditions are satisfied.

Operation

A durable command to the outside world. It records intent, idempotency identity, lifecycle, attempts, and failure information.

Operations are internal product machinery, but they are valuable diagnostic records.

Decision

A durable request for human judgement. It records why the judgement is needed, options, recommendation when applicable, resolution, and whether a resolution was truly human or came from an allowed default.

Blocking unresolved Decisions correspond to NEEDS_YOU at the Task level.

Review

Evaluates one exact candidate Git revision. It contains status, reviewer kind, comments, and acknowledgement of acceptance criteria/verification context.

A Review can become STALE when the current candidate revision changes.

Verification Definition and Run

Definition says what command/check to run. Run records what happened against a specific revision. A green result cannot be carried forward blindly to a different revision.

Activity Item and Agent Event

Agent Event is normalized protocol/observed information. Activity Item is the user-facing projection. Both preserve whether information is a fact or claim.

Project Knowledge and Artifacts

These are valuable later but not part of the first vertical slice. Do not turn Forge into an AI memory system before the core work loop is strong.