@aitne-sh/aitne 0.1.11 → 0.1.12

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

@@ -90,7 +90,7 @@ Clarifications are answered with the **`background-task-reply`** skill.
 
 ## Hard rules
 
-1. **Localhost only.** `http://127.0.0.1:8321/api/background-task/*`.
+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
@@ -110,7 +110,7 @@ Clarifications are answered with the **`background-task-reply`** skill.
 ```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://127.0.0.1:8321/api/background-task
+  http://localhost:8321/api/background-task
 ```
 
 Body:
@@ -149,7 +149,7 @@ 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://127.0.0.1:8321/api/background-task/<taskId>
+curl --silent --fail http://localhost:8321/api/background-task/<taskId>
 ```
 
 `report` is the full, unparaphrased result. Quote from it; don't invent
@@ -162,7 +162,7 @@ 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://127.0.0.1:8321/api/background-task?state=completed&notify=false&sinceHours=168"
+curl --silent --fail "http://localhost:8321/api/background-task?state=completed&notify=false&sinceHours=168"
 ```
 
 Each row carries `title`, `significance`, and `report`. Summarize

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

@@ -65,7 +65,7 @@ user-visible text** (token hygiene). The GET is the authoritative source.
 ```bash
 curl --silent --fail -X POST -H 'Content-Type: application/json' \
   -d '{"clarificationId":"<uuid>","answer":"api first"}' \
-  http://127.0.0.1:8321/api/background-task/<taskId>/clarify
+  http://localhost:8321/api/background-task/<taskId>/clarify
 ```
 
 - `answer` (1..8192) — the owner's reply, verbatim and faithful. Do not
@@ -96,5 +96,5 @@ Status codes — handle each, don't retry blindly:
 
 ## Localhost only
 
-`http://127.0.0.1:8321/api/background-task/*`. JSON body in single quotes
+`http://localhost:8321/api/background-task/*`. JSON body in single quotes
 (project convention) so the daemon hooks classify the payload as data.

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

@@ -0,0 +1,93 @@
+---
+name: board
+description: Read-only Task Board — list everything in motion (recurring DMs, Agents, app-fetch, reminders, background/browser/research) via GET /api/tasks, and preview a delete's blast radius via GET /api/tasks/impact. For writes use the `task` skill.
+allowed-tools:
+  - Bash(curl *)
+  - Read
+---
+
+# Task Board — see everything in motion
+
+One place to answer two questions the user actually asks:
+
+1. **"What do I have running / set up?"** — a single inventory across every
+   creation path (recurring DMs, Agents, app-fetch managed tasks, pending
+   one-off reminders, and in-flight background / browser / research work).
+2. **"What breaks if I delete / change X?"** — the blast radius, with each
+   affected row labelled by its real cascade.
+
+The board is **read-only and computed on demand** — it stores nothing and
+mirrors nothing. It does **not** replace the proactive reminder surface: pending
+one-off reminders are already injected into your DM context every turn, so use
+the board when the user *asks* to look, not as a standing checklist.
+
+## When to use
+
+- The user asks what's scheduled / running / set up ("show me my agents",
+  "what's running", "do I still have that Zoom sweep?").
+- Before a delete/modify, to tell the user the impact ("if I stop the digest,
+  what goes with it?").
+- To resolve a vague reference ("turn off the morning thing") to a concrete
+  `ref` you can then act on with the `task` skill.
+
+## Inventory — `GET /api/tasks`
+
+```bash
+curl --silent --fail http://localhost:8321/api/tasks
+```
+
+Returns `{ items, total, generatedAt }`. Each item:
+
+| Field | Meaning |
+|---|---|
+| `ref` | typed handle — `rs:<id>` (recurring DM), `mt_<n>` (app-fetch), `agent:<slug>`, `as:<id>` (one-off reminder), `bt:<id>` (background), `bx:<id>` (browser), `cluster:<slug>` (research) |
+| `title` | human label — passed through verbatim from the owning row |
+| `kind` | `dm` / `agent` / `app_fetch` / `reminder` / `background` / `browser` / `research` |
+| `status` | `active` / `paused` / `pending` / a fulfiller state (`running`, `awaiting_user`, …) |
+| `cadence` | human schedule label, or null for one-shot work |
+| `fulfilledBy` | typed ref of the row that actually executes (for `app_fetch`, its `rs:` schedule) |
+| `origin` | `system` / `user` / `agent` |
+| `lastResult`, `lastRunAt`, `nextRunAt` | at-a-glance health, when the owner tracks them |
+
+Summarise naturally; don't read the JSON back verbatim. The `kind` / `status`
+/ `cadence` labels are a fixed English vocabulary; `title` is passed through
+verbatim from the owning row.
+
+## Blast radius — `GET /api/tasks/impact?ref=<ref>`
+
+```bash
+curl --silent --fail "http://localhost:8321/api/tasks/impact?ref=mt_3"
+```
+
+Returns `{ ref, found, summary, nodes }`. Each node is a row a delete/modify
+would touch, with its real cascade semantics:
+
+- `is_a_cascade` — a 1:1 wrapper deleted **with** the target (a managed task and
+  its recurring schedule die together).
+- `set_null_satellite` — an Agent or automation trigger that **references** the
+  schedule and **survives** its deletion.
+- `owner_paired_schedule` — an Agent's **own** recurring schedule (shown when the
+  target is `agent:<slug>`): disabled with the Agent, removed only on hard-delete.
+- `no_action_unlinked` — pending fires that are unlinked/skipped, not deleted.
+- `self` — the target row itself.
+
+`found:false` (still `200`) means the ref resolves to no live row. Lead with the
+`summary`, then list what survives vs what's removed so the user can decide.
+
+## Writes go through the `task` skill
+
+This skill never creates, edits, or deletes. When the user wants to act on a
+board item, hand the resolved `ref` (or a `kind` for a new item) to the **`task`**
+skill, which routes the write to the hardened owner endpoint. Detailed authoring
+(a full recurring Agent, an app-fetch with dedup) still belongs to the
+specialised skills (`agent-create`, `managed-tasks`, `schedule`,
+`background-task`) — `task` is the single front door to them.
+
+## Hard rules
+
+1. **Localhost only.** `http://localhost:8321/api/tasks*`.
+2. **Read-only.** This skill issues only GETs. Never mutate from here.
+3. **Never reactivate a muted/concluded research cluster** by listing it — the
+   board only surfaces active/dormant clusters and `impact` never changes status.
+4. **Never read or relay a browser-task final-confirm token.** The board surfaces
+   only safe fields (`status`/`ref`); a pending `!~xxxxxxxx` token is never shown.

package/agent-assets/skills/browser-history/SKILL.md

@@ -15,7 +15,7 @@ their own destination policy — see the cluster-update flow below.
 ## Hard rules
 
 1. **Localhost only.** Every request goes to
-   `http://127.0.0.1:8321/api/browser-history/*` (or `localhost`).
+   `http://localhost:8321/api/browser-history/*`.
    A curl to any other host is a contract violation and the daemon's
    absolute-block layer will reject it.
 2. **No raw SQLite.** Never invoke `sqlite3`, never `Read` a path under
@@ -75,7 +75,7 @@ so do NOT add an auth header to it.)
 
 ```bash
 curl --silent --show-error \
-  http://127.0.0.1:8321/api/browser-history/research-clusters
+  http://localhost:8321/api/browser-history/research-clusters
 ```
 
 Use `--silent --show-error` (not `--fail`): the agent's `curl` runs
@@ -94,7 +94,7 @@ curl --silent --show-error \
   -X POST \
   -H 'Content-Type: application/json' \
   -d '{"kind":"research_assist"}' \
-  http://127.0.0.1:8321/api/browser-history/offers/quantum-mechanics/accept
+  http://localhost:8321/api/browser-history/offers/quantum-mechanics/accept
 ```
 
 ## Flow: routine.research_cluster_update

package/agent-assets/skills/browser-history-respond/SKILL.md

@@ -87,15 +87,15 @@ pre-summarise.
 
 ```bash
 curl --silent --fail \
-  http://127.0.0.1:8321/api/browser-history/offers/pending
+  http://localhost:8321/api/browser-history/offers/pending
 
 curl --silent --fail -X POST \
   -H 'Content-Type: application/json' \
   -d '{"kind":"research_assist"}' \
