orc-ai 0.1.36 → 0.1.37

package/README.md

@@ -197,6 +197,27 @@ The `--mcp-config` flag wires the host agent back to ORC's [HTTP MCP endpoint](#
 
 ## Connect your agent
 
+For coding-agent access, check the installed `spec` CLI bridge first (`spec --help`,
+`spec specs`). It can call ORC's MCP server without configuring MCP separately in
+each agent. Use an existing ORC registration or an inline endpoint for your selected
+installation:
+
+```sh
+spec call --mcp-http http://127.0.0.1:7700/mcp context --data '{"project":"my-app"}'
+spec call --mcp-http http://127.0.0.1:7700/mcp skill_read --data '{"name":"orc-sdlc","project":"my-app"}'
+```
+
+For authenticated servers, use existing secure secret references in spec configuration;
+do not put secrets in command arguments. Use `SPEC_NO_CACHE=1` when refreshing live
+context and effective skills. Direct MCP connections below remain supported when
+already configured. Check the CLI bridge before reporting ORC unavailable.
+
+Lifecycle hooks and MCP registration are separate. The hook examples below record
+session activity; also register ORC in the client's supported MCP configuration
+using `orc mcp` (stdio) or `<origin>/mcp` (HTTP). Preserve existing servers and
+configure authentication privately. Verify tool discovery and a project-scoped
+`context` call in each client; installed hooks alone do not establish MCP access.
+
 ### Claude Code
 
 Add to `~/.claude/settings.json`:
@@ -309,17 +330,18 @@ The task loop automatically picks up queued tasks and spawns worker agents:
 
 ```bash
 # Create a task with a workflow and backend
-orc task add "Implement user auth" --skill orc-coder --backend claude --priority high
+orc task add "Implement user auth" --skill orc-sdlc --backend claude --priority high
 
 # Or batch-create with dependencies via MCP
 task_batch_create({ tasks: [
-  { title: "Design schema", skill_name: "orc-planner" },
-  { title: "Implement API",  skill_name: "orc-coder", blocked_by: [0] },
-  { title: "Review code",    skill_name: "orc-reviewer", blocked_by: [1] }
+  { ref: "design", title: "Design schema", skill_name: "orc-sdlc" },
+  { ref: "api", title: "Implement API", skill_name: "orc-sdlc", depends_on: ["design"] },
+  { ref: "tests", title: "Verify API integration", skill_name: "orc-sdlc", depends_on: ["api"] }
 ]})
 ```
 
 The loop handles concurrency, session resume on feedback, review round limits, stale claim cleanup, and backend routing.
