@lvlup-sw/exarchos 2.0.1

package/commands/refactor.md

@@ -0,0 +1,139 @@
+---
+description: Start refactor workflow for code improvement
+---
+
+# Refactor
+
+Start refactor workflow for: "$ARGUMENTS"
+
+## Workflow Overview
+
+Refactor workflows are **exploration-first**: understand scope before committing to a track.
+
+```
+/exarchos:refactor → Explore → Brief → [Implement|Plan] → Validate → Update Docs → [CONFIRM]
+                                    │
+                   ┌────────────────┼────────────────┐
+                   │                                 │
+              --polish                          (default)
+           (direct, ≤5 files)               (full delegation)
+```
+
+**Single human checkpoint:** Completion confirmation (polish) or merge confirmation (overhaul).
+
+## Skill Reference
+
+Follow the refactor skill: `@skills/refactor/SKILL.md`
+
+## Command Variants
+
+### Default: Overhaul Track
+
+```bash
+/refactor "Restructure the authentication module into separate concerns"
+```
+
+Full delegation workflow with worktree isolation.
+
+### Fast Path: Polish Track
+
+```bash
+/refactor --polish "Extract validation logic into utility functions"
+```
+
+Direct implementation, <=5 files, single concern.
+
+### Explore First
+
+```bash
+/refactor --explore "Not sure of scope, assess first"
+```
+
+Explore to assess scope, then decide track.
+
+### Mid-Workflow: Switch to Overhaul
+
+```bash
+/refactor --switch-overhaul
+```
+
+Switch from polish to overhaul if scope expands.
+
+## Process
+
+### Step 1: Initialize State
+
+Initialize workflow state using `mcp__exarchos__exarchos_workflow` with `action: "init"`, featureId `refactor-<slug>`, and workflowType `refactor`.
+
+### Step 2: Explore
+
+Assess scope using `@skills/refactor/references/explore-checklist.md`:
+
+1. **What code is affected?**
+2. **How many files/modules?**
+3. **What is the test coverage?**
+4. **What documentation needs updating?**
+
+Select track based on scope assessment.
+
+### Step 3: Execute Track
+
+**Polish Track:**
+- Brief (capture goals in state)
+- Implement directly (orchestrator may write code)
+- Validate (tests pass, goals met)
+- Update docs
+- Completion checkpoint
+
+**Overhaul Track:**
+- Brief (detailed goals and approach)
+- Plan (extract tasks via `/exarchos:plan`)
+- Delegate (TDD in worktrees via `/exarchos:delegate`)
+- Review (quality review via `/exarchos:review`)
+- Update docs
+- Synthesize (PR via `/exarchos:synthesize`)
+- Merge checkpoint
+
+## Arguments
+
+| Argument | Effect |
+|----------|--------|
+| `<description>` | Refactor description for scope context |
+| `--polish` | Select polish track (<=5 files, single concern) |
+| `--explore` | Explore scope before selecting track |
+| `--switch-overhaul` | Switch from polish to overhaul mid-workflow |
+
+## State Management
+
+Refactor workflows use extended state schema. See `@skills/refactor/SKILL.md` for full schema.
+
+Key fields:
+- `workflowType: "refactor"`
+- `track: "polish" | "overhaul"`
+- `explore: { scopeAssessment }`
+- `brief: { problem, goals, approach, successCriteria }`
+- `validation: { testsPass, goalsVerified, docsUpdated }`
+
+## Auto-Chain Behavior
+
+Both tracks auto-chain through phases with ONE human checkpoint.
+
+**Polish:**
+```
+explore → brief → implement → validate → update-docs → [HUMAN: complete]
+          (auto)   (auto)      (auto)     (auto)
+```
+
+**Overhaul:**
+```
+explore → brief → plan → delegate → review → update-docs → synthesize → [HUMAN: merge]
+          (auto)  (auto)  (auto)    (auto)   (auto)        (auto)
+```
+
+## Resume Support
+
+Refactor workflows resume like other workflows:
+
+```bash
+/exarchos:resume ~/.claude/workflow-state/refactor-<slug>.state.json
+```

package/commands/reload.md

