@lvlup-sw/exarchos 2.7.1 → 2.8.1

package/skills/generic/discovery/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: discovery
+description: "Research and discovery workflow for document deliverables — competitive analyses, architecture comparisons, ADR scaffolding, literature reviews, vendor evaluations. No TDD requirement. Phases: gathering → synthesizing → completed. Triggers: 'discover', 'research', 'explore topic', or discover."
+metadata:
+  author: exarchos
+  version: 1.0.0
+  mcp-server: exarchos
+  category: workflow
+  phase-affinity: gathering
+---
+
+# Discovery Workflow Skill
+
+A workflow type for tasks whose deliverable is a **document, not code**. Explicitly
+exempt from the Iron Law (no failing test requirement) because there is nothing to test.
+
+## When to Use
+
+- Competitive analyses and market research
+- Architecture comparisons and ADR scaffolding
+- Literature reviews and vendor evaluations
+- Design research that does NOT feed into implementation planning
+
+## When NOT to Use
+
+- If the deliverable includes code changes → use `/exarchos:oneshot` or `/exarchos:ideate`
+- If you need TDD enforcement → use any other workflow type
+- If the research feeds directly into implementation → use `/exarchos:ideate` (which includes a design phase)
+
+## Phases
+
+### Phase 1: Gathering (initial)
+
+Collect sources, references, and raw material for the deliverable.
+
+1. Define the research question or deliverable scope
+2. Identify and collect sources (URLs, documents, code references)
+3. Record sources in workflow state:
+
+```typescript
+mcp__exarchos__exarchos_workflow({
+  action: "set", featureId: "<id>",
+  updates: { "artifacts.sources": ["<source1>", "<source2>", "..."] }
+})
+```
+
+4. Create an outline of the deliverable
+
+**Transition:** When `artifacts.sources` is a non-empty array → `synthesizing`
+
+### Phase 2: Synthesizing
+
+Draft the deliverable document from gathered sources.
+
+1. Write the document based on gathered sources and outline
+2. Commit the document to the repo (typically under `docs/research/` or `docs/designs/`)
+3. Record the report path:
+
+```typescript
+mcp__exarchos__exarchos_workflow({
+  action: "set", featureId: "<id>",
+  updates: { "artifacts.report": "<path-to-document>" }
+})
+```
+
+**Transition:** When `artifacts.report` is set → `completed`
+
+### Optional: Escalation to Implementation
+
+If discovery surfaces an implementation need:
+
+1. Note the finding in the report
+2. After completing the discovery workflow, start a new workflow:
+   ```bash
+   ideate <implementation-topic>
+   ```
+   Reference the discovery report as design input.
+
+## Event Emissions
+
+Optionally emit events at key moments for observability:
+
+```typescript
+mcp__exarchos__exarchos_event({
+  action: "append", stream: "<featureId>",
+  event: { type: "discovery.sources_collected", data: { sourceCount: N } }
+})
+```
+
+```typescript
+mcp__exarchos__exarchos_event({
+  action: "append", stream: "<featureId>",
+  event: { type: "discovery.report_committed", data: { path: "<report-path>" } }
+})
+```

package/skills/generic/dogfood/SKILL.md

@@ -10,6 +10,12 @@ metadata:
 
 # Dogfood Skill
 
+## VCS Provider
+
+This skill uses VCS operations through Exarchos MCP actions (`create_issue`, etc.).
+These actions automatically detect and route to the correct VCS provider (GitHub, GitLab, Azure DevOps).
+No `gh`/`glab`/`az` commands needed — the MCP server handles provider dispatch.
+
 ## Overview
 
 Retrospective analysis of Exarchos MCP tool usage. Uses the MCP server's own self-service capabilities as the primary diagnostic instrument — describe APIs, views, playbooks, and runbooks turned inward to diagnose failures.
@@ -144,8 +150,8 @@ Produce the report using the template from `references/report-template.md`. Incl
 
 For findings in the **Code Bug** and **Documentation Issue** buckets, offer to create GitHub issues:
 
