@revisium/orchestrator 0.1.0-alpha.2 → 0.1.0-alpha.3

package/control-plane/bootstrap.config.json

@@ -47,6 +47,31 @@
             "type": "number",
             "default": 0
           },
+          "playbook_id": {
+            "type": "string",
+            "default": "",
+            "description": "Installed playbook selected for this run"
+          },
+          "pipeline_id": {
+            "type": "string",
+            "default": "",
+            "description": "Installed pipeline row id selected for this run"
+          },
+          "params": {
+            "type": "string",
+            "default": "",
+            "description": "Serialized JSON run params"
+          },
+          "route_decision": {
+            "type": "string",
+            "default": "",
+            "description": "Serialized JSON structured route decision"
+          },
+          "execution_profile": {
+            "type": "string",
+            "default": "",
+            "description": "Serialized JSON resolved execution profile"
+          },
           "created_by": {
             "type": "string",
             "default": ""
@@ -285,6 +310,21 @@
             "default": "",
             "description": "Serialized JSON, secret-redacted, capped"
           },
+          "artifact_ref": {
+            "type": "string",
+            "default": "",
+            "description": "Stable run artifact reference, e.g. run_id/attempt_id"
+          },
+          "stdout_tail": {
+            "type": "string",
+            "default": "",
+            "description": "Secret-redacted process stdout tail, capped"
+          },
+          "stderr_tail": {
+            "type": "string",
+            "default": "",
+            "description": "Secret-redacted process stderr tail, capped"
+          },
           "lesson": {
             "type": "string",
             "default": ""
@@ -452,7 +492,12 @@
           "runner": {
             "type": "string",
             "default": "claude-code",
-            "description": "claude-code|codex|script"
+            "description": "Deprecated alias for runner_id"
+          },
+          "runner_id": {
+            "type": "string",
+            "default": "",
+            "description": "Portable playbook runner binding, for example claude-code or revo-integrator"
           },
           "allowed_tools": {
             "type": "array",
@@ -828,7 +873,7 @@
       "data": {
         "id": "integrator",
         "name": "integrator",
-        "system_prompt": "[DEPRECATED] Integration is now deterministic code in src/runners/integrator.ts; this role is retired from the executed chain and is not dispatched. Kept only so `run create --role integrator` validates against KNOWN_ROLES.",
+        "system_prompt": "[DEPRECATED] Integration is now deterministic code in src/runners/integrator.ts; this role is retired from the executed chain and is not dispatched. Kept only so `run create --role integrator` resolves to a seeded role row.",
         "model_level": "standard",
         "effort": "high",
         "runner": "script",

package/control-plane/default-playbook/catalog/pipelines.json

@@ -0,0 +1,329 @@
+[
+  {
+    "id": "feature-development",
+    "path": "prompts/orchestrator.md",
+    "triggers": [
+      "new feature",
+      "multi-repo change",
+      "task-to-PR work"
+    ],
+    "required_roles": [
+      "orchestrator",
+      "analyst",
+      "reviewer",
+      "developer",
+      "integrator",
+      "watcher"
+    ],
+    "alternative_roles": [],
+    "optional_roles": [],
+    "route_gates": [
+      "task spec approval",
+      "merge approval"
+    ],
+    "platform_invocation": "canonical-only",
+    "execution_policy": {
+      "raw": [
+        "Built-in default (slice 5, plan 0015): the pipeline graph is DATA — see template_json.",
+        "analyst -> reviewer[plan gate] -> developer -> reviewer[code] (bounded rework, cap 3) -> integrator(script) -> watcher[post-integrator] -> merge gate."
+      ],
+      "template_json": {
+        "specVersion": "1.0",
+        "pipelineId": "feature-development",
+        "entry": "analyst",
+        "verdicts": {
+          "domain": [
+            "approved",
+            "clean",
+            "blocker",
+            "changes_requested"
+          ]
+        },
+        "nodes": {
+          "analyst": {
+            "id": "analyst",
+            "kind": "agent",
+            "roleRef": "role:analyst",
+            "next": "planReviewer",
+            "onFailure": "abort",
+            "resultSchema": "schema:plan"
+          },
+          "planReviewer": {
+            "id": "planReviewer",
+            "kind": "agent",
+            "roleRef": "role:reviewer",
+            "next": "planGate",
+            "onFailure": "abort",
+            "resultSchema": "schema:reviewVerdict"
+          },
+          "planGate": {
+            "id": "planGate",
+            "kind": "humanGate",
+            "reason": "plan-review",
+            "outcomes": [
+              "approved"
+            ],
+            "branches": [
+              {
+                "when": {
+                  "op": "verdict.eq",
+                  "value": "approved"
+                },
+                "goto": "developer"
+              },
+              {
+                "default": "blockedEnd"
+              }
+            ]
+          },
+          "developer": {
+            "id": "developer",
+            "kind": "agent",
+            "roleRef": "role:developer",
+            "next": "codeReview",
+            "onFailure": "abort",
+            "resultSchema": "schema:change"
+          },
+          "codeReview": {
+            "id": "codeReview",
+            "kind": "agent",
+            "roleRef": "role:reviewer",
+            "next": "codeReviewRouter",
+            "onFailure": "abort",
+            "resultSchema": "schema:reviewVerdict"
+          },
+          "codeReviewRouter": {
+            "id": "codeReviewRouter",
+            "kind": "choice",
+            "branches": [
+              {
+                "when": {
+                  "op": "verdict.in",
+                  "value": [
+                    "approved",
+                    "clean"
+                  ]
+                },
+                "goto": "integrator"
+              },
+              {
+                "when": {
+                  "op": "all",
+                  "of": [
+                    {
+                      "op": "verdict.in",
+                      "value": [
+                        "blocker",
+                        "changes_requested"
+                      ]
+                    },
+                    {
+                      "op": "counter.lt",
+                      "scope": "codeReviewLoop",
+                      "value": 3
+                    }
+                  ]
+                },
+                "goto": "reworkDeveloper"
+              },
+              {
+                "default": "blockedEnd"
+              }
+            ]
+          },
+          "reworkDeveloper": {
+            "id": "reworkDeveloper",
+            "kind": "agent",
+            "roleRef": "role:developer",
+            "next": "codeReview",
+            "onFailure": "abort",
+            "resultSchema": "schema:change",
+            "incrementCounters": [
+              "codeReviewLoop"
+            ]
+          },
+          "integrator": {
+            "id": "integrator",
+            "kind": "script",
+            "scriptRef": "script:integrator",
+            "next": "watcherPost",
+            "catch": [
+              {
+                "onError": "revo.ScriptBlocked",
+                "goto": "blockedEnd"
+              },
+              {
+                "onError": "revo.ScriptFailed",
+                "goto": "failedEnd"
+              }
+            ],
+            "onFailure": "route",
+            "resultSchema": "schema:integration"
+          },
+          "watcherPost": {
+            "id": "watcherPost",
+            "kind": "agent",
+            "roleRef": "role:watcher",
+            "next": "watcherRouter",
+            "onFailure": "abort",
+            "resultSchema": "schema:watchVerdict"
+          },
+          "watcherRouter": {
+            "id": "watcherRouter",
+            "kind": "choice",
+            "branches": [
+              {
+                "when": {
+                  "op": "verdict.in",
+                  "value": [
+                    "approved",
+                    "clean"
+                  ]
+                },
+                "goto": "mergeGate"
+              },
+              {
+                "when": {
+                  "op": "all",
+                  "of": [
+                    {
+                      "op": "verdict.in",
+                      "value": [
+                        "blocker",
+                        "changes_requested"
+                      ]
+                    },
+                    {
+                      "op": "counter.lt",
+                      "scope": "watcherLoop",
+                      "value": 3
+                    }
+                  ]
+                },
+                "goto": "watcherRework"
+              },
+              {
+                "default": "blockedEnd"
+              }
+            ]
+          },
+          "watcherRework": {
+            "id": "watcherRework",
+            "kind": "agent",
+            "roleRef": "role:developer",
+            "next": "integrator",
+            "onFailure": "abort",
+            "resultSchema": "schema:change",
+            "incrementCounters": [
+              "watcherLoop"
+            ]
+          },
+          "mergeGate": {
+            "id": "mergeGate",
+            "kind": "humanGate",
+            "reason": "merge-review",
+            "outcomes": [
+              "approved"
+            ],
+            "branches": [
+              {
+                "when": {
+                  "op": "verdict.eq",
+                  "value": "approved"
+                },
+                "goto": "mergedEnd"
+              },
+              {
+                "default": "blockedEnd"
+              }
+            ]
+          },
+          "mergedEnd": {
+            "id": "mergedEnd",
+            "kind": "terminal",
+            "status": "succeeded"
+          },
+          "failedEnd": {
+            "id": "failedEnd",
+            "kind": "terminal",
+            "status": "failed"
+          },
+          "blockedEnd": {
+            "id": "blockedEnd",
+            "kind": "terminal",
+            "status": "blocked"
+          }
+        },
+        "title": "Feature development — plan + merge gates, bounded code-review + watcher rework",
+        "policy": {
+          "conflicts": [
+            [
+              "developer",
+              "reviewer"
+            ]
+          ],
+          "enforcement": "strict"
+        },
+        "scopes": {
+          "codeReviewLoop": {
+            "cap": 3,
+            "parent": null
+          },
+          "watcherLoop": {
+            "cap": 3,
+            "parent": null
+          }
+        }
+      }
+    }
+  },
+  {
+    "id": "local-change",
+    "path": "prompts/orchestrator.md",
+    "triggers": [
+      "small local edit",
+      "obvious fix",
+      "repo-local maintenance"
+    ],
+    "required_roles": [
+      "orchestrator",
+      "developer"
+    ],
+    "alternative_roles": [],
+    "optional_roles": [],
+    "route_gates": [],
+    "platform_invocation": "canonical-only",
+    "execution_policy": {
+      "raw": [
+        "Built-in default (slice 5, plan 0015): the pipeline graph is DATA — see template_json.",
+        "orchestrator routes; the graph runs developer -> done with no gate."
+      ],
+      "template_json": {
+        "specVersion": "1.0",
+        "pipelineId": "local-change",
+        "entry": "developer",
+        "verdicts": {
+          "domain": [
+            "approved"
+          ]
+        },
+        "nodes": {
+          "developer": {
+            "id": "developer",
+            "kind": "agent",
+            "roleRef": "role:developer",
+            "next": "doneEnd",
+            "onFailure": "abort",
+            "resultSchema": "schema:change"
+          },
+          "doneEnd": {
+            "id": "doneEnd",
+            "kind": "terminal",
+            "status": "succeeded"
+          }
+        },
+        "title": "Local change — developer only, no gate"
+      }
+    }
+  }
+]

package/control-plane/default-playbook/catalog/roles.json

@@ -0,0 +1,56 @@
+[
+  {
+    "id": "orchestrator",
+    "path": "prompts/orchestrator.md",
+    "surface": "any",
+    "rights": "read-only",
+    "allowed_tools": ["Read", "Grep", "Glob"],
+    "default_model_level": "deep",
+    "runner_id": "claude-code"
+  },
+  {
+    "id": "analyst",
+    "path": "prompts/analyst.md",
+    "surface": "any",
+    "rights": "read-only",
+    "allowed_tools": ["Read", "Grep", "Glob"],
+    "default_model_level": "deep",
+    "runner_id": "claude-code"
+  },
+  {
+    "id": "reviewer",
+    "path": "prompts/reviewer.md",
+    "surface": "any",
+    "rights": "read-only",
+    "allowed_tools": ["Read", "Grep", "Glob"],
+    "default_model_level": "deep",
+    "runner_id": "claude-code"
+  },
+  {
+    "id": "developer",
+    "path": "prompts/developer.md",
+    "surface": "any",
+    "rights": "write-working-tree",
+    "allowed_tools": ["Read", "Grep", "Glob", "Edit", "Write", "Bash"],
+    "default_model_level": "standard",
+    "runner_id": "claude-code"
+  },
+  {
+    "id": "integrator",
+    "path": "prompts/integrator.md",
+    "surface": "repo",
+    "rights": "git-gh",
+    "allowed_tools": ["Read", "Bash"],
+    "default_model_level": "standard",
+    "runner_id": "revo-integrator"
+  },
+  {
+    "id": "watcher",
+    "path": "prompts/watcher.md",
+    "surface": "repo",
+    "rights": "read-only",
+    "allowed_tools": ["Read", "Grep", "Glob", "Bash"],
+    "default_model_level": "cheap",
+    "runner_id": "claude-code"
+  }
+]

package/control-plane/default-playbook/package.json

@@ -0,0 +1,5 @@
+{
+  "name": "@revisium/orchestrator-default-playbook",
+  "version": "0.1.0",
+  "description": "Built-in default agent playbook (roles + data-driven pipelines) seeded by `revo bootstrap` so a fresh control-plane has a working pipeline out-of-the-box."
+}

package/control-plane/default-playbook/playbook.json

@@ -0,0 +1,13 @@
+{
+  "id": "revisium-default",
+  "name": "Revisium Default Playbook",
+  "schema_version": 2,
+  "package": "@revisium/orchestrator-default-playbook",
+  "catalogs": {
+    "roles": "catalog/roles.json",
+    "pipelines": "catalog/pipelines.json"
+  },
+  "supported_runtimes": [
+    "revo"
+  ]
+}

package/control-plane/default-playbook/prompts/analyst.md

@@ -0,0 +1,27 @@
+# Analyst
+
+You are the **analyst** role in a software delivery pipeline. You run FIRST, before any
+code is written, and you do not edit files — you read and reason.
+
+## Goal
+
+Turn the task request into a concrete, reviewable **plan** the developer can implement and a
+reviewer can check against. The plan is the artifact a human approves at the plan gate.
+
+## What to do
+
+1. Read the relevant code, configuration, and docs to understand the current behavior.
+2. State the problem precisely: what is being asked, what is in scope, what is explicitly out.
+3. Identify the files/modules that must change and the key risks (data, contracts, security,
+   migrations, concurrency, public API).
+4. Produce a short, ordered implementation plan with verification steps.
+
+## Output
+
+Emit a structured plan. End your output with a single clear verdict token:
+
+- `approved` — the task is well understood and the plan is ready for a developer.
+- `changes_requested` — the request is ambiguous or under-specified; explain what is missing.
+- `blocker` — the task cannot proceed as stated (e.g. conflicts with an invariant); explain why.
+
+Keep it concise. You are read-only: never modify the working tree.

package/control-plane/default-playbook/prompts/developer.md

@@ -0,0 +1,25 @@
+# Developer
+
+You are the **developer** role. You implement the approved plan and you are the only role
+that writes to the working tree.
+
+## Goal
+
+Make the smallest correct change that satisfies the approved plan, with verification, so the
+reviewer can approve it and the integrator can ship it.
+
+## What to do
+
+1. Implement the plan. Do not gold-plate and do not expand scope beyond what was approved.
+2. Follow the existing conventions of the codebase you are editing.
+3. Run the project's verification (build, lint, tests) and fix what you broke.
+4. On a rework pass (reviewer requested changes), address each reviewer finding directly.
+
+## Output
+
+Summarize what you changed and how you verified it, then end with a verdict token:
+
+- `approved` — the change is implemented and verification passes.
+- `blocker` — you could not complete the change (explain the obstacle for a human).
+
+You may read, edit, write, and run commands in the working tree, scoped to the task repo.

package/control-plane/default-playbook/prompts/integrator.md

@@ -0,0 +1,20 @@
+# Integrator
+
+The **integrator** is a built-in SYSTEM SCRIPT, not an LLM agent. The engine dispatches it via
+the `revo-integrator` runner; this file documents its contract.
+
+## Goal
+
+Take the developer's approved change and integrate it: stage the working-tree diff onto a
+feature branch and open (or update) a pull request via `git` + `gh`.
+
+## Behavior
+
+- Commits the change on a feature branch derived from the task id.
+- Opens a draft PR (or reuses an existing one for the same branch).
+- Reports an integration result the pipeline routes on:
+  - success — proceed to the post-integration watcher.
+  - `revo.ScriptBlocked` — a precondition failed (e.g. dirty base); the run blocks for a human.
+  - `revo.ScriptFailed` — git/gh failed; the run fails.
+
+The integrator never authors product code — it only ships what the developer produced.

package/control-plane/default-playbook/prompts/orchestrator.md

@@ -0,0 +1,23 @@
+# Orchestrator
+
+You are the **orchestrator** role. You route and coordinate; you do not write code.
+
+## Goal
+
+Understand the incoming task well enough to confirm the selected pipeline fits, and frame the
+work for the roles that follow (analyst, developer, …).
+
+## What to do
+
+1. Read the task request and the target repository context.
+2. Confirm scope and the chosen pipeline are appropriate; surface mismatches early.
+3. Hand off cleanly to the next role in the pipeline.
+
+## Output
+
+End your output with a verdict token:
+
+- `approved` — the task is framed and ready to proceed.
+- `blocker` — the task cannot proceed as routed (explain for a human).
+
+You are read-only: never modify the working tree.

package/control-plane/default-playbook/prompts/reviewer.md

@@ -0,0 +1,27 @@
+# Reviewer
+
+You are the **reviewer** role. You are read-only and decorrelated from the developer: you
+never wrote the change you are reviewing, and you must not edit it.
+
+## Goal
+
+Judge whether the work in front of you is correct, complete, and safe to proceed. You review
+both **plans** (before development) and **code** (after development), depending on where you
+are invoked in the pipeline.
+
+## What to do
+
+1. Read the plan or diff and the surrounding code it touches.
+2. Check correctness, scope creep, missing tests/verification, and risk (data, contracts,
+   security, migrations, concurrency, public API).
+3. Be specific: cite the file and the concern. Distinguish must-fix from nice-to-have.
+
+## Output
+
+End your output with a single clear verdict token:
+
+- `approved` — proceed; the work is correct and complete (nits are acceptable to defer).
+- `changes_requested` — fixable issues that must be addressed before proceeding.
+- `blocker` — a serious defect or risk that must be resolved (drives the bounded rework loop).
+
+Keep findings actionable. You are read-only: never modify the working tree.

package/control-plane/default-playbook/prompts/watcher.md

@@ -0,0 +1,24 @@
+# Watcher
+
+You are the **watcher** role. You run AFTER integration (the PR is open) and you are read-only.
+
+## Goal
+
+Confirm the integrated change is healthy before it reaches the merge gate: the PR exists, CI
+is not red, and nothing obviously broke.
+
+## What to do
+
+1. Inspect the opened pull request and its checks.
+2. Look for failing CI, merge conflicts, or missing required status.
+3. Do not edit code — if something is wrong, report it so the pipeline can rework or block.
+
+## Output
+
+End your output with a single clear verdict token:
+
+- `clean` — the integrated change is healthy; proceed to the merge gate.
+- `dirty` — something is wrong with the integration (drives rework/fail per the pipeline).
+- `blocker` — a hard problem a human must resolve.
+
+You are read-only: never modify the working tree.