ftown 0.27.0 → 0.28.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ftown",
-  "version": "0.27.0",
+  "version": "0.28.1",
   "description": "CLI bridge for ftown — generic PTY-over-Centrifugo relay",
   "type": "module",
   "main": "dist/index.js",
@@ -73,5 +73,5 @@
   "overrides": {
     "qs": "6.16.1"
   },
-  "gitHead": "443f64c38ecd3d577f762d5e87986221fac1d26a"
+  "gitHead": "1d602fcdc7e33f265c1f486ce9e26f03654f4dec"
 }

package/skills/ftown/SKILL.md

@@ -53,6 +53,9 @@ ftown sessions preview --clear
 ftown sessions preview-reply --message "The preview is ready."
 ftown status set --state working --headline "Reviewing the API client" --progress 0/1
 ftown board
+ftown plan
+ftown plan add "Review the API client" --after p1 --priority 1
+ftown sessions create --parent --plan-item p2 --prompt "Review the API client"
 ftown brief set --file brief.md
 ftown attention list
 ftown worktrees list
@@ -128,6 +131,45 @@ ftown board --wait --until any-done --timeout 300
 ftown events --wait
 ```
 
+Plain `ftown board` appends a `planned` section with up to 5 ready plan
+items (`→ <id> <title>`, then `+N more`). `ftown board --all` also shows
+retired (archived) children after the live ones, suffixed `(retired)`.
+Tree events include the `plan` kind for plan changes and `removed` when a
+child is removed or archived while not already exited.
+
+## Plan list
+
+Keep the plan on the manager: `ftown plan` defaults to your own session
+(`$FTOWN_SESSION_ID`, the manager), and `--session-id <id>` targets another
+session's plan. This is the manager's plan, not a ticket system — it is a
+short ordered todo list the manager keeps for its own coordination. Add
+items, order them with precedence, and link each child to one item:
+
+```bash
+ftown plan [--json] [--session-id <id>]
+ftown plan add <title...> [--note <t>] [--after <id,id>] [--priority 1|2|3]
+ftown plan start <id> --session <child-id>
+ftown plan done <id>
+ftown plan drop <id>
+ftown plan todo <id>
+ftown plan edit <id> [--title <t>] [--note <t>|--no-note] [--after <ids>|--no-after] [--priority n]
+ftown plan rm <id>
+ftown sessions create --parent --plan-item <id> --prompt "<task>"
+```
+
+Precedence comes from `--after <id,id>` and `--priority 1|2|3` (1 is
+highest). An item is ready when it is `todo` and every item in its `after`
+list is `done` or `dropped`; the list shows `→` ready, `·` waiting, `▸`
+started, `✓` done and `✗` dropped. Creating a child with `--plan-item <id>`
+requires a parent, fails before creating anything when the item is unknown
+or not `todo`, and otherwise marks the item `started` with that child
+linked. When the linked child's card becomes `done`, its item becomes
+`done` too; a `failed` card leaves the item `started` for the manager to
+decide. `ftown plan start <id> --session <child-id>` links an existing
+child by hand, and `done`/`drop`/`todo` set the state directly. Every plan
+change emits one `plan` tree event (`<id> <state>: <title>`, plus
+` → ready: …` when items become ready). Exit codes: 0 ok, 1 error, 2 usage.
+
 **Delegating work.** Delegate implementation to ftown child sessions (`ftown sessions create --parent ...`) rather than in-process subagents — only sessions appear on the board and dashboard (cards, events, digests, parent-first questions).
 A child session may use its own subagents for reviews and lookups. Pick the CLI and model with `ftown quota --json` (see `references/quota.md`).
 

package/skills/ftown/references/orchestrator.md

@@ -1,39 +1,43 @@
 # Worker coordination examples
 
-Read `../SKILL.md` for identity, reporting and cleanup behavior, and
-`sessions.md` for the command reference. Use an ordinary session with the
-requested task and parent link; no special orchestrator mode is needed.
+Read `../SKILL.md` for identity, reporting and cleanup, and
+`sessions.md` for the command reference. No special orchestrator mode is needed.
 
 List existing sessions before creating another worker. Give each worker a
-bounded task, clear writable files and acceptance checks; save the returned
-`session.id`. Omit `--shell` to inherit your harness. Provider flavors require
-a bridge-host token configured with `ftown env set <flavor>`. Before picking a
-CLI, model and effort, run `ftown quota --json` and follow `quota.md` (owner
+bounded task, clear writable files and checks; save the returned
+`session.id`. Omit `--shell` to inherit your harness. Before picking a CLI,
+model and effort, run `ftown quota --json` and follow `quota.md` (owner
 tiers first); never route to `exhausted`.
 
+Keep the plan on the manager — the manager's plan, not a ticket system.
+Add steps with `ftown plan add` (`--after`/`--priority` set precedence;
+ready = every `after` done or dropped) and create each child with
+`--plan-item`, so its item starts and completes with the child:
+
 ```bash
 ftown brief set --file brief.md
