Operator Job-Flow Audit

Status: product decision review in progress
Started: 2026-07-28
Parent concern: PROD-01

Outcome

aegi should not force every freelancer or agency through one project, approval, time, billing, or portal funnel.

The coherent model is:

• the client account is the durable business anchor
• projects are optional delivery structure
• delivery, commercial, and collaboration records remain independently useful
• context follows the operator when it is known and safe
• genuine workflow state produces next actions
• optional product features remain available without masquerading as required work

The target is therefore not one mandatory flow. It is a small set of consistent operating laws that make every valid flow feel connected.

The owner direction is now explicit: aegi should be quietly prepared, not bossy. The app brings the things that matter into reach and removes repeated setup, but it does not claim to know which valid piece of work the operator must choose next.

Layered Product Method

The product promise is:

aegi reduces operational drag. It keeps the business around the work organized so the user can focus on doing the work.

Every change in this program should be evaluated through the same operator question:

I sat down to work on Acme. How quickly can I understand the situation, begin working, capture what happened, and follow through without reconstructing context?

To turn that promise into concrete decisions without jumping straight from a vibe to isolated UI changes, PROD-01 works through six layers:

1. Promise. Define the human outcome: less operational drag, less context reconstruction, and more time doing paid or meaningful work.
2. Jobs. Audit the real loops an operator performs: orient, begin, capture, coordinate, follow through, and close the commercial loop.
3. Product laws. Decide what the app may infer, what requires confirmation, what deserves attention, and what must remain optional.
4. System contracts. Encode those laws once in shared context, workflow, permission, state, and handoff primitives instead of feature-by-feature guesses.
5. Surfaces. Keep, remove, connect, separate, and visually reprioritize only after the underlying contract is clear.
6. Proof. Verify the smallest path with automated scenarios, then dogfood whether it actually feels faster and calmer.

The layers run in both directions. A surface problem can reveal a missing system contract, while a product law is only credible when it improves a real operator job. No layer is considered complete merely because its document or code exists.

The working scorecard for each job is:

• Understand: Is the current state and genuine next actor apparent?
• Begin: Can the user start or resume without rebuilding known context?
• Capture: Does stopping, saving, or recording happen at the natural moment?
• Follow through: Does success lead to the exact durable record or next responsible action?
• Escape hatch: Can a valid simpler or more advanced workflow continue without being forced through the preferred path?

Keep, Remove, Connect, And Separate

Keep

• client accounts as the durable business anchor
• projects as optional delivery structure
• Today for the workday and Overview for agency-level intervention
• client focus, record pins, working tabs, resumable create drafts, and actionable success handoffs
• typed workflow state, explicit permissions, and exact record destinations
• separate delivery, commercial, collaboration, and portal projections

Remove or demote

• optional feature absence presented as required attention
• selectors for context the current route already establishes
• passive reporting in daily execution surfaces
• duplicate actions that differ only because the user entered through another route
• generic collection destinations when the causal record is known
• explanatory or assistant-style copy that restates visible state

Connect better

• visible client/project/task context → global create actions
• project/task/note/reminder context → timer and follow-through
• task/blocker/client-response state → the exact owning resolution surface
• approved time → optional period-based billing readiness
• successful creation → the durable created record
• portal response → the exact org-side item and next actor

Keep deliberately separate

• client focus from temporary visible route context
• project structure from mandatory time or billing workflows
• time approval from mandatory invoicing
• internal review from client visibility
• attention from optional feature adoption
• Files from feature-owned attachments
• future AI suggestions from core workflow truth

Current Strengths

The code already contains more of the intended operating layer than the older workflow backlog implies:

• Today is the role-neutral home and routes typed operational items to their exact resolution surfaces.
• The working-scope model now carries explicit, visible client/project, and focused-client context into global create dialogs without making projects mandatory or changing persistent focus.
• Client, project, task, time-entry, quote, contract, invoice, subscription, file, and calendar creation already use resumable drafts or actionable success handoffs in their primary create surfaces.
• Nested creation can resume its parent flow. For example, a project created from the timer is selected when the timer resumes.
• Reminders inherit linked client/project records and reopen through compact shell previews.
• Pinned projects now expose blocker and task follow-through instead of passive reporting.
• Overview interventions and Today operational work are backed by durable state, actors, actions, permissions, and exact destinations.

PROD-01 should consolidate these working patterns instead of replacing them.

Repeated Friction Patterns

1. Visible record context is not a first-class shell contract

Resolution: addressed by PROD-01A; awaiting owner dogfooding.

Before PROD-01A, the global create layer understood explicit caller options and client focus, but not the exact client, project, task, or other record visible on the route.

