Tasks, statuses, and goals

Projects track work as tasks and point it at goals. This page defines each piece and says why it is there. API has the endpoints, Architecture has how it is stored, and Projects in the intelligence docs has what becomes company knowledge.

The descriptions below are the ones people see. Types and statuses carry their own one-line description in workspace, and types also carry the example title and the prompts the desktop app shows when you write one, so the app and this page say the same thing.

Templates

Every project starts from a template, chosen when the project is created. The template sets the project's statuses and task types, and it can't be changed afterwards: every task's status belongs to its project's template. Two templates are built in:

General is the base for teams whose work isn't software: the fewest statuses and types that still say where work stands. The app lists General first and picks neither, so whoever creates the project chooses, with what each one sets up in front of them. Both use the same status categories, so closing, archiving, the assistant, and what becomes company knowledge work the same way in either. A project made before templates existed is General, with its open tasks in Todo and its finished ones in Done, and so is a template saved before them. Every scratchpad is General too. A project created through the API without a template or workflow uses product development, and so does a saved template unless it names General.

Tasks

A taskTask: One thing a project needs to do, decide, answer, or remember. It has a type, a status, and a title, and everything else is optional. The API and the database call it an item. is one thing a project needs to do, decide, answer, or remember. Every task has a type, a status, and a title of up to 200 characters. Everything else is optional, so adding one never takes more than New, a title, and Enter.

A new task is written in the same dialog a task opens in, so it looks the same before and after it is added. It starts as yours, or with the type, owner, and goal the list is filtered to, so it shows up where you added it. Changes to an open task wait for Save, so nothing half-typed is saved, and closing with unsaved changes asks first.

The API and the database still call a task an item. Older clients send kind and read state, and workspace keeps both in step with the type and status.

Types

A task typeTask type: What kind of task it is: task, bug, chore, feature, question, or note. The type decides which extra fields the form asks for and which part of the task can become company knowledge. says what kind of task it is. It decides how the task asks for its details and which part of the task can become company knowledge. A project offers its template's types. Product development offers these six:

General offers three of these, Task, Question, and Note, which read the same in either template.

Each type asks in its own words rather than with a box per detail. The title leads with the type, as a menu you can change, and shows that type's example, and the text below it gets the label and prompt in the table. One text with the right prompt holds steps, expectations, and context without making anyone fill in five boxes, and it reads as written when it is shown back. A type gets a field of its own only for what that text can't hold: today, the answer to a question, written once it is settled.

Every field is optional. The one rule is that a bug needs a resolution to close. Changing a task's type keeps the fields both types share and drops the rest, and the old values stay in the task's history.

Statuses

A task statusTask status: Where a task stands, such as Todo or In review. Each status belongs to a status category and carries a one-line description the app shows beside its name. says where a task stands. Every status belongs to one of six fixed status categoriesStatus category: One of six fixed stages every task status belongs to: backlog, unstarted, started, review, completed, or canceled. Completed and canceled are closed. Rules read the category rather than the status's name, so they keep working when a project adds statuses of its own., and every rule reads the category, never the status's name. A project uses its template's statuses. Product development uses these six:

There is no Canceled status. Work the project no longer wants is archived instead, in whatever status it had: it leaves every view except one filtered to archived tasks, nothing is deleted, and unarchiving brings it back.

General uses four:

A new task starts in Triage, or in Todo in a general project, at the top of the project, until someone decides where it goes. That is true whoever adds it: a person in the app, the assistant in a chat, or anything else through the API. If you already know where it belongs, pick another open status as you add it. The API accepts any of the project's statuses, Done included, which adds the task already closed. Lists group tasks under their status's name, so a heading always reads the same as the rows under it.

Status categories

The six categories, in the order work moves through them, are backlog, unstarted, started, review, completed, and canceled. Completed and canceled are closed; the other four are open.

Statuses can grow, but the categories are fixed, because rules need a meaning they can rely on:

• Closed decides the rules. It is when a bug needs a resolution, when a resolution counts as company knowledge, and what older clients read as resolved.
• Agents read open work in category order. The agent's context pack lists backlog tasks first, then unstarted, started, and review, each in the project's order. General's Waiting is in the started category.
• Custom statuses stay safe. When projects get statuses of their own, each one picks a category, so every rule keeps working without knowing its name.

Other task fields

Archive, versions, and history