-  http://127.0.0.1:8321/api/browser-history/offers/<slug>/accept
+  http://localhost:8321/api/browser-history/offers/<slug>/accept
 
 curl --silent --fail -X POST \
-  http://127.0.0.1:8321/api/browser-history/offers/<slug>/decline
+  http://localhost:8321/api/browser-history/offers/<slug>/decline
 ```
 
 JSON body in single quotes (project convention) so the daemon hooks

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

@@ -21,7 +21,7 @@ B-4 purchase tokens, or workflow approvals — those live under
 
 ## Hard rules
 
-1. **Localhost only.** `http://127.0.0.1:8321/api/browser-task/*`.
+1. **Localhost only.** `http://localhost:8321/api/browser-task/*`.
 2. **POST, ack, end the turn. NEVER poll for completion.** After a
    successful POST, reply once ("Started — I'll report back when it's
    done.") and stop. Do not GET `/:id` in a loop, "wait and check", or
@@ -64,7 +64,7 @@ B-4 purchase tokens, or workflow approvals — those live under
 ```bash
 curl --silent --fail -X POST -H 'Content-Type: application/json' \
   -d '{"description":"Post \"Hello world\" to twitter.com"}' \
-  http://127.0.0.1:8321/api/browser-task
+  http://localhost:8321/api/browser-task
 ```
 
 Body:

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

@@ -25,11 +25,11 @@ user but compound into duplicate DMs/notifications at fire time.
 1. **Agent Plan check.** Scan `<today>` `## Agent Plan` for a row with
    HH:MM within ±15 min of your target AND an overlapping subject. If
    present, the plan is already in place — do NOT add a second one.
-2. **Pending schedule check.** `GET /api/schedule?status=pending,running`
-   and look for an item whose `scheduledFor` is within ±15 min of your
-   target with a matching `description` subject. If found, skip (or
-   PATCH the existing item if it needs updating — never register a
-   parallel second one).
+2. **Pending schedule check.** In a live owner DM pending one-off rows
+   appear in `<scheduled_reminders>` — dedup there and cancel/PATCH any
+   the conversation made moot. Else `GET
+   /api/schedule?status=pending,running` for one within ±15 min with a
+   matching `description`; if found, skip or PATCH.
 3. **Recurring check.** `GET /api/recurring-schedules?enabled=true` to
    confirm no recurring rule/Agent already covers this cadence (e.g. a
    daily 09:00 inbox triage, or the morning briefing). If covered, skip.
@@ -74,14 +74,16 @@ record, create the recurring work/DM per the "Recurring" section below.
 
 > **The wake-up agent has NO memory of why it was scheduled.** A `scheduled.task` session is self-contained: it receives only `state/today.md` (which carries the day's schedule and state) plus the `prompt` + `taskContext` you provide — **NOT** `identity/profile.md` or `policies/management.md` (the `scheduled.task` injection policy opts those out). Nothing else. (`description` is just an optional list label — never the agent body.)
 
-Include all four elements in the `prompt`:
+Author the `prompt` with the **core frame** below. A one-shot task rarely needs the
+extended (operational) sections; if a one-shot *does* mutate code or state, add two
+sections on top of the core frame — `# Scope` (WHERE it may act: the editable
+surface, and what it must not touch) and `# Verification` (which checks confirm the
+change is good, and "don't claim success unless they passed").
 
-| Element | What it answers |
-|---|---|
-| **What** | Specific verb + object (notify, check, update, prepare) |
-| **Why** | The trigger or reason (meeting approaching, deadline, user request) |
-| **Who/What** | Concrete names, IDs, URLs, filenames |
-| **Expected output** | What "success" looks like (notification sent, file updated) |
+{{> ref:prompt-frame }}
+
+For a simple one-shot — a timed reminder — the frame collapses to one tight,
+self-contained brief:
 
 **Good:** `"15-minute reminder for the 14:00 design review. Attendees: Sarah, Mike. Agenda: API v2 breaking changes. Prepare the meeting-note template and notify the user via Slack."`
 
@@ -165,7 +167,7 @@ curl -s -X PATCH http://localhost:8321/api/schedule/42 \
   -H 'Content-Type: application/json' \
   -d '{"time":"2026-04-06T17:00:00-04:00"}'
 ```
-Fields: `time` (ISO 8601), `prompt` (the agent instruction, ≤8000 chars, non-dm only, OR `null` to clear on a legacy row), `description` (optional label ≤200 chars, non-dm only), `message` (dm only), `tier` (`lite`/`medium`/`high` OR `null` to clear), `model` (registered id / alias / composite OR `null` to clear), `taskContext`. At least one required. Only `pending` items editable. `description`/`message` mutually exclusive; `prompt`/`message` mutually exclusive. Tier ↔ model swap form is in the model-selection reference above. Response: `{ "status":"updated", "id":42, "warnings":[] }` / 404 / 409 — surface `warnings[]` (e.g. `schedule.model_deprecated`) to the next turn.
+Fields: `time` (ISO 8601), `prompt` (the agent instruction, ≤8000 chars, non-dm only — cannot be cleared; a row must always carry a non-empty prompt), `description` (optional label ≤200 chars, non-dm only), `message` (dm only), `tier` (`lite`/`medium`/`high` OR `null` to clear), `model` (registered id / alias / composite OR `null` to clear), `taskContext`. At least one required. Only `pending` items editable. `description`/`message` mutually exclusive; `prompt`/`message` mutually exclusive. Tier ↔ model swap form is in the model-selection reference above. Response: `{ "status":"updated", "id":42, "warnings":[] }` / 404 / 409 — surface `warnings[]` (e.g. `schedule.model_deprecated`) to the next turn.
 
 ### GET /api/schedule — List scheduled items
 ```bash

package/agent-assets/skills/schedule/references/batch.md

@@ -57,7 +57,7 @@ curl -s -X POST http://localhost:8321/api/schedule/batch \
 | `rows[].taskContext.sub_flow` | No | Branches the task-flow rendering when the dispatcher needs a specialised sub-flow. |
 | `rows[].taskPrompt` | No | Override for the agent body (min 20 chars when set). |
 | `rows[].correlationId` | No | Defaults to the morning routine's correlation id when omitted. |
-| `rows[].model` | No | Registered model id (`claude-opus-4-8`, `claude-sonnet-4-6`, `gpt-5.4`, `gemini-3.1-pro-preview`, …), legacy alias (`sonnet` / `opus` — auto-rewritten to `tier`), composite `<backendId>/<modelId>`, or `null`. Mutually exclusive with `rows[].tier`. Omit both to let `process_backend_config` decide. |
+| `rows[].model` | No | Registered model id (`claude-opus-4-8`, `claude-sonnet-5`, `gpt-5.4`, `gemini-3.1-pro-preview`, …), legacy alias (`sonnet` / `opus` — auto-rewritten to `tier`), composite `<backendId>/<modelId>`, or `null`. Mutually exclusive with `rows[].tier`. Omit both to let `process_backend_config` decide. |
 | `atomic` | No | `true` (default) wraps inserts in one transaction — any row error rolls back all. `false` commits successful rows individually. |
 
 ## Success

package/agent-assets/skills/schedule/references/model-selection.md

@@ -25,7 +25,7 @@ even after `/settings/models` re-routes the process key). The two are
   route to `tier:"medium"` / `tier:"high"`; the alias is not stored
   verbatim.
 - **Registered model ids** — any id from `MODEL_REGISTRY` across the
-  four backends. Examples: `claude-opus-4-8`, `claude-sonnet-4-6`,
+  four backends. Examples: `claude-opus-4-8`, `claude-sonnet-5`,
   `claude-haiku-4-5-20251001`, `gpt-5.4`, `gemini-3.1-pro-preview`.
   The row persists `(model, backend_id)` together so the dispatcher
   honors the pin at fire time.

package/agent-assets/skills/schedule/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/task/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: task
+description: Unified write facade for tracked work — create/edit/delete any task through one path. POST /api/tasks {kind: reminder|dm|agent|app_fetch|background}; PATCH/DELETE /api/tasks/<ref>. Forwards to the hardened owners (dedup, cascade, dm_session split intact).
+allowed-tools:
+  - Bash(curl *)
+---
+
+# Task — one path to create, edit, or delete any tracked work
+
+Instead of choosing among six creation skills, route every write through
+`/api/tasks`. The facade **forwards** your request to the existing hardened
+owner endpoint by `kind` (create) or ref prefix (edit/delete) — it never
+re-implements them, so each owner's dedup, FK cascade, validation, the
+`dm_session` recurring split, and auth tier all still apply unchanged.
+
+Pair it with the **`board`** skill (read inventory + blast-radius).
+
+## Create — `POST /api/tasks`
+
+Send `{ "kind": "...", ...ownerFields }`. The facade strips `kind` and forwards
+the rest to the owner, so **provide the owner's own fields** (it does not rename
+them). Pick the kind:
+
+| `kind` | Routes to | Provide | Detailed authoring skill |
+|---|---|---|---|
+| `reminder` | `POST /api/schedule/dm` | `time` (ISO8601), `message` | `schedule` |
+| `dm` | `POST /api/recurring-schedules` | `description` (≥20), `recurrenceRule`, `prompt?` (task_type is pinned to `dm_session`) | `schedule` |
+| `agent` | `POST /api/agents` | `slug`, `name`, `schedule` (`{kind:"recurring",recurrence}` or `{kind:"cron",expression}`), `prompt?` | `agent-create` |
+| `app_fetch` | `POST /api/managed-tasks` | `intent`, `app`, `cadence`, `recurrenceRule`, `output_path?` (send an `Idempotency-Key` header) | `managed-tasks` |
+| `background` | `POST /api/background-task` | `brief`, `title?`, `notificationPolicy?` | `background-task` |
+
+```bash
+curl --silent --fail -X POST -H 'Content-Type: application/json' \
+  -d '{"kind":"reminder","time":"2026-07-01T15:00:00+09:00","message":"call the dentist"}' \
+  http://localhost:8321/api/tasks
+```
+
+For anything beyond the simple case — authoring a full recurring Agent, an
+app-fetch where dedup / output-path shape matter, a self-contained background
+brief — open the **detailed skill** in the last column for its field rules, then
+either POST through that skill directly or mirror its body here. The facade is
+the front door; the specialised skills are the manual.
+
+## Edit / delete — `PATCH` / `DELETE /api/tasks/<ref>`
+
+Address the row by its typed `ref` from the board (`rs:<id>`, `mt_<n>`,
+`agent:<slug>`, `as:<id>`). PATCH forwards your patch body to the owning edit
+endpoint; DELETE forwards to the owning delete (cascade preserved).
+
+```bash
+curl --silent --fail -X PATCH -H 'Content-Type: application/json' \
+  -d '{"enabled":false}' http://localhost:8321/api/tasks/rs:42
+
+curl --silent --fail -X DELETE http://localhost:8321/api/tasks/mt_3
+```
+
+## Response envelope
+
+Every dispatch returns the owner's HTTP status with
+`{ ok, dispatchedTo, kind, result }` — `result` is the owner's own body
+(e.g. `{ status:"created", item }`). Read `result` for ids and warnings.
+
+## Hard rules
+
+1. **Localhost only.** `http://localhost:8321/api/tasks*`.
+2. **A `dm` create is always a `dm_session` row.** You cannot create recurring
+   autonomous *work* through `kind:"dm"` — that is `kind:"agent"`. The facade
+   enforces this (it never opens the 410'd recurring agent-task door, and never
+   stamps an agent id onto a schedule).
+3. **Editing/deleting an Agent is privileged.** `agent:<slug>` routes to
+   `/api/agents`, which may require the dashboard's authorization — a `401` means
+   it needs human approval, exactly as editing the Agent directly does. Built-in
+   Agents are undeletable (`409`); stopping one needs the stop-warning ack.
+4. **Fulfillers are read-only here.** `bt:` / `bx:` / `cluster:` refs return
+   `422` — manage them on their own surfaces; never resume a force-failed browser
+   task or surface a pending `!~` confirm token.
+5. **Preview destructive changes first.** For a delete/modify the user may not
+   fully grasp, run `GET /api/tasks/impact?ref=<ref>` (the `board` skill) and
+   confirm the blast radius before acting.