@timqi/pier 0.0.1

package/skills/pier-slack/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: pier-slack
+description: Read and write Slack through Pier's slack tool — a channel's history for a time range, one thread, posting into a thread, and the Slack-specific syntax for mentions and links. Read before answering questions about Slack conversations or posting anything to a workspace.
+---
+
+# Reading and writing Slack
+
+Pier holds the bot token and makes every call itself. State what you want; it
+resolves the channel, pages the API and hands back a finished transcript. Reads
+are live and nothing is kept between calls — write down what you need to keep.
+
+## Where am I
+
+If this conversation reached you *through* Slack, omitting `channel` means
+"here":
+
+- `{"operation":"post","text":"..."}` replies in the thread you are in
+- `{"operation":"read_thread"}` reads it
+- `{"operation":"context"}` names it: `channel`, `channelName`, `kind`,
+  `threadTs`
+
+`inSlack:false` from `context` means a task, subagent or web session started
+this: there is no current conversation and `channel` is required.
+
+`{"operation":"channels"}` lists what Pier can reach (`id`, `name`, `kind`,
+`respondsToMessages`); pass either an id or a `#name` anywhere a channel is
+wanted. `not_in_channel` means someone must run `/invite @Pier`.
+
+## Never ask for an id
+
+You already have them:
+
+- **The person talking to you** — a message may start with `[name<id> time]`,
+  added by Pier, not typed by them. It appears only when the speaker or the day
+  changes, so the last one you saw still applies.
+- **Anyone in a transcript** — every line carries `name[id]`.
+- **This channel and thread** — from `context`.
+
+Asking a human to paste their own user ID is never acceptable.
+
+## Reading
+
+```json
+{"operation":"read_channel","channel":"#incidents",
+ "since":"2024-06-01T00:00:00Z","until":"2024-06-02T00:00:00Z"}
+```
+
+```json
+{"operation":"read_thread"}
+```
+
+Omit both arguments for the thread you are in; pass `channel` + `thread_ts` for
+another. A thread read returns the parent plus every reply, with `threadTs` at
+the top of the reply rather than on each line.
+
+```json
+{"operation":"read_message","channel":"#ops","ts":"1717243800.000100"}
+```
+
+One message and nothing else, when that is the whole question. Add `thread_ts`
+when it was posted inside a thread — a channel read cannot see thread replies,
+and the error will say so.
+
+- `since` / `until` / `after` take **ISO 8601, epoch seconds, or a `ts` from an
+  earlier read**. Omitting `until` reads up to now.
+- `after` returns only what is strictly newer than that message — use it to
+  re-read a channel or thread without seeing what you saw last time.
+- `limit` caps the result (default and max 400). When `truncated` is true,
+  narrow the range rather than raising the limit.
+- Messages are oldest-first, one line each, shaped as the reply's `format`
+  field says — `<ts> | <time, UTC> | <name>[<id>] | <text>`:
+
+  ```
+  1717243800.000100 | 2024-06-01T12:10Z | Ada[U1] | deploy? [thread: 4 replies]
+  ```
+
+  The leading `ts` is Slack's id: pass it back as `thread_ts` or `after`.
+- A channel read returns thread **parents** only; `[thread: N replies]` marks
+  the ones worth opening with `read_thread`.
+- `incomplete` means the read stopped early and its value says why. Retry or
+  work with a partial answer, but do not report it as everything.
+
+## Posting
+
+```json
+{"operation":"post","text":"**Deploy done** — 3 services, 0 rollbacks."}
+```
+
+| Goal | Arguments |
+| --- | --- |
+| Reply where you are | omit `channel` and `thread_ts` |
+| Reply in a specific thread | `channel` + `thread_ts` |
+| Start a new top-level message | `thread_ts: "none"` |
+
+Going top-level takes the explicit `"none"`: a channel's main flow is wider
+than a thread. A `thread_ts` is never inherited across a change of `channel`.
+The response carries `ts` and `threadTs` for replying under what you posted.
+
+## Message syntax
+
+`text` is **standard markdown** and Slack renders it natively: `**bold**`,
+`_italic_`, `` `code` ``, fenced blocks, `# headings`, `- lists`, tables and
+blockquotes. Never hand-convert to the older `*bold*` mrkdwn; it renders
+literally.
+
+Four things are Slack syntax, which markdown cannot express:
+
+| Intent | Write | Not |
+| --- | --- | --- |
+| Mention a person | `<@U04B7Q2>` | `@alice` — plain text, no ping |
+| Link a channel | `<#C0123456>` | `#general` — plain text |
+| Notify a group | `<!here>`, `<!channel>` | `@here` — plain text |
+| Hyperlink | `[label](https://…)` | — |
+
+- **Never guess an id from a name.** A wrong `<@U…>` either fails or pings a
+  stranger, and both look like it worked. With no id, write the person's name
+  as prose.
+- **Escape `&`, `<`, `>`** when they are text and not markup: `&amp;`, `&lt;`,
+  `&gt;`.
+- Emoji as `:white_check_mark:`, not the raw glyph.
+- ~11,000 characters per message. Split longer content across replies in one
+  thread rather than truncating.
+
+## Rules
+
+- **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.
+- Read before you write. A summary of the wrong thread is worse than none.
+- 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.
+- Resolve vague times ("yesterday") to an explicit ISO range and say which
+  range you used.