• Archive hides a task, open or finished, without deleting it. It keeps its status and is read-only until someone unarchives it. The list stays on live work, and nothing is lost.
• Versions. Every change to a task's content (its title, body, type, fields, links, or resolution) writes a new version with who wrote it. Restoring an old version writes it again as a new one, so a restore never destroys anything. Company knowledge cites the exact version it came from.
• Change log. Every change to the status, owner, target date, goal, archive, or position is recorded with who made it and when, so "who moved this to Done?" always has an answer. The same write adds a line to the project's activity for a status change, an owner change, an archive, or an unarchive, which is how a task moving to In progress shows up there without anyone writing it down. Target date, goal, and position changes add none. In the app, a task's History shows versions and changes as one timeline, newest first, with Restore beside each earlier version.
• No silent overwrites. An edit says which version it started from. If someone else saved first, the edit is refused and comes back with the current task, so you see their change before making yours.
• History is permanent. Text pasted into a task stays in its history after an edit, so never paste a secret into a task.

How work moves

The stages exist so anyone can open a project and see where its work really stands, without asking anyone. A few beliefs shape how they work:

• Honest over hopeful. A status says where the work is, not where we'd like it to be. Move a task when its reality changes.
• Decide before you plan. Triage holds what someone reported, and Backlog holds what is worth doing someday. Keeping both out of Todo means Todo is a list people can actually work from.
• Starting is a commitment. In progress means someone is on it right now. If nobody is, it goes back to Todo. A short In progress list is a healthy one.
• Done means accepted. When someone else should check the work, In review holds it until they do, so nothing looks done too early. If the check finds a problem, it goes back to In progress.
• Every task ends, and the ending is written down. Done closes a task, and its resolution says what happened, so the next person, and company knowledge, doesn't have to guess. Work the project drops is archived in whatever status it had, and dropping it is an honest ending, not a failure.
• The path is a guide, not a gate. A two-minute chore can go straight from Triage to Done, and a reopened task goes back to wherever its work is. Every move is in the change log, so moving is cheap.
• Order is priority; status is progress. Within a stage, the order of the list says what matters most, and goals say why. A status never means "important".

flowchart LR
  T[Triage] --> B[Backlog] --> TD[Todo] --> P[In progress] --> R[In review] --> D[Done]
  T -- clearly worth doing --> TD
  T -- quick work --> D
  R -- changes needed --> P

Done closes a task; work the project drops is archived in whatever status it had. Any closed task can be reopened into an open stage. A few things happen on their own when a task moves:

• Closing it (moving it to Done) asks a bug for its resolution and lets the resolution count as company knowledge.
• Reopening it keeps the resolution on the task but stops it counting until the task closes again.
• Assigning it to someone else notifies them.
• Every move is recorded with who made it and when.

Anyone who can edit the project moves tasks. The assistant can add tasks, which land in Triage, or Todo in a general project, marked "Added by assistant", but in this release only people move them.

Notes and questions rarely need the whole path. A question's answer counts as soon as it is saved, so move the question to Done once the answer is settled. A note counts once it is saved and long enough to stand on its own, so mark it Done whenever you want it off the open list.

Examples

Each example starts with the path the task took.

A bug, from report to knowledge

Triage → Todo → In progress → In review → Done

A feature idea that waits, then is dropped

Triage → Backlog, then archived

Dana suggests "Export the rent roll to Excel", with why it matters: "Owners rebuild the rent roll by hand every month." In triage the team agrees it is worth doing, just not now, so it goes to Backlog. Three months later the new reporting page covers it, and Dana archives it, still in Backlog. The idea, why it mattered, and who archived it stay on record, and unarchiving brings it back. None of it becomes company knowledge: a feature counts only through its resolution, and only once it is closed.

A quick chore, straight to Done

Triage → Done

Marcus adds "Rotate the staging access keys", does it in ten minutes, and ticks it off. A chore doesn't need a resolution, but one line helps the next person: "Rotated Oct 3; next rotation due Jan 3."

A task that goes back from review

Todo → In progress → In review → In progress → In review → Done

Ilan finishes "Publish the October pricing sheet" and moves it to In review for Sara. She finds two buildings missing, so it goes back to In progress. He adds them, sends it back to review, and Sara moves it to Done. The change log shows both rounds, which answers "why did this take a week?" without a meeting.

A question, answered

Triage → Done

Sara asks "Which carrier handles EU shipments now?" Ilan fills in the answer: "DHL. The FedEx contract ended in August." The answer counts as company knowledge as soon as it is saved, in Ilan's words, and Sara moves the question to Done.

A note, recorded

Triage → Done

After a vendor call, Dana writes a note: "Call with Acme, Oct 2: they can't deliver the replacement units before the 15th because their warehouse is moving. They'll confirm a firm date by Friday. If it slips past the 20th, we use the backup supplier." A note of 200 characters or more stands on its own, so it counts as company knowledge from the moment it is saved. Dana marks it Done to take it off the open list.

