OMPTS: Opinionated Modular Pi Todo System

A todo list for the Pi coding agent. It has two modes.

• Normal mode keeps a task list for one session.
• OpenSpec sync mode shows the tasks of one OpenSpec change. When the agent completes a task, the extension ticks the box in tasks.md and checks that OpenSpec agrees.

Why use it

• The panel counts every task, so hiding finished rows does not hide your progress.
• Stopped work shows Idle or Paused. It never looks like it is still running.
• A task is complete only when the box is written and OpenSpec confirms it.
• A stale or broken view is marked as stale. It never passes for current.
• /todos refresh redraws the panel without changing any task.

Install

pi install npm:om-pi-todo

Then run /reload in Pi. To install from GitHub instead, see the install guide. If you already use @juicesharp/rpiv-todo, read the install guide first. Both register a todo tool, so you must disable one.

Tell your agent how to use it

The todo tool already carries these rules in its own guidance. Add this block to ~/.pi/agent/AGENTS.md (or a project AGENTS.md) if your agent still skips them.

## Todo list (OMPTS extension)

- Use the `todo` tool for work with 3 or more steps. Set a task `in_progress` before you start. Set it `completed` the moment it is done.
- In OpenSpec sync mode, call `list` first. Work under the listed task ids. Do not copy plan tasks into new tasks.
- Pass `expectedRevision` when you change a linked task's status. Take it from the latest `list`, `get` or result.
- Complete a linked task only when its acceptance criteria are met. A ticked box is not proof that tests passed. Say what you ran and what it showed.
- For a temporary step outside the plan, use `scope: "incidental"` with a `reason`.
- Set `waitingReason` when you wait for an approval or a review. Set `failureReason` when work fails. Clear each with an empty string when it is resolved.
- If a result says a box was written but not confirmed, stop and tell the user. Do not repeat the completion.

Documentation

• How to install
• How to use
• How to uninstall

Requirements

• Pi 0.99.1 or newer. Tested on 0.99.1.
• Node.js 22 or newer.
• The openspec command on your PATH, for sync mode only. Tested with 1.13.1.

Pi supplies these host packages. The extension lists them as peers and ships no copy: @earendil-works/pi-ai, @earendil-works/pi-coding-agent, @earendil-works/pi-tui and typebox.

Develop

bun install
bun run setup:host   # fetches the Pi host packages into .pi-host/
bun run ci           # format check, lint, type check and tests

• bun run ci checks your working folder. bun run ci:clean checks a fresh clone of your last commit, which is what CI sees.
• git push runs bun run ci:clean first, through a Husky hook. Skip it once with git push --no-verify.
• GitHub Actions runs the same steps on every push and pull request.
• Contributor notes for agents are in AGENTS.md.

Release (maintainers)

Releases go to npm as om-pi-todo. Release Please prepares each one. You never edit the version or the changelog by hand.

1. Write commits and pull request titles in the Conventional Commits style: feat:, fix:, perf:, docs:. Add ! for a breaking change, for example feat!:.

2. Merge to main. Release Please opens or updates a pull request called "chore(main): release X.Y.Z". It bumps version in package.json and writes CHANGELOG.md.

3. Read that pull request. Check the version and the changelog text. Its CI checks run.

4. Merge it. Release Please tags the commit and creates a GitHub release.

5. The publish job runs the full gate on that exact commit, then stages the version on npm. It is not installable yet. The job adds the approval steps to the GitHub release.

6. Approve it with two-factor authentication:

   npm stage list om-pi-todo
   npm stage approve <stage-id>

   You can also use the Staged tab at https://www.npmjs.com/package/om-pi-todo. To reject a version, run npm stage reject <stage-id>.

What each commit type does before version 1.0.0:

One-time setup

No npm token is used. npm trusts the release workflow through OIDC. A trusted publisher can only be added to a package that already exists, so publish the first version by hand.

1. Publish the first version by hand, then tag it and create its GitHub release, so Release Please counts from it:

   npm login
   npm publish --provenance=false --access public --ignore-scripts
   git tag v0.1.0 && git push origin v0.1.0
   gh release create v0.1.0 --title v0.1.0 --notes-file CHANGELOG.md

2. Create a private GitHub App with no webhook. Give it read and write access to Contents and Pull requests. Install it on this repository only. Generate a private key. Save these repository secrets:

   gh secret set RELEASE_APP_ID
   gh secret set RELEASE_APP_PRIVATE_KEY < path/to/private-key.pem

3. Create the environment npm-publish, limited to the main branch. In GitHub, open Settings, Environments.

4. Add the npm trusted publisher. It needs npm 11.15 or later and asks for 2FA. The names must match exactly:

   npm trust github om-pi-todo --file release.yml --repo cmdaltctr/om-pi-todo --env npm-publish --allow-stage-publish
   npm trust list om-pi-todo

   --allow-stage-publish lets the workflow stage a version but not release it. You still approve every release.

5. Turn the workflow on:

   gh variable set RELEASE_PLEASE_ENABLED --body true

If the publish job fails with ENEEDAUTH, the workflow file name, the environment name or the repository in step 4 does not match npm's record. Nothing is published. Fix the setting and run the job again.

After the first staged release is approved and shows a provenance badge, open the package settings on npmjs.com and choose "Require two-factor authentication and disallow tokens".

If the smoke or gate step fails, nothing is staged. The tag and GitHub release already exist. Push a fix: commit. Release Please then proposes the next patch version.

Tooling you can copy

If you fork this project or start a similar Pi extension, set up the same checks. Each row says what it is for.

Three details that are easy to miss:

• Pi host packages. Pi supplies @earendil-works/* and typebox. List them as peerDependencies. Add peer = false to bunfig.toml, or bun install will copy them into node_modules and a Pi packaging check will complain. scripts/setup-host.sh fetches them into .pi-host/ for tests and type checks, so no path on your machine is hard-coded.
• Pin actions. Every action in the workflow uses a full commit SHA, not a tag.
• Test a clean clone. bun run ci can pass in your folder and fail in CI. bun run ci:clean removes that gap.

Licence and credit

MIT. See LICENSE.

This project began as a copy of @juicesharp/rpiv-todo 2.11.0 (MIT, copyright juicesharp). Each reused file and its hash are listed in NOTICE.md.