create-pmos 0.515.0 → 0.517.0

package/workspace/guide/breakdown.md

@@ -1,122 +1,22 @@
 ---
 type: Guide
-title: "Breakdown: an initiative's items"
-description: "How to break an initiative into items, move them in the Tree and on the Board, keep what an agent proposes, hand an item to an agent, and use pmos item from a terminal."
-timestamp: 2026-10-05
+title: "An initiative's tasks, and pmos item"
+description: "Where an initiative's tasks show in the workspace, how an agent adds tasks, who made a change, and the pmos item commands."
+timestamp: 2026-11-03
 ---
 
-# Breakdown: an initiative's items
+# An initiative's tasks, and pmos item
 
-An initiative's breakdown is the list of items that do its work. Each item has a title, an owner, a stage and a state. The state is Todo, Doing, Review or Done.
-
-The workspace keeps the items in `planning/runs/plan-items.jsonl` in the repository. Each change adds one line to that file. Nothing is changed or removed. The workspace page and the `pmos item` command use the same writer, so they always show the same items.
-
-## Open the Breakdown
-
-1. Select an initiative in the list.
-2. In the detail, press **Breakdown**. The row shows how many items are done, for example "7 of 12". It shows "no breakdown" when the initiative has no items, and "no breakdown · 9 proposed" when an agent proposed items that you did not keep yet.
-3. The Breakdown opens in a tab. Press **Tree** or **Board** at the top to change the view. The bar on the right shows the same count as the detail.
-
-## The Tree
-
-The Tree shows the stages of the initiative in order, for example Intake, Spec, Contract, Build and Evaluate. A stage shows only when it has items, items an agent proposed, or a step that is still owed.
-
-- **Stage header.** The name, CURRENT on the stage the initiative is at now, and a count such as "2 of 5 · 3 proposed". Press the arrow at the end of the header to collapse or expand the stage.
-- **Owed row.** "Owed: contract · agent" means that the workflow still needs that step from the agent (or from you). The row has the label DERIVED. You cannot edit it, move it or tick it. It goes away when the step is done.
-- **Show n done.** Done items are folded away. Press the line to show them.
-- **Owed steps are not shown.** When the workflow cannot be read, the Tree shows no owed rows. A note at the top says so and gives the reason. The owed rows come back the next time the workflow can be read.
-- **Flagged lines.** A line in `plan-items.jsonl` can have no effect: a broken line, an item added twice, or a Keep that was not written from the workspace page. The rows cannot show such a line, so a note at the top of the pane gives the number of flagged lines and the first three.
-- **Item row.** A grip, a box to tick, the title and one line with the owner, the due date and, when an agent made the last change, which agent ("by agent · sess-3"). At most two signals show (see Signals below). Press the title to open the item sheet. Press the three dots for a menu: Open, Move to a state, Move up, Move down, Hand to agent, Withdraw.
-- **Add item.** Press **Add item** at the end of a stage, type a title and press Enter. The field stays open for the next title. Press Enter in an empty field, or Escape, to close it. To add many items at once, paste a list with one title on each line. Markers such as `- `, `* `, `[ ] ` and `1. ` are removed. You can paste at most 50 lines.
-
-### Signals
-
-| Signal | What it means |
-|---|---|
-| Blocked | You or an agent gave a reason why the item cannot go on. The reason shows when you point at the signal, and in the item sheet. |
-| no evidence | An agent moved the item to Done without evidence, such as a commit or a pull request. Add the evidence in the item sheet, or move the item back. |
-| late | The due date is in the past and the item is not Done. |
-| Doing, Review | The state of the item, in the Tree only. On the Board, the column shows the state. |
-| moved by you | You moved an item that an agent owns. The agent sees the same signal. |
-| Proposed | Only on an item an agent added before D98 that was never kept. Since D98 an agent's item is live at once. |
-
-### Keys in the Tree
-
-| Key | What it does |
-|---|---|
-| Arrow up, Arrow down (or k, j) | Move between rows and stage headers. |
-| Enter | Open the item sheet of the row. |
-| Space | Tick the row Done, or tick it back to Todo. |
-| n | Add an item after the row, or at the end of the stage. |
-| Alt+Arrow up, Alt+Arrow down | Move the row up or down. At the top or the bottom of a stage, the row moves into the stage before or after. |
-| Escape | Close the add field or the sheet. |
-
-To move an item with a mouse or a finger, drag its grip. Drop it between two rows to change its order, or drop it on a stage header to put it at the end of that stage. On a phone, hold the grip for a moment before you drag.
-
-Collapsing a stage is your own view. The workspace keeps it in this browser only. It writes nothing to the repository.
-
-## The Board
-
-The Board shows the same items in four columns: Todo, Doing, Review and Done. A card is always in the column of its state, so the Tree and the Board always agree.
-
-- Each card shows the title, the stage, the owner, the due date and, when an agent made the last change, which agent. The card's menu has Move to a state, Hand to agent and Withdraw. Open it with the three dots, or, on a wide Board with a mouse, where the cards have no three dots, right-click the card or press Shift+F10 on it.
-- An empty column says so, for example "Nothing in Review.".
-- The Done column shows the items done in the last 14 days. Older done items stay in the Tree, and the column says how many there are.
-- When the Board is wide enough, drag a card to another column to change its state. To make it wide on a desktop, fold the list or the detail with its `⟨` button ([Layout](layout.md#folding)).
-- When the Board is narrow, for example on a phone, it shows one column at a time. Press Todo, Doing, Review or Done above the cards to change the column. To move a card, press the card, then press the new state in the item sheet.
-
-If you move an item that an agent owns, the item shows "moved by you". The agent sees the same signal.
-
-## The item sheet
-
-The sheet shows every field of one item, from top to bottom:
-
-1. The state: Todo, Doing, Review or Done. Under it, two lines show only when they apply:
-   - "Added by agent · sess-3 on 5 Oct." for an item that an agent added. It is live; withdraw it if you do not want it.
-   - **Add evidence**, for an item that reads Done with no evidence. Type `commit:<sha>`, `pr:<number>`, `file:<path>` or `note:<text>` and press Enter. If the workspace refuses the reference, a message tells you why and your text stays in the field to correct.
-2. Title.
-3. Owner: You, Agent, a person (type the name) or a tracker (type the reference).
-4. Stage.
-5. After: the items that must finish first. Choose an item of this initiative, or type the id of an item in another initiative and press **Add**.
-6. Start and Due.
-7. Milestone.
-8. Blocked, and Blocked because. An item is blocked only when you give a reason.
-9. Note.
-10. **Hand to agent.**
-11. History: who made each change, what changed, and when.
-
-Each field saves by itself: a text field when you press Enter or leave it, the other fields when you change them. Each save adds one line to the file. Press **Close** or Escape to close the sheet.
-
-## Undo
-
-Done and Withdraw wait 8 seconds before they are saved. A message shows at the bottom with **Undo**. Press **Undo** to cancel. Nothing is saved. If you do not press it, the change is saved after 8 seconds. If you close the page during the 8 seconds, the change is saved at once.
-
-A tick back from Done to Todo is saved at once.
+An initiative owns its task breakdown. In the workspace, its tasks show under the initiative in Home's list (the 3 most urgent, then **Show N more tasks**) and on the initiative's page in the Viewer. Press **+** at the top of Home's list, then **Task**, to add one. A check box is a task: amber when it is late. [Home](home.md) explains the list.
 
 ## Items an agent adds
 
-An agent can add items with `pmos item add`. Since D98 its items are live at once: they show in the Tree and on the Board and count in the progress, with no Keep card. Each item names the agent that added it, so you can withdraw it if you do not want it. A Keep line from before D98 has no effect any more and is not flagged.
-
-Today shows two breakdown cards:
-
-- **no evidence**: an agent marked an item Done without evidence, such as a commit or a pull request. Open the item and add the evidence, or ask the agent to run its move again with `--evidence`.
-- **check**: a line in `plan-items.jsonl` that has no effect, for example a Keep that the workspace page did not write.
-
-## Hand to agent
-
-Press **Hand to agent** in the item sheet, or in the menu of a row or a card (the three dots, or a right-click or Shift+F10 on a card of a wide Board).
-
-1. The sheet shows one line: "Agent will: …" with what the agent does first and where it works, for example on a new branch. Press **Details** to read the full prompt, the branch and the folder.
-2. Press **Go** to start the session, or **Cancel**. Go starts exactly what you read. If the item changed after you read it, Go refuses, and you must press Hand to agent again.
-3. The session opens in a terminal tab. The agent reports with `pmos item`.
-
-If a session already works on the item, the sheet says "A session is already working on this item." and offers **Open session**.
+An agent can add items with `pmos item add`. Since D98 its items are live at once: they show under the initiative and count in its progress, with no Keep card. Each item names the agent that added it, so you can withdraw it if you do not want it. A Keep line from before D98 has no effect any more and is not flagged.
 
-Nothing else starts a session from the Breakdown. A drag, a drop or a change of state never starts one.
 
 ## Who made a change
 
-Each line in the file names who wrote it. The workspace shows it as:
+Each line in the file names who wrote it. The history of an item shows it as:
 
 | Label | Who |
 |---|---|
@@ -124,7 +24,7 @@ Each line in the file names who wrote it. The workspace shows it as:
 | agent · sess-3 | The agent session that the workspace started, from its terminal. |
 | agent (unknown) | A command run without a session the workspace started, and not at your own terminal. |
 
-The file records an agent with its full session token, for example `agent:sess-3.0a1b2c3d`. The workspace page gets only `agent:sess-3` and shows "agent · sess-3".
+The file records an agent with its full session token, for example `agent:sess-3.0a1b2c3d`. The workspace shows it as "agent · sess-3".
 
 An agent can change, move and withdraw any item, the items you added included. Each of those lines names the agent, so the history of the item shows who did what.