-```bash
-gh issue create --title "<type>: <summary>" --body "<issue body>" --label "bug"
+```typescript
+exarchos_orchestrate({ action: "create_issue", title: "<type>: <summary>", body: "<issue body>", labels: ["bug"] })
 ```
 
 Only file issues with user confirmation — present the draft first.

package/skills/generic/dogfood/references/report-template.md

@@ -94,13 +94,13 @@ Issues discovered solely through debug trace (not visible in conversation errors
 Ready-to-file issue bodies for Code Bugs and Documentation Issues:
 
 #### Issue: [CB-1 title]
-```
-gh issue create --title "bug: [summary]" --label "bug" --body "..."
+```typescript
+exarchos_orchestrate({ action: "create_issue", title: "bug: [summary]", body: "...", labels: ["bug"] })
 ```
 
 #### Issue: [DOC-1 title]
-```
-gh issue create --title "docs: [summary]" --label "bug" --body "..."
+```typescript
+exarchos_orchestrate({ action: "create_issue", title: "docs: [summary]", body: "...", labels: ["bug"] })
 ```
 
 ### Patterns & Trends

package/skills/generic/oneshot-workflow/SKILL.md

@@ -11,6 +11,12 @@ metadata:
 
 # Oneshot Workflow Skill
 
+## VCS Provider
+
+This skill uses VCS operations through Exarchos MCP actions (`create_pr`, `merge_pr`, etc.) when the synthesize path is taken.
+These actions automatically detect and route to the correct VCS provider (GitHub, GitLab, Azure DevOps).
+No `gh`/`glab`/`az` commands needed — the MCP server handles provider dispatch.
+
 A lean, four-phase workflow type for changes that are too small to justify the
 full `feature` flow (`ideate → plan → plan-review → delegate → review → synthesize → completed`)
 but still deserve event-sourced auditability and a planning step. The workflow is
@@ -103,7 +109,7 @@ pure functions of `state.oneshot.synthesisPolicy` and the
 |---|---|---|
 | `plan` | Lightweight one-page plan: goal, approach, files to touch, tests to add. No design doc. No subagent dispatch. | `artifacts.plan` set → transition to `implementing` |
 | `implementing` | In-session TDD loop. Write a failing test, make it pass, refactor. Commit as you go. The TDD iron law applies — *no production code without a failing test first*. | Tests pass + typecheck clean + finalize_oneshot called |
-| `synthesize` | Reached **only** when `synthesisOptedIn` is true. Hands off to the existing synthesis flow — see `@skills/synthesis/SKILL.md`. PR created via `gh pr create`, auto-merge enabled, CI gates apply. | PR merged → `completed` |
+| `synthesize` | Reached **only** when `synthesisOptedIn` is true. Hands off to the existing synthesis flow — see `@skills/synthesis/SKILL.md`. PR created via `exarchos_orchestrate({ action: "create_pr" })`, auto-merge enabled, CI gates apply. | PR merged → `completed` |
 | `completed` | Terminal. For direct-commit path, commits are already on the branch — there's nothing more to do. For synthesize path, the PR merge event terminates the workflow. | — |
 
 `cancelled` is also reachable from any phase via the universal cancel
@@ -282,7 +288,7 @@ pipeline view.
 
 If finalize resolved to `synthesize`, hand off to the standard synthesis
 flow — see `@skills/synthesis/SKILL.md`. The same `prepare_synthesis` /
-`validate_pr_body` / `gh pr create` machinery used by the `feature`
+`validate_pr_body` / `create_pr` machinery used by the `feature`
 workflow applies. After the PR merges, the workflow transitions
 `synthesize → completed` via the existing `mergeVerified` guard, same as
 every other workflow type.
@@ -351,7 +357,7 @@ Agent:
      → guard sees policy='on-request' + 1 synthesize.requested event
      → resolves to 'synthesize'
  10. hands off to @skills/synthesis/SKILL.md → prepare_synthesis →
-     validate_pr_body → gh pr create → merge
+     validate_pr_body → create_pr → merge
 ```
 
 ### Example C — `synthesisPolicy: 'always'` (PR mandatory)