+Each task's configured flow handles its review; a separate review task is unnecessary.
 
 Every task runs a **flow graph** (see [Task flows](#task-flows)); `orc-default` is the build → review → done pipeline described above.
 
@@ -464,7 +486,7 @@ The graph itself is deterministic; only the nodes are agents. That means loops,
 ```bash
 orc flow list                                    # what graphs are available
 orc flow show orc-default              # nodes, edges, limits
-orc task add "Fix the flaky test" --flow orc-default --skill orc-bugfix
+orc task add "Fix the flaky test" --flow orc-default --skill orc-sdlc
 orc flow status <taskId>                         # active nodes + the ledger of outcomes
 orc flow resume <taskId> --outcome approved      # resolve a human gate
 orc flow halt <taskId>                           # stop it and kill live nodes
@@ -508,6 +530,53 @@ orc job add on-change --command "bun run lint"      --trigger watch --watch "./s
 orc job add on-push   --command "bun run ci"        --trigger webhook
 ```
 
+Jobs separate **what runs** from **when it runs**. Choose **Run command**,
+**Run agent**, or **Create task** in the dashboard. Command is required only for
+Run command. Agent jobs save instructions, backend, optional model and explicit
+tool approval; each run links to its tracked session. Task jobs save a task title
+and instructions and link to the created task. **Start the task flow automatically**
+is off by default, so generated tasks wait for a manual flow start.
+The CLI accepts typed actions through `--action-config <json>`.
+
+New jobs are disabled by default. Select **Enable this job immediately** during
+creation or pass `orc job add ... --enable` to opt in. Jobs supports enable/disable
+directly in the list and for selected rows. Projects shares the selection toolbar
+for activate, pause and archive actions; select-all applies only to displayed rows.
+Failed bulk updates remain selected so you can retry them.
+
+### Webhooks
+
+Open **Activity → Webhooks** to see all configured event sources and their connected
+jobs. Create a source without a job, copy its URL and one-time signing secret, then
+register them with the provider. Sources belong to the selected project, or are
+shared across projects when created in All projects.
+
+In **Jobs → New job** (or Edit), choose **Webhook** as the trigger, select an
+existing source or create one inline, and set this job's event/action filters.
+One source can trigger multiple enabled jobs, each with its own filters and action.
+The Webhooks page shows source enablement, connected jobs and recent deliveries,
+including individual run results and links to generated tasks or agent sessions.
+Deleting a job disconnects it while preserving the reusable source.
+
+For command jobs, accepted JSON is passed unchanged on stdin; bounded metadata is
+also available as `ORC_WEBHOOK_*` environment variables. Agent and task jobs receive
+up to 50,000 characters of event data, explicitly marked as untrusted input, alongside
+the configured instructions. Delivery history stores event metadata and a payload
+hash, not the payload body or signing secret; generated tasks and agent prompts can
+contain the supplied event data.
+
+Generic endpoints verify `X-Orc-Signature-256: sha256=<HMAC-SHA256 of the raw body>`.
+Use `X-Orc-Event` for event filtering and `X-Orc-Delivery` (or
+`Idempotency-Key`) for deduplication. GitHub endpoints use
+`X-Hub-Signature-256`, `X-GitHub-Event` and `X-GitHub-Delivery` directly.
+Event names and payload `action` values are configurable, so PR lifecycle,
+reviews, workflow runs, releases, or later providers use the same job trigger.
+
+Signing secrets are encrypted at rest and shown only when an endpoint is created or
+rotated. The receiver is intentionally outside normal ORC bearer authentication;
+the per-endpoint HMAC is its authentication boundary. Management remains under the
+authenticated API.
+
 ### Gateway (Telegram / Slack)
 
 Approve agent work from your phone, search memory, or start a live AI session.
@@ -551,7 +620,7 @@ Same commands as Telegram. Create a Slack app at [api.slack.com/apps](https://ap
 
 ## Skills
 
-ORC ships with agent workflow skills and built-in skill templates for the task loop.
+ORC ships two entry-point skills. Their supporting references load only when needed; custom skills and packages remain supported.
 
 ### Install skills
 
@@ -560,21 +629,23 @@ ORC ships with agent workflow skills and built-in skill templates for the task l
 npx skills add niradler/orc --all
 
 # Or pick specific ones
-npx skills add niradler/orc --skill orc-session orc-tasks
+npx skills add niradler/orc --skill orc-platform orc-sdlc
 
 # Global install
 npx skills add niradler/orc --all -g
 ```
 
-### Agent workflow skills
+### Entry-point skills
+
+| Skill | Purpose |
+| --- | --- |
+| `orc-platform` | Operate ORC domains: setup/interfaces/auth, memory and maintained KBs/digests/embeddings, work/operations, sessions/SSH/Git/chat, rules and agent packages |
+| `orc-sdlc` | Requirements → risk/complexity classification → direct work or plan → implementation → tests/completeness → review/rework → authorized Git delivery, with shared learning throughout |
 
-| Skill           | Triggers on                                                                |
-| --------------- | -------------------------------------------------------------------------- |
-| `orc-session`   | Session start, context compaction, resuming work                           |
-| `orc-tasks`     | Task creation, status updates, HITL review, task decomposition             |
-| `orc-memory`    | Short project facts, "remember this", "what did we decide"                 |
-| `orc-knowledge` | Searching indexed docs, managing knowledge collections                     |
-| `orc-gateway`   | Telegram/Slack setup, remote approval, live agent sessions                 |
+Start with the relevant entry point and read only its selected reference. Platform
+guidance groups related domains while keeping memory, execution and rules independently
+loadable; SDLC has planning, development and review/delivery references. Clear low-risk
+work can execute directly; assigned managed nodes preserve roles and flow contracts.
 
 ### Built-in skill templates
 
@@ -585,7 +656,7 @@ On the **Skills** page, each built-in has an **Agent discovery** toggle, plus
 across the installation and defaults to visible. Hidden built-ins stay on the
 Skills page for management and remain readable by name, including supporting
 files; existing task flows continue to use them. User/imported skills and authored
-global/project instruction overrides remain discoverable.
+global/project instruction overrides of current skills remain discoverable.
 
 The policy is saved under `skills.hidden_builtins` in `~/.orc/config.json` and
 read afresh for discovery, including by existing MCP processes. `GET /api/skills`
@@ -595,16 +666,14 @@ omits hidden built-ins; `include_hidden=true` returns the management catalog wit
 API authentication. This installation-wide preference ignores project config.
 New built-ins default to visible until hidden explicitly.
 
-| Skill              | Type     | Purpose                                                                     |
-| ------------------ | -------- | --------------------------------------------------------------------------- |
-| `orc-worker-base`  | Base     | Default worker behavior - ORC awareness, status updates, deliverable format |
-| `orc-main-base`    | Base     | Orchestration agent - planning, decomposition, monitoring                   |
-| `orc-coder`        | Workflow | Implementation - understand, plan, implement, verify, submit                |
-| `orc-planner`      | Workflow | Task decomposition with dependencies and workflow assignment                |
-| `orc-reviewer`     | Workflow | Structured evaluation - correctness, tests, security, conventions           |
-| `orc-bugfix`       | Workflow | Bug investigation - reproduce, root-cause, fix, regression test             |
-| `orc-requirements` | Skill    | Requirements interview - outcome, criteria, constraints, scope              |
-| `orc-report`       | Skill    | Project status report - health summary, blockers, active work               |
+Retired built-in names (such as `orc-coder` and `orc-reviewer`) remain readable
+as compatibility routes for saved tasks, authored overrides and frozen flows, but
+are not additional discovery entries. New tasks and built-in flows use
+`orc-sdlc`; the node role selects implementation versus independent review.
+Applicable authored legacy worker/coder/reviewer/knowledge instructions remain
+role-scoped supplements with revision provenance, including on resume. Other authored
+legacy domain guidance is indexed from the canonical effective read and loads by name
+when relevant. Conflicts are surfaced rather than silently rewriting stored overlays.
 
 Add custom skills by creating a `SKILL.md` in `~/.orc/skills/my-workflow/SKILL.md`.
 
@@ -670,6 +739,15 @@ The **Agents** page creates/reads specialist profiles. API `/api/agents` and `/a
 
 ## MCP tools
 
+Agents can fetch original skill scripts/assets with
+`skill_read({name: "orc-platform", ref: "scripts/upload-session.py", download: true, project: "my-app"})`.
+It returns a signed ten-minute `download_url`, `sha256`, `size_bytes` and expiry
+instead of the file body. Download to a local file and verify the hash; do not
+reconstruct scripts from tool text. The URL authorizes only that file version and
+does not contain the API secret. Keep it private. Expiry, API restart or file changes
+require a new URL. Downloading never executes scripts. The authenticated REST mint
+endpoint is `POST /api/skills/<name>/download` with `ref` and optional scope.
+
 Tools are available to any connected agent. Start every session with `context`.
 
 | Category      | Tools                                                                                                                                       |