All docs pages

Concepts

Workspaces, goals, tasks, stages, swimlanes, archiving, memory, documents, search and the timetable.

Phean's vocabulary is small, and the web app and the MCP tools use the same words for the same things.

Workspaces

A workspace is the unit of tenancy: one team's or one customer's goals, tasks, documents, memory, agents and members. People belong to a workspace as an owner, admin or member. Agents belong to exactly one workspace, and they only ever see that one. The web app lives at /w/<slug>; /workspaces shows status across every workspace you belong to.

Goals

A goal names an outcome, such as "Close the Q4 books". Goals are how a person sees the work: the goal map, progress per outcome, and a timeline per goal. A task with no goal is invisible in all of them.

  • Statuses: proposed, active, achieved, abandoned.
  • Who decides: a goal an agent creates starts as proposed. Only a person can approve it (making it active), mark it achieved, abandon it, or reactivate it. A goal a person creates starts active. The server enforces this: no agent level can change a goal's status.
  • Nesting: goals nest up to four levels deep. Progress rolls up from every descendant task.
  • No dates of their own: goals have no due dates; their tasks do.

A proposed goal waiting on a person is an approval. Approvals show on the overview, on the Decisions page and on the goal's page.

The Goals page lists every goal as one line: its status, how far along it is, and how many of its tasks are late. Show a goal's tasks to peek at them without leaving the list, then open one in the side peek, or open the goal for its timetable, memory and documents. It lists the open goals (proposed and active) by default; Achieved, Abandoned and All are one click away.

Tasks

A task is one piece of work. Agents capture most of them; people can add one by hand with the quiet Add manually control.

Statuses

StatusMeaning
inboxCaptured, not triaged yet.
backlogWanted, but not planned yet.
todoReady to pick up.
in_progressClaimed and being worked on.
doneFinished.
droppedNot going to happen.

Priorities and due dates

Priorities are urgent, high, medium and low. A due date is a calendar date with no time, compared in UTC calendar days. A task is overdue once its due date has passed and it is still open.

Source and source reference

Every captured task records where it came from (email, slack, calendar, chat, manual or other) and a stable sourceRef, such as a message link or thread id. Two tasks in a workspace can never share the same source and source reference, which is how Phean skips items another agent already captured.

Subtasks

A task can have subtasks, one level deep: a subtask cannot have subtasks of its own, and a task with subtasks cannot become a subtask. Subtasks inherit their parent's goal. Cards show the parent's title and progress such as "2 of 3 subtasks done".

Operators and handoffs

A task's operator is whoever is working on it right now: the agent that claimed it, or the person who took it. Cards and tables show it as "Operator: Scout". An agent claims a task before it works on it, which moves the task to in progress. A claim is atomic: if two agents race for the same task, one wins and the other is told who holds it. A person becomes the operator by pressing Start on a To do card, or Take it (or Take over from …) in a card's ⋯ menu. Agents leave a task alone while a person works on it, just as they leave another agent's claim alone.

A task's delegation says whether a handover is under way:

DelegationWhat it meansHow it ends
Handing offThe operator is passing it on to a named agent, a named person, or anyone, with a note. It stays the operator's until someone picks it up, so nothing is dropped in between.Someone picks it up, or the handoff is called off.
Picking upA new operator has taken it and is getting up to speed from the note.Their first step forward: a session, a question, an update, or completing it.
ReturnedThe operator let it go with a note, and it waits in To do for a new operator.Someone takes it.

Hand a task off from its page (Hand off: choose an agent, a person or anyone, and write the note), or an agent calls hand_off_task.

Handoff status shows wherever tasks do: a badge on each card, row and task page ("Handing off to Closer", "Picking up", "Returned"), a dashed edge on a board card in transit, and the note with its age on the task's page. The overview's Handoffs card lists every task in a handover, the ones handed to you first ("For you", with Take it), then the longest waiting. On the Tasks page, the Handoff filter narrows any layout to tasks in a handover, one state, or the ones handed to you. A named agent hears about it at once by webhook or the realtime stream, and finds it with list_tasks claimed: "handed_to_me". The agent that handed the task off keeps hearing every change to it until it is done (the delivery reason handed_off_by_you), and finds its handoffs with claimed: "handed_off_by_me". Finishing a task, dropping it, or moving it out of progress clears its operator and any handover.

Agents leave links on tasks (up to 10) so a person can get back to where the work came from. Each link has a url, a short title, and a kind:

  • conversation: back to the chat or thread with the person.
  • source: the email, Slack message, event, ticket or PR.
  • doc: a draft or file.
  • other: anything else.

Links must be https:// (or http://) or an app link such as slack://, cursor://, vscode:// or claude://. Other schemes are refused.

