@aitne-sh/aitne 0.1.10 → 0.1.12

package/agent-assets/skills/agent-create/SKILL.md

@@ -90,10 +90,23 @@ Fields:
   fires. Only shapes that map are actually run: minute a single value; hour a
   single value or `*` / `*/N`. Pick one explicit, mappable cadence.
 - **`schedule.timezone`** — IANA zone; omit to inherit the daemon default.
+- **`schedule.defer_in_quiet_hours`** — boolean, default `false`. When `true`, a
+  firing that lands inside the user's quiet hours is pushed to the window's end
+  instead of running — the whole run moves, so the data is fresh at delivery
+  time. Mechanical rule: **set `true` whenever the Expected output includes
+  DMing the user**; leave it `false` for silent file-writing work deliberately
+  scheduled overnight.
 - **`backend`** — optional. `tier` is `lite`/`medium`/`high` (cost/capability knob;
   the standalone control that works). `process_key` defaults to `agent.task`;
   omit unless you know you need another. (Pinning a backend *engine* without a
   `model` is a known no-op — prefer `tier`.)
+- **`playbooks`** — optional array of operating-playbook slugs to inject into the
+  Agent's prompt at fire time: `research`, `markdown-note`, `monitoring`. Declaring
+  one makes the daemon inject that playbook's full methodology into every run — a
+  hard guarantee, and the only way the methodology reaches the Agent (there is no
+  separate skill copy). **Declare every playbook you name in the prompt's
+  `# Important`** — a bare mention is not injected on its own. An unknown slug is
+  rejected as `invalid_definition` on field `playbooks`.
 - **`prompt`** — the Agent's instructions (the Markdown body). **This is the most
   important field. Write it in detail.**
 
@@ -104,43 +117,46 @@ Fields:
 > management rules). It does NOT remember this conversation or why you created
 > it. An under-specified prompt produces a vague, drifting Agent.
 
-Write the prompt as a self-contained brief covering all four:
+Author every Agent prompt with the **canonical frame** below, and resolve any
+missing required slot with the user *before* you `POST /api/agents` (clarify-back).
 
-| Element | What it must answer |
-|---|---|
-| **Requirements / preconditions** | What must be true / what inputs to read first (files, APIs, accounts). What to do if a precondition is missing. |
-| **Goal** | The single outcome this Agent exists to produce, stated concretely. |
-| **Process** | The ordered steps to run each firing — specific verbs, endpoints, filenames, decision rules. |
-| **Expected output** | What "done" looks like: which file/section is written, whether/when to DM the user, what NOT to do. |
+{{> ref:prompt-frame }}
 
-**Good prompt (excerpt):**
-```
-## Goal
-Each morning, surface inbox items that need the user's decision today.
-
-## Requirements
-- Read state/today.md for the day's agenda before triaging.
-- Mail access via the mail skill endpoints; if mail is unreachable, log the gap
-  to the Agent Log and exit without DMing.
-
-## Process
-1. GET unread mail from the last 24h.
-2. Classify: actionable-today / FYI / ignore (rules: …).
-3. Append a "## Inbox triage" section to state/today.md with the actionable set.
-4. DM the user ONLY if ≥1 item is time-sensitive today.
-
-## Output
-- today.md updated with the triage section.
-- At most one DM, sent only for time-sensitive items.
+### Declare the playbooks you reference
+
+Whenever the prompt's `# Important` names a playbook, ALSO list its slug in the
+top-level `playbooks` field so the daemon injects that methodology into every
+firing as a hard guarantee — not just a by-reference skill the Agent might skip:
+
+```json
+"playbooks": ["research", "markdown-note"]
 ```
 
