pi-tasque

Pi extension for durable project tasks plus in-session todos.

What this package provides

pi-tasque gives agents two task layers:

• Session todos: current-session execution checklist for inspect, edit, verify, and handoff steps.
• Durable tasks: repo-local backlog, specs, dependencies, notes, and ownership.

The bridge between the layers is explicit. pi-tasque can link, promote, or import tasks, but it does not automatically sync lifecycle state between todos and durable tasks.

Install

Install with Pi:

pi install npm:@bumpyclock/pi-tasque

For local development, install the local package path once:

pi install /Users/adityasharma/Projects/pi-tasque

Then use this edit loop:

edit TypeScript files -> /reload -> test behavior

Pi loads the extension entrypoint from the installed package path, so TypeScript source edits do not require reinstalling the local package. Use /reload in the Pi session after changing files under src/.

Agent guidance

Use todo for current-session checklists; use task for durable project work, ownership, notes, specs, dependencies, and explicit todo links.

Lifecycle boundaries

There is no automatic lifecycle sync between session todos and durable tasks:

• Completing a todo does not mark a durable task done.
• Marking a durable task done does not complete linked todos.
• task link actions record relationships only.
• task promote/import actions are explicit bridge operations.

Example workflow

Create a session todo:

{
  "action": "create",
  "subject": "Investigate failing release check",
  "owner": "developer"
}

Claim durable work and create one linked todo:

{
  "action": "claim",
  "task": "task-123",
  "for": "developer",
  "todo": true
}

List links:

{ "action": "list_links" }

Finish durable work after verification:

{
  "action": "finish",
  "task": "task-123",
  "because": "Docs and package checks passed."
}

Tool and command reference

Surface	Purpose	Notes
todo	Manage current-session tactical todos.	Session-local; replayed from successful todo and task results.
/todos	Show grouped current-session todos.	Interactive UI only.
task	Manage durable project tasks and todo links.	Resolves operations to the current git project root.
Todo overlay	Show active session todos above the editor.	Completed todos hide on the next turn.
Task status footer	Show cached durable-task status.	Display-only; agents should call task for fresh data.

todo

Manage current-session todos. Todos are branch-replayed from previous successful todo results in the current session branch.

Actions:

• create: add a todo, with optional description, owner, metadata, and blockers.
• update: change status, text, owner, metadata, or dependencies with blockedBy, addBlockedBy, and removeBlockedBy.
• list: list visible todos; deleted tombstones are hidden unless includeDeleted is true.
• get: fetch one todo by id.
• delete: tombstone one todo.
• clear: clear current todo state.

Examples:

{
  "action": "create",
  "subject": "Run README verification",
  "owner": "developer"
}

{
  "action": "update",
  "id": 1,
  "status": "in_progress",
  "activeForm": "verifying docs"
}

/todos

Show current-session todos grouped by status in interactive Pi UI. It reports pending, in-progress, and completed groups and requires interactive mode.

Example:

/todos

Above-editor todo overlay

Shows active session todos above the editor. The overlay rebuilds on session start, compaction, and tree switches, then updates after successful todo and task executions that affect todo state.

Completed todos remain visible until the next turn, then hide from the overlay.

task

Manage durable project tasks. Most durable task operations run from the current git project root; handoff_check resolves the root only when linked todos exist.

Read actions:

• doctor: check task-system health.
• find: find ready or open tasks. lane applies only to ready; use view: "tree" for an open-task tree. With view: "tree", task filters the tree to a parent task.
• show: show one task. Use with: ["spec"] to include spec content in the display.
• deps: show dependency tree for one task.
• notes: show notes for one task.
• similar: search for similar tasks by text.
• handoff_check: check whether current-session todos and linked durable tasks are ready for final handoff. Not-ready returns ok: true, ready: false; internal failures return ok: false.
• spec: operate on the spec attached to a task. mode is required and must be show, check, set, or update.
  • show returns the attached spec content.
  • check validates the attached spec against the task. Returns ok: true when validation passes; returns ok: false with error.code: "spec_check_failed" and diagnostics when validation fails.
  • set attaches a new spec using the text field. Overwrites any existing spec.
  • update updates the existing spec using the text field.
  • text is required for set and update; rejected for show and check.
  • show and check are read-only. set and update are mutations serialized through the per-project queue.

show with with:["spec"] vs spec action: show with with:["spec"] includes spec content as extra context in the task display — useful for reading the spec alongside other task fields. The spec action with mode:"show" returns spec content alone; spec action with mode:"check" validates the attached spec and reports pass/fail with diagnostics. Use show for display context, spec check for validation.

