@lvlup-sw/exarchos 2.7.1 → 2.8.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lvlup-sw/exarchos",
-  "version": "2.7.1",
+  "version": "2.8.1",
   "description": "Structure for agentic development — durable SDLC workflows, convergence gates, agent teams, and audit trails for Claude Code",
   "type": "module",
   "bin": {

package/skills/claude/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__plugin_exarchos_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)

package/skills/claude/cleanup/references/merge-verification.md

@@ -10,22 +10,21 @@ The cleanup action trusts the `mergeVerified` flag — it does not query GitHub
 
 ## Verification Methods
 
-### gh CLI (Primary)
+### VCS MCP Action (Primary)
 
-```bash
-gh pr view 123 --json state,mergedAt,headRefName
-# Check: .state == "MERGED" and .mergedAt is not null
+```typescript
+// List PRs to check merge state
+exarchos_orchestrate({ action: "list_prs", state: "merged" })
+// Check: each PR's state is "MERGED" and mergedAt is not null
 ```
 
-> Or use GitHub MCP `pull_request_read` if available for structured data.
-
 ### For Stacked PRs
 
 When verifying a stacked PR set, check ALL PRs in the stack:
 
-```bash
-# List PRs for the branch stack
-gh pr list --head "feature/*" --json number,state,headRefName
+```typescript
+// List PRs for the branch stack
+exarchos_orchestrate({ action: "list_prs", head: "feature/*", state: "all" })
 ```
 
 Collect from each merged PR:

package/skills/claude/debug/references/thorough-track.md

@@ -121,8 +121,11 @@ git commit -m "fix: <issue summary>"
 git push -u origin <branch-name>
 
 # Create PR and enable auto-merge
-gh pr create --base main --title "fix: <issue summary>" --body "<pr-body>"
-gh pr merge <number> --auto --squash
+```
+
+```typescript
+exarchos_orchestrate({ action: "create_pr", base: "main", head: "<branch-name>", title: "fix: <issue summary>", body: "<pr-body>" })
+exarchos_orchestrate({ action: "merge_pr", prId: "<number>", strategy: "squash" })
 ```
 
 Then update the PR description:

package/skills/claude/debug/references/troubleshooting.md

@@ -36,7 +36,7 @@ When Exarchos MCP tools are available, emit events throughout the debug workflow
 1. **At workflow start (triage):** `mcp__plugin_exarchos_exarchos__exarchos_event` with `action: "append"` -> `workflow.started` with workflowType "debug", urgency
 2. **On track selection:** `mcp__plugin_exarchos_exarchos__exarchos_event` with `action: "append"` -> `phase.transitioned` with selected track (hotfix/thorough)
 3. **On each phase transition:** `mcp__plugin_exarchos_exarchos__exarchos_event` with `action: "append"` -> `phase.transitioned` from->to
-4. **Thorough track stacking:** Handled by `/exarchos:synthesize` (PR creation via `gh pr create`)
+4. **Thorough track stacking:** Handled by `/exarchos:synthesize` (PR creation via `exarchos_orchestrate({ action: "create_pr" })`)
 5. **Hotfix track commit:** Single `git commit -m "fix: <description>"` + `git push` -- no multi-branch stacking needed
 6. **On complete:** `mcp__plugin_exarchos_exarchos__exarchos_event` with `action: "append"` -> `phase.transitioned` to "completed"
 

package/skills/claude/delegation/SKILL.md

@@ -43,7 +43,7 @@ Rationalization patterns that violate this principle are catalogued in `referenc
 
 **Auto-detection:** tmux + `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` present means `agent-team`. Otherwise `subagent`. Override with `/exarchos:delegate --mode subagent|agent-team`.
 
-**CRITICAL:** Always specify `model: "opus"` for coding tasks (when not using native agent definitions).
+Use the `recommendedModel` from `prepare_delegation` task classifications when available. If no classification exists (e.g., fixer dispatch), omit `model` to inherit the session default.
 
 ### Pre-Dispatch Schema Discovery
 
