@timqi/pier 0.1.3 → 0.1.4

package/skills/pier-slack/SKILL.md

@@ -1,88 +1,69 @@
 ---
 name: pier-slack
-description: Read and write Slack through Pier's slack tool, including the Slack-specific syntax for mentions and links. Read before answering questions about Slack conversations or posting anything to a workspace.
+description: Slack from the shell with `pier slack` — read, post, edit, files — and Slack's mention syntax. Read before reading or posting to Slack.
 ---
 
-# Writing Slack correctly
+# Slack from the shell
 
-The tool description lists the operations and parameters. This is what goes
-wrong without instructions.
+`pier slack --help` lists the subcommands (`whoami`, `channels`, `user`,
+`history`, `thread`, `message`, `permalink`, `file`, `upload`, `post`,
+`edit`, `delete`, `react`) and their flags. There is no Slack tool. The token
+is the vault's (`SLACK_TOKEN`); an `approve`-level one may pause the command
+until the operator approves. A `vault:` line is the pier-vault skill's.
 
-## Markdown is not Slack syntax
-
-`text` is **standard markdown** and Slack renders it natively: `**bold**`,
-`_italic_`, `` `code` ``, fences, headings, lists, tables, blockquotes. Never
-hand-convert to the older mrkdwn `*bold*` — it renders literally.
+Where you are: the first speaker header ends `slack:<channel>/<thread_ts>`;
+without it, name a channel explicitly.
 
-Four things markdown cannot express:
-
-| Intent | Write | Not |
-| --- | --- | --- |
-| Mention a person | `<@U04B7Q2>` | `@alice` — plain text, pings nobody |
-| Link a channel | `<#C0123456>` | `#general` — plain text |
-| Notify the channel | `<!here>`, `<!channel>` | `@here` — plain text |
-| Hyperlink | `[label](https://…)` | — |
+- `<channel>` is an id, `#name`, or a pasted message link, which also
+  supplies `<ts>` and the thread: `thread <link>`, `post <link> "text"`.
+- Times: ISO 8601 (naive = local), epoch seconds, or a `ts`. `--after` is
+  strictly newer; the transcript header's `last <ts>` is your next `--after`.
+- A wide range belongs on disk: `history … --threads --out raw.txt`, then
+  read pieces. `--json` is for scripts, not for you.
+- 11 000 chars per message; split across replies in one thread.
+- Slack's failures are one `slack: <method>: <code>` line: `not_in_channel` →
+  someone `/invite`s the bot; `channel_not_found` → see `channels`;
+  `missing_scope` → the operator reinstalls the app (on `channels` it means no
+  `im:read`/`mpim:read`; ids still work); `cant_update_message` → not yours.
+  Pier's own checks are `slack: channel|ts|time|user: <why>`.
 
-- **Never guess an id from a name.** A wrong `<@U…>` fails or pings a stranger,
-  and both look like it worked. With no id, write the person's name as prose.
-- **You already have the ids** — the sender header on the message you are
-  answering, `name[id]` on every transcript line, `context` for this channel and
-  thread. Asking a human to paste their own user ID is never acceptable.
-- Escape `&` `<` `>` when they are text, not markup: `&amp;` `&lt;` `&gt;`.
-- Emoji as `:white_check_mark:`, not the raw glyph.
-- 11,000 chars per message; the tool refuses longer `text`. Split longer
-  content across replies in one thread rather than truncating.
+## Transcript format
 
-## Targeting
+```
+# C079TC7GUBG 2024-06-01 00:00 → now · +0800 · 41 messages · last 1717.000400
+09:12 ada: the db is on fire [thread 3 · 1717.000100] [file log.txt F1 2KB]
+  09:14 bob: restarting it [edited] [:eyes: 2]
+```
 
-- Omitting `channel`/`thread_ts` means "here" — the conversation that reached
-  you. `context` names it; `inSlack:false` means a task, subagent or web session
-  started this, so `channel` is required.
-- `channels` lists what Pier can reach; an id or a `#name` works anywhere a
-  channel is wanted.
-- `thread_ts:"none"` is the only way to a new top-level message — a channel's
-  main flow is wider than a thread. A `thread_ts` is never inherited across a
-  change of `channel`.
-- A `ts` means nothing outside the conversation it was read in, and `edit` /
-  `delete` always take it explicitly — no default from the thread you are in.
+A date line when the day changes; replies indented under `--threads`.
+Markers: `[edited]`, `[thread N · <ts>]` on a parent, `[in thread <ts>]` on
+a reply met in the channel, `[file <name> <F…> <size>]`, `[:emoji: N]`,
+`[attachment: t]`/`[blocks]` for empty text. `--ts` prefixes each line with
+its `ts` (what `thread`, `edit`, `--after` take); `--ids` renders `name[id]`.
 
