Skip to content
Surfaces
Sections
GreenwaysVisual language · v2
Navigator

Greenways visual language · v2

Visual navigator

Move between the four sections without leaving the current visual system.
Current layerBrand · OS · Product · InfraEvery section can grow independently while sharing the same v2 visual contract.
Profile
Skip to product model
ForemanProduct model · low-fidelity contract

Issue #35 · specimen data only

Choose the project.
Understand the work.
See the evidence.

One buildout may span several providers and interfaces. Foreman keeps every person, agent, connection, and live session distinct while presenting one coherent project outcome.

01 · Core journey

Five steps, one evidence trail.

  1. 1
    Choose project/foreman/projects/The exact project and repository context are visible.
  2. 2
    Inspect buildout/foreman/buildouts/:buildoutId/Goal, work, sessions, attention, and evidence share one view.
  3. 3
    Open work or session/foreman/work-items/:workItemId/The bounded task and live context remain distinct.
  4. 4
    Approve or hand off/foreman/approvals/Consequential scope and human intervention are explicit.
  5. 5
    Inspect activity and evidence/foreman/activity/Claims link to artifacts or authoritative external observation.

02 · Domain

Entities do not blur together.

primaryProject

The stable home for one software effort, its people, connections, repository links, and buildouts.

Owner
Foreman application
Parents
None
Required fields and states

Normal: name · summary · human owner · active buildouts · attention required · repository link

States: first-use · active · paused · degraded · completed

primaryBuildout

One intended project outcome spanning multiple work items, sessions, connections, approvals, and artifacts.

Owner
Foreman application
Parents
project
Required fields and states

Normal: goal · state · human attention · work progress · sessions · artifacts · GitHub state

States: planned · active · paused · waiting-for-approval · degraded · completed · failed · cancelled

primaryWork item

A bounded unit of work with dependencies, an owner, expected output, and explicit completion evidence.

Owner
Foreman application
Parents
buildout
Required fields and states

Normal: title · state · owner · dependencies · expected output · next action

States: proposed · ready · active · blocked · waiting-for-approval · completed · failed · cancelled

primaryPerson

A human actor who owns projects, operates sessions, and makes consequential decisions.

Owner
Human actor
Parents
None
Required fields and states

Normal: name · project role · attention assigned · available actions

States: active · paused

primaryAgent

A named bounded profile with a mandate; it is not a provider account or a live session.

Owner
Person or project
Parents
person, project
Required fields and states

Normal: name · purpose · project scope · current sessions · attention required

States: active · paused · degraded

expandedProvider

The external product or tool behind a connection, shown only when attribution or diagnosis requires it.

Owner
External service or local tool
Parents
None
Required fields and states

Normal: provider name

States: active · degraded · disconnected

primaryConnection

A configured relationship to a provider or tool, including login and observed availability without implying authority.

Owner
Person or project
Parents
provider
Required fields and states

Normal: name · state · last observed · affected work · safe action

States: login-required · connecting · ready · degraded · disconnected · revoked

primarySession

One live or resumable working context on a specific surface; sessions never merge across providers.

Owner
Person or agent on one connection
Parents
agent, connection, buildout
Required fields and states

Normal: name · person or agent · connection · state · current work item · last activity

States: available · connecting · active · idle · disconnected · ended · failed

contextualRun

One attempt to progress a work item inside one session, with checkpoints and attributable output.

Owner
Foreman application
Parents
work-item, session
Required fields and states

Normal: attempt · state · session · started time · output summary

States: queued · running · completed · failed · cancelled · timed-out

primaryApproval

One exact human decision covering a consequential request, its scope, expiry, and visible consequences.

Owner
Person
Parents
project, buildout, work-item
Required fields and states

Normal: request · requesting actor · scope · consequence · expiry · decision

States: pending · approved · denied · expired · revoked

contextualHandoff

A durable bounded request from one attributable session to another, with a distinct return path.

Owner
Foreman application
Parents
buildout, work-item, session, agent
Required fields and states

Normal: purpose · origin · target · state · expected deliverable · attention required

States: draft · requested · waiting-for-approval · authorised · queued · accepted · running · returning · completed · denied · expired · cancelled · disconnected · partial · failed

contextualArtifact

A referenced output with exact ancestry, producer, and availability state.

Owner
Producing work or external authority
Parents
work-item, run, handoff
Required fields and states

Normal: name · type · producer · state · open or download action

States: expected · producing · available · stale · missing · invalid

contextualGitHub record

A rebuildable Foreman view of an exact GitHub issue, branch, commit, pull request, review, or check.

Owner
GitHub
Parents
project, buildout, work-item
Required fields and states

Normal: record type · number or revision · state · canonical link · last verified

States: requested · waiting-for-approval · authorised · submitted · uncertain · verified · failed · cancelled

primaryActivity entry

An attributable event linking the actor, affected object, causal predecessor, and evidence.

Owner
Observed actor or authority
Parents
project, buildout
Required fields and states

Normal: time · actor · plain-language event · affected object · evidence link

States: active · waiting-for-approval · completed · failed · cancelled

03 · Required states

The difficult states are part of the product.

