claude-do-it 0.1.1 → 0.1.3

package/README.md

@@ -1,5 +1,7 @@
 # claude-do-it
 
+[![CI](https://github.com/DomiR/claude-do-it/actions/workflows/ci.yml/badge.svg)](https://github.com/DomiR/claude-do-it/actions/workflows/ci.yml)
+
 **A Markdown todo that you and Claude edit at the same time.**
 
 You type in a browser editor. Claude reads the list, plans each task, hands it
@@ -9,6 +11,11 @@ on disk all merge instead of overwriting each other: every open file is one
 [Loro](https://loro.dev) CRDT held by a small daemon on your machine. The file
 itself stays plain Markdown, so any other editor still works on it.
 
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="docs/images/editor-dark.png">
+  <img alt="The do-it editor: a Markdown todo with tasks, tags, and the status lines agents write under each task" src="docs/images/editor-light.png">
+</picture>
+
 ```mermaid
 flowchart LR
   you["You<br/>browser editor"] <-->|"live sync"| daemon
@@ -27,9 +34,11 @@ flowchart LR
   on demand and stops after 30 idle minutes.
 - **The browser editor.** Built with Foldkit and CodeMirror 6. It keeps the
   todo as plain Markdown while showing a live PlainTasks preview with markers,
-  tags, actions, stamps, and a command palette. Task lines always stay
-  rendered: markers show as ☐ ✔ ✘ and links as their text, with a popover to
-  edit them.
+  tags, actions, stamps, and a command palette. Every line stays rendered
+  while you edit it: Markdown you type renders as soon as it is complete, a
+  formatting bar on top applies the same formats, task markers show as ☐ ✔ ✘
+  and delete like one character, and links show as their text with a popover
+  to edit them.
 - **The `/do-it` skill for Claude Code.** It turns a session into a conductor
   that sizes, plans, and delivers every task through worker agents and one
   shared tester.
@@ -38,9 +47,37 @@ flowchart LR
 
 Needs [Bun](https://bun.sh) 1.3 or newer on macOS or Linux.
 
+### As a Claude Code plugin
+
+In Claude Code:
+
+```
+/plugin marketplace add DomiR/claude-do-it
+/plugin install do-it@do-it
+```
+
+Or from a terminal:
+
+```bash
+claude plugin marketplace add DomiR/claude-do-it
+claude plugin install do-it@do-it
+```
+
+The plugin brings the skill and the `do-it` command, with nothing else to
+install. Claude Code puts the plugin's `bin` folder on its Bash tool's PATH,
+and the `do-it` there runs the published CLI of the same version through
+`bunx`, which downloads it on first use. A `do-it` you installed yourself comes
+first, so keep it as current as the plugin. Plugin skills carry the
+plugin's name, so the command is `/do-it:do-it`. The plugin's `do-it` exists
+only inside Claude Code: to run `do-it open TODO.md` in your own terminal, also
+install the CLI as below.
+
+### With the CLI
+
 ```bash
 bun add -g claude-do-it        # or: npm install -g claude-do-it (Bun still runs it)
 do-it skill install            # the /do-it skill, copied into ~/.claude/skills/do-it
+do-it doctor                   # checks Bun, PATH, the daemon, and the skill
 do-it --help
 ```
 
@@ -48,6 +85,15 @@ Run `do-it skill install` again after upgrading to refresh the skill. It never
 replaces a skill directory it did not create unless you pass `--force`.
 `do-it --skill` prints the skill, and `do-it skill path` shows where the
 package keeps it. To try it without installing, use `bunx claude-do-it open TODO.md`.
+Skip `do-it skill install` when you use the plugin: you would get the skill
+twice, as `/do-it` and `/do-it:do-it`.
+
+`do-it doctor` checks that Bun is 1.3 or newer, which `do-it` your PATH finds (a
+repo checkout, the global bun install, a bunx copy, or a global npm install),
+that a running daemon has this CLI's version and build, and that the installed
+skill matches the one this package ships. It prints one line per check and the
+exact command that fixes each problem, never starts the daemon, and exits 1
+when it finds a problem. `--skill-dir DIR` checks a skill installed elsewhere.
 
 The command is `do-it`, not `do`: `do` is a reserved word in bash and zsh.
 
@@ -70,12 +116,38 @@ ln -s "$PWD/skill" ~/.claude/skills/do-it                  # the skill, always c
 /do-it PLAN.md
 ```
 
-The browser opens on the todo. Add one task per line. The session sizes each
-task, plans it, starts a worker in its own worktree, and writes one status line
-under it, plus any question it needs you to answer (answer by writing under the
-question). Delivered tasks are checked off with their branch and test result.
-Inside Herdr (`HERDR_ENV=1`) the workers are Claude architects in Herdr
-worktrees and tabs with Codex lanes; elsewhere they are Claude Code subagents.
+With the plugin, the command is `/do-it:do-it` (for example `/do-it:do-it PLAN.md`).
+
+The browser opens on the todo (inside Sheprd, in a split beside the
+conversation). Add one task per line. The session is a conductor: it marks each
+task `@started` as soon as it picks it up, sizes it, and delegates the rest
+(planning, building, the single test queue, review, and answers to questions)
+to agents, watching them instead of doing the work itself. Each task gets one
+status line under it, plus any question it needs you to answer (answer by
+writing under the question). Delivered tasks are checked off with `@done`,
+their branch, and their test result. An optional messenger agent can write
+those lines for the conductor.
+
+Small tasks are planned by Opus and built by a Sonnet worker; medium ones use
+Opus for both. Large tasks use a stronger planner, reviewer, and model when the
+session finds one (an agent type or a CLI on PATH), otherwise Opus, and are always split
+into subtasks written under the task. The first subtask is `Review this task`:
+nothing is built until you check it off, and you can edit the other subtasks
+before you do.
+
+PlainTasks tags steer the work: `@critical`, `@high`, and `@today` go first,
+`@low` last, and `@due(date)` reaches the worker as a deadline. Agents never
+change your tags; `@started`, `@done`, and `@cancelled` come only from the
+`do-it todo` commands.
+The skill checks where it runs and starts workers there:
+
+| Where | Workers |
+| --- | --- |
+| Herdr (`HERDR_ENV=1`) | one Claude session per task in a Herdr worktree and space, started in the background |
+| [Orca](https://www.onorca.dev) | one Orca worktree per task, with Claude in a terminal of its own (`orca worktree create`, then `orca terminal create`) |
+| [T3 Code](https://github.com/pingdotgg/t3code), with its `t3` CLI | one T3 Code thread per task, in its own worktree (`t3 thread start --worktree`) |
+| super.engineering (formerly Superconductor), with its `sc` CLI | one super.engineering worktree per task with a Claude session working it, started in the background (`sc worktree create --background`) |
+| Any other terminal | Claude Code subagents in worktrees, which need nothing beyond Claude Code |
 
 Set `DO_IT_BROWSER` to the command that should open links, or to `true` to
 open nothing.
@@ -95,6 +167,7 @@ do-it diff TODO.md --since 9 --wait 300
 do-it watch TODO.md --todos           # or --settle 25 for one line per pause
 do-it status
 do-it stop
+do-it doctor                          # what is wrong with this install, and how to fix it
 ```
 
 ### How versions work
@@ -105,6 +178,14 @@ document has moved on, nothing is applied and the reply is the latest version
 plus a diff (exit 1). With `--section ID` a stale version still applies while
 that section is unchanged.
 
+`do-it watch TODO.md --settle 25` prints one `Settled at version N by WHO`
+line once nobody changed the document for 25 seconds. When the person's latest
+change adds a line (Enter at the end of a task or inside one), it settles after
+`--settle-line` seconds instead (2 by default), so a new todo reaches the agents
+at once. Every other change (typing, editing or deleting text, toggling a box)
+waits the full `--settle`. Set `--settle-line` to the `--settle` value to
+always wait the full period.
+
 A resumed watch that missed history prints
 `Missed changes, now at version N: run do-it read`. Use `--quiet` to skip the
 initial `Watching PATH at version N` line.
@@ -115,7 +196,7 @@ agent.
 | Exit code | Meaning |
 | --- | --- |
 | 0 | Done |
-| 1 | Refused, or version mismatch |
+| 1 | Refused, version mismatch, or a problem `do-it doctor` found |
 | 2 | Invalid arguments |
 | 3 | The daemon is not running and could not start |
 | 4 | Nothing changed yet |
@@ -132,10 +213,18 @@ agent.
 | Move up | `Cmd-Ctrl-Up` or `Alt-Up` | `Ctrl-Shift-Up` or `Alt-Up` |
 | Move down | `Cmd-Ctrl-Down` or `Alt-Down` | `Ctrl-Shift-Down` or `Alt-Down` |
 | Continue task | `Enter` | `Enter` |
+| Note under the task (folds with it) | `Shift-Enter` | `Shift-Enter` |
 | Expand a PlainTasks tag, or indent | `Tab` | `Tab` |
 | Outdent | `Shift-Tab` or `Cmd-[` | `Shift-Tab` or `Ctrl-[` |
 | Open link | `Cmd-Shift-U` or `Alt-Enter` | `Alt-Enter` |
-| Edit link (or click a link on a task line) | `Cmd-K` | `Ctrl-K` |
+| Edit link (or click a link) | `Cmd-K` | `Ctrl-K` |
+| Bold | `Cmd-B` | `Ctrl-B` |
+| Italic | `Cmd-Shift-I` | `Alt-Shift-I` |
+| Strikethrough | `Cmd-Shift-X` | `Ctrl-Shift-X` |
+| Inline code | `Cmd-E` | `Ctrl-E` |
+| Task line on or off | `Cmd-Alt-4` | `Ctrl-Shift-4` |
+| Bulleted line on or off | `Cmd-Alt-5` | `Ctrl-Shift-5` |
+| Project heading on or off | `Cmd-Alt-2` | `Ctrl-Shift-2` |
 | Go to project | `Cmd-P` | `Ctrl-P` |
 | Command palette | `Cmd-Shift-P` or `F1` | `Ctrl-Shift-P` or `F1` |
 | Find | `Cmd-F` | `Ctrl-F` |
@@ -150,7 +239,10 @@ There is one daemon per user. Any command starts it on demand; `do-it stop` or
 record, a per user token (mode 0600), the log, and the last version of each
 file, so version numbers survive restarts. It listens on `127.0.0.1:47100`
 (`DO_IT_PORT`) and only answers requests that carry the token or the browser
-cookie the `open` link sets.
+cookie the `open` link sets. The runtime record and `/health` also carry a
+build id (the npm build's id, or `source:` and the checkout path), which
+`do-it doctor` compares with its own. In a checkout that id names the
+checkout, not the revision, so after a `git pull` run `do-it stop` yourself.
 
 ## How it's built
 
@@ -173,12 +265,50 @@ in [docs/plan.md](docs/plan.md) and [docs/design.md](docs/design.md).
 
 ```bash
 bun run test                          # unit, daemon, and end to end tests
-bun run typecheck
+bun run check                         # typecheck (effect-tsgo tsc)
+bun run lint                          # Oxlint with the Effect rules
+bun run format                        # oxfmt (bun run fmt:check only checks)
 bun run build:web
 bun run build:npm                     # the npm package, in dist/npm
 bun --cwd packages/web run dev        # editor with a proxy to the daemon on 47100
 ```
 
+CI runs the typecheck, lint, format check, tests, and both builds on every push
+and pull request.
+`claude plugin validate . --strict` checks the plugin and marketplace manifests.
+
+### Release
+
+Set `APP_VERSION` in `packages/protocol/src/index.ts` (the npm package takes its
+version from it), and the same version in `.claude-plugin/plugin.json` and in
+the pinned `claude-do-it@` version in `bin/do-it` (`tests/plugin.test.ts` checks
+that the three match). Add a section for the new version at the top of
+`CHANGELOG.md`. Commit to `main`, then tag and push:
+
+```bash
+git tag vX.Y.Z && git push origin vX.Y.Z
+```
+
+The Release workflow checks that the tag equals `v` plus `APP_VERSION` and the
+`version` in `.claude-plugin/plugin.json`, runs the CI checks, builds
+`dist/npm`, and publishes it to npm with trusted publishing (OIDC), which adds
+provenance itself. No `NPM_TOKEN` secret is needed. The job has
+`id-token: write`, runs on a GitHub-hosted runner, and installs the latest npm
+first, because trusted publishing needs npm 11.5.1 or newer. The plugin's
+`do-it` runs that exact npm version, so a plugin installed from `main` fails
+until the workflow has published it: push the tag right after the commit.
+
+One time setup on npmjs.com, as the `domir` account: open the package
+`claude-do-it`, then Settings, Trusted Publisher, and choose GitHub Actions.
+Enter the organization or user `DomiR`, the repository `claude-do-it`, and the
+workflow filename `release.yml` (the filename only, with the extension), and
+leave the environment empty. Under allowed actions, tick `npm publish`: the
+workflow publishes directly. The fields are case sensitive, npm does not check
+them when you save, and a new configuration must finish its first successful
+publish within two days. A wrong value shows up only as a failed publish.
+Afterwards, set Publishing access to "Require two-factor authentication and
+disallow tokens".
+
 ## Acknowledgements
 
 The editor's notebook colours, PlainTasks markers, tag completions, stamps, and