Tasks the assistant suggested

Triage → …

In a project chat about a lease renewal, the assistant suggests three tasks in one card, all ticked. Sara unticks one, types "make the second one a bug", and submits. Two tasks land in Triage, marked "Added by assistant", and from there they move like any other task.

Saved views

A saved view is a way of looking at a project's tasks that everyone on the project shares: a list or a board, with filters, a grouping, and a sort. Views are the project's tabs. Editors save and edit them; owners delete them and set their order. A project has at most 20, and no two share a name.

A list groups its tasks by status, goal, owner, or type, or not at all. A board ignores the grouping: its columns are always statuses. Either can be sorted by position, target date, last updated, created, or time in status.

A filter narrows a view to tasks of some types, categories, statuses, owners, or goals, to overdue tasks, or to archived tasks. Without the archived filter a view leaves archived tasks out. A task shows when it matches every filter that is set, and any one of the values a filter lists. If a status a view names is retired, or a goal it names is deleted, the view drops it and carries on.

Every project starts with its template's views, whether it was made from a template or is a scratchpad:

Starting views belong to the system rather than to whoever made the project. They can be renamed, edited, or deleted like any other view.

A view is shared, so it never says "me". Showing only your own tasks, the view you last had open, and changes you haven't saved stay on your device. Two people editing the same view are handled the way two people editing a task are: if someone else saved first, the edit is refused and comes back with the view as it is now.

Goals

A goalGoal: An outcome a project is working toward, with one lead, an optional target date, and a status. A project has at most five active goals, and closing one needs a note saying how it ended. is an outcome a project is working toward, written as the result rather than the work: "New prices live in every building", not "Update prices".

On track, at risk, and off track are active. Achieved, missed, and dropped close the goal and need a closing note.

• At most five active goals. With more than five, none of them is really a priority.
• Owners decide what a goal is; the lead reports on it. Owners create, edit, and delete goals. The lead can change only the status and the closing note, and checks in each week.
• Contributors are worked out, not typed in. They are the owners of the unarchived tasks linked to the goal.
• Deleting a goal unlinks its tasks. Each unlink shows in that task's change log. A goal that has check-ins can't be deleted; close it as dropped instead.
• Agents read active goals as standing guidance: the outcome, how we'll know, the target date, the lead, and the status. Goals steer an agent; they never grant it anything.

Projects used to have one free-text goals box. Its text moved into each project's instructions under a "Goals:" heading wherever the instructions would still fit in 20,000 characters; elsewhere it stayed in the old goals field. Turning it into real goals is up to each project's owners.

Check-ins

Once a week, the goal's lead or a project owner checks in on each active goal: on track, at risk, or off track, with a one-line note of up to 500 characters saying why. The goal takes that status. A check-in doesn't close a goal; closing is a status change with a closing note. Anyone on the project can read a goal's check-ins, newest first.

Each project has a check-in day, Monday to Friday. It is Monday unless an owner changes it. Dates are New York's for everyone, because workspace keeps no time zone per person.

A late check-in clears the overdue goal, and it also counts for the next check-in day, which is never more than six days away. A closed goal has no state.

Check-ins are permanent. Nobody can edit or delete one, and a goal that has them can't be deleted either, so the record of how a goal went stays whole.

On weekdays Flow sends the lead of each due or overdue goal a Slack direct message: once on the day it is due, and once when it becomes overdue, so at most two for a missed week. The message names the goal and the project, says when the check-in was due, and links to the project to post it; a reply in Slack isn't saved. A lead who has left the project or has no Slack account gets no message. Due and overdue goals show in Flow whether or not the messages are sent.

What becomes company knowledge

Only a statement a task has settled counts, and only while it is settled: a note's text, a question with its answer, and a resolution while the task is closed. An open task's own text never counts, because it is a plan or a guess, and plans change. The rules, minimums, and whose words each statement is are on Projects, and the reasoning is docs/decisions/0096-project-tasks-are-signals-only-settled-statements-are-evidence.md↗.

For developers

Types and statuses are rows rather than code, so a new type, or a project's own status later, is an insert. Rules read the category and never compare a status's name. Goal statuses are a fixed list, checked by the database.

A client showing a project's tasks follows its changes instead of reloading them. It reads the project's change number before it loads the tasks, then asks what changed after that number, and keeps the newest number each answer gives it. An answer holds the tasks that changed, whole. It can also say to reload the goals, views, and settings, or to reload every task instead of merging. Anything written while the tasks were loading comes back in the first answer. The fields are in Following changes.