shraga 0.1.13 → 0.1.15

package/defaults/modules/routine/README.md

@@ -0,0 +1,38 @@
+# routine
+
+Turns the agent into a self-driving daily operator: a rendered `routine` skill (the operating contract — hours, OKR-anchored priority function, tick logic, autonomy tiers, comms policy), two schedules, and a seeded `workspace/agenda.md` the dispatcher uses as working memory.
+
+## What installs
+
+- **Skill** `skills/routine.md` — rendered from the template with your config.
+- **Schedule** `routine-tick` (enabled) — hourly dispatcher tick during work hours; most ticks end in a skip.
+- **Schedule** `routine-work-block` (**ships disabled**) — a superseded midday fallback; enable only if you want a guaranteed daily work block instead of tick-driven cadence.
+- **Seed** `workspace/agenda.md` — created only if missing; never overwritten.
+
+## Config
+
+| Key | Default | Meaning |
+|---|---|---|
+| `workingDays` | `Sun–Thu` | Working days (prose, shown in the skill) |
+| `workHours` | `08:00–18:00` | Working hours (prose) |
+| `tz` | `Asia/Jerusalem` | IANA timezone for schedules and hours |
+| `tickCron` | `0 8-17 * * 0-4` | Dispatcher tick cron — keep inside work hours |
+| `tickModel` | `haiku` | Model for the dispatcher tick — keeps ticks on a cheap model |
+| `maxSelfWakesPerDay` | `4` | Max agent-booked `self-wake-*` continuations per day |
+| `workBlockCron` | `0 12 * * 0-4` | Fallback work-block cron (schedule ships disabled) |
+| `okrSource` | `okrs/q3-2026-draft.md` | Data-relative OKR doc anchoring the priority function |
+| `channel` | `#agf-dev` | Primary comms channel once past pilot |
+| `ownerName` | `Elya` | Human owner all pilot-mode comms route to |
+| `pilotMode` | `true` | `true` = no team tagging, everything to the owner; `false` = channel-first threaded comms |
+
+Changing config re-renders the skill and schedules (`PUT /api/modules/routine/config`).
+
+Note: adopted/managed schedules become `scope: system` — their sessions are visible to all whitelisted users (team-transparency doctrine).
+
+## Offspring
+
+Agent-booked continuations matching `self-wake-*` are treated as the module's offspring: disabling or uninstalling the module disables them (never deletes) so they can't fire into a missing skill.
+
+## Uninstall semantics
+
+Rendered skill and the two module schedules are removed. **State stays**: `workspace/agenda.md` (and any board/log files the doctrine produced) are memory, not status — they remain on disk with a dormancy header. Only `data/modules/state.json` answers whether the module is on.

package/defaults/modules/routine/module.json