-## Reading
+## Markdown is not Slack syntax
 
-- A channel read returns thread **parents** only; `[thread: N replies]` marks
-  the ones worth a `read_thread`.
-- `read_message` also needs `thread_ts` when the message was posted inside a
-  thread — a channel read cannot see thread replies.
-- The leading `ts` on a line is Slack's id: pass it back as `thread_ts` or
-  `after`. `after` is strictly newer, for re-reading without seeing what you
-  already saw.
-- `truncated` → narrow the range rather than raising `limit` (default and max
-  400). `incomplete` → the read stopped early for the reason given; work with a
-  partial answer, but never report it as everything.
-- Resolve a vague time ("yesterday") to an explicit ISO range and say which
-  range you used.
+`text` is standard markdown (never mrkdwn `*bold*`). Beyond it:
 
-## Files
+| Intent | Write | Not |
+| --- | --- | --- |
+| Mention a person | `<@U04B7Q2>` | `@alice` — pings nobody |
+| Link a channel | `<#C0123456>` | `#general` |
+| Notify the channel | `<!here>`, `<!channel>` | `@here` |
+| `& < >` as text | `&amp; &lt; &gt;` | |
 
-`[file: <name> <F… id> <size>]` on a line is an upload, never its bytes.
-`fetch_file` with that `F…` id (no `channel` needed) saves it and replies with a
-marker line — `[postmortem.pdf](file:///…)` — so you read it only if the
-question needs its contents. Over 32 MB or refused by Slack: `[attachment lost:
-<name> — <reason>]`.
+**Never guess an id**: a wrong `<@U…>` pings a stranger. Ids come from the
+speaker header, `--ids` or `user`; never ask a human for theirs.
 
 ## Rules
 
-- Read before you write. A summary of the wrong thread is worse than none.
-- **In a busy thread, say nothing unless you are needed.** You are handed every
-  message, including humans talking to each other. `<silent>why</silent>` sends
-  nothing at all — prefer it to acknowledging what was not addressed to you.
-- `edit` replaces `text` outright; read the message first if you are changing
-  part of it. Slack keeps no version a reader can open and may not mark the
-  message as edited, so when the previous wording mattered to people, say what
-  changed instead of quietly rewriting history. A running status or tally is
-  better as one message edited in place than one message per change.
-- `delete` cannot be undone, and deleting a thread parent leaves its replies.
-  Say what you removed; a message vanishing with no word looks like a bug.
-- Never post credentials, tokens or file contents you were not asked to share:
-  a channel is usually wider than the conversation you are in.
-- "Slack agent access is switched off" means the operator disabled it on
-  purpose. Say so and stop; do not look for another route.
+- **Reply in the thread you were reached in** (`--thread <thread_ts>`); a
+  top-level post is a stated choice.
+- **Edit and delete only what you posted** (`whoami`); `edit` replaces the
+  whole text, `delete` has no undo.
+- **Your reply is itself a new message** in this thread — even a `<silent>`
+  turn posts one muted footer line — so you cannot leave the thread with none
+  of your messages; say so once.
+- **In a busy thread say nothing unless needed**: `<silent>why</silent>`.
+- Never post credentials or file contents you were not asked to share: a
+  channel is wider than this conversation.

package/skills/pier-tasks/SKILL.md

@@ -1,170 +1,73 @@
 ---
 name: pier-tasks
-description: Delegate work to Pier subagents with the task tool — one-shot, parallel fan-out, chains, mid-run control. Read before delegating to a subagent, coordinating agents, or running long background work.
+description: Subagents and scheduled tasks with `pier task`. Read before delegating work, coordinating agents, or scheduling anything.
 ---
 
 # Pier tasks
 
