From 61897fefe50b1b2dadb940c3f29bb8926f948d6d Mon Sep 17 00:00:00 2001 From: James Macfie <1654201+jamesmacfie@users.noreply.github.com> Date: Wed, 10 Jun 2026 16:04:11 +1200 Subject: [PATCH] docs: update readme with usage details --- README.md | 104 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 104 insertions(+) diff --git a/README.md b/README.md index e52d0a3..62e6887 100644 --- a/README.md +++ b/README.md @@ -4,6 +4,110 @@ ![screenshot of slack](./example.png) +## Usage + +The bot is driven entirely from Slack. There are two ways to interact with it: + +1. **Posting handover items** — write a normal message in the handover channel. +2. **Running commands** — `@mention` the bot followed by a command. + +### Posting a handover item + +Any message you post in the handover channel becomes an item in your handover +post for the day. The bot keeps your published handover in sync with what you +write: + +- **Edit** one of your messages and the corresponding item is updated. +- **Delete** one of your messages and the item is removed. + +#### Backdating an item + +Prefix a message with a relative date in parentheses to file it against a +previous day instead of today: + +| Prefix | Meaning | +| ------------------ | ---------------------------------------- | +| `(today): …` | Today (the default if no prefix is used) | +| `(yesterday): …` | The previous day | +| `(2 days ago): …` | _N_ days before today | +| `(1 day late): …` | _N_ days before today, flagged as late | + +Items filed against an earlier day with `… days ago` / `… days late` are shown +in the handover with a `(N days late)` note. + +### Commands + +Commands are issued by `@mention`-ing the bot and then typing a CLI-style +command, for example: + +``` +@handover remind --at 09:30 +``` + +Arguments are parsed like a shell, so wrap values containing spaces in quotes. +Run any command (or sub-command) with no arguments, or pass `--help`, to see its +usage. Command responses are sent to you privately so they don't clutter the +channel. + +#### `remind` — set your daily reminder + +Control when the bot reminds you to post your handover. Reminders are only sent +on your configured workdays. + +| Command | Description | +| ----------------------------- | --------------------------------------------------- | +| `@handover remind` | Show your current reminder time | +| `@handover remind --at 09:30` | Set the time of day (`HH:MM`) to be reminded | + +If you never set a time, the default of `17:00` is used. (`-t` is shorthand for +`--at`.) + +#### `workdays` — choose which days you're reminded + +| Command | Description | +| ------------------------------------------ | ------------------------------------ | +| `@handover workdays` | Show your current workdays | +| `@handover workdays on Monday Tuesday` | Turn reminders on for the given days | +| `@handover workdays off Friday` | Turn reminders off for the given days | + +Days are case-insensitive and accept `Monday` through `Sunday`. The `on`/`off` +commands accept one or more days at a time. + +#### `history` — review past handovers + +Fetch a private copy of your previous handover posts. + +| Command | Description | +| ------------------------------------ | ---------------------------------------- | +| `@handover history` | Show the last 7 days of handovers | +| `@handover history --days-before 14` | Show the last _N_ days (maximum 30) | + +(`-d` is shorthand for `--days-before`.) + +#### `format` — customise how handover text is rendered + +Formats are regular-expression find-and-replace rules applied to **everyone's** +handover items when they are rendered. They're useful for turning shorthand into +links, emoji, or richer formatting. Each rule has a unique `id` so it can be +updated or deleted later. + +| Command | Description | +| -------------------------------------------------------- | ------------------------------------ | +| `@handover format` / `@handover format list` | List all formats | +| `@handover format set ` | Create or update a format | +| `@handover format delete ` | Delete a format | + +- `` is a JavaScript regular expression (e.g. `/PR-(\d+)/g`). +- `` is the replacement string and may reference capture groups + (e.g. `$1`). +- Add a human-readable note with `-d` / `--description`. + +For example, to turn `PR-123` into a link: + +``` +@handover format set pr-link "/PR-(\d+)/g" "" --description "Link PR references" +``` + ## Prerequisite Make sure you have pnpm installed globally. If not, run the following command: