UX Principles

Forge is not primarily a chat interface. It is an engineering-work workspace. The UI should keep the developer oriented around work, evidence, decisions, and review.

1. Attention first

The most important visual question is not “which processes exist?” It is “where does the developer need to act?”

Surface clearly:

• open Decisions;
• Reviews waiting for the human;
• failed/errored Operations requiring intervention;
• blocked Tasks;
• stale verification/review state.

Do not use urgent styling for routine agent activity.

2. Work before sessions

Navigation starts from Project/Feature/Task. Agent Runs are subordinate details. A developer should not need to remember which Claude session corresponds to which piece of engineering work.

3. Progressive disclosure

Default views show meaningful summaries. Deeper details are available without being forced into the main workflow.

Example:

Task activity
  ↓ expand
normalized tool step
  ↓ inspect raw
exact provider protocol/log

Raw logs are diagnostic, not the normal reading experience.

4. Never fake certainty

The UI should visibly distinguish:

• Fact versus agent Claim;
• current versus Stale Review/Verification;
• connection health versus sync freshness;
• “command accepted” versus external Operation finished;
• agent Turn completed versus Task ready for Review.

5. Revision awareness

Whenever the user approves or evaluates something, the UI should make the revision scope understandable. A stale approval should never look green/current after code changes.

6. Fast local interaction

Use optimistic interaction only where the domain can safely reconcile it. Otherwise show immediate local feedback that the command was accepted, then update when durable/external outcomes arrive.

Large histories must not block navigation.

7. Review is a workspace, not a modal

Review can involve reading diffs, acceptance criteria, verification, agent assumptions, comments, and repeated revisions. Give it enough space. Avoid forcing important review into a small popover.

8. Decisions should be answerable quickly

Decision cards need:

• reason/type;
• concise context;
• options;
• recommendation if present;
• affected Task;
• enough supporting evidence to judge;
• a path to deeper context.

The user should not have to read an entire transcript to understand why the agent stopped.

9. Keyboard-first without keyboard-only

Forge is a developer tool. Important navigation and review actions should gain shortcuts, but every important action must remain discoverable and usable with pointer interaction.

10. Design for returning later

Task and Feature pages should preserve the engineering story: plan/revisions, Decisions, implementation attempts, review feedback, verification, and final result. The project should feel understandable after days or weeks away.