@lvlup-sw/exarchos 2.0.1

package/skills/shepherd/SKILL.md

@@ -0,0 +1,264 @@
+---
+name: shepherd
+description: "Shepherd PRs through CI checks and code reviews to merge readiness. Use after /synthesize to monitor CI, address CodeRabbit/Graphite feedback, fix failures, restack, and request approval. Triggers: 'shepherd', 'tend PRs', 'check CI', or /shepherd. Do NOT use before PRs are published — run /synthesize first."
+metadata:
+  author: exarchos
+  version: 1.0.0
+  mcp-server: exarchos
+  category: workflow
+  phase-affinity: synthesize
+---
+
+# Shepherd Skill
+
+## Overview
+
+Iterative loop that shepherds published PRs through CI checks and automated code reviews to merge readiness. Runs after `/synthesize` (or `/review` if PRs already exist). Monitors CI, addresses CodeRabbit and Graphite agent feedback, fixes failures, restacks as needed, and requests approval when everything is green.
+
+**Position in workflow:**
+```
+/synthesize → /shepherd (assess → fix → restack → loop) → /cleanup
+```
+
+## Triggers
+
+Activate this skill when:
+- User runs `/shepherd` command
+- User says "shepherd", "tend PRs", "check CI", "address review feedback"
+- PRs are published and need monitoring through the CI/review gauntlet
+- After `/synthesize` completes and PRs are enqueued
+
+## Prerequisites
+
+- Active workflow with PRs published (PR URLs in `synthesis.prUrl` or `artifacts.pr`)
+- Graphite stack submitted (`gt submit` already ran)
+- User has `gh` CLI authenticated
+
+## Process
+
+The shepherd loop repeats until all PRs are green or the user aborts.
+
+### 1. Assess
+
+Gather the current state of all PRs in the stack. See `references/assess-checklist.md` for detailed steps.
+
+**Read PR URLs from workflow state:**
+```
+mcp__exarchos__exarchos_workflow({ action: "get", featureId: "<id>", fields: ["synthesis", "artifacts"] })
+```
+
+**For each PR, check three dimensions:**
+
+| Dimension | Tool | Pass condition |
+|-----------|------|----------------|
+| CI checks | `gh pr checks <number>` | All checks pass |
+| CodeRabbit | `scripts/check-coderabbit.sh --owner <owner> --repo <repo> --json <numbers>` | All APPROVED or NONE |
+| Other reviews | `gh pr view <number> --json reviews,reviewRequests` | No CHANGES_REQUESTED |
+
+**Check stack health:**
+```
+mcp__graphite__run_gt_cmd({ args: ["log"] })
+```
+
+Verify base branch targeting is correct and stack is not in a broken state.
+
+**Report status to user:**
+```markdown
+## PR Status — Iteration <N>
+
+| PR | CI | CodeRabbit | Reviews | Base |
+|----|-----|-----------|---------|------|
+| #123 | pass | APPROVED | pending | main |
+| #124 | fail | CHANGES_REQUESTED | — | #123 |
+```
+
+### 2. Evaluate
+
+If ALL dimensions pass for ALL PRs → skip to step 5 (Request Approval).
+
+Otherwise, categorize issues:
+
+| Issue type | Action |
+|------------|--------|
+| CI failure | Investigate logs, fix directly or dispatch |
+| CodeRabbit feedback | Read comments, address feedback |
+| Graphite/human review feedback | Read comments, address feedback |
+| Base branch wrong | Restack via `gt restack` |
+| Stack broken | Reconstruct via `scripts/reconstruct-stack.sh` |
+
+### 3. Fix
+
+Address issues based on type. See `references/fix-strategies.md` for detailed strategies.
+
+**For review feedback (CodeRabbit, Graphite agent, human):**
+1. Read PR comments: `gh api repos/<owner>/<repo>/pulls/<number>/comments`
+2. Read review comments: `gh pr view <number> --json reviews`
+3. Categorize feedback: actionable fix vs. style nit vs. question to answer
+4. For actionable fixes: apply changes directly (if small) or dispatch via delegation
+5. For questions: respond on the PR via `gh pr comment` or `gh api`
+
+**For CI failures:**
+1. Read check details: `gh pr checks <number> --json name,status,conclusion,detailsUrl`
+2. Identify failure cause from logs
+3. Fix directly (if small) or dispatch via delegation
+4. Push fixes to the appropriate stack branch
+
+**For stack issues:**
+1. Restack: `mcp__graphite__run_gt_cmd({ args: ["restack"] })`
+2. Verify: `mcp__graphite__run_gt_cmd({ args: ["log"] })`
+
+### 4. Resubmit
+
+After fixes are applied:
+```
+mcp__graphite__run_gt_cmd({ args: ["submit", "--no-interactive", "--publish", "--merge-when-ready"] })
+```
+
+Return to step 1 (Assess) for the next iteration.
+
+### 5. Request Approval
+
+When all checks and reviews are green:
+
+1. Identify required approvers (repo settings or user-specified)
+2. Request review:
+   ```bash
+   gh pr edit <number> --add-reviewer <approver>
+   ```
+3. Report to user:
+   ```markdown
+   ## Ready for Approval
+
+   All CI checks pass. All automated reviews approved.
+   Approval requested from: <approvers>
+
+   PRs:
+   - #123: <url>
+   - #124: <url>
+
+   Run `/cleanup` after merge completes.
+   ```
+
+## Iteration Limits
+
+**Default: 5 iterations.** If the loop exceeds this limit without all PRs going green, pause and report to the user with a summary of persistent issues.
+
+The user can override: `/shepherd --max-iterations 10`
+
+## State Management
+
+Track shepherd progress in the workflow state under the `shepherd` field.
+
+### Initialize Shepherd
+
+```
+mcp__exarchos__exarchos_workflow({
+  action: "set",
+  featureId: "<id>",
+  updates: {
+    "shepherd": {
+      "startedAt": "<ISO8601>",
+      "currentIteration": 0,
+      "maxIterations": 5,
+      "iterations": [],
+      "approvalRequested": false
+    }
+  }
+})
+```
+
+### Record Iteration
+
+After each assess cycle:
+```
+mcp__exarchos__exarchos_workflow({
+  action: "set",
+  featureId: "<id>",
+  updates: {
+    "shepherd": {
+      "currentIteration": <N>,
+      "iterations": [
+        {
+          "iteration": <N>,
+          "assessedAt": "<ISO8601>",
+          "ciStatus": "pass | fail | pending",
+          "reviewStatus": {
+            "coderabbit": "APPROVED | CHANGES_REQUESTED | PENDING | NONE",
+            "otherReviews": "approved | changes_requested | pending | none"
+          },
+          "stackHealth": "healthy | needs-restack | broken",
+          "actions": ["fixed lint error in src/foo.ts", "addressed CodeRabbit feedback on PR #123"],
+          "result": "all-green | fixes-applied | blocked"
+        }
+      ]
+    }
+  }
+})
+```
+
+### Record Approval Request
+
+```
+mcp__exarchos__exarchos_workflow({
+  action: "set",
+  featureId: "<id>",
+  updates: {
+    "shepherd": {
+      "approvalRequested": true,
+      "approvalRequestedAt": "<ISO8601>",
+      "approvers": ["<username>"]
+    }
+  }
+})
+```
+
+## Completion Criteria
+
+- [ ] All CI checks pass on all PRs
+- [ ] CodeRabbit: APPROVED or NONE on all PRs
+- [ ] No CHANGES_REQUESTED from any reviewer
+- [ ] Stack is healthy (correct base branches, no conflicts)
+- [ ] Approval requested from required reviewers
+- [ ] State updated with shepherd history
+
+## Anti-Patterns
+
+| Don't | Do Instead |
+|-------|------------|
+| Force-merge with failing CI | Fix the failures first |
+| Dismiss CodeRabbit reviews without reading | Address or acknowledge each comment |
+| Skip restack when base branch changes | Always verify stack health |
+| Loop indefinitely | Respect iteration limits, escalate to user |
+| Fix issues without recording in state | Track every iteration for resumability |
+| Push directly to main | All fixes go through the stack branches |
+
+## Exarchos Integration
+
+When Exarchos MCP tools are available:
+
+1. **On shepherd start:** `mcp__exarchos__exarchos_event` with `action: "append"` — event type `shepherd.started` with PR URLs and iteration count
+2. **On each iteration:** `mcp__exarchos__exarchos_event` with `action: "append"` — event type `shepherd.iteration` with assessment results and actions taken
+3. **On approval request:** `mcp__exarchos__exarchos_event` with `action: "append"` — event type `shepherd.approval_requested` with approver list
+4. **On completion:** `mcp__exarchos__exarchos_event` with `action: "append"` — event type `shepherd.completed` with total iterations and final status
+
+## Troubleshooting
+
+| Issue | Cause | Resolution |
+|-------|-------|------------|
+| CI check stuck in pending | GitHub Actions queue delay | Wait 5 min, re-check. If still pending, re-trigger via `gh run rerun <id>` |
+| CodeRabbit not reviewing | PR too large or rate-limited | Check `scripts/check-coderabbit.sh` output. Wait 10 min or split PR |
+| Stack base branch wrong | Rebase drift after fixes | `mcp__graphite__run_gt_cmd` with `["restack"]`, then resubmit |
+| Iteration limit exceeded | Persistent flaky test or review loop | Report blockers to user with iteration history |
+| Resubmit creates draft PRs | Missing `--publish` flag | Always use `--publish --merge-when-ready` together |
+
+## Performance Notes
+
+- Check all PR dimensions in parallel (CI, CodeRabbit, reviews) rather than sequentially
+- Use `--json` flag on `gh pr checks` and `gh pr view` to reduce parsing overhead
+- Limit iteration state recording to changed fields (don't re-record entire history each iteration)
+
+## Transition
+
+After approval is granted and PRs merge:
+- Run `/cleanup` to resolve the workflow to completed state
+- Shepherd state persists in workflow for audit trail

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

@@ -0,0 +1,124 @@
+# Assessment Checklist
+
+Detailed steps for gathering PR status during each shepherd iteration.
+
+## 1. Identify PRs
+
+Read PR URLs from workflow state:
+```
+mcp__exarchos__exarchos_workflow({ action: "get", featureId: "<id>", fields: ["synthesis", "artifacts"] })
+```
+
+Extract PR numbers from URLs (e.g., `https://github.com/owner/repo/pull/123` → `123`).
+
+If no PRs in state, check Graphite:
+```
+mcp__graphite__run_gt_cmd({ args: ["log"] })
+```
+
+## 2. CI Check Status
+
+For each PR:
+```bash
+gh pr checks <number> --json name,status,conclusion,detailsUrl
+```
+
+Classification:
+| conclusion | Status |
+|------------|--------|
+| `SUCCESS` | pass |
+| `NEUTRAL`, `SKIPPED` | pass (ignorable) |
+| `FAILURE`, `TIMED_OUT` | fail |
+| `ACTION_REQUIRED` | needs attention |
+| `null` (still running) | pending |
+
+**Aggregate rule:** ALL checks must be `SUCCESS`, `NEUTRAL`, or `SKIPPED` for CI to pass. Any `FAILURE` or `TIMED_OUT` → CI fails.
+
+**Wait for pending:** If checks are still running, inform the user and suggest waiting. Do NOT treat pending as failure unless it has been pending for an unreasonable time (>30 minutes).
+
+## 3. CodeRabbit Review Status
+
+Use the existing script:
+```bash
+scripts/check-coderabbit.sh --owner <owner> --repo <repo> --json <pr-numbers...>
+```
+
+Output (JSON mode):
+```json
+[
+  {"pr": "123", "state": "APPROVED", "verdict": "pass"},
+  {"pr": "124", "state": "CHANGES_REQUESTED", "verdict": "fail"}
+]
+```
+
+**If CHANGES_REQUESTED:** Read the specific comments to understand what needs fixing.
+
+## 4. Other Review Status
+
+Check for reviews from Graphite agent, human reviewers, or other bots:
+```bash
+gh pr view <number> --json reviews,reviewRequests
+```
+
+Review classification:
+| state | Meaning |
+|-------|---------|
+| `APPROVED` | Reviewer approved |
+| `CHANGES_REQUESTED` | Reviewer wants changes |
+| `COMMENTED` | Non-blocking comment |
+| `PENDING` | Review requested but not submitted |
+| `DISMISSED` | Review was dismissed |
+
+**Aggregate rule:** No `CHANGES_REQUESTED` reviews from any reviewer. `COMMENTED` and `PENDING` are non-blocking.
+
+## 5. Stack Health
+
+Check the Graphite stack state:
+```
+mcp__graphite__run_gt_cmd({ args: ["log"] })
+```
+
+Verify:
+- All expected branches are present in the stack
+- Base branch targeting is correct (bottom of stack targets `main`)
+- Each PR's base matches its parent in the stack
+- No "needs restack" indicators
+
+If base branch has advanced:
+```
+mcp__graphite__run_gt_cmd({ args: ["restack"] })
+```
+
+## 6. Merge Readiness
+
+Check if `--merge-when-ready` is active:
+```bash
+gh pr view <number> --json autoMergeRequest
+```
+
+If `autoMergeRequest` is null, merge-when-ready is not set. Re-enable:
+```
+mcp__graphite__run_gt_cmd({ args: ["submit", "--no-interactive", "--publish", "--merge-when-ready"] })
+```
+
+## 7. Aggregate and Report
+
+Build the status table:
+
+```markdown
+## PR Status — Iteration <N>
+
+| PR | CI | CodeRabbit | Reviews | Stack | Merge Queue |
+|----|-----|-----------|---------|-------|-------------|
+| #123 | pass | APPROVED | 1 approved | healthy | enqueued |
+| #124 | fail (lint) | CHANGES_REQUESTED | pending | healthy | blocked |
+
+### Issues Found
+1. **PR #124 CI:** Lint failure in `src/foo.ts:42` — unused import
+2. **PR #124 CodeRabbit:** Suggests extracting helper function in `bar.ts`
+
+### Recommended Actions
+1. Fix lint error in `src/foo.ts`
+2. Address CodeRabbit feedback on `bar.ts`
+3. Resubmit stack after fixes
+```

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

@@ -0,0 +1,191 @@
+# Fix Strategies
+
+How to address common issues found during shepherd assessment.
+
+## Decision: Fix Directly vs. Delegate
+
+| Condition | Approach |
+|-----------|----------|
+| 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 `/delegate --pr-fixes [PR_URL]` |
+| Test changes needed | Fix directly (keep TDD cycle tight) |
+
+**Default to fixing directly** — delegation adds overhead. Only delegate when the fix scope warrants it.
+
+## CI Failures
+
+### Lint / Format
+
+1. Read the failure details:
+   ```bash
+   gh pr checks <number> --json name,conclusion,detailsUrl
+   ```
+2. Checkout the failing branch:
+   ```
+   mcp__graphite__run_gt_cmd({ args: ["checkout", "<branch-name>"] })
+   ```
+3. Run the linter locally to reproduce:
+   ```bash
+   npm run lint    # or project-specific command
+   ```
+4. Fix the issues
+5. Commit and resubmit:
+   ```
+   mcp__graphite__run_gt_cmd({ args: ["modify", "-m", "fix: lint errors"] })
+   mcp__graphite__run_gt_cmd({ args: ["submit", "--no-interactive", "--publish", "--merge-when-ready"] })
+   ```
+
+### Test Failures
+
+1. Identify which tests failed from CI output
+2. Checkout the branch and reproduce locally:
+   ```bash
+   npm run test:run
+   ```
+3. Fix the failing tests (maintain TDD — don't delete tests, fix the code or update test expectations if the behavior changed intentionally)
+4. Verify all tests pass locally before pushing
+5. Commit and resubmit
+
+### Build / TypeCheck Failures
+
+1. Reproduce locally:
+   ```bash
+   npm run build && npm run typecheck
+   ```
+2. Fix type errors or build issues
+3. Commit and resubmit
+
+### Flaky Tests
+
+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)
+3. If consistently flaky, fix the test or mark it with a skip annotation and create a follow-up issue
+
+## Review Feedback
+
+### CodeRabbit Comments
+
+1. Read all CodeRabbit comments:
+   ```bash
+   gh api repos/<owner>/<repo>/pulls/<number>/comments --jq '.[] | select(.user.login | test("coderabbit")) | {path: .path, line: .line, body: .body}'
+   ```
+2. Also check the review body (summary comments):
+   ```bash
+   gh api repos/<owner>/<repo>/pulls/<number>/reviews --jq '.[] | select(.user.login | test("coderabbit")) | {state: .state, body: .body}'
+   ```
+3. Categorize each comment:
+
+   | Category | Action |
+   |----------|--------|
+   | Bug/correctness issue | Must fix |
+   | Security concern | Must fix |
+   | Style/naming suggestion | Fix if reasonable, otherwise acknowledge |
+   | Performance suggestion | Fix if low-effort, otherwise note for later |
+   | False positive | Dismiss with explanation |
+
+4. Apply fixes to the appropriate branch
+5. Respond to CodeRabbit if needed (it re-reviews automatically on push)
+
+### Graphite Agent Comments
+
+Same approach as CodeRabbit. Graphite agent reviews tend to focus on:
+- PR description quality
+- Commit message format
+- Breaking change detection
+- Dependency impact
+
+### Human Reviewer Comments
+
+1. Read comments carefully
+2. For each comment, determine if it's:
+   - A required change (fix it)
+   - A question (answer it on the PR)
+   - A suggestion (discuss or implement)
+   - An approval with minor nits (fix nits, note the approval)
+3. Respond to the reviewer on the PR:
+   ```bash
+   gh pr comment <number> --body "Addressed feedback: <summary of changes>"
+   ```
+
+## Stack Issues
+
+### Needs Restack
+
+When the base branch (usually `main`) has advanced:
+```
+mcp__graphite__run_gt_cmd({ args: ["restack"] })
+```
+
+If restack has conflicts:
+1. Resolve conflicts in each affected file
+2. `git add <resolved-files>` then continue:
+   ```
+   mcp__graphite__run_gt_cmd({ args: ["continue"] })
+   ```
+3. After resolution, resubmit
+
+### Wrong Base Branch
+
+If a PR targets the wrong base:
+```
+mcp__graphite__run_gt_cmd({ args: ["restack"] })
+mcp__graphite__run_gt_cmd({ args: ["submit", "--no-interactive", "--publish", "--merge-when-ready"] })
+```
+
+### Stack Reconstruction
+
+If the stack is in a broken state:
+```bash
+scripts/reconstruct-stack.sh
+```
+
+Then resubmit.
+
+## Commit Strategy for Fixes
+
+When making fixes to stack branches:
+
+1. **Checkout the target branch:**
+   ```
+   mcp__graphite__run_gt_cmd({ args: ["checkout", "<branch-name>"] })
+   ```
+
+2. **Apply fixes and amend:**
+   ```
+   mcp__graphite__run_gt_cmd({ args: ["modify", "-m", "fix: <description>"] })
+   ```
+
+3. **Restack dependent branches:**
+   ```
+   mcp__graphite__run_gt_cmd({ args: ["restack"] })
+   ```
+
+4. **Resubmit the full stack:**
+   ```
+   mcp__graphite__run_gt_cmd({ args: ["submit", "--no-interactive", "--publish", "--merge-when-ready"] })
+   ```
+
+**IMPORTANT:** Always resubmit with `--publish --merge-when-ready` to maintain merge queue enrollment.
+
+## Responding on PRs
+
+When addressing feedback, communicate clearly:
+
+```bash
+# Reply to a specific review comment
+gh api repos/<owner>/<repo>/pulls/<number>/comments/<comment-id>/replies \
+  -f body="Fixed in <commit-sha>. <brief explanation>"
+
+# General PR comment summarizing all fixes
+gh pr comment <number> --body "$(cat <<'EOF'
+Addressed review feedback:
+- Fixed lint error in `src/foo.ts` (unused import)
+- Extracted helper function per CodeRabbit suggestion
+- Added missing error handling in `bar.ts`
+
+All CI checks should pass on the next run.
+EOF
+)"
+```