Work Buddy Knowledge Handbook¶

This documentation is auto-generated from the knowledge store.

525 units across 4 types:

concept: 83
directions: 69
integration: 15
reference: 11
service: 5
skill: 275
system: 44
workflow: 23

Architecture¶

Architecture & Repo Structure concept — Repository layout, subsystem organization, and development conventions
Account-backed Agent Execution concept — Provider-neutral execution of long-running agents through locally authenticated Claude Code and Codex hosts, with server-authoritative model discovery and conversation-scoped provenance.
Artifact System reference — Shared lifecycle infrastructure for any persisted resource — pluggable Storage × Lifecycle × Provenance composition with skill declarations.
Data Backups concept — Local and opt-in off-machine restore coverage for ordinary vital SQLite databases and portable Truth payloads, plus local-only authorized Journal/Sources checkpoints.
Backup Now Directions directions — Take an immediate manual snapshot of work-buddy's vital SQLite databases as an anchor point before a risky operation.
Backup Restore Directions directions — Restore work-buddy's vital SQLite databases from a local or remote snapshot, with manifest validation and migration forward-roll.
Consolidated Index system — One unified lexical+dense hybrid search substrate (work_buddy/index/) serving every work-buddy corpus — system knowledge, native Journal, Projects, Contracts and Personal Knowledge, vault chunks, conversation spans, Chrome tabs, summaries, and task notes — from a single SQLite DB. Composable ports (Partition/Encoder/ResidentCache), one shared store keyed by a partition column, builds serialized on a DB-wide writer gate, FTS5⊕dense RRF search with metadata filter pushdown. Database partitions use durable build-then-ack outbox delivery; sealed Markdown roots are detached from Vault discovery and stale index rows. Flag-gated by index.enabled; each consumer routes via its own index.consumers. gate.
Context Pipeline reference — Unified two-stage context collection and curation, including structured native task context and separate Obsidian vault context.
Contracts concept — Explicit work commitments — schema, lifecycle, bounded deliverables
Control Graph concept — Unified view-model over preferences, requirements, health, and registry. Powers the Settings tab; backs the fix + help systems.
Conversation Observability system — Durable session-attributed activity DB for Claude Code: commits, file writes, GitHub PR activity, uncommitted work, observed-session metadata, and optional LLM topic summaries. Replaces ad-hoc per-call JSONL scans in sessions/inspector.py.
Data-First Skills concept — The Op/skill-declaration split — executable Ops registered by stable ID, inert skill declarations that reference them, and the loader + load-time validator that resolves declarations against the Op registry.
Embedding Service service — Local HTTP service on port 5124 providing dense vector embeddings for search and similarity; exposes a symmetric default model plus an asymmetric query/document pair via role-aware client wrappers.
Dashboard Event Bus concept — In-process pub/sub + SSE stream + localhost cross-process ingress that powers real-time dashboard updates without a global panel-refresh timer.
Feature Cards concept — Component-gated dashboard cards — the reusable pattern for widgets whose existence (and backend work) is justified by an opted-in component.
Health System (mental model) concept — Four-layer mental model of work-buddy's health system: do I want this? / is the setup correct? / is it running right now? / how does the user repair it?
Components & health checks layer system — Runtime probes: is this component (service, integration, plugin) actually running and reachable right now?
Fixers layer system — Per-requirement repair functions: clicking 'Fix' on a failed requirement runs the registered fixer to bring it back to passing.
Requirements layer system — Configuration-time validation: does the environment have what a component needs (plugins installed, configs present, secrets reachable, directories created)?
Hot-Path Discipline concept — Why store reads and request-serving surfaces must stay cheap: the two root causes of multi-second dashboard stalls (once-only work repeated on the hot path; unbounded external/blocking calls) and the fix shapes (memoize-on-change-signal, per-process schema gate, connection-share/batch, stale-while-revalidate + prewarm, deadline-bound external calls).
Inference concept — Local inference subsystems — admission control, LLM backends, embedding service, and provider dispatch for LM Studio / LM Link.
Local Inference Broker reference — Admission-control + priority scheduling + per-call metrics for every local-inference call. Work-buddy is the scheduler of record for LM Studio / LM Link traffic, not LM Studio itself.
Local Model Fleet system — Per-machine "what's loaded on which box" view of the local-inference fleet — reachability, loaded models, and hardware (multi-GPU) — behind a provider-neutral seam with LM Studio as the first adapter.
Inference Provenance system — First-class provenance for every inference call across work-buddy — a stable call_id + plain-text description per local/cloud completion and embedding, written beside the cost ledger and surfaced as the Settings › Inference activity feed.
Knowledge System concept — Unified system documentation and personal knowledge — typed units, DAG hierarchy, and full-content retrieval.
LLM Runner concept — Unified LLM call entry point (LLMRunner, llm_call) with semantic tier enum, normalized LLMResponse, and built-in tier escalation. Replaces the split between run_task (structured output) and llm_with_tools (tool calls).
Local LLM With Tools concept — Compatibility path for local LM Studio-served models invoking a restricted whitelist of work-buddy MCP tools via /api/v1/chat. Internal callers use architecture/llm-runner; the MCP-exposed llm_with_tools skill retains this path.
Local human identity boundary concept — Persistent installation-qualified actor, loopback session, Origin/CSRF, and exact one-use gesture boundary for protected local dashboard actions.
MarkdownDB concept — Frozen legacy Markdown-to-SQLite reconciliation abstraction retained for pre-seal compatibility and migration inspection.
MCP Server Import Discipline concept — Critical safety constraint: why heavy library imports in skill callables deadlock the MCP server, and the correct pattern to avoid it
Schema Migration Ladder concept — Per-DB versioned SQLite migration runner: PRAGMA user_version as authority, _migration_history for audit, AST-based hashing (ignores cosmetic edits, catches behavioral ones, stable across Python versions), downgrade guard, transaction-wrapped apply, baseline-stamp for adopting on legacy DBs.
Process Execution system — How work-buddy starts operating-system processes. One package, work_buddy.process, owns every launch through four intents (tool run, worker, host, visible terminal), fixes the runtime context of work-buddy's own processes through host roles (console, interpreter image, identity), records that context for status and health, and an architecture test keeps every launch inside the package.
Repository Structure concept — Directory layout — what lives where, with subsystem README pointers
Resilience Framework system — Unified fault-mitigation foundation for guarded calls — propagating Deadline, outcome taxonomy, execution seam, composable strategy library, pipeline/registry, and the broker/Obsidian adapters.
Async Execution Queue concept — Unified disk-backed queue for three kinds of background work: retries of transient failures, deferred submissions (llm_submit), and scheduled jobs — shared sidecar sweep, per-reason policy (backoff, failure escalation)
Skill Registry concept — How Skills and Workflow definitions are registered, how Workflows resolve by stable identity and executable aliases, and how probe-disabled Skills recover without a module reload.
Shared source foundation system — Authority-qualified source identity, exact retained representations, provenance, authorized resolution, disclosure, dependency maintenance, and redaction beneath Work Buddy domains.
Sources Maintenance Operator skill — Preview, export, recover, safely abort, import, redact, or resume an exact paused effect through a high-consent operator boundary.
Summarization Framework concept — Composition-based summarization — Source × Strategy × Store with a shared refresh orchestrator. Two compositions today: conversation sessions (layered disclosure → durable store) and Chrome tabs (flat extraction → TTL cache).
Truth concept — Scoped, provenance-aware claim stores with append-only history, human confirmation authority, document content attestations, tracked-edit proposals, deterministic recovery, and integrity enforcement.
Vault Semantic Index system — Native chunk-level semantic search over configured Markdown roots ("vaults"), in work-buddy's own processes (not Obsidian's heap). Heading-aware chunker → SQLite chunk store with float16 vector blobs + FTS5 → hybrid lexical⊕dense (RRF) search served warm from the embedding service. Reached via the vault_search / vault_index / vault_config skills and a 5-minute incremental cron.
Workflow Cancel Directions directions — How to cancel a workflow run — finding the run id, the reason argument, and how cancel relates to the automatic idle sweep.
Workflow Run Lifecycle concept — WorkflowService lifecycle operations, persisted definition/run identity, cancellation, idle expiry, and gateway restart recovery.
Workflow System concept — Workflow definitions, stable identity, admission, application service, DAG execution, and result visibility

Artifacts¶

Artifacts system — Artifacts skills and workflows
Artifact Cleanup skill — Run TTL-based cleanup over registered artifacts. By default, sweeps every registered artifact (filesystem, llm-cache, messages, notifications, llm-queue, …). Pass name to scope the sweep to a single artifact. Use dry_run=true (default) to preview what would be deleted. The name field is deliberately distinct from artifact_save's type field (which means filesystem subtype) — they live in different namespaces.
Artifact Delete skill — Delete an artifact and its metadata by ID.
Artifact Get skill — Retrieve an artifact by ID (filename stem). Returns metadata and content (inline if < 50KB, otherwise file path).
Artifact List skill — List artifacts in the data store, filtered by type, recency, tags, or session. Sorted by creation time (newest first).
Artifact Registry skill — Return the cross-backend artifact-registry introspection map. For each registered artifact, lists its name, storage kind (FilesystemStorage, SqliteRowsStorage, JsonRecordsStorage, …), lifecycle kind (trigger+action+optional retention), provenance kind (SessionTagged or none), declared capabilities, and the MCP operations it exposes. Single source of truth for 'what does this persisted resource look like.'
Artifact Save skill — Save an artifact (context bundle, export, report, snapshot, or scratch) to the centralized data store with metadata and TTL-based lifecycle.
Commit Record skill — Record structured commit metadata (hash, files, test results, knowledge units updated) as an artifact. Called after a successful git commit to enable enriched commit cards in the dashboard.

Automation¶

Automation concept — Lazy-resolution layer that decides how far the agent may take a task (operating tier) and how loudly to resurface it. Pure-function resolvers over stored signals; no I/O, no DB writes — surfaces (dashboard, engage view, audit log) call them per-read.
Action contexts reference — resolve_who_can_act answers "who can act on this task now?" by consulting the CONTEXT_REGISTRY against the live tool-status cache. Tasks declare agent_required_contexts + user_required_contexts; the resolver returns a WhoCanActDecision with per-side unmet tokens and a handoff-eligible flag.
Pickup-time readiness reference — compute_pickup_readiness pure function -- 5-rule precedence ladder deciding whether a task is ready to execute as-is or should develop first when picked up. Reads creation_effort + user_involvement + provenance + staleness + deadline + has_action_items.
Risk model + automation tiers + dynamic resurfacing concept — Operating-tier and dynamic resurfacing-level resolvers. Pure functions reading the four risk dimensions (financial, privacy, accuracy, compute) + three amplifiers (reversibility, regret_potential, inference_uncertainty) against the user's tolerance config. Returns OperatingTierDecision / ResurfacingDecision dataclasses with typed pipeline_blocker per ROADMAP §3.3.

