@lvlup-sw/exarchos 2.0.1

package/hooks/hooks.json

@@ -0,0 +1,53 @@
+{
+  "hooks": {
+    "PreCompact": [{
+      "matcher": "auto",
+      "hooks": [{
+        "type": "command",
+        "command": "node \"${CLAUDE_PLUGIN_ROOT}/dist/exarchos-cli.js\" pre-compact",
+        "timeout": 30,
+        "statusMessage": "Saving workflow checkpoint..."
+      }]
+    }],
+    "SessionStart": [{
+      "matcher": "startup|resume",
+      "hooks": [{
+        "type": "command",
+        "command": "node \"${CLAUDE_PLUGIN_ROOT}/dist/exarchos-cli.js\" session-start",
+        "timeout": 10,
+        "statusMessage": "Checking for active workflows..."
+      }]
+    }],
+    "PreToolUse": [{
+      "matcher": "mcp__exarchos__.*",
+      "hooks": [{
+        "type": "command",
+        "command": "node \"${CLAUDE_PLUGIN_ROOT}/dist/exarchos-cli.js\" guard",
+        "timeout": 5
+      }]
+    }],
+    "TaskCompleted": [{
+      "hooks": [{
+        "type": "command",
+        "command": "node \"${CLAUDE_PLUGIN_ROOT}/dist/exarchos-cli.js\" task-gate",
+        "timeout": 120,
+        "statusMessage": "Running quality gates..."
+      }]
+    }],
+    "TeammateIdle": [{
+      "hooks": [{
+        "type": "command",
+        "command": "node \"${CLAUDE_PLUGIN_ROOT}/dist/exarchos-cli.js\" teammate-gate",
+        "timeout": 120,
+        "statusMessage": "Verifying teammate work..."
+      }]
+    }],
+    "SubagentStart": [{
+      "hooks": [{
+        "type": "command",
+        "command": "node \"${CLAUDE_PLUGIN_ROOT}/dist/exarchos-cli.js\" subagent-context",
+        "timeout": 5
+      }]
+    }]
+  }
+}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@lvlup-sw/exarchos",
+  "version": "2.0.1",
+  "description": "Governed SDLC workflows for Claude Code — agent orchestration, quality gates, and Graphite stacked PRs",
+  "type": "module",
+  "bin": {
+    "exarchos-cli": "./dist/exarchos-cli.js"
+  },
+  "files": [
+    "dist/exarchos-mcp.js",
+    "dist/exarchos-cli.js",
+    "commands",
+    "skills",
+    "rules",
+    "scripts",
+    "hooks",
+    "settings.json",
+    ".mcp.json",
+    ".claude-plugin",
+    "CLAUDE.md.template",
+    "AGENTS.md",
+    "!**/*.test.sh",
+    "!**/*.test.ts",
+    "!**/test-fixtures",
+    "!**/trigger-tests"
+  ],
+  "scripts": {
+    "build": "tsc && bun run build:mcp && bun run build:cli",
+    "build:cli": "bun build servers/exarchos-mcp/src/cli.ts --outfile dist/exarchos-cli.js --target node",
+    "build:mcp": "bun build servers/exarchos-mcp/src/index.ts --outfile dist/exarchos-mcp.js --target bun --minify",
+    "prepare": "tsc",
+    "bench": "cd servers/exarchos-mcp && npx vitest bench",
+    "test": "vitest",
+    "test:run": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "validate": "bash scripts/validate-plugin.sh",
+    "validate:companion": "bash scripts/validate-companion.sh"
+  },
+  "keywords": [
+    "claude-code-plugin",
+    "agent-governance",
+    "workflow",
+    "sdlc",
+    "tdd",
+    "graphite",
+    "event-sourcing",
+    "code-review"
+  ],
+  "author": "lvlup-sw",
+  "license": "Apache-2.0",
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^3.0.0"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  }
+}

package/rules/coding-standards.md

