@lvlup-sw/exarchos 2.4.3 → 2.6.0

package/skills/opencode/spec-review/SKILL.md

@@ -0,0 +1,294 @@
+---
+name: spec-review
+description: "Stage 1 spec compliance review. Triggers: /review stage 1. Verifies implementation matches design specification — functional completeness, TDD compliance, and test coverage. Do NOT use for code quality checks — use quality-review instead. Do NOT use for debugging."
+metadata:
+  author: exarchos
+  version: 1.0.0
+  mcp-server: exarchos
+  category: workflow
+  phase-affinity: review
+---
+
+# Spec Review Skill
+
+## Overview
+
+Stage 1 of two-stage review: Verify implementation matches specification and follows TDD.
+
+For a complete worked example, see `references/worked-example.md`.
+
+> **MANDATORY:** Before accepting any rationalization for approving without full verification, consult `references/rationalization-refutation.md`. Every common excuse is catalogued with a counter-argument and the correct action.
+
+## Triggers
+
+Activate this skill when:
+- User runs `/review` command (first stage)
+- Task implementation is complete
+- Need to verify spec compliance before quality review
+- Subagent reports task completion
+
+## Execution Context
+
+This skill runs in a SUBAGENT spawned by the orchestrator, not inline.
+
+The orchestrator provides:
+- State file path (preferred) OR design/plan paths
+- Diff output from `exarchos_orchestrate({ action: "review_diff" })` (context-efficient)
+- Task ID being reviewed
+
+The subagent:
+- Reads state file to get artifact paths
+- Uses diff output instead of reading full files
+- Runs verification commands
+- Generates report
+- Returns verdict to orchestrator
+
+### Data Handoff Protocol
+
+The **orchestrator** is responsible for generating the diff before dispatching the spec-review subagent. The subagent does NOT generate its own diff.
+
+**Orchestrator responsibilities:**
+1. Generate diff: `exarchos_orchestrate({ action: "review_diff", worktreePath: "<worktree-path>", baseBranch: "main" })`
+2. Pass diff content in the subagent dispatch prompt
+3. Include state file path for artifact resolution
+
+**Subagent responsibilities:**
+1. Receive diff content from dispatch prompt (do NOT re-generate)
+2. Read state file for design/plan artifact paths
+3. Run verification commands against the working tree
+4. Return structured JSON verdict
+
+### Context-Efficient Input
+
+Instead of per-worktree diffs, receive an integrated diff from the
+integration branch (e.g., `feature/integration-branch`) against main:
+
+```bash
+# Generate integrated diff for review
+git diff main...integration > /tmp/combined-diff.patch
+
+# Alternative: use review-diff script against integration branch via orchestrate
+# exarchos_orchestrate({ action: "review_diff", worktreePath: "<worktree-path>", baseBranch: "main" })
+```
+
+This provides the complete picture of all changes across all tasks and reduces context consumption by 80-90%.
+
+### Pre-Review Schema Discovery
+
+Before evaluating, query the review strategy runbook to determine the appropriate evaluation approach:
+
+- **Evaluation strategy:** `exarchos_orchestrate({ action: "runbook", id: "review-strategy" })` to determine the review approach based on diff scope, prior fix cycles, and review stage.
+
+## Review Scope
+
+### Review Scope: Combined Changes
+
+After delegation completes, spec review examines:
+- The **complete integrated diff** (main...feature/integration branch)
+- All changes across all tasks in one view
+- The full picture of combined functionality
+
+This enables catching:
+- Cross-task interface mismatches
+- Bugs not visible in isolation
+- Combined behavior vs specification
+
+**Spec Review focuses on:**
+- Functional completeness
+- TDD compliance
+- Specification alignment
+- Test coverage
+
+**Does NOT cover (that's Quality Review):**
+- Code style
+- SOLID principles
+- Performance optimization
+- Error handling elegance
+
+## Review Checklist
+
+For the full checklist with verification commands, tables, and report template, see `references/review-checklist.md`.
+
+**Verification:**
+```bash
+npm run test:run
+npm run test:coverage
+npm run typecheck
+```
+
+```typescript
+exarchos_orchestrate({
+  action: "check_tdd_compliance",
+  featureId: "<featureId>",
+  taskId: "<taskId>",
+  branch: "<branch>"
+})
+```
+
+## Fix Loop
+
+If review FAILS:
+
+1. Create fix task with specific issues
+2. Dispatch to implementer (same or new)
+3. Re-review after fixes
+4. Repeat until PASS
+
+```typescript
+// Return to implementer
+Task({
+  model: "opus",
+  description: "Fix spec review issues",
+  prompt: `
+# Fix Required: Spec Review Failed
+
+## Issues to Fix
+1. Missing rate limiting implementation
+   - Add rate limiter middleware
+   - Test: RateLimiter_ExceedsLimit_Returns429
+
+2. Email validation incomplete
+   - Add MX record check
+   - Test: ValidateEmail_InvalidDomain_ReturnsError
+
+## Success Criteria
+- All tests pass
+- Coverage >80%
+- All issues resolved
+`
+})
+```
+
+## Required Output Format
+
+The subagent MUST return results as structured JSON. The orchestrator parses this JSON to populate state. Any other format is an error.
+
+```json
+{
+  "verdict": "pass | fail | blocked",
+  "summary": "1-2 sentence summary",
+  "issues": [
+    {
+      "severity": "HIGH | MEDIUM | LOW",
+      "category": "spec | tdd | coverage",
+      "file": "path/to/file",
+      "line": 123,
+      "description": "Issue description",
+      "required_fix": "What must change"
+    }
+  ],
+  "test_results": {
+    "passed": 0,
+    "failed": 0,
+    "coverage_percent": 0
+  }
+}
+```
+
+## Anti-Patterns
+
+| Don't | Do Instead |
+|-------|------------|
+| Skip to quality review | Complete spec review first |
+| Accept incomplete work | Return for fixes |
+| Review code style here | Save for quality review |
+| Approve without tests | Require test coverage |
+| Let scope creep pass | Flag over-engineering |
+
+## Cross-Task Integration Issues
+
+If an issue spans multiple tasks:
+1. Classify as "cross-task integration"
+2. Create fix task specifying ALL affected tasks
+3. Dispatch fix to implementer with context from all affected tasks
+4. Mark original tasks as blocked until cross-task fix completes
+
+## State Management
+
+### On Review Complete
+
+**Pass:**
+```
+action: "set", featureId: "<id>", updates: {
+  "reviews": { "spec-review": { "status": "pass", "summary": "...", "issues": [] } }
+}
+```
+
+**Fail:**
+```
+action: "set", featureId: "<id>", updates: {
+  "reviews": { "spec-review": { "status": "fail", "summary": "...", "issues": [{ "severity": "...", "file": "...", "description": "..." }] } }
+}
+```
+
+> **Important:** The review value MUST be an object with a `status` field (e.g., `{ "status": "pass" }`), not a flat string (e.g., `"pass"`). The `all-reviews-passed` guard silently ignores non-object entries. Accepted statuses: `pass`, `passed`, `approved`, `fixes-applied`.
+
+### Phase Transitions and Guards
+
+For the full transition table, consult `@skills/workflow-state/references/phase-transitions.md`.
+
+**Quick reference:**
+- `review` → `synthesize` requires guard `all-reviews-passed` — all `reviews.{name}.status` must be passing
+- `review` → `delegate` requires guard `any-review-failed` — triggers fix cycle when any review fails
+
+### Schema Discovery
+
+Use `exarchos_workflow({ action: "describe", actions: ["set", "init"] })` for
+parameter schemas and `exarchos_workflow({ action: "describe", playbook: "feature" })`
+for phase transitions, guards, and playbook guidance. Use
+`exarchos_orchestrate({ action: "describe", actions: ["check_tdd_compliance", "check_static_analysis"] })`
+for orchestrate action schemas.
+
+## Transition
+
+All transitions happen **immediately** without user confirmation:
+
+### Pre-Chain Validation (MANDATORY)
+
+Before invoking quality-review:
+1. Verify `reviews["spec-review"].status === "pass"` in workflow state (all tasks passed)
+2. If not: "Spec review did not pass, cannot proceed to quality review"
+
+> **Guard shape:** The `all-reviews-passed` guard requires `reviews["spec-review"]` to be an object with a `status` field set to a passing value (`pass`, `passed`, `approved`, `fixes-applied`). Flat strings like `reviews: { "spec-review": "pass" }` are silently ignored and will block the `review → synthesize` transition.
+
+### If PASS:
+1. Record results — the reviews value MUST be an object with a `status` field, not a flat string:
+   ```
+   exarchos_workflow({ action: "set", featureId: "<id>", updates: {
+     reviews: { "spec-review": { status: "pass", summary: "...", issues: [] } }
+   }})
+   ```
+2. Output: "Spec review passed. Auto-continuing to quality review..."
+3. Orchestrator dispatches quality-review subagent immediately
+
+> **Gate events:** Do NOT manually emit `gate.executed` events via `exarchos_event`. Gate events are automatically emitted by the `check_review_verdict` orchestrate handler. Manual emission causes duplicates.
+
+### If FAIL:
+1. Record results with failing status and issue details:
+   ```
+   exarchos_workflow({ action: "set", featureId: "<id>", updates: {
+     reviews: { "spec-review": { status: "fail", summary: "...", issues: [{ severity: "HIGH", file: "...", description: "..." }] } }
+   }})
+   ```
+2. Output: "Spec review found [N] issues. Auto-continuing to fixes..."
+3. Auto-invoke delegate with fix tasks:
+   ```typescript
+   [Invoke the exarchos:delegate skill with args: --fixes <plan-path>]
+   ```
+
+This is NOT a human checkpoint - workflow continues autonomously.
+
+## Troubleshooting
+
+| Issue | Cause | Resolution |
+|-------|-------|------------|
+| Test file not found | Task didn't create expected test | Check plan for test file paths, verify worktree contents |
+| Coverage below threshold | Implementation incomplete or tests superficial | Add missing test cases, verify assertions are meaningful |
+| TDD compliance check fails | Implementation committed before tests | Check git log order — test commits must precede or accompany implementation |
+| Diff too large for context | Many tasks with large changes | Generate per-worktree diffs with `exarchos_orchestrate({ action: "review_diff", worktreePath: "<task-worktree>" })` to review incrementally |
+
+## Performance Notes
+
+- Use the integrated diff (`exarchos_orchestrate({ action: "review_diff" })`) instead of reading full files — reduces context by 80-90%
+- Review per-task when the combined diff exceeds 2,000 lines
+- Run TDD compliance check (`exarchos_orchestrate({ action: "check_tdd_compliance" })`) in parallel with spec tracing

package/skills/opencode/spec-review/references/rationalization-refutation.md

@@ -0,0 +1,13 @@
+# Rationalization Refutation — Spec Review
+
+Common rationalizations that undermine spec review rigor, with counter-arguments and correct actions.
+
+| Rationalization | Counter-argument | What to do instead |
+|-----------------|------------------|--------------------|
+| "The implementation obviously matches the spec" | Obvious agreement is an illusion of familiarity. Reviewers who assume compliance find it — confirmation bias makes you see what you expect instead of what exists. | Independently trace each spec requirement to the implementing code. Use the compliance matrix to verify each requirement has a corresponding implementation and test. |
+| "Tests pass so it must be correct" | Tests only verify what they test. Passing tests prove nothing about untested requirements, missing edge cases, or spec items with no corresponding test. A 100% pass rate on incomplete coverage is misleading. | Check test coverage against the spec — not just line coverage, but requirement coverage. Every spec item needs at least one test that would fail if the requirement were unmet. |
+| "This is a minor deviation from the spec" | Minor deviations compound. Each "small" gap erodes the contract between design and implementation. What seems minor today becomes a confusing inconsistency tomorrow. | Flag the deviation explicitly with severity classification. Either update the spec to match reality (with rationale) or require the implementation to match the spec. No silent deviations. |
+| "The spec was ambiguous anyway" | Ambiguity is not a license to guess. If the spec is ambiguous, the correct action is to resolve the ambiguity — not to implement an assumption and hope it aligns. | Escalate the ambiguity: document the interpretation in the review report, request spec clarification, and block the review until the ambiguity is resolved or explicitly accepted. |
+| "The implementer said it's done" | Self-assessment of completeness is unreliable. Implementers have blind spots about their own work — they know what they intended, not necessarily what they built. | Verify independently. Read the code and tests yourself. Run the verification scripts. Compare against the spec line by line. The implementer's assessment is a starting point, not evidence. |
+| "We're running behind, just approve it" | Schedule pressure produces the exact conditions where defects escape. Approving incomplete work creates more rework than the time "saved" by skipping review. | Document what's incomplete, file it as a blocking issue, and return to the implementer. A clean review now prevents a costly debugging session later. |
+| "The edge cases are obvious and handled" | Obvious to whom? Edge cases that the implementer considered obvious are often the ones with subtle bugs. The reviewer's job is to independently verify, not to trust claims of coverage. | List the edge cases from the spec. For each one, find the test that exercises it. If no test exists, flag it as missing coverage. |

package/skills/opencode/spec-review/references/review-checklist.md

@@ -0,0 +1,79 @@
+---
+name: spec-review-checklist
+description: "Validation script invocations and report template for spec compliance verification."
+---
+
+# Spec Review Checklist
+
+## Adversarial Review Posture
+
+You are an ADVERSARIAL reviewer. Your job is to find what's wrong, not confirm what's right.
+
+- Do NOT trust the implementer's self-assessment of completeness
+- Do NOT assume passing tests mean the spec is satisfied
+- Do NOT accept "it works" as evidence of correctness
+- Independently verify each spec requirement against the actual code
+- Treat every claim as unverified until you see the evidence yourself
+
+Consult `references/rationalization-refutation.md` when you feel tempted to accept a rationalization for skipping verification.
+
+## Automated Verification
+
+Run these scripts as the authoritative checks:
+
+```bash
+# Full test suite
+npm run test:run
+
+# Coverage thresholds (line >80%, branch >70%, function 100% for public APIs)
+npm run test:coverage
+
+# Type safety
+npm run typecheck
+```
+
+```typescript
+// TDD compliance (test-first ordering, naming conventions, coverage)
+exarchos_orchestrate({
+  action: "check_tdd_compliance",
+  featureId: "<featureId>",
+  taskId: "<taskId>",
+  branch: "<branch>"
+})
+```
+
+## Manual Checks
+
+After scripts pass, verify:
+- All spec requirements implemented (compare to design/plan)
+- No over-engineering beyond spec
+- No missing edge cases
+
+## Report Template
+
+```markdown
+## Spec Review Report
+
+### Summary
+- Status: [PASS | FAIL | NEEDS_FIXES]
+- Tested: [timestamp]
+
+### Compliance Matrix
+| Requirement | Implemented | Test Exists | Notes |
+|-------------|-------------|-------------|-------|
+
+### Issues Found
+1. [Issue] — File: `path` — Fix: [required change]
+
+### Verdict
+[PASS] Ready for quality review
+[FAIL] Return to implementer with fix list
+```
+
+## Completion Criteria
+
+- [ ] `check_tdd_compliance` orchestrate action passes
+- [ ] All tests pass
+- [ ] Coverage meets thresholds
+- [ ] All spec requirements verified
+- [ ] State file updated with review results

package/skills/opencode/spec-review/references/worked-example.md

@@ -0,0 +1,72 @@
+---
+name: spec-review-worked-example
+description: "Complete trace of the spec review skill in action, showing happy path and false-positive correction."
+---
+
+# Worked Example: Spec Review — Workflow Transition Validation
+
+## Context
+
+Feature: HSM phase transition guards for the Exarchos MCP server. The orchestrator dispatches a spec-review subagent after all tasks complete. The subagent receives the integrated diff and the state file path.
+
+## Inputs Received
+
+- **Diff:** `git diff main...feature/hsm-guards` (420 lines)
+- **State file:** Contains design path, plan path, and 4 completed tasks
+- **Task ID:** Combined review (all tasks)
+
+## Step 1: Read Spec Artifacts
+
+Subagent reads design (`docs/designs/2026-02-15-hsm-guards.md`) and plan (`docs/plans/2026-02-16-hsm-guards.md`) from state. Design specifies 5 guard conditions; plan decomposes into 4 tasks with 12 TDD test cases.
+
+## Step 2: Run Verification Commands
+
+```
+npm run test:run          — 47 passed, 0 failed
+npm run test:coverage     — 89% line, 82% branch
+npm run typecheck          — clean
+exarchos_orchestrate({ action: "check_tdd_compliance" }) — passed: true
+```
+
+All automated checks pass.
+
+## Step 3: Trace Spec to Implementation
+
+Subagent maps each design requirement to diff hunks:
+
+| Requirement | Found in Diff | Test Exists |
+|-------------|--------------|-------------|
+| Guard: `planReviewComplete` | Yes — `guards.ts:34` | Yes |
+| Guard: `allTasksComplete` | Yes — `guards.ts:52` | Yes |
+| Guard: `allReviewsPassed` | Yes — `guards.ts:68` | Yes |
+| Guard: `docsUpdated` | Yes — `guards.ts:81` | Yes |
+| Error message on guard failure | **NOT FOUND** | No |
+
+## Gap Found
+
+Design specifies: "Guards must return descriptive error messages on failure." The implementation returns `false` without messages. This is a real spec gap.
+
+## False-Positive Correction
+
+Subagent initially flags "Missing rate-limit guard" as a spec gap. On re-reading the design, rate limiting is listed under "Future Work," not current scope. Subagent removes this from findings.
+
+**Agent reasoning:** "Rate limiting appears in the design's Future Work section (not Technical Design). Flagging it would be scope creep. Removing from issues list."
+
+## Verdict
+
+```json
+{
+  "verdict": "fail",
+  "summary": "4 of 5 spec requirements met. Missing guard failure error messages.",
+  "issues": [{
+    "severity": "HIGH",
+    "category": "spec",
+    "file": "src/guards.ts",
+    "description": "Guards return boolean without error messages",
+    "required_fix": "Return { allowed: boolean, reason: string } per design spec"
+  }],
+  "test_results": { "passed": 47, "failed": 0, "coverage_percent": 89 }
+}
+```
+
+State updated with `reviews["spec-review"].status = "fail"`. Orchestrator dispatches fix task automatically.

package/skills/opencode/synthesis/SKILL.md

@@ -0,0 +1,217 @@
+---
+name: synthesis
+description: "Create pull request from completed feature branch using GitHub-native stacked PRs. Use when the user says 'create PR', 'submit for review', 'synthesize', or runs /synthesize. Validates branch readiness, creates PR with structured description, and manages merge queue. Do NOT use before review phase completes. Not for draft PRs."
+metadata:
+  author: exarchos
+  version: 2.0.0
+  mcp-server: exarchos
+  category: workflow
+  phase-affinity: synthesize
+---
+
+# Synthesis Skill
+
+## 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.
+
+**Prerequisites:**
+- All delegated tasks complete with reviews passed (spec + quality)
+- The integration branch already exists from delegation phase
+- Task branches present and pushed to remote
+
+Do NOT proceed if either review is incomplete or failed -- return to `/review` first.
+
+**Entry points:** Synthesis is normally reached from the `review` phase of
+feature / debug / refactor workflows. It is also reachable from `oneshot`
+workflows via the opt-in path — when a user signals "let's open a PR for
+this" during `plan` or `implementing`, the `request_synthesize` event is
+appended, and `finalize_oneshot` then resolves the choice state and
+transitions the workflow to `synthesize`. See
+`@skills/oneshot-workflow/SKILL.md` for the opt-in mechanics and
+`synthesisPolicy` semantics.
+
+## Triggers
+
+Activate this skill when:
+- User runs `/synthesize` command
+- All reviews have passed successfully
+- Ready to submit PRs
+- Oneshot workflow resolved to `synthesize` via `finalize_oneshot`
+
+## Process
+
+> **Runbook:** Follow the synthesis-flow runbook:
+> `exarchos_orchestrate({ action: "runbook", id: "synthesis-flow" })`
+> If runbook unavailable, use `describe` to retrieve action schemas: `exarchos_orchestrate({ action: "describe", actions: ["prepare_synthesis"] })`
+
+### Step 1: Verify Readiness
+
+Call the `prepare_synthesis` composite action to validate all preconditions in a single operation:
+
+```typescript
+mcp__exarchos__exarchos_orchestrate({
+  action: "prepare_synthesis",
+  featureId: "<id>"
+})
+```
+
+This action performs:
+- **Phase readiness** -- Confirms workflow is in the correct phase with all reviews complete
+- **Stack integrity** -- Detects diverged branches, missing task branches, or broken parent chains and reconstructs automatically
+- **Test verification** -- Runs `npm run test:run && npm run typecheck` from the stack top
+- **Benchmark regression** -- If `state.verification.hasBenchmarks` is true, checks for performance regressions
+- **Quality signals** -- Queries `code_quality` view for regressions and actionable hints
+- **Gate events** -- Auto-emits `gate.executed` events for each check (tests, benchmarks, CodeRabbit)
+
+For the full breakdown of individual checks the composite action performs, see `references/synthesis-steps.md`.
+
+**On success:** All checks passed. The response includes a readiness summary with any quality hints to present to the user. Proceed to Step 2.
+
+**On failure:** The response identifies which check failed and provides remediation guidance. Follow the guidance -- typically returning to `/review` or `/delegate`.
+
+If any quality hint has `confidenceLevel: 'actionable'`, present the `suggestedAction` to the user before proceeding.
+
+### Step 2: Write and Validate PR Descriptions
+
+For each PR in the stack, write a structured description following `references/pr-descriptions.md`. Required sections: **Summary**, **Changes**, **Test Plan**, plus a footer. Projects can override required sections via `.exarchos/pr-template.md`.
+
+**Title format:** `<type>: <what>` (max 72 chars)
+
+Write the PR body to a temp file:
+```bash
+cat > /tmp/pr-body.md <<'EOF'
+## Summary
+[2-3 sentences: what changed, why it matters]
+
+## Changes
+- **Component** -- Description of change
+
+## Test Plan
+[Testing approach and coverage]
+
+---
+**Results:** Tests X pass · Build 0 errors
+**Design:** [doc](path)
+**Related:** #issue
+EOF
+```
+
+Validate **before** creating the PR:
+```typescript
+mcp__exarchos__exarchos_orchestrate({
+  action: "validate_pr_body",
+  bodyFile: "/tmp/pr-body.md"
+})
+```
+
+**Do NOT call `gh pr create` 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
+```
+
+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`
+3. **Update state:**
+
+```typescript
+mcp__exarchos__exarchos_workflow({
+  action: "set", featureId: "<id>", updates: {
+    "artifacts": { "pr": ["<url1>", "<url2>"] },
+    "synthesis": { "mergeOrder": ["<branch1>", ...], "prUrl": ["<url1>", ...], "prFeedback": [] }
+  }
+})
+```
+
+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
+- **'no'** -- Pause workflow; resume later with `/rehydrate`
+
+### Event Emissions (REQUIRED)
+
+After PRs are created and auto-merge is enabled, emit the `stack.submitted` event:
+
+```typescript
+mcp__exarchos__exarchos_event({ action: "append", stream: "<featureId>", event: {
+  type: "stack.submitted",
+  data: {
+    branches: ["task-001-branch", "task-002-branch"],
+    prNumbers: [101, 102]
+  }
+}})
+```
+
+During shepherd iterations (CI monitoring loop), emit after each assessment:
+
+```typescript
+mcp__exarchos__exarchos_event({ action: "append", stream: "<featureId>", event: {
+  type: "shepherd.iteration",
+  data: {
+    iteration: 1,
+    prsAssessed: 2,
+    fixesApplied: 0,
+    status: "all-green"
+  }
+}})
+```
+
+These events are checked by `check-event-emissions` during workflow validation. Missing emissions will trigger warnings.
+
+### Post-Merge Cleanup
+
+After PRs merge, invoke cleanup:
+```typescript
+mcp__exarchos__exarchos_workflow({
+  action: "cleanup", featureId: "<id>", mergeVerified: true,
+  prUrl: ["<url>", ...], mergedBranches: ["<branch>", ...]
+})
+```
+
+Then sync: `git fetch --prune` and remove worktrees.
+
+## Anti-Patterns
+
+| Don't | Do Instead |
+|-------|------------|
+| Skip review phase | Always run `/review` first |
+| Force push stack branches | Use normal push |
+| Delete worktrees before merge | Wait for merge confirmation |
+| Create PR with failing tests | Ensure review phase passes first |
+| Run readiness scripts manually | Use `prepare_synthesis` composite action |
+
+## Handling Failures
+
+See `references/troubleshooting.md` for test failures, PR check failures, merge queue rejections, and MCP tool errors.
+
+## Phase Transitions and Guards
+
+For the full transition table, consult `@skills/workflow-state/references/phase-transitions.md`.
+
+**Quick reference:** The `synthesize` → `completed` transition requires guard `pr-url-exists` — set `synthesis.prUrl` or `artifacts.pr` in the same `set` call as `phase`.
+
+### Schema Discovery
+
+Use `exarchos_workflow({ action: "describe", actions: ["set", "init"] })` for
+parameter schemas and `exarchos_workflow({ action: "describe", playbook: "feature" })`
+for phase transitions, guards, and playbook guidance. Use
+`exarchos_orchestrate({ action: "describe", actions: ["prepare_synthesis"] })`
+for orchestrate action schemas.
+
+## Completion Criteria
+
+- [ ] `prepare_synthesis` readiness check passed
+- [ ] PR descriptions written per `references/pr-descriptions.md`
+- [ ] PRs created and auto-merge enabled
+- [ ] PR links provided to user
+- [ ] State updated with PR URLs and merge order