Backups¶

Backups concept — Data-backup skills — snapshot, restore, and remote sync of work-buddy's databases
Data Backup skill — Take a local snapshot of work-buddy's vital SQLite DBs and portable Truth exports. Remote GitHub upload requires an explicit persistent private-content opt-in or exact one-shot high consent.
Data Backup List skill — List local snapshots (and optionally remote ones). Each entry includes snapshot_id, timestamp, size, manual flag, and the manifest summary (commit + schema versions).
Data Restore skill — Restore work-buddy's vital SQLite DBs from a snapshot. Validates the manifest (refuses if the snapshot's commit or schema is newer than the running code), unpacks to staging, runs migrations forward, verifies integrity, then atomically swaps into place (the old DBs are moved to .data/db.pre_restore_/ for safety).
Sensitive Data Checkpoint skill — Seal a local-only SQLite Journal hot snapshot beside an already authorized, content-aware Sources export and verify both by digest. The checkpoint is never eligible for the unencrypted remote backup.
Source Foundation Restore Operator skill — Inspect or explicitly reconcile the fail-closed Source Foundation fence left by a machine restore.

Browser¶

Browser integration — Chrome tab triage and browser-integrated workflows
Chrome Triage workflow — Triage currently-open Chrome tabs through the unified source pipeline: collect tabs, attach cached Haiku summaries + tag signals, embedding-fused cluster (Louvain over embedding+tag+window-gated proximity), Sonnet-refine cluster boundaries + propose a per-cluster action (close all tabs / group in Chrome / route to tasks / etc.), and spawn a group umbrella thread + group sub-threads with the tabs as ContextItems. The user reviews and approves via the dashboard column grid + per-column action chip.
Chrome Triage Directions directions — How to run Chrome tab triage — pipeline overview + the agent's role (confirm completion; user reviews on the dashboard column grid).

Calendar¶

Calendar subsystem (provider-neutral) integration — How work-buddy reads and writes calendar data through a provider-neutral seam; google_native is the default and the Obsidian Google Calendar bridge is an opt-in transitional compatibility adapter.
Calendar Coverage skill — Report which calendars work-buddy can actually see and how many events each yields in a window. Distinguishes subscribed vs blacklisted vs errored calendars. Defaults to a today..today+days window when start/end omitted.
Calendar Create Event skill — Create a new event on one of the user's real calendars. Heavy per-change consent — the approval prompt shows the target calendar, title, and start–end in the user's timezone, with a shared-calendar warning when others can see the calendar.
Calendar Delete Event skill — Permanently delete an event from one of the user's real calendars. Heavy per-change consent; always re-prompts because deletion is irreversible.
Calendar Get Event skill — Fetch one calendar event by its provider-local id on a given calendar. Uses a windowed lookup because the Obsidian plugin's getEvent is broken; prefer calendar_list_events with a tight range when you know the date.
Calendar Health skill — Liveness probe for the calendar provider. Returns the configured adapter's readiness payload (ready flag, calendar count, plugin version). Use it to distinguish 'bridge/provider down' from 'no calendars visible' when calendar features are missing.
Calendar List Events skill — List calendar events overlapping a date window (ISO YYYY-MM-DD start/end), optionally restricted to specific calendar ids. Returns canonical CalendarEvent dicts with offset-aware times preserved.
Calendar Update Event skill — Modify an existing event on one of the user's real calendars. Heavy per-change consent with a before→after diff in the prompt; always re-prompts because an update can cancel or move an event.
Google Calendar native (OAuth) setup directions — Step-by-step setup for the google_native calendar provider — Google Cloud project, Desktop-app OAuth client, where to put the client secret, the one-time consent flow, and switching the provider over.

Clarify¶

Text-segmenter SubCall system — Generic text-segmentation SubCall. Splits captured prose into distinct matters. Used by inline-capture (right-click 'Send to agent') to detect multi-matter selections. Reusable for any future singular-input pipeline (per-message email triage, etc.).

Context¶

Context concept — Context skills and workflows
Agent Docs skill — Search and navigate all agent documentation: directions, system docs, skills, and workflows. Supports exact path lookup, subtree browsing, and natural language search with hierarchical progressive disclosure.
Agent Docs Rebuild skill — Reload the knowledge store from disk and reindex. Use after a direct edit to a unit's .md file, or after registry changes, so the store cache and search index reflect them.
Chrome Activity skill — Query Chrome browsing history from the rolling tab ledger. Supports: hot_tabs (ranked by engagement), changes (opened/closed/navigated/engaged/moved), sessions (domain clusters), tabs_at (snapshot at a time), context (tab proximity and window layout), details (full URLs by filter), status (ledger health). Output is compact (no URLs) — use details query for full URLs.
Chrome Content skill — Extract full page text from currently-open Chrome tabs. Filter by domain or title substring, or get top-engagement tabs. Free — no LLM calls. Use for single-tab inspection or reading specific page content.
Chrome Infer skill — Infer what the user is working on by reading page content from engaged Chrome tabs and analyzing with Haiku. Evaluates provided theories against actual page evidence. Caches results per tab to avoid redundant API calls. ~$0.001/call.
Chrome Route To Tasks skill — Walk a Chrome-group thread's tabs and create one task per tab. Each tab's title becomes the task text; the URL goes into a linked summary note.
Chrome Route To Umbrella Task skill — Create a single task representing the whole Chrome group. The cluster label becomes the task text; the tabs are listed in the linked summary note.
Chrome Tab Close skill — Close specified Chrome tabs by tab ID. Returns count of closed/missing tabs.
Chrome Tab Group skill — Create a Chrome tab group or add tabs to an existing group. Returns the group ID.
Chrome Tab Move skill — Move Chrome tabs to a specific position or window.
Collect And Orient workflow — Generate a fresh context bundle and use it to orient on the user's current work state. This is the primary "what's going on right now?" workflow.
Context Collection Directions directions — How to collect context and synthesize an orientation — priority order, flags, contract cross-reference
Context Review Directions directions — How to review an existing context bundle — freshness check, same synthesis rules as context-collect, no re-collection
Context Block skill — Collect and render native context sources plus explicitly enabled compatibility sources. Obsidian, Obsidian wellness/tasks, Day Planner, and Datacore sources are skipped before cache or collector access when Obsidian is opted out; filesystem Vault and provider-neutral Calendar remain independent. Supports per-source depth, target-date windows, max-chars budgets, Markdown or JSON, and cache reuse.
Context Bundle skill — Run permitted native collectors and save a context bundle to disk. Obsidian app sources are skipped before cache or collector access when the feature is opted out; filesystem Vault and provider-neutral Calendar remain available. Use individual collectors when only one source is needed.
Context Calendar skill — Provider-neutral Calendar schedule for a given date. With the current configuration it uses native Google OAuth and never calls Obsidian.
Context Chat skill — Recent Claude Code conversations and CLI history with tool usage, duration, and outcome snippets
Context Chrome skill — Currently open Chrome tabs (requires Chrome extension running)
Context Drill Down skill — Expand one item from a context source. Works on structured sources that implement drill_down: tasks (field: 'note' / 'line'), git (field: 'full_message' / 'diff_stats'), projects (field: 'description' / 'full'). Markdown-wrapper sources don't implement drill-down, since the prompt already holds their full body at DEEP depth.
Context Git skill — Recent git activity across all repos: commits, diffs, dirty trees. Pass annotate=true to tag commits made by agent sessions with their session ID.
Context Messages skill — Inter-agent messaging state: pending, recent, unread messages
Context Obsidian skill — Explicit legacy-only Obsidian vault summary for an opted-in compatibility profile; native Journal and domain stores do not use this path.
Context Projects skill — Active projects with identity, state, and trajectory — synthesized from vault directories, STATE.md files in repos, task tags, git activity, and contracts. Filters the rendered output to active projects by default; pass statuses to widen.
Context Search skill — Search indexed content (conversations, documents, tabs). Requires IR index — build with ir_index first. Methods: 'substring' (exact match, no embedding service), 'keyword' (BM25), 'semantic' (dense), or comma-delimited combo like 'keyword,semantic' (default, RRF fused).
Context Tasks skill — Native task summary: outstanding tasks plus recent lifecycle changes (last 48h by default)
Context Vault skill — Vault context: contract-relevant notes from the native vault index
Context Wellness skill — Explicit legacy-only wellness summary from Obsidian journal files. Unavailable without an explicit Obsidian opt-in; native Journal profiles own current markers.
Datacore Compile Plan skill — Compile a structured JSON query plan into a Datacore query string. Plan keys: target (required), path, tags, tags_any, status, text_contains, exists, frontmatter, child_of, parent, expressions, negate.
Datacore Evaluate skill — Evaluate a Datacore expression (e.g. arithmetic, field access).
Datacore Fullquery skill — Execute a Datacore query with timing and revision metadata. Same as datacore_query but includes duration_s and revision.
Datacore Get Page skill — Get a single vault page by path with Datacore metadata: frontmatter, sections, tags, links, timestamps.
Datacore Query skill — Explicit legacy-only Datacore query against an opted-in Obsidian vault. Native domain queries and search do not require this skill; never suggest enabling Obsidian when it is opted out.
Datacore Run Plan skill — Compile and execute a structured query plan in one step. Preferred over raw datacore_query when building queries programmatically — the plan schema is simpler and validates before execution.
Datacore Schema skill — Summarize the vault's Datacore schema: object types, top tags, frontmatter keys, path prefixes. Use before building queries to understand what's available.
Datacore Status skill — Check if Datacore plugin is installed, initialized, and queryable. Returns version, index revision, and object type counts.
Datacore Validate skill — Validate a Datacore query string without executing it. Returns parse error details if invalid.
Docs Edit workflow — Edit or create any knowledge unit by editing its Markdown file directly, with Workflow identity scaffolding, kind-aware validation, and index propagation bracketing the edit.
Docs Delete skill — Delete a unit from the knowledge store. Cleans up parent/child references.
Docs Get skill — [Legacy] Get a knowledge unit by name. Use agent_docs instead.
Docs Index skill — [Legacy] Build IR index. Use agent_docs_rebuild instead.
Docs Move skill — Move a unit to a new path. Updates parent/child references; for a Workflow, preserves workflow_id and rewrites path-based Directions bindings.
Docs Query skill — [Legacy] Search knowledge units. Use agent_docs instead.
Docs Validate skill — Validate the knowledge store: structural integrity (DAG, command/store mappings, thinned-command format, store-path validity, required and kind-specific fields, directions fields, placeholder duplicates, parent-child symmetry, Skill Op resolution, Workflow identity/address integrity, Step-DAG and reasoning-Step consistency, Directions-to-Workflow and Workflow-delegation binding resolution) plus the advisory durable-surfaces content audit (transient identifiers in unit prose).
Index Rebuild skill — Incrementally (re)build the consolidated index (work_buddy/index/) into its separate db. Flag-gated — a no-op while index.enabled is false; when enabled it refreshes the named partition (including native journal, projects, contracts, or personal_knowledge), or all partitions when none is given. Database partitions snapshot durable search events, build and verify source/index parity, then acknowledge exactly that snapshot; interruption leaves replayable lag. The result carries wb.search-outbox-delivery/v1 readiness evidence. Pass force:true only for a deliberate partition backfill. The op self-skips while any build holds the shared writer gate.
Ir Index skill — Build or check the IR search index. Run 'build' to (re)encode dense vectors for indexed documents; builds across every IR source share one SQLite DB and serialize on a DB-wide advisory lock, so a build that arrives while another is running returns {skipped true, reason 'build_in_progress'} rather than queueing behind it. 'status' is never gated and returns per-source counts including dense_eligible_docs (how many docs CAN be encoded) and pending_eligible (real backlog — NOT doc_count vs vector_count, which is misleading because sources like conversation intentionally leave dense_text empty for tool-only spans).
Knowledge skill — Search across both system documentation and personal knowledge from the Obsidian vault. Returns results tagged with their source scope (system or personal).
Knowledge Index Rebuild skill — Rebuild the knowledge search index. Uses the persistent on-disk cache by default — unchanged units keep their cached vectors, so typical warm rebuilds are <1s. Pass force=true to purge the cache and re-embed everything (slow — 1-3 minutes for the full store).
Knowledge Index Status skill — Check the knowledge search index status: whether it's built, unit count, and whether dense vectors are available.
Knowledge Mint skill — Create or update a versioned personal-knowledge record in SQLite, with stable aliases, provenance, and idempotent mutation receipts.
Knowledge Personal skill — Search personal knowledge from the SQLite authority. Includes versioned insights, patterns, feedback, preferences, aliases, and relationships, with category and severity filters.
Review Latest Bundle workflow — Read the most recent existing context bundle without re-collecting. Faster than collect-and-orient when a recent bundle already exists.
Session Find Uncommitted directions — How to invoke and present uncommitted session results — per-entry format and follow-up suggestion
Session Identify directions — Locate a prior Claude Code conversation by topic, then drill into it for the specific turns that matter
Session Commits skill — Extract git commits made during Claude Code sessions. Parses raw JSONL for Bash tool calls containing 'git commit' and their results. Scope to one session or scan all recent sessions.
Session Expand skill — Full context around a specific message in a session. Returns untruncated text for the target and surrounding messages.
Session Get skill — Browse messages in a Claude Code session. Paginated with role/type filtering. Use after context_search finds a session.
Session Locate skill — Jump from a context_search hit to the relevant conversation page. Takes a span_index from search result metadata and returns messages centered on that chunk.
Session Search skill — Hybrid search within a single session. Uses IR (keyword/semantic/substring) scoped to the session, then resolves chunk hits to message-level results via the span map.
Session Uncommitted skill — Find agent sessions that wrote files still present in dirty git state. Answers: 'which sessions wrote code that was never committed?' Cross-references Write/Edit/NotebookEdit tool calls against git status --porcelain across all repos.
Session Wb Activity skill — Summary of what a session did through work-buddy's MCP gateway — skills invoked, workflows run, errors, key artifacts. Reads from the per-session activity ledger.
Session Inspection concept — Random-access into canonical agent-harness conversation sessions, including Claude Code, Codex, and registered transcript providers
Vault Config skill — Add/update ('set') or remove a vault in the semantic index's vault_index.vaults config. Writes config.local.yaml (the user-override layer); changes apply on the next vault build (the 5-min cron or a manual vault_index build) — no restart. Removing a vault deletes only its config entry; its already-indexed chunks stay searchable until an explicit prune.
Vault Index skill — Build or check the vault semantic index. 'status' returns per-vault chunk/vector counts, pending backlog, last build, and DB size — read locally, so it works even when the embedding service is down. 'build' incrementally (re)indexes changed files and encodes new chunks in-service (shared inference broker, BACKGROUND priority); it skips when a build is already running. The 5-minute sidecar cron calls this with action=build.
Vault Recon skill — Diagnostic-grade vault reconnaissance. Returns cross-tabs an agent can reason over to spot recurring conventions: frontmatter state machines (type x status), tag families (depth-3 tree), path-by-type distribution, recent activity by region, cardinality-capped frontmatter values. Single page walk with anti-noise caps.
Vault Recon Collect skill — Legacy, explicit-only Datacore vault reconnaissance entry point. Its system schedule and automatic investigation escalation are retired; never suggest it when Obsidian is opted out.
Vault Search skill — Hybrid (lexical + dense) semantic search over your indexed vault(s) — notes and repos chunked at heading level, running natively in work-buddy (not Obsidian / Smart Connections). Returns ranked chunk excerpts with bm25 and dense scores. Served warm from the embedding service's resident matrix; degrades to lexical-only (FTS5) if the embedding service is down.
Workflow Cancel skill — Cancel a running workflow run — drop it from the in-memory active-runs map, mark its on-disk DAG cancelled (kept for audit), and revoke its consent blanket. Idempotent; a completed run is left untouched.
Workflow Sweep Idle skill — Cancel active workflow runs that have had no step progress past the idle threshold. Runs automatically on an interval in the MCP gateway; also callable manually (with dry_run) for observability.

Contracts¶

Contracts system — Contracts skills and workflows
Active Contracts skill — List active contracts from the Contracts SQLite authority; before the authority seal only, the provider may use its read-only legacy import fallback.
Analyze Contracts workflow — Review all active contracts, check health, and surface issues for the user.
Contract Check Directions directions — How to analyze contracts — health flags, alignment check, per-contract next actions, work-pattern cross-reference
Contract Creation Directions directions — How to guide contract creation — interview flow, minimum viable fields, scope checking, WIP awareness, confirmation rules
Contract Constraints skill — Read structured bottleneck constraints for active contracts from the Contracts SQLite authority, without requiring Obsidian.
Contract Health skill — Contracts SQLite health report: status counts, overdue, stale, missing structured fields; no Obsidian dependency.
Contract Wip Check skill — Check the structured active-contract count from SQLite against the WIP limit (max 3), without requiring Obsidian.
Contracts Summary skill — Formatted summary of Contracts SQLite records with title, status, deadline, and progress; no Obsidian dependency.
Create Contract workflow — Guide the user through defining a new contract for a bounded deliverable.
Create Contract skill — Create one revisioned contract in the sealed Contracts SQLite authority after the user confirms the draft.
Overdue Contracts skill — List structured Contracts SQLite records past their deadline, without requiring Obsidian.
Stale Contracts skill — List Contracts SQLite records not reviewed in N days (default 7), without requiring Obsidian.

Conversation Observability¶

Conversation Observability concept — Durable session-attributed activity derived from Claude Code JSONL sessions — commits, writes, uncommitted work, topic summaries
Conversation Observability Get skill — One session's full picture, composed. Returns the observed-session row (metadata: start/end, message_count, span/tool counts) and, via opt-in flags, its LLM summary, commits, file writes, and PR activity — one call instead of four. All flags default off, so a bare call returns just the observed row. Complements session_summary_get (the LLM summary alone, with its own generation status). Returns None when the session has not been observed yet.
Conversation Observability List skill — List observed agent sessions (Claude Code, Codex, …) by conversation time, newest first. Recency is measured by when the conversation happened, not when the row was last refreshed, so a resumed old session does not resurface as recent. Filters: since/until (explicit window, ISO or relative shorthand) or days (recency), and project.
Conversation Observability Refresh skill — Refresh the conversation_observability DB: observed sessions metadata, session-attributed commits, session-attributed file writes (with dirty-state snapshot), and session-attributed GitHub PR activity. Stale-only by default; pass stale_only=false to force every recent session to re-load.
Conversation Observability Summarize skill — DEPRECATED — legacy v1 entry. Generates LLM topic summaries for stale Claude Code sessions in batches. No-ops while the on-by-default Session Summaries policy is active (the queue worker handles refresh on the 5-min cadence; see summarization_worker_tick) — i.e. unless the user opted out. Preserved for rollback compatibility and as an MCP-callable v1 path; new callers should use summarization_worker_tick or wait for the natural cron drain.
Conversation Observability Summary Get skill — DEPRECATED ALIAS — use session_summary_get instead. Same callable, shorter canonical name. Look up the cached tldr + topic summaries for one session_id; returns None when nothing has been summarized yet.
Conversation Observability Uncommitted skill — Return the legacy session_uncommitted report from the DB-backed attribution layer. Refreshes first; see also context/session_uncommitted (the thin compat wrapper).
Session PRs Get skill — List the GitHub pull-request events (created / merged / closed / reviewed) attributed to one session, detected structurally from gh pr Bash invocations in its JSONL. Read-only.
Session Summary Get skill — Look up the cached tldr + topic summaries for one session_id. Returns None when the session hasn't been summarized. Canonical replacement for the verbose conversation_observability_summary_get.

Conversations¶

Conversations system — Conversations skills and workflows
Conversation Management Directions directions — When and how to use agent-user conversations — decision guide, response types, behavioral notes. The threads namespace is reserved for the universal-entity primitive.
Conversation Acknowledge skill — Acknowledge exactly the oldest delivered user turn for a generation-leased conversation consumer.
Conversation Ask skill — Ask a question in a conversation and optionally wait for the user's response.
Conversation Close skill — Close a conversation.
Conversation Create skill — Create a new conversation with the user. Opens a chat sidebar on the dashboard.
Conversation List skill — List conversations.
Conversation Poll skill — Check or await an exact conversation question, defaulting to the current question.
Conversation Receive skill — Receive the oldest unacknowledged user turn for a generation-leased conversation consumer.
Conversation Send skill — Send a message in an existing conversation (fire-and-forget, no response expected).

Cowork¶

Co-work concept — The human-and-agent surface for living documents, with durable editing, source-safe file import, explicit file writes, content provenance, proposal review, and first-class Truth observability and management.
Co-work Content Provenance concept — Frozen-target, append-only attestations that keep content source, authorship, human review, and the attester distinct.
Co-think system — Explicit, non-evidential support for human deliberation within the Co-work document experience.
Co-work Action Snapshot Get skill — Read the exact frozen document version and focus attached to a targeted Co-work Chat turn.
Cowork Doc Comment skill — Raise a quote-anchored concern as a flag (replacement: null) on a cowork doc; flags are not deletion edits.
Cowork Doc Expression Mark skill — Propose linking an existing passage to an existing claim (an expression row), propose-weight and read-mostly in v1.
Cowork Doc Get skill — Read one cowork doc's metadata, source-writeback policy, hashes, open proposals, expressions, feedback, and drift.
Cowork Doc List skill — List registered cowork docs in a scope with source-writeback mode, hashes, drift, and open-proposal counts.
Cowork Doc Propose Edit skill — Propose one or more quote-anchored tracked edits on a cowork doc as an open proposal. Normal consent weight, no decision authority.
Cowork Doc Serialize skill — Return one cowork doc's canonical Markdown at its current head, with the head and projection digests that identify it.
Co-work Truth Analysis Fetch skill — Fetch one server-admitted search hit through the guarded public-network boundary and persist an exact run-owned source receipt.
Co-work Truth Analysis Job Get skill — Read the exact frozen passage, bounded Truth context, research limits, and typed output schema bound to one Co-work Truth-analysis worker run, terminalizing an overdue active run when necessary.
Co-work Truth Analysis Job Submit skill — Submit one immutable typed candidate set for the exact Co-work Truth-analysis run without writing to the Truth ledger.
Co-work Truth Analysis Search skill — Run one replay-safe bounded web query for the exact Co-work Truth-analysis worker and persist up to five lead-only hits.
Co-work Verify Job Get skill — Read the exact immutable context and output schema bound to one job-scoped Co-work Verify worker.
Co-work Verify Job Submit skill — Submit one typed output for the exact job and role encoded by a constrained Co-work Verify worker session.
Co-work document targets and action snapshots system — Reusable Working on ranges and immutable exact-version action targets shared by Chat, Verify, and Co-think.
Co-work Folder concept — The folder a person selects as their Co-work working boundary: what it owns on disk, what it contains, and the lifecycle entry point for setting one up.
Co-work Folder Setup Boundary system — The read-only proof that a selected folder is the only Co-work folder on its line of descent, and the explicit all-or-nothing setup that writes only after that proof holds.
Co-work document rendering system — Server-side conversion of a Co-work document's canonical Markdown into a downloadable deliverable, with a host-capability gate and an untrusted-content boundary.
Source-backed Co-work documents system — Domain bindings, headless structured-document kernel, durable change records, projection recovery, and source-dependency maintenance for Co-work documents.
Co-work Truth surface system — First-class Co-work rail surface for observing and managing the claims, expressions, evidence, decision provenance, and lifecycle beneath a document or Folder.
Co-work Verify configuration system — Criterion-first, append-only configuration with separate authorship, activation authority, executor admission, and data-sharing facts.
Co-work Verify and Co-think system — Exact-version document evaluation and deliberately non-evidential support for human deliberation inside the Co-work document surface.
Co-work Verify and Co-think surfaces system — HTTP, MCP, event, Review, Chat, and editor projections for Co-work Verify and Co-think.
Co-work Verify authority and orchestration system — Coordinator-first routing, role separation, and the human-only authority boundary for Co-work Verify.
Co-work Verify durable dispatch and rechecks system — Closed durable worker dispatch, fail-closed restart recovery, and proposal-linked re-evaluation obligations.

Daily Journal¶

Daily Journal system — Daily journal lifecycle — line-range segmentation, per-thread tag/summary manifest, clustering, routing, rewrite, and update synthesis.
Retired Journal Backlog Processing concept — Historical description of the retired Markdown Running Notes backlog pipeline.
Segment Notes workflow — Read the Running Notes section from a journal file, identify coherent threads of related content, and annotate the text with inline thread IDs. The raw text is never modified â€” only HTML comment tags are inserted.
Update Journal workflow — Append activity-detected Log entries to an Obsidian journal file.

Dev¶

Development concept — Developmental mode — tools and directions for building, debugging, and modifying work-buddy itself
Cross-platform release packaging reference — Native Linux and macOS artifact builds plus hosted black-box installation acceptance and least-privilege release aggregation.
Dashboard Development concept — Develop dashboard user tasks with proportional UX review, explicit verification evidence, and isolated write environments.
Dashboard UX Directions directions — Discover dashboard tasks independently of existing controls, walk the complete interaction, prioritize useful information, and verify outcomes with honest evidence.
Dashboard UX Review workflow — Record scenario coverage and verification evidence for the affected dashboard change.
Dashboard Verification Directions directions — Select a safe dashboard environment, explore through the harness-specific browser, encode regression, and record scoped evidence.
MCP Gateway Design Tenets directions — Five architectural principles for designing skills, plus the priming hazard and agentic stub patterns for workflow authoring
Dev Doc Update workflow — Review current-session code changes, cross-check against the knowledge store, update units that have gone stale or need creating, then validate store integrity. Enforces scan → propose → confirm → apply → validate → report so doc drift cannot be silently skipped and broken cross-refs cannot silently ship.
Dev Doc Update Directions directions — How to run /wb-dev-document — scan current changes, propose knowledge-store edits, confirm, apply by editing each unit's Markdown file (docs_edit / native Edit) plus docs_delete, validate store integrity, report. Rules for what to check and what not to clobber.
Development Mode directions — Enter developmental agent mode — orient on architecture, key locations, and dev workflow for modifying work-buddy itself
Dev-Mode Orientation workflow — Forced orientation before dev work — activate dev mode, search the knowledge store for the subsystem being modified, read the code, then declare the prior art found. Only after advancing the step with a non-trivial declaration may the agent proceed with the actual task.
Dev PR workflow — Commit work-buddy code changes with test verification, chained doc update, PII scan, cleanup review, and commit metadata recording. Replaces the prose /wb-commit directions.
Dev PR Directions directions — How to run /wb-dev-pr — chained doc-update via /wb-dev-document, test verification, PII scan, transient-identifier scan, cleanup review, commit, metadata record, push + PR. Replaces the prose /wb-commit directions (dev/commit).
Dev Release workflow — Cut a tagged three-platform work-buddy release with preflight gates, native artifact acceptance, one draft-release aggregation job, and a human-only publish step.
Dev Release Directions directions — How to run /wb-dev-release: preflight gates (releasable main, version/tag/CHANGELOG agreement, Obsidian-plugin pin check), consent-gated tag push, release-CI watch, draft verification, human-only publish.
Documentation Architecture directions — Where system documentation lives, what is canonical vs legacy, and how to make documentation changes
Durable surfaces — no transient narrative directions — Authoring rule for code and agent docs: describe the system's current behavior, not the journey of how it got there. No commit hashes, branch names, PR numbers, dates, agent-session tags, stage labels, or 'after X' framing in code identifiers, comments, log strings, tests, knowledge units, slash-command text, or CLAUDE.md.
Live Testing Directions directions — How to drive a live end-to-end test of an in-progress code change — distinct from unit tests; verifies wiring across MCP server, sidecar, and surfaces with the user in the loop.
MCP Registry Reload directions — When and how to refresh the MCP gateway skill registry. Pick by what changed: DATA (declarations / workflows / param schemas) → reload_skill_data, no restart; CODE (Op bodies, new Op modules, gateway functions) → Ctrl+R restart; transient tool-probe failure → recheck_disabled_skill.
Obsidian Plugin Integration directions — Build a new Obsidian plugin integration for work-buddy — probe, wrap, package, and optionally collect
Session Retrospective directions — Switch to developmental mode and critique/debug this session's execution — then fix what you find
Stress Test workflow — Subprocess isolation validation workflow (developer tool). The compute-primes step runs in a subprocess to exercise the gateway's subprocess execution path.
Testing concept — Testing as a development concern in work-buddy, covering how the per-surface test runners relate to each other and what a passing run does and does not prove.
Dashboard Browser Surface concept — Authentication and tool selection for interactive dashboard exploration on each agent harness.
Claude Code Dashboard Browser Recipe concept — Use the Claude Browser pane to explore the authenticated isolated dashboard dev server.
Codex Dashboard Browser Recipe concept — Use the projected Playwright MCP browser to explore an authenticated isolated dashboard.
Browser Setup Required concept — Initialize harness identity and establish an interactive browser surface before claiming dashboard verification.
React Dashboard Testing concept — Dashboard test runners, isolated environments, authentication, and the evidence each verification surface provides.

Disclosure¶

Progressive Disclosure system — Unified navigation contract for tree-shaped drillable resources. One MCP skill (drill_tree) walks any registered TreeDrillable at three depths (index/summary/full).
Drill Tree skill — Walk a tree-shaped drillable resource at three depths (index|summary|full). Default depth is index — cheapest walk. Today's domains: knowledge (units via agent_docs), summary (summarization framework's per-node store).
Walk skill — Universal tree navigation — canonical short name for drill_tree. Walks any registered TreeDrillable at three depths (index | summary | full). Today's domains: knowledge (units), summary (framework per-node store).

Email¶

Email integration (Thunderbird bridge) integration — How work-buddy reads email via the thunderbird-work-buddy companion extension and feeds it into the triage Review pool
Email Triage workflow — Triage recent unread email through the unified source pipeline: fetch via the Thunderbird bridge, synthesise tags from sender/folder/labels, embedding-fused cluster, refine cluster boundaries + propose a per-cluster action (close / create one task per email / create umbrella task), and spawn a group umbrella thread + group sub-threads with the emails as ContextItems. The user reviews and approves via the dashboard's Threads tab.
Email Accounts skill — List the email accounts visible through the bridge — only accounts the user has explicitly allowed in the extension's options page are exposed (default-deny).
Email Close skill — Mark an email cluster as not actionable — newsletters, automated notifications, etc. Advisory only: dismisses the Thread without touching the underlying mailbox (Thunderbird bridge is read-first in v1).
Email Create Tasks skill — Walk an email-cluster thread and create one native task per email. Sender and date land in each task's Co-work knowledge document.
Email Create Umbrella Task skill — Create one native task for an email cluster and place its message context in a Co-work knowledge document.
Email Display skill — Open a message in Thunderbird's UI. Useful when the user wants to read it themselves — does not modify anything.
Email Get skill — Fetch one email message by its operational handle (provider_message_id + folder_path) — returns the body up to max_body_chars chars plus all summary fields.
Email Health skill — Liveness probe for the email bridge. Returns the bridge's /health payload (port, version, allowed-account count). Use this when the user reports email features are missing — it distinguishes 'bridge down' from 'no accounts allowed'.
Email Record Into Task skill — Append an email cluster as context in an existing task's Co-work knowledge document. The target task must already have an active document.
Email triage directions directions — Run one source-pipeline pass over recent email; spawns Threads carrying the agent's per-cluster proposals.

Entities¶

Entities system — Entity registry — a reference-resolution layer for the user's named world. Authored, tagged, federated entity_resolve, append-only reference index.
Editing an Entity directions — How to update an entity's name/description, manage tags and aliases, and delete — plus the consent posture on destructive edits.
Listing Entities directions — How to browse the entity registry — hierarchical tag filter, presentation, drill-down via entity_get.
Creating an Entity directions — How to author a new entity — canonical name, tags, aliases, description, and the post-creation ritual.
Resolving an Entity directions — When and how to call entity_resolve — the pull-based lookup an agent uses on an unfamiliar proper noun before asking the user.
Entity Add Alias skill — Attach an alias to an entity. Globally unique (one alias, one entity); raises on collision.
Entity Add Reference skill — Explicitly append a reference row for an entity. The standard recording path is the side-effect of entity_resolve/create/update; this exists for scripts and dashboard-driven recording.
Entity Create skill — Create a new entity with optional description, tags, and aliases. Consent-gated for agent-author writes. Optionally anchors an initial reference if source_path + source_kind are supplied.
Entity Delete skill — Hard-delete an entity, cascading through tags, aliases, and references. Consent-gated (both user and agent authors must approve).
Entity Get skill — Fetch a single entity by canonical name, alias, or integer id. Returns tags, aliases, and the 5 most-recent reference rows.
Entity List skill — List entities ordered by most-recently-updated. Optional hierarchical tag filter: tag='person' returns 'person', 'person/family', 'person/colleague', etc.
Entity List References skill — List references for an entity, newest first. Default limit 50 to keep dashboard responses small.
Entity Remove Alias skill — Detach an alias from an entity. No-op if not attached.
Entity Resolve skill — Federated lookup across the entity store + the project registry. Returns all matches in parallel, flagged by provider. Optionally records a reference when source_path + source_kind are supplied.
Entity Set Tags skill — Replace the full tag set on an entity. Pass an empty list to clear. Tags are normalized; exact duplicates and redundant ancestor tags (person when person/family is present) are collapsed before writing.
Entity Update skill — Update an entity's canonical name and/or description. Tags + aliases are managed through their own skills so a rename PATCH can't accidentally wipe them.

Events¶

Events backbone integration — The durable, in-process delivery spine for event-shaped facts — a thing happened ("X happened"), emitted or received, published to 0..N consumers that may react asynchronously. A CloudEvents-superset envelope + a SQLite log (inbox-dedup + per-consumer offsets + DLQ) + one drain thread + a consent gate. RPC, observability, and supervision are excluded by category (the inclusion rule).
Event New workflow — Author an event source in conversation — elicit what to watch, propose a grounded EventSourceDef draft, dry-run it with zero side effects, confirm, then activate it. The conversational front end for event_source_create; builds polling watchers (e.g. a stock-watcher) without hand-editing .md files.
Event New Directions directions — How to run /wb-event-new — author an event source in conversation (elicit → propose → dry-run → confirm → activate → monitor). Builds polling watchers on the events backbone via event_source_create, grounded to registered source types and actions.
Event Publish skill — Publish one event onto the work-buddy Events backbone — a fire-and-forget fact ("X happened") delivered to 0..N consumers. For manual or agent-initiated emits. The type is reverse-DNS (ai.workbuddy...).
Event Source Create skill — Author an event source — validate the structured fields and write /.md. Builds a polling watcher that fetches state, reacts on a meaningful change, evaluates a CEL condition, and fires a scoped action (notify). Refuses to overwrite unless overwrite=true; a malformed source returns its validation errors.
Event Source Dry Run skill — Preview an event source without any side effects — fetch, diff against the last value, and evaluate the condition, but never publish, run an action, or advance the cursor. Returns the sampled value, whether it changed, the would-emit event, and whether the condition would pass. The preview the /wb-event-new authoring loop shows before activating.
Event Source List skill — List authored event sources — name, type, interval, enabled state, action, condition, semantic (Tier-3 gate present?), and autonomy — plus any sources that failed validation and why. Read-only.
Event Source Toggle skill — Enable or disable an authored event source by rewriting its .md. A disabled source is skipped by the poll tick (no fetch, no fire) but its definition and cursor are preserved.
Event Sources Poll skill — Poll every enabled, due event source once — fetch, diff against the last value, and publish ai.workbuddy.source..changed when a watched value changes. The periodic tick behind pull-based event sources; normally fired by the event-source-poll cron job, not called by hand.

Features¶

Features concept — User-facing component opt-in/out system and configuration-time requirements.
LM Studio Embedding Offload Setup directions — Procedure for offloading work-buddy's document-side passage encoder to LM Studio — download GGUF, verify metadata, run drift test, update config.
Feature Preferences directions — How to check feature preferences before recommending or using a component, and how the requirements system differs from runtime health checks.
User-authored Scheduled Jobs directions — How a user authors a personal scheduled cron job — file location, frontmatter schema, collision behavior, hot-reload.

Harness¶

Harness Projection concept — Agent-host projection for Claude Code, Codex, and future harnesses using generated rulesync input rather than duplicating work-buddy workflow behavior.

Inference¶

Fleet Roster skill — Add/update or clear a machine's entry in the inference.fleet roster (config.local.yaml) — its role label and optional hardware specs. Enriches live-discovered fleet machines, joined by device_id.
Fleet Status skill — Local model fleet snapshot — per-machine reachability, currently loaded model(s) with live context utilization, and hardware (GPU/VRAM/RAM), across the local-inference fleet (LM Studio + LM Link).

Inline¶

Inline Commands system — Retired Obsidian right-click and
Inline Consume Modes (Retired) concept — Historical note-mutation modes used by the retired Obsidian inline dispatcher.
Inline Commands Directions (Retired) directions — Route new selection and action features to native application surfaces rather than the retired Obsidian inline framework.
Inline Commands Overview (Retired) concept — Historical architecture of the retired Obsidian menu and
Inline Persistent Watchers (Retired) concept — Historical record of the retired

Journal¶

Journal system — Journal skills, logical-day policy, mutable notes, planning, and dashboard projections.
Activity Timeline skill — Authority-aware activity inference over native Journal SQLite records, with pre-seal Markdown compatibility and optional deeper signals.
Journal Day Lifecycle concept — Timezone-aware Journal logical-day windows, boundary policy, DST handling, and safe transitions.
Day Planner skill — Generate a time-blocked plan from calendar events and focused tasks, then optionally store it as a Source-backed native Journal artifact.
Hot Files skill — Explicit legacy-only Obsidian activity view that fuses Vault Events and Keep the Rhythm. Disabled when Obsidian is opted out; retained only for compatibility inspection.
Retired Journal Content Migration Operator concept — Historical description of the retired Markdown-to-Co-work compatibility migration. The private native Journal importer supersedes this path.
Journal Append To Note skill — Explicit legacy compatibility action for appending an archived journal-group thread to an existing vault note. Disabled when Obsidian is opted out; not part of native Journal.
Journal Prompt Generation Complete skill — Retain one lease-bound Journal worker result as identified agent output and bind it as an unreviewed prompt variant.
Journal Prompt Generation Context skill — Retrieve the frozen seed and prompt for one lease-bound Journal generation worker. This internal skill is disclosure-accounted and rejects every other agent session.
Journal Rewrite Running Notes skill — Explicit legacy compatibility cleanup for an archived Markdown Running Notes thread. Disabled when Obsidian is opted out and fenced by native Journal authority.
Journal Route To Considerations skill — Explicit legacy compatibility action that routes an archived journal-group thread into vault consideration notes. Disabled when Obsidian is opted out; not part of native Journal.
Journal Route To Tasks skill — Explicit legacy compatibility action that routes an archived journal-group thread into native tasks. Disabled when Obsidian is opted out; new Journal actions use native item routing.
Journal Sign In skill — Read the active Journal profile’s typed fields and optionally write user-supplied values through Sources with optimistic concurrency.
Journal Smart Processing Complete skill — Commit one lease-bound Journal Smart worker classification as the capture's routing, annotation, and optional task proposal.
Journal Smart Processing Context skill — Retrieve the exact saved capture and classification contract for one lease-bound Journal Smart worker. This internal skill is disclosure-accounted and rejects every other agent session.
Journal State skill — Read the native Journal day: logical date, activity window, frozen profile, typed fields, and entries.
Journal Write skill — Create Source-backed native Journal records or a generated briefing artifact, with AI provenance and no automatic Truth analysis.
Log Record Lifecycle concept — What a Journal Log record is, which records accept in-place text and time edits, and how the day timeline offers them.
Running Note Lifecycle concept — Mutable atomic Running Notes model and dashboard/provider responsibilities.
Running Notes skill — Read native Running Note records from the Journal database. Supports a logical day, date range, recent N-day window, or same-day view.
Source-backed Journal capture system — Durable Quick Capture path that commits exact input to Sources before Journal routing or optional processing.
Journal Update Directions directions — How to detect activity and append journal Log entries — format, synthesis rules, approval flow
Vault Write At Location skill — Legacy compatibility insert into a section of a vault note. Disabled with the Obsidian feature; never used by native Journal or Telegram capture.

Memory¶

Memory system — Personal memory subsystem — semantic store, mental models, retention, reflection
Hindsight Memory Server integration — External Hindsight server providing semantic memory storage and reflection
Memory Prune skill — Delete memories from the bank. CONSENT-GATED, IRREVERSIBLE. Call with no args to list documents for review. Then provide document_id to delete a specific document's memories, or memory_type to bulk-delete a category (world/experience/observation).
Memory Read skill — Read from personal memory (Hindsight). No LLM cost. Modes: 'search' (default) — semantic + keyword recall, use descriptive topic phrases with specific entity names for best results; 'model' — fetch a mental model by ID; 'recent' — list latest memories.
Memory Reflect skill — LLM-powered reasoning over memories. CONSENT-GATED: triggers a server-side LLM call against your Anthropic API key (~1-3K tokens per call). Use memory_read for free retrieval first.
Memory Write skill — Store a personal fact, preference, or constraint in memory