@@ -0,0 +1,37 @@
+---
+name: reload
+description: "Manually trigger context reload to recover from context degradation."
+---
+
+# Reload Context
+
+Manually trigger a context reload to recover from context degradation.
+
+## Process
+
+1. **Checkpoint current state** — Save workflow context to disk
+2. **Clear session** — Type `/clear` to start fresh with pre-computed context
+
+## Steps
+
+### Step 1: Save Context Checkpoint
+
+The PreCompact hook will fire, saving:
+- Workflow checkpoint (phase, tasks, artifacts)
+- Pre-assembled context document (structured Markdown summary)
+
+This happens automatically when you type `/clear`.
+
+### Step 2: Clear and Reload
+
+Type `/clear` in the chat. The SessionStart hook will:
+1. Detect the saved checkpoint
+2. Inject the pre-computed context document
+3. Resume with full workflow awareness
+
+## When to Use
+
+- Context feels degraded (agent forgets workflow state, repeats questions)
+- After long sessions with many tool calls
+- Before complex operations that need full context
+- The auto-compact threshold (95%) will trigger this automatically, but you can manually trigger it anytime

package/commands/resume.md

@@ -0,0 +1,130 @@
+---
+description: Resume workflow from saved state file
+---
+
+# Resume
+
+Resume workflow from state file: "$ARGUMENTS"
+
+## Purpose
+
+Restore workflow context after:
+- Starting a new Claude Code session
+- Context auto-summarization
+- Explicit checkpoint
+
+## Skill Reference
+
+- Workflow state: `@skills/workflow-state/SKILL.md`
+
+## Process
+
+### Step 1: Locate State File
+
+If no argument provided, the SessionStart hook automatically discovers active workflows on session start. To manually locate state files, check the state directory:
+
+```bash
+ls ~/.claude/workflow-state/*.state.json
+```
+
+### Step 2: Reconcile State
+
+The SessionStart hook automatically verifies state matches git reality on resume. Review reported discrepancies (missing worktrees, branches).
+
+### Step 3: Load Context Summary
+
+The SessionStart hook provides workflow context automatically. Read the state file using `mcp__exarchos__exarchos_workflow` with `action: "get"` and the featureId for detailed state.
+
+### Step 4: Display Context
+
+Output the summary to restore orchestrator context:
+
+```markdown
+## Workflow Context Restored
+
+**Feature:** <feature-id>
+**Phase:** <phase>
+**Last Updated:** <timestamp>
+
+### Artifacts
+- Design: `<path or "not created">`
+- Plan: `<path or "not created">`
+- PR: <url or "not created">
+
+### Task Progress
+- Completed: X / Y
+
+### Pending Tasks
+- [status] ID: Title
+- ...
+
+### Active Worktrees
+- .worktrees/xxx (branch-name)
+- ...
+
+### Next Action
+<suggested command based on phase>
+```
+
+### Step 5: Prompt for Action
+
+After displaying context, ask:
+
+> Ready to continue. Run the suggested next action, or specify what you'd like to do.
+
+## Usage Examples
+
+### Resume Specific Workflow
+
+```
+/exarchos:resume ~/.claude/workflow-state/user-authentication.state.json
+```
+
+### List and Choose
+
+```
+/exarchos:resume
+```
+
+Lists available workflows, then:
+
+```
+/exarchos:resume ~/.claude/workflow-state/<chosen-feature>.state.json
+```
+
+## Context Efficiency
+
+The resume process is designed to be context-efficient:
+
+1. **Minimal output** - Only essential state displayed
+2. **File references** - Full details remain in files, not conversation
+3. **Action-oriented** - Immediately suggests next step
+4. **No history replay** - Fresh start with current state
+
+## Error Handling
+
+### State File Not Found
+
+```
+ERROR: State file not found: <path>
+
+Available workflows:
+  <list from workflow state directory>
+```
+
+### Reconciliation Issues
+
+```
+WARNING: State discrepancies found
+
+Missing worktrees:
+  - .worktrees/001-types
+
+Missing branches:
+  - feature/001-types
+
+Options:
+1. Fix discrepancies manually
+2. Update state to match reality
+3. Continue anyway (may cause issues)
+```

package/commands/review.md