package/skills/pier-tasks/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: pier-tasks
+description: Delegate work to Pier subagents with the task tool — one-shot delegation, core-joined parallel fan-out, chained steps, and mid-run control (steer/resume/contact). Read before delegating to a subagent, coordinating multiple agents, or running long background work.
+---
+
+# Orchestrating Pier tasks
+
+## Core model
+
+- Every run executes a persisted task definition. An inline `task` draft
+  (`operation:"run"` without `task_id`) creates and runs a one-shot subagent
+  atomically; it is tagged `kind:"subagent"` and hidden from task lists.
+- **Nothing blocks.** Every operation returns immediately; results, group
+  joins, and decision replies arrive later as system follow-up messages in
+  your session. Your only waiting primitive is ending your turn.
+- The child session survives the run — `resume` continues it with full
+  context intact. Poll state without blocking via `{"operation":"get",
+  "run_id":"..."}` (or `group_id`, or `task_id` for that task's recent runs).
+
+## Single delegation (the common case)
+
+```json
+{"operation":"run","task":{"name":"review-auth","action":{
+  "type":"agent","session":{"mode":"fresh","cwd":"/abs/project"},
+  "prompt":"Review src/auth/*.ts for injection risks. Output: file:line + issue + fix."}}}
+```
+
+Returns a run summary (`runId`, `state:"queued"`, ids). Finish your turn; the
+result arrives as a follow-up. `callback:"none"` silences it.
+
+A summary's `triggerSource` is who fired that run (`agent` when you did, plus
+`manual` / `cron` / `watch` / `task`); a definition's `trigger` is only its
+schedule policy, where `manual` means on-demand — by a human or by you.
+
+- `fresh`: clean context, requires `cwd`. `fork`: child starts with a copy of
+  your conversation — use when the task needs your context. `reuse`: sends
+  work to an existing session by id.
+- The child inherits your current model unless `launch.model` is set.
+  Unknown models fail with the available list in the error. `launch` applies to
+  `fresh` and `fork` only — a `reuse` session owns its own model and tools.
+- The child has the same tools you do; there is no capability knob to pick.
+- Runs time out after 900s by default; set `timeoutSeconds` in the draft for
+  longer jobs.
+
+## Parallel fan-out (core-joined)
+
+Pass `tasks[]` (each entry a draft or `{"task_id":"..."}`) and Pier joins the
+group in core — you never track run ids across turns:
+
+```json
+{"operation":"run","join":"all","tasks":[
+  {"name":"review-correctness","action":{...}},
+  {"name":"review-tests","action":{...}}]}
+```
+
+- `join:"all"` (default): one aggregated follow-up when every member
+  finishes, listing each member's name, state, and result.
+- `join:"first"`: the first finished run wins; the rest are cancelled but
+  their sessions stay resumable (ids are in the callback).
+- `get`/`cancel` accept `group_id`: observe or stop the whole group as one
+  unit.
+- Limits: 4 agents active at once, 16 children per tree, nesting caps at
+  you → child → grandchild. Extra members queue rather than fail.
+
+## Chains
+
+Run step 1, end your turn, receive its callback, splice the needed part into
+step 2's prompt. Children share nothing implicitly (except fork's copied
+history) — every prompt must be self-contained: paths, acceptance criteria,
+expected output format. Branching and retries are your own logic between
+turns.
+
+## Choosing a model
+
+Omit `launch.model` to inherit your own model — the right default. Override
+only when the task profile clearly differs:
+
+- `anthropic/claude-opus-5` — hardest reasoning: architecture, gnarly debugging
+- `anthropic/claude-fable-5` — long autonomous implementation runs
+- `anthropic/claude-sonnet-5` — balanced default: implementation, review
+- `anthropic/claude-haiku-5` — cheap and fast: listings, extraction, simple checks
+- `openai/gpt-5.6` series (e.g. `gpt-5.6-sol`) — cross-vendor second opinion
+
+An unknown id fails with the available models listed in the error.
+
+## Mid-run control
+
+- `steer` — interrupt a running child with corrected instructions
+- `follow_up` — queue a message for after its current turn
+- `resume` — continue a finished child in its same session; this expires any
+  unanswered decision on that run
+- `cancel` — stop a run (or a whole group via `group_id`); cancellation
+  cascades to the run's own children
+
+## Supervisor decisions (as a child)
+
+`{"operation":"contact","reason":"decision","message":"..."}` returns a
+receipt immediately. State what you are waiting for and **end your turn** —
+never spin or poll. The answer arrives as a follow-up if your run is still
+active; if your run already finished, Pier resumes your session with the
+reply as the prompt. One open decision per run.
+
+As a parent: the question arrives as a system input with a message id, steered
+into your current turn at the next step boundary so a blocked child is not
+waiting on the end of your turn; answer
+with `{"operation":"reply","message_id":"...","message":"..."}`. A run that
+finished while awaiting your answer shows `pendingDecisionId` in `get` and
+sends no completion callback — the question is the notification.
+
+`reason:"progress"` is fire-and-forget status for the parent.
+
+## Rules
+
+- One concern per child. For fan-out, let core join via `tasks[]` — never
+  hand-aggregate run ids across turns.
+- Repeating the same role? Create a durable task once (`operation:"create"`)
+  and run it by `task_id` — cheaper than re-sending the draft every time.
+- Inline drafts must use `action.type:"agent"`; triggers are forced manual;
+  do not target another session with `reuse` from an inline draft.
+- After launching work, end your turn. The callback starts your next one.