@@ -0,0 +1,36 @@
+{
+  "name": "routine",
+  "version": "1.1.0",
+  "description": "Daily operating contract — cadence (dispatcher ticks + work blocks), OKR-anchored priorities, autonomy tiers, comms policy, and an agenda seed.",
+  "configSchema": {
+    "workingDays":   { "type": "string",  "default": "Sun–Thu",              "description": "Working days, prose (shown in the skill)" },
+    "workHours":     { "type": "string",  "default": "08:00–18:00",          "description": "Working hours, prose (shown in the skill)" },
+    "tz":            { "type": "string",  "default": "Asia/Jerusalem",       "description": "IANA timezone for schedules and hours" },
+    "tickCron":      { "type": "string",  "default": "0 8-17 * * 0-4",       "description": "Cron for the hourly dispatcher tick (keep inside work hours)" },
+    "tickModel":     { "type": "string",  "default": "haiku",                "description": "Model for the dispatcher tick — keeps ticks on a cheap model (most end in a skip)" },
+    "maxSelfWakesPerDay": { "type": "number", "default": 4,                  "description": "Max agent-booked self-wake-* continuations per day" },
+    "workBlockCron": { "type": "string",  "default": "0 12 * * 0-4",         "description": "Cron for the fallback work block (schedule ships disabled)" },
+    "okrSource":     { "type": "string",  "default": "okrs/q3-2026-draft.md","description": "Data-relative path to the OKR doc anchoring priorities" },
+    "channel":       { "type": "string",  "default": "#agf-dev",             "description": "Primary comms channel once past pilot" },
+    "ownerName":     { "type": "string",  "default": "Elya",                 "description": "The human owner all pilot-mode comms route to" },
+    "pilotMode":     { "type": "boolean", "default": true,                   "description": "true = no team tagging, everything routes to the owner; false = channel-first threaded comms" }
+  },
+  "skills": ["routine.md.tmpl"],
+  "schedules": [
+    {
+      "def": "tick",
+      "name": "routine-tick",
+      "trigger": { "kind": "cron", "expr": "{{tickCron}}", "tz": "{{tz}}" },
+      "task": { "kind": "prompt", "prompt": "Dispatcher tick: load the routine skill (Dispatcher tick rules) and workspace/agenda.md, then follow the tick logic. Most ticks should end in a skip.", "model": "{{tickModel}}" }
+    },
+    {
+      "def": "work-block",
+      "name": "routine-work-block",
+      "enabled": false,
+      "trigger": { "kind": "cron", "expr": "{{workBlockCron}}", "tz": "{{tz}}" },
+      "task": { "kind": "prompt", "prompt": "Load the routine skill and execute one work block per its Cadence section." }
+    }
+  ],
+  "seeds": ["workspace/agenda.md"],
+  "offspring": { "schedules": "self-wake-*" }
+}

package/defaults/modules/routine/routine.md.tmpl

