@lvlup-sw/exarchos 2.0.1

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

@@ -0,0 +1,215 @@
+# 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 -> Plan -> Delegate -> Review -> Update Docs -> Synthesize
+   |         |        |         |          |            |             |
+   |         |        |         |          |            |             +-- PR creation
+   |         |        |         |          |            +-- Update architecture docs
+   |         |        |         |          +-- Quality review (emphasized)
+   |         |        |         +-- TDD implementation in worktrees
+   |         |        +-- 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:**
+```
+action: "set", featureId: "refactor-<slug>", updates: {
+  "track": "overhaul",
+  "explore": {
+    "startedAt": "<ISO8601>",
+    "scopeAssessment": {
+      "filesAffected": ["<paths>"],
+      "modulesAffected": ["<modules>"],
+      "testCoverage": "good | gaps | none",
+      "recommendedTrack": "overhaul"
+    }
+  }
+}, phase: "brief"
+```
+
+### 2. Brief Phase
+
+Detailed capture of refactor intent (more thorough than polish).
+
+**Save brief and advance:**
+```
+action: "set", featureId: "refactor-<slug>", updates: {
+  "brief": {
+    "problem": "<problem statement>",
+    "goals": ["<goal1>", "<goal2>"],
+    "approach": "<approach>",
+    "affectedAreas": ["<areas>"],
+    "outOfScope": ["<items>"],
+    "successCriteria": ["<criteria>"],
+    "docsToUpdate": ["<doc paths>"]
+  }
+}, phase: "overhaul-plan"
+```
+
+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:**
+```
+action: "set", featureId: "refactor-<slug>", updates: {
+  "artifacts": { "plan": "<plan-file-path>" },
+  "tasks": [{ "id": "001", "title": "...", "status": "pending", "branch": "...", "blockedBy": [] }, ...]
+}, phase: "overhaul-delegate"
+```
+
+> **Note:** There is no `plan-review` phase in the refactor HSM. Overhaul goes directly `overhaul-plan` -> `overhaul-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:**
+```
+action: "set", featureId: "refactor-<slug>", phase: "overhaul-review"
+```
+
+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:**
+```
+action: "set", featureId: "refactor-<slug>", phase: "overhaul-update-docs"
+```
+
+### 6. Update Docs Phase
+
+**Mandatory** - documentation must reflect new architecture.
+
+Verify all documentation links are valid:
+
+```bash
+bash scripts/verify-doc-links.sh --docs-dir docs/
+```
+
+**On Exit 0:** All links valid.
+**On Exit 1:** 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:**
+```
+action: "set", featureId: "refactor-<slug>", updates: {
+  "validation": { "docsUpdated": true },
+  "artifacts": { "updatedDocs": ["<doc paths>"] }
+}, phase: "synthesize"
+```
+
+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 Graphite, 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-delegate -> overhaul-review -> overhaul-update-docs -> synthesize -> completed
+           (auto)   (auto)          (auto)               (auto)             (auto)                  (auto)        [HUMAN]
+```
+
+**Next actions:**
+- `AUTO:refactor-brief` after explore
+- `AUTO:overhaul-plan` after brief
+- `AUTO:refactor-delegate` after overhaul-plan
+- `AUTO:refactor-review` after overhaul-delegate
+- `AUTO:refactor-update-docs` after overhaul-review
+- `AUTO:refactor-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

package/skills/refactor/references/polish-track.md

@@ -0,0 +1,170 @@
+---
+name: polish-track
+---
+
+# Polish Track — Detailed Phase Guide
+
+## Purpose
+
+Fast path for small, contained refactors. Single session, minimal ceremony. Orchestrator may write implementation code directly (exception to orchestrator constraints).
+
+## Phases
+
+```
+Explore -> Brief -> Implement -> Validate -> Update Docs -> Complete
+   |         |          |           |             |
+   |         |          |           |             +-- Update affected documentation
+   |         |          |           +-- Run tests, verify goals met
+   |         |          +-- Direct implementation (no worktree)
+   |         +-- Capture goals and approach in state
+   +-- Quick scope assessment, confirm polish-appropriate
+```
+
+### 1. Explore Phase
+
+Use `@skills/refactor/references/explore-checklist.md` to assess:
+- Current code structure
+- Files/modules affected (must be <=5 for polish)
+- Test coverage of affected areas
+- Documentation that needs updates
+- Confirm polish is appropriate
+
+**Initialize workflow:**
+```
+action: "init", featureId: "refactor-<slug>", workflowType: "refactor"
+```
+
+**Set track and scope assessment:**
+```
+action: "set", featureId: "refactor-<slug>", updates: {
+  "track": "polish",
+  "explore": {
+    "startedAt": "<ISO8601>",
+    "scopeAssessment": {
+      "filesAffected": ["<paths>"],
+      "modulesAffected": ["<modules>"],
+      "testCoverage": "good | gaps | none",
+      "recommendedTrack": "polish"
+    }
+  }
+}, phase: "brief"
+```
+
+### 2. Brief Phase
+
+Capture refactor intent and approach in state (not separate document).
+
+Use `@skills/refactor/references/brief-template.md` to structure:
+- Problem statement (2-3 sentences)
+- Specific goals (bulleted list)
+- High-level approach
+- Out of scope items
+- Success criteria
+- Docs to update
+
+**Save brief and advance:**
+```
+action: "set", featureId: "refactor-<slug>", updates: {
+  "brief": {
+    "problem": "<problem statement>",
+    "goals": ["<goal1>", "<goal2>"],
+    "approach": "<approach>",
+    "affectedAreas": ["<areas>"],
+    "outOfScope": ["<items>"],
+    "successCriteria": ["<criteria>"],
+    "docsToUpdate": ["<doc paths>"]
+  }
+}, phase: "polish-implement"
+```
+
+### 3. Implement Phase
+
+**Orchestrator may write code directly** (polish track exception).
+
+Constraints:
+- Follow TDD (write/update test first if behavior changes)
+- Commit after each logical change
+- Stop if scope expands beyond brief
+
+When done, commit via Graphite:
+```typescript
+mcp__graphite__run_gt_cmd({ args: ["create", "-m", "refactor: <description>"], cwd: "<repo-root>" })
+```
+
+**Advance to validation:**
+```
+action: "set", featureId: "refactor-<slug>", phase: "polish-validate"
+```
+
+### 4. Validate Phase
+
+Verify scope hasn't expanded beyond polish limits:
+
+```bash
+bash scripts/check-polish-scope.sh --repo-root <path>
+```
+
+**On Exit 0:** Scope OK — stay on polish track.
+**On Exit 1:** Scope expanded — switch to overhaul track.
+
+Then run the refactor validation:
+
+```bash
+bash scripts/validate-refactor.sh --repo-root <path>
+```
+
+**On Exit 0:** All checks pass (tests, lint, typecheck).
+**On Exit 1:** One or more checks failed — fix before proceeding.
+
+**Save validation results and advance:**
+```
+action: "set", featureId: "refactor-<slug>", updates: {
+  "validation": { "testsPass": true, "goalsVerified": ["<verified goals>"] }
+}, phase: "polish-update-docs"
+```
+
+### 5. Update Docs Phase
+
+**Mandatory** - documentation must reflect new architecture.
+
+Use `@skills/refactor/references/doc-update-checklist.md` to update:
+- Architecture docs if structure changed
+- API docs if interfaces changed
+- README if setup/usage changed
+- Inline comments if complex logic moved
+
+If `docsToUpdate` is empty, verify no docs need updating.
+
+**Mark docs updated and complete:**
+```
+action: "set", featureId: "refactor-<slug>", updates: {
+  "validation": { "docsUpdated": true },
+  "artifacts": { "updatedDocs": ["<doc paths>"] }
+}, phase: "completed"
+```
+
+> **Note:** The HSM transitions directly from `polish-update-docs` to `completed`. There is no `synthesize` phase for polish track.
+
+## Auto-Chain
+
+```
+explore -> brief -> polish-implement -> polish-validate -> polish-update-docs -> completed
+           (auto)   (auto)              (auto)             (auto)                (auto)
+```
+
+**Next actions:**
+- `AUTO:refactor-brief` after explore
+- `AUTO:polish-implement` after brief
+- `AUTO:refactor-validate` after polish-implement
+- `AUTO:refactor-update-docs` after polish-validate
+- `AUTO:completed` after polish-update-docs
+
+## Completion Criteria
+
+- [ ] Scope assessment completed (<=5 files)
+- [ ] Brief goals captured
+- [ ] Implementation complete
+- [ ] All tests pass
+- [ ] Each goal verified
+- [ ] Documentation updated
+- [ ] User confirmed completion

package/skills/shared/prompts/context-reading.md

@@ -0,0 +1,58 @@
+# Context Reading Instructions
+
+## For Subagents
+
+You are a subagent with isolated context. Read your own context from files rather than relying on information passed inline.
+
+## Reading Task Details
+
+If given a state file path, read task details using MCP tools:
+
+**Get your task:**
+
+```
+action: "get", featureId: "<feature-id>", query: ".tasks[] | select(.id == \"<task-id>\")"
+```
+
+**Get plan path:**
+
+```
+action: "get", featureId: "<feature-id>", query: ".artifacts.plan"
+```
+
+Then read the specific task section:
+
+```bash
+~/.claude/scripts/extract-task.sh <plan-path> <task-id>
+```
+
+## Reading for Review
+
+If reviewing, read the diff instead of full files:
+
+```bash
+~/.claude/scripts/review-diff.sh <worktree-path> main
+```
+
+## Reading Design Context
+
+If you need design context:
+
+**Get design path from state:**
+
+```
+action: "get", featureId: "<feature-id>", query: ".artifacts.design"
+```
+
+Then read the design file:
+
+```bash
+Read({ file_path: "<design-path>" })
+```
+
+## Best Practices
+
+1. **Read on demand** - Only read files when you need the information
+2. **Use diffs** - Prefer diffs over full file contents for reviews
+3. **Extract sections** - Use extract-task.sh for single task context
+4. **Trust state file** - The state file is the source of truth for workflow state

package/skills/shared/prompts/report-format.md

@@ -0,0 +1,54 @@
+# Standard Report Format
+
+## Task Completion Report
+
+When reporting task completion, use this format:
+
+```markdown
+## Task Complete: [Task ID]
+
+### Files Modified
+- `path/to/file.ts` - [Brief change description]
+- `path/to/test.ts` - [Tests added]
+
+### Tests
+- **Added:** [Count] new tests
+- **Status:** PASS / FAIL
+- **Coverage:** [X]% (if available)
+
+### TDD Verification
+- [x] Test failed first (RED confirmed)
+- [x] Test passes after implementation (GREEN confirmed)
+- [x] No extra code beyond requirements
+
+### Issues (if any)
+- [Issue description and resolution]
+
+### Status
+**COMPLETE** / **BLOCKED** (reason)
+```
+
+## Review Report
+
+When reporting review results:
+
+```markdown
+## Review: [Type] - [Task ID]
+
+### Verdict
+**PASS** / **FAIL** / **NEEDS_FIXES**
+
+### Findings
+
+#### HIGH Priority
+1. [Issue] - File: `path:line` - Fix: [Required action]
+
+#### MEDIUM Priority
+1. [Issue] - File: `path:line` - Suggestion: [Recommended action]
+
+#### LOW Priority
+1. [Observation] - File: `path:line`
+
+### Summary
+[1-2 sentence summary of review results]
+```

package/skills/shared/prompts/tdd-requirements.md

@@ -0,0 +1,39 @@
+# TDD Requirements
+
+## The Iron Law
+
+> **NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST**
+
+## Process
+
+1. **RED**: Write a failing test
+   - Test must fail for the expected reason
+   - Run tests to confirm failure
+   - Verify the failure message matches expectations
+
+2. **GREEN**: Write minimum code to pass
+   - Only implement what's needed to pass the test
+   - No extra features or "nice to have" code
+   - Run tests to confirm passing
+
+3. **REFACTOR**: Clean up (optional)
+   - Improve code quality while keeping tests green
+   - Apply SOLID principles where beneficial
+   - Run tests after each refactor
+
+## Test Naming
+
+Follow: `MethodName_Scenario_ExpectedOutcome`
+
+Examples:
+- `CreateUser_ValidInput_ReturnsUserId`
+- `CreateUser_EmptyEmail_ThrowsValidationError`
+- `GetUser_NonExistentId_ReturnsNull`
+
+## Verification
+
+Before marking complete:
+- [ ] Test failed first (witnessed the RED)
+- [ ] Test passes after implementation (confirmed GREEN)
+- [ ] No extra code beyond test requirements
+- [ ] All related tests still pass