CLAUDE.md

1# Watcher: Shared Knowledge Base
2 
3This file contains shared infrastructure knowledge for all watcher instances.
4Each watcher has its own identity in its subdirectory and its own LEARNINGS.md.
5Agent sessions inspecting this directory will find the layout and CLI reference below.
6 
7## Layout
8 
9The singular watcher root mirrors `~/.agent-deck/conductor/`:
10 
11```
12~/.agent-deck/watcher/
13  CLAUDE.md        — this file (shared knowledge base)
14  POLICY.md        — behavior rules (escalation, dedup, retry, health thresholds)
15  LEARNINGS.md     — cross-watcher patterns accumulated over time
16  clients.json     — routing map: sender key -> conductor name
17 
18  <name>/          — per-watcher directory (one per registered watcher)
19    meta.json      — watcher registration metadata (type, created_at, expiry)
20    state.json     — latest health snapshot (last_event_ts, error_count, adapter_healthy)
21    task-log.md    — append-only event log (one Markdown heading per event)
22    LEARNINGS.md   — per-watcher patterns (optional, watcher-specific)
23```
24 
25## Files
26 
27| File | Purpose |
28|------|---------|
29| `CLAUDE.md` | Shared mechanism knowledge. Read by agent sessions to understand watcher infrastructure. |
30| `POLICY.md` | Behavior rules: escalation thresholds, dedup strategy, retry backoff, health thresholds. |
31| `LEARNINGS.md` | Cross-watcher patterns. Add entries as you notice recurring behaviors. |
32| `clients.json` | Routing map loaded by the engine. Key format: `<adapter>:<channel>` or email address. |
33 
34## For Agents Inspecting This Directory
35 
36To inspect watcher health and list all registered watchers:
37 
38```bash
39agent-deck watcher list --json
40agent-deck watcher status &lt;name&gt;
41```
42 
43The `list --json` output includes `last_event_ts`, `error_count`, and `health_status` per watcher.
44 
45To check if a specific sender would be routed:
46 
47```bash
48agent-deck watcher test &lt;name&gt;
49```
50 
51## Why This Folder Shape
52 
53Watcher state mirrors the conductor pattern (`~/.agent-deck/conductor/`) for consistency:
54both subsystems use a singular directory root with shared top-level files and
55per-instance subdirectories. This makes the layout predictable and tooling reusable.
56 
57The legacy `~/.agent-deck/watchers/` path is preserved as a relative compatibility
58symlink pointing to `watcher/`. Existing tooling that reads `watchers/` continues
59to work without modification.
60