-ftown sessions create --parent --worktree --workdir /path/to/repo --name fix-auth \
-  --prompt "Fix the auth bug; run the checks; report findings."
+ftown plan add "Fix the auth bug" --priority 1
+ftown sessions create --parent --plan-item p1 --worktree --workdir /path/to/repo --name fix-auth --prompt "Fix auth; run checks."
 ftown board --wait --until any-done --timeout 300
-ftown brief note "First worker done; reviewing"
 ftown attention list
-ftown harness mail send <worker-id> --type task "Check the expired-token case too"
+ftown harness mail send <worker-id> --type task "Check the expired-token case"
 ```
 
-Loop: spawn children, `ftown board --wait --until any-done --timeout 300`
-(or `any-blocked`/`any-ready`/`all-done`), act, repeat until all are done.
-Children keep cards current; progress goes on the card, never as mail. A
-child's question comes to you first: answer from facts you hold with
-`ftown attention answer`, or escalate preferences and irreversible choices
-with `ftown attention escalate --note`. Mail is for directed instructions,
-results and escalations; read it with `ftown harness mail read`. Each new
-batch nudges the recipient at most once, and a nudge may append a one-line
-digest of child status. Use `ftown sessions screen <worker-id> --limit 100`
-only to investigate terminal detail. Parallel tasks need disjoint write
-ownership and serialized shared resources. Children set their card to done
-and mail their result; you raise one "Work complete" notice for the whole job.
+Loop: keep the plan on the manager, create children with `--plan-item`,
+`ftown board --wait --until any-done` (or `any-blocked`/`any-ready`/
+`all-done`), act, repeat until all are done. Children keep cards current;
+progress goes on the card, never as mail. A child's question comes to you
+first: answer from facts you hold with `ftown attention answer`, or
+escalate preferences and irreversible choices
+with `ftown attention escalate --note`. Mail is for directed
+instructions, results and escalations; read it with
+`ftown harness mail read`. Each mail batch nudges at most once (a digest
+may be appended). Use `ftown sessions screen <worker-id> --limit 100`
+only to investigate. Parallel tasks need disjoint write
+ownership and serialized shared resources. Children set their card to
+done and report to the parent; you raise one "Work complete" notice
+for the whole job.
 
-After accepting a result, follow up before explicit cleanup with
+After accepting a result, clean up with
 `ftown sessions remove <worker-id>`, which retires a clean, merged or pushed
-bridge worktree and otherwise keeps it and says why.
+worktree and otherwise keeps it and says why.

package/skills/ftown/references/sessions.md

@@ -76,18 +76,73 @@ ftown board [--json] [--since <n>] [--ready] [--all] [--session-id <id>]
 # Wait until a board condition holds
 ftown board [--wait --until any-change|any-done|any-blocked|all-done|any-ready [--timeout <s≤300>]] [--session-id <id>]
 
-# Tree events for my tree (status, attention, pr, preview, exit, idle, result, mail)
+# Tree events for my tree (status, attention, pr, preview, exit, idle, result, mail, plan, removed)
 ftown events [--json] [--since <n>] [--limit <n>] [--wait [--timeout <s≤300>]] [--session-id <id>]
 ```
 
 `--ready` lists only children whose PR checks passed and who are not done;
-`--all` includes archived/completed children; `--since <n>` limits the board
-to children with events after that cursor (the board prints its cursor).
-Pass the cursor back as `--since` to see only what changed.
+`--all` includes retired (archived) children after the live ones, newest
+first, capped at 50 and suffixed `(retired)` in plain output; `--since <n>`
+limits the board to children with events after that cursor (the board
+prints its cursor). Pass the cursor back as `--since` to see only what
+changed. Plain board output appends a `planned` section after the child
+rows: up to 5 ready plan items as `→ <id> <title>`, then `+N more` when
+more are ready.
+
+Tree events also include `plan` (one per plan change, summary
+`<id> <state>: <title>`, plus ` → ready: <id>, …` when items become ready)
+and `removed` (summary `removed`, when a child is removed or archived
+while not already exited).
 
 Exit codes for `status`, `board` and `events`: 0 ok, 1 error, 2 usage,
 3 wait timed out with the condition unmet.
 
