@lvlup-sw/exarchos 2.0.1

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

@@ -0,0 +1,109 @@
+---
+name: synthesis-steps
+---
+
+# Synthesis Process
+
+## Step 1: Verify Readiness
+
+Run the pre-synthesis readiness check:
+```bash
+scripts/pre-synthesis-check.sh \
+  --state-file ~/.claude/workflow-state/<featureId>.state.json \
+  --repo-root <repo-root>
+```
+
+The script validates all readiness conditions:
+- All delegated tasks complete (from state file)
+- All reviews passed (from state file)
+- No outstanding fix requests (from state file)
+- Graphite stack branches exist (`gt log`)
+- All tests pass (`npm run test:run && npm run typecheck`)
+
+**On exit 0:** All checks passed -- proceed to Step 2.
+**On exit 1:** Output identifies the failing check. Return to `/exarchos:review` or `/exarchos:delegate` as appropriate.
+
+Use `--skip-tests` if tests were already verified in review phase. Use `--skip-stack` to defer stack check to Step 2.
+
+## Step 2: Verify and Reconstruct Graphite Stack
+
+Run the stack reconstruction script to detect and fix any broken stack state:
+```bash
+scripts/reconstruct-stack.sh \
+  --repo-root <repo-root> \
+  --state-file ~/.claude/workflow-state/<featureId>.state.json
+```
+
+The script has three phases:
+1. **Detection** -- Parses `gt log` for diverged branches, restack markers, or missing task branches
+2. **Reconstruction** -- If issues detected: resets branch pointers, removes blocking worktrees, re-tracks with correct parent chain
+3. **Validation** -- Confirms `gt log` shows a clean stack with correct parent chain
+
+**On exit 0:** Stack is healthy (or was successfully reconstructed) -- proceed to Step 3.
+**On exit 1:** Reconstruction failed validation. Manual intervention required -- inspect `gt log` output and resolve conflicts.
+
+Use `--dry-run` to preview reconstruction actions without making changes.
+
+## Step 3: Quick Test Verification
+
+Run tests from the top of the Graphite stack to confirm everything works:
+```bash
+npm run test:run
+npm run typecheck
+```
+
+If these fail, return to `/exarchos:review` or `/exarchos:delegate` to resolve.
+
+## Step 4: Check CodeRabbit Review State
+
+Get PR numbers from the Graphite stack, then run the CodeRabbit review check:
+```bash
+# Get PR numbers from gt log
+PR_NUMBERS=$(gt log --short | grep -o '#[0-9]*' | sed 's/#//')
+
+# Check CodeRabbit review state
+scripts/check-coderabbit.sh \
+  --owner <owner> --repo <repo> \
+  $PR_NUMBERS
+```
+
+The script queries GitHub's PR reviews API for each PR, filters for CodeRabbit reviews, and classifies the latest review state.
+
+**On exit 0:** All PRs are APPROVED or have no CodeRabbit review -- proceed to Step 5.
+**On exit 1:** 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]" })
+```
+After fixes are applied, return to Step 4 to re-check.
+
+## Step 5: Submit Stack to Merge Queue
+
+Enqueue the stack for merging (PRs already exist from delegation):
+
+```
+mcp__graphite__run_gt_cmd({
+  args: ["submit", "--no-interactive", "--publish", "--merge-when-ready"],
+  cwd: "<repo-root>",
+  why: "Enqueue stacked PRs in merge queue after review gates pass"
+})
+```
+
+After submission, use `mcp__graphite__run_gt_cmd` with `["log", "--short"]` to get the PR URLs for each stack entry.
+
+## Step 6: Cleanup After Merge
+
+After PRs are merged, use Graphite to clean up:
+```
+mcp__graphite__run_gt_cmd({
+  args: ["sync"],
+  cwd: "<repo-root>",
+  why: "Pull latest trunk, clean up merged branches"
+})
+```
+
+Then remove worktrees if they exist:
+```bash
+# Remove worktrees used during delegation
+git worktree list | grep ".worktrees/" | awk '{print $1}' | xargs -I{} git worktree remove {}
+git worktree prune
+```

package/skills/synthesis/references/troubleshooting.md

@@ -0,0 +1,115 @@
+# Troubleshooting
+
+## Handling Failures
+
+### Test Failure (Unexpected)
+
+If tests fail during synthesis (they passed in review):
+
+1. Return to review phase to investigate
+2. Re-run `/exarchos:review` to diagnose
+3. Dispatch fixes via `/exarchos:delegate --fixes`
+4. Return to synthesis after review passes
+
+### PR Checks Fail
+
+1. Wait for CI feedback
+2. Create fix task for failures
+3. Push fixes to the stack branches
+4. Re-run synthesis verification
+
+### 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)
+2. Fix failing checks
+3. Push fixes and re-enqueue
+
+## Handling PR Feedback
+
+If the user receives PR review comments:
+
+1. Offer to address feedback:
+   ```typescript
+   Skill({ skill: "exarchos:delegate", args: "--pr-fixes [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 stack with `mcp__graphite__run_gt_cmd` using `["modify", "-m", "fix: <description>"]` and resubmit with `["submit", "--no-interactive", "--publish", "--merge-when-ready"]`
+5. Return to merge confirmation
+
+## Final Report Template
+
+```markdown
+## Synthesis Complete
+
+### Pull Requests
+[PR URLs from gt log --short]
+
+### Stack Branches
+- task/001-types
+- task/002-api
+- task/003-tests
+
+### Test Results
+- Unit tests: PASS
+- Type check: PASS
+- Lint: PASS
+- Build: PASS
+
+### Next Steps
+1. Wait for CI/CD checks
+2. Request code review (if required)
+3. Merge when approved
+4. Worktrees will be cleaned up after merge
+
+### Documentation
+- Design: docs/designs/YYYY-MM-DD-feature.md
+- Plan: docs/plans/YYYY-MM-DD-feature.md
+```
+
+## MCP Tool Call Failed
+If an Exarchos MCP tool returns an error:
+1. Check the error message -- it usually contains specific guidance
+2. Verify the workflow state exists: call `mcp__exarchos__exarchos_workflow` with `action: "get"` and the featureId
+3. If "version mismatch": another process updated state -- retry the operation
+4. If state is corrupted: call `mcp__exarchos__exarchos_workflow` with `action: "cancel"` and `dryRun: true`
+
+## State Desync
+If workflow state doesn't match git reality:
+1. The SessionStart hook runs reconciliation automatically on resume
+2. If manual check needed: compare state file with `git log` and branch state
+3. Update state via `mcp__exarchos__exarchos_workflow` with `action: "set"` to match git truth
+
+## PR Creation Failed
+If `gt submit` fails:
+1. Check the error output for specific guidance
+2. Run `gt log` to verify the stack state
+3. If rebase conflict: run `gt restack` to resolve
+4. If authentication issue: check GitHub token permissions
+
+## Stack Rebase Conflict
+If `gt restack` encounters conflicts:
+1. Resolve conflicts manually in each affected file
+2. Run `git add <resolved-files>` then `gt continue`
+3. After resolution, re-run `gt submit --no-interactive --publish --merge-when-ready`
+
+## Exarchos Integration
+
+When Exarchos MCP tools are available:
+
+1. **After stack submission:** Call `mcp__exarchos__exarchos_event` with `action: "append"` with event type `stack.enqueued` including PR numbers from `gt log --short`
+2. **Monitor merge status:** Use `mcp__graphite__run_gt_cmd` with `["log", "--short"]` to check stack/PR status
+3. **On successful merge:** Call `mcp__exarchos__exarchos_event` with `action: "append"` with event type `phase.transitioned` to mark workflow complete
+
+## Performance Notes
+
+- Complete each step fully before advancing -- quality over speed
+- Do not skip validation checks even when the change appears trivial
+- Verify all tests pass before creating PR. Do not skip the pre-submit validation step.

package/skills/validate-all-skills.sh

@@ -0,0 +1,57 @@
+#!/usr/bin/env bash
+# validate-all-skills.sh — Run frontmatter validation on all SKILL.md files
+#
+# Usage: bash skills/validate-all-skills.sh
+# Must be run from the repository root, or provide SKILLS_DIR env var.
+#
+# Iterates over skills/*/SKILL.md (excluding test-fixtures and shared),
+# extracts folder name, and calls validate-frontmatter.sh for each.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+VALIDATOR="${SCRIPT_DIR}/validate-frontmatter.sh"
+SKILLS_DIR="${SCRIPT_DIR}"
+shopt -s nullglob
+
+# Colors
+GREEN='\033[0;32m'
+RED='\033[0;31m'
+RESET='\033[0m'
+
+PASS_COUNT=0
+FAIL_COUNT=0
+TOTAL=0
+
+for skill_file in "${SKILLS_DIR}"/*/SKILL.md; do
+  folder_path=$(dirname "$skill_file")
+  folder_name=$(basename "$folder_path")
+
+  # Skip test fixtures and shared
+  if [[ "$folder_name" == "test-fixtures" || "$folder_name" == "shared" ]]; then
+    continue
+  fi
+
+  TOTAL=$((TOTAL + 1))
+
+  validation_output=""
+  validation_output=$("$VALIDATOR" "$skill_file" "$folder_name" 2>&1) && validation_exit=0 || validation_exit=$?
+
+  if [[ "$validation_exit" -eq 0 ]]; then
+    PASS_COUNT=$((PASS_COUNT + 1))
+    printf "%b" "Validating $(printf '%-30s' "${folder_name}...") ${GREEN}PASS${RESET}\n"
+  else
+    FAIL_COUNT=$((FAIL_COUNT + 1))
+    # Extract the first error for the summary line
+    first_error=$(echo "$validation_output" | head -n 1 | sed 's/^ERROR: //')
+    printf "%b" "Validating $(printf '%-30s' "${folder_name}...") ${RED}FAIL${RESET} (${first_error})\n"
+  fi
+done
+
+echo ""
+echo "=== Results: ${PASS_COUNT}/${TOTAL} skills passed ==="
+
+if [[ "$FAIL_COUNT" -gt 0 ]]; then
+  exit 1
+fi
+exit 0

package/skills/validate-frontmatter.sh

@@ -0,0 +1,237 @@
+#!/usr/bin/env bash
+# validate-frontmatter.sh — Validate YAML frontmatter in SKILL.md files
+#
+# Usage: validate-frontmatter.sh <path-to-SKILL.md> <expected-folder-name>
+#
+# Runs all checks, collects errors, exits 0 if clean or 1 if any errors found.
+# Designed for macOS compatibility (no GNU-specific tools).
+
+set -euo pipefail
+
+SKILL_FILE="${1:-}"
+EXPECTED_FOLDER="${2:-}"
+
+if [[ -z "$SKILL_FILE" || -z "$EXPECTED_FOLDER" ]]; then
+  echo "Usage: validate-frontmatter.sh <path-to-SKILL.md> <expected-folder-name>"
+  exit 2
+fi
+
+if [[ ! -f "$SKILL_FILE" ]]; then
+  echo "ERROR: File not found: $SKILL_FILE"
+  exit 2
+fi
+
+ERRORS=()
+FRONTMATTER=""
+BODY=""
+
+# ---------------------------------------------------------------------------
+# check_frontmatter_exists
+#   Verify file starts with --- and has a closing ---.
+#   Extract frontmatter between delimiters and body after closing delimiter.
+# ---------------------------------------------------------------------------
+check_frontmatter_exists() {
+  local first_line
+  first_line=$(head -n 1 "$SKILL_FILE")
+
+  if [[ "$first_line" != "---" ]]; then
+    ERRORS+=("check_frontmatter_exists: Missing opening --- delimiter")
+    return
+  fi
+
+  # Find the closing --- (second occurrence, so line number > 1)
+  local closing_line=0
+  local line_num=0
+  while IFS= read -r line; do
+    line_num=$((line_num + 1))
+    if [[ "$line_num" -gt 1 && "$line" == "---" ]]; then
+      closing_line=$line_num
+      break
+    fi
+  done < "$SKILL_FILE"
+
+  if [[ "$closing_line" -eq 0 ]]; then
+    ERRORS+=("check_frontmatter_exists: Missing closing --- delimiter")
+    return
+  fi
+
+  # Extract frontmatter (between line 2 and closing_line - 1)
+  local fm_start=2
+  local fm_end=$((closing_line - 1))
+  FRONTMATTER=$(sed -n "${fm_start},${fm_end}p" "$SKILL_FILE")
+
+  # Extract body (everything after closing delimiter)
+  local body_start=$((closing_line + 1))
+  local total_lines
+  total_lines=$(awk 'END {print NR}' "$SKILL_FILE")
+  if [[ "$body_start" -le "$total_lines" ]]; then
+    BODY=$(tail -n +"$body_start" "$SKILL_FILE")
+  else
+    BODY=""
+  fi
+}
+
+# ---------------------------------------------------------------------------
+# check_required_fields
+#   Verify name: and description: are present in the frontmatter.
+# ---------------------------------------------------------------------------
+check_required_fields() {
+  if [[ -z "$FRONTMATTER" ]]; then
+    return
+  fi
+
+  if ! echo "$FRONTMATTER" | grep -q '^name:'; then
+    ERRORS+=("check_required_fields: Missing required field 'name'")
+  fi
+
+  if ! echo "$FRONTMATTER" | grep -q '^description:'; then
+    ERRORS+=("check_required_fields: Missing required field 'description'")
+  fi
+}
+
+# ---------------------------------------------------------------------------
+# check_name_matches_folder
+#   Verify the name: value matches the expected folder name (kebab-case).
+# ---------------------------------------------------------------------------
+check_name_matches_folder() {
+  if [[ -z "$FRONTMATTER" ]]; then
+    return
+  fi
+
+  local name_value
+  name_value=$(echo "$FRONTMATTER" | grep '^name:' | sed 's/^name:[[:space:]]*//' | tr -d '"' | tr -d "'" || true)
+
+  if [[ -z "$name_value" ]]; then
+    return  # Already caught by check_required_fields
+  fi
+
+  if [[ "$name_value" != "$EXPECTED_FOLDER" ]]; then
+    ERRORS+=("check_name_matches_folder: Name '${name_value}' does not match folder '${EXPECTED_FOLDER}'")
+  fi
+}
+
+# ---------------------------------------------------------------------------
+# check_no_xml_tags
+#   Verify the frontmatter section contains no < or > characters.
+# ---------------------------------------------------------------------------
+check_no_xml_tags() {
+  if [[ -z "$FRONTMATTER" ]]; then
+    return
+  fi
+
+  if echo "$FRONTMATTER" | grep -q '[<>]'; then
+    ERRORS+=("check_no_xml_tags: Frontmatter contains '<' or '>' characters (breaks Claude Code parsing)")
+  fi
+}
+
+# ---------------------------------------------------------------------------
+# check_word_count
+#   Count words in the body and verify <= 2000 words.
+# ---------------------------------------------------------------------------
+check_word_count() {
+  if [[ -z "$BODY" ]]; then
+    return
+  fi
+
+  local word_count
+  word_count=$(echo "$BODY" | wc -w | tr -d ' ')
+
+  if [[ "$word_count" -gt 2000 ]]; then
+    ERRORS+=("check_word_count: Body has ${word_count} words (limit: 2000)")
+  fi
+}
+
+# ---------------------------------------------------------------------------
+# check_references_exist
+#   Find all references/*.md patterns in the body and verify each file exists
+#   relative to the SKILL.md's parent directory.
+# ---------------------------------------------------------------------------
+check_references_exist() {
+  if [[ -z "$BODY" ]]; then
+    return
+  fi
+
+  local skill_dir
+  skill_dir=$(dirname "$SKILL_FILE")
+
+  # Find all references/*.md patterns in the body
+  local refs
+  refs=$(echo "$BODY" | grep -oE 'references/[^)[:space:]"]+\.md' || true)
+
+  if [[ -z "$refs" ]]; then
+    return
+  fi
+
+  while IFS= read -r ref; do
+    if [[ ! -f "${skill_dir}/${ref}" ]]; then
+      ERRORS+=("check_references_exist: Referenced file '${ref}' not found relative to $(basename "$skill_dir")/")
+    fi
+  done <<< "$refs"
+}
+
+# ---------------------------------------------------------------------------
+# check_negative_trigger
+#   Verify the description contains a negative trigger phrase
+#   (e.g., "Do NOT" or "Not for") to help Claude Code disambiguate skills.
+# ---------------------------------------------------------------------------
+check_negative_trigger() {
+  if [[ -z "$FRONTMATTER" ]]; then
+    return
+  fi
+
+  local desc_value
+  desc_value=$(echo "$FRONTMATTER" | grep '^description:' | sed 's/^description:[[:space:]]*//' | tr -d '"' | tr -d "'" || true)
+
+  if [[ -z "$desc_value" ]]; then
+    return  # Already caught by check_required_fields
+  fi
+
+  if ! echo "$desc_value" | grep -qi 'Do NOT\|Not for'; then
+    ERRORS+=("check_negative_trigger: Description lacks a negative trigger phrase (e.g., 'Do NOT ...' or 'Not for ...')")
+  fi
+}
+
+# ---------------------------------------------------------------------------
+# check_no_orphan_references
+#   Verify every .md file in references/ is actually referenced in the body.
+#   Only checks .md files (not .sh, .json, etc.).
+# ---------------------------------------------------------------------------
+check_no_orphan_references() {
+  local skill_dir
+  skill_dir=$(dirname "$SKILL_FILE")
+  local refs_dir="${skill_dir}/references"
+
+  if [[ ! -d "$refs_dir" ]]; then
+    return  # No references directory — nothing to check
+  fi
+
+  for ref_file in "$refs_dir"/*.md; do
+    [[ -f "$ref_file" ]] || continue
+    local ref_name="references/$(basename "$ref_file")"
+    if ! echo "$BODY" | grep -qF "$ref_name"; then
+      ERRORS+=("check_no_orphan_references: File '${ref_name}' exists but is not referenced in SKILL.md")
+    fi
+  done
+}
+
+# ---------------------------------------------------------------------------
+# Main — Run all checks, report errors, exit appropriately
+# ---------------------------------------------------------------------------
+
+check_frontmatter_exists
+check_required_fields
+check_name_matches_folder
+check_no_xml_tags
+check_word_count
+check_references_exist
+check_negative_trigger
+check_no_orphan_references
+
+if [[ ${#ERRORS[@]} -gt 0 ]]; then
+  for err in "${ERRORS[@]}"; do
+    echo "ERROR: $err"
+  done
+  exit 1
+fi
+
+exit 0