@lvlup-sw/exarchos 2.0.1

package/skills/refactor/COMMAND.md

@@ -0,0 +1,67 @@
+# /refactor Command
+
+## Purpose
+
+Start a refactoring workflow for code improvements, cleanup, or restructuring.
+
+## Usage
+
+```
+/refactor [target] [--polish] [--explore-only]
+```
+
+## Arguments
+
+| Argument | Description |
+|----------|-------------|
+| `target` | Optional. File, directory, or module to refactor. If omitted, will prompt. |
+
+## Flags
+
+| Flag | Description |
+|------|-------------|
+| `--polish` | Force polish track (direct implementation, no worktrees). Use for small, well-scoped refactors. |
+| `--explore-only` | Run exploration phase only, output scope assessment without proceeding. |
+
+## Examples
+
+### Start refactor with exploration
+```
+/refactor src/services/auth
+```
+
+### Force small refactor mode
+```
+/refactor src/utils/helpers.ts --polish
+```
+
+### Just assess scope
+```
+/refactor src/api --explore-only
+```
+
+## Workflow Entry
+
+The command triggers the refactor skill which:
+
+1. **Explore phase**: Assesses scope (files, concerns, cross-module impact)
+2. **Track selection**:
+   - Polish (<=5 files, single concern) -> direct implementation
+   - Overhaul (>5 files or multiple concerns) -> full workflow
+3. **Brief capture**: Records problem, goals, approach in state
+4. **Execution**: Track-specific implementation
+5. **Validation**: Tests pass, goals met, docs updated
+
+## State Initialization
+
+**Initialize refactor workflow:**
+
+```
+action: "init", featureId: "refactor-<slug>", workflowType: "refactor"
+```
+
+## See Also
+
+- `/exarchos:debug` - For bug fixes
+- `/exarchos:ideate` - For new features
+- `/exarchos:plan` - For implementation planning (used by overhaul track)

package/skills/refactor/SKILL.md

