@lvlup-sw/exarchos 2.5.0 → 2.6.0

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

@@ -0,0 +1,267 @@
+# 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 → polish-implement → polish-validate → polish-update-docs → CHECKPOINT
+```
+
+### Transition Rules
+
+| From | To | Condition | Auto? |
+|------|-----|-----------|-------|
+| explore | brief | Scope assessed | Yes |
+| brief | polish-implement | Brief captured | Yes |
+| polish-implement | polish-validate | Changes complete | Yes |
+| polish-validate | polish-update-docs | Validation passed | Yes |
+| polish-update-docs | completed | Docs updated | Yes |
+| completed | — | 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:brief
+
+# After brief
+The SessionStart hook determines the next action automatically.
+Returns: AUTO:polish-implement
+
+# After polish-implement
+The SessionStart hook determines the next action automatically.
+Returns: AUTO:polish-validate
+
+# After polish-validate (passed)
+The SessionStart hook determines the next action automatically.
+Returns: AUTO:polish-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 → overhaul-plan → overhaul-plan-review → overhaul-delegate → overhaul-review → overhaul-update-docs → synthesize → CHECKPOINT
+                                                                                    ↑                           │
+                                                                                    └─────── fixes ─────────────┘ (if review fails)
+```
+
+### Transition Rules
+
+| From | To | Condition | Auto? |
+|------|-----|-----------|-------|
+| explore | brief | Scope assessed | Yes |
+| brief | overhaul-plan | Brief captured | Yes |
+| overhaul-plan | overhaul-plan-review | Plan created | Yes |
+| overhaul-plan-review | overhaul-delegate | Plan approved | Yes |
+| overhaul-delegate | overhaul-review | All tasks complete | Yes |
+| overhaul-review (pass) | overhaul-update-docs | Review approved | Yes |
+| overhaul-review (fail) | overhaul-delegate | Fix tasks dispatched | Yes (loop) |
+| overhaul-update-docs | synthesize | Docs updated | Yes |
+| synthesize | completed | Human approves PR | CHECKPOINT |
+
+### Overhaul Auto-Chain Commands
+
+Use the SessionStart hook with the featureId after each phase:
+
+```text
+# After explore
+Returns: AUTO:brief
+
+# After brief
+Returns: AUTO:overhaul-plan
+
+# After overhaul-plan
+Returns: AUTO:overhaul-plan-review
+
+# After overhaul-plan-review (approved)
+Returns: AUTO:overhaul-delegate
+
+# After overhaul-delegate
+Returns: AUTO:overhaul-review
+
+# After overhaul-review (passed)
+Returns: AUTO:overhaul-update-docs
+
+# After overhaul-review (failed)
+Returns: AUTO:delegate:--fixes
+
+# After overhaul-update-docs
+Returns: AUTO: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__plugin_exarchos_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: "overhaul-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 polish-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] ─→ polish-implement ─→ polish-validate │
+│                           │                                         ↓          │
+│                           │                                  polish-update-docs │
+│                           │                                         ↓          │
+│                           │                                   ▣ COMPLETE       │
+│                           │                                                    │
+│                           └─→ [overhaul] ─→ overhaul-plan ─→ overhaul-delegate │
+│                                                                    ↓           │
+│                                                          overhaul-review ───┐  │
+│                                                                    ↓        │  │
+│                                                       overhaul-update-docs  │  │
+│                                                                    ↓        │  │
+│                                                              synthesize     │  │
+│                                                                    ↓        │  │
+│                                                              ▣ PR-MERGE     │  │
+│                                                                             │  │
+│                                          overhaul-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:brief | Continue to brief capture (inline) |
+| AUTO:polish-implement | Continue to implement phase (inline - orchestrator implements) |
+| AUTO:polish-validate | Continue to validate phase (inline) |
+| AUTO:polish-update-docs | Continue to update-docs phase (inline) |
+| AUTO:overhaul-plan | `Skill({ skill: "exarchos:plan", args: "--refactor <state-file>" })` |
+| AUTO:overhaul-plan-review | Plan-review human checkpoint (inline gap analysis) |
+| AUTO:overhaul-delegate | `Skill({ skill: "exarchos:delegate", args: "<state-file>" })` |
+| AUTO:delegate:--fixes | `Skill({ skill: "exarchos:delegate", args: "--fixes <state-file>" })` |
+| AUTO:overhaul-review | `Skill({ skill: "exarchos:review", args: "<state-file>" })` |
+| AUTO: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/generic/refactor/references/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: "<polish-implement|overhaul-plan>"
+```
+
+Phase transitions:
+- Polish track -> `polish-implement`
+- Overhaul track -> `overhaul-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 = "polish-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 = "overhaul-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.

package/skills/generic/refactor/references/phases/explore.md

@@ -0,0 +1,132 @@
+# Explore Phase
+
+## Purpose
+
+Assess refactoring scope to determine appropriate track (polish vs overhaul).
+
+## Entry Conditions
+
+- Refactor workflow initiated via `/exarchos:refactor`
+- Target area identified (file, directory, or module)
+
+## Process
+
+### Step 1: Scope Discovery
+
+Use exploration tools to understand the impact:
+
+```bash
+# Find files that will be affected
+# Use Glob to find files in target area
+# Use Grep to find references to target code
+```
+
+Questions to answer:
+1. How many files will be modified?
+2. How many modules/packages are affected?
+3. Are there cross-module dependencies?
+4. What's the test coverage of affected code?
+
+### Step 2: Concern Analysis
+
+Identify what types of changes are needed:
+
+- [ ] Renaming (variables, functions, files)
+- [ ] Extracting (new functions, classes, modules)
+- [ ] Moving (relocating code between files/modules)
+- [ ] Restructuring (changing architecture)
+- [ ] Cleaning (removing dead code, improving style)
+
+Count distinct concerns - multiple indicates overhaul track.
+
+### Step 3: Test Assessment
+
+Evaluate existing test coverage:
+
+```bash
+# Check for test files covering affected code
+# Review test coverage if available
+```
+
+| Coverage Level | Implication |
+|----------------|-------------|
+| Good (>80%) | Either track viable |
+| Gaps (50-80%) | Overhaul recommended (need test additions) |
+| Poor (<50%) | Overhaul required (significant test work) |
+
+### Step 4: Documentation Check
+
+Identify docs that reference affected code:
+
+- Architecture documentation
+- API documentation
+- README files
+- Inline comments with explanations
+
+Significant doc updates → overhaul track indicator.
+
+## Track Decision Matrix
+
+| Criterion | Polish | Overhaul |
+|-----------|--------|----------|
+| Files affected | <=5 | >5 |
+| Concerns | 1 | >1 |
+| Cross-module | No | Yes |
+| Test gaps | No | Yes |
+| Doc updates | Minor | Significant |
+
+**Rule**: If ANY criterion indicates overhaul, use overhaul track.
+
+## Output
+
+**Save assessment and advance to brief:**
+
+```
+action: "set", featureId: "refactor-<slug>", updates: {
+  "explore": {
+    "filesAffected": <count>,
+    "filesList": ["<path1>", "<path2>"],
+    "modulesAffected": ["<module1>"],
+    "concerns": ["<concern1>", "<concern2>"],
+    "crossModule": <true|false>,
+    "testCoverage": "<good|gaps|none>",
+    "docsImpacted": ["<doc1>"],
+    "recommendedTrack": "<polish|overhaul>",
+    "completedAt": "<ISO8601>"
+  }
+}, phase: "brief"
+```
+
+## Exit Conditions
+
+- Scope assessment complete
+- Track recommendation recorded
+- State updated with findings
+- Ready to proceed to brief phase
+
+## If --explore-only Flag
+
+When `--explore-only` is specified:
+
+1. Complete assessment as normal
+2. Output summary to user
+3. Do NOT transition to brief phase
+4. Keep phase as "explore" in state
+
+```markdown
+## Exploration Summary
+
+**Target:** <target path>
+**Recommended Track:** <polish|overhaul>
+
+### Scope Assessment
+- Files: <count>
+- Modules: <list>
+- Concerns: <list>
+- Cross-module: <yes|no>
+- Test coverage: <good|gaps|none>
+- Docs to update: <list>
+
+### Rationale
+<explanation of track recommendation>
+```

package/skills/generic/refactor/references/phases/overhaul-delegate.md

@@ -0,0 +1,136 @@
+# Overhaul Track: Delegate/Review
+
+## Purpose
+
+Execute large refactors using worktree-isolated subagents with the standard delegation workflow.
+
+## Entry Conditions
+
+- Track is `overhaul`
+- Plan created with tasks defined
+- Tasks defined in plan document
+
+## Phase Flow
+
+```
+delegate → review → [update-docs OR delegate --fixes]
+```
+
+## Delegation Phase
+
+Invoke the delegation skill with explicit Skill tool call:
+
+```typescript
+Skill({ skill: "exarchos:delegate", args: "~/.claude/workflow-state/<feature>.state.json" })
+```
+
+The `/exarchos:delegate` skill handles:
+- Creating worktrees for each task
+- Dispatching subagents via Task tool with `model: "opus"`
+- Using the implementer prompt template
+- Tracking task completion in state
+
+### Refactor-Specific Task Guidance
+
+Each delegated task should emphasize:
+
+1. **Working State**: Code must compile and tests pass after task
+2. **Atomic Changes**: One logical change per commit
+3. **Test-First**: New code should have tests
+
+Example task prompt addition:
+```
+IMPORTANT: After this task, code MUST:
+- Build successfully
+- Pass all tests
+- Not break existing functionality
+```
+
+### Task Dependencies
+
+Refactors often have strict ordering:
+```
+Create new class → Move methods → Update callers → Remove old code
+```
+
+Ensure dependencies are respected in delegation.
+
+## Review Phase
+
+```
+/exarchos:review ~/.claude/workflow-state/<feature>.state.json
+```
+
+### Refactor Review Criteria
+
+When type is "refactor", apply additional scrutiny:
+
+| Criterion | Description |
+|-----------|-------------|
+| Behavior preserved | Same inputs produce same outputs |
+| No regressions | Existing functionality works |
+| Goals achieved | Brief goals are met |
+| Performance OK | No degradation |
+
+See `overhaul-review.md` for detailed criteria.
+
+## State Updates
+
+**After delegation complete:**
+
+```
+action: "set", featureId: "refactor-<slug>", phase: "review"
+```
+
+**After review passes:**
+
+```
+action: "set", featureId: "refactor-<slug>", phase: "update-docs"
+```
+
+**After review fails (dispatch fix tasks, loop back):**
+
+```
+action: "set", featureId: "refactor-<slug>", updates: {
+  "reviews.<id>.status": "failed",
+  "reviews.<id>.findings": ["<issue1>"]
+}
+```
+
+## Auto-Chain Behavior
+
+No human checkpoints in this chain. Automatic progression:
+
+| From | To | Condition |
+|------|-----|-----------|
+| delegate | review | All tasks complete |
+| review | update-docs | Review passes |
+| review | delegate --fixes | Review fails (loop) |
+
+## Transition to Review
+
+After all tasks complete, auto-continue to review:
+
+1. Update state: `.phase = "review"`
+2. Output: "All tasks complete. Auto-continuing to review..."
+3. Invoke immediately:
+   ```typescript
+   Skill({ skill: "exarchos:review", args: "~/.claude/workflow-state/<feature>.state.json" })
+   ```
+
+This is NOT a human checkpoint - workflow continues autonomously.
+
+## Exit Conditions
+
+**Success Path:**
+- All tasks delegated and completed
+- Review passes
+- Ready for update-docs phase
+
+**Failure Path:**
+- Review failures documented
+- Fix tasks dispatched via `--fixes`:
+  ```typescript
+  Skill({ skill: "exarchos:delegate", args: "--fixes ~/.claude/workflow-state/<feature>.state.json" })
+  ```
+- Loop until review passes