Messaging¶

Messaging system — Messaging skills and workflows
Messaging Block Semantics concept — When the messaging Stop hook blocks an agent from ending its turn, and how to clear it
Get Thread skill — Get all messages in a conversation thread
Query Messages skill — Query messages by recipient, sender, status, or limit
Read Message skill — Fetch a single message with full body content
Reply To Message skill — Reply to an existing message
Send Message skill — Send a message to another agent or project
Update Message Status skill — Update a message's status (e.g., pending → resolved)

Metacognition¶

Metacognition concept — Self-accountability framework — scan for patterns the user has chosen to be held to, apply graduated interventions
Blindspot Detection Directions directions — How to scan for active work-pattern blindspots — intervention levels, cascade checking, rewriting template, output format

Modes¶

Modes system — Session modes and the mode_toggle skill
Mode Toggle skill — Toggle a session mode (e.g. dev, knowledge) on or off. Pass active=true to enable, active=false to disable, or omit to flip the current state. Returns the full set of active modes after the change. Activating a mode is refused when its activation constraint is unmet. Modes gate which skills and workflows are discoverable (wb_search) and callable (wb_run) via their available_when declarations.

Morning¶

Morning Routine concept — Configurable morning routine — journal, tasks, contracts, calendar, metacognition
Morning Routine Directions directions — How to run the morning routine with the active Journal profile, blindspot scan, synthesis, proposed MITs, briefing persistence, day planner, and quality checks
Morning Routine workflow — Configurable morning routine that coordinates journal, tasks, contracts, calendar, and metacognition into a single briefing-first flow. Collect everything, then synthesize and act.

Notifications¶

Notification & Consent System system — Multi-surface notifications, requests, and consent — Obsidian, Telegram, Dashboard
Consent System directions — How consent-gated operations work — auto-request in gateway, pre-flight bundling, session scope, risk levels
Consent List skill — List all consent entries with their status (mode, tier, expiry for temporary grants).
Notification List Pending skill — List all pending notifications and requests awaiting user response.
Notification Send skill — Send a fire-and-forget notification to the user via all available surfaces (Obsidian, Telegram if enabled). No response expected. Optionally target specific surfaces.
Sending Notifications directions — How to send fire-and-forget notifications — parameters, surface rendering, and examples
Sending Requests and Consent directions — How to request user decisions — request_send, consent_request, surface rendering, blocking vs non-blocking, and handling responses
Request Poll skill — Check/wait for a response to a previously delivered request. Without timeout_seconds: single immediate check. With timeout_seconds: blocks until response or timeout (max recommended: 110s). Response is cleared from Obsidian after reading (one-shot).
Request Send skill — Create a request, deliver to all available surfaces, and optionally poll for the user's response. Supports choice, boolean, freeform, and range response types. Without timeout_seconds: non-blocking (returns immediately, use request_poll later). With timeout_seconds: blocks until response or timeout (max recommended: 110s to stay within MCP call limits).
Notification Surfaces service — Surface details — Obsidian modals, Telegram messages, Dashboard forms
Telegram Bot integration — Telegram bot for mobile access — commands, setup, architecture

Obsidian¶

Obsidian Integration integration — Explicit legacy compatibility for Obsidian import, export, bridge, and filesystem fallback; native Work Buddy domains do not require the app.
Obsidian Bridge integration — Optional legacy HTTP bridge to Obsidian for explicitly enabled compatibility workflows.
Google Calendar Integration integration — Google Calendar access via Obsidian Google Calendar plugin (stale/unmaintained) + eval_js bridge
Datacore Query Directions (Legacy) directions — Legacy-only guidance for an explicit Datacore query against an opted-in Obsidian vault; the slash command and automatic use are retired.
Day Planner Plugin Integration integration — Obsidian Day Planner plugin (v0.28.0) integration -- plan entry format, settings, runtime surface
Keep the Rhythm Integration integration — Retired app-only writing activity integration retained for explicit Obsidian compatibility; never part of the opted-out normal path.
Obsidian Retry skill — Synchronous bridge-aware retry for Obsidian-dependent skills. Checks bridge health before each attempt, waits between retries, and returns a structured result. Use when you need the result before proceeding (e.g., step 1 of a multi-step task). For fire-and-forget retries, the gateway's automatic background retry handles it.
Tag Wrangler Integration integration — Retired app-only Tag Wrangler integration retained for explicit Obsidian compatibility; never part of the opted-out normal path.
Retired Obsidian Tasks Plugin Compatibility integration — Frozen pre-cutover Tasks-plugin integration retained for import, audit, and rollback evidence only; never live task authority.
Typed Obsidian Exception Hierarchy concept — Typed ObsidianError subclasses raised by the bridge layer; classified by isinstance + error_kind rather than substring matching
Vault Event Tracking concept — Retired app-only Obsidian event ledger retained for explicit compatibility; never bootstrapped on the opted-out normal path.
Picking a Vault Write Path concept — When to use bridge.write_file_raw directly vs. vault_write — the safe/fallback distinction explained
Vault Location Writer reference — Legacy section-aware vault writer retained for opt-in file compatibility and pre-seal migration work outside sealed native-domain roots.

Operations¶

Operations concept — How to operate work-buddy — MCP gateway, sessions, Python environment
Agent Sessions reference — Session ID setup, agent directories, the uv-managed Python environment, and uv dependency management
MCP Gateway directions — How to discover and invoke agent-invocable Skills and Workflows through the MCP gateway
Retry skill — Retry a previously recorded operation by its ID. Use wb_status() to discover recent/pending operations after a timeout. Operations with retry_policy='manual' cannot be auto-retried. Operations with an active execution lease will be refused to prevent double-dispatch.
Status CLI (shell-pollable consent/operation status) directions — Read-only shell command for polling consent-request and operation status from tooling that cannot speak MCP (the Monitor tool, bash loops, cron)
wbuddy CLI directions — The wbuddy shell CLI: bootstrap, provisioning, app launch, harness surface sync, sidecar lifecycle, and the deliberately scoped local Truth consumer surface. The wb_* gateway remains the agent operations surface.

Projects¶

Projects system — Project registry — identity, observations, memory, discovery, and lifecycle
Deleting a Project directions — Pre-flight steps before deleting a project — confirm slug, explain impact, then call
Discovering Project Candidates directions — How to evaluate and triage project_discover candidates — create, alias, or ignore
Listing Projects directions — How to list and present projects — grouping by status, detail drill-down via project_get
Creating a Project directions — Parameter defaults, slug rules, when to ask vs infer, and post-creation ritual for project_create
Recording Project Observations directions — What makes a good observation, slug disambiguation, and existence prerequisite for project_observe
Project Add Alias skill — Attach an alternative slug (alias) to a project. Aliases route to the canonical row across skills. Writes a revision.
Project Add Folder skill — Attach a folder to a project. Writes a revision capturing the new folder set.
Project Confirm Description skill — Mark the latest revision as user-confirmed. Use this when a human reviews an LLM-authored description (or other agent edit) and signs off.
Project Create skill — Manually create a project. Accepts initial folders + aliases + provenance metadata. Consent-gated.
Project Delete skill — Soft-delete a project (set status='deleted'). Row + folders + aliases + revision history are preserved. Consent-gated.
Project Discover skill — Discover project candidates from task tags and git repos not yet in the registry. Returns candidates for agent review — evaluate each and use project_create to promote real projects.
Project Get skill — Get a single project (resolved via slug or alias) with its folders, aliases, and recent Hindsight memory recall
Project List skill — List projects with folders + aliases, ordered by lifecycle status. Soft-deleted rows are filtered by default; pass include_deleted=True to see them.
Project Memory skill — Read from the project memory bank (Hindsight-backed). Modes: 'search' (semantic recall, optionally scoped to one project), 'model' (fetch a mental model: project-landscape, active-risks, recent-decisions, inter-project-deps), 'recent' (latest project memories)
Project Observe skill — Record an observation about a project — strategic decisions, supervisor feedback, pivots, blockers, or anything that shapes trajectory but wouldn't appear in code or tasks
Project Remove Alias skill — Detach an alias from a project. Writes a revision.
Project Remove Folder skill — Detach a folder from a project. Writes a revision.
Project Revisions List skill — Return revision history for a project, newest first. Each entry snapshots the project state plus folder + alias sets at that revision.
Project Set Folder Archived skill — Flip the archived flag on a project folder (mark dormant or active). Writes a revision.
Project State At skill — Reconstruct a project's state as of a given timestamp (latest revision ≤ timestamp). Includes folders + aliases as they were then.
Project Sync skill — Legacy pre-seal reconciliation for project Markdown. Once Projects SQLite is authoritative, returns a deterministic disabled result and performs no file reads or writes.
Project Update skill — Update a project's identity: name, status, or description. Writes a revision row capturing the change (author + summary).

Routing¶

Routing concept — Information routing workflows — moving captured items to their destinations with user confirmation
Route Information workflow — Given a batch of discrete information items (each with an ID, raw text, and optional agent-proposed metadata), present routing recommendations to the user in clusters, get confirmation or correction, and execute the approved routings.

Search¶

Search concept — Universal IR search verb (find) plus the markdown-formatted twin (context_search). Search any indexed source — conversations, summaries, knowledge units, Chrome tabs, task notes, documents, projects — with optional per-source drill.
Find skill — Structured IR search across any indexed source. Returns a plain list of hits, or — when drill=True — the funnel shape (stage1_hits + candidate_items + drilled). Subsumes summary_search (which remains as an alias).

Services¶