First use

Nothing is configured yet.

Show an honest setup checklist and no invented activity.
Active

Work is progressing.

Show a current run, session, or verified transition.
Paused

Progress deliberately stopped.

Show actor, reason, and pause time.
Waiting for approval

Consequential work cannot continue.

Show exact request, scope, recipient, and expiry.
Degraded

The view is partly useful.

Name the unavailable portion and last successful observation.
Disconnected

A required surface is unreachable.

Keep desired and last observed connection states distinct.
Completed

The declared outcome has evidence.

Place artifacts or authoritative read-back beside the claim.
Failed

The declared outcome was not reached.

Show failure stage, retained work, and a safe next action.
Cancelled

An authorised actor stopped the operation.

Show actor, time, and downstream consequences.

04 · Truthfulness

A request is not a result.

  1. A requested or sent handoff is not accepted work.
  2. Accepted or running work is not completed work.
  3. A ready connection or provider login does not imply permission to read, write, publish, spend, review, or merge.
  4. A local branch, commit, patch, or command exit does not prove a GitHub mutation occurred.
  5. An external mutation becomes verified only after canonical read-back from the external authority.
  6. Desired, requested, and observed states remain visibly distinct.
  7. Person, agent profile, connection, client, and live session identities remain distinct.
  8. Unavailable, stale, uncertain, and partial outcomes cannot be collapsed into success.

05 · Relationships

One buildout, many attributable contexts.

projectone-to-manybuildout

A buildout belongs to one project outcome context.

buildoutone-to-manywork-item

Work items retain explicit dependencies and completion evidence.

buildoutmany-to-manysession

One buildout may span several sessions and providers; sessions remain distinct.

personone-to-manyagent

An agent is a bounded profile, not a copy of the person.

connectionone-to-manysession

A connection may host several sessions without granting identical authority.

work-itemone-to-manyrun

Retries and resumptions create attributable attempts rather than overwrite history.

handofftwo-endedsession

Origin and target sessions are separately identified and never collapsed.

approvaloptional-one-to-manyhandoff

Approval covers only exact requested scope and does not imply completion.

approvaloptional-one-to-manygithub-projection

External mutation permission is distinct from general code or agent access.

runone-to-manyartifact

Artifacts preserve producer and ancestry.

github-projectionone-to-manyactivity-entry

Verified external state requires authoritative observation evidence.

06 · Disclosure

Technical detail stays available, not dominant.

Normal UI

Help a person choose work, understand attention, and take the next safe action.

plain-language state · owner · next action · human attention · adjacent evidence
Expanded details

Support attribution and precise inspection without dominating the task view.

provider name · session and correlation identifiers · timestamps · canonical URLs · artifact ancestry · requested versus actual state
Diagnostics

Explain adapters, storage, synchronisation, retries, policy evaluation, and low-level failure.

adapter revision · transport · retry generation · raw normalised error · authority trace

07 · Delivery surfaces

Shared objects, purpose-built views.

Desktop and browser workspace

  • Overview/foreman/first-use · active · degraded
  • Projects/foreman/projects/first-use · active · paused
  • Project/foreman/projects/:projectId/active · paused · degraded · completed
  • Buildouts/foreman/buildouts/planned · active · paused · waiting-for-approval · degraded · completed · failed · cancelled
  • Buildout/foreman/buildouts/:buildoutId/planned · active · paused · waiting-for-approval · degraded · completed · failed · cancelled
  • Work item/foreman/work-items/:workItemId/proposed · ready · active · blocked · waiting-for-approval · completed · failed · cancelled
  • Session/foreman/sessions/:sessionId/available · connecting · active · idle · disconnected · ended · failed
  • People and agents/foreman/people-agents/active · paused · degraded
  • Connections/foreman/connections/login-required · connecting · ready · degraded · disconnected · revoked
  • Approvals/foreman/approvals/pending · approved · denied · expired · revoked
  • Activity/foreman/activity/active · degraded · failed
  • Diagnostics/foreman/settings/diagnostics/active · degraded · disconnected

Browser companion

  • Current context/companion/current/first-use · active · disconnected
  • Handoff/companion/handoffs/:handoffId/draft · requested · waiting-for-approval · authorised · queued · accepted · running · returning · completed · denied · expired · cancelled · disconnected · partial · failed
  • Approval/companion/approvals/:approvalId/pending · approved · denied · expired · revoked
  • Recent activity/companion/activity/active · degraded

CLI companion

  • Statusforeman statusfirst-use · active · degraded · disconnected
  • Projectforeman project show <project>active · paused · degraded
  • Buildoutforeman buildout show <buildout>planned · active · paused · waiting-for-approval · degraded · completed · failed · cancelled
  • Session identityforeman session identifyavailable · connecting · active · idle · disconnected · ended · failed
  • Handoffforeman handoff <request|status|cancel>draft · requested · waiting-for-approval · authorised · queued · accepted · running · returning · completed · denied · expired · cancelled · disconnected · partial · failed
  • Approvalforeman approval <show|respond>pending · approved · denied · expired · revoked
  • Activityforeman activity tailactive · degraded · failed