Forge — Design Agent Brief

Use this file when handing the product to a UI/UX design agent. It summarizes the design task; the linked current docs provide exact domain meaning.

Product

Forge is a local-first engineering workspace for one developer coordinating their own work and work delegated to AI coding agents. It is not a chat app or terminal manager. The unit of organization is engineering work (Task), and the flagship value is keeping the developer aware and in control while agents perform implementation.

Read first:

• ../product/PRD.md
• ../architecture/STATE_MACHINES.md
• UX_PRINCIPLES.md
• INFORMATION_ARCHITECTURE.md
• USER_FLOWS.md

Desired feeling

Dense enough for a serious developer tool, calm rather than dashboard-noisy, extremely clear about where human attention is required. The UI should feel fast/local and make long-running agent work legible without forcing raw transcript reading.

Avoid a “chat app with a sidebar” as the primary composition. Conversation/Run detail exists, but Task/Review/Decision are first-class workspaces.

Primary hierarchy

Workspace
└── Project
    ├── Feature
    │   └── Task
    └── Task

Task states are exactly:

Backlog → Ready → Working ⇄ Needs You
                     ↓
                   Review ⇄ Working
                     ↓
                    Done

Planning, agent startup, verification, AI review, and human-review progress are subordinate workflows/badges, not extra Kanban columns.

Required surfaces to design eventually

1. Project Overview

Answer: “Where do I need to act, and what is moving?”

Priority order:

1. open Decisions / Needs You;
2. Reviews awaiting human judgement;
3. failed/degraded Operations/Runs;
4. active Tasks;
5. recent completion.

2. Task Workspace — highest priority

Must support the full engineering story:

• Task goal/status/actions;
• acceptance criteria;
• current work/Agent Run summary;
• meaningful activity;
• Decisions;
• Plan when present;
• candidate diff;
• verification;
• Review/comments;
• revision/round history.

Design this before spending time on a beautiful Kanban board.

3. Review Workspace

Large enough for serious diff reading. Show:

• base/candidate revision identity;
• file tree;
• diff with inline comments;
• current/stale Verification;
• acceptance criteria;
• agent assumptions/claims;
• prior review round;
• strong Request changes / Approve current revision actions.

A stale Review/Verification must never look equivalent to a current green one.

4. Decision Inbox

This is eventually a flagship surface. A Decision card should show:

• Task/project context;
• reason;
• concise question/context;
• options;
• agent recommendation when present;
• supporting evidence/deep-link;
• resolution action.

It must be possible to resolve simple Decisions without opening raw logs.

5. Plan Workspace

Markdown-oriented but revision aware:

• current immutable revision;
• annotations/review feedback;
• revision history;
• Draft/In Review/Approved state;
• Feature-plan decomposition preview/edit/confirm.

6. Kanban / List / Tree

Three views of the same Tasks. Do not duplicate state systems.

Kanban columns: Backlog, Ready, Working, Needs You, Review, Done.

Cards may show badges for agent active, blocked dependency, verification failure, plan review, Decision count, etc.

7. Agent Run diagnostics

Secondary power-user view with provider Strategy, Run/Turn history, normalized events, raw log access, stop reason, capability/policy snapshot. It should not displace Task as the root navigation model.

States the design must express distinctly

Do not reduce all of these to a spinner or green/red dot:

• command accepted but external Operation pending;
• worktree preparing;
• provider starting;
• provider active;
• Agent Turn finished but candidate revision still settling;
• Task Needs You;
• Review current vs stale;
• Verification current vs stale;
• Connection connected but Sync stale/degraded;
• Fact vs agent Claim;
• provider capability unavailable.

Interaction principles

• Progressive disclosure: meaningful summary → normalized detail → raw evidence.
• Keyboard-friendly, never keyboard-only.
• Human judgement actions are explicit and revision-aware.
• Destructive actions state exactly what will be lost/removed.
• High-density lists use virtualization/paging rather than tiny unreadable typography.
• No status relies on color alone.
• Avoid notification fatigue; “agent working normally” is not urgent.

Visual deliverables requested from a design pass

1. navigation/information architecture validation;
2. low-fidelity wireframes for Project Overview, Task, Review, Decision Inbox, Plan;
3. component/state inventory;
4. high-fidelity design for Task + Review first;
5. responsive behavior for normal laptop/desktop widths;
6. keyboard/focus interaction notes;
7. loading/error/stale/degraded states;
8. small semantic token/component direction, not a huge bespoke design system.

Design should be validated against the core acceptance scenario in ../product/ACCEPTANCE_SCENARIOS.md.