@@ -0,0 +1,51 @@
+---
+description: Run two-stage review (spec compliance + code quality)
+---
+
+# Review
+
+Review implementation for: "$ARGUMENTS"
+
+## Workflow Position
+
+```
+/exarchos:ideate → [CONFIRM] → /exarchos:plan → /exarchos:delegate → /exarchos:review → /exarchos:synthesize → [CONFIRM] → merge
+                                                                        ▲▲▲▲▲▲▲▲▲▲▲▲▲▲
+                            ON BLOCKED ──────────────────────────────────────┘
+                            ON FAIL → /exarchos:delegate --fixes (auto)
+```
+
+Review runs AFTER delegation completes -- reviews the Graphite stack diff.
+
+## Skill References
+
+- **Stage 1 (spec compliance):** `@skills/spec-review/SKILL.md`
+- **Stage 2 (code quality):** `@skills/quality-review/SKILL.md`
+
+Reviews MUST be dispatched to subagents (not run inline). Use the Graphite stack diff to reduce context by 80-90%:
+
+```bash
+TARGET_BRANCH=$(gt parent 2>/dev/null || echo "main")
+gt diff $TARGET_BRANCH > /tmp/stack-diff.patch
+```
+
+## Idempotency
+
+Before reviewing, check review status in state:
+1. Skip tasks where both reviews already passed
+2. Only review pending tasks
+3. If all reviews passed, skip to auto-chain
+
+## Output
+
+Track the feature name and plan path as `$FEATURE_NAME` and `$PLAN_PATH`.
+
+## Auto-Chain
+
+All transitions happen **immediately** without user confirmation:
+
+- **ON PASS:** Update state `.phase = "synthesize"`, invoke `Skill({ skill: "exarchos:synthesize", args: "$FEATURE_NAME" })`
+- **ON FAIL:** Update state with failed review details, invoke `Skill({ skill: "exarchos:delegate", args: "--fixes $PLAN_PATH" })`
+- **ON BLOCKED:** Update state `.phase = "blocked"`, invoke `Skill({ skill: "exarchos:ideate", args: "--redesign $FEATURE_NAME" })`
+
+**No pause for user input** -- this is not a human checkpoint.

package/commands/sync-schemas.md

@@ -0,0 +1,74 @@
+---
+description: Synchronize TypeScript types from backend OpenAPI specs
+---
+
+# Sync Schemas
+
+Regenerate TypeScript types and Zod schemas from backend OpenAPI specifications.
+
+## Skill Reference
+
+Follow the schema sync skill: `@skills/sync-schemas/SKILL.md`
+
+## Quick Process
+
+### Step 1: Detect Monorepo Root
+
+```bash
+MONOREPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null)
+
+# Handle worktree case
+if [[ "$(pwd)" == *".worktrees"* ]]; then
+  MONOREPO_ROOT=$(pwd)
+fi
+
+cd "$MONOREPO_ROOT"
+```
+
+### Step 2: Run Sync
+
+```bash
+npm run sync:schemas
+```
+
+### Step 3: Verify
+
+```bash
+npm run typecheck
+```
+
+### Step 4: Report
+
+```markdown
+## Schema Sync Complete
+
+Generated files:
+- `apps/aegis-api/openapi.json`
+- `shared/types/src/generated/aegis.ts`
+- `shared/validation/src/generated/aegis.zod.ts`
+- `apps/ares-elite-web/src/api/generated/aegis.schemas.ts`
+
+Typecheck: PASS
+```
+
+## When to Use
+
+Run this command after modifying:
+- `*Endpoints.cs` - API endpoint definitions
+- `**/Models/*.cs` - Request/response DTOs
+- `**/Dtos/*.cs` - Data transfer objects
+
+## Auto-Invocation
+
+This command is auto-invoked by `/exarchos:delegate` when subagents modify API files. You typically only need to run it manually when:
+- CI schema-check fails
+- Making quick backend changes outside the workflow
+- Verifying types after pulling changes
+
+## Failure Recovery
+
+| Issue | Solution |
+|-------|----------|
+| Build failure | Check C# compilation errors in Aegis.API |
+| Orval failure | Verify `apps/aegis-api/openapi.json` is valid JSON |
+| TypeScript errors | Breaking API change - update consumers |

package/commands/synthesize.md