@@ -262,7 +262,9 @@ Handles review failures instead of initial implementation. Uses `references/fixe
 
 **Arguments:** `--fixes <state-file-path>` — state JSON containing review results in `.reviews.<taskId>.specReview` or `.reviews.<taskId>.qualityReview`.
 
-For detailed fix-mode process, see `references/fix-mode.md`. For PR feedback workflows (`--pr-fixes`), see `references/pr-fixes-mode.md`.
+For detailed fix-mode process, see `references/fix-mode.md`.
+
+> **Deprecated:** `--pr-fixes` has been superseded by `/exarchos:shepherd`. Use the shepherd skill for PR feedback workflows.
 
 ---
 
@@ -349,7 +351,6 @@ This is NOT a human checkpoint — the workflow continues autonomously.
 | `references/testing-patterns.md` | Arrange/Act/Assert, naming, mocking conventions |
 | `references/pbt-patterns.md` | Property-based testing patterns |
 | `references/fix-mode.md` | Detailed fix-mode process |
-| `references/pr-fixes-mode.md` | PR feedback fix workflows |
 | `references/state-management.md` | State patterns and benchmark labeling |
 | `references/troubleshooting.md` | Common failure modes and resolutions |
 | `references/adaptive-orchestration.md` | Adaptive team composition |

package/skills/claude/delegation/references/agent-teams-saga.md

@@ -103,7 +103,6 @@ exarchos_event append:
     teammateName: {name}
     worktreePath: {path}
     assignedTaskIds: [{taskIds}]
-    model: "opus"
 
 # Execute side effect
 # Note: teammates inherit the lead's permission mode (per Claude Code docs).
@@ -112,7 +111,6 @@ Task:
   subagent_type: "general-purpose"
   team_name: {featureId}
   name: {teammateName}
-  model: "opus"
   prompt: {spawnPrompt}  # See implementer-prompt.md template
 ```
 