+## Plan list
+
+The plan is the manager's plan, not a ticket system: a todo list with
+precedence stored on the manager (parent) session. It defaults to
+`FTOWN_SESSION_ID`; `--session-id <id>` targets another session's plan.
+
+```bash
+# List in plan order (--json passes the PlanView through)
+ftown plan [--json] [--session-id <id>]
+
+# Add (title is the remaining words; precedence via --after/--priority)
+ftown plan add <title...> [--note <t>] [--after <id,id>] [--priority 1|2|3] [--session-id <id>]
+
+# Link an existing child, or set state directly
+ftown plan start <id> --session <child-id> [--session-id <id>]
+ftown plan done <id> [--session-id <id>]
+ftown plan drop <id> [--session-id <id>]
+ftown plan todo <id> [--session-id <id>]
+
+# Edit or remove (removing strips the id from other items' after lists)
+ftown plan edit <id> [--title <t>] [--note <t>|--no-note] [--after <ids>|--no-after] [--priority n] [--session-id <id>]
+ftown plan rm <id> [--session-id <id>]
+
+# Create a child for a plan item (marks it started, linked to the child)
+ftown sessions create --parent --plan-item <id> --prompt "<task>"
+```
+
+List marks: `→` ready, `·` waiting, `▸` started, `✓` done, `✗` dropped,
+printed as `<mark> <id> [P<priority>] <title>` plus `(after p1,p2)` or
+`→ <child name>` when linked. Ordering is ready first, then waiting (both
+by priority ascending, then creation time), then started, done and
+dropped. An item is ready when it is `todo` and every item in its `after`
+list is `done` or `dropped`; precedence is set only with `--after` and
+`--priority` (1 is highest). Item ids are `p<n>` and are never reused.
+Limits: 200 items, title 140 characters, note 500, at most 20 `after`
+ids; `after` ids must exist, with no self-reference or cycles.
+
+`--plan-item <id>` (on `ftown sessions create`, requires `--parent` or
+`--parent-id`) fails with an error before any session is created when the
+item is unknown or not `todo`; after creation the item becomes `started`
+with the child linked, and a linking failure only warns (the session
+stays). When a linked child's card becomes `done`, the item becomes
+`done`; a `failed` card leaves it `started` for the manager to decide.
+Setting an item back to `todo` clears its linked session. Exit codes for
+`ftown plan`: 0 ok, 1 error, 2 usage.
+
 ## Manager brief
 
 A coordinating session keeps a markdown brief plus timestamped notes; the
@@ -362,6 +417,7 @@ Fan-out targets are messaged sequentially, one JSON result line per target.
 | `--command` | Full command override (skips `--shell` builder) |
 | `--parent` | Set parent to `$FTOWN_SESSION_ID` |
 | `--parent-id` | Explicit parent session UUID |
+| `--plan-item <id>` | Do plan item `p<n>` of the parent (requires `--parent` or `--parent-id`; see Plan list) |
 | `--worktree` | Create a bridge-owned git worktree for the session (see Worktrees) |
 | `--branch <b>` | Worktree branch (requires `--worktree`; default `ftown/<slug(name)>`) |
 | `--base <ref>` | Ref the worktree branch starts from (requires `--worktree`) |
@@ -443,6 +499,10 @@ The CLI wraps the loopback API. Raw access if needed:
 | GET | `/api/sessions/:id/attention/routed` | Open parent-routed items of my children → `{ items }` |
 | GET/PUT/DELETE | `/api/sessions/:id/brief` | Read, set/clear (`{ text: string \| null }`) or delete the manager brief |
 | POST | `/api/sessions/:id/brief/notes` | Append a brief note (`{ text }`) |
+| GET | `/api/sessions/:id/plan` | Read the plan (`PlanView`: ordered items plus ready ids) |
+| POST | `/api/sessions/:id/plan` | Add a plan item (`{ title, note?, after?, priority? }`) → `{ item }` |
+| PATCH | `/api/sessions/:id/plan/:itemId` | Edit a plan item (`{ title?, note?: string\|null, after?, priority?, state?, sessionId?: string\|null }`) → `{ item }`; item id is `p<n>` |
+| DELETE | `/api/sessions/:id/plan/:itemId` | Remove a plan item (strips it from other items' `after`) → `{ ok: true }` |
 | GET | `/api/worktrees` | List bridge-owned worktrees with git status |
 | POST | `/api/worktrees/prune` | Retire eligible archived worktrees → `{ removed, retained }` |
 | GET | `/api/sessions/:id/attention/:eventId` | Read one item (`?waitSeconds=0..25` long-polls until resolved) → `{ event }`; 404 `attention_not_found` |