@@ -0,0 +1,46 @@
+---
+paths: "**/*.ts", "**/*.tsx", "**/*.cs"
+---
+
+# Coding Standards
+
+Apply these standards when reviewing or writing TypeScript or C# code.
+
+## SOLID Constraints
+
+| Principle | TypeScript | C# |
+|-----------|-----------|-----|
+| **S**RP | One primary component/class per file | One public type per file; filename matches type name |
+| **O**CP | Discriminated unions or strategy pattern, not type switches | No `switch` on types/enums for logic; use polymorphism |
+| **L**SP | Implement all interface methods fully | Subclasses must not throw `NotImplementedException` |
+| **I**SP | Small focused interfaces, composed as needed | Small role-specific interfaces (e.g., `IReadable`, `IWritable`) |
+| **D**IP | Depend on interfaces, inject implementations | All dependencies via constructor injection; never `new` concrete services |
+
+## Control Flow
+
+- **Guard clauses first**: Validate/narrow at function entry
+- **Early return**: Exit immediately when conditions fail
+- **No arrow code**: Flatten nested conditionals with early returns
+- **Extract complexity**: Complex conditions into named predicates/helpers
+
+## Error Handling
+
+| Pattern | TypeScript | C# |
+|---------|-----------|-----|
+| Recoverable errors | Result types (consider `neverthrow`) | `Result<T>` pattern |
+| Programmer errors | Custom error classes with discriminated unions | Exceptions + `ArgumentNullException.ThrowIfNull()` |
+| Silent catches | Never — always handle or rethrow | Never — always handle or rethrow |
+| Boundaries | Explicit error boundaries at API/UI layers | Explicit error boundaries at API/UI layers |
+
+## Code Organization (DRY)
+
+- Extract duplicated logic into utility functions/helpers
+- Use built-in collection methods (TS: `map`/`filter`/`reduce`; C#: LINQ)
+- Leverage standard utility types (TS: `Partial`, `Pick`, `Omit`; C#: generics, records)
+- Do not re-implement standard library functionality
+
+---
+
+For TypeScript-specific standards, see `@skills/quality-review/references/typescript-standards.md`.
+
+For C#-specific standards, see `@skills/dotnet-standards/references/csharp-standards.md`.

package/rules/mcp-tool-guidance.md

@@ -0,0 +1,26 @@
+---
+name: mcp-tool-guidance
+description: "Prefer specialized MCP tools over generic CLI approaches."
+---
+
+# MCP Tool Guidance
+
+Use specialized MCP tools over generic approaches:
+
+1. **Workflow state** — Exarchos MCP, never manual JSON
+2. **PR creation** — Graphite MCP (`gt submit --no-interactive --publish --merge-when-ready`), never `gh pr create`
+3. **State management** — `exarchos_workflow` set/get, never edit JSON directly
+
+> Additional tool guidance (Serena, GitHub MCP, Context7) is provided by the exarchos-dev-tools companion. Install: `npx @lvlup-sw/exarchos-dev`
+
+## Quick Reference — `exarchos_workflow`
+
+Before calling, consult `@skills/workflow-state/references/mcp-tool-reference.md` for full action signatures, error handling, and anti-patterns.
+
+| Action | Key Parameters |
+|--------|---------------|
+| `get` | `featureId`, optional `query` (dot-path) or `fields` (string array for projection) |
+| `set` | `featureId`, `updates` (object), `phase` (string) — send both in one call for guarded transitions |
+| `init` | `featureId`, `workflowType` (`"feature"` / `"debug"` / `"refactor"`) |
+| `cleanup` | `featureId`, `mergeVerified: true`, `prUrl`, `mergedBranches` |
+| `cancel` | `featureId`, optional `dryRun: true` |

package/rules/pr-descriptions.md

@@ -0,0 +1,12 @@
+---
+name: pr-descriptions
+description: "PR title and body format guidelines for Graphite stacked PRs."
+---
+
+# PR Descriptions
+
+**Title:** `<type>: <what>` (max 72 chars)
+
+**Body:** Summary (2-3 sentences) → Changes (bulleted, `**Component** — description`) → Test Plan → Footer (`---` + results, design doc, related PRs). Aim for 120-200 words.
+
+See `skills/synthesis/references/pr-descriptions.md` for template and examples.

package/rules/rm-safety.md

@@ -0,0 +1,9 @@
+---
+alwaysApply: true
+---
+
+# rm Safety
+
+**NEVER:** `rm -rf /`, `rm -rf ~`, `rm -rf .` in home/root, rm with unset variables (`$UNSET_VAR/*`)
+
+**Always:** Use specific paths, `ls` before deleting, avoid `-f` unless needed, verify `-r` targets. When uncertain, preview with `echo rm ...` or ask the user.

package/rules/skill-path-resolution.md

@@ -0,0 +1,10 @@
+---
+name: skill-path-resolution
+description: "Resolve @skills/<name>/SKILL.md paths to ~/.claude/skills/<name>/SKILL.md."
+---
+
+# Skill Path Resolution
+
+`@skills/<name>/SKILL.md` resolves to `~/.claude/skills/<name>/SKILL.md`.
+
+When encountered: read the skill file, follow its instructions, use templates from its directory. If not found, report to user and fall back to inline instructions.

package/rules/tdd.md

@@ -0,0 +1,41 @@
+---
+paths: "**/*.ts", "**/*.tsx", "**/*.cs"
+---
+
+# TDD Rules
+
+Enforce strict TDD when modifying TypeScript or C# files.
+
+## TDD Workflow
+
+### RED Phase
+1. Write a test that describes expected behavior
+2. Run tests — test MUST fail
+3. Verify it fails for the RIGHT reason (not a compilation error)
+
+### GREEN Phase
+1. Write the minimum code to make the test pass
+2. Run tests — test MUST pass
+3. No extra features or optimizations
+
+### REFACTOR Phase
+1. Clean up code while tests stay green
+2. Extract helpers, improve naming, apply SOLID
+3. Run tests after each change
+
+## Conventions
+
+| | TypeScript | C# |
+|--|-----------|-----|
+| Framework | Vitest | TUnit |
+| Test files | `foo.test.ts` (co-located) | `Foo.Tests.cs` (co-located) |
+| Naming | `Method_Scenario_Outcome` | `Method_Scenario_Outcome` |
+| Run | `npm run test:run` | `dotnet test` |
+| Pattern | Arrange / Act / Assert | Arrange / Act / Assert |
+| Mocking | `vi.mock()`, `vi.fn()` | NSubstitute (`Substitute.For<T>()`) |
+| PBT | `@fast-check/vitest` | FsCheck |
+
+For test code patterns and examples, see `@skills/delegation/references/testing-patterns.md`.
+For property-based testing templates, see `@skills/delegation/references/pbt-patterns.md`.
+
+Property tests are written alongside example tests in the RED phase. They complement, not replace, example tests.

package/rules/telemetry-awareness.md

@@ -0,0 +1,9 @@
+---
+name: telemetry-awareness
+description: "Apply telemetryHints from session-start output to subsequent MCP tool calls."
+---
+
+# Telemetry Awareness
+
+When `telemetryHints` appear in session-start output, apply the suggested
+optimizations to subsequent MCP tool calls for the remainder of the session.

package/scripts/assess-refactor-scope.sh

@@ -0,0 +1,239 @@
+#!/usr/bin/env bash
+# Assess Refactor Scope
+# Assesses scope and recommends track (polish vs overhaul).
+# Replaces explore phase scope assessment prose with deterministic validation.
+#
+# Usage: assess-refactor-scope.sh --files <file1,file2,...> | --state-file <path>
+#
+# Exit codes:
+#   0 = polish recommended
+#   1 = overhaul recommended
+#   2 = usage error (missing required args)
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# Colors
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m'
+
+# ============================================================
+# ARGUMENT PARSING
+# ============================================================
+
+FILES=""
+STATE_FILE=""
+
+usage() {
+    cat << 'USAGE'
+Usage: assess-refactor-scope.sh --files <file1,file2,...> | --state-file <path>
+
+Required (one of):
+  --files <file1,file2,...>   Comma-separated list of affected files
+  --state-file <path>        Path to workflow state JSON (reads explore.scopeAssessment.filesAffected)
+
+Optional:
+  --help                     Show this help message
+
+Exit codes:
+  0  Polish recommended (<=5 files, single module, good test coverage)
+  1  Overhaul recommended (scope exceeds polish limits)
+  2  Usage error (missing required args)
+USAGE
+}
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --files)
+            if [[ -z "${2:-}" ]]; then
+                echo "Error: --files requires a comma-separated list" >&2
+                exit 2
+            fi
+            FILES="$2"
+            shift 2
+            ;;
+        --state-file)
+            if [[ -z "${2:-}" ]]; then
+                echo "Error: --state-file requires a path argument" >&2
+                exit 2
+            fi
+            STATE_FILE="$2"
+            shift 2
+            ;;
+        --help)
+            usage
+            exit 0
+            ;;
+        *)
+            echo "Error: Unknown argument '$1'" >&2
+            usage >&2
+            exit 2
+            ;;
+    esac
+done
+
+if [[ -z "$FILES" && -z "$STATE_FILE" ]]; then
+    echo "Error: --files or --state-file is required" >&2
+    usage >&2
+    exit 2
+fi
+
+# ============================================================
+# DEPENDENCY CHECK
+# ============================================================
+
+if [[ -n "$STATE_FILE" ]]; then
+    if ! command -v jq &>/dev/null; then
+        echo "Error: jq is required but not installed" >&2
+        exit 2
+    fi
+fi
+
+# ============================================================
+# PARSE FILES
+# ============================================================
+
+FILE_LIST=()
+
+if [[ -n "$STATE_FILE" ]]; then
+    if [[ ! -f "$STATE_FILE" ]]; then
+        echo "Error: State file not found: $STATE_FILE" >&2
+        exit 2
+    fi
+    # Read files from state file
+    while IFS= read -r line; do
+        FILE_LIST+=("$line")
+    done < <(jq -r '.explore.scopeAssessment.filesAffected[]' "$STATE_FILE" 2>/dev/null)
+elif [[ -n "$FILES" ]]; then
+    IFS=',' read -ra FILE_LIST <<< "$FILES"
+fi
+
+FILE_COUNT=${#FILE_LIST[@]}
+
+# ============================================================
+# ASSESS SCOPE
+# ============================================================
+
+CHECK_PASS=0
+CHECK_FAIL=0
+RESULTS=()
+
+check_pass() {
+    local name="$1"
+    RESULTS+=("- **PASS**: $name")
+    CHECK_PASS=$((CHECK_PASS + 1))
+}
+
+check_fail() {
+    local name="$1"
+    local detail="${2:-}"
+    if [[ -n "$detail" ]]; then
+        RESULTS+=("- **FAIL**: $name — $detail")
+    else
+        RESULTS+=("- **FAIL**: $name")
+    fi
+    CHECK_FAIL=$((CHECK_FAIL + 1))
+}
+
+# Check 1: File count (<=5 for polish)
+if [[ $FILE_COUNT -le 5 ]]; then
+    check_pass "File count within polish limit ($FILE_COUNT <= 5)"
+else
+    check_fail "File count exceeds polish limit" "$FILE_COUNT files (max 5)"
+fi
+
+# Check 2: Cross-module span
+# Extract unique top-level directories (Bash 3 compatible — no associative arrays)
+MODULE_LIST=""
+for f in "${FILE_LIST[@]}"; do
+    top_dir="$(echo "$f" | cut -d'/' -f1)"
+    # Add to list if not already present
+    if ! echo "$MODULE_LIST" | grep -qF "|$top_dir|"; then
+        MODULE_LIST="${MODULE_LIST}|$top_dir|"
+    fi
+done
+# Count unique modules
+MODULE_COUNT=0
+MODULE_NAMES=""
+if [[ -n "$MODULE_LIST" ]]; then
+    MODULE_NAMES="$(echo "$MODULE_LIST" | tr '|' '\n' | sort -u | grep -v '^$' | tr '\n' ' ')"
+    MODULE_COUNT="$(echo "$MODULE_LIST" | tr '|' '\n' | sort -u | grep -vc '^$' || true)"
+fi
+
+if [[ $MODULE_COUNT -le 1 ]]; then
+    check_pass "Single module scope ($MODULE_NAMES)"
+else
+    check_fail "Cross-module span detected" "$MODULE_COUNT modules: $MODULE_NAMES"
+fi
+
+# Check 3: Test coverage (check if .test.ts/.test.sh files exist for affected files)
+MISSING_TESTS=()
+for f in "${FILE_LIST[@]}"; do
+    # Skip files that are already test files
+    if [[ "$f" == *.test.ts || "$f" == *.test.sh ]]; then
+        continue
+    fi
+    # Skip non-source files
+    if [[ "$f" != *.ts && "$f" != *.sh ]]; then
+        continue
+    fi
+    # Derive expected test file name
+    if [[ "$f" == *.ts ]]; then
+        test_file="${f%.ts}.test.ts"
+    elif [[ "$f" == *.sh ]]; then
+        test_file="${f%.sh}.test.sh"
+    fi
+    # We can only check existence if we have a reference directory,
+    # but for scope assessment we just note the expected test counterparts
+    MISSING_TESTS+=("$test_file")
+done
+
+# For scope assessment purposes, having test counterparts is informational
+if [[ ${#MISSING_TESTS[@]} -eq 0 ]]; then
+    check_pass "Test coverage assessment (all source files have known patterns)"
+else
+    # This is informational, not a hard fail for track decision
+    check_pass "Test coverage assessment (${#MISSING_TESTS[@]} test counterparts to verify)"
+fi
+
+# ============================================================
+# DETERMINE RECOMMENDATION
+# ============================================================
+
+RECOMMENDATION="polish"
+if [[ $FILE_COUNT -gt 5 ]]; then
+    RECOMMENDATION="overhaul"
+fi
+if [[ $MODULE_COUNT -gt 1 ]]; then
+    RECOMMENDATION="overhaul"
+fi
+
+# ============================================================
+# STRUCTURED OUTPUT
+# ============================================================
+
+echo "## Scope Assessment Report"
+echo ""
+echo "**Files affected:** $FILE_COUNT"
+echo "**Modules:** ${MODULE_NAMES:-}"
+echo "**Recommendation:** $RECOMMENDATION"
+echo ""
+
+for result in "${RESULTS[@]}"; do
+    echo "$result"
+done
+
+echo ""
+echo "---"
+echo ""
+
+if [[ "$RECOMMENDATION" == "polish" ]]; then
+    echo "**Result: POLISH** — Scope is within polish limits"
+    exit 0
+else
+    echo "**Result: OVERHAUL** — Scope exceeds polish limits"
+    exit 1
+fi