Services & Infrastructure concept — Sidecar-managed services — dashboard, messaging, embedding, and service pointers
Dashboard service — Flask host for the Python-generated root dashboard and incrementally migrated React dashboard, with shared same-origin APIs.
Dashboard — Automation surfaces concept — Dashboard automation surfaces remaining in Today plus native task attention and triage controls in the React Tasks view.
Dashboard Chat Sidebar concept — Retained root-dashboard right-rail conversation surface; React authoring uses shared chat primitives and widget-native assisted drafts.
Dashboard — Costs tab concept — LLM cost / usage view with two complementary sources (per-call internal log + Claude Code transcripts), row-level backend filters, and the Anthropic rate-limit observation chip. The unified llm_costs_query skill reads both sources.
Dashboard Form Bridge concept — Frozen legacy schema-driven agent/form bridge; new React forms use host-owned assisted drafts and human-only submission.
Root Dashboard Frontend concept — Root-dashboard frontend architecture at /: Python-generated modules, event delegation, escaping, shared widgets, and content-hashed assets.
React Dashboard concept — Incrementally migrated React dashboard shell, routing, provider selection, and same-origin API boundary at /app.
React Dashboard Appearance System concept — Semantic visual grammar, skins, color scheme, typography tiers, density, and accessibility contracts.
Assisted Draft Context Get skill — Consume the exact explicitly disclosed initial or authored-turn form snapshot for one hosted assistance worker.
Assisted Draft Propose Patch skill — Propose allowlisted field edits against a consumed frozen form snapshot without acquiring submission authority.
Assisted Draft Reference Search skill — Search one form-authorized, host-visible reference projection for a hosted assisted-draft worker without dispatching any returned skill or workflow.
Widget-native assisted drafts concept — Advisory conversations that patch declared host drafts without acquiring submission, DOM, or domain authority.
React Dashboard Calendar Surface concept — Library-neutral calendar model and shared Timeline/List presentation contract.
React Dashboard Chat Primitives concept — Reusable React chat components and a typed provider seam mirroring house conversation semantics for the /app dashboard.
React Tasks View system — Authoritative React task workspace for capture, filtering, triage, detail editing, Co-work knowledge, contextual Help, confirmed completion, and conflict recovery.
React Dashboard Widget Platform concept — Standard React widget composition, identity, layout, drafts, help, and interaction contracts.
Inter-Agent Messaging service — Inter-agent messaging service for cross-session communication
Sidecar Daemon service — Unified process supervisor, cron scheduler, and message-driven job dispatcher
System Tray reference — Desktop notification-area icon and control panel for the sidecar — its own login item, not a supervised service

Settings¶

Settings system — Registry-driven Work Buddy settings, authority boundaries, App/System placement, and persistence.

Status¶