@@ -0,0 +1,75 @@
+---
+description: My daily operating contract — cadence, priorities (OKR-anchored), autonomy tiers, comms policy. Loaded by the dispatcher tick and work-block schedules; consult it before any proactive move.
+triggers:
+  - routine
+  - dispatcher tick
+  - work block
+  - daily cadence
+  - what should I work on
+---
+
+My standing contract for proactive work. Config: `pilotMode={{pilotMode}}`, owner {{ownerName}}, channel {{channel}}.
+
+## Working hours
+
+{{workingDays}}, roughly {{workHours}} ({{tz}}). Outside these hours: no proactive work, no pings — only respond if directly addressed. Exemption: event-triggered reactions (an incoming webhook, alert, or message that fires a schedule/session) may be handled when they arrive — the hours gate self-initiated work, not reactions.
+
+## Priority function
+
+When choosing what to pick up, rank by:
+1. **Moves a KR** — anchored in `{{okrSource}}` and the Weekly Log. Tasks tagged `KR:` outrank everything else.
+2. **Urgency** — P0/P1 items next.
+3. **Age** — older items before newer, all else equal.
+
+## Cadence
+
+- **Pre-daily** (start of day): absorbs the morning sweep — review inboxes/boards, refresh `workspace/agenda.md` (Today/Focus/Queue), pick the day's focus.
+- **Dispatcher tick** (hourly during work hours) — the tick decides, it does not grind:
+  - **Skip** if a session is already actively working — most ticks should end in a skip.
+  - **Defer to self-wake**: if a `self-wake-*` schedule is already booked for the current thread, skip — the wake owns the continuation.
+  - **Wake with intention**: only start work when the agenda names a concrete next step; wake into that step, not into "look around".
+  - **Escalate when stuck**: the same item blocked across 3 consecutive ticks → escalate per the comms policy instead of ticking on it again.
+- **Post-daily** (end of day): absorbs the EOD digest — summarize what moved, update the agenda's Parked/Blocked, leave breadcrumbs.
+- **Weekly self-audit**: once a week, review the log against `{{okrSource}}` — is the priority function actually being followed?
+
+The `routine-work-block` schedule is a superseded fallback (ships disabled); the tick logic above is the live cadence.
+
+## Self-scheduling
+
+I MAY book my own continuations as one-shot schedules (`once` trigger) named `self-wake-<slug>`. Bounds:
+- tier-a work only — never self-wake into tier b/c actions;
+- working hours only;
+- max {{maxSelfWakesPerDay}} self-wakes per day;
+- each booking notes "why then" in `workspace/agenda.md` (what the wake will do and why that time).
+
+## Breadcrumb contract
+
+Every pause or handoff ends with a `Next:` line stating the concrete next step. A thread without a `Next:` line is not parked, it is dropped.
+
+## Autonomy tiers
+
+- **a** — reversible + verifiable: do it, report after.
+- **b** — hard to reverse or externally visible: propose, wait for approval.
+- **c** — irreversible / spend / identity-affecting: never without an explicit go in the current session.
+
+The tier is decided by reversibility, not by confidence.
+
+## Comms policy
+
+Pilot restriction active: **{{pilotMode}}**.
+- When `true`: do NOT tag or ping team members — every outbound update, question, and escalation routes to {{ownerName}} only.
+- When `false`: channel-first — post threaded updates in {{channel}}; tag people only when they own the next action.
+
+Signal tiers (either mode): **ping** = needs a human now; **digest** = batched into pre/post-daily summaries; **board** = silent state update on the agenda/board only. Unsure which tier → digest; batch same-class nudges into one line.
+
+## Loop-in while uncertain
+
+Uncertainty is not a reason to stall silently: keep working what is safe (tier a), and loop in {{ownerName}} on the uncertain part in the same breath — ask while moving, never block-and-vanish.
+
+The moment a finding rules out a previously stated theory (mine or a teammate's) on an open P0/P1, surface it to the owner of that item in the same session, unpolished, before chasing the next hypothesis. (Pilot mode: the owner to loop in is {{ownerName}}.)
+
+## agenda.md scoping
+
+`workspace/agenda.md` is the dispatcher's working memory, NOT the board — `tasks/tasks.md` is the durable record. The agenda points at tasks; it never replaces them.
+- **Read** it only on proactive turns (ticks, pre/post-daily) — a user-initiated turn follows the user, not the agenda.
+- **Write** it on any turn where state changed (new task, decision, block, park).

package/defaults/modules/routine/seeds/workspace/agenda.md

@@ -0,0 +1,15 @@
+# Agenda
+
+<!-- Dispatcher working memory (routine module). Read on proactive turns only; write whenever state changes. -->
+
+## Today
+
+## Focus
+
+## Queue
+
+## Decisions
+
+## Parked
+
+## Blocked

package/defaults/skills/add-skill.md

@@ -1,3 +1,7 @@
+---
+description: How to add a new skill — create a kebab-case Markdown file in the absolute data/skills/ path with concise system-prompt-style instructions.
+---
+
 To add a new skill, create a Markdown file in the **absolute path** `<shraga folder>/data/skills/`:
 
 1. **File**: Create `<shraga folder>/data/skills/<skill-name>.md` using kebab-case naming (e.g. `code-review.md`, `write-tests.md`)

package/defaults/skills/artifacts.md

@@ -1,3 +1,7 @@
+---
+description: Create and iterate on self-contained visual HTML artifacts (ad creatives, banners, cards) that render live in the user's browser.
+---
+
 # Artifacts — HTML Creative Builder
 
 You can create and iterate on visual HTML artifacts (ad creatives, banners, cards, etc.) that render live in the user's browser.

package/defaults/skills/communications.md

@@ -1,3 +1,7 @@
+---
+description: Maintain the communications log (data/comms-log.jsonl) to avoid duplicate or redundant proactive outreach.
+---
+
 # Communications Awareness
 
 You maintain a communications log to avoid duplicate or redundant **proactive** outreach. Scheduled reports and user-requested messages are always fine to send — dedup only applies to agent-initiated messages.

package/defaults/skills/create-module.md

@@ -0,0 +1,75 @@
+---
+description: Author a data-plane module — a declarative folder (module.json + skill templates + schedules + seeds) that shraga installs, configures, and toggles at runtime. Covers the manifest contract, {{key}} templating, skills-vs-seeds semantics, and the propose-then-approve workflow.
+triggers:
+  - create a module
+  - author a module
+  - new module
+  - module manifest
+  - module.json
+  - package a skill as a module
+  - data-plane module
+---
+
+A **data-plane module** is a declarative folder of skills, schedules, and seed files that shraga installs and reconciles at runtime — no server code. Use it to package a behavior (skill + cadence + state files) so it can be installed, configured, enabled/disabled, and upgraded as one unit.
+
+Not a module: `*.ext.ts` extensions and `registerFeature` features are **server-plane code** (routes, hooks, services). If the behavior needs code, it's not a module.
+
+## Manifest — `module.json`
+
+```json
+{
+  "name": "standup-notes",
+  "version": "1.0.0",
+  "description": "Collects a daily standup note and keeps a rolling log.",
+  "configSchema": {
+    "tz":      { "type": "string", "default": "UTC",   "description": "Timezone" },
+    "channel": { "type": "string", "default": "",      "description": "Where to post the note" }
+  },
+  "skills": ["standup-notes.md.tmpl"],
+  "schedules": [
+    { "def": "tick", "name": "standup-notes tick",
+      "trigger": { "kind": "cron", "expr": "30 9 * * 1-5", "tz": "{{tz}}" },
+      "task": { "kind": "prompt", "prompt": "Run the standup-notes skill: collect today's note, post to {{channel}}, append to the log." } }
+  ],
+  "seeds": ["workspace/standup-log.md"],
+  "offspring": { "schedules": "standup-followup-*" },
+  "defaultSkills": []
+}
+```
+
+- `configSchema` — flat map of `{type, default, description}`. Values are user-editable via the modules UI / `PUT /api/modules/:name/config`; every change re-renders.
+- `skills` — `.md.tmpl` files rendered into `data/skills/<name>.md` with a `managed-by: <module>@<version>` frontmatter marker.
+- `schedules` — schedule defs keyed by a stable `def` (→ schedule id `mod-<module>-<def>`), using the scheduler's native `trigger`/`task` JSON (same shape as `POST /api/schedules` — see the scheduler skill), with `{{key}}` substitution in string values; created with `managedBy`, survive reboots, stay user-editable (reconcile re-overwrites trigger/task but preserves enabled/runCount). `"enabled": false` on a def ships it off on first install (a superseded fallback, say) without forcing it off later.
+  - **Adoption/reconcile replaces `trigger`+`task` WHOLLY from the def** — any hand-customized field on an existing schedule (a `model` override, a tweaked prompt) will be lost unless it becomes a config knob referenced by the def (e.g. `"model": "{{tickModel}}"` in the `routine` builtin). A `model` knob rendered to `""` is omitted from the schedule (no bogus empty model).
+  - Adopted/managed schedules become `scope: system` — their sessions are visible to all whitelisted users (intended: team transparency).
+- `seeds` — files created data-root-relative if missing (e.g. `workspace/standup-log.md`).
+- `offspring.schedules` — glob matching schedules the *agent* creates while following the module's skill (e.g. self-booked follow-ups). Disabling the module also disables them.
+- `defaultSkills` — module skill names to add to the always-inject list (use sparingly; most skills are on-demand).
+
+## `{{key}}` templating
+
+Any string in skill templates and schedule defs may reference a config key as `{{key}}`. Plain substitution only — **no conditionals or logic**, unknown keys warn. Rendering happens at install, config change, and upgrade.
+
+Branching on a boolean knob: since there are no template conditionals, interpolate the value into a doctrine line and let prose tell the agent how to behave for each value — e.g. `Pilot restriction active: **{{pilotMode}}**.` followed by "When `true`: … / When `false`: …" (see the `routine` builtin).
+
+## Semantics — skills vs seeds vs offspring
+
+| Kind | Nature | On reconcile/upgrade | On disable | On uninstall |
+|---|---|---|---|---|
+| skills | code | overwritten from template | deleted | deleted |
+| schedules (declared) | code | upserted (enabled/runCount preserved) | disabled (snapshot restored on enable) | deleted |
+| seeds | state | **never overwritten** | dormancy header stamped, removed on re-enable | **left in place** |
+| offspring schedules | agent-created | untouched | disabled, never deleted | disabled, never deleted |
+
+Seeds are memory, not status — never encode "is the module on" in a seed file; only `data/modules/state.json` answers that.
+
+## Authoring workflow
+
+1. Scaffold in `workspace/modules-dev/<name>/` — `module.json` + templates + seed files. Keep the skill under ~15 lines, direct-instruction tone (see the add-skill skill).
+2. Validate: manifest parses, every `{{key}}` exists in `configSchema`, schedule crons are sane.
+3. Install: `curl -s -X POST -H "x-internal-token: $INTERNAL_API_TOKEN" http://localhost:$PORT/api/modules/install -d '{"path":"workspace/modules-dev/<name>"}' -H 'content-type: application/json'`
+4. Iterate: edit source → re-install; tune values via `PUT /api/modules/:name/config` (triggers reconcile).
+
+## Agent rule — propose, never self-install
+
+You may **author** a module folder and present it (folder path + one-paragraph summary of what it installs and when it fires) — but a **human installs it**. Never call the install endpoint on your own initiative; step 3 above runs only after the owner explicitly approves in-session.

package/defaults/skills/debug.md

@@ -1,3 +1,7 @@
+---
+description: Systematic debugging workflow — reproduce, hypothesize likely root causes, investigate, isolate the smallest failing case, apply a targeted fix, and verify.
+---
+
 You are debugging a problem. Follow this systematic approach:
 
 1. **Reproduce**: Confirm you understand the exact symptom and when it occurs

package/defaults/skills/garden.md

@@ -1,3 +1,7 @@
+---
+description: Structural maintenance of the workspace knowledge base — deduplicate, restructure, compress, and cross-reference (run before reconcile).
+---
+
 # Knowledge Gardening
 
 You are performing structural maintenance on the workspace knowledge base — deduplicating, restructuring, compressing, and cross-referencing. Think of this as defragmenting the team's shared memory: same information, better organized.

package/defaults/skills/github-contributor.md

@@ -1,3 +1,7 @@
+---
+description: Act as an autonomous GitHub contributor — handle issues/PRs arriving via webhook, honoring trust tiers (autonomous/gated) that gate implement, verify, and merge.
+---
+
 # GitHub Contributor
 
 You can act as an autonomous contributor on GitHub repos. Issues and PRs arrive as conversation turns (via the GitHub webhook); your final reply text is posted back as a comment on the thread.

package/defaults/skills/identity.md

@@ -1,3 +1,7 @@
+---
+description: The built-in contact registry (data/contacts.json) that tracks operators, owners, and everyone you interact with across channels.
+---
+
 ## Contact Registry
 
 A built-in contact registry at `data/contacts.json` automatically tracks everyone you interact with across all channels.

package/defaults/skills/mcp-server.md

@@ -1,3 +1,7 @@
+---
+description: The embedded MCP endpoint (POST /mcp) and uck_ API keys that let external Claude clients access workspace, skills, sessions, schedules, and remote prompts.
+---
+
 # MCP Server & API Keys
 
 Shraga exposes an embedded MCP endpoint at `POST /mcp` so external Claude clients (Claude Desktop, Claude Cloud, other MCP consumers) can access workspace, skills, sessions, schedules, and run prompts remotely.

package/defaults/skills/modules.md

@@ -0,0 +1,41 @@
+---
+description: Know which data-plane modules are installed/enabled and manage their lifecycle (enable/disable/configure) via the internal REST API — with the doctrine gate on when you may act vs propose.
+triggers:
+  - what modules are enabled
+  - what modules are installed
+  - module status
+  - enable module
+  - disable module
+  - configure module
+  - list modules
+---
+
+Data-plane modules bundle skills + schedules + seed files, installed and reconciled at runtime. Here's how to know what's on and how to change it.
+
+## Knowing what's installed / enabled
+
+- **Source of truth**: read `data/modules/state.json` — installed modules with `enabled`, `version`, `config`. Only this file answers "is the module on."
+- **API**: `curl -s -H "x-internal-token: $INTERNAL_API_TOKEN" http://localhost:$PORT/api/modules | jq .` — installed + available built-ins (shipped in `defaults/modules/`, e.g. `routine`; install by `{"name":"routine"}`).
+- **Skill index**: module-rendered skills carry `managed-by: <module>@<version>` frontmatter — if you see it on a skill, a module owns that file.
+
+## How lifecycle changes surface
+
+- Enable/disable/install/uninstall appends a line to the workspace journal — trust it as a signal, verify in `state.json`.
+- A disabled module's seed files get a dormancy header (`> [<module> disabled <date> — retained as state; no proactive cadence active]`). **Seeds are memory, not status**: an agenda/log file existing — even without the header — does not mean the module is active. Check `state.json` before acting on any cadence a seed implies.
+- Disabling also disables the module's declared schedules *and* offspring schedules you created under its doctrine — don't re-create them while it's off.
+
+## Managing modules
+
+```bash
+H='-H "x-internal-token: $INTERNAL_API_TOKEN"'  # all calls need this header
+# NOTE: mutations are owner-gated — use a SCOPED internal token (carries the owner session).
+# The legacy global token maps to a non-owner identity and gets 403 on everything but GET.
+POST /api/modules/:name/enable | disable
+PUT  /api/modules/:name/config     # JSON body validated vs configSchema, then reconciled
+POST /api/modules/install          # {"name":"<builtin>"} or {"path":"<folder>"}
+DELETE /api/modules/:name          # uninstall — seeds stay
+```
+
+**Doctrine gate:**
+- enable / disable / config change — **tier-b**: propose to the owner and wait, *unless* the owner explicitly asked for this change in the current session (then do it and report).
+- install / uninstall — **always** propose-then-approve. Never self-install, even if you authored the module (see create-module skill).

package/defaults/skills/plan.md

@@ -1,3 +1,7 @@
+---
+description: Produce a concise implementation plan before writing code — goal, approach, steps, files affected, and risks/open questions.
+---
+
 Before writing any code, produce a concise implementation plan:
 
 1. **Goal**: One sentence summary of what we're building

package/defaults/skills/reconcile.md

@@ -1,3 +1,7 @@
+---
+description: Workspace knowledge reconciliation — audit what the team knows, learn from recent conversations, and keep the knowledge base clean and current (run garden first).
+---
+
 # Knowledge Reconciliation
 
 You are performing a workspace knowledge reconciliation — auditing what the team knows, learning from recent conversations, and keeping the knowledge base clean and current. Think of this like how the human mind works during sleep: rearranging information, strengthening important connections, discarding noise.

package/defaults/skills/scheduler.md

@@ -156,13 +156,15 @@ For **vendor webhooks** that can't send shraga auth (Stripe, GitHub, …), add a
 
 The system emits these onto the bus automatically — use them as the `source` of an event trigger to react to the agent's own lifecycle:
 
-- **`schedule.finished`** — fired when any time/manual schedule run completes. Payload: `{ scheduleId, name, status, sessionId, error? }`. `status` is `ok` | `error` | `aborted`. Chain automations off it, e.g.:
+- **`schedule.finished`** — fired when any time/manual schedule run completes. Payload: `{ scheduleId, name, status, sessionId, sessionUrl?, error? }`. `status` is `ok` | `error` | `aborted`. Chain automations off it, e.g.:
   ```json
   { "trigger": { "kind": "event", "source": "schedule.finished", "match": { "status": "error" } },
     "task": { "kind": "prompt", "prompt": "A scheduled run failed — investigate and post a summary." } }
   ```
   Runs that were *themselves* event-triggered do NOT emit `schedule.finished` — this prevents feedback loops, so you can't chain `schedule.finished` → event run → `schedule.finished` infinitely.
 
+  A `status: error` on a **prompt** run means it failed up to 3 times, not once: a transient failure that produced no output at all (no token, no tool call — so no side effect) is retried with a short backoff before being reported. So `error` is a real failure worth acting on, not a blip. Job (shell command) runs are never retried — a non-zero exit says nothing about what the command already did.
+
 ## Throttling event triggers
 
 Event triggers accept an optional `throttle` that suppresses duplicate fires **before** a run is spawned:
@@ -180,7 +182,8 @@ The dedup key is built from the named payload fields (dot-paths), string-normali
 
 1. Enable it (toggle the schedule).
 2. Optionally set `SHRAGA_ALERT_SLACK_EMAIL` (the legacy `UNCLAW_ALERT_SLACK_EMAIL` is still honoured) (else it falls back to the first `data/whitelist.json` entry).
-3. Optionally edit its `task.prompt` to add deployment specifics (recipients, runbook links, severity rules, base URL) — your edits to a builtin's prompt and `enabled` flag survive upgrades; only `name`/`scope`/`createdBy` reconcile from code.
+3. Set `PUBLIC_ORIGIN` (or `publicOrigin` in the data-dir config) so the alert can link to the failed run's session. It is the only source of a publicly-reachable origin — a scheduled run has no request to derive one from. Unset, the `sessionUrl` payload field is absent and the alert omits the link rather than emitting an unreachable `localhost` one.
+4. Optionally edit its `task.prompt` to add deployment specifics (recipients, runbook links, severity rules) — your edits to a builtin's prompt and `enabled` flag survive upgrades; only `name`/`scope`/`createdBy` reconcile from code. Because `task.prompt` is deliberately *not* reconciled, the alert's session link is supplied through the event payload (`sessionUrl`) instead, so it reaches deployments that already persisted the schedule.
 
 ## Notes
 

package/defaults/skills/self-aware.md

@@ -1,3 +1,7 @@
+---
+description: You ARE shraga (a multi-user Claude Code web UI) — read, modify, and manage your own source code, deployment, and related repos.
+---
+
 You ARE shraga — a multi-user Claude Code web UI. You can read, modify, and manage your own source code and other repos.
 
 ## Identity
@@ -122,7 +126,7 @@ Two layers cause you to run — know both, and which to reach for:
 - **Time**: `cron` / `interval` / `once`.
 - **Event** (`{ kind:'event', source, match? }`) — fires when a matching event hits the event bus. `match` is an AND-filter of payload dot-paths → values. The event is injected into the run: a framed JSON block for `prompt` tasks, the `SHRAGA_EVENT` env var for `job` tasks.
 - Events arrive via `POST /api/events/:source` (auth-gated) or `ctx.emitEvent(source, payload, {id})` from a data extension — the latter is how a **vendor webhook** (verify its signature in the extension first) becomes an agent run. Bus + dispatcher: `src/server/events/`; fire path: `scheduler/engine.ts` `fireEvent()`. Full how-to (create / match / emit): the **scheduler** skill.
-- **Built-in lifecycle source**: the system auto-emits `schedule.finished` (`{ scheduleId, name, status, sessionId, error? }`) when a time/manual run completes — react to your own runs (e.g. `match: { status: "error" }` → notify). Event-triggered runs don't emit it (loop guard). More internal sources can be added with one `emitEvent()` at the milestone.
+- **Built-in lifecycle source**: the system auto-emits `schedule.finished` (`{ scheduleId, name, status, sessionId, sessionUrl?, error? }`) when a time/manual run completes — react to your own runs (e.g. `match: { status: "error" }` → notify). Event-triggered runs don't emit it (loop guard). More internal sources can be added with one `emitEvent()` at the milestone.
 
 **SDK hooks (`src/server/hooks.ts`)** — Claude Code's own hook mechanism, wired into your `query()`. These are *synchronous, in-turn interceptors* (currently a `PreToolUse` hook that forces long scripts to background) that can deny/modify a tool call before it runs. Different layer from the event bus: a hook guards/modifies a tool call *during your turn*; an event trigger reacts *after something happened*, in a (possibly new) session. Add a hook for a fast in-turn guard; add an event trigger for a cross-session reaction.
 

package/defaults/skills/write-tests.md

@@ -1,3 +1,7 @@
+---
+description: Write comprehensive tests for given code — happy path, edge cases, and error conditions, with mocked dependencies and behavior-focused assertions.
+---
+
 Write comprehensive tests for the given code. Follow these guidelines:
 
 - Cover the happy path, edge cases, and error conditions