-## Delegate, then wait
+`pier task --help` lists the five commands and their flags. Each prints one
+JSON receipt, exit 0; a refusal is a `task:` line, exit 1 (`--model` with no
+or several hits lists the menu under it); a bad flag is `task:` plus the
+usage, exit 2. `--prompt -` reads stdin.
 
-```json
-{"operation":"run","prompt":"Review src/auth/*.ts. Return file:line, issue, fix."}
-```
+## Delegate, then end your turn
 
-One concern per child. `run` with `prompt` or a full `task` draft atomically
-creates a persisted one-shot (`kind:"subagent"`, hidden from `list`); do not
-`create` it. Name defaults to the prompt's first line; `name` overrides it.
-
-All operations return immediately. Results and decision replies arrive by
-callback; **end your turn after launching work**. Default callbacks are system
-follow-ups, batched when several are due. A long turn delays them; there is no
-status query. The receipt's `next` tells you where/how delivery happens:
-
-- `callback:"origin"` (default): result returns to you after your turn.
-- `callback:"steer"`: interrupts at a step boundary; use when needed mid-turn,
-  not for work you launch and forget. Receipt echoes `callbackMode`.
-- `callback:"none"`: no delivery; means you do not want the result, not pull later.
-- Single-run `callback_session_id`: deliver to another existing session.
-  Top-level sessions only, and never with `callback:"none"` or `tasks[]`;
-  inside a run it is refused, so your result always returns to you.
-
-Receipts include `runId`, `taskId`, state. Keep IDs: the callback also names
-`Run:`, and there is no lookup by task. `triggerSource` names the actual invoker
-(`agent/manual/cron/watch/task`); the definition's `trigger` is scheduling
-policy (`manual` means on demand).
-
-## Sessions and prompts
-
-- Default `fresh`: clean context. `cwd` defaults to your directory, accepts an
-  absolute path or one relative to yours, and must exist.
-- `reuse`: existing session by `sessionId`; continues its history after it is
-  idle. `launch` applies only to fresh sessions; reused sessions own their
-  model/tools. Children otherwise have your tools, including `task`.
-- **The prompt is the handoff**: no implicit copy of your discussion. Include
-  the goal, current decisions, latest constraints, absolute paths, acceptance
-  criteria, verification and output format. `input` accepts any JSON, appended
-  in `<task_input>`.
-- For more work on an existing result, `resume` that run with a delta prompt;
-  its session/context survives. Start fresh for unrelated work or stale context.
-- Stored role: `run` with `task_id` and optional `input`;
-  `session_mode:"fresh"` overrides a stored reuse policy. Archived tasks refuse.
-
-`timeoutSeconds` also works in the shorthand and in a `tasks[]` entry; use a
-`task` draft for reuse:
-
-```json
-{"operation":"run","task":{"timeoutSeconds":7200,"action":{"type":"agent","session":{"mode":"reuse","sessionId":"..."},"prompt":"Check the result"}}}
+```sh
+pier task run --prompt "Review src/auth/*.ts. Return file:line, issue, fix."
 ```
 
-Inline drafts may omit `trigger`; only `manual` is allowed. A nested
-`callback` is refused: use the top-level delivery options above. Nested
-callbacks matter for saved schedules (below).
-
-## Groups and chains
+The prompt is the whole handoff (goal, constraints, absolute paths, output
+format); the child sees nothing of your conversation. `--cwd` defaults to
+yours; `--timeout` (default 3600 s) starts when the run does.
 
-`tasks[]` needs 2+ entries: prompt strings,
-`{prompt,cwd?,launch?,name?,timeoutSeconds?}`, full drafts, or `{task_id}`. Do not combine it with `task`, `task_id` or `session_mode`.
-
-```json
-{"operation":"run","tasks":["Review correctness","Review test gaps"],"join":"all"}
-```
+**Callbacks are the only delivery; there is no status query.** The result
+arrives as a system message once your turn ends, so **end your turn after
+launching** — never poll. Keep the receipt's `runId`; the callback names
+`Run:`. `--callback steer` interrupts your running turn instead; `none`
+drops the result; `--callback-session <id>` delivers elsewhere.
 
-- `join:"all"` (default): one callback with every member's name, state and result
-  when all are terminal.
-- `join:"first"`: first **any terminal state**, including failure/overlap skip,
-  wins. Others are cancelled; their sessions remain resumable, IDs in callback.
-- Core owns the join; never hand-aggregate member IDs across turns. Members have
-  no individual callbacks; `none`/`steer` applies to the group. `cancel` and
-  `recover` accept `group_id`. Admission failure (e.g. limit or missing cwd)
-  rolls back the group: nothing runs.
+| Flags | Run |
+| --- | --- |
+| `--task-id <id>` | a saved definition, as is |
+| `--session <id> --prompt …` | continue an idle session (it keeps its cwd and model) |
+| `--run <id> --prompt …` | existing run: running → steer; `--after` → after its turn; finished → resume (`--callback*` apply only then). The receipt's `delivery` says which |
+| `--member --prompt … --member …` | batch: flags before the first `--member` are defaults, ≥2 members, `--join all` (default) or `first`; the callback is the group's |
 
-For a chain: launch step 1 → end turn → receive callback → put needed results
-in step 2's self-contained prompt. Branching and retries are your responsibility.
+A child that needs your answer ends its turn with the question as its result;
+answer it with `--run <id> --prompt`. Core owns the join: never aggregate
+members by hand.
 
 ## Model choice
 
-Default: inherit your current model. For harder reasoning, raise
-`launch.thinking` first (`off/minimal/low/medium/high/xhigh/max`). For cheap bulk
-work, choose the same provider's smallest current model with low/off thinking;
-for an independent vendor's opinion, choose its flagship.
+Default: your model. Harder reasoning: `--thinking` first
+(`off/minimal/low/medium/high/xhigh/max`). `--model <name>` is matched
+against the operator's menu (substring of provider, id or note — "let gpt
+review it" is `--model gpt`); none or several hits lists the pins, pick one.
+`--model ?` prints the menu. Never name a model id from memory.
 
-Before naming a model, call `{"operation":"models"}`; never use IDs from memory.
-It returns operator pins (`source:"menu"`, intent notes/usual thinking) or the
-live catalog (`source:"catalog"`). Prefer a matching pin and its thinking level.
-`launch.model` overrides inheritance. Unknown model IDs fail the run and report
-available IDs by callback; invalid `launch.thinking` fails the call.
+## Cancel · recover
 
-## Control and decisions
+`pier task cancel --run <id> | --group <id>` — the runs you launched.
 
-`message` must be non-empty, at most 16 KiB. Controls require ownership: your delegated
-trees, or only descendants when you are a subagent.
+`pier task recover (--run <id> | --group <id>) --reason <text>` — the full
+result after its callback settled, for text truncated (8000 chars; 2000 per
+member) or lost to compaction. **Never to check progress**: the refusal
+reveals no state.
 
-- `steer`: interrupt a child with corrections.
-- `follow_up`: queue guidance after its current turn.
-- `resume`: terminal run only; same session, new run ID/callback, same depth,
-  message as prompt. Expires its unanswered decision. Being a new run, it takes
-  the same `callback` and `callback_session_id` as `run`, under the same rule:
-  a subagent may not redirect them.
-- `cancel`: run or group; cascades to descendants, terminal runs unchanged.
+## Saved definitions
 
-`steer`/`follow_up` require a non-terminal run; undelivered guidance expires when
-it ends. For finished work use `resume`.
-
-Child → supervisor:
-
-```json
-{"operation":"contact","reason":"decision","message":"Use API A or B?"}
+```sh
+pier task save --name nightly --bash "make check" --cwd /repo --cron "0 3 * * *" --tz UTC
 ```
 
