ulta-tasklist

Synced from ulta-tasklist/README.md. The repository is the source of truth.

ulta-tasklist is a standalone Pi package that provides a richer update_plan/tasklist-style planning tool. It keeps the familiar flat todo-list shape while adding clearer planning context and completion criteria:

a singleton top-level goal;
longer actionable step text;
optional RFC2119-style requirements for each step.

Install

Install directly from GitHub with Pi:

pi install git:github.com/applepi-ai/ulta-tasklist

After installation, start Pi normally and enable/use the installed package according to your Pi configuration.

Local development

Clone the package and run the lightweight checks:

git clone https://github.com/applepi-ai/ulta-tasklist.git
cd ulta-tasklist
npm run check

Load the extension from a local checkout for a smoke test:

pi --offline --no-extensions -e ./index.ts --list-models

Tool

`update_plan`

Input shape:

{
  "goal": "Create and verify a richer lightweight planning extension.",
  "plan": [
    {
      "status": "in_progress",
      "step": "Implement the extension entrypoint and register the enriched planning tool.",
      "requirements": [
        "The step MUST create a valid pi extension entrypoint.",
        "The step MUST register the update_plan tool.",
        "The step SHOULD keep the plan format flat and easy to read."
      ]
    },
    {
      "status": "pending",
      "step": "Run a smoke check that loads the extension.",
      "requirements": [
        "The step MUST run a command that exercises extension loading.",
        "The step MUST report whether the check passed."
      ]
    }
  ]
}

Valid statuses are pending, in_progress, and completed.

Requirements are allowed to be empty. When no requirements are specified, the tool warns that this is acceptable for research or exploratory work, but requirements should be provided when a step has tangible output.

Requirements that are present but do not include an RFC2119 keyword such as MUST, SHOULD, or MAY are accepted with a warning.

TUI panel and editing

When a plan exists, the extension shows a persistent compact Plan+ widget above the editor. By default it is one line: progress, active step, next step, and key hints. Use ctrl+shift+p (configurable, see below) or /plan-plus-toggle to expand/collapse the widget. In expanded mode, the current active step is expanded and bolded with its requirements, the next pending step is expanded in regular styling, and completed/later steps stay collapsed.

When all steps are marked completed, Plan+ automatically clears the active plan and hides the widget. The extension also registers /clear to start a new session while clearing Plan+ state, so stale completed plans do not reappear after clearing.

Use /plan-plus-edit to expand the Plan+ widget and activate inline editing in place. The inline editor lets users expand a pending step into a full form, edit only un-started (pending) steps, and add new pending steps. Completed and in-progress steps are read-only. Saving records the manual edit in session state without sending an interrupting user message to the agent; the edited plan is provided as hidden context on the next agent turn.

Inline editor controls:

list mode: ↑/↓ choose an editable pending step or the new-step row, enter edit, a add, s save and exit edit mode, esc cancel
form mode: type to edit the selected field, tab/↑/↓ move fields, ctrl+n +Req, ctrl+d -Req, ctrl+s save the expanded form, esc return to the list

Configuring the toggle shortcut

The expand/collapse shortcut defaults to ctrl+shift+p (Pi and outfitter composite profiles reserve ctrl+shift+t for cycling the thinking level). It can be overridden, in priority order:

The ULTA_TASKLIST_TOGGLE_KEY environment variable, e.g. ULTA_TASKLIST_TOGGLE_KEY=alt+p.
extensions/ulta-tasklist/config.jsonc in the active agent directory ($PI_CODING_AGENT_DIR, or ~/.pi/agent when unset):
```
{
  // Key for expanding/collapsing the Plan+ widget.
  "toggleKey": "alt+p"
}
```
The same file under ~/.pi/agent, as a fallback when the active agent directory is ephemeral (e.g. an outfitter composite profile).

Invalid or missing values fall back to the default. The widget’s key hints always show the resolved key.

Prototype learning

The flat enriched format feels like a practical middle ground: it preserves the low overhead of update_plan but makes completion criteria explicit. A later version could optionally add a second tool for completing a single step without resending the full plan.