package/skills/generic/prune-workflows/SKILL.md

@@ -10,6 +10,12 @@ metadata:
 
 # Prune Workflows Skill
 
+## VCS Provider
+
+This skill's safeguards use VCS operations internally (open PR detection).
+The orchestrate handler manages VCS provider dispatch automatically.
+No `gh`/`glab`/`az` commands needed — the MCP server handles provider dispatch.
+
 ## Overview
 
 Bulk-cancel stale non-terminal workflows that have accumulated in the pipeline. Wraps the `prune_stale_workflows` orchestrate action with an interactive dry-run-then-confirm UX so the user always sees the candidate set before any state mutates.

package/skills/generic/quality-review/references/auto-transition.md

@@ -34,7 +34,7 @@ Quality-review itself is NOT a human checkpoint — it auto-continues. However,
 
 Gate events are automatically emitted by the orchestrate handlers — do NOT manually emit `gate.executed` events via `exarchos_event`.
 
-1. **Read CI status** via `gh pr checks <number>` (or GitHub MCP `pull_request_read` with method `get_status` if available)
+1. **Read CI status** via `exarchos_orchestrate({ action: "check_ci", prId: "<number>" })`
 2. **Gate events** — emitted automatically by `check_static_analysis`, `check_security_scan`, `check_context_economy`, `check_operational_resilience`, `check_workflow_determinism`, and `check_review_verdict` handlers
 3. **Read unified status** via `exarchos_view` with `action: "tasks"`, `fields: ["taskId", "status", "title"]`, `limit: 20`
 4. **Query convergence** via `exarchos_view` with `action: "convergence"`, `workflowId: "<featureId>"` for per-dimension gate results

package/skills/generic/refactor/references/overhaul-track.md

@@ -161,7 +161,7 @@ Invoke `/exarchos:synthesize` skill:
 Skill({ skill: "exarchos:synthesize", args: "<feature-name>" })
 ```
 
-Creates PR via `gh pr create`, updates description via `gh pr edit`. **Human checkpoint:** Confirm merge.
+Creates PR via `exarchos_orchestrate({ action: "create_pr" })`, updates description via `gh pr edit --body`. **Human checkpoint:** Confirm merge.
 
 > Or use GitHub MCP `update_pull_request` if available.
 

package/skills/generic/shepherd/SKILL.md

@@ -11,6 +11,12 @@ metadata:
 
 # Shepherd Skill
 
+## VCS Provider
+
+This skill uses VCS operations through Exarchos MCP actions (`check_ci`, `list_prs`, `merge_pr`, `get_pr_comments`, `add_pr_comment`, etc.).
+These actions automatically detect and route to the correct VCS provider (GitHub, GitLab, Azure DevOps).
+No `gh`/`glab`/`az` commands needed — the MCP server handles provider dispatch.
+
 Iterative loop that shepherds published PRs through CI checks and code reviews to merge readiness. Uses the `assess_stack` composite action for all PR health checks, fixing failures and addressing feedback until the stack is green.
 
 > **Note:** Shepherd is not a separate HSM phase. It operates as a loop within the `synthesize` phase. The workflow phase remains `synthesize` throughout the shepherd iteration cycle. Events (`shepherd.iteration`, `ci.status`) and the `shepherd_status` view track loop progress without requiring a phase transition.
@@ -35,8 +41,8 @@ Activate when:
 ## Prerequisites
 
 - Active workflow with PRs published (PR URLs in `synthesis.prUrl` or `artifacts.pr`)
-- PRs created and pushed (`gh pr create` already ran)
-- GitHub MCP tools available (preferred) or `gh` CLI authenticated
+- PRs created and pushed (`create_pr` already ran)
+- Exarchos MCP tools available for VCS operations
 
 ## Process
 
@@ -126,7 +132,7 @@ These events feed `selfCorrectionRate` and `avgRemediationAttempts` metrics in C
 | `ci-fix` | Read logs, reproduce locally, fix, commit to stack branch |
 | `comment-reply` | Read context from `actionItem.context`, compose response, post via GitHub MCP |
 | `review-address` | Fix code for CHANGES_REQUESTED, reply to each thread |
-| `restack` | Run `git rebase origin/<base>`, verify with `gh pr list` |
+| `restack` | Run `git rebase origin/<base>`, verify with `exarchos_orchestrate({ action: "list_prs" })` |
 | `escalate` | Consult `references/escalation-criteria.md` |
 
 Every inline review comment must get a reply. The goal is that a human scanning the PR sees every thread has a response.
@@ -136,8 +142,11 @@ Every inline review comment must get a reply. The goal is that a human scanning
 After fixes are applied, resubmit the stack:
 ```bash
 git push --force-with-lease