-**Bad prompt:** `"Triage my inbox."` — no requirements, no steps, no output
-contract; the Agent will improvise differently every day.
+Valid slugs: `research`, `markdown-note`, `monitoring`. If you name a playbook in
+the prompt but forget to declare it, the create response returns a `warnings[]`
+entry (`playbook_referenced_not_declared`) — read it and add the missing slug.
+
+### Operational (state-mutating) Agents — extend the frame
+
+Most Agents are content / knowledge agents (research, monitoring, note) and the
+core frame above is the right shape. When the Agent instead **mutates code, files,
+or system state** — the general-purpose archetype — extend the frame with scope,
+a run-time autonomy boundary, and a verification receipt:
+
+{{> ref:prompt-frame-extended }}
+
+The `# Output` decision feeds one schedule field: if the output contract
+includes DMing the user, also set `schedule.defer_in_quiet_hours: true` so a
+firing inside quiet hours waits for the window's end instead of producing a
+message that would be held anyway.
 
 ## Responses & errors
 
 - `201 { "status": "created", "slug": "…" }` — the Agent is live; its recurring
-  schedule is paired and it will fire on the next matching tick.
+  schedule is paired and it will fire on the next matching tick. The response may
+  also carry `warnings[]` (non-blocking authoring lint — e.g. an empty prompt, a
+  missing `# Instruction` section, or a playbook you named but didn't declare);
+  the Agent is still created, but fix the flagged issues and re-save its `agent.md`.
 - `400 one_shot_not_supported` — the schedule was not `cron`/`recurring`. Use the
   `schedule` skill for one-time tasks.
 - `400 invalid_recurrence` — a `kind:"recurring"` schedule carried a malformed

package/agent-assets/skills/agent-create/references/prompt-frame-extended.md

@@ -0,0 +1,132 @@
+---
+kind: reference
+name: prompt-frame-extended
+description: The extended prompt frame for operational / state-mutating agents (code, files, system state) — adds Goal / Context / Inputs / Scope / Execution Mode / Requirements / Constraints / Verification and a structured Output receipt on top of the core frame, plus the operational clarify-back slot.
+---
+
+### When to reach for the extended frame
+
+Use it when the agent **mutates code, files, or system state**, or runs a
+multi-step engineering-flavored task (the *general-purpose* agents). Content /
+knowledge agents (research, monitoring, note) stay on the **core** frame — their
+verification and output shape come from the playbooks, so they never carry the
+sections below. Forcing this scaffolding onto a content agent is empty boilerplate
+that dilutes the real instruction and eats the 8000-char cap.
+
+Add these on top of the core `# Role` / `# Important` / `# Instruction`:
+
+```markdown
+# Goal              # the outcome this agent exists to produce (fold into # Role if one line)
+# Context           # background, why it matters, the spec / state to read first
+# Inputs            # concrete artifacts: files, paths, URLs, repos, prior-run note, error logs
+# Role
+Act as a careful <engineer / researcher / reviewer / editor>.
+Prioritize <correctness / minimal change / source-backed claims / maintainability>.
+# Scope             # WHERE it may act
+Do:     - <in-scope actions / the editable surface>
+Do not: - <areas, files, or data it must not touch>
+# Execution Mode    # WHEN to act vs escalate
+Proceed autonomously after reading the relevant context.
+Escalate instead of acting when an action is outward-facing or irreversible
+(send / publish / pay / delete), a data / schema migration, a broad refactor, or
+the requirements are materially contradictory.
+On escalation: if the user is reachable, DM a concise approval request and defer the
+action; if running unattended, record the proposed action + reason and skip it.
+# Requirements      # success conditions
+- <condition 1> ...
+# Constraints       # behavioral prohibitions not already in Scope / Execution Mode
+- No speculative changes; preserve behavior outside the requested scope; no new
+  dependencies unless clearly necessary; do not remove existing tests / validation.
+# Verification
+- Run the checks relevant to what changed: code → tests / typecheck / lint;
+  research → cross-check each claim against ≥ 2 sources.
+- Don't claim verification unless the checks passed; if they can't be run, say why.
+# Output            # structured receipt for the user to review
+1. Summary of what was done
+2. Files changed / sources used
+3. Checks run + results
+4. Assumptions made
+5. Remaining risks / follow-ups
+```
+
+Three rules keep the extended frame from sprawling (over-specification — the same
+prohibition restated three times — is its main failure mode):
+
+- **One prohibition, one section** — spatial → `# Scope`, risk / timing →
+  `# Execution Mode`, behavioral → `# Constraints`. Never restate "don't touch
+  unrelated files" in all three.
+- **Fold short sections up** — an empty `# Goal` / `# Context` / `# Constraints` is
+  omitted, not left as a stub (`# Goal` folds into `# Role` when it's one line).
+- **Content archetypes stay on the core frame** — never give a research / note
+  agent `# Verification` or receipt scaffolding.
+
+#### `# Execution Mode` — the run-time autonomy boundary
+
+Clarify-back (below, and in the core frame) resolves ambiguity at **authoring**
+time, with the user present. `# Execution Mode` governs the **deployed** agent at
+**run** time, usually with no user present — the gap where an agent that hits a risk
+boundary mid-run has no instruction. Encode the product's posture: act on the safe,
+reversible majority; on the risky minority **defer + flag** (DM an approval request,
+hold the action) when the user is reachable, or **record + skip** when unattended.
+Never guess, never block waiting.
+
+### Clarify-back — the operational slot
+
+On top of the content-archetype slots in the core frame, an operational agent has
+its own required slots:
+
+| Archetype | Required slots (ask only if unknown) | Sensible default |
+|---|---|---|
+| **General / operational** (code, files, system state) | editable surface / scope; what "done" means (success criteria); may it act autonomously or propose-then-confirm; which checks to run | propose-then-confirm for irreversible / outward actions; run the repo's standard checks; deliver as a branch / PR or draft, not a direct commit / send |
+
+### Worked example — an operational agent
+
+A recurring "keep the repo green" agent, extended frame end-to-end:
+
+```markdown
+# Goal
+Keep <repo> free of lint and type errors introduced during the day.
+
+# Context
+CI runs lint + typecheck on every PR; errors on `develop` block everyone. You run
+nightly to catch and fix what slipped in.
+
+# Inputs
+- Repo: <org/repo>, branch `develop`.
+- Commands: `pnpm lint`, `pnpm typecheck` (project root).
+
+# Role
+Act as a careful engineer. Prioritize minimal, behavior-preserving changes.
+
+# Scope
+Do:     fix lint / type errors in app source under `packages/`.
+Do not: touch test fixtures, generated files, or `*.config.*`; change runtime behavior.
+
+# Execution Mode
+Proceed autonomously for mechanical fixes. Escalate (open a draft PR + DM, do not
+merge) if a fix needs a behavior change, touches a public API, or the error count is
+> 30 (likely a systemic cause to confirm first). Running unattended: never merge —
+always deliver as a PR for review.
+
+# Requirements
+- `pnpm lint` and `pnpm typecheck` both pass after your changes.
+- One PR titled `nightly: lint+type sweep <YYYY-MM-DD>`.
+
+# Constraints
+- No new dependencies; no disabling of rules to silence errors; do not remove tests.
+
+# Verification
+- Run `pnpm lint` and `pnpm typecheck`; include the final output in the receipt.
+- If either still fails, leave those errors unfixed and list them — don't claim green.
+
+# Output
+1. Summary of what was fixed.
+2. Files changed (+ the PR link).
+3. `pnpm lint` / `pnpm typecheck` results.
+4. Assumptions made.
+5. Remaining errors / follow-ups.
+```
+
+**Bad:** `"Keep the repo green nightly."` — no scope (which files?), no autonomy
+boundary (merge or PR?), no verification contract. An agent with write access and
+no `# Scope` / `# Execution Mode` is how unattended automation does damage.

package/agent-assets/skills/agent-create/references/prompt-frame.md

@@ -0,0 +1,125 @@
+---
+kind: reference
+name: prompt-frame
+description: The canonical core prompt frame (# Role / # Important / # Instruction / # Output), the operating-playbook references, and the clarify-back gate the DM agent uses to author a deployed agent's prompt. Shared byte-identical between agent-create and schedule.
+---
+
+### The core frame
+
+Author the deployed agent's prompt as this Markdown skeleton. It is classic,
+model-agnostic structure and reads identically under every backend. Keep it well
+under the 8000-char cap — durable methodology lives in the playbooks (below), not
+inlined here.
+
+```markdown
+# Role
+You are <agent identity>. Every <cadence> you <the single outcome this agent exists for>.
+
+# Important
+- <hard constraints & rules to uphold>
+- Preconditions: read <inputs> first; if <precondition> is missing, <fallback> and do not guess.
+- Do NOT <the things that would make the output wrong or unsafe>.
+- <playbook reference — name the methodology you'll follow, e.g. "Follow the research playbook.">
+
+# Instruction
+1. <ordered, concrete step — specific verb + endpoint / filename / decision rule>
+2. <step — include a worked EXAMPLE wherever a step is non-obvious>
+   e.g. "Classify each item actionable-today / FYI / ignore — 'PR review requested' → actionable-today; a newsletter → ignore."
+3. ...
+
+# Output
+- <format & destination: which file / section, frontmatter, append-vs-new-file, when/whether to DM>
+- <if writing a note, say "follow the markdown-note playbook for structure">
+- (Omit this section only when the task produces no durable artifact and no DM.)
+```
+
+Rules that make the difference between a sharp agent and a drifting one:
+
+- **`# Instruction` steps must include concrete examples.** A step the agent could
+  read two ways needs a worked example pinning the intended one. Vague steps are
+  the #1 cause of a drifting agent.
+- **`# Important` is the guardrail section** — preconditions, fallbacks, the
+  explicit "do NOT" list, and the playbook reference all live here. Don't scatter
+  guardrails across the other sections.
+- **The deployed agent has no memory of this conversation.** Everything it needs is
+  in the prompt or in a playbook it is told to follow — nothing else carries over.
+
+Migrating from the old four-element skeleton:
+
+| Old element | New home |
+|---|---|
+| Goal | `# Role` (identity + the single outcome) |
+| Requirements / preconditions | `# Important` (preconditions + fallbacks) |
+| Process | `# Instruction` (ordered steps, **with examples**) |
+| Expected output | `# Output` |
+| guardrails / "what NOT to do" | `# Important` |
+
+### Operating playbooks (never inline the full text)
+
+Durable methodology lives in the operating playbooks, kept central so a single
+update reaches every agent. Do NOT paste a playbook's full content into the prompt
+— that copy would silently go stale. How the methodology reaches the run depends
+on the path:
+
+- **Recurring Agent** (agent definition): name the playbook in `# Important` AND
+  declare its slug in the top-level `playbooks:` field. The daemon then injects the
+  full methodology into every run — the single, guaranteed copy in the prompt.
+- **One-off task** (`/schedule`): there is no `playbooks:` field and no injection.
+  Fold the handful of steps you actually need straight into `# Instruction`; a
+  run-once task has no staleness concern, so inlining is the right call here.
+
+| If the agent's job is… | Name this playbook in `# Important` | Also |
+|---|---|---|
+| Research a topic and report | "Follow the **research** playbook." | + markdown-note if it writes a note |
+| Watch something and report changes | "Follow the **monitoring** playbook." | + markdown-note for the rolling note |
+| Produce / update a free-form topic note | "Follow the **markdown-note** playbook." | — |
+
+The markdown-note playbook governs *free-form topic notes only* — never the
+structured context-vault files (today.md, journal, roadmap), which keep their own
+schemas.
+
+### Clarify-back before you deploy
+
+If a required slot for the agent's archetype is unknown from the conversation, ask
+the user **one consolidated question** before creating the agent — never guess. (The
+runtime drops an ambiguous task rather than salvaging it, so ambiguity has to be
+resolved now.) Batch all missing slots into a single message and pair each with a
+sensible **default** the user can accept in one tap. Ask only *missing, required*
+slots — don't interrogate.
+
+| Archetype | Required slots (ask only if unknown) | Sensible default |
+|---|---|---|
+| **Research** | topic/scope; what you mainly want (a decision? situational awareness? specific sub-questions?); depth (how many angles/sources); output destination (Obsidian note? DM? both); cadence + time | medium depth (3–5 angles); Obsidian note + short DM digest |
+| **Monitoring / digest** | what to watch; what counts as a noteworthy change; where to record; notify threshold (always vs only-on-change) | notify only on material change; record to a rolling note |
+| **Any task writing a note** | destination path; title pattern; append-to-existing vs new-file-per-run | new dated file under the topic folder |
+
+### Worked example — a content agent
+
+**Good** (research → note; core frame + playbook references):
+
+```markdown
+# Role
+You are the user's AI-news researcher. Every morning you produce a verified digest
+of the most important AI developments from the last 24h.
+
+# Important
+- Read context/research/ai-news.md for what you already reported; don't repeat it.
+- Follow the **research** playbook for method + source verification, and the
+  **markdown-note** playbook for the note's shape.
+- Do NOT include a claim backed by a single source without marking it "(single source)".
+
+# Instruction
+1. Pick 3–5 distinct angles not already covered in the existing note.
+2. For each angle, find 2–4 authoritative sources with WebSearch; open the top 1–2
+   in full if the agent has page-fetch access (a standard scheduled agent does not).
+   e.g. for "model releases" prefer the lab's own post over a news aggregator.
+3. Cross-check every material claim against ≥ 2 sources before including it.
+
+# Output
+- Write context/research/ai-news/<YYYY-MM-DD>-digest.md per the markdown-note playbook.
+- DM the user the 2–4 sentence "what matters" summary + the note path.
+```
+
+**Bad:** `"Research the latest AI news every morning and send me a summary."` — no
+preconditions, no method, no source bar, no output contract; the agent improvises
+differently (and shallowly) every day.

package/agent-assets/skills/background-task/SKILL.md

@@ -0,0 +1,184 @@
+---
+name: background-task
+description: Hand a long-running or open-ended task (deep research, multi-repo CI audit, monitor X over time, bulk compile) to /api/background-task. Compose a self-contained brief, set the notification policy, POST, ack, end the turn. Read GET /:id for follow-up detail.
+allowed-tools:
+  - Bash(curl *)
+---
+
+# Background Task — long-running work from DM
+
+A detached worker runs the task in its own session with its own budget.
+**The daemon delivers the result to the user directly — in your own voice —
+when it finishes or needs input. You are NOT in that delivery path.** Your
+job is the front bookend only: scope the task *now*, compose a
+self-contained **brief**, choose a notification policy, POST it,
+acknowledge in one line, and **end your turn**. The worker's run is
+invisible to you.
+
+This is the surface for *generic* long tasks. For an open-ended **browser**
+job (post a tweet, fill a form) use the `browser-task` skill. For a
+*recurring* cadence ("every morning…", "each hour check my PRs") use
+`agent-create` / `schedule` — a background task is a single detached run.
+
+## When to background it (triage)
+
+Background work that is **long-running or open-ended** so the user can keep
+chatting. No duration guess — decide on the signals:
+
+1. **Category** — deep research, a multi-repo / multi-file audit,
+   "monitor / watch X", a multi-step web dig, a bulk compile. Strongest
+   signal.
+2. **Owner signal** — explicit ("take your time", "report back later") or a
+   research-style bang command.
+3. **Scoping reveals size** — if resolving the request shows large or
+   genuinely open-ended work, delegate it.
+
+**Bias toward backgrounding category-1 work; keep plausibly-quick lookups
+inline** (delivery costs a turn's latency). One task per request: "research
+X AND audit Y" → two POSTs.
+
+## Compose the brief — this is the real work
+
+The worker sees ONLY your `brief` (it does not inherit the conversation,
+the user profile, or the management rules). An under-specified brief forces
+a clarification round-trip you can avoid by writing it well *this turn*.
+Resolve ambiguity with the user now, then encode all of:
+
+- **Objective** — the end state as an outcome ("find which repos have a red
+  main build", not "go look at repos").
+- **Scope & inputs** — the concrete inputs the worker can't infer: the repo
+  list, what "failing" means, which sites, the date range.
+- **Output language** — the user's language for `result`, `draft`, and any
+  clarification.
+- **Persona hints** — a line on the user's voice so the `draft` summary
+  reads right if it's sent directly.
+- **Notification policy + criteria** — see below; for `if_significant` the
+  criteria MUST be written into the brief in concrete terms.
+- **Expected output** — what a good `result` contains (a per-repo table, a
+  ranked list, a one-paragraph verdict).
+
+The worker can read owner memory itself to fill in preferences, so you need
+only supply the *task-specific* inputs above. **Promoting an inline task?**
+Also fold in the work you already did (findings, partial results) so the
+worker continues rather than restarting cold.
+
+## Notification policy — you author it
+
+`notificationPolicy` decides whether the worker's result reaches the user.
+The worker doesn't free-judge; it evaluates the policy you set:
+
+- **`always`** (default) — the user asked and wants the answer, even
+  "nothing found / 0 issues". The common case; always delivered.
+- **`if_significant`** — delivered **only if** the concrete criteria are
+  met. Prefer the structured **`significanceCriteria`** array (below) over
+  prose; vague criteria defeat the policy.
+- **`silent`** — never delivered; filed only.
+
+A filed (`silent` / unmet-`if_significant`) result is not lost — it surfaces
+in the daily digest and the user can pull it (see "Filed results" below).
+
+## Endpoints (localhost only)
+
+| Method | Path | Purpose |
+|---|---|---|
+| POST | `/api/background-task` | Create + dispatch, or schedule (`scheduleAt`). |
+| GET | `/api/background-task?state=...` | List (also `notify`, `sinceHours` for the filed pull). |
+| GET | `/api/background-task/:id` | The artifact — verbatim `report`, `draft`, `notify`, clarifications. |
+| POST | `/api/background-task/:id/cancel` | Force-stop. |
+
+Clarifications are answered with the **`background-task-reply`** skill.
+
+## Hard rules
+
+1. **Localhost only.** `http://localhost:8321/api/background-task/*`.
+2. **POST, ack, end the turn. NEVER poll for completion.** After a
+   successful POST, reply once and stop. Do NOT GET `/:id` in a loop or
+   "wait and check". Ending your turn has zero effect on the detached
+   worker — it keeps running and the daemon delivers the result as a DM in
+   your voice. The only allowed GET is a single on-demand read answering an
+   explicit user question (see "Follow-up detail").
+3. **Never invent `taskId` / `clarificationId`** — uuid v4 minted by the
+   daemon; read them from responses.
+4. **The worker has no messaging tool** — it cannot DM the user; it writes
+   its artifact and *you* (the daemon, in your voice) deliver.
+5. **One task per request.**
+
+## POST — composing a request
+
+`POST /api/background-task` with the self-contained brief:
+
+```bash
+curl --silent --fail -X POST -H 'Content-Type: application/json' \
+  -d '{"brief":"Audit these repos for a red main-branch CI build: aitne/daemon, aitne/web. \"Failing\" = the latest default-branch run concluded failure. Summary in English. Only notify if at least one repo is red. Output: one line per failing repo with the job.","title":"CI audit","notificationPolicy":"if_significant"}' \
+  http://localhost:8321/api/background-task
+```
+
+Body:
+
+- `brief` (1..16384) — the self-contained worker prompt above.
+- `title` (1..200, optional) — short human label for status + the DM.
+- `notificationPolicy` — `always` (default) / `if_significant` / `silent`.
+- `significanceCriteria` (optional, `if_significant` only) — up to 12
+  atomic conditions (each ≤500 chars), e.g. `["any repo's main build is
+  red","spend > $100"]`. Worker notifies iff one is met. Omit otherwise.
+- `tier` (optional) — `lite` / `medium` / `high` budget envelope. Default
+  is fine; use `high` only for genuinely heavy research.
+- `maxBudgetUsd` (optional) — override the dollar cap (hard ceiling `15`;
+  a larger value is rejected `400`). Prefer `tier` over a raw dollar value.
+- `scheduleAt` (ISO 8601, optional) — defer the *run* to a fire time (the
+  worker starts then; it is compute, so it runs even during quiet hours).
+  The eventual *result delivery* is what respects quiet hours, not the run.
+  `202` with `{ taskId, status:"scheduled", scheduledFor, scheduleRowId }`.
+  A time more than 60s in the past is rejected `400`.
+
+Immediate response carries `taskId` and `status`. Then ack once and stop
+(Hard rule 2).
+
+## Acknowledgement
+
+One line, no ceremony, no internal mechanism names (`taskId`, "worker",
+"artifact"); your output language is already governed by your policy.
+Structural examples (English): *"Started the audit in the background — I'll
+report when it's done."* / *"On it. I'll dig into that and come back with
+what I find."* Do NOT promise a specific time; say "when it's done".
+
+## Follow-up detail — answer from the artifact, don't guess
+
+The delivered DM carries a *summary*. When the user later asks for precise
+detail it didn't include ("what exactly did it find on repo X?", "show me
+the numbers"), do a **single** read and answer from the verbatim `report`:
+
+```bash
+curl --silent --fail http://localhost:8321/api/background-task/<taskId>
+```
+
+`report` is the full, unparaphrased result. Quote from it; don't invent
+detail. If you lack the `taskId`, list `state=completed` and match by
+`title`.
+
+## Filed results — the "did that monitor ever run?" pull
+
+A `silent` / unmet-`if_significant` result is filed (`notify=false`), not
+pushed. When the user asks whether a backgrounded task ran:
+
+```bash
+curl --silent --fail "http://localhost:8321/api/background-task?state=completed&notify=false&sinceHours=168"
+```
+
+Each row carries `title`, `significance`, and `report`. Summarize
+naturally; offer to pull any in full.
+
+## Force-stop — "stop" / "cancel" / "abort"
+
+On a clear stop signal, find the task (by `taskId`, or list
+`state=running,awaiting_user,pending` and match the topic), then
+`POST /api/background-task/<taskId>/cancel` with optional
+`{"reason":"user_cancel"}`. `200` = accepted; `404 not_found` = stale id,
+re-read; `409 already_terminal` = too late, report `currentState`
+verbatim. "wait" is NOT a cancel.
+
+## Scheduling — `scheduleAt` ≠ the `schedule` skill
+
+For "do this research at <time>" use `scheduleAt` in this POST. The
+`schedule` skill is for listing / modifying / cancelling pending schedules;
+a recurring cadence is `agent-create`.

package/agent-assets/skills/background-task-reply/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: background-task-reply
+description: |
+  When a background task is parked on a clarifying question and the
+  owner's DM answers it, relay the answer via
+  POST /api/background-task/<taskId>/clarify. Use ONLY when a task is in
+  awaiting_user AND the conversation shows the question was just asked.
+allowed-tools:
+  - Bash(curl *)
+---
+
+# Background Task — clarification relay
+
+A detached background task can pause to ask the owner one question
+(`awaiting_user`). The daemon already DMed that question to the owner, in
+your voice — you did NOT author it and you do not poll for it. You act only
+when the owner comes back with an answer, translating their natural-language
+reply into the structured `/clarify` call that un-parks the worker.
+
+This skill does NOT spawn tasks (that's `background-task`) and does NOT
+deliver results (the daemon does that directly).
+
+## Hard rule — never cold-call
+
+This skill is a no-op unless BOTH hold:
+
+1. `GET /api/background-task?state=awaiting_user` returns a non-empty list
+   (call this FIRST). Empty → do nothing; the owner's message is not a
+   clarification answer.
+2. The conversation shows the agent recently asked that task's question —
+   a pending `task_clarification` in your catchup context, or a recent
+   assistant DM that posed it. No recent question → the reply is about
+   something else; leave the parked task alone (its deadline scanner
+   handles a genuine no-answer).
+
+Relaying when the owner didn't answer the question is a worse failure than
+missing an ambiguous reply. When unsure whether the message answers the
+question, ask ONE short clarifier rather than guessing.
+
+## Endpoints
+
+| Method | Path | Purpose |
+|---|---|---|
+| GET | `/api/background-task?state=awaiting_user` | List parked tasks. Call FIRST. |
+| GET | `/api/background-task/:id` | Read the open `clarifications` row (`resolved:false`) for its `id` + `question`. |
+| POST | `/api/background-task/:id/clarify` | Relay the answer. |
+
+## Resolving which task
+
+1. `GET /api/background-task?state=awaiting_user`. Usually exactly one
+   parked task; if several, match the owner's reply to the right one by
+   topic / `title`, or ask which.
+2. `GET /api/background-task/<taskId>` — read the open `clarifications`
+   entry (`resolved:false`) and re-read the `question` so you can confirm
+   the owner's message actually answers it. The GET response exposes each
+   clarification row's identifier as `id`; to answer, POST `/clarify` with
+   that value in the request-body field `clarificationId`.
+
+If your catchup context already carries the `clarificationId` in metadata,
+you may use it — but **never surface a `clarificationId` or `taskId` in
+user-visible text** (token hygiene). The GET is the authoritative source.
+
+## Relay the answer
+
+```bash
+curl --silent --fail -X POST -H 'Content-Type: application/json' \
+  -d '{"clarificationId":"<uuid>","answer":"api first"}' \
+  http://localhost:8321/api/background-task/<taskId>/clarify
+```
+
+- `answer` (1..8192) — the owner's reply, verbatim and faithful. Do not
+  re-decide the task on their behalf; pass what they said.
+- `clarificationId` is optional — if you omit it the daemon resolves the
+  single open clarification — but prefer passing the explicit id when more
+  than one task is parked.
+
+Then ack briefly ("Got it, picking that back up.") and end the turn — the
+worker resumes on its own and the daemon delivers the eventual result.
+
+Status codes — handle each, don't retry blindly:
+
+- `200` — recorded; the worker resumes. Brief ack.
+- `400 validation_error` — `clarificationId` not a uuid, or `answer` empty
+  / > 8192 chars. Re-read with GET and re-send.
+- `409 not_awaiting_user` (carries `currentState`) — the task already moved
+  on (finished, cancelled, or the window closed). Tell the owner the state
+  plainly; do not re-send.
+- `409 no_open_clarification` — nothing to answer; your state was stale.
+  Re-read with GET first.
+- `409 already_resolved` — the question was already answered (a racing
+  reply landed first). The worker has resumed; do not re-send. A brief ack
+  is enough.
+- `410 expired` — the clarification deadline passed; the worker will time
+  out. Apologise briefly and offer to re-run if relevant.
+- `404 not_found` — stale `taskId`; re-read with GET.
+
+## Localhost only
+
+`http://localhost:8321/api/background-task/*`. JSON body in single quotes
+(project convention) so the daemon hooks classify the payload as data.