@fdcn/sourcefed 0.2.0

package/dist/data/core/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: core
+description: Core sourcefed usage guide. Read this before creating monitors. Covers monitor creation per source (Jira issue, GitHub PR, Slack thread), event delivery and acknowledgement semantics, daemon modes, CLI usage, and troubleshooting. Use when the user asks to watch or monitor a Jira ticket, GitHub PR, Slack thread, or when sourcefed monitor events arrive in the session.
+---
+
+# Sourcefed core
+
+Sourcefed lets you create **monitors** that watch a Jira issue, GitHub PR, or
+Slack thread and route NEW events into the session you're currently working in,
+so you can react to them as they happen.
+
+Every monitor is detect-only: it routes events into the session and never
+replies to the watched thread unless you are explicitly asked to.
+
+## Create a monitor
+
+Monitors belong to the session that created them; list, status, and stop only
+affect that session's monitors.
+
+- **Jira issue**: `monitor_create({ name: "PROJ-12345", sourceType: "jira", issueKey: "PROJ-12345" })`
+- **GitHub PR**: `monitor_create({ name: "PR #42", sourceType: "github", repo: "owner/repo", prNumber: 42 })`
+- **Slack thread**: `monitor_create({ name: "thread", sourceType: "slack", threadUrl: "<thread-url>" })`
+
+You will be notified of:
+
+- **Jira**: new comments, description edits, and summary/status/assignee/priority/label changes.
+- **GitHub**: new reviews (including bot reviews), PR and line-level comments,
+  CI failures, merge conflicts, and the PR being merged or closed.
+- **Slack**: new replies in the thread. Slack monitors are always detect-only
+  and never reply.
+
+GitHub and Slack use webhook delivery when configured and fall back to polling
+when unavailable. Jira always uses polling. You can lower `pollIntervalSec`
+(min 15) for time-sensitive work, but prefer the default to avoid hammering
+APIs.
+
+Actionable events trigger an agent turn. Stable all-passing CI is suppressed to
+avoid notification noise; other informational events are added as context only.
+
+## Lifecycle
+
+- `monitor_list` — see monitors created by this session.
+- `monitor_status { id }` — detail on one of this session's monitors.
+- `monitor_stop { id }` — stop routing events for one of this session's monitors.
+- GitHub monitors remove themselves after the PR is merged. Jira monitors
+  remove themselves when `SOURCEFED_JIRA_TERMINAL_STATUS` matches the issue
+  status; leave it unset to disable automatic Jira removal.
+
+## When an event arrives
+
+Events are fed into your session as a message (e.g. a new review comment, a CI
+failure, a Jira status change). Treat it like any new input: read it, decide
+whether it needs action, and act (or tell the user it needs a decision). If the
+event is non-actionable (e.g. CI all-passing), acknowledge it and move on — do
+not fabricate work from it.
+
+## Daemon and CLI
+
+Sourcefed runs as a shared HTTP daemon (`@sourcefed/daemon`) that owns
+polling, webhooks, cursors, and state. The MCP server, the CLI, and host
+adapters (OpenCode, Pi) are all consumers of the daemon.
+
+- `sourcefed daemon [--port 18787]` — run the shared daemon (rpc, events, webhooks).
+- `sourcefed mcp --stdio|--http` — expose the daemon through MCP.
+- `sourcefed monitor create|list|status|stop` — drive a running daemon from the shell.
+
+When `SOURCEFED_DAEMON_URL` is unset, the OpenCode and Pi adapters spawn one
+local HTTP daemon automatically (if none is running) and connect to it, so
+monitors persist across sessions and share a single registry.
+
+Load the full command reference with `sourcefed skills get core --full`.

package/dist/data/core/references/commands.md