@@ -0,0 +1,122 @@
+---
+description: Create pull request from feature branch
+---
+
+# Synthesize
+
+Create final PR for: "$ARGUMENTS"
+
+## Workflow Position
+
+```
+/exarchos:ideate → [CONFIRM] → /exarchos:plan → /exarchos:delegate → /exarchos:review → /exarchos:synthesize → [CONFIRM] → merge
+                                                                                          ▲▲▲▲▲▲▲▲▲▲▲▲▲▲▲▲▲▲▲▲
+```
+
+This command is the **exit point** of the development workflow. After creating the PR, asks for confirmation before merging.
+
+## Skill Reference
+
+Follow the synthesis skill: `@skills/synthesis/SKILL.md`
+
+## Prerequisites
+
+- [ ] Review phase complete (all checks passed)
+- [ ] Spec review: PASS
+- [ ] Quality review: APPROVED
+
+## Process
+
+### Step 1: Verify Branch State
+```bash
+git log --oneline -5  # Confirm all task commits present
+```
+
+### Step 2: Submit Stacked PRs
+
+Follow `@rules/pr-descriptions.md` for concise format.
+
+**Always use Graphite** to submit stacked PRs:
+```typescript
+mcp__graphite__run_gt_cmd({
+  args: ["submit", "--no-interactive", "--publish", "--merge-when-ready", "--stack"],
+  cwd: "<repo-root>"
+})
+```
+
+**NEVER use `gh pr create` or `mcp__plugin_github_github__create_pull_request`** — these create non-stacked PRs that bypass Graphite's stack management.
+
+### Step 3: Cleanup (After Merge)
+```bash
+git worktree remove .worktrees/task-name
+git branch -d feature/task-branch
+git worktree prune
+```
+
+## Handling Failures
+
+- **PR checks fail:** Push fixes to feature branch
+- **Review feedback:** Use `/exarchos:delegate --pr-fixes` to address comments
+
+## Output
+
+When complete:
+```markdown
+## Synthesis Complete
+
+PR: [URL]
+Tests: X pass | Build: 0 errors
+```
+
+## Direct Edits
+
+You can make direct edits to stack branches at any time:
+- Edit files in your IDE
+- Stage and commit via Graphite: `gt modify -m "fix: <description>"`
+- Resubmit the stack: `gt submit --no-interactive`
+
+**NEVER use `git commit` or `git push`** — always use `gt modify` and `gt submit` to keep the stack consistent.
+
+## Idempotency
+
+Before synthesizing, check synthesis status:
+1. Check if `synthesis.prUrl` exists in state
+2. If PR exists and is open, skip to merge confirmation
+3. If PR merged, update phase to "completed"
+
+## Human Checkpoint
+
+After PR is created, this is a **human checkpoint** - user confirmation required.
+
+### Save State
+
+Update state using `mcp__exarchos__exarchos_workflow` with `action: "set"` and the `featureId`:
+- Set `artifacts.pr` to the PR URL
+- Set `synthesis.prUrl` to the PR URL
+
+## Auto-Chain
+
+After PR created:
+
+1. Update state with PR URL
+2. Output: "PR created: [URL]. All checks passing."
+3. **PAUSE for user input**: "Merge PR? (yes/no/feedback)"
+
+This is one of only TWO human checkpoints in the workflow.
+
+4. **On 'yes'** (yes, y, merge):
+   ```bash
+   gh pr merge <PR_NUMBER> --squash --auto
+   ```
+   > Or use GitHub MCP `merge_pull_request` if available.
+
+   Update state: `.phase = "completed"`
+
+5. **On 'feedback'** (feedback, comments, fixes, changes, address):
+   Auto-continue to fixes:
+   ```typescript
+   Skill({ skill: "exarchos:delegate", args: "--pr-fixes [PR_URL]" })
+   ```
+   After fixes complete, workflow returns here automatically.
+
+6. **On 'no'**: "Workflow paused. Run `/exarchos:resume` to continue later."

package/commands/tdd.md

@@ -0,0 +1,58 @@
+---
+name: tdd
+description: "Plan implementation following strict TDD (Red-Green-Refactor)."
+---
+
+# TDD Implementation Plan
+
+Create a detailed TDD implementation plan for: "$ARGUMENTS"
+
+## Skill Reference
+
+Follow the implementation-planning skill: `@skills/implementation-planning/SKILL.md`
+
+## TDD Workflow Reference
+
+Follow the strict TDD workflow from `rules/tdd.md`. For test code patterns, see `@skills/delegation/references/testing-patterns.md`.
+
+## Plan Requirements
+
+Generate a step-by-step implementation plan where:
+
+1. **Every implementation step starts with a failing test**
+2. **Each step is labeled with its TDD phase**: [RED], [GREEN], or [REFACTOR]
+3. **Include test verification after each implementation**
+
+## Plan Format
+
+```
+## Implementation Plan: [Feature Name]
+
+### Step 1: [RED] Write failing test for [behavior]
+- Create test file at [path]
+- Test: `MethodName_Scenario_ExpectedOutcome`
+- Expected failure reason: [reason]
+- Run: `npm run test:run` or `dotnet test`
+
+### Step 2: [GREEN] Implement minimum code
+- Modify [file]
+- Implementation: [brief description]
+- Run: `npm run test:run` - verify test passes
+
+### Step 3: [REFACTOR] Clean up
+- Apply: [SOLID principle or improvement]
+- Run: `npm run test:run` - verify tests stay green
+
+### Step 4: [RED] Write failing test for [next behavior]
+...
+```
+
+## Deliverables
+
+The plan MUST include:
+- [ ] Test file locations
+- [ ] Test method names following naming convention
+- [ ] Expected failure reasons for RED phase
+- [ ] Minimal implementation description for GREEN phase
+- [ ] Specific refactoring actions for REFACTOR phase
+- [ ] Verification commands after each step