@lvlup-sw/exarchos 2.4.3 → 2.6.0

package/skills/cursor/refactor/references/brief-template.md

@@ -0,0 +1,81 @@
+# Refactor Brief Template
+
+## Purpose
+
+The brief captures refactor intent without the overhead of a full design document. Store in workflow state, not as a separate file.
+
+## Brief Fields
+
+### Problem (Required)
+What's wrong with the current code? Be specific.
+
+**Polish example:** "The UserService class has grown to 500 lines with mixed responsibilities"
+
+**Overhaul example:** "The authentication module uses callbacks throughout, making error handling inconsistent and testing difficult"
+
+### Goals (Required)
+List specific, measurable goals. Each goal should be verifiable.
+
+**Good goals:**
+- Extract validation logic into separate UserValidator class
+- Convert callback-based auth to async/await pattern
+- Reduce cyclomatic complexity of processOrder from 15 to <5
+
+**Bad goals:**
+- Make the code better
+- Clean things up
+- Improve performance (without metrics)
+
+### Approach (Required)
+High-level description of how you'll achieve the goals.
+
+**Polish approach:** "Extract validation methods to new class, update callers, run tests"
+
+**Overhaul approach:** "Phase 1: Create async wrapper around existing callbacks. Phase 2: Convert internal methods to async. Phase 3: Update public API. Phase 4: Remove callback support."
+
+### Affected Areas (Required)
+List specific paths/modules that will change.
+
+### Out of Scope (Required)
+Explicitly state what you're NOT changing. Prevents scope creep.
+
+### Success Criteria (Required)
+How will you know the refactor is complete?
+
+- All existing tests pass
+- [Specific goal] is achieved
+- [Metric] is improved by [amount]
+- Documentation reflects new structure
+
+### Docs to Update (Required)
+List documentation files that need updating after refactor.
+
+## 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": ["<area 1>", "<area 2>"],
+    "outOfScope": ["<exclusion 1>", "<exclusion 2>"],
+    "successCriteria": ["<criterion 1>", "<criterion 2>"],
+    "docsToUpdate": ["<doc 1>", "<doc 2>"]
+  }
+}, phase: "polish-implement | overhaul-plan"
+```
+
+## Polish vs Overhaul Brief Depth
+
+| Field | Polish | Overhaul |
+|-------|--------|----------|
+| Problem | 1-2 sentences | Paragraph with context |
+| Goals | 1-3 items | 3-5 items |
+| Approach | 1 sentence | Paragraph with phases |
+| Affected Areas | File paths | Module/package paths |
+| Out of Scope | 1-2 items | 3+ items |
+| Success Criteria | 2-3 items | 4+ items |
+| Docs to Update | 0-2 files | 2+ files |

package/skills/cursor/refactor/references/doc-update-checklist.md

@@ -0,0 +1,113 @@
+# Documentation Update Checklist
+
+## Purpose
+
+Every refactor MUST update affected documentation. This is not optional. Code without accurate documentation creates technical debt.
+
+## Before Starting
+
+1. Review `docsToUpdate` list from brief
+2. Read each document to understand current state
+3. Note specific sections that need changes
+
+## Documentation Types
+
+### Architecture Documentation
+
+**When to update:** Structure, module organization, or dependencies changed
+
+**What to check:**
+- [ ] Component diagrams accurate
+- [ ] Module descriptions current
+- [ ] Dependency arrows correct
+- [ ] Technology choices documented
+
+### API Documentation
+
+**When to update:** Public interfaces, method signatures, or behavior changed
+
+**What to check:**
+- [ ] Function/method signatures match code
+- [ ] Parameter descriptions accurate
+- [ ] Return value documentation correct
+- [ ] Examples still work
+- [ ] Error cases documented
+
+### README Files
+
+**When to update:** Setup, usage, or configuration changed
+
+**What to check:**
+- [ ] Installation steps current
+- [ ] Configuration examples valid
+- [ ] Usage examples work
+- [ ] Prerequisites listed
+
+### Inline Comments
+
+**When to update:** Complex logic moved or rewritten
+
+**What to check:**
+- [ ] Comments explain "why" not "what"
+- [ ] No stale comments referring to old code
+- [ ] Complex algorithms documented
+- [ ] TODO items addressed or updated
+
+## Verification
+
+After updating documentation, run automated link verification:
+
+```typescript
+exarchos_orchestrate({
+  action: "verify_doc_links",
+  docsDir: "docs/"
+})
+```
+
+**On `passed: true`:** All links valid.
+**On `passed: false`:** Broken links found — fix before proceeding.
+
+Additionally:
+
+1. [ ] Read each updated doc fresh
+2. [ ] Verify code references are accurate
+3. [ ] Test any code examples
+
+## State Update
+
+**Record updated docs:**
+
+```
+action: "set", featureId: "refactor-<slug>", updates: {
+  "validation.docsUpdated": true,
+  "artifacts.updatedDocs": ["<doc1>", "<doc2>"]
+}
+```
+
+## If No Docs Need Updating
+
+If `docsToUpdate` is empty, verify this is correct:
+
+1. Review affected areas
+2. Confirm no public interfaces changed
+3. Confirm no architectural changes made
+4. Document verification in state:
+
+**Confirm no docs needed:**
+
+```
+action: "set", featureId: "refactor-<slug>", updates: {
+  "validation.docsUpdated": true,
+  "artifacts.updatedDocs": []
+}
+```
+
+## Common Mistakes
+
+| Mistake | Correction |
+|---------|------------|
+| "Docs don't need updating" | Always verify; code changes usually need doc updates |
+| Update code examples only | Also update prose descriptions |
+| Skip architecture docs | These are often most important |
+| Leave TODO comments | Address or remove them |
+| Assume readers know context | Document the "why" |

package/skills/cursor/refactor/references/explore-checklist.md

@@ -0,0 +1,79 @@
+---
+name: explore-checklist
+---
+
+# Refactor Exploration Checklist
+
+## Scope Assessment
+
+### Files Analysis
+- [ ] List all files that will be modified
+- [ ] Count total files affected
+- [ ] Identify file types (source, test, config, docs)
+
+### Module Analysis
+- [ ] List modules/packages affected
+- [ ] Identify cross-module dependencies
+- [ ] Check for circular dependencies that might complicate refactor
+
+### Test Coverage
+- [ ] Check test coverage of affected code
+- [ ] Identify test gaps
+- [ ] Note tests that will need updating
+
+### Documentation Impact
+- [ ] List documentation that references affected code
+- [ ] Identify architecture docs that may need updates
+- [ ] Check for API documentation impacts
+
+## Track Selection
+
+### Polish Track Indicators (all must be true)
+- [ ] <=5 files affected
+- [ ] Single concern being addressed
+- [ ] No cross-module changes
+- [ ] Good test coverage exists
+- [ ] Documentation changes are minor
+
+### Overhaul Track Indicators (any one triggers)
+- [ ] >5 files affected
+- [ ] Multiple concerns being addressed
+- [ ] Cross-module changes required
+- [ ] Test coverage gaps exist
+- [ ] Architectural documentation needs updating
+
+## Deterministic Scope Assessment
+
+Run the scope assessment script for a deterministic track recommendation:
+
+```typescript
+exarchos_orchestrate({
+  action: "assess_refactor_scope",
+  files: ["<file1>", "<file2>", "..."]
+})
+// or
+exarchos_orchestrate({
+  action: "assess_refactor_scope",
+  stateFile: "<path>"
+})
+```
+
+**On `passed: true`:** Polish recommended — scope is contained (<=5 files, single module).
+**On `passed: false`:** Overhaul recommended — scope exceeds polish limits (>5 files or cross-module).
+
+## Output
+
+**Save assessment and advance to brief:**
+
+```
+action: "set", featureId: "refactor-<slug>", updates: {
+  "explore.scopeAssessment": {
+    "filesAffected": ["<list>"],
+    "modulesAffected": ["<list>"],
+    "testCoverage": "good | gaps | none",
+    "recommendedTrack": "polish | overhaul"
+  },
+  "track": "<selected-track>",
+  "explore.completedAt": "<ISO8601>"
+}, phase: "brief"
+```

package/skills/cursor/refactor/references/overhaul-track.md

@@ -0,0 +1,194 @@
+# Overhaul Track — Detailed Phase Guide
+
+## Purpose
+
+Rigorous path for architectural changes, migrations, and multi-file restructuring. Uses full delegation model with worktree isolation.
+
+## Phases
+
+```
+explore -> brief -> overhaul-plan -> overhaul-plan-review -> overhaul-delegate -> overhaul-review -> overhaul-update-docs -> synthesize -> completed
+   |         |           |                  |                       |                  |                    |                     |
+   |         |           |                  |                       |                  |                    |                     +-- PR creation
+   |         |           |                  |                       |                  |                    +-- Update architecture docs
+   |         |           |                  |                       |                  +-- Quality review (emphasized)
+   |         |           |                  |                       +-- TDD implementation in worktrees
+   |         |           |                  +-- Human checkpoint: verify plan coverage
+   |         |           +-- Extract tasks from brief
+   |         +-- Detailed goals, approach, affected areas
+   +-- Thorough scope assessment, identify affected systems
+```
+
+### 1. Explore Phase
+
+Thorough scope assessment using `@skills/refactor/references/explore-checklist.md`:
+- Read affected code to understand current structure
+- Identify ALL files/modules that will change
+- Assess test coverage of affected areas
+- Identify documentation that will need updates
+- Map dependencies and impact
+
+**Initialize workflow:**
+```
+action: "init", featureId: "refactor-<slug>", workflowType: "refactor"
+```
+
+**Set track and scope assessment, then transition to brief:**
+
+Before calling `set`, query the required guard shape:
+```
+exarchos_workflow({ action: "describe", playbook: "refactor" })
+```
+Use the returned guard requirements for the `explore → brief` transition to construct your `set` call with the correct fields.
+
+### 2. Brief Phase
+
+Detailed capture of refactor intent (more thorough than polish).
+
+**Save brief and advance to overhaul-plan:**
+
+Call `exarchos_workflow({ action: "describe", playbook: "refactor" })` for the `brief → overhaul-plan` guard requirements, then `set` the required fields and phase.
+
+Then auto-invoke plan:
+```typescript
+Skill({ skill: "exarchos:plan", args: "--refactor ~/.claude/workflow-state/<feature>.state.json" })
+```
+
+### 3. Plan Phase
+
+Invoke `/exarchos:plan` skill with explicit Skill tool call:
+
+```typescript
+Skill({ skill: "exarchos:plan", args: "--refactor ~/.claude/workflow-state/<feature>.state.json" })
+```
+
+The `/exarchos:plan` skill:
+- Extracts tasks from the brief
+- Focuses on incremental, testable changes
+- Each task leaves code in working state
+- Dependency order matters more for refactors
+
+**Save plan and advance to plan-review:**
+
+Call `exarchos_workflow({ action: "describe", playbook: "refactor" })` for the `overhaul-plan → overhaul-plan-review` guard requirements, then `set` the required fields (plan artifact, tasks array) and phase.
+
+**Human checkpoint:** Plan-review verifies plan coverage against the brief before committing to delegation. The orchestrator compares design sections against planned tasks.
+- Gaps found → set `.planReview.gaps`, auto-loop back to `/exarchos:plan --revise`
+- Approved → set `.planReview.approved = true`, auto-invoke delegate
+
+Then auto-invoke delegate:
+```typescript
+Skill({ skill: "exarchos:delegate", args: "~/.claude/workflow-state/<feature>.state.json" })
+```
+
+### 4. Delegate Phase
+
+Invoke `/exarchos:delegate` skill for TDD implementation in worktrees:
+
+```typescript
+Skill({ skill: "exarchos:delegate", args: "~/.claude/workflow-state/<feature>.state.json" })
+```
+
+The `/exarchos:delegate` skill:
+- Creates worktrees for each task
+- Dispatches subagents via Task tool with `model: "opus"`
+- Uses implementer prompt template for full context
+- Parallel execution where dependencies allow
+- Tracks progress in state file
+
+**Advance to review:**
+
+Call `exarchos_workflow({ action: "describe", playbook: "refactor" })` for the `overhaul-delegate → overhaul-review` guard requirements, then `set` the phase.
+
+Then auto-invoke review:
+```typescript
+Skill({ skill: "exarchos:review", args: "~/.claude/workflow-state/<feature>.state.json" })
+```
+
+### 5. Review Phase
+
+Invoke `/exarchos:review` skill with emphasis on quality:
+
+```typescript
+Skill({ skill: "exarchos:review", args: "~/.claude/workflow-state/<feature>.state.json" })
+```
+
+The `/exarchos:review` skill:
+- Quality review is emphasized for refactors
+- Refactors are high regression risk
+- Verifies structure matches brief goals
+
+**Advance to doc updates:**
+
+Call `exarchos_workflow({ action: "describe", playbook: "refactor" })` for the `overhaul-review → overhaul-update-docs` guard requirements, then `set` the phase.
+
+### 6. Update Docs Phase
+
+**Mandatory** - documentation must reflect new architecture.
+
+Verify all documentation links are valid:
+
+```typescript
+exarchos_orchestrate({
+  action: "verify_doc_links",
+  docsDir: "docs/"
+})
+```
+
+**On `passed: true`:** All links valid.
+**On `passed: false`:** Broken links found — fix before proceeding.
+
+For overhaul, typically includes:
+- Architecture documentation updates
+- API documentation changes
+- Migration guides if public interfaces changed
+- Updated diagrams
+
+**Mark docs updated and advance to synthesize:**
+
+Call `exarchos_workflow({ action: "describe", playbook: "refactor" })` for the `overhaul-update-docs → synthesize` guard requirements, then `set` the required fields (validation, artifacts) and phase.
+
+Then auto-invoke synthesize:
+```typescript
+Skill({ skill: "exarchos:synthesize", args: "<feature-name>" })
+```
+
+### 7. Synthesize Phase
+
+Invoke `/exarchos:synthesize` skill:
+
+```typescript
+Skill({ skill: "exarchos:synthesize", args: "<feature-name>" })
+```
+
+Creates PR via `gh pr create`, updates description via `gh pr edit`. **Human checkpoint:** Confirm merge.
+
+> Or use GitHub MCP `update_pull_request` if available.
+
+## Auto-Chain
+
+```
+explore -> brief -> overhaul-plan -> overhaul-plan-review -> overhaul-delegate -> overhaul-review -> overhaul-update-docs -> synthesize -> completed
+           (auto)   (auto)          [HUMAN]                  (auto)               (auto)             (auto)                  (auto)        [HUMAN]
+```
+
+**Next actions:**
+- `AUTO:brief` after explore
+- `AUTO:overhaul-plan` after brief
+- `AUTO:overhaul-plan-review` after overhaul-plan
+- `WAIT:human-checkpoint:overhaul-plan-review` at plan-review
+- `AUTO:overhaul-delegate` after overhaul-plan-review (approved)
+- `AUTO:overhaul-review` after overhaul-delegate
+- `AUTO:overhaul-update-docs` after overhaul-review
+- `AUTO:synthesize` after overhaul-update-docs
+- `WAIT:human-checkpoint:synthesize` after synthesize
+
+## Completion Criteria
+
+- [ ] Full exploration done
+- [ ] Detailed brief captured
+- [ ] Plan created
+- [ ] All tasks delegated and complete
+- [ ] Quality review passed
+- [ ] Documentation updated
+- [ ] PR merged