-Requires an active delegated Agent run with a supervisor (scheduled cron/watch
-runs have none). `progress` is fire-and-forget; `decision` steers the supervisor
-and permits one open question per run. State what you await and **end your
-turn**, never spin/poll. A finished run with an open question suppresses its
-completion callback: the question is the notification.
+Only for schedules or roles run more than once; `--task-id` updates. A
+schedule's results reach nobody unless `--callback-session <id>` names a
+session; `pier task list` shows definitions, never runs.
 
-Supervisor → child:
-
-```json
-{"operation":"reply","message_id":"...","message":"Use API A"}
-```
+## Limits
 
-Only the addressed supervisor may reply. Same text twice is a no-op; different
-text errors. The answer steers an active child or auto-resumes a terminal one
-with the reply as prompt; the continuation's callback returns to the replier.
-
-## Recover lost information only
-
-`recover` requires `run_id` or `group_id` plus `reason` (e.g. text truncated,
-context lost to compaction). **Never use it to check progress.**
-
-- Run must be terminal and its callback settled: delivered, abandoned, or none.
-  Group members wait for their group callback; a terminal race winner is
-  readable while losers are still cancelling.
-- Whole-group recovery additionally requires every member terminal. An open
-  decision directs you to `reply`. Other premature requests get a refusal
-  that reveals no state.
-- Callbacks truncate each result at 8000 characters; recovered groups truncate
-  member results at 2000. Notes point to `recover run_id`, which returns full
-  text. `none` remains a no-result preference, not a polling workflow.
-
-## Persistence and limits
-
-`create` files an operator-visible definition only for recurring roles or
-cron/watch schedules; the operator must archive it. `update` takes the entire
-draft, including `trigger`. Schedules notify only with nested
-`callback:{"type":"session","sessionId":"..."}`; `origin` needs an invoker,
-which scheduled runs lack.
-
-- Inside a run: Agent actions only (stored/inline), no reuse or create/update.
-- Depth 0–2: three levels of nesting below the invoking session; a fourth
-  level errors. Each root allows 16 descendant runs (depth ≥1, resumes included). Your direct
-  children are separate roots and do not count toward that limit.
-- 6 Agent runs execute instance-wide; others queue without error. A queued run
-  waits **unbounded**, ended only by cancellation or a restart.
-- Default timeout 3600s; `timeoutSeconds:1–86400` in a draft, the `prompt`
-  shorthand or a `tasks[]` entry. It starts when the run does, not at enqueue,
-  and reports `failed / task timed out`.
-- Restart marks queued/running runs `interrupted`; callbacks still apply.
-  During drain, new roots are refused: retry after restart.
-- Watch probes that matched nothing are kept only 50 deep per watch; older
-  ones are deleted unless a message, a pending callback or a resume needs them.
+- A delegated run does not delegate: `pier task` is refused inside a run
+  someone waits on — ask in your result; your supervisor runs it.
+- 6 agent runs execute at once instance-wide; the rest queue until cancelled
+  or a restart marks them `interrupted` (callbacks still fire).
+- During a restart drain new runs are refused: retry after.