@@ -0,0 +1,198 @@
+---
+name: refactor
+description: "Code improvement workflow with two tracks: polish (small, direct changes) and overhaul (large, delegated restructuring). Use when the user says \"refactor\", \"clean up\", \"restructure\", \"reorganize\", \"refactor this code\", or runs /refactor. Handles explore, brief, implement, validate, and documentation phases. Do NOT use for bug fixes (use /debug) or new features (use /ideate). Applies to existing code only."
+metadata:
+  author: exarchos
+  version: 1.0.0
+  mcp-server: exarchos
+  category: workflow
+  phase-affinity:
+    - explore
+    - brief
+    - implement
+    - validate
+    - update-docs
+    - synthesize
+---
+
+# Refactor Workflow Skill
+
+## Overview
+
+Two-track workflow for improving existing code. Polish track for small, contained refactors; overhaul track for architectural changes and migrations. Both tracks emphasize exploration before commitment and mandatory documentation updates.
+
+## Triggers
+
+Activate this skill when:
+- User runs `/refactor` command
+- User wants to improve existing code structure
+- User mentions "refactor", "restructure", "clean up", "migrate"
+- User asks to "move", "extract", "rename", or "reorganize" code
+
+**Disambiguation:** If the user says "fix" or "clean up" — use `/refactor` when the code *works* but needs structural improvement. Use `/debug` when something is *broken* (error, crash, wrong behavior).
+
+## Workflow Overview
+
+```
+                              /exarchos:refactor
+                                  |
+                            +-----+-----+
+                            |  Explore  |
+                            +-----+-----+
+                                  |
+                   +--------------+--------------+
+                   |                             |
+              --polish                       (default)
+                   |                             |
+                   v                             v
+          +--------------+              +--------------+
+          |    Polish    |              |   Overhaul   |
+          |    Track     |              |    Track     |
+          +--------------+              +--------------+
+```
+
+## Command Interface
+
+### Start Refactor Workflow
+
+```bash
+# Default: overhaul track
+/refactor "Description of what needs refactoring"
+
+# Fast path: polish track
+/refactor --polish "Small contained refactor description"
+
+# Explore first, then decide track
+/refactor --explore "Unsure of scope, explore first"
+```
+
+### Mid-Workflow Commands
+
+```bash
+# Switch from polish to overhaul (during explore/brief)
+/exarchos:refactor --switch-overhaul
+
+# Resume after context compaction
+/exarchos:resume
+```
+
+## Track Comparison
+
+| Aspect | Polish | Overhaul |
+|--------|--------|----------|
+| Scope | <=5 files, single concern | No limit |
+| Worktree | No (direct) | Yes (isolated) |
+| Delegation | No | Yes (full workflow) |
+| Documentation | Mandatory update phase | Mandatory update phase |
+| Human Checkpoints | 0 | 1 (merge) |
+
+## Polish Track
+
+Fast path for small, contained refactors (<=5 files, single concern). Orchestrator may write code directly (exception to orchestrator constraints). No worktree, no delegation.
+
+Phases: Explore -> Brief -> Implement -> Validate -> Update Docs -> Complete
+
+For detailed phase instructions, state management, and auto-chain behavior, see `@skills/refactor/references/polish-track.md`.
+
+## Overhaul Track
+
+Rigorous path for architectural changes, migrations, and multi-file restructuring. Uses full delegation model with worktree isolation.
+
+Phases: Explore -> Brief -> Plan -> Delegate -> Review -> Update Docs -> Synthesize
+
+For detailed phase instructions, skill invocations, and auto-chain behavior, see `@skills/refactor/references/overhaul-track.md`.
+
+## State Management
+
+Initialize refactor workflow:
+```
+action: "init", featureId: "refactor-<slug>", workflowType: "refactor"
+```
+
+Full state schema:
+```json
+{
+  "version": "1.1",
+  "featureId": "refactor-<slug>",
+  "workflowType": "refactor",
+  "track": "polish | overhaul",
+  "phase": "explore | brief | polish-implement | polish-validate | polish-update-docs | overhaul-plan | overhaul-delegate | overhaul-review | overhaul-update-docs | synthesize | completed | cancelled | blocked",
+  "explore": {
+    "startedAt": "ISO8601",
+    "completedAt": "ISO8601 | null",
+    "scopeAssessment": {
+      "filesAffected": ["string"],
+      "modulesAffected": ["string"],
+      "testCoverage": "good | gaps | none",
+      "recommendedTrack": "polish | overhaul"
+    }
+  },
+  "brief": {  // See references/brief-template.md for field descriptions
+    "problem": "string",
+    "goals": ["string"],
+    "approach": "string",
+    "affectedAreas": ["string"],
+    "outOfScope": ["string"],
+    "successCriteria": ["string"],
+    "docsToUpdate": ["string"]
+  },
+  "artifacts": {
+    "plan": "string | null",
+    "pr": "string | null",
+    "updatedDocs": ["string"]
+  },
+  "validation": {
+    "testsPass": "boolean",
+    "goalsVerified": ["string"],
+    "docsUpdated": "boolean"
+  }
+}
+```
+
+## Track Switching
+
+If scope expands beyond polish limits during explore or brief phase, use `mcp__exarchos__exarchos_workflow` with `action: "set"` to set `track` to "overhaul" and update `explore.scopeAssessment.recommendedTrack`.
+
+**Scope thresholds:** If >5 files affected OR changes cross module boundaries -> recommend overhaul track.
+
+**Indicators to switch:**
+- More than 5 files affected
+- Multiple concerns identified
+- Cross-module changes needed
+- Test coverage gaps require new tests
+
+Output: "Scope expanded beyond polish limits. Switching to overhaul track."
+
+## Integration Points
+
+**CRITICAL:** All skill invocations MUST use explicit `Skill()` tool calls:
+
+| Skill | Invocation | Usage |
+|-------|------------|-------|
+| `/exarchos:plan` | `Skill({ skill: "exarchos:plan", args: "--refactor <state-file>" })` | Task extraction from brief |
+| `/exarchos:delegate` | `Skill({ skill: "exarchos:delegate", args: "<state-file>" })` | Subagent dispatch for TDD |
+| `/exarchos:review` | `Skill({ skill: "exarchos:review", args: "<state-file>" })` | Quality review |
+| `/exarchos:synthesize` | `Skill({ skill: "exarchos:synthesize", args: "<feature>" })` | PR creation |
+
+## Anti-Patterns
+
+| Don't | Do Instead |
+|-------|------------|
+| Skip exploration | Always assess scope first (see `references/explore-checklist.md`) |
+| Use polish for large changes | Switch to overhaul when scope expands |
+| Skip doc updates | Documentation is mandatory (see `references/doc-update-checklist.md`) |
+| Add features during refactor | Scope creep - stick to brief goals |
+| Skip tests because "just moving code" | Refactors need test verification |
+| Create design document for polish | Use brief in state file instead |
+| Work in main for overhaul | Use worktree isolation |
+
+## Exarchos Integration
+
+When Exarchos MCP tools are available, emit events throughout the refactor workflow:
+
+1. **At workflow start (explore):** `mcp__exarchos__exarchos_event` with `action: "append"` → `workflow.started` with workflowType "refactor"
+2. **On track selection:** Auto-emitted by `exarchos_workflow` `set` when `phase` is provided — emits `workflow.transition` with selected track (polish/overhaul)
+3. **On each phase transition:** Auto-emitted by `exarchos_workflow` `set` when `phase` is provided — emits `workflow.transition` with from/to/trigger/featureId
+4. **Overhaul track stacking:** Handled by `/delegate` (subagents use `gt create` per implementer prompt)
+5. **Polish track commit:** Single `gt create -m "refactor: <description>"` — no multi-branch stacking needed
+6. **On complete:** Auto-emitted by `exarchos_workflow` `set` when transitioning to terminal state — emits `workflow.transition` to "completed"

