# pi-native-todo

Native task planning and state tracking for Pi. Array-based, branch-replayable, and displayed in a live widget above the editor.

## Philosophy

- **One tool** — `todo` to read or replace the full task list
- **No IDs** — no numbering, no `nextId`, no `blockedBy`
- **No action verbs** — no `create`/`update`/`delete`. Pass the complete `tasks` array to set the list. Omit a task to remove it.
- **No background processes** — no polling, no watchers, no timers
- **No files** — state lives in `toolResult.details`, survives via session branch replay
- **Live widget** — shows the current todo list above the editor

## Install

```bash
pi install npm:pi-native-todo
```

Then restart pi or run `/reload`.

## Usage

### Read current todo list

```json
todo({})
```

### Replace the full todo list

```json
todo({
  "tasks": [
    { "content": "Do something", "status": "in_progress" },
    { "content": "Do something else", "status": "pending" }
  ]
})
```

### Clear all tasks

```json
todo({ "tasks": [] })
```

## Statuses

- `pending` — not started
- `in_progress` — actively working
- `completed` — finished

## Prompt guidelines

The tool injects guidelines that ask the agent to:

- Use todos only for non-trivial, multi-phase, dependent, or ambiguous work.
- Keep steps short, concrete, ordered, and easy to verify.
- Maintain exactly one `in_progress` task at a time.
- Move tasks through `pending` → `in_progress` → `completed` without skipping states.
- Update the plan immediately when the task structure changes.
- Finish with every task completed or explicitly removed.

## Development

```bash
npm install
npm run check
npm test
```

## License

MIT