From 0d7ef0d26be025cafa9ee21e37b88b093272ac9f Mon Sep 17 00:00:00 2001 From: Andrii Pasichnyk <67899666+pasichDev@users.noreply.github.com> Date: Sun, 4 Oct 2026 21:29:19 +0300 Subject: [PATCH 1/2] docs: add 3.1 workflow guide --- docs/3.1.md | 200 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 200 insertions(+) create mode 100644 docs/3.1.md diff --git a/docs/3.1.md b/docs/3.1.md new file mode 100644 index 0000000..6f40ee5 --- /dev/null +++ b/docs/3.1.md @@ -0,0 +1,200 @@ +# Docket 3.1 + +Docket 3.1 turns the shared agent todo list into a small work console. + +The core loop is still deliberately simple: capture work from any MCP-capable agent and keep it visible across projects. Digests add a layer above that list: an agent can read the tools where work already lives, publish one verified snapshot, and hand any item back to an agent by number. + +## The 3.1 workflow + +```text +GitHub / GitLab / Notion / git / mail / chat / files + │ + ▼ + docket:digest + │ + ▼ + Docket dashboard home page + │ + ┌──────────────┼──────────────┐ + ▼ ▼ ▼ + what changed needs you shipped + │ + ▼ + #7 / D-XXXXXX/7 + │ + ▼ + "take 7" + │ + ▼ + digest_take + │ + ▼ + claimed Docket task + │ + ▼ + todo_complete(id, reason) +``` + +The important boundary is intentional: **Docket does not log in to GitHub, GitLab, Notion, Slack, Gmail, or another work system.** Your agent reads those sources with the tools and credentials it already has. Docket stores only the digest the agent publishes. + +## Try it + +Install or update: + +```sh +npx -y @pasichdev/docket setup +``` + +If you already use Docket 3.0, 3.1 upgrades in place. There is no todo-store format migration in this release. + +Install the Docket skill for Claude Code: + +```text +/plugin marketplace add pasichDev/docket +/plugin install docket@docket +``` + +Then ask: + +```text +make a digest +``` + +or, for example: + +```text +make a digest for the last 7 days +``` + +The `docket:digest-setup` skill can detect available sources and write the local configuration in: + +```text +~/.config/docket/digest.json +``` + +Open the dashboard: + +```text +http://localhost:8787 +``` + +The home page now shows the latest digest. The ordinary task list lives at `/tasks`. + +## Hand work to an agent + +Every published digest item receives a number. + +If the dashboard shows: + +```text +#7 Fix failing release workflow +``` + +you can tell any connected agent: + +```text +take 7 +``` + +or copy the stable handle: + +```text +D-7K2F9A/7 +``` + +The agent calls `digest_take`, receives the full item brief, and gets a Docket task claimed in its name. If the digest item already corresponds to a Docket task, Docket reuses it instead of creating a duplicate. + +When the work is finished, the agent closes it with: + +```text +todo_complete(id, reason) +``` + +The reason is kept with the task history, so a hand-off ends with an explanation rather than a disappearing checkbox. + +## What changed since the previous digest + +Docket compares two published digests by item identity and computes: + +- newly listed work; +- status changes such as `open → merged`; +- items no longer listed. + +This comparison is produced by Docket itself when the digest is stored. It is not based on the agent remembering what it wrote last time. + +That gives the dashboard a useful first question: **what actually moved?** + +## Owners and depth + +Digest items can carry an `owner`: + +- `you`; +- `agent`; +- a person from the configured `people` list. + +The dashboard can group the next actions by person. + +Routine items stay compact. Important blocked, failing, stale, or decision-heavy items can include a Markdown `detail` field with the deeper analysis. + +## Seen items + +Marking an item **seen** hides routine noise without losing state. + +A seen item stays out of later digests while its status remains unchanged. If that status moves, for example an open pull request merges, it becomes relevant again. + +Seen marks are stored and synchronized alongside digests. + +## Sources + +Built-in digest workflows cover work from: + +- GitHub pull requests and issues; +- GitLab merge requests and issues; +- Notion; +- local git repositories; +- Docket tasks; +- Obsidian; +- project files; +- mail and chat through connected MCP tools. + +Additional read-only MCP sources can be configured for systems such as Jira, Linear, YouTrack, Sentry, Slack, or another server the agent can query. + +Source failures are part of the digest rather than silently ignored, so a snapshot can say that one area could not be checked. + +## Local and self-hosted + +Digests work in both deployment modes. + +### Local Mode + +Digests are stored in `digests.json.enc` and can sync between paired devices. They use their own cursor and sequence space, separate from todo synchronization. + +### Self-hosted Mode + +Clients publish and read digests through the Docket Server. All paired clients see the same digest state immediately through the server rather than waiting for peer synchronization. + +## Daily digests + +Digest configuration can define a daily schedule. The skill can offer a macOS LaunchAgent or Linux user timer for a headless run. + +The schedule is opt-in. Docket does not silently install background jobs. + +The Claude Code SessionStart hook can also show a one-line summary of the newest digest and suggest creating a fresh one when it is old. + +## Useful commands and tools + +| Action | Command / tool | +|---|---| +| Setup Docket | `npx -y @pasichdev/docket setup` | +| Open dashboard | `docket web` | +| Configure digest sources | `docket:digest-setup` skill | +| Build a digest | `docket:digest` skill | +| Publish from an agent | `digest_publish(...)` | +| Read latest/recent digests | `digest_list`, `digest_get` | +| Give item 7 to an agent | `digest_take("7")` | +| Read seen-state | `digest_seen()` | +| Finish handed-off work | `todo_complete(id, reason)` | + +For the full data shape, configuration options, storage and sync behavior, see [Digests](digests.md). + +For the complete release history, see the [changelog](../CHANGELOG.md). From 0ad3a0e3569c2e8af9d8f1e46c114c36ddb082db Mon Sep 17 00:00:00 2001 From: Andrii Pasichnyk <67899666+pasichDev@users.noreply.github.com> Date: Sun, 4 Oct 2026 21:29:31 +0300 Subject: [PATCH 2/2] docs: surface 3.1 digest workflow --- README.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/README.md b/README.md index 42afe70..543af97 100644 --- a/README.md +++ b/README.md @@ -44,6 +44,21 @@ this exact copy of docket and tells you it did — but the short form survives moving or reinstalling, and `npx` leaves nothing on `PATH`. + +## What's new in 3.1 + +Docket 3.1 adds **digests**: an agent can read the work you already have in GitHub, GitLab, Notion, git, mail, chat and other configured sources, verify the current state, and publish one snapshot to the dashboard. + +The useful loop is short: + +```text +make a digest → see what changed → copy #7 → tell an agent "take 7" → task is claimed → close with a reason +``` + +Digests also add owners, deeper per-item analysis, seen-state, "what changed" between snapshots, issue support, configurable MCP/file sources, daily headless runs, and the same behavior in Local and Self-hosted modes. + +**Start here:** [Docket 3.1 workflow guide](docs/3.1.md) · [Full digest reference](docs/digests.md) · [3.1 changelog](CHANGELOG.md#310) + ## Why A thought that shows up mid-session is worth capturing but not worth the