Recipe - plan and work through a big job

Goal: for a request that is more than a small change, agree on a plan with the user first, then work through it one task at a time with a todo list, so nothing is forgotten, even in a long chat that gets summarized.

1. Decide whether the request needs a plan

Suggest plan mode before you change anything when the request:

• touches several canvases or resources (routes, workflows, custom blocks, test suites, app config, ...),
• spans more than one area (for example a route, its trigger and a database integration), or
• is vague: you would have to guess what the user wants.

Do not suggest it for one or two small, clear changes (one new route, one fixed block, one renamed field). Just do those.

Call suggest_plan_mode:

{ "reason": "Three new routes, a KV store and test suites: worth agreeing on a plan first." }

The call always waits for the user, in every mode. The result says what they chose:

Result	What to do
User switched to plan mode: look around with read tools and write the plan now. ...	You are now in plan mode. Go to step 2 in the same reply.
User chose to continue without a plan. Go on with the task.	Do the work as usual, without a todo list.
The user did not approve suggest_plan_mode ...	Ask the user what they want, or continue without a plan.

In plan mode suggest_plan_mode is not offered: you are already planning.

2. Write the plan (plan mode)

In plan mode you only have read tools. Use list, get, get_canvas and search_docs to see what exists, then reply with the plan as text:

• A numbered list of main tasks. Give a task subtasks when it has more than one step.
• Every task that changes something ends with a check subtask: call_route, or a test suite you write and run.
• "Commit" or "save a version" means Fluxify versioning (commit_version), not git.
• When the work will be ready for production, add a last task "Ask the user about promoting to production". Never promote on your own.
• End the plan by telling the user how to start, word for word or close to it: Reply "go ahead" to start. Switch to Auto first if you don't want to approve each change.

To change the plan, the user replies in plan mode; write the whole plan again with the change.

3. After approval: write the todo list

The user approves the plan by switching to Manual or Auto and replying "go ahead". update_todos is offered from then on. Your first call writes the plan as the list.

Call update_todos with items:

{
  "items": [
    {
      "text": "Build GET /products",
      "subtasks": [
        { "text": "save_route GET /products" },
        { "text": "edit_canvas: read products from the KV store, respond 200" },
        { "text": "Check with call_route" }
      ]
    },
    {
      "text": "Cover it with a test suite",
      "subtasks": [{ "text": "save_test_suite with a 200 case" }, { "text": "run_test_suite until it passes" }]
    },
    { "text": "Save a version of GET /products" },
    { "text": "Ask the user about promoting to production" }
  ]
}

Every call answers with the whole list and the task to do next:

{
  "todos": [
    {
      "id": "1",
      "text": "Build GET /products",
      "status": "pending",
      "subtasks": [
        { "id": "1.1", "text": "save_route GET /products", "status": "pending" },
        { "id": "1.2", "text": "edit_canvas: read products from the KV store, respond 200", "status": "pending" },
        { "id": "1.3", "text": "Check with call_route", "status": "pending" }
      ]
    },
    {
      "id": "2",
      "text": "Cover it with a test suite",
      "status": "pending",
      "subtasks": [
        { "id": "2.1", "text": "save_test_suite with a 200 case", "status": "pending" },
        { "id": "2.2", "text": "run_test_suite until it passes", "status": "pending" }
      ]
    },
    { "id": "3", "text": "Save a version of GET /products", "status": "pending" },
    { "id": "4", "text": "Ask the user about promoting to production", "status": "pending" }
  ],
  "next": { "id": "1.1", "text": "save_route GET /products", "status": "pending" }
}

Rule	Value
Ids	Given by position: 1, 2, ... for main tasks, 1.1, 1.2, ... for subtasks
Depth	One level of subtasks
Size	At most 30 items in all, 200 characters each
Statuses	pending, in_progress, done, dropped
In progress	One item at a time
A main task with subtasks	Its status comes from its subtasks: done when they are all done or dropped

A call that breaks a rule fails with the reason, and the list stays as it was.

4. Work one task at a time

Start the item next names, then mark it. Call update_todos with id and status:

{ "id": "1.1", "status": "in_progress" }

Do the work (here save_route), then:

{ "id": "1.1", "status": "done" }

Read next from the result and go on: 1.2, then 1.3. Mark an item done only when its check passed. Mark one dropped when it is no longer needed. A main task with subtasks can only be marked dropped (that drops its open subtasks); otherwise mark its subtasks.

5. Change the list mid-way

When the user stops you and adds or drops work, write the whole list again with items, keeping the statuses of what is already done:

{
  "items": [
    { "text": "Build GET /products", "status": "done", "subtasks": [{ "text": "save_route GET /products", "status": "done" }, { "text": "edit_canvas: read products from the KV store, respond 200", "status": "done" }, { "text": "Check with call_route", "status": "done" }] },
    { "text": "Add a ?category= filter to GET /products" },
    { "text": "Cover it with a test suite" },
    { "text": "Save a version of GET /products" },
    { "text": "Ask the user about promoting to production" }
  ]
}

Ids follow the new positions, so read them from the result.

6. Finish

When every item is done or dropped, the list is finished and update_todos is no longer offered. { "items": [] } clears the list the same way. End with a short summary of what you changed and how you checked it. For the promotion task, ask the user; do not call promote_version unless they say so.

After a summary

In a long chat the earlier part is replaced by a summary. The summary ends with the current todo list, and the latest update_todos result is never shortened. Carry on from the item in progress, or the first pending one, as if nothing happened.

Common problems

What you see	What to do
update_todos works only after the user approves a plan.	There is no approved plan and no open list. Work without one, or suggest plan mode.
Only one item can be in_progress at a time	Mark the finished item done first.
Task 2 has subtasks: mark those instead.	Mark the subtasks; the main task follows them.
The list has 31 items	Merge small steps into one subtask; keep it to 30.
You are in plan mode already: write the plan.	Don't suggest plan mode in plan mode. Write the plan.