+ 
+
+
+
+
+ Mission Control for shared execution state. Activity for the live history your agents can build on. +
+ +--- + ## What changes after you install this | Before OrgX | After OrgX | diff --git a/skills/orgx-design-agent/SKILL.md b/skills/orgx-design-agent/SKILL.md index 5166623a..3201298e 100644 --- a/skills/orgx-design-agent/SKILL.md +++ b/skills/orgx-design-agent/SKILL.md @@ -35,4 +35,5 @@ For UI changes: ## Reporting Protocol (OrgX) - `orgx_emit_activity` for intent/execution/review/completed. -- `orgx_apply_changeset` for decisions and state updates. +- `orgx_request_decision` for the default-safe human approval path. +- Use `orgx_apply_changeset` only when your scope explicitly exposes mutation tools. diff --git a/skills/orgx-marketing-agent/SKILL.md b/skills/orgx-marketing-agent/SKILL.md index 682f04ef..d269d5dc 100644 --- a/skills/orgx-marketing-agent/SKILL.md +++ b/skills/orgx-marketing-agent/SKILL.md @@ -37,4 +37,5 @@ When asked for a campaign/content: ## Reporting Protocol (OrgX) - `orgx_emit_activity` for progress updates. -- `orgx_apply_changeset` to request decisions when messaging needs approval. +- `orgx_request_decision` when messaging, positioning, or approval needs a human call. +- Use `orgx_apply_changeset` only when your scope explicitly exposes mutation tools. diff --git a/skills/orgx-operations-agent/SKILL.md b/skills/orgx-operations-agent/SKILL.md index 0ad4583c..2813901b 100644 --- a/skills/orgx-operations-agent/SKILL.md +++ b/skills/orgx-operations-agent/SKILL.md @@ -37,4 +37,5 @@ For ops deliverables: ## Reporting Protocol (OrgX) - `orgx_emit_activity` for progress and status. -- `orgx_apply_changeset` for blocking decisions and state changes. +- `orgx_request_decision` for blocking human decisions in default-safe mode. +- `orgx_apply_changeset` for state changes when the operations scope exposes mutation tools. diff --git a/skills/orgx-orchestrator-agent/SKILL.md b/skills/orgx-orchestrator-agent/SKILL.md index 587eaa90..3fca9068 100644 --- a/skills/orgx-orchestrator-agent/SKILL.md +++ b/skills/orgx-orchestrator-agent/SKILL.md @@ -42,4 +42,5 @@ When creating work: ## Reporting Protocol (OrgX) - Use `orgx_emit_activity` frequently (append-only). -- Use `orgx_apply_changeset` for entity mutations and decisions. +- Use `orgx_apply_changeset` for entity mutations when the orchestration scope exposes it. +- Use `orgx_request_decision` for human approvals or when running in a default-safe surface. diff --git a/skills/orgx-power/SKILL.md b/skills/orgx-power/SKILL.md new file mode 100644 index 00000000..3be73f22 --- /dev/null +++ b/skills/orgx-power/SKILL.md @@ -0,0 +1,103 @@ +--- +name: orgx-power +description: Power-user OrgX skill for OpenClaw. Use when you explicitly need the full mutation surface for entity CRUD, run control, checkpoints, stream reassignment, or agent-config policy changes. +version: 1.0.0 +user-invocable: true +tags: + - orchestration + - orgx + - power-user + - openclaw +--- + +# OrgX Power (OpenClaw) + +Use this skill only when the caller explicitly needs the **full mutation surface** exposed by the OrgX OpenClaw plugin. This is the elevated counterpart to the default-safe `orgx` skill. + +> Use `orgx` by default. Use `orgx-power` when you need admin or orchestration operations that change entity state directly. + +## When to use this skill + +- creating or updating OrgX entities directly +- reassigning streams or changing execution ownership +- pausing, resuming, cancelling, or rolling back runs +- listing or restoring checkpoints +- inspecting or updating managed agent config policy +- working against the unscoped `/orgx/mcp` endpoint rather than a domain-scoped safe surface + +## Elevated tool surface + +These tools are part of the plugin registry, but are elevated and should be used intentionally: + +- `orgx_apply_changeset` +- `orgx_create_entity` +- `orgx_update_entity` +- `orgx_list_entities` +- `orgx_reassign_stream` +- `orgx_reassign_streams` +- `orgx_delegation_preflight` +- `orgx_run_action` +- `orgx_checkpoints_list` +- `orgx_checkpoint_restore` +- `orgx_agent_sessions` +- `orgx_resume_agent_session` +- `orgx_clear_agent_session` +- `update_agent_config` +- `orgx_sentinel_catalog` + +The default-safe reporting tools still apply and should usually wrap elevated work: + +- `orgx_emit_activity` +- `orgx_request_decision` +- `orgx_register_artifact` +- `orgx_spawn_check` +- `orgx_proof_status` +- `orgx_verify_completion` + +## Operating discipline + +1. Announce intent with `orgx_emit_activity` before making mutations. +2. Prefer `orgx_request_decision` before irreversible or org-wide changes. +3. Use `orgx_apply_changeset` when you need idempotent batched state updates. +4. Register artifacts for anything another operator would need to inspect later. +5. Verify completion and proof state after major mutations. + +## Examples + +### Batched entity mutation + +```js +orgx_apply_changeset({ + initiative_id: "aa6d16dc-d450-417f-8a17-fd89bd597195", + idempotency_key: "run_abc_turn_7_commit_1", + operations: [ + { op: "task.update", task_id: "task_uuid", status: "in_progress" }, + { op: "decision.create", title: "Use SSE for live updates", urgency: "medium" } + ] +}) +``` + +### Reassign a stream + +```js +orgx_reassign_stream({ + initiative_id: "aa6d16dc-d450-417f-8a17-fd89bd597195", + workstream_id: "7f8e2f61-...", + domain: "operations", + role: "reliability" +}) +``` + +### Run control + +```js +orgx_run_action({ + runId: "9d5c8b2b-...", + action: "pause", + reason: "Waiting for approval on production cutover" +}) +``` + +## Safety note + +This skill assumes the runtime actually exposes the elevated tools. In the managed OrgX agent suite, many domain-scoped surfaces intentionally hide them. If a tool is unavailable, fall back to the safe `orgx` skill and request the necessary human decision or orchestration context. diff --git a/skills/orgx-product-agent/SKILL.md b/skills/orgx-product-agent/SKILL.md index ad2f3f7e..14c7fb63 100644 --- a/skills/orgx-product-agent/SKILL.md +++ b/skills/orgx-product-agent/SKILL.md @@ -36,4 +36,5 @@ When producing product artifacts: ## Reporting Protocol (OrgX) - Use `orgx_emit_activity` for progress updates and next steps. -- Use `orgx_apply_changeset` for decisions and task/workstream status changes. +- Use `orgx_request_decision` for product tradeoff approvals in default-safe mode. +- Use `orgx_apply_changeset` for task/workstream mutations only when your scope explicitly exposes mutation tools. diff --git a/skills/orgx-sales-agent/SKILL.md b/skills/orgx-sales-agent/SKILL.md index 565cf103..a2ba256f 100644 --- a/skills/orgx-sales-agent/SKILL.md +++ b/skills/orgx-sales-agent/SKILL.md @@ -37,4 +37,5 @@ When producing sales materials: ## Reporting Protocol (OrgX) - `orgx_emit_activity` for progress. -- `orgx_apply_changeset` for decisions and approvals when required. +- `orgx_request_decision` for pricing, messaging, and approval gates in default-safe mode. +- Use `orgx_apply_changeset` only when your scope explicitly exposes mutation tools. diff --git a/skills/orgx/SKILL.md b/skills/orgx/SKILL.md index f9129253..32f04969 100644 --- a/skills/orgx/SKILL.md +++ b/skills/orgx/SKILL.md @@ -1,7 +1,7 @@ --- name: orgx -description: Use when managing work with OrgX — reporting progress, requesting decisions, registering artifacts, syncing memory, checking quality gates, or viewing org status. Activates for phrases like "report progress", "request approval", "create initiative", "check orgx", "sync with orgx", "register artifact". -version: 3.0.0 +description: Use when managing work through the OrgX OpenClaw plugin — reporting progress, requesting decisions, registering artifacts, syncing memory, checking quality gates, inspecting agent config policy, or viewing org status. Activates for phrases like "report progress", "request approval", "check orgx", "sync with orgx", or "register artifact". +version: 3.1.0 user-invocable: true tags: - orchestration @@ -12,39 +12,107 @@ tags: # OrgX Integration -Connect to OrgX for multi-agent orchestration, decision workflows, initiative tracking, model routing, quality gates, and structured work reporting. +Use this skill when the **OrgX OpenClaw plugin** is installed and connected. This skill describes the **local plugin MCP surface** exposed by `@useorgx/openclaw-plugin`, not the broader hosted OrgX platform. + +> Default-safe rule: if you are using a domain-scoped OrgX endpoint or the managed OrgX agent suite, prefer the **reporting contract** (`orgx_emit_activity`, `orgx_request_decision`, `orgx_register_artifact`) unless you know your scope explicitly allows mutation tools. ## Quick Start ```bash -# Install the plugin -openclaw plugins install @useorgx/openclaw-plugin +# Install from ClawHub +openclaw plugins install clawhub:@useorgx/openclaw-plugin -# Or via npx -npx @useorgx/openclaw-plugin +# Pair with OrgX +openclaw orgx connect ``` After installing, pair with OrgX via the live dashboard at `http://127.0.0.1:18789/orgx/live` or set `ORGX_API_KEY` in your environment. Managed agent-suite provisioning and MCP client config edits are opt-in. -## MCP Tools Reference +## Tool Surface -### Work Reporting (primary contract) +### Default-safe tools -Use the **two-tool reporting contract** for launch reporting: +These are the tools you should assume are available in the plugin's domain-scoped OrgX surface: -**`orgx_emit_activity`** — Append-only telemetry (frequent updates). -``` +- `orgx_status` +- `orgx_sync` +- `list_agent_configs` +- `get_agent_config` +- `orgx_emit_activity` +- `orgx_report_progress` +- `update_stream_progress` (legacy alias) +- `orgx_register_artifact` +- `orgx_request_decision` +- `orgx_spawn_check` +- `orgx_quality_score` +- `orgx_proof_status` +- `orgx_record_outcome` +- `orgx_get_outcome_attribution` +- `orgx_verify_completion` + +### Mutation and admin tools + +These exist in the plugin, but are **not guaranteed** in every domain scope. + +Available to operations and/or orchestration flows: + +- `update_agent_config` +- `orgx_apply_changeset` +- `orgx_reassign_stream` +- `orgx_reassign_streams` +- `orgx_agent_sessions` +- `orgx_resume_agent_session` +- `orgx_clear_agent_session` + +Available on the unscoped `/orgx/mcp` endpoint for power users and debugging: + +- `orgx_sentinel_catalog` +- `orgx_delegation_preflight` +- `orgx_run_action` +- `orgx_checkpoints_list` +- `orgx_checkpoint_restore` +- `orgx_create_entity` +- `orgx_update_entity` +- `orgx_list_entities` + +If you explicitly need that elevated surface, use the `orgx-power` skill. + +## Reporting Contract + +### Progress updates + +Use `orgx_emit_activity` as the append-only status feed. + +```js orgx_emit_activity({ initiative_id: "aa6d16dc-d450-417f-8a17-fd89bd597195", message: "Implemented auth middleware and validated redirects", - phase: "execution", // intent | execution | blocked | review | handoff | completed - progress_pct: 60, // optional 0-100 - next_step: "Add integration tests" // optional + phase: "execution", + progress_pct: 60, + next_step: "Add integration tests" }) ``` -**`orgx_apply_changeset`** — Transactional state mutations (batched, idempotent). +Use `orgx_report_progress` or `update_stream_progress` only when a caller explicitly expects those aliases. + +### Human decisions + +Use `orgx_request_decision` as the default-safe decision path. + +```js +orgx_request_decision({ + initiative_id: "aa6d16dc-d450-417f-8a17-fd89bd597195", + question: "Approve the SSE rollout plan?", + context: "Load test passed, but dashboard reconnect behavior still needs manual QA.", + options: ["Approve rollout", "Hold for QA", "Rework plan"], + urgency: "medium", + blocking: true +}) ``` + +If your scope explicitly allows `orgx_apply_changeset`, use it for batched state mutations and idempotent updates. + +```js orgx_apply_changeset({ initiative_id: "aa6d16dc-d450-417f-8a17-fd89bd597195", idempotency_key: "run_abc_turn_7_commit_1", @@ -55,126 +123,89 @@ orgx_apply_changeset({ }) ``` -Backward-compatible aliases: +Backward-compatible aliases still exist: + - `orgx_report_progress` delegates to `orgx_emit_activity` +- `update_stream_progress` delegates to `orgx_report_progress` - `orgx_request_decision` delegates to `orgx_apply_changeset` (`decision.create`) -**`orgx_register_artifact`** — Register a deliverable (PR, document, config, etc.). -``` +### Deliverables + +Register anything that should show up in OrgX history with `orgx_register_artifact`. + +```js orgx_register_artifact({ name: "PR #107: Fix Vercel build size", - artifact_type: "pr", // pr | commit | document | config | report | design | other + artifact_type: "pr", description: "Reduced function size by pruning recursive assets", - url: "https://github.com/org/repo/pull/107" // (optional) + url: "https://github.com/org/repo/pull/107" }) ``` -### Org Status & Sync +## Common Workflows -**`orgx_status`** — View active initiatives, agent states, pending decisions, tasks. +### Org status and memory sync -**`orgx_sync`** — Push local memory/daily log to OrgX, receive org context back. -``` +- `orgx_status` for active initiatives, pending decisions, and task state. +- `orgx_sync` to push local memory and receive current org context. + +```js orgx_sync({ memory: "Contents of MEMORY.md", dailyLog: "Today's session summary" }) ``` -### Quality & Spawning +### Quality and proof -**`orgx_spawn_check`** — Check quality gate + get model routing before spawning a sub-agent. -``` -orgx_spawn_check({ domain: "engineering", taskId: "..." }) -// Returns: { allowed: true, modelTier: "sonnet", checks: {...} } -``` +- `orgx_spawn_check` before handing work to another model or agent. +- `orgx_quality_score` after completing a meaningful unit of work. +- `orgx_proof_status`, `orgx_verify_completion`, and `orgx_get_outcome_attribution` for proof ladder checks. -**`orgx_quality_score`** — Record quality score (1-5) for completed work. -``` -orgx_quality_score({ - taskId: "...", - domain: "engineering", - score: 4, - notes: "Clean implementation, good test coverage" -}) +```js +orgx_spawn_check({ domain: "engineering", taskId: "..." }) ``` -### Entity Management - -**`orgx_create_entity`** — Create an initiative, workstream, task, decision, milestone, artifact, or blocker. - -**`orgx_update_entity`** — Update status/fields on any entity. +### Agent policy visibility -**`orgx_list_entities`** — Query entities by type and status. +Use these when you need to inspect the managed OrgX agent behavior policy: -### Run Control +- `list_agent_configs` +- `get_agent_config` -**`orgx_delegation_preflight`** — Score scope quality and estimate ETA/cost before execution. - -**`orgx_run_action`** — Pause, resume, cancel, or rollback a run. - -**`orgx_checkpoints_list`** / **`orgx_checkpoint_restore`** — List and restore run checkpoints. +Only orchestration and operations flows should assume `update_agent_config` is available. ## Reporting Protocol -When working on a task or initiative, follow the two-tool reporting contract. This keeps state deterministic and idempotent. - ### On task start -Call `orgx_emit_activity` with `phase: "intent"` and a brief summary of what you're about to do. - -### At meaningful progress points -Call `orgx_emit_activity` at natural checkpoints: after finishing research, after implementation passes, after tests pass, etc. Include `progress_pct` when possible. - -### When you need a human decision -Call `orgx_apply_changeset` with a `decision.create` operation including clear context/options. Set `blocking: true` when work must pause. Set urgency appropriately: -- **low** — Can wait hours/days -- **medium** — Should be decided today -- **high** — Blocking progress, needs attention soon -- **urgent** — Critical path, needs immediate attention -### When you produce a deliverable -Call `orgx_register_artifact` for anything the team should see: PRs, documents, config changes, reports, design files. Include a URL when available. +Call `orgx_emit_activity` with `phase: "intent"` and a short summary of the intended work. -### On task completion -1. Call `orgx_emit_activity` with `phase: "completed"` and `progress_pct: 100` -2. Call `orgx_apply_changeset` to mark task/milestone completion or record final decisions -3. Call `orgx_quality_score` to self-assess your work (1-5 scale) +### At meaningful progress points -### On blockers -Call `orgx_emit_activity` with `phase: "blocked"` and describe the blocker. If human intervention is needed, use `orgx_apply_changeset` with a `decision.create` op. +Call `orgx_emit_activity` after research, implementation, verification, or handoff milestones. Include `progress_pct` when the state is clear. -## Model Routing +### When blocked -OrgX classifies tasks for model selection: +1. Call `orgx_emit_activity` with `phase: "blocked"`. +2. If a human decision is required, call `orgx_request_decision`. +3. Only use `orgx_apply_changeset` directly if your scope explicitly allows mutation tools. -| Task Type | Tier | Model | -|---|---|---| -| Architecture, strategy, decisions, RFCs | **opus** | `anthropic/claude-opus-4-6` | -| Implementation, code, features, docs | **sonnet** | `anthropic/claude-sonnet-4` | -| Status checks, formatting, templates | **local** | `ollama/qwen2.5-coder:32b` | +### On completion -Always call `orgx_spawn_check` before spawning sub-agents to get the right model tier. +1. Call `orgx_emit_activity` with `phase: "completed"` and `progress_pct: 100`. +2. Register the artifact if something ship-worthy was produced. +3. Record a quality score when appropriate. ## Live Dashboard -The plugin serves a live dashboard at `http://127.0.0.1:18789/orgx/live` showing: -- **Activity Timeline** — Real-time feed of agent work with threaded session views -- **Agents/Chats** — Active sessions grouped by agent -- **Decisions** — Pending approvals with inline approve/reject -- **Initiatives** — Active workstreams and progress - -## Entity API - -For direct API access: -``` -GET /api/entities?type={type}&status={status}&limit={n} -POST /api/entities -PATCH /api/entities -POST /api/entities/{type}/{id}/{action} -``` +The plugin serves a local dashboard at `http://127.0.0.1:18789/orgx/live` showing: -Entity types: `initiative`, `workstream`, `task`, `decision`, `milestone`, `artifact`, `agent`, `blocker` +- activity timeline +- active agent/chat sessions +- pending decisions +- initiative and workstream state -## MCP Server (mcp.useorgx.com) +## Hosted OrgX MCP Server -For environments that support MCP servers directly (Claude Desktop, Cursor, etc.), connect to `mcp.useorgx.com` for the full suite of 26+ OrgX tools including initiative management, decision workflows, and agent orchestration. +`https://mcp.useorgx.com/mcp` exists as a separate hosted OrgX MCP surface. Treat that as **separate from this plugin skill** unless the user explicitly asks for the hosted, server-side toolset.