package/skills/refactor/phases/auto-chain.md

@@ -0,0 +1,262 @@
+# Auto-Chain Behavior
+
+## Purpose
+
+Define automatic phase transitions for refactor workflows, minimizing human intervention while maintaining quality.
+
+## Design Principle
+
+**Single human checkpoint per track.**
+
+- Polish track: One checkpoint at completion (commit approval)
+- Overhaul track: One checkpoint at merge (PR approval)
+
+All other transitions are automatic.
+
+## Polish Track Auto-Chain
+
+```text
+explore → brief → implement → validate → update-docs → CHECKPOINT
+```
+
+### Transition Rules
+
+| From | To | Condition | Auto? |
+|------|-----|-----------|-------|
+| explore | brief | Scope assessed | Yes |
+| brief | implement | Brief captured | Yes |
+| implement | validate | Changes complete | Yes |
+| validate | update-docs | Validation passed | Yes |
+| update-docs | complete | Docs updated | Yes |
+| complete | — | Human approves commit | CHECKPOINT |
+
+### Polish Auto-Chain Commands
+
+After each phase, use the SessionStart hook with the featureId to determine the next action:
+
+```text
+# After explore
+The SessionStart hook determines the next action automatically.
+Returns: AUTO:refactor-brief
+
+# After brief
+The SessionStart hook determines the next action automatically.
+Returns: AUTO:polish-implement
+
+# After implement
+The SessionStart hook determines the next action automatically.
+Returns: AUTO:refactor-validate
+
+# After validate (passed)
+The SessionStart hook determines the next action automatically.
+Returns: AUTO:refactor-update-docs
+
+# After update-docs
+The SessionStart hook determines the next action automatically.
+Returns: WAIT:human-checkpoint:polish-update-docs
+```
+
+### Polish Checkpoint
+
+At completion, present to user:
+
+```markdown
+## Polish Refactor Complete
+
+**Changes Made:**
+<summary of files modified>
+
+**Goals Achieved:**
+- <goal 1>: ✓
+- <goal 2>: ✓
+
+**Validation:**
+- Tests: ✓ All passing
+- Docs: ✓ Updated
+
+**Action Required:**
+Ready to commit changes. Approve to commit, or request modifications.
+```
+
+## Overhaul Track Auto-Chain
+
+```text
+explore → brief → plan → delegate → review → update-docs → synthesize → CHECKPOINT
+                                        ↑                    │
+                                        └─── fixes ──────────┘ (if review fails)
+```
+
+### Transition Rules
+
+| From | To | Condition | Auto? |
+|------|-----|-----------|-------|
+| explore | brief | Scope assessed | Yes |
+| brief | plan | Brief captured | Yes |
+| plan | delegate | Plan created | Yes |
+| delegate | review | All tasks complete | Yes |
+| review (pass) | update-docs | Review approved | Yes |
+| review (fail) | delegate | Fix tasks dispatched | Yes (loop) |
+| update-docs | synthesize | Docs updated | Yes |
+| synthesize | complete | Human approves PR | CHECKPOINT |
+
+### Overhaul Auto-Chain Commands
+
+Use the SessionStart hook with the featureId after each phase:
+
+```text
+# After explore
+Returns: AUTO:refactor-brief
+
+# After brief
+Returns: AUTO:overhaul-plan
+
+# After plan
+Returns: AUTO:refactor-delegate
+
+# After delegate
+Returns: AUTO:refactor-review
+
+# After review (passed)
+Returns: AUTO:refactor-update-docs
+
+# After review (failed)
+Returns: AUTO:refactor-delegate:--fixes
+
+# After update-docs
+Returns: AUTO:refactor-synthesize
+
+# After synthesize
+Returns: WAIT:human-checkpoint:synthesize
+```
+
+### Overhaul Checkpoint
+
+#### PR Approval
+
+```markdown
+## Refactor PR Ready
+
+**PR:** <url>
+
+**Summary:**
+<refactor summary>
+
+**Goals Achieved:**
+- <goal 1>: ✓
+- <goal 2>: ✓
+
+**Review Status:**
+- Behavior preserved: ✓
+- Tests passing: ✓
+- Docs updated: ✓
+
+**Action Required:**
+Review PR and approve merge, or request changes.
+```
+
+## Track Switching
+
+If polish track discovers scope expansion, it switches to overhaul:
+
+```text
+polish:implement → [scope expands] → overhaul:plan
+```
+
+Auto-chain handles this via MCP tools:
+
+```text
+# When scope expands during implement, use mcp__exarchos__exarchos_workflow with action: "set":
+# 1. First call: Set updates
+updates: { "implement.switchReason": "<reason>", "implement.switchedAt": "<ISO8601>" }
+
+# 2. Second call: Transition phase and track
+phase: "plan"
+updates: { "track": "overhaul" }
+
+# Next action returns
+The SessionStart hook determines the next action automatically.
+Returns: AUTO:overhaul-plan
+```
+
+## Failure Handling
+
+### Polish Track Failures
+
+| Failure | Recovery |
+|---------|----------|
+| Validate fails | Return to implement, fix issues |
+| Tests fail | Fix tests, re-validate |
+| Scope expands | Switch to overhaul track |
+
+### Overhaul Track Failures
+
+| Failure | Recovery |
+|---------|----------|
+| Review fails | Delegate fixes, re-review |
+| Synthesize fails | Fix PR issues, re-synthesize |
+
+All recoveries are automatic loops until success.
+
+## State Machine Summary
+
+```text
+┌─────────────────────────────────────────────────────────────────┐
+│                        REFACTOR WORKFLOW                         │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                  │
+│  START → explore → brief ─┬─→ [polish] ─→ implement ─→ validate │
+│                           │                                ↓     │
+│                           │                          update-docs │
+│                           │                                ↓     │
+│                           │                          ▣ COMPLETE  │
+│                           │                                      │
+│                           └─→ [overhaul] ─→ plan ─→ delegate     │
+│                                                          ↓       │
+│                                                      review ───┐ │
+│                                                          ↓     │ │
+│                                                    update-docs │ │
+│                                                          ↓     │ │
+│                                                    synthesize  │ │
+│                                                          ↓     │ │
+│                                                    ▣ PR-MERGE  │ │
+│                                                                │ │
+│                                  delegate:--fixes ←────────────┘ │
+│                                        (on review fail)          │
+│                                                                  │
+│  Legend: ▣ = Human Checkpoint                                   │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## Integration with workflow-auto-resume.md
+
+The auto-chain actions are handled by workflow-auto-resume.md rules.
+
+**CRITICAL:** Use explicit `Skill()` tool invocations to ensure skills are actually invoked:
+
+| Action | Skill Invocation |
+|--------|------------------|
+| AUTO:refactor-brief | Continue to brief capture (inline) |
+| AUTO:polish-implement | Continue to implement phase (inline - orchestrator implements) |
+| AUTO:refactor-validate | Continue to validate phase (inline) |
+| AUTO:refactor-update-docs | Continue to update-docs phase (inline) |
+| AUTO:overhaul-plan | `Skill({ skill: "exarchos:plan", args: "--refactor <state-file>" })` |
+| AUTO:refactor-delegate | `Skill({ skill: "exarchos:delegate", args: "<state-file>" })` |
+| AUTO:refactor-delegate:--fixes | `Skill({ skill: "exarchos:delegate", args: "--fixes <state-file>" })` |
+| AUTO:refactor-review | `Skill({ skill: "exarchos:review", args: "<state-file>" })` |
+| AUTO:refactor-synthesize | `Skill({ skill: "exarchos:synthesize", args: "<feature-name>" })` |
+
+### Example Overhaul Chain
+
+```typescript
+// After brief complete
+Skill({ skill: "exarchos:plan", args: "--refactor ~/.claude/workflow-state/refactor-auth.state.json" })
+
+// After plan complete (invoked by /exarchos:plan skill)
+Skill({ skill: "exarchos:delegate", args: "~/.claude/workflow-state/refactor-auth.state.json" })
+
+// After all tasks complete (invoked by /exarchos:delegate skill)
+Skill({ skill: "exarchos:review", args: "~/.claude/workflow-state/refactor-auth.state.json" })
+
+// After review passes, update-docs runs inline, then:
+Skill({ skill: "exarchos:synthesize", args: "refactor-auth" })
+```

package/skills/refactor/phases/brief.md

@@ -0,0 +1,176 @@
+# Brief Phase
+
+## Purpose
+
+Capture refactoring intent in a structured format without the overhead of a full design document.
+
+## Entry Conditions
+
+- Explore phase complete
+- Track selected (polish or overhaul)
+- Scope assessment available in state
+
+## Brief Structure
+
+The brief captures these required fields:
+
+### 1. Problem Statement
+
+**What's wrong with the current code?** Be specific and measurable.
+
+Good examples:
+- "UserService class has grown to 500 lines with authentication, validation, and persistence mixed together"
+- "The payment module uses 4 different error handling patterns inconsistently"
+- "Test setup duplicated across 12 test files with slight variations"
+
+Bad examples:
+- "Code is messy"
+- "Need to clean things up"
+- "Could be better"
+
+### 2. Goals
+
+**What specific outcomes will this refactor achieve?** Each goal must be verifiable.
+
+Good goals:
+- "Extract validation into UserValidator class (<100 lines)"
+- "Consolidate error handling to single pattern using Result type"
+- "Create shared TestFixtures reducing setup duplication by 80%"
+
+Bad goals:
+- "Improve code quality"
+- "Make it cleaner"
+- "Better organization"
+
+### 3. Approach
+
+**How will you achieve the goals?** High-level strategy.
+
+Polish approach (1-2 sentences):
+- "Extract methods, create new class, update callers"
+
+Overhaul approach (phases):
+- "Phase 1: Create adapter for new pattern alongside old"
+- "Phase 2: Migrate internal callers"
+- "Phase 3: Migrate external callers"
+- "Phase 4: Remove old pattern"
+
+### 4. Affected Areas
+
+**Specific paths that will change.** From explore phase.
+
+### 5. Out of Scope
+
+**What you're explicitly NOT changing.** Prevents scope creep.
+
+Examples:
+- "Not changing the public API"
+- "Not addressing performance issues"
+- "Not updating unrelated tests"
+
+### 6. Success Criteria
+
+**How will you verify the refactor is complete?**
+
+- All existing tests pass
+- New tests added for [specific areas]
+- [Goal 1] achieved (measurable)
+- No new linting errors
+- Documentation updated
+
+### 7. Docs to Update
+
+**Documentation that needs updating.** From explore phase.
+
+## Brief Depth by Track
+
+| Field | Polish | Overhaul |
+|-------|--------|----------|
+| Problem | 1-2 sentences | Paragraph with context |
+| Goals | 1-3 items | 3-5 items |
+| Approach | 1-2 sentences | Phases described |
+| Out of Scope | 1-2 items | 3+ items |
+| Success Criteria | 2-3 items | 4+ items |
+
+## Interactive Capture
+
+When in brief phase, prompt user for each field if not provided:
+
+```
+## Refactor Brief
+
+Based on exploration, preparing brief for <polish|overhaul> track.
+
+**Problem:** <from user or prompt>
+**Goals:** <from user or prompt>
+...
+```
+
+## State Update
+
+**Save brief and advance:**
+
+```
+action: "set", featureId: "refactor-<slug>", updates: {
+  "brief": {
+    "problem": "<problem statement>",
+    "goals": ["<goal 1>", "<goal 2>"],
+    "approach": "<approach description>",
+    "affectedAreas": ["<from explore>"],
+    "outOfScope": ["<exclusion 1>"],
+    "successCriteria": ["<criterion 1>"],
+    "docsToUpdate": ["<from explore>"],
+    "capturedAt": "<ISO8601>"
+  }
+}, phase: "<implement|plan>"
+```
+
+Phase transitions:
+- Polish track -> `implement`
+- Overhaul track -> `plan`
+
+## Validation
+
+Before proceeding, validate brief completeness:
+
+```
+Required fields check:
+[x] Problem: defined
+[x] Goals: at least 1
+[x] Approach: defined
+[x] Affected areas: from explore
+[x] Out of scope: at least 1
+[x] Success criteria: at least 2
+[x] Docs to update: from explore (can be empty)
+```
+
+If validation fails, prompt for missing fields.
+
+## Exit Conditions
+
+- All required fields captured
+- Brief stored in state
+- Phase transitioned appropriately:
+  - Polish -> implement
+  - Overhaul -> plan
+
+## Transition
+
+After brief is captured, auto-continue to next phase:
+
+### Polish Track
+
+1. Update state: `.phase = "implement"`
+2. Output: "Brief captured. Auto-continuing to implementation..."
+3. Continue with implement phase inline (no Skill invocation - orchestrator implements directly)
+
+### Overhaul Track
+
+1. Update state: `.phase = "plan"`
+2. Output: "Brief captured. Auto-continuing to planning..."
+3. Invoke immediately:
+   ```typescript
+   Skill({ skill: "exarchos:plan", args: "--refactor ~/.claude/workflow-state/<feature>.state.json" })
+   ```
+
+This is NOT a human checkpoint - workflow continues autonomously.