From 8b65aea55d0c7afbad72892b173e3098d0531e9a Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 2 Oct 2026 01:07:43 +0000 Subject: [PATCH] Teach the Cursor plugin that only a person settles a decision The OrgX MCP server no longer lets a model approve or reject a decision: approve_decision, reject_decision, and orgx_decide approve/reject return where the person decides (the decisions widget for ordinary decisions, otherwise the review_url in OrgX). It also added orgx_command_status, which the default v2 profile this plugin connects with exposes. - commands/orgx-review-pending-decisions: drop "do not auto-approve without confirmation", which implied the agent could approve; point the person to the widget or review_url, never call orgx_widget_decide, and confirm a settled decision with orgx_command_status. - rules/orgx-execution-loop: report the state OrgX holds; decisions wait on a person, spawned work is checked with orgx_command_status until next_poll_after_ms is null. - skills/orgx-runtime-reporting: decisions wait on the person; a new step reports started work as started and reads its real state; unclear writes retry with the same idempotency key. - skills/orgx-execution-control-plane, agents/orchestrator: the same rule in one line each. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01RM5b4LVyYeCd4HzETsPviS --- agents/orchestrator.md | 2 ++ commands/orgx-review-pending-decisions.md | 9 ++++---- rules/orgx-execution-loop.mdc | 1 + skills/orgx-execution-control-plane/SKILL.md | 1 + skills/orgx-runtime-reporting/SKILL.md | 22 +++++++++++++++++--- 5 files changed, 28 insertions(+), 7 deletions(-) diff --git a/agents/orchestrator.md b/agents/orchestrator.md index 7ff530a..bf127a6 100644 --- a/agents/orchestrator.md +++ b/agents/orchestrator.md @@ -4,4 +4,6 @@ Coordinate cross-domain work in OrgX. - Keep execution aligned to the active initiative and workstream. - Decide when a specialist agent should be invoked. +- Treat a spawned specialist run as started, not done: check `orgx_command_status` before synthesizing its output. +- Route decisions to the person through their `review_url`; never approve or reject one yourself. - Synthesize specialist outputs into one concrete next step. diff --git a/commands/orgx-review-pending-decisions.md b/commands/orgx-review-pending-decisions.md index eb9fc43..be27a31 100644 --- a/commands/orgx-review-pending-decisions.md +++ b/commands/orgx-review-pending-decisions.md @@ -1,7 +1,8 @@ -Review OrgX decisions that still need human approval. +Review OrgX decisions that still need a person's call. Checklist: - List the pending decisions in priority order. -- Give enough context to approve or reject safely. -- Do not auto-approve anything without explicit user confirmation. -- If a decision blocks execution, say exactly what remains blocked. +- Give enough context for the person to approve or reject safely. +- You cannot settle a decision. Calling `approve_decision`, `reject_decision`, or `orgx_decide` with `action: "approve"` or `"reject"` only returns where the person decides: the decisions widget's Approve button for ordinary decisions, otherwise the decision page in OrgX (`review_url`). Point the person there; never call `orgx_widget_decide`. +- Never say a decision was approved or rejected unless OrgX shows it settled (`orgx_command_status` with `kind: "decision"`). +- If a decision blocks execution, say exactly what remains blocked and that it is waiting on the person. diff --git a/rules/orgx-execution-loop.mdc b/rules/orgx-execution-loop.mdc index 593ac8c..ebb87b3 100644 --- a/rules/orgx-execution-loop.mdc +++ b/rules/orgx-execution-loop.mdc @@ -9,5 +9,6 @@ alwaysApply: true - Prefer starting from OrgX bootstrap context, resumable workstreams, and proof status before inventing new scope. - Use fresh OrgX context injected by the `sessionStart` hook through `additional_context`; if the hook does not report exact-session activation as ready, treat that context as informational rather than authority. - If work is blocked by missing context or a real decision, surface it explicitly instead of guessing. +- Report the state OrgX holds, not the state you asked for. Only a person settles a decision: hand them its `review_url` and say it is waiting on them. Spawning or delegating work starts it; check `orgx_command_status` (`kind: "run"`, the returned run ID) before calling it done, and check again after `next_poll_after_ms` until it is `null`. - Close the loop with proof, artifacts, and verification steps whenever work is ready for review. - Keep repo-local overrides in `.cursor/orgx/` additive to the default OrgX bundle. diff --git a/skills/orgx-execution-control-plane/SKILL.md b/skills/orgx-execution-control-plane/SKILL.md index 8e8c2d4..ccd47a6 100644 --- a/skills/orgx-execution-control-plane/SKILL.md +++ b/skills/orgx-execution-control-plane/SKILL.md @@ -18,4 +18,5 @@ Keep Cursor work anchored to OrgX workstreams, decisions, proof, and execution s - Do not invent work that is not grounded in the active OrgX context. - Do not call work complete without verification. +- Do not call a decision approved or a spawned run done until OrgX says so: decisions are settled only by a person (`review_url`), and `orgx_command_status` reports a run's real state. - Keep repo-local `.cursor/orgx/` overlays additive to the plugin defaults. diff --git a/skills/orgx-runtime-reporting/SKILL.md b/skills/orgx-runtime-reporting/SKILL.md index 765bd88..1c2b5af 100644 --- a/skills/orgx-runtime-reporting/SKILL.md +++ b/skills/orgx-runtime-reporting/SKILL.md @@ -42,19 +42,35 @@ session is still fresh. 4. Handle blockers structurally: - If judgment is required, request a decision with explicit options. +- A decision waits on a person. `approve_decision`, `reject_decision`, and + `orgx_decide` approve/reject only return where the person decides (the + decisions widget for ordinary decisions, otherwise the `review_url` in + OrgX). Report the blocker as waiting on them; never report a decision as + approved or rejected yourself. - If context is missing, report the exact missing dependency. -5. Close execution cleanly: +5. Report started work as started: +- Spawning, delegating, or launching work starts a run; it does not finish + one. Keep the returned run, decision, or command ID and read its real state + with `orgx_command_status` (`kind: "run" | "decision" | "command"`): + `queued`, `held`, `running`, `succeeded`, `failed`, `cancelled`, or + `not_found`, with `waiting_on` naming a person or agent. Check again after + `next_poll_after_ms`; `null` means the state is final. +- If a write's outcome is unclear, retry it with the same idempotency key; + OrgX replays the stored result instead of duplicating the write (a 409 means + the first attempt is still in flight). + +6. Close execution cleanly: - When the task is complete and verified, emit completion activity and update entity state if the task ID is available. -6. If no OrgX IDs are available: +7. If no OrgX IDs are available: - Continue the work, but make the final response easy for the hook reconciler to classify: name decisions, artifacts, blockers, next actions, and verification. - Do not claim OrgX was updated unless an MCP tool or API call actually succeeded. -7. Preserve Work Graph continuity: +8. Preserve Work Graph continuity: - When a Work Graph report is generated, include its `work_graph_fingerprint` and `signup_hydration.hydration_key` in summaries or artifacts that are safe to store.