-# Re-enable auto-merge if needed:
-gh pr merge <number> --auto --squash
+```
+
+Re-enable auto-merge if needed:
+```typescript
+exarchos_orchestrate({ action: "merge_pr", prId: "<number>", strategy: "squash" })
 ```
 
 Return to Step 1 for the next iteration. Track iteration count against the limit (default 5). If the limit is reached without reaching `request-approval`, escalate per `references/escalation-criteria.md`.

package/skills/generic/shepherd/references/assess-checklist.md

@@ -11,9 +11,9 @@ mcp__plugin_exarchos_exarchos__exarchos_workflow({ action: "get", featureId: "<i
 
 Extract PR numbers from URLs (e.g., `https://github.com/owner/repo/pull/123` → `123`).
 
-If no PRs in state, check GitHub:
-```bash
-gh pr list --json number,baseRefName,headRefName,url
+If no PRs in state, check VCS:
+```typescript
+exarchos_orchestrate({ action: "list_prs", state: "open" })
 ```
 
 ## 2. CI Check Status
@@ -105,8 +105,8 @@ coderabbit: 5 total, 5 replied
 ## 5. Stack Health
 
 Check the branch stack state:
-```bash
-gh pr list --json number,baseRefName,headRefName,state
+```typescript
+exarchos_orchestrate({ action: "list_prs", state: "open" })
 ```
 
 Verify:
