@tianshu-ai/tianshu 0.3.0

package/plugins/workboard/skills/large-input-large-output.md

@@ -0,0 +1,185 @@
+---
+name: large-input-large-output
+description: How to handle tasks that read many large files OR produce a large structured output (long HTML, long markdown report, long codegen). Read this when a task description asks you to ingest more than two non-trivial files at once, or to write more than ~500 lines in one shot, or both. Covers the read-then-summarise pattern, skeleton-then-fill pattern, and the spill-to-file escape hatch.
+scope: worker
+---
+
+# Reading lots, writing lots
+
+The default failure mode for a task like *"read these 5 markdown
+notes and produce one HTML report"* is:
+
+1. You issue 5 parallel `read_file` calls in one assistant turn.
+2. Five tool results, each tens of KB, all land in the next
+   prompt as raw text.
+3. You try to emit the whole HTML in one tool call.
+4. The LLM call truncates / returns empty / the run aborts as
+   `no_completion`.
+
+The orchestrator can't see this from outside — to it the task
+just stalled. From the inside the cause is obvious: you carried
+too much state in the prompt and asked for too much output in
+one shot.
+
+This skill is the recipe for not doing that.
+
+## When this applies
+
+Read this skill at the top of any task description that:
+
+- names ≥ 2 source files you have to read in detail, OR
+- asks for an output > ~500 lines (long HTML / long md / long
+  code), OR
+- bundles "read material A, B, C, ... and synthesise into D"
+  (the canonical multi-input synthesis shape).
+
+If the task is a small one-off ("read README.md, summarise",
+"write a 50-line script"), this skill is overkill. Skip it.
+
+## Pattern 1 — Read-then-summarise per file
+
+Cardinal rule: **what you keep in the prompt should be what you
+need for the next step, not what you originally read.**
+
+Sequence:
+
+1. Read file 1.
+2. **Immediately** write a structured summary to disk:
+   ```
+   write_file({
+     path: "/tmp/<task-slug>/summary-01.md",
+     content: "<2-3 paragraphs covering the bits that matter
+       for the final output: claims, citations, headings,
+       any quote you'll want verbatim>"
+   })
+   ```
+3. Repeat for file 2, file 3, ... — **one file per turn**, not
+   five files in one batched read.
+4. When you start composing the output, read the **summary**
+   files, not the originals. The summaries fit comfortably; the
+   originals don't.
+5. If you discover the summary is missing a fact mid-composition,
+   targeted re-read the original (`read_file` with `offset` and
+   `limit`) — don't load the whole thing again.
+
+Why per-turn matters: tool results from a single turn all stay
+in the next prompt. Five 30 KB files in one turn = 150 KB you
+never wanted to keep. One file per turn lets auto-compact (which
+fires after each turn_end) trim earlier turns away once you've
+written the summary file.
+
+## Pattern 2 — Long output: write iteratively, not in one shot
+
+When the deliverable is big (long HTML, multi-section markdown,
+a 1500-line generated file), the failure mode you want to avoid
+is **emitting the whole thing in one tool call.** Two reasons:
+
+- The provider's tool_use input stream truncates large strings,
+  so a `write_file` carrying thousands of lines of `content`
+  often fails with `content` missing entirely.
+- Even if the call lands, the next agent / human reading the
+  task has nothing to follow until the giant blob arrives. A
+  partial run leaves nothing on disk.
+
+Do this instead:
+
+1. Decide the structure of the output up front (TOC, section
+   list, what each section contains). Write that as a short
+   plan in the task description — you'll reference it as you go.
+2. Write the file in pieces. The shape that works depends on
+   the deliverable:
+   - **Markdown / prose / HTML report:** use `write_file` for
+     the first chunk (front matter / TOC / first section), then
+     `read_file` and `edit_file` to append each subsequent
+     section. Each `edit_file` call can target the end-of-file
+     marker (e.g. "</body>") and replace it with `new_section +
+     marker`.
+   - **Generated code:** `write_file` the file once with the
+     real content; if the result is so big the call is
+     truncating, the file is too big for one LLM run regardless
+     of tool shape — split the deliverable into separate files
+     (one module per file is the right shape anyway).
+3. After each chunk: keep the chunk size small enough that the
+   tool_use args don't get truncated. There's no fixed line
+   count — watch for the truncation hint in the tool result.
+
+This pattern's side benefits:
+
+- The output file exists after the first call, so a partial
+  run still leaves something on disk.
+- The agent can `read_file` what it just wrote when composing
+  later sections, keeping coherence without re-loading sources.
+
+What *not* to do:
+
+- Do not write a "skeleton" full of `<!-- TODO: section X -->`
+  placeholders and then try to fill them all in one
+  `edit_file({edits: [...]})` batch. The combined batch JSON
+  ends up larger than the original write would have been and
+  trips the same truncation it was meant to avoid. (This
+  recipe used to be in this skill; it didn't work.)
+
+## Pattern 3 — Spill to file (escape hatch)
+
+If you absolutely must work with the raw text of a large source
+mid-composition (e.g. exact quote attribution), **don't paste
+the whole file into your reasoning**. Instead:
+
+1. Read the file once, write its content to
+   `/tmp/<task-slug>/source-<n>.md` (you can also just leave it
+   at its original path).
+2. Use `read_file` with `offset` + `limit` to pull the exact
+   slice you need.
+3. Throw the slice into your output and move on. Don't keep the
+   full file's content in your reasoning across turns.
+
+`tenant_config_read` (for skills / config) and `read_file` (for
+workspace) both support `offset` + `limit`. Use them.
+
+## Anti-patterns — don't do these
+
+- **Five `read_file` calls in one assistant turn.** This is
+  the most common offender. Even if every file is "small", the
+  combined tool result will dominate the next prompt.
+- **Asking the LLM to "now generate the whole HTML"** after
+  loading five sources. Either you trim sources first (pattern
+  1) or you write iteratively (pattern 2) or both.
+- **Re-reading a file you've already summarised.** If you wrote
+  a summary, trust it. If you don't, write a better summary next
+  time.
+- **Treating `task_complete` as the moment the deliverable is
+  produced.** It's the moment you announce the deliverable is
+  done. The file should already exist on disk before you call
+  task_complete.
+- **One giant `write_file` for a 2000-line HTML report.** Even
+  if the model can produce it without truncating, the next
+  agent / human reading the work has nothing to follow until
+  the whole thing lands. Write the file in chunks (Pattern 2).
+- **One `edit_file` call per tiny edit** when you're making
+  several adjacent changes — the `edits[]` batch is atomic
+  and saves round-trips. (This is the right reason to use
+  `edits[]`; it's not a workaround for tool-arg truncation.)
+
+## When you're stuck mid-task
+
+If you find yourself in the failure mode this skill describes —
+you've loaded too much, the next call is failing, you're not
+sure how to proceed:
+
+1. Stop trying to emit the deliverable.
+2. Write `/tmp/<task-slug>/state.md` capturing what you've done
+   so far and what's left.
+3. **Then** call `task_complete` with summary
+   `"partial: section 1/4 written. See state.md for remaining
+   work."` — including the fact that it's partial in the
+   summary.
+4. The orchestrator can read state.md and either continue this
+   task or split the rest into a follow-up task. That's
+   recoverable; a `no_completion` stall is not.
+
+## See also
+
+- `workboard-howto` — task lifecycle, task_complete contract,
+  how the orchestrator reads your output.
+- `microsandbox-exec-howto` — for tasks that compile / run code
+  rather than read / write large text.

package/plugins/workboard/skills/workboard-howto.md

@@ -0,0 +1,166 @@
+---
+name: workboard-howto
+description: How to use the workboard plugin — drop tasks on the kanban, watch the worker pool process them, and patch / move / delete rows. The board is per-user inside a tenant.
+---
+
+# Using the workboard
+
+The workboard plugin gives you a per-user kanban with five visible
+columns and a worker pool that automatically picks up `todo` tasks.
+This skill is the contract between you (the agent) and the user's
+view of the board.
+
+## When to use
+
+- The user asks you to "remember to do X later" → drop a task.
+- A multi-step request can be split into independent units of work
+  → file each unit as a task so the user can track progress.
+- You want to hand off a long-running step to a worker → pin
+  the task with `worker_agent_id` (the slug of the worker; see
+  `tenant_config_list({path:"workers"})` for what's registered).
+  Pinning by slug is the recommended path — dispatch by kind is
+  not exposed.
+
+If the user is asking a one-shot question, do NOT create a task.
+Tasks are for work that survives across turns.
+
+## Tools at a glance
+
+| Tool          | Use when …                                                    |
+| ------------- | ------------------------------------------------------------- |
+| `task_list`   | Reading the board (always do this first to avoid duplicates). |
+| `task_create` | Adding a new ready task. Default project is `inbox`.          |
+| `task_update` | Changing title / description / priority / project.            |
+| `task_move`   | Walking a task between columns (`todo`→`in_progress`→`done`). |
+| `task_delete` | Removing a task you created by mistake.                       |
+
+## Status lifecycle
+
+```
+ready  →  in_progress  →  done
+                   ↘     ↗
+                    awaiting-intervention   (label, not status)
+                          ↘
+                           main agent picks task_continue /
+                           task_retry_fresh / task_extend_timeout /
+                           task_abort
+```
+
+- `ready` tasks are claimable by workers. Don't sit on them.
+- `in_progress` is set automatically when a worker claims.
+- `done` is the happy path: worker called `task_complete`, OR
+  you called `task_abort` on a stuck task (with a reason).
+- A failure / watchdog timeout adds the `awaiting-intervention`
+  label to a `ready` row and drops a `task_intervention_required`
+  notification on you. Pick one of the four intervention tools —
+  do NOT just `task_move(status="ready")`, that would skip the
+  reason-tracking and re-queue without context.
+- The legacy `stalled` label is treated identically by the pool's
+  skip filter; old rows still work.
+
+## Project slugs
+
+Tasks group under a free-form `project` slug (default `inbox`).
+Use this when the user has multiple parallel threads — e.g.
+`website-redesign`, `q3-research`. Re-use existing slugs; don't
+fragment with typos. Call `task_list` with no filter first to see
+what already exists.
+
+## Worker roles
+
+Every worker pool runs at least one `echo` worker — a 30-second
+sleep that writes a short result_summary. This exists so the loop
+is visible end-to-end.
+
+Real worker roles ship with later PRs (per ADR-0002 §1):
+
+Worker registry is per-tenant and lives at
+`_tenant/config/workers/<slug>/`. The two seeded entries on a
+fresh tenant are `echo-demo` (a no-op demo) and `llm-default`
+(a generic LLM worker). The user typically authors more workers
+via the chat agent + `tenant_config_write` (see the
+`worker-creator` skill for the contract).
+
+Set `worker_agent_id` on a task to pin it to one specific
+worker. Leave it empty to let any enabled worker pick it up
+(rarely what you want — prefer pinning so behaviour is
+predictable). Use `tenant_config_list({path:"workers"})` to
+discover available slugs.
+
+## Common patterns
+
+> **task_create / task_delete are batch tools.** Always wrap items in
+> the `tasks` / `ids` array — even for a single row. Per-row
+> failures don't abort the rest of the batch; check the
+> `results[]` field in the response.
+
+**Drop a task and forget it (delegated work):**
+
+```
+task_create({
+  tasks: [
+    {
+      title: "Convert the Q2 sales CSV to a one-page chart",
+      description: "Source: /uploads/q2-sales.csv. Output: /reports/q2.png",
+      worker_agent_id: "coder"
+    }
+  ]
+})
+```
+
+**Track your own progress (delegate to the demo worker):**
+
+```
+task_create({
+  tasks: [
+    {
+      title: "Reach out to 5 candidate contributors",
+      worker_agent_id: "echo-demo"   // demo: marks done after a delay
+    }
+  ]
+})
+// later, after you do the work:
+task_move({ id: "<id>", status: "done", result_summary: "Sent 5 DMs" })
+```
+
+**Bulk-create a roadmap, then drop them all:**
+
+```
+task_create({
+  tasks: [
+    { title: "Stage 1: write spec",  worker_agent_id: "llm-default" },
+    { title: "Stage 2: implement",   worker_agent_id: "coder"       },
+    { title: "Stage 3: test",        worker_agent_id: "coder"       },
+  ]
+})
+// later:
+task_delete({ ids: ["<id1>", "<id2>", "<id3>"] })
+```
+
+**Revive an awaiting-intervention task:**
+
+```
+// resume the same session, optional hint:
+task_continue({ task_id: "<id>", hint: "use skeleton-then-fill" })
+
+// or start a brand new session, optional revised brief:
+task_retry_fresh({ task_id: "<id>", description: "..." })
+
+// or just give it more time (especially when failure_reason
+// starts with "watchdog timeout"):
+task_extend_timeout({ task_id: "<id>", additional_ms: 600_000 })
+
+// or give up:
+task_abort({ task_id: "<id>", reason: "data missing" })
+```
+
+## Don'ts
+
+- Don't poll `task_list` in a tight loop. The worker pool drains
+  immediately on writes; the user sees updates within a few
+  seconds via the kanban panel.
+- Don't create tasks for one-turn questions. The user will see
+  them pile up.
+- Don't hand-edit `result_summary` on a worker-completed task —
+  it's the worker's report. Use `task_update.description` for
+  your own notes.

package/plugins/workboard/skills/worker-creator.md

@@ -0,0 +1,267 @@
+---
+name: worker-creator
+description: How to create or edit a workboard worker agent — agent.json fields, the kind/slug/SOUL trio, allow-list semantics (omit = unrestricted), and which tools to use. Read this when the user asks you to add, configure, or tighten a worker's permissions.
+scope: main
+---
+
+# Authoring workboard worker agents
+
+Worker agents live as directory bundles under
+`tenant-config:///workers/<slug>/`. Each bundle has up to three
+files; only `agent.json` is required.
+
+```
+tenant-config:///workers/<slug>/
+├── agent.json     (required)
+├── SOUL.md        (optional — system prompt)
+└── skills/        (optional — per-worker skill bundle)
+    └── <name>/SKILL.md
+```
+
+The pool scans this directory on activation; new workers show up
+on the next worker pool refresh, edits take effect on the next
+worker run.
+
+## When to use this skill
+
+- User says "create a worker that uses Sonnet" / "add an LLM
+  researcher" / etc. → read this, then write `agent.json`.
+- User says "lock down what worker X can call" → read this and
+  patch `agent.json`'s allow-lists.
+- User says "make a custom prompt for the LLM worker" → write
+  `SOUL.md` next to `agent.json`.
+
+If the user is **just running tasks** on existing workers, this
+skill is not relevant — use `workboard-howto` instead.
+
+## Reuse first, create second
+
+Before writing a new `workers/<slug>/agent.json`, *always*:
+
+```
+tenant_config_list({ path: "workers" })
+```
+
+If an existing worker fits the role (match by responsibility,
+not by name), reuse it. If it almost fits, edit its SOUL.md
+instead of forking. Only build a new bundle when:
+
+- nothing existing fits and the user's request genuinely needs
+  a new role, **or**
+- the user explicitly asked for a new worker ("make a separate
+  worker for X").
+
+This is the single most-violated rule. The cost of a stray
+worker isn't the disk space — it's the maintenance burden
+and the row clutter the user sees in Worker agents. See the
+`worker-fleet` skill's "Reuse over create" section for the
+full checklist; this skill assumes you've already decided a
+new worker is the right move.
+
+## Tool you'll use
+
+`tenant_config_write` does all writes. Don't reach for any
+worker_agent_* tool — that set was retired (use the filesystem).
+Path inside the workspace is `workers/<slug>/<file>`. Examples:
+
+```
+tenant_config_write({
+  path: "workers/sonnet-researcher/agent.json",
+  content: '{...}'
+})
+
+tenant_config_write({
+  path: "workers/sonnet-researcher/SOUL.md",
+  content: "You are..."
+})
+```
+
+`tenant_config_list` / `tenant_config_read` to inspect existing
+workers (see `tenant-config:///workers/`).
+
+## Critical rules — read before writing anything
+
+1. **`kind` must be one of the registered kinds.** As of today
+   that's `"llm"` and `"echo"`. Calling it `"coder"` or
+   `"researcher"` does NOT create a new runtime; the loader
+   skips unknown kinds with a warning and the worker never
+   shows up in the pool. If you want a Sonnet-driven coding
+   worker, the kind is still `"llm"` — the *role* lives in
+   `displayName` / `description` / `SOUL.md`.
+
+2. **The system prompt goes in `SOUL.md`, not `agent.json`.**
+   Two reasons: long markdown with quotes / backticks doesn't
+   round-trip through JSON cleanly (you'll bork the file with
+   a parse error), and the loader doesn't read prompt fields
+   from agent.json. Always write SOUL.md as a separate
+   `tenant_config_write` call.
+
+3. **`agent.json` knows nothing about slug.** The slug is the
+   directory name (`workers/<slug>/`). Do not add a `slug:`
+   field; it's silently ignored, which is worse than rejected.
+
+4. **Allowed top-level keys in `agent.json`:** `kind`,
+   `displayName`, `description`, `modelId`, `toolsAllow`,
+   `skillsAllow`, `enabled`, `source`. Anything else is
+   ignored. If your worker isn't doing what you expect, check
+   the server log for `fs worker agent has errors` — that's
+   where the loader complains.
+
+## `agent.json` schema
+
+```jsonc
+{
+  // Required: which runtime drives this worker.
+  "kind": "llm" | "echo",
+
+  // Optional: human-readable name shown in the admin UI.
+  // Defaults to the slug if omitted.
+  "displayName": "Sonnet Researcher",
+
+  // Optional: free-form description for humans.
+  "description": "Long-form research worker, slow but careful.",
+
+  // Optional: model id (kind=llm only). Don't guess — call
+  // `model_list` first to see which providers/models the host
+  // has registered AND which one is the default. Examples
+  // depend on host config but typically look like
+  // "sap-proxy/claude-sonnet-4-6", "sap-openai/gpt-5",
+  // "sap-perplexity/sonar-pro". Omit (or set null) to use the
+  // host default.
+  "modelId": "sap-proxy/claude-sonnet-4-6",
+
+  // Optional: tool / skill allow-lists. SEE BELOW for semantics.
+  "toolsAllow":  null | string[],
+  "skillsAllow": null | string[],
+
+  // Optional. Defaults to true. Set false to mute the worker
+  // without removing its config (e.g. "disable but keep
+  // around").
+  "enabled": true,
+
+  // Optional provenance hint.
+  //   "builtin" → seed shipped by a plugin
+  //   "user"    → human authored
+  // Default "user" for files you write yourself.
+  "source": "user"
+}
+```
+
+## Allow-list semantics — read carefully
+
+Both `toolsAllow` and `skillsAllow` follow the same rule:
+
+| Field shape   | Meaning |
+|---|---|
+| **omitted / `null`** | **No restriction** — worker sees every host + plugin + tenant tool/skill currently exposed. New plugins added later become automatically available. |
+| **`[]`** (empty array) | **Total deny** — worker can't call any tool / read any skill. Almost never what you want. |
+| **`["a","b"]`** | **Allow-list** — exactly those names, nothing else. Static; new plugins do **not** flow in. |
+
+Two extra invariants the runtime layers on top:
+
+1. `task_complete` is **always** available to LLM workers (forced
+   by the worker pool) — you don't need to list it.
+2. Orchestration tools (`task_create`, `task_list`, `task_update`,
+   `task_move`, `task_delete`, `task_get_history`) are **always
+   denied** to workers regardless of `toolsAllow`. Workers are
+   for *doing* tasks, not *managing* the board. Don't include
+   them; the runtime strips them anyway.
+
+Tenant skills (anything under `_tenant/config/skills/` or
+`_tenant/config/workers/<slug>/skills/`) **bypass** the
+`skillsAllow` filter — they always show through. Only host /
+plugin skills are gated by the allow-list.
+
+## Picking a slug
+
+The directory name is the slug — it's also the worker's runtime
+identity (used in logs, task assignment, etc). Rules:
+
+- kebab-case: `[a-z0-9][a-z0-9-]*`
+- short and meaningful: `sonnet-researcher`, `local-dev`,
+  `customer-support`. Not `worker1`, not `default`, not `tmp`.
+- unique within the tenant.
+- once you pick a slug, **don't rename** — tasks already
+  assigned to that worker reference it by slug. Rename = lose
+  history. If you need a new identity, create a fresh bundle and
+  delete the old one with `tenant_config_delete`.
+
+## SOUL.md
+
+Per-worker system prompt. Whatever you put in here replaces the
+default kind prompt. Keep it focused on:
+
+- the worker's identity ("you are a long-form research worker")
+- exit contract (call `task_complete` with a summary)
+- any house rules ("write deliverables under ./projects/<slug>/")
+
+If you don't write a `SOUL.md`, the worker uses its kind's
+default. For `kind: "llm"` that's the prompt shipped by the
+`llm-default` seed.
+
+## Per-worker skills
+
+Drop a `<name>/SKILL.md` under `workers/<slug>/skills/` and that
+skill becomes visible to **only** this worker (not main, not
+other workers). Useful for narrow operating instructions ("when
+you build sandboxes, always pin Node 20"). Frontmatter follows
+the standard skill format — see `skill-creator` for details.
+
+## Workflow
+
+1. Check the existing slugs:
+   ```
+   tenant_config_list({ path: "workers" })
+   ```
+2. Pick a slug; confirm with the user if you're unsure.
+3. Write `agent.json` with **only** the keys listed in the
+   schema above. Pick `kind: "llm"` for any LLM-driven worker
+   (the worker's role lives in displayName + SOUL.md, not in
+   the kind id). If in doubt about
+   `toolsAllow` / `skillsAllow`, omit them — unrestricted is
+   the right default for most cases.
+4. **Separately** call `tenant_config_write` again to write
+   `SOUL.md` if the worker needs a custom prompt. Do NOT try
+   to embed the prompt as a string inside `agent.json`.
+5. Optionally seed any private skills under `skills/<name>/SKILL.md`.
+6. Tell the user: pool picks the new worker up on the next
+   worker-pool refresh (currently: server restart). Mention this
+   cost — they may want to pick a moment to restart.
+7. After a refresh, point them at the Worker agents admin page
+   so they can verify the row + expand it to see the effective
+   tools/skills the worker will actually have. If the row
+   doesn't appear there, look at `tenant_config_read({ path:
+   "workers/<slug>/agent.json" })` and the server log for
+   loader errors.
+
+## Common mistakes
+
+- **Inventing a new `kind` for the role**. `kind` is the
+  runtime, not a label — only `"llm"` and `"echo"` exist
+  today. "Coder" / "researcher" / "reviewer" are all
+  `kind: "llm"` with different SOUL.md.
+- **Embedding the system prompt in `agent.json`** (e.g. as
+  `"soul": "..."`). Won't be read, will break the JSON parser
+  the moment the prompt contains a quote.
+- **Adding `slug` / `id` / unknown keys to `agent.json`**.
+  Slug is the directory name; the loader uses fixed key names
+  (see schema). Anything else is silently ignored.
+- **Empty array thinking it means "default"**. `[]` means
+  "deny everything". Use `null` (or omit the field entirely)
+  for "no restriction".
+- **Listing `task_create` / `task_list` in `toolsAllow`**.
+  They're denied by the runtime regardless. Wastes a slot; just
+  omit them.
+- **Reusing a slug**. The new bundle inherits old task history
+  pointed at that slug. Delete first.
+- **Writing `SOUL.md` for `kind: "echo"`**. Echo workers don't
+  run an LLM; the prompt does nothing. Stick to `agent.json`.
+- **Forgetting to include `kind`**. The loader skips bundles
+  with no kind, with a warning in the server log. Always include
+  it.
+
+## See also
+
+- `workboard-howto` — using the kanban + tasks day-to-day.
+- `skill-creator` — how to author the markdown skills you might
+  drop into `workers/<slug>/skills/`.