feat(plan): file-based revisions, free-form status, and optimistic locking

docs/tools/plan/index.md

@@ -25,12 +25,44 @@ No additional options are required. All agents that include `type: plan` in thei
 
 ## Available Tools
 
-| Tool          | Description                                                                                       |
-| ------------- | ------------------------------------------------------------------------------------------------- |
-| `write_plan`  | Create or update a shared plan by name. Replaces the entire plan content — read it first to preserve what you want to keep. Each write bumps the revision number. |
-| `read_plan`   | Read a shared plan by name, including its title, content, author, revision number, and last-updated timestamp. |
-| `list_plans`  | List all shared plans with their name, title, author, revision, and last-updated timestamp. |
-| `delete_plan` | Delete a shared plan by name.                                                                     |
+| Tool                    | Description                                                                                       |
+| ----------------------- | ------------------------------------------------------------------------------------------------- |
+| `write_plan`            | Create or update a shared plan by name. Replaces the entire plan content — read it first to preserve what you want to keep. Each write bumps the revision number. |
+| `read_plan`             | Read a shared plan by name, including its title, content, author, status, revision number, and last-updated timestamp. |
+| `list_plans`            | List all shared plans with their name, title, author, status, revision, and last-updated timestamp. |
+| `delete_plan`           | Delete a shared plan by name.                                                                     |
+| `update_plan_from_file` | Create or update a plan, taking the new content from a file on disk instead of inline. Use it with `export_plan_to_file` to edit a large plan without re-sending its whole body. |
+| `export_plan_to_file`   | Write a plan's content to a file. The content goes to disk and is **not** returned as tool output, so materialising a plan costs no tokens. |
+| `set_plan_status`       | Set a plan's free-form status without rewriting its body. The plan must already exist. |
+| `get_plan_status`       | Read a plan's status and current revision without fetching its body.                  |
+
+### Cheap edits with file-based revisions
+
+Re-sending a whole plan on every revision is expensive. The file-based tools let
+an agent edit a plan without paying input-token cost for its body:
+
+1. `export_plan_to_file` writes the current plan content to a path. The content
+   is written to disk and is **not** returned.
+2. The agent edits that file in place with its filesystem tools.
+3. `update_plan_from_file` commits the file's new contents as the next revision.
+
+### Free-form status
+
+Each plan carries a free-form `status` string. There is no fixed vocabulary:
+define your own in the system prompt (e.g. `idle`, `in-progress`, `blocked`,
+`done`, `canceled`). Read and write it independently of the body with
+`get_plan_status` and `set_plan_status`, or pass `status` to `write_plan` and
+`update_plan_from_file`. The TUI surfaces the status next to the plan title.
+
+### Optimistic locking
+
+When several sessions edit the same plan, concurrent writes could silently
+overwrite each other. Every read returns a `revision` number; pass the value you
+last read as `last_known_revision` to `write_plan`, `update_plan_from_file`,
+`set_plan_status`, or `delete_plan`. If the plan changed since (its current
+revision no longer matches), the write is rejected with a version-conflict
+error and the caller should re-read the plan and retry. Omit
+`last_known_revision` to write unconditionally (last writer wins).
 
 ### Plan Names
 
@@ -46,7 +78,8 @@ Each plan document contains:
 | `title`    | A short human-readable title (optional)                   |
 | `content`  | The full Markdown or free-form plan text                  |
 | `author`   | Free-form label identifying who last wrote the plan       |
-| `revision` | Monotonically increasing counter, bumped on every write   |
+| `status`   | Free-form lifecycle label (optional), e.g. `in-progress`  |
+| `revision` | Monotonically increasing version counter, bumped on every write |
 | `updatedAt`| ISO 8601 timestamp of the last write                      |
 
 ## Example

examples/shared_plan.yaml

@@ -26,8 +26,12 @@ agents:
       You are a software architect. Use list_plans to see existing plans and
       read_plan to inspect one, then use write_plan to create or revise a plan
       by name. Always read before writing so you preserve content you want to
-      keep. Set the title and use "architect" as the author. When the
-      high-level plan is ready, hand off to the builder.
+      keep. Set the title and use "architect" as the author. Note the revision
+      you read and pass it as last_known_revision when you write, so a
+      concurrent edit by the builder is detected instead of silently lost; on a
+      conflict, re-read and retry. Use set_plan_status to mark the plan
+      "drafting" while you work and "ready-for-build" when the high-level plan
+      is done, then hand off to the builder.
     toolsets:
       - type: plan
     handoffs:
@@ -37,12 +41,15 @@ agents:
     model: openai/gpt-4o
     description: Reviews plans and adds concrete implementation steps
     instruction: |
-      You are an implementation engineer. Use read_plan to read the architect's
-      plan, then use write_plan to append concrete, actionable implementation
-      steps. Always read before writing so you don't lose the architect's work.
-      Use "builder" as the author. Delete obsolete plans with delete_plan. When
-      done, hand off back to root.
+      You are an implementation engineer. For large plans, edit cheaply: call
+      export_plan_to_file to write the current plan to a scratch file, edit that
+      file in place to add concrete implementation steps, then call
+      update_plan_from_file to commit it (passing last_known_revision so you
+      don't clobber a concurrent edit). Use "builder" as the author and
+      set_plan_status to "done" when the plan is complete. Delete obsolete plans
+      with delete_plan. When done, hand off back to root.
     toolsets:
       - type: plan
+      - type: filesystem
     handoffs:
       - root