Feature-owned buttons often passed the correct context. The quick-action dock and other global entrypoints could not consistently do so.

Former result:

• creating from the correct page can still reopen a client/project selector
• a global New task action on a project route does not inherently know the project
• each feature must remember to reconstruct context independently

2. Genuine attention and optional creation are mixed

Resolution: addressed on client overview by PROD-01B; broader attention surfaces remain governed by the same product law.

Backend-owned Overview and Today interventions represent real states that need an actor. Before PROD-01B, the client overview also derived next actions from absent optional records:

• no project becomes Create project
• no subscription becomes Create subscription
• no shared document becomes Open files

Those are available capabilities, not evidence that the client needs attention. The pattern makes project-led, subscription-led, and collaboration-led behavior feel prescribed even though the operating model explicitly supports all of them as optional.

3. Completion handoffs are broadly good but not universal

Resolution: addressed by PROD-01C; awaiting owner dogfooding.

Most major create dialogs preserve the current surface and offer an Open action after success. Important exceptions still end with confirmation only or route to a broad workspace:

• the topbar timer quick-stop creates the entry but offers no Open entry handoff
• reminder creation confirms success without offering its durable detail
• request create/review/close transitions often stop at a toast
• some portal response and upload transitions confirm success without exposing the submitted record or next actor

4. Today contains the right work but its orientation can be calmer

Resolution: addressed by PROD-01D; awaiting owner dogfooding.

Before PROD-01D, Today separated:

• typed operational work
• project tasks
• timer, agenda, reminders, and notes

That separation protects different workflow semantics, but the operator still has to scan several large sections to establish the shape of the day.

The desired improvement is not a prescriptive Start here recommendation. It is a calmer orientation model:

• Needs you: records where the viewer is the durable next actor
• Today: due tasks, reminders, and agenda commitments
• Continue: active timer plus pinned or recent work

These lanes can emphasize real urgency without ranking unlike work through a speculative universal score. Full queues remain available.

5. Billing readiness exists in several places rather than one weekly loop

Time, client overview, org overview, and invoice creation each understand part of billing readiness. The operator can still need to assemble:

• which period is being billed
• which approved time remains uncovered
• which project/client rate applies
• whether an invoice or recurring arrangement already covers the work
• what should happen after approval

This must remain assisted rather than mandatory, but it needs one truthful period-based entrypoint.

6. Portal spotlight behavior now preserves the causal record

Portal attention and recent-work cards are whole-card links. Projects, invoices, support replies, file requests, project updates, contracts, and quotes now carry their known record identity into the destination. Shared files and featured resources open the artifact directly when a URL exists; files without a direct URL are focused inside Files.

Aggregate billing cards still open Billing because their values intentionally represent several records. The exact invoice attention items beside them continue to open invoice detail.

Job Audit

Operator job	Trigger	Context already known	Smallest successful path	Success handoff	Remaining friction
Start the day	Open the app	viewer, organization, client focus, date	Today → open exact task or operational item	owning record or queue	tasks and operational work are separately ranked; no bounded Start here set
Resume client work	Select client focus, open client, search, or pin	client	open relevant record or global workspace already scoped to client	current client context persists	visible route context and focus are separate concepts and are not expressed through one precedence rule
Resume project work	Today task, project pin, search, or project route	client, project, sometimes task	open blocker/task or start exact-context timer	project/task/time record	global create actions can lose the visible project context
Capture time	dock, Today, project/task, or active timer	explicit route context, client focus, active timer	start → stop and save	durable time entry	full timer offers Open entry; topbar quick-stop does not
Capture a note	global action, client/project, timer, quick access	client focus, caller context, active timer context	type; autosave	canonical note remains available across surfaces	route context depends on the caller rather than one shared contract
Schedule follow-through	reminder action from shell or record	linked record, client focus, current actor	create reminder	reminder appears in shell/Today	standalone success does not offer the durable reminder directly
Plan and perform delivery	client/project/Today	client and optional project	create project/task → perform → complete/update	next task, blocker, update, or completed project	optional project creation is sometimes presented as required next action
Review team time	Today or Time queue	entry, owner, review state, client/project	open exact entry → approve/return	next entry or billing readiness	approval-to-billing handoff is distributed across surfaces
Bill a period	ready-to-bill signal, client, or Invoices	client, approved entries, rate snapshots, period	inspect one recommendation → add → draft invoice	invoice detail	readiness is not yet one obvious weekly queue and must not require time tracking
Set up a client relationship	create client or open client	client	add only the people, portal, delivery, billing, or files structure actually needed	usable client anchor	client next actions currently promote absent optional features
Exchange client material	project/client Files or request	client, optional project, request, next actor	request/share → client response → review → close	exact submitted item or next actor	exact request state remains visible after response; the next actor is preserved without a redundant redirect
Communicate progress	project update or client feedback	project, visibility, response actor	draft/publish → client response → handle	updated project/client state	follow-through after publish/response handling is not consistently explicit
Client completes portal work	portal overview/attention	tenant, client, causal record	pay, review, upload, acknowledge, or reply	resolved state or next actor	exact record destinations are now carried whenever record identity exists; aggregate cards remain collection-level