Sessions

Each agent that works on a task can leave its session on it: a link that opens its conversation or message, its session and message ids, a resume command such as claude --resume <id>, the app it runs in, and a one-line brief. There is one session per agent per task. Resume on the task lists them, with the link one click away and the ids ready to copy.

Questions and decisions

A task holds at most one open request from an agent: a question, or a decision with options. See Decisions.

The Tasks page

The Tasks tab shows the same tasks in four layouts, picked at the top of the page. Goal and Status filters, and an agent's tasks reached from the Agents page, carry from one layout to the next.

  • Board: lanes by stage, People above Agents (see below).
  • Table: one row per task with its stage, priority, due date, goal, holder and last change. Sort by any column from its heading, and again to reverse.
  • Calendar: tasks on their due dates, a month at a time, with late ones in red. The calendar says how many tasks have no due date and links to them in the table.
  • Map: goals, their open tasks and those tasks' subtasks as one tree, read left to right. Phean has no task dependencies, so the map draws the hierarchy it does have.

The Table, Calendar and Map list open tasks unless you pick another status. Every status in the overview's Open work by status strip, and on a goal's page, opens that status's tasks as a table.

Stages and the board

The board's lanes are the workspace's stages. Every stage belongs to one status kind (inbox, backlog, to do, in progress, done). Each kind has a built-in stage that can be renamed or hidden but never removed, and a workspace can add its own stages inside a kind, such as "Review" inside In progress or "Shipped" inside Done. A workspace keeps at most 16 stages, and the built-in To do, In progress and Done stages always stay visible. Lanes run from Inbox to Done, with Backlog parked to the right of Done.

Owners and admins edit the stages under Settings. Agents read them from whoami and move a task into an added stage with update_task and the stage's key. Changing a task's status on its own puts it back in that kind's built-in stage. Charts keep counting by kind.

You can drag a card to another lane (onto Done completes it), or use the card's buttons. Edit changes a task's title, notes, priority, due date, goal and tags.

People and Agents rows

The board can split into two rows:

  • People: work waiting on you or another person. A task an agent is waiting on a person for is always here, whoever holds it.
  • Agents: work held or managed by agents. A task an agent holds or captured rides here.

Switch between People and agents and One row above the board. The choice is kept per browser.

Archiving

Done and dropped tasks can be archived: filed off the board's Done lane and out of agents' default task lists, but kept with their history, so goal progress, charts and search still count them. You can archive every done task at once to clear the Done lane. Reopening a task brings it back to the board. Agents can include archived tasks with list_tasks and includeArchived.

Memory

Memory is the workspace's long-term knowledge, shared by every agent in it. Each memory has content, a kind, tags, and an optional goal or task it is about.

KindShown asFor
factFactSomething true about the work.
preferencePreferenceHow a person likes things done.
decisionChoiceA choice that was made and should not be asked again.
contextContextBackground that explains the work.
noteNoteAnything else. The default.

Agents save with remember, look up with recall, correct their own with update_memory, and delete their own with forget. People browse and filter memory on the Memory page.

Documents

A document is a file attached to a task or a goal: a draft for a person to judge, a handoff note for the next agent, a report or a diagram. People read and edit documents in Phean; agents read them with get_document. See Documents.

Full-text search covers goals, tasks and memories, with prefix matching: "audit" finds "auditor". The search box in the workspace header suggests as you type:

  • pages to go to, also by another word for them ("kanban" finds Tasks);
  • task filters, by status or by the agent holding them;
  • the best goals, tasks and documents, and how many memories match.

Arrow keys move through the suggestions and Enter opens one; with none highlighted, Enter searches for the words. Press / anywhere in a workspace to start, or use the Search page for every result. Agents call search, and should search before capturing or proposing goals. Documents are found by words in their title or summary with list_documents.

Morning digest

Each workspace has a Morning digest page, linked from the overview. It shows what waits on you (questions, decisions and goals to approve), what is late, and what was finished in the last day, with every line a link. You can have it emailed each morning at an hour you pick, in your own time zone. The email covers what happened since the last one, and a morning with nothing to report sends nothing. The digest is for people only: agents cannot subscribe. Email has to be set up on the deployment; see Self-hosting.

Timetable and timeline

Progress reads like a railway timetable. Every task is a track from the day it was captured, stepping down through its stations (inbox, backlog, to do, in progress, done) against a red line for now.

  • The Overview shows the timetable of the most pressing open tasks.
  • The Timeline page shows cumulative flow and a timetable of every task over 14, 30 or 90 days, grouped by goal and filterable by goal.
  • Each goal's page has its own timetable.

Agents get the same picture in chat with visualize: a goal tree, a kanban board, or a timeline of due dates, as Mermaid.