package/skills/pier-vault/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: pier-vault
+description: Run a command with a named vault secret via `pier vault run`, never seeing the value. Read before anything needing a token, key or password, or on a `vault:` error.
+---
+
+# Pier vault
+
+```
+pier vault run SLACK_BOT_TOKEN=SLACK_TOKEN -- ./fetch_weekly.py --out raw/weekly
+```
+
+`ENV=NAME` puts the secret `NAME` into the command's environment as `ENV`;
+`NAME` alone is `NAME=NAME`; list as many as needed. Everything after `--`
+runs as is (same cwd and stdio, its exit code is yours). Use the name a
+skill gives you; never invent one.
+
+- **No value is ever printed** — not by `pier vault run`, not by you: no
+  `echo`, log line, file or config. The command reads its environment.
+- **No workaround for a missing secret**: you cannot obtain the value another
+  way; ask the operator with the link from the error.
+- **`approve` secrets may pause**: every use asks the operator through `vt`
+  and the command waits. Say so when a step may sit waiting; do not retry in
+  a loop.
+
+## When it fails
+
+One stderr line, exit 2, the command did not run.
+
+| stderr | Do |
+| --- | --- |
+| `vault: no secret named X — file it at <link>` | Stop. Give the operator that exact link (it opens the Console with the name filled in); the value goes there, never to you. |
+| `vault: locked — <reason>` | The operator unlocks Pier's key store (Console → Settings → Security). Nothing you run helps. |
+| `vault: vt is required for X (approve level) and was not found` | `vt` is not on PATH here. Tell the operator; you cannot change the level. |
+| `pier: Pier is not running (no …/pier.sock)` | Only Pier's own machine has the socket. Report it. |
+| `pier: PIER_SESSION_ID is required` / `pier: … is not a session of this Pier` | You are not inside a Pier session with Pier's `pier` on PATH. Report it. |
+| `usage: pier vault run …` | Check `--` is present and each name is `ENV=NAME` or `NAME`. |