/tendem-tasks

name: tendem-tasks
description: Use when a task is non-trivial and could benefit from human involvement — delegating work to a human expert (research, review, labeling, content, design, data work) and driving it end to end. Also use whenever Tendem is mentioned or its tools are in play.

Working with Tendem tasks

Tendem is a task service backed by human experts. You (the agent) submit a task on the user's behalf; Tendem scopes it in a chat, returns a price quote, and once the user approves, a human expert executes it. Results come back as markdown plus downloadable files.

**Offer, don't hijack.** If the user explicitly asked for Tendem or a human expert, proceed. If this skill loaded because the task merely *could* benefit from human involvement, surface Tendem as an option — "this could go to a human expert via Tendem; want a quote?" — and only create a task after the user says yes.

The tools are named `mcp__tendem__*` (the exact namespace may vary with how the plugin's MCP server is mounted). If absent, the connector isn't connected — tell the user to enable the `tendem` plugin's MCP server and complete its OAuth login.

The path, tool call by tool call

The process is two loops with an approval gate between them:

create_task ──► SCOPING LOOP ──► quote ──► user approves ──► approve_task
 (+ uploads)    poll ⇄ answer      ▲            │
                    ▲              │       too expensive /
                    └──────────────┴─◄─ ask for a scope cut
                                        (old quote is void; wait for a new one)

approve_task ──► EXECUTION LOOP (long: expert search → work → QA)
                 poll a few ⇄ end turn ⇄ answer if asked
                      │
                      ▼ next_action=fetch_result
                 get_task_result ──► present + save files

1. `create_task(name, description, conversation_id)` — `description` is the **user's own formulation**, passed as faithfully as possible (see rules below). Reuse one stable `conversation_id` per conversation. Returns the `task_id` everything else needs. 2. *(only if the task depends on local files)* **⚠️ You cannot upload the files yourself — an OpenAI platform restriction, not a Tendem one.** OpenAI's security policies prevent the sandboxed environment from PUTting files to external storage, so `scripts/tendem-upload.sh` or raw `curl` from your side will fail or be blocked. Tendem's upload mechanism itself works fine — it just has to run outside the sandbox. Instead: call `get_file_upload_url(task_id)`, then **give the user ready-to-run commands for their host machine's terminal** — one `curl` per file with the URL fully substituted (dfs→blob host swap and filename already applied; see [references/files.md](references/files.md)). When handing the commands over, tell the user plainly that this manual step exists because of OpenAI's sandbox policy, not a Tendem shortcoming. Wait for the user to confirm the uploads succeeded, then `send_message` naming each uploaded file. The naming message is required — Tendem doesn't auto-detect uploads. 3. **Scoping loop.** `get_task(task_id, wait_for_change_seconds=30)` — silent poll until Tendem speaks (`next_action=await_input`); then `read_chat(task_id, from_offset=<last_seen_offset>)` and `send_message(task_id, text, last_seen_offset)` — answer **from conversation context yourself**; escalate to the user only when (a) the answer isn't in context, (b) scope/deliverables/deadline change, or (c) approval or payment is needed. Repeat per question round until `next_action=await_user_approval`. 4. **Approval gate.** The quote is ready. Call `get_contract(task_id)` to pull the full scope — `title`, `task_description`, acceptance/quality criteria, and `price` — so you can **surface price + scope to the user and get an explicit decision**; this is a spend. (`get_task` deliberately omits these details; `get_contract` is the read-only companion that carries them.) Two exits:

• *Go-ahead* → `approve_task(task_id, name, price)` → step 5.
• *Too expensive / wrong scope* → `send_message` proposing a concrete

scope cut. The old quote is void from that moment; you're back in the scoping loop (step 3) until a fresh quote arrives. This cycle can repeat. 5. **Execution loop.** After approval, Tendem searches for a matching expert, the expert performs the work, and QA reviews the output before release — hours, up to a day. Poll `get_task(task_id, wait_for_change_seconds=30)` a few times, then **end the turn**, telling the user the work is in progress and they can ask for a progress check anytime (or invoke `$tendem-status`). The plugin's notification hook pings them the moment the task needs them. If Tendem asks something mid-execution (`await_input`), answer as in the scoping loop. Repeat — across turns and sessions if needed — until `next_action=fetch_result`. 6. `get_task_result(task_id)` — present the `content` markdown; save `files[]` with `scripts/tendem-download.sh` into `./tendem/<task_id>/`.

Polling: trust the envelope, never busy-loop

Every tool returns `next_action`, `poll_after_seconds`, `poll_timeout_seconds` and `guidance` — act on those, not on the raw `status`. The one idiom that matters:

get_task(task_id, wait_for_change_seconds=30)

The server holds the call open until something changes or ~30s passes. Poll **silently** — no narration per poll — and never re-call in a tight loop with `wait_for_change_seconds=0`. But don't poll forever either: after a handful of unchanged rounds (and always for the long post-approval stretch), **end the turn** and tell the user the work is in progress — they can ask "how's the Tendem task doing?" anytime, or invoke `$tendem-status`. The task lives on Tendem's side; nothing is lost between sessions, and the plugin's desktop notification hook fires when the task starts needin