@@ -0,0 +1,75 @@
+# Sourcefed command reference
+
+## CLI
+
+```text
+sourcefed daemon [--port 18787]       Run the shared daemon (rpc, events, webhooks)
+sourcefed mcp --stdio                       Serve MCP over stdio
+sourcefed mcp --http [--port 18788]          Serve MCP over HTTP at /mcp
+sourcefed monitor create [options]          Create a monitor via a running daemon
+sourcefed monitor list [--target-kind KIND] [--target-id ID]
+sourcefed monitor status --id ID [--target-kind KIND] [--target-id ID]
+sourcefed monitor stop --id ID [--target-kind KIND] [--target-id ID]
+sourcefed monitor start --id ID [--target-kind KIND] [--target-id ID]
+sourcefed monitor remove --id ID --yes [--target-kind KIND] [--target-id ID]
+sourcefed monitor events [--target-kind KIND] [--target-id ID]
+sourcefed monitor ack --event-id ID[,ID...] [--target-kind KIND] [--target-id ID]
+sourcefed monitor sources
+sourcefed skills [list]                     List bundled skills
+sourcefed skills get <name> [--full]        Output skill content (--full adds references)
+sourcefed skills get --all                  Output every skill
+sourcefed skills path [name]                Print skill directory path
+```
+
+### monitor create options
+
+```text
+--name NAME           Human-readable monitor name (defaults to the source type)
+--source-type TYPE    jira | github | slack
+--issue-key KEY       Jira issue key (jira)
+--repo OWNER/NAME     GitHub repository (github)
+--pr-number N         GitHub PR number (github)
+--channel-id ID       Slack channel (slack)
+--thread-ts TS        Slack parent message timestamp (slack)
+--thread-url URL      Slack thread URL (slack)
+--poll-interval-sec N Poll interval in seconds (min 15)
+--target-kind KIND    Target kind for ownership scoping (default: cli)
+--target-id ID        Target id for ownership scoping (default: hostname)
+```
+
+## Environment
+
+```text
+SOURCEFED_DAEMON_URL            Base URL of a shared daemon (default http://127.0.0.1:18787).
+                                When unset, adapters auto-spawn one local HTTP daemon.
+SOURCEFED_DAEMON_TOKEN          Bearer token required when binding a non-loopback host
+SOURCEFED_SLACK_TOKEN           Slack bot/user token for direct Slack Web API polling
+SOURCEFED_STATE_DIR             State directory (default ~/.local/state/sourcefed)
+SOURCEFED_DAEMON_PORT           HTTP daemon port (default 18787)
+SOURCEFED_MCP_PORT              MCP HTTP port (default 18788)
+SOURCEFED_WEBHOOK_PORT          Optional webhook listener port (default 8788)
+SOURCEFED_JIRA_BASE_URL         Jira base URL (default https://<site>.atlassian.net)
+SOURCEFED_JIRA_TERMINAL_STATUS  Jira status that auto-removes monitors
+GH_TOKEN / GITHUB_TOKEN         GitHub token for direct API polling
+SOURCEFED_GITHUB_WEBHOOK_SECRET GitHub webhook secret (enables webhooks)
+SOURCEFED_SLACK_SIGNING_SECRET  Slack signing secret (enables webhooks)
+SOURCEFED_SKILLS_DIR            Override the bundled skills directory
+```
+
+## Daemon protocol
+
+The daemon speaks a small JSON protocol over HTTP (`POST /rpc`, `GET /events?target=...`
+for SSE). Any harness can talk to it directly:
+
+```json
+{ "id": 1, "method": "monitor.create", "params": { ... } }
+{ "id": 1, "result": { ... } }
+```
+
+```text
+data: { "type": "event", "target": { "kind": "...", "id": "..." }, "events": [ ... ] }
+```
+
+Methods: `monitor.create`, `monitor.list`, `monitor.status`, `monitor.stop`,
+`monitor.events`, `monitor.ack`, `monitor.subscribe`, `monitor.unsubscribe`,
+`daemon.sourceTypes`.

package/dist/data/sourcefed/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: sourcefed
+description: Live Jira, GitHub, and Slack monitoring for agent hosts. Create monitors that route new issue comments, PR reviews, CI failures, and Slack thread messages into the current session as they happen.
+hidden: true
+---
+
+# Sourcefed
+
+Sourcefed turns external collaboration threads into live agent input: create a
+monitor for a Jira issue, GitHub PR, or Slack thread and NEW events are routed
+into the session you are working in, so you can react to them as they happen.
+
+This file is a discovery stub, not the usage guide. Before running any
+`sourcefed` command, load the actual workflow content from the CLI:
+
+```bash
+sourcefed skills get core             # start here — workflows, patterns, troubleshooting
+sourcefed skills get core --full      # include full command reference and templates
+```
+
+The CLI serves skill content that always matches the installed version, so
+instructions never go stale. The content in this stub cannot change between
+releases, which is why it just points at `skills get core`.
+
+## When to load this skill
+
+- A user asks to monitor a Jira ticket, GitHub PR, or Slack thread.
+- You found or are working on a Jira ticket, PR, or thread and want new
+  activity routed into your session.
+- You opened a PR and want to be notified of reviews, comments, CI failures,
+  merge conflicts, or the merge itself.