Status concept — Status skills and workflows
Claude Code Usage Scan skill — Scan Claude Code's local transcript JSONLs into the cost cache (~/.claude/projects/*/.jsonl). Incremental by default. Use full_rebuild=true after a pricing or schema change.
Dashboard Interact skill — Frozen compatibility bridge for registered root-dashboard forms. Jobs authoring is not supported: every jobs-add-job action returns form_migrated with /app/jobs. New React forms use widget-native assisted drafts with human-only submission.
Escalation Recent skill — Recent LLM-escalation observability records. Each record is one logical job (one LLMRunner.call OR one adapter-level escalation chain across multiple calls) with its full per-tier attempt list, final outcome, and trace correlation.
Feature Status skill — Show which tools, features, and skills are available or disabled, and why. Use this to diagnose missing integrations.
List Sessions skill — List all known agent sessions with metadata
Llm Call skill — Make a single LLM API call (Tier 2 execution). Cheaper than spawning a full agent session. Supports freeform text or structured JSON output via output_schema (inline dict or named schema from work_buddy/llm/schemas/). Routes to Claude via 'tier' or to a local/remote OpenAI-compatible server (LM Studio, vLLM, Ollama) via 'profile'. Handles caching and cost tracking automatically.
Llm Costs skill — Check LLM token usage, costs, and breakdown for this session. Shows per-task costs, per-model costs, cache hit rates, and top callers.
Llm Costs Query skill — Aggregate LLM cost / usage across one or both data sources (work-buddy's per-call internal log + Claude Code transcripts). Smart parameters: time window (named or ISO range), group_by (project, model, session, day, tool), source filter, min_cost / project / model filters, and previous-window comparison. Single skill covering most cost questions.
Llm Submit skill — Asynchronously submit an llm_call for background execution. Returns immediately with an operation_id; the sidecar's retry sweep invokes llm_call with your params and messages the originating session on completion. Use when local inference latency (tens of seconds) would block the caller unnecessarily. For synchronous bounded calls use llm_call. Cloud tier calls are already fast — no point submitting them; profile is therefore required.
Llm With Tools skill — Invoke a local model with restricted work-buddy MCP tool access, so it can look things up (projects, tasks, journal, context) while answering. Tool access is limited to a named preset defined in work_buddy/llm/tool_presets.py (currently: 'readonly_safe', 'readonly_context'). No arbitrary tool list accepted at call time — presets are the security boundary. Requires 'profile' and 'tool_preset'.
Reload Skill Data skill — Data-only registry refresh: reload skill declarations + workflows from disk and rebuild the registry WITHOUT purging sys.modules. Picks up edited/added declarations (including parameter-schema changes) and new workflows whose Ops already exist — no server restart, no class-identity breakage. Does NOT pick up edited Op code or brand-new Op modules (those still need a Ctrl+R restart). This is the correct tool for data changes during dev; for code changes, restart.
Remote Session Begin skill — Launch or resume a visible Claude Code session in a real terminal window. If session_id or session_name is provided, resumes that session; otherwise starts a new one. Designed for Remote Control (phone app) connection.
Remote Session List skill — List resumable Claude Code sessions from ~/.claude/sessions/. Shows session ID, name, cwd, and start time.
Service Health skill — Check if the messaging service is running
Session Activity skill — Query the session activity ledger — what this agent session has done through work-buddy. Filters by event type, skill, category, status. Returns last N matching entries (newest first).
Session Resume skill — Resume an existing Claude Code session in a new local terminal window. No prompt is sent and remote-control is off — the terminal opens directly into the conversation, ready for the user to type. cwd is auto-derived from the session's recorded working directory.
Session Summary skill — Compact summary of what this agent session has done — counts by category/skill, errors, mutations, key artifacts created, workflow progress.
Setup Help Directions directions — How to present component health diagnostics — structured output format, lead with the fix
Setup Wizard Directions directions — How to run the setup wizard — modes, feature preferences, requirements, guided setup
Setup Help skill — Diagnose wanted components. An opted-out component or a child of an opted-out dependency returns disabled without probes, requirement checks, retries, or setup advice. Use 'all' for an overview or provide a component ID.
Setup Wizard skill — Comprehensive setup wizard for work-buddy. Validates bootstrap requirements, checks feature health, manages user preferences (wanted/unwanted features), and provides guided first-time setup. Modes: 'status' (quick overview), 'guided' (interactive walkthrough), 'diagnose' (deep diagnostic for one component), 'preferences' (view/edit).
Sidecar Jobs skill — List all sidecar jobs with their enabled state, next eligible fire time, heartbeat status, and whether exclusion windows are active. Disabled jobs report no next fire.
Sidecar Status skill — Check if the sidecar daemon is running and get its current state: supervised services health, scheduler status, upcoming job schedule, and the runtime context the daemon recorded (its interpreter, its console, and what its services run on).
Tailscale Status Directions directions — Check Tailscale VPN status — daemon state, tailnet identity, online peers, Serve config
Tailscale Status skill — Check Tailscale VPN status: daemon state, tailnet identity, online peers, and Serve configuration (published ports).
User Job Create skill — Author a personal scheduled cron job by writing a .md file under /user_jobs/. Validates the cron expression and refuses to overwrite an existing job. The scheduler hot-reloads (~30s) and starts firing the job. See features/user-jobs for the schema.

Summarization¶

Summarization system — Producer + search surface for content summaries. Per-session TL;DR+topics, per-page flat extracts, and the coarse-to-fine retrieval funnel over them.
Summarization Failure Handling concept — Classified retry, queue fairness, dormancy, dead-letter, and revival semantics for automatic conversation summaries.
Summarization Backfill skill — Observe historical conversation sessions and enqueue every missing or stale summary without making LLM calls.
Summarization Worker Tick skill — Drain the active summarization queue once. Runs by default, respects the Session Summaries preference, remains dormant without a plausible backend, rotates failures for fairness, and excludes visible dead letters.
Summary Search skill — Coarse-to-fine retrieval funnel over framework summaries. Stage 1 ranks query against summary nodes; stage 2 (optional) drills into raw spans of top items. Each hit carries a drill_node_id ready to hand to drill_tree.

Tasks¶

Tasks system — Native task authority, skills, workflows, Co-work knowledge documents, and frozen legacy migration.
Task action items reference — Per-action-item rows attached to a parent task. Each item carries its own risk profile, required contexts, and definition_of_done. Execution invariant: an agent_unapproved item must not be executed by an agent.
Task Archive Directions directions — How to archive completed tasks — map the user's scope intent to older_than_days, default to a 7-day buffer, and let the consent prompt be the scope check
Task Assign Directions directions — How to assign a task — presentation format, completion tracking, state change protocol
Task Briefing Directions directions — How to present the daily task status summary — concise format, required sections, one next action
Task Completeness Sweep Directions directions — How to run a full-list completeness sweep — audit every open task for whether it is already done, warn about cost upfront, fan out the per-task task-completeness investigator over the whole list, defer all mutations to a reviewable AUDIT.md, and apply backdated toggles only on user sign-off.
Task Handoff Directions directions — How to write a structured session handoff prompt and package it as native task knowledge.
Inline TODOs Directions (Retired) directions — The Obsidian inline
Task Namespace Organization reference — Inventory, preview, atomic apply, and conditional undo for independent task namespaces.
Namespace Lookup skill — Return the closest existing namespace tags to a single query. Designed for the 'did you mean?' check before minting a brand-new namespace — the agent calls this to confirm a proposed namespace isn't a near-duplicate of something that already exists.
Native Task System system — Canonical SQLite task authority with revision-checked mutations, projection-free Co-work knowledge documents, durable cutover safety, and frozen legacy imports.
Session Tasks Get skill — List the tasks a session was assigned to (the reverse of task→sessions), each enriched with its current text + state. Bridge-independent — reads the SQLite task store, so it works even when Obsidian isn't running. Read-only.
Task Completeness workflow — Investigate whether a task was already completed (fully/partially/differently), judge the spirit not the letter, then optionally mark it complete with the correct prior date.
Task Me — what should I do right now? workflow — What should I do right now? Loads tasks, calendar, and active contracts; clamps the day plan to the current moment; surfaces 1–2 next-action recommendations; and optionally writes the resulting plan back to the journal Day Planner.
Task Me Directions directions — How to run /wb-task-me — the re-runnable engage flow that answers what should I do right now
Task New workflow — Interactive task creation with independent registered project associations and namespace choices. Plans the task, enriches with registry and namespace context, resolves uncertain new organization, then applies via task_create.
Task Creation Directions directions — How to create a task via the task-new workflow, choosing registered project links independently of free-form namespace organization.
Retired Task-note Content Adapter system — Retired pre-cutover compatibility seam for legacy task-note Markdown; never current task authority.
Task-note Migration Operator skill — Legacy per-note migration operator retained only for pre-native recovery; superseded by the native task importer and cutover.
Task Read Directions directions — How to read a task without claiming it — inspection-only path that does not write a session assignment
Scattered Tasks Directions directions — How to present scattered task results and triage into action categories
Task Search Directions directions — How to search tasks - distinguish description-text search (task_search, store-only) from note-body hybrid retrieval (context_search source=task_note)
Task Triage workflow — Interactive inbox review: surface tasks that need decisions, collect user input, apply state changes.
Task Update Description Directions directions — How to update a native task description safely with revision checking and idempotent replay.
Task Archive skill — Archive eligible completed native tasks by lifecycle flag without moving or rendering Markdown. Default policy leaves the last 7 days visible.
Task Assign skill — Claim a native task for the current session and return structured task plus current Co-work knowledge context.
Task Briefing skill — Daily task status summary with contract constraints, MITs, focused, overdue, stale, suggestions
Task Change State skill — Update task metadata: state (not completion), urgency, due date. Cannot set state='done' — use task_toggle for completion.
Task Create skill — Create a native task and optionally provision a projection-free Co-work knowledge document. GTD vocabulary is optional; agent-driven creators should set creation_provenance and appropriate user_involvement.
Task Creation Reconcile skill — Bounded maintenance owner that rolls hidden task-plus-document creation intents forward after process crashes or response loss.
Task Delete skill — Soft-delete a native task into Trash. Task history and Co-work knowledge remain recoverable.
Task List skill — List tasks from the SQLite store (bridge-independent — works even when Obsidian isn't running). With no arguments returns every live, non-archived, OPEN task, oldest-created first. The enumeration complement to task_search, which matches by text — use task_list to pull the whole open backlog (e.g. for a full-list review) rather than a single lookup.
Task Namespace Suggest skill — Rank existing namespace tags by relevance to a task text (hybrid BM25+embedding via the shared embedding service; falls back to token overlap). Returns ranked candidates from the existing universe only — it does not propose new namespaces. The calling agent decides whether to apply suggestions, add more, or mint a new namespace.
Task Note Readers skill — Sessions whose transcripts show they read a task through native task/document calls, with legacy Markdown reads retained only as historical evidence.
Task Proposals Reconcile skill — Resume already-approved task proposal executions and synchronize durable Journal proposal follow-ups after an interrupted process.
Task Provenance skill — The three session↔task provenance roles for one task — created-by (who minted it), assigned (who claimed it), and developed-by (whose commits satisfied it, with note-read awareness + informed/convergent classification). Read-only; developed-by is derived at read time, never stored.
Task Read skill — Read native structured task context plus the current projection-free Co-work knowledge-document head without claiming it.
Task Review Inbox skill — Get inbox tasks with suggested actions (mit, snooze, kill, needs_date)
Task Scattered skill — Retired legacy vault-task discovery surface; unavailable under native task authority.
Task Search skill — Search native task descriptions in TaskStore. For full-text knowledge search, use the task-note IR source, which indexes current Co-work document heads rather than Markdown files.
Task Set Tags skill — Replace a native task's complete structured tag and namespace set. Namespace spelling is independent of registered project associations; this operation does not change project links.
Task Stale Check skill — Find forgotten/stale tasks across inbox, snoozed, MIT, and focused
Task Sync skill — Retired legacy Markdown reconciliation surface; unavailable under native task authority.
Task Toggle skill — Complete, reopen, or toggle a native task atomically. Preserves an optional historical done date and the prior attention state for an idempotent reopen.
Task Update Description skill — Update a native task description with revision checking and an idempotent mutation receipt.
Task Triage Directions directions — How to run interactive task triage — presentation rules, actions, summary format
Weekly Review workflow — Agentic weekly planning session. The agent assembles the strategic picture,
Weekly Review Directions directions — How to run the weekly task review — MIT drafting, WIP enforcement, constraint validation
Weekly Review Data skill — Gather all data for the weekly review: contracts, constraints, WIP, tasks, staleness, suggestions

Threads¶

Threads — universal-entity primitive system — The Thread is the FSM-resolution subtype of the WorkItem base. Replaces the older split between PoolEntry (now folded into states) and ActionItem (now folded into sub-Threads). Task is a sibling subtype on the shared WorkItem base — Task(WorkItem), NOT a Thread subclass.
Action Catalog (typed lens over skill + workflow registries) concept — Filtered view over the existing skill + workflow registries: entries where is_action=True. Four action kinds: Standard, Improvised, Suggestion, Clarification.
Autonomy policy (composed, not enum) concept — Per-Thread policy composed from orthogonal axes. Saved compositions are configuration, not types. Sub-threads override DOWN axis-by-axis only. Auto-advance branch resolvers gate every INFERRING_ → AWAITING__CONFIRMATION transition.
Thread event log (canonical state) concept — Every state-affecting operation produces an event. The current-state cache exists for query convenience but events are authoritative.
Thread FSM (resolution phase) concept — 14-state FSM that runs from inciting event to terminal. The state catalog, transition table, and transition wiring are in place and active.
Threads — parent-child relationship patterns (decompose / group / singular) concept — Three parent-child relationship patterns. Decompose: parent has an action, children FSM-execute, cascade-on-terminal advances parent. Group: umbrella holds N cluster sub-threads with item-level drag-drop reorganization (Chrome / journal / email scans). Singular: umbrella holds N children whose actions render hoisted onto the parent's card so the user sees one thread with N proposals (inline-capture multi-record path).
LLM-call priority queue (lives in work_buddy/llm/, not threads/) concept — General infrastructure for dispatching LLM work by priority. Threads enqueue; the queue dispatches. Reusable by any client (scheduled jobs, agents, batch ops). MUST NOT be reimplemented inside the Thread package.
Resolution phase (vs. execution) concept — Resolution = the cyclic, human-in-loop FSM where the system decides what to do. Execution = whichever runtime owns the dispatched action; the threads FSM dispatches but does not itself host the action runtime.
Run Source Pipeline skill — Run an end-to-end non-Journal source pipeline: collect raw items, annotate with tags + summary, algorithmically cluster, LLM-refine cluster boundaries + per-cluster action proposals (local-first tier_chain), and spawn a group umbrella thread + group sub-threads with the items as ContextItems.
Thread Defer skill — Defer a thread so it resurfaces at a future time. Sets the cached resurface_at field; the existing Later mechanic re-surfaces the thread when the time arrives.
Thread Dismiss skill — Mark a thread as dismissed via the standard FSM transition. For group sub-threads this is the 'do nothing with this cluster' action. For umbrellas it cascades through the existing dismiss flow.
Thread Rename skill — Rewrite a thread's title (and description) — used by the action-chip 'Rename' affordance and by the LLM cluster-refinement step when it overrides an algorithmic cluster label.

Truth¶

Truth concept — Scoped, evidence-backed claim stores with append-only history, human confirmation gates, source receipts, and belief revision.
Truth Claim Challenge skill — Challenge a confirmed claim with a supported, nonterminal conflicting claim while preserving both histories.
Truth Claim Confirm skill — Ask the human to review one server-composed claim and its active receipts, then confirm only that exact content.
Truth Claim Propose skill — Propose a profile-valid claim and atomically attach supporting spans and one optional derivation.
Truth Claim Propose From Conversation skill — Propose an unconfirmed Truth claim supported by one exact durable Work Buddy conversation message.
Truth Claim Redact skill — Ask the human to destroy readable content from one exact claim while retaining identity, hashes, links, status, and audit history.
Truth Claim Reject skill — Ask the human to reject one exact claim as plain noise, false content, or a preference correction.
Truth Claim Supersede skill — Create or select a successor claim and atomically attach its support, derivation, and typed supersession link.
Truth Evidence Capture skill — Validate a source locator and capture immutable evidence with engine-assigned trust and authoritative agent provenance.
Truth Hindsight Projection Authorization skill — Preview, grant, inspect, or revoke a narrow expiring authorization for background projection of eligible confirmed Truth into Hindsight.
Truth Hindsight Projection Tick skill — Reconcile authoritative current Truth claims with the replaceable Hindsight memory projection, then drain a bounded durable outbox batch.
Truth Query skill — Query confirmed claims by current or historical belief time, or inspect active conflicts and review findings.
Truth Source Usage Reconcile skill — Recover Sources acknowledgement receipts for Truth mutations that committed before a process interruption.
Truth Span Mark skill — Resolve a quote selector against captured evidence and append one immutable evidence span for claim support.
Truth Store Create skill — Safely initialize and register one Folder's canonical .wbuddy/cowork Truth store from a complete profile. A store id is minted when neither the request nor profile supplies one.
Truth Store List skill — List registered Truth stores with their canonical paths, profiles, titles, last-seen times, and reachability.
Truth Sweep skill — Run and record an integrity, supersession-dependency, or source-dependency sweep for one Truth store.

Vault¶

Vault Health Namespace integration — Legacy vault reconnaissance documentation retained for migration evidence; automatic Datacore collection and investigation are retired.
Vault Investigation Agent Directions (Retired) directions — Historical documentation for the retired vault-recon investigation escalation; it must not spawn, probe Obsidian, or notify the user.
Vault Recon Directions (Legacy) directions — Read an existing legacy vault_recon snapshot during explicit migration inspection; scheduled collection and the slash command are retired.

Websearch¶

WebSearch subsystem integration — Provider-neutral general web search + retrieval — Jina default with a keyless ddgs fallback, behind a calendar/email-style provider seam, plus trafilatura extraction, evidence-card shaping, and a broker-admitted LOCAL_FAST relevance classify. Standalone and events-agnostic.
Web Fetch skill — Fetch a URL and extract clean readable text (Jina r.jina.ai reader when a key is configured, else trafilatura). Best-effort — an unreachable page returns ok with empty text rather than an error. Use to pull the body of a specific page (e.g. one of web_search's hits).
Web Search skill — General web search — Jina default with a keyless ddgs fallback. Returns ranked hits (title, url, snippet, and full page text when the backend provides it). Ephemeral — results are not persisted. Use for arbitrary lookups, research, or fact-checking from inside an agent flow.
Web Search Health skill — Report which web-search backend is active (first usable in the routing order — ddgs is keyless, Jina needs a key) and its readiness. Use to distinguish "no backend usable" from "Jina key missing, falling back to ddgs".