Failed check semantics: When spec check reports validation failures, the tool result has details.ok: false, error.code: "spec_check_failed", and a details.diagnostics object with the issues. The CLI process exits successfully (no thrown error); the failure is reported in structured details so agents can inspect and react to individual check failures without catching exceptions.

Handoff check semantics: handoff_check is read-only. It checks pending/in-progress/blocked todos plus linked durable task status. closed linked tasks are ready; open, in_progress, blocked, deferred, and unknown statuses block handoff; canceled is a warning. Missing/invalid linked tasks are reported as readErrors with ready:false.

Mutation actions:

• create: create a durable task, with optional description, under, planned, or needsPlan.
• note: add a note.
• finish: mark done.
• reopen: reopen a task.
• defer: defer a task.
• start: mark started.
• claim: assign ownership; start defaults to true, requireSpec enforces an attached spec, and todo: true creates one linked session todo.
• block / unblock: manage hard blocker edges.
• order / unorder: manage sequencing edges.

Lifecycle mutation actions:

• mark_planned: mark an existing task as planned. Requires task (non-empty id). Runs through the mutation queue.

Batch actions:

• bulk: run multiple lifecycle/note mutations sequentially with fail-fast semantics. Requires items — an array of { action, task, because? } objects. Supported item actions: start, finish, reopen, defer, note, mark_planned. because is required for note, optional for finish/defer. On first failure, remaining items are skipped. No rollback of completed mutations. Result details contain completed (task ids), optional failed (task + error), and skipped (task ids).
• create_tree: create a nested tree of durable tasks in one call. Requires root — a node object { title, kind, priority, description?, planned?, needsPlan?, children? }. Children are recursive nodes. Creates parent before children, wiring generated parent ids. On first failure, remaining subtree is skipped — no orphan children are created. No rollback. Result details contain created (id + title), optional failed (title + error), and skipped (titles).

Bridge actions:

• link: associate an existing todo with an existing durable task via todo metadata.
• list_links: inspect current todo ↔ durable task associations.
• promote: create a durable task from an existing todo, add a promotion note, link metadata, and complete the source todo.
• import: import a durable task, or an open-tree task plus children when available, into session todos with metadata links. to currently accepts only "todo".

Examples:

{ "action": "find", "tasks": "ready", "lane": "coding", "for": "developer" }

{ "action": "find", "view": "tree", "task": "task-parent" }

{ "action": "show", "task": "task-123", "with": ["spec"] }

{ "action": "spec", "task": "task-123", "mode": "show" }

{ "action": "spec", "task": "task-123", "mode": "check" }

{
  "action": "spec",
  "task": "task-123",
  "mode": "set",
  "text": "# Spec\n\nAcceptance criteria..."
}

{
  "action": "spec",
  "task": "task-123",
  "mode": "update",
  "text": "## Updated section\n\nRevised details..."
}

{ "action": "mark_planned", "task": "task-456" }

{
  "action": "bulk",
  "items": [
    { "action": "finish", "task": "task-1", "because": "Verified" },
    { "action": "start", "task": "task-2" },
    { "action": "mark_planned", "task": "task-3" }
  ]
}

{
  "action": "create_tree",
  "root": {
    "title": "Add auth module",
    "kind": "task",
    "priority": 2,
    "planned": true,
    "children": [
      {
        "title": "Design auth API",
        "kind": "task",
        "priority": 2,
        "needsPlan": true
      },
      { "title": "Implement token refresh", "kind": "task", "priority": 3 }
    ]
  }
}

{ "action": "handoff_check" }

{
  "action": "create",
  "task": "Add cwd guard tests",
  "kind": "task",
  "priority": 2,
  "under": "task-parent",
  "planned": true
}

{ "action": "block", "task": "task-child", "by": "task-blocker" }

{ "action": "order", "task": "task-later", "after": "task-earlier" }

{ "action": "link", "todo": 3, "task": "task-123" }

{
  "action": "promote",
  "todo": 4,
  "kind": "task",
  "priority": 2,
  "under": "task-parent",
  "for": "developer"
}

{
  "action": "import",
  "task": "task-123",
  "to": "todo",
  "for": "developer"
}

Task status footer

The status footer shows cached durable-task status in interactive UI:

• ready coding count
• ready planning count
• mine count for in-progress tasks assigned to pi
• loading, stale, and error states

It refreshes on session start, periodically, and after successful durable mutations from task.

The footer is display-only. Refreshed status is not injected into the model context; agents should use task for fresh durable task data. If agents claim with a non-pi assignee, those tasks may not appear in the footer's mine count.

Verification

Run full local verification before handoff:

npm run typecheck && npm test