@@ -199,7 +197,7 @@ If a compensating action itself fails after 3 retries, mark the workflow with `_
 | **Permissions inherit from lead** | Do NOT set `mode` at spawn -- not respected. All teammates inherit the lead's permission mode. |
 | **Teammates load MCP automatically** | Exarchos MCP tools are available without explicit instruction. The spawn prompt guides WHICH tools to use, not HOW to access them. |
 
-**CRITICAL:** Ensure your session is using the opus model for coding tasks. All teammates inherit the session model -- use Task tool dispatch if you need per-task model selection.
+**Model selection:** Teammates inherit the session model. Model is configured via `.exarchos.yml` and resolved by `prepare_delegation`. Use Task tool dispatch if you need per-task model override.
 
 ## Event Payload Conventions
 

package/skills/claude/delegation/references/fixer-prompt.md

@@ -109,7 +109,6 @@ When done, report:
 ```typescript
 Task({
   subagent_type: "general-purpose",
-  model: "opus",
   description: "Fix: SQL injection vulnerability",
   prompt: `
 # Fix Task: SQL Injection in User Query

package/skills/claude/delegation/references/implementer-prompt.md

@@ -280,7 +280,6 @@ When done, report:
 ```typescript
 Task({
   subagent_type: "general-purpose",
-  model: "opus",
   description: "Implement user validation",
   prompt: `
 # Task: Implement User Email Validation

package/skills/claude/delegation/references/parallel-strategy.md

@@ -21,8 +21,8 @@ Group B (depends on Group A):
 
 ```typescript
 // CORRECT: Single message, parallel execution
-Task({ model: "opus", description: "Task 001", prompt: "..." })
-Task({ model: "opus", description: "Task 002", prompt: "..." })
+Task({ description: "Task 001", prompt: "..." })
+Task({ description: "Task 002", prompt: "..." })
 
 // WRONG: Separate messages = sequential
 ```
@@ -59,7 +59,7 @@ Agent Teams supports one team per session. If you need more parallel groups than
 | Parallel dispatch | Multiple `Task()` in one message | Named teammates in agent team |
 | Waiting | `TaskOutput({ block: true })` | `TeammateIdle` hook (fires when teammate idle) |
 | Visibility | None (background) | tmux split panes |
-| Model control | `model: "opus"` per task | Session model for all |
+| Model control | `recommendedModel` from config | Session model for all |
 | Max parallelism | Unlimited | One team, N teammates |
 | Resume on crash | Task results preserved | Teammates lost (worktrees survive) |
 
@@ -73,14 +73,9 @@ TaskOutput({ task_id: "task-002-id" })
 
 ## Model Selection Guide
 
-| Task Type | Model | Reason |
-|-----------|-------|--------|
-| Code implementation | `opus` | Best quality for coding |
-| Code review | `opus` | Thorough analysis |
-| File search/exploration | (default) | Speed over quality |
-| Simple queries | `haiku` | Fast, low cost |
+Model selection is config-driven via `.exarchos.yml`. The `prepare_delegation` action returns a `recommendedModel` in each task classification based on the config cascade: per-agent override, then default-model, then fallback. Override per-task via the Task tool's `model` parameter when needed.
 
-**Note:** When using Agent Teams, all teammates inherit the session's model. Use Task tool dispatch if you need per-task model selection (e.g., `haiku` for simple queries, `opus` for implementation).
+**Note:** When using Agent Teams, all teammates inherit the session's model. Model is resolved from `.exarchos.yml` config via `prepare_delegation`. Use Task tool dispatch if you need per-task model override.
 
 ## Agent Teams Dispatch Pattern
 
@@ -106,7 +101,7 @@ Each teammate receives the full implementer prompt including TDD requirements, f
 | Cross-task deps | Orchestrator manages phases | Shared task list + unblocked task detection |
 | Monitoring | `TaskOutput` polling | tmux panes + `TeammateIdle` hook |
 | State updates | Orchestrator updates state | Hook auto-updates via state bridge |
-| Model per task | Yes (`model: "opus"` per Task) | No (session model for all) |
+| Model per task | Yes (`recommendedModel` per Task) | No (session model for all) |
 | Quality gates | Manual via `post_delegation_check` action | Automatic via `TeammateIdle` hook |
 | Recovery | Task results preserved | Worktrees survive, teammates lost |
 

package/skills/claude/delegation/references/worked-example.md

@@ -41,13 +41,13 @@ Build two self-contained prompts from `implementer-prompt.md` and dispatch in a
 
 ```typescript
 Task({
-  subagent_type: "general-purpose", model: "opus", run_in_background: true,
+  subagent_type: "general-purpose", run_in_background: true,
   description: "Implement task-001: Email format validator",
   prompt: `# Task: Email Format Validator\n\n## Working Directory\n/project/.worktrees/task-001\n\n[Full implementer prompt with TDD, file paths, acceptance criteria...]`
 })
 
 Task({
-  subagent_type: "general-purpose", model: "opus", run_in_background: true,
+  subagent_type: "general-purpose", run_in_background: true,
   description: "Implement task-002: Domain MX check",
   prompt: `# Task: Domain MX Check\n\n## Working Directory\n/project/.worktrees/task-002\n\n[Full implementer prompt with TDD, file paths, acceptance criteria...]`
 })
@@ -86,7 +86,7 @@ Re-dispatch with fixer prompt in the same worktree:
 
 ```typescript
 Task({
-  subagent_type: "general-purpose", model: "opus",
+  subagent_type: "general-purpose",
   description: "Fix task-002: DNS mock missing",
   prompt: `# Fix Task: DNS Mock Missing\n\n## Adversarial Verification Posture\nIndependently verify the failure...\n\n## Working Directory\n/project/.worktrees/task-002\n\n## Issue to Fix\n**File:** src/validators/domain.test.ts\n**Problem:** Missing vi.mock('dns') — test makes real network calls\n**Fix:** Add vi.mock('dns') with MX record stub\n\n## Verification\nRun: npm run test:run\nAll tests must pass without network access.`
 })

package/skills/claude/delegation/references/workflow-steps.md

@@ -40,7 +40,6 @@ TodoWrite({
 // Launch multiple in single message for parallel execution
 Task({
   subagent_type: "general-purpose",
-  model: "opus",
   run_in_background: true,
   description: "Implement task 001",
   prompt: "[Full implementer prompt]"
@@ -48,7 +47,6 @@ Task({
 
 Task({
   subagent_type: "general-purpose",
-  model: "opus",
   run_in_background: true,
   description: "Implement task 002",
   prompt: "[Full implementer prompt]"

package/skills/claude/delegation/references/worktree-enforcement.md

@@ -64,7 +64,7 @@ When using native isolation:
 | Don't | Do Instead |
 |-------|------------|
 | Make subagents read plan files | Provide full task text in prompt |
-| Use default model for coding | Specify `model: "opus"` |
+| Use default model for coding | Use configured model from `prepare_delegation` |
 | Send sequential Task calls | Batch parallel tasks in one message |
 | Skip worktree for parallel work | Create isolated worktrees |
 | Forget to track in TodoWrite | Update status for every task |

package/skills/claude/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 /exarchos: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__plugin_exarchos_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__plugin_exarchos_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
+   /exarchos:ideate <implementation-topic>
+   ```
+   Reference the discovery report as design input.
+
+## Event Emissions
+
+Optionally emit events at key moments for observability:
+
+```typescript
+mcp__plugin_exarchos_exarchos__exarchos_event({
+  action: "append", stream: "<featureId>",
+  event: { type: "discovery.sources_collected", data: { sourceCount: N } }
+})
+```
+
+```typescript
+mcp__plugin_exarchos_exarchos__exarchos_event({
+  action: "append", stream: "<featureId>",
+  event: { type: "discovery.report_committed", data: { path: "<report-path>" } }
+})
+```

package/skills/claude/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/claude/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/claude/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/claude/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/claude/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/claude/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/claude/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/claude/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/claude/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: "..." })`