package/dist/guidance.md

@@ -0,0 +1,71 @@
+# sourcefed — monitoring guidance
+
+sourcefed is a monitor service. It lets you create **monitors** that watch a Jira issue, GitHub
+PR, or Slack thread and route NEW events into the host session where the monitor was created.
+The OpenCode and Pi adapters drive the Sourcefed daemon client (`@sourcefed/daemon`) for
+monitor tools and event delivery; the same daemon can be served through MCP (`@sourcefed/mcp`)
+or driven directly by the CLI.
+
+All transports speak the same daemon JSON protocol over HTTP (`POST /rpc` +
+`GET /events` SSE). The MCP adapter adds the 2026 resource-subscription flow
+(`subscriptions/listen`, `notifications/resources/updated`, `monitor_events_ack`)
+on top. When `SOURCEFED_DAEMON_URL` is unset, the OpenCode and Pi adapters
+spawn one local HTTP daemon automatically (if none is running) and connect to it.
+
+## When to create a monitor
+
+- **You found or are working on a Jira ticket** → create a Jira monitor for its issue key. You
+  will be notified of new comments, description edits, and summary/status/assignee/priority/label changes.
+- **You are on a branch with an active PR (or just opened one)** → create a GitHub monitor for
+  `repo#prNumber`. You will be notified of new reviews (including bot reviews), PR and
+  line-level comments, CI failures, merge conflicts, and the PR being merged or closed.
+- **You were given a Slack thread** → create a Slack monitor for the thread URL. It is
+  detect-only: it reads new messages and routes notifications into this session, but never replies.
+
+## How to create one
+
+Use the `monitor_create` tool:
+
+- Jira: `monitor_create({ name: "<key>", sourceType: "jira", issueKey: "PROJ-12345" })`
+- GitHub: `monitor_create({ name: "<pr>", sourceType: "github", repo: "owner/name", prNumber: 42 })`
+- Slack: `monitor_create({ name: "<thread>", sourceType: "slack", threadUrl: "<slack-thread-url>" })`
+
+GitHub and Slack use webhook delivery when configured and fall back to polling when unavailable.
+Jira always uses polling. Slack monitors are
+always detect-only and never reply. You can lower
+`pollIntervalSec` (min 15) for time-sensitive work, but prefer the default to avoid hammering APIs.
+Actionable events trigger an agent turn. Stable all-passing CI is suppressed to avoid notification noise; other informational events are added as context only.
+
+The abstract `Monitor` consolidates transport fallback and recovery and composes whichever
+generic `PollMonitor` and `WebhookMonitor` transports a source exposes as class attributes.
+Each provider is its own package (`@sourcefed/provider-{jira,github,slack}`) with monitor and
+event modules; the built-in registry (`SOURCE_MAP`) is composed by the daemon, which imports
+the provider packages directly. Jira exposes only polling;
+GitHub and Slack expose both. Do not add source-specific transport branches to tools,
+scheduling, or the daemon.
+
+## Skills
+
+The CLI bundles skills that teach agents how to use sourcefed, in the agent-browser style: a
+thin discovery stub points at CLI-served content that always matches the installed version.
+
+```bash
+sourcefed skills           # list available skills
+sourcefed skills get core  # load the core usage guide (--full adds references)
+```
+
+## Lifecycle
+
+- Monitors belong to the target that created them; list, status, and stop only affect that target's monitors.
+- `monitor_list` — see monitors created by this session.
+- `monitor_status { id }` — detail on one of this session's monitors.
+- `monitor_stop { id }` — stop routing events for one of this session's monitors.
+- GitHub monitors remove themselves after the PR is merged. Jira monitors remove themselves when
+  `SOURCEFED_JIRA_TERMINAL_STATUS` matches the issue status; leave it unset to disable automatic Jira removal.
+
+## When an event arrives
+
+Events are fed into your session as a message (e.g. a new review comment, a CI failure, a Jira
+status change). Treat it like any new input: read it, decide whether it needs action, and act
+(or tell the user it needs a decision). If the event is non-actionable (e.g. CI all-passing),
+acknowledge it and move on — do not fabricate work from it.