@@ -136,8 +136,8 @@ mcp__plugin_github_github__pull_request_read({
 The response includes `autoMergeRequest` — if null, merge-when-ready is not set.
 
 If `autoMergeRequest` is null, merge-when-ready is not set. Re-enable:
-```bash
-gh pr merge <number> --auto --squash
+```typescript
+exarchos_orchestrate({ action: "merge_pr", prId: "<number>", strategy: "squash" })
 ```
 
 ## 7. Aggregate and Report

package/skills/generic/shepherd/references/fix-strategies.md

@@ -8,7 +8,7 @@ How to address common issues found during shepherd assessment.
 |-----------|----------|
 | Single file, < 20 lines changed | Fix directly in the stack branch |
 | Multiple files, contained concern | Fix directly if < 5 files |
-| Cross-cutting or architectural | Delegate via `/exarchos:delegate --pr-fixes [PR_URL]` |
+| Cross-cutting or architectural | Route to `/exarchos:delegate --fixes` for subagent dispatch |
 | Test changes needed | Fix directly (keep TDD cycle tight) |
 
 **Default to fixing directly** — delegation adds overhead. Only delegate when the fix scope warrants it.
@@ -105,7 +105,7 @@ These events feed `selfCorrectionRate` and `avgRemediationAttempts` metrics in C
 
 If a test passes locally but fails in CI:
 1. Check if it's a known flaky test
-2. Re-run CI: `gh pr checks <number> --watch` (or push an empty commit to retrigger)
+2. Re-run CI: `exarchos_orchestrate({ action: "check_ci", prId: "<number>" })` (or push an empty commit to retrigger)
 3. If consistently flaky, fix the test or mark it with a skip annotation and create a follow-up issue
 
 ## Addressing Inline Review Comments
@@ -268,7 +268,7 @@ When making fixes to stack branches:
    git push --force-with-lease
    ```
 
-**IMPORTANT:** After pushing, verify auto-merge is still enabled: `gh pr view <number> --json autoMergeRequest`.
+**IMPORTANT:** After pushing, verify auto-merge is still enabled: `gh pr view <number> --json autoMergeRequest` (no MCP equivalent yet — use VCS CLI directly).
 
 ## Responding on PRs
 
@@ -286,4 +286,4 @@ mcp__plugin_github_github__add_issue_comment({
   body: "Addressed review feedback:\n- Fixed Sentry bug: ...\n- Replied to DI concern...\n\nAll inline review threads have replies."
 })
 ```
-Fallback (if MCP token lacks write scope): `gh pr comment <number> --body "..."`
+Fallback (if MCP token lacks write scope): `exarchos_orchestrate({ action: "add_pr_comment", prId: "<number>", body: "..." })`

package/skills/generic/synthesis/SKILL.md

@@ -11,6 +11,12 @@ metadata:
 
 # Synthesis Skill
 
+## VCS Provider
+
+This skill uses VCS operations through Exarchos MCP actions (`create_pr`, `merge_pr`, `list_prs`, `check_ci`, etc.).
+These actions automatically detect and route to the correct VCS provider (GitHub, GitLab, Azure DevOps).
+No `gh`/`glab`/`az` commands needed — the MCP server handles provider dispatch.
+
 ## Overview
 
 Submit stacked PRs after review phase completes. The `prepare_synthesis` composite action consolidates readiness checks, stack verification, test validation, and quality signal analysis into a single call -- eliminating the multi-script coordination that historically caused synthesis failures.
@@ -105,20 +111,33 @@ mcp__exarchos__exarchos_orchestrate({
 })
 ```
 
-**Do NOT call `gh pr create` until validation passes.** If validation fails, fix the body and re-validate.
+**Do NOT call `create_pr` until validation passes.** If validation fails, fix the body and re-validate.
 
 ### Step 3: Submit and Merge
 
-Create PRs using the validated body and enable auto-merge:
-```bash
-# For each branch in the stack (bottom-up):
-gh pr create --base <parent-branch> --head <branch> --title "<type>: <what>" --body-file /tmp/pr-body.md
-gh pr merge <number> --auto --squash
+Create PRs using the validated body and enable auto-merge. For each branch in the stack (bottom-up):
+
+```typescript
+// Create PR via VCS MCP action
+exarchos_orchestrate({
+  action: "create_pr",
+  base: "<parent-branch>",
+  head: "<branch>",
+  title: "<type>: <what>",
+  body: "<pr-body>"
+})
+
+// Enable auto-merge
+exarchos_orchestrate({
+  action: "merge_pr",
+  prId: "<number>",
+  strategy: "squash"
+})
 ```
 
 After submission:
 1. **Apply benchmark label** -- If `verification.hasBenchmarks` is true, apply label: `gh pr edit <number> --add-label has-benchmarks`
-2. **Record PR URLs** -- Capture URLs from `gh pr list --json number,url,headRefName`
+2. **Record PR URLs** -- Capture URLs via `exarchos_orchestrate({ action: "list_prs", state: "open" })`
 3. **Update state:**
 
 ```typescript
@@ -135,7 +154,7 @@ For merge ordering strategy, see `references/merge-ordering.md`.
 **Human checkpoint:** Output "Stacked PRs enqueued: [URLs]. Waiting for CI/merge queue." then **PAUSE for user input**: "Merge stack? (yes/no/feedback)"
 
 - **'yes'** -- PRs merge; transition to completed via `cleanup`
-- **'feedback'** -- Route to `delegate --pr-fixes [PR_URL]` to address comments, then return here
+- **'feedback'** -- Route to `shepherd [PR_URL]` to address comments, then return here
 - **'no'** -- Pause workflow; resume later with `rehydrate`
 
 ### Event Emissions (REQUIRED)

package/skills/generic/synthesis/references/github-native-stacking.md

@@ -8,15 +8,15 @@ PR stacking creates a chain of dependent pull requests that merge bottom-up into
 
 ## 1. PR Chain Creation
 
-Create PRs that chain together by setting each PR's `--base` to the previous branch:
+Create PRs that chain together by setting each PR's base to the previous branch:
 
-```bash
-# First PR in chain targets main
-gh pr create --base main --head feat/step-1 --title "feat: step 1" --body "..."
+```typescript
+// First PR in chain targets main
+exarchos_orchestrate({ action: "create_pr", base: "main", head: "feat/step-1", title: "feat: step 1", body: "..." })
 
-# Subsequent PRs target the previous PR's branch
-gh pr create --base feat/step-1 --head feat/step-2 --title "feat: step 2" --body "..."
-gh pr create --base feat/step-2 --head feat/step-3 --title "feat: step 3" --body "..."
+// Subsequent PRs target the previous PR's branch
+exarchos_orchestrate({ action: "create_pr", base: "feat/step-1", head: "feat/step-2", title: "feat: step 2", body: "..." })
+exarchos_orchestrate({ action: "create_pr", base: "feat/step-2", head: "feat/step-3", title: "feat: step 3", body: "..." })
 ```
 
 The resulting chain looks like:
@@ -72,15 +72,14 @@ After rebasing a mid-stack branch, all downstream branches in the stack must als
 
 View the current PR chain and its state:
 
-```bash
-# List all open PRs with base/head branch relationships
-gh pr list --json number,baseRefName,headRefName,title,state \
-  --jq '.[] | "\(.number): \(.baseRefName) <- \(.headRefName) [\(.state)]"'
-
-# Example output:
-# 101: main <- feat/step-1 [OPEN]
-# 102: feat/step-1 <- feat/step-2 [OPEN]
-# 103: feat/step-2 <- feat/step-3 [OPEN]
+```typescript
+// List all open PRs with base/head branch relationships
+exarchos_orchestrate({ action: "list_prs", state: "open" })
+
+// Example output shows PR numbers, base/head branches, titles, and state:
+// 101: main <- feat/step-1 [OPEN]
+// 102: feat/step-1 <- feat/step-2 [OPEN]
+// 103: feat/step-2 <- feat/step-3 [OPEN]
 ```
 
 To validate stack integrity, use the `validate_pr_stack` action via orchestrate:
@@ -97,32 +96,29 @@ exarchos_orchestrate({
 GitHub's native merge queue ensures PRs pass CI before merging:
 
 - **Enable:** Repository Settings > Rules > Branch protection > Require merge queue
-- **Auto-merge:** `gh pr merge --auto --squash` enables auto-merge once checks pass
+- **Auto-merge:** `exarchos_orchestrate({ action: "merge_pr", prId: "<number>", strategy: "squash" })` enables auto-merge once checks pass
 - **For stacks:** Enable auto-merge on each PR, then merge bottom-up
 
-```bash
-# Enable auto-merge on all PRs in the stack
-gh pr merge 101 --auto --squash
-gh pr merge 102 --auto --squash
-gh pr merge 103 --auto --squash
-
-# Merge the first PR to start the cascade
-gh pr merge 101 --squash
+```typescript
+// Enable auto-merge on all PRs in the stack
+exarchos_orchestrate({ action: "merge_pr", prId: "101", strategy: "squash" })
+exarchos_orchestrate({ action: "merge_pr", prId: "102", strategy: "squash" })
+exarchos_orchestrate({ action: "merge_pr", prId: "103", strategy: "squash" })
 ```
 
 After PR 101 merges and its branch is deleted, GitHub retargets PR 102 to `main`. If auto-merge is enabled on PR 102, it merges automatically once CI passes.
 
-## 7. Graphite to GitHub-Native Equivalents
+## 7. Graphite to Exarchos MCP Equivalents
 
-| Graphite Command | GitHub-Native Equivalent |
+| Graphite Command | Exarchos MCP Equivalent |
 |---|---|
 | `gt create <branch> -m "feat: ..."` | `git checkout -b <branch> && git commit -m "feat: ..." && git push -u origin <branch>` |
-| `gt submit --no-interactive --publish --stack` | `gh pr create --base <base> --title "..." --body "..."` (per PR) |
-| `gt log` | `gh pr list --json number,baseRefName,headRefName` |
+| `gt submit --no-interactive --publish --stack` | `exarchos_orchestrate({ action: "create_pr", base: "<base>", title: "...", body: "..." })` (per PR) |
+| `gt log` | `exarchos_orchestrate({ action: "list_prs", state: "open" })` |
 | `gt modify -m "..."` | `git commit --amend -m "..." && git push --force-with-lease` |
 | `gt sync` | `git fetch --prune && git rebase origin/main` |
 | `gt restack` | `git rebase origin/<base-branch>` per branch in stack |
-| `mcp__graphite__run_gt_cmd` | `gh` CLI directly via Bash tool |
+| `mcp__graphite__run_gt_cmd` | `exarchos_orchestrate` VCS actions |
 
 ## 8. Error Handling
 

package/skills/generic/synthesis/references/merge-ordering.md

@@ -2,7 +2,7 @@
 
 ## Overview
 
-GitHub-native stacked PRs merge bottom-up: the base branch merges first, then each dependent branch in sequence. This ordering is enforced by creating PRs with correct base branches and enabling auto-merge (`gh pr merge --auto --squash`).
+GitHub-native stacked PRs merge bottom-up: the base branch merges first, then each dependent branch in sequence. This ordering is enforced by creating PRs with correct base branches and enabling auto-merge via `exarchos_orchestrate({ action: "merge_pr", prId: "<number>", strategy: "squash" })`.
 
 ## Stack Ordering Rules
 

package/skills/generic/synthesis/references/synthesis-steps.md

@@ -74,7 +74,7 @@ The script queries GitHub's PR reviews API for each PR, filters for CodeRabbit r
 **On `passed: true`:** All PRs are APPROVED or have no CodeRabbit review -- proceed to Step 5.
 **On `passed: false`:** At least one PR has CHANGES_REQUESTED or PENDING. The output identifies which PRs need attention. Route to fix cycle:
 ```typescript
-Skill({ skill: "exarchos:delegate", args: "--pr-fixes [PR_URL]" })
+Skill({ skill: "exarchos:shepherd", args: "[PR_URL]" })
 ```
 After fixes are applied, return to Step 4 to re-check.
 
@@ -121,13 +121,13 @@ mcp__plugin_exarchos_exarchos__exarchos_orchestrate({
 
 Create PRs for each branch in the stack (bottom-up) and enable auto-merge:
 
-```bash
-# For each branch in the stack (bottom-up):
-gh pr create --base <parent-branch> --head <branch> --title "<type>: <what>" --body "<pr-body>"
-gh pr merge <number> --auto --squash
+```typescript
+// For each branch in the stack (bottom-up):
+exarchos_orchestrate({ action: "create_pr", base: "<parent-branch>", head: "<branch>", title: "<type>: <what>", body: "<pr-body>" })
+exarchos_orchestrate({ action: "merge_pr", prId: "<number>", strategy: "squash" })
 ```
 
-After creation, use `gh pr list --json number,url,headRefName` to get the PR URLs for each stack entry.
+After creation, use `exarchos_orchestrate({ action: "list_prs", state: "open" })` to get the PR URLs for each stack entry.
 
 ## Step 7: Cleanup After Merge
 

package/skills/generic/synthesis/references/troubleshooting.md

@@ -21,7 +21,7 @@ If tests fail during synthesis (they passed in review):
 ### Merge Queue Rejection
 
 If the merge queue rejects a PR:
-1. Check CI status via `gh pr checks <number>` (or GitHub MCP `pull_request_read` with method `get_status` if available)
+1. Check CI status via `exarchos_orchestrate({ action: "check_ci", prId: "<number>" })`
 2. Fix failing checks
 3. Push fixes and re-enqueue
 
@@ -29,20 +29,13 @@ If the merge queue rejects a PR:
 
 If the user receives PR review comments:
 
-1. Offer to address feedback:
+1. Route to the shepherd skill:
    ```typescript
-   Skill({ skill: "exarchos:delegate", args: "--pr-fixes [PR_URL]" })
+   Skill({ skill: "exarchos:shepherd", args: "[PR_URL]" })
    ```
 
-2. Delegate reads PR comments via gh CLI:
-   ```bash
-   gh pr view <number> --json reviews,comments
-   ```
-   > Or use GitHub MCP `pull_request_read` if available.
-
-3. Creates fix tasks from review comments
-4. After fixes, amend the commit with `git commit --amend -m "fix: <description>"` and push with `git push --force-with-lease`
-5. Return to merge confirmation
+2. Shepherd reads PR comments, assesses CI, and applies fixes directly
+3. After fixes, return to merge confirmation
 
 ## Final Report Template
 
@@ -50,7 +43,7 @@ If the user receives PR review comments:
 ## Synthesis Complete
 
 ### Pull Requests
-[PR URLs from gh pr list]
+[PR URLs from list_prs action]
 
 ### Stack Branches
 - task/001-types
@@ -88,11 +81,11 @@ If workflow state doesn't match git reality:
 3. Update state via `mcp__plugin_exarchos_exarchos__exarchos_workflow` with `action: "set"` to match git truth
 
 ## PR Creation Failed
-If `gh pr create` fails:
+If `create_pr` fails:
 1. Check the error output for specific guidance
-2. Run `gh pr list --json number,baseRefName,headRefName` to verify the branch state
+2. Run `exarchos_orchestrate({ action: "list_prs", state: "open" })` to verify the branch state
 3. If rebase conflict: run `git rebase origin/<base>` to resolve
-4. If authentication issue: check GitHub token permissions
+4. If authentication issue: check VCS provider token permissions
 
 ## Stack Rebase Conflict
 If `git rebase` encounters conflicts:
@@ -104,8 +97,8 @@ If `git rebase` encounters conflicts:
 
 When Exarchos MCP tools are available:
 
-1. **After stack submission:** Call `mcp__plugin_exarchos_exarchos__exarchos_event` with `action: "append"` with event type `stack.enqueued` including PR numbers from `gh pr list --json number`
-2. **Monitor merge status:** Use `gh pr list --json number,state,mergedAt` to check stack/PR status
+1. **After stack submission:** Call `mcp__plugin_exarchos_exarchos__exarchos_event` with `action: "append"` with event type `stack.enqueued` including PR numbers from `exarchos_orchestrate({ action: "list_prs", state: "open" })`
+2. **Monitor merge status:** Use `exarchos_orchestrate({ action: "list_prs", state: "all" })` to check stack/PR status
 3. **On successful merge:** Call `mcp__plugin_exarchos_exarchos__exarchos_event` with `action: "append"` with event type `phase.transitioned` to mark workflow complete
 
 ## Performance Notes

package/skills/opencode/cleanup/SKILL.md

@@ -11,6 +11,12 @@ metadata:
 
 # Cleanup Skill
 
+## VCS Provider
+
+This skill uses VCS operations through Exarchos MCP actions (`list_prs`, `get_pr_comments`, etc.).
+These actions automatically detect and route to the correct VCS provider (GitHub, GitLab, Azure DevOps).
+No `gh`/`glab`/`az` commands needed — the MCP server handles provider dispatch.
+
 ## Overview
 
 Resolve merged workflows to `completed` state in a single operation. Replaces the manual multi-step process of navigating HSM guards after PR stacks merge.
@@ -52,12 +58,12 @@ mcp__exarchos__exarchos_view({ action: "pipeline" })
 
 For each PR associated with the workflow, verify it is merged.
 
-**Primary method** — gh CLI:
-```bash
-gh pr view <number> --json state,mergedAt,headRefName
+**Primary method** — VCS MCP action:
+```typescript
+exarchos_orchestrate({ action: "list_prs", state: "merged" })
 ```
 
-> Or use GitHub MCP `pull_request_read` if available.
+For individual PR details, use `exarchos_orchestrate({ action: "get_pr_comments", prId: "<number>" })` or the VCS provider's native API.
 
 Collect from merged PRs:
 - `prUrl`: The PR URL (or array of URLs for stacked PRs)