Proposed Product Laws

1. Context precedence is deterministic

For any create or follow-through action:

1. explicit context supplied by the invoking record
2. exact visible record context
3. active work context when relevant to the new record
4. selected client focus
5. no default

Last-used client/project context must not silently assign durable records. It may appear as a visible suggestion only.

Each feature opts into only the context it can truthfully own:

• task: project
• timer: client, optional project/task/note
• note: personal, client, or project
• reminder: linked records
• event, file, and link: client and optional project where supported
• invoice, quote, subscription, and portal: client; project remains optional only where the domain explicitly supports it
• contract: client and optional project

Defaults remain visible, removable, and backend-authorized.

2. Attention is not the same as availability

Needs attention may contain only a durable state with:

• a causal record
• a responsible actor
• a valid action
• a completion condition

Optional capabilities such as Create project, Create subscription, or Upload file belong in a quiet client-scoped Create action, not in the attention queue merely because no such record exists.

3. Creation does not steal navigation by default

When a user creates a record from an existing work surface:

• keep them in place
• close the completed editor
• confirm success once
• offer Open {record} when a durable detail destination exists

Redirect automatically only when the user explicitly entered a route-backed composition flow or the created record is unambiguously the next workspace.

Nested creation resumes its parent flow instead.

4. Smart means quietly prepared

The app remembers and arranges; the user decides.

At the beginning of a day, the operator should be able to see:

• what genuinely needs their response
• what is committed for today
• what they were already working on

The product does not need to declare one correct next move.

5. Smart means exact, not chatty

Recommendations use real state and specific verbs. They do not add assistant prose, speculative urgency, or multiple competing primary actions.

6. One surface has one dominant job

• Today executes the workday.
• Overview prioritizes agency-level interventions.
• Client detail explains one client's world.
• Domain workspaces operate across clients.
• Record detail performs and resolves the record's workflow.

7. The nearest truthful destination wins

If the causal record and valid action are known, open that record and action. Use a collection only when no durable record destination exists or the job is genuinely queue-based.

Bounded Delivery Plan

PROD-01A — Safe working-scope inheritance

Introduce one route/shell working-scope contract and apply it to global create actions. Do not change client focus when merely inheriting visible context.

Implementation status: landed on 2026-07-28. Client and project detail routes now register temporary visible context with the shell. Global create actions resolve explicit invocation context first, visible route context second, and persistent client focus third. Incoherent client/project combinations are dropped rather than guessed, and route inheritance never mutates client focus.

Initial targets:

• project route → task, timer, note, reminder, file, contract
• client route → project, timer, note, reminder, invoice, subscription, quote, contract, file, link, portal
• task/pinned project surfaces → exact task/project context

PROD-01B — Truthful client actions

Split client Needs attention from optional client-scoped Create actions. Remove absent optional features from recommendation ranking.

Implementation status: landed on 2026-07-28. The client overview now reserves Needs attention for an enabled-but-incomplete portal or an existing billing relationship in an attention or past-due state. Missing projects, subscriptions, invoices, shared files, and unused billing setup no longer manufacture urgency. Permission-valid person, project, invoice, and subscription actions remain available in a separate, quiet Create group.

PROD-01C — Completion handoff consistency

Apply the existing actionable-success pattern to the remaining high-frequency exceptions, starting with timer quick-stop and reminder creation, then request and portal response loops.

Implementation status: landed on 2026-07-28. The shared actionable-success contract now spans organization and portal surfaces. Timer quick-stop offers the exact saved time entry, reminder creation offers the durable reminder detail, and both portal support and project request creation offer the exact new request without forcing navigation.

Portal request handoffs use canonical requestId routes. Choosing Open request preserves the active client workspace, scrolls to the matching request card, moves programmatic focus to it, and gives it a temporary selected treatment. This provides an exact destination without introducing a second request-detail surface.

The response-loop audit deliberately leaves these transitions as in-place confirmation:

• organization support reply, owner assignment, and resolution already occur inside the selected request drawer
• portal request replies already occur inside the matching request thread
• project feedback and acknowledgements already occur on the causal project and request
• agreement responses return to the matching agreement collection
• file-request uploads and response documents already expose the created file or the Files workspace

The rule is therefore not “every success needs a button.” A success action is added when completion would otherwise lose the created durable record or next responsible action. When the user already remains at that record, one quiet confirmation is the lower-friction result.

PROD-01D — Calm workday orientation

Reshape the top of Today around Needs you, Today, and Continue without forcing a universal ranking or hiding the underlying typed-work, task, reminder, and agenda queues.

Implementation status: landed on 2026-07-28. Today now uses three deterministic lanes:

• Needs you contains actionable operational records assigned to the viewer or left in a shared queue the viewer can act on
• Today contains overdue and due-today tasks, due reminders, and calendar commitments on the viewer's local date
• Continue contains the active timer, pinned notes, and every remaining open task

Project tasks are partitioned between Today and Continue; they are not ranked by a cross-signal numeric score. Existing backend order remains intact inside each task lane. The page-wide task scope defaults to the viewer and unassigned work, with All tasks available for team operation. The operational lane separately defaults to the viewer/shared queue and keeps the explicit team queue option.

Full workspaces remain directly available from each lane. Calendar events and reminders outside today are not presented as today's commitments, but Calendar and Reminders remain one action away. The hero reports the three lane counts instead of declaring one supposedly correct next move.

PROD-01E — Weekly billing readiness

The All invoices workspace now offers one optional, period-based Ready to bill surface when eligible tracked time actually exists. It defaults to the current month, supports the shared date presets and a custom range, and groups readiness by client and currency without combining unlike money.

Each client row shows only the useful summary: duration, calculated value, project/general-work scope, and period. Prepare invoice carries that exact client, currency, and period into a separate invoice draft. It does not add time silently: the composer still asks the user to confirm the compact recommendation before entries are reserved.

The readiness calculation uses approved, billable, unallocated hourly time and historical rate/currency snapshots. It excludes subscription-covered, retainer, non-billable, pending-review, reserved, and already-invoiced entries. Missing rates remain explicit rather than producing a false total. Very large result sets ask the user to narrow the period rather than displaying a partial amount.

Direct invoice creation, manual lines, project-scoped invoices, and workflows that never track time remain unchanged. The feature appears as useful context, not an overdue queue or required billing process.

PROD-01F — Exact portal follow-through

Portal overview now routes each record-specific spotlight to the narrowest existing destination:

• recent projects open project detail
• recent shared files and featured resources open the artifact directly when possible
• support replies and submitted requests focus their exact request thread
• file-request attention focuses the exact request in Files
• project-update attention opens project detail and focuses the exact update
• contract attention opens the exact review dialog, while quote attention focuses the exact quote
• invoice attention continues to open invoice detail

The shared handoff behavior scrolls, focuses, and visibly marks the target only when it exists in the authorized result set. Unknown or stale identifiers do not focus another record.

Completion behavior follows the restraint rule established in PROD-01C. File and document responses return to the same request card with its new state, and acknowledgment stays on that causal record; they no longer offer a redundant generic Open Files action. Standalone file uploads still offer the exact created file.

Draft quotes are no longer emitted as portal attention because the portal Agreements workspace intentionally exposes only client-reviewable quotes.

PROD-01G — State-aware dock

The quick-action dock now reflects the same viewer-specific operational truth as Today without becoming a second overview or a prescriptive task ranker.

When exactly one authorized workflow record needs the viewer, the dock exposes one visually restrained attention action and opens that exact blocker, time entry, file request, support request, or client-feedback destination. When several unrelated records need the viewer, the dock opens the bounded Needs you lane instead of claiming that one cross-type record is objectively most important. View-only and teammate-owned records do not create a personal dock interruption.

The collapsed trigger carries only a small attention dot. Opening the dock reveals the action with a truthful count and useful tooltip context. Persistent client focus scopes both the count and destination.

Configured create actions retain their order, shortcuts, permissions, and behavior. The attention action is separate from customization and pinned work, and disappears completely when nothing needs the viewer. Ready to bill remains optional billing context rather than being promoted into an obligation.

Resolved Direction

Owner direction confirms:

1. the experience must be helpful without becoming bossy or forcing one flow
2. the primary work is deciding what to keep, remove, connect, and disconnect, not adding product surface area
3. ease, minimalism, and practical usefulness are the product differentiators
4. future AI and workflow features must sit on a coherent non-AI core
5. visible context, truthful attention, and calm daily orientation are the correct foundations

PROD-01A through PROD-01G are now implemented for dogfooding. Together they establish the first complete operating-flow pass: context follows creation, attention is truthful, completion preserves the causal record, Today stays calm, billing readiness remains optional, portal spotlights preserve identity, and the dock exposes genuine work without displacing stable capture actions.