@lvlup-sw/exarchos 2.0.1

package/commands/checkpoint.md

@@ -0,0 +1,85 @@
+---
+description: Save workflow state and prepare for session handoff
+---
+
+# Checkpoint
+
+Save current workflow progress for potential session handoff.
+
+## When to Use
+
+Use `/exarchos:checkpoint` when:
+- Context is getting heavy (many tool calls, large outputs)
+- Before a long-running operation
+- At natural workflow boundaries
+- Before stepping away from the keyboard
+
+## Skill Reference
+
+- Workflow state: `@skills/workflow-state/SKILL.md`
+
+## Process
+
+### Step 1: Identify Active Workflow
+
+The SessionStart hook automatically discovers active workflows on session start. If you need to locate the state file manually, check the state directory:
+
+```bash
+ls ~/.claude/workflow-state/*.state.json
+```
+
+### Step 2: Ensure State is Current
+
+Update state file with latest progress:
+- Current phase
+- Task completion status
+- Worktree locations
+- Any pending items
+
+### Step 3: Reconcile State
+
+The SessionStart hook automatically verifies state matches git reality on resume. If manual reconciliation is needed, review state file contents against actual worktree and branch state.
+
+Fix any discrepancies.
+
+### Step 4: Output Checkpoint Summary
+
+```markdown
+## Checkpoint Saved
+
+**Feature:** <feature-id>
+**Phase:** <current-phase>
+**State file:** `~/.claude/workflow-state/<feature>.state.json`
+
+### Progress
+- Tasks: X/Y complete
+- Current: <what's in progress>
+- Next: <suggested next action>
+
+### Resume Instructions
+
+To continue this workflow in a new session:
+
+```bash
+/exarchos:resume ~/.claude/workflow-state/<feature>.state.json
+```
+
+Or start Claude Code fresh and run the resume command.
+```
+
+## Auto-Checkpoint Triggers
+
+The orchestrator should suggest `/exarchos:checkpoint` when:
+
+1. **After `/exarchos:delegate` completes** - All tasks done, before review
+2. **After PR created** - In `/exarchos:synthesize`, before feedback loop
+3. **After 3+ feedback iterations** - Context accumulation risk
+4. **When user mentions context issues** - Proactive save
+
+## Output
+
+After checkpointing, provide:
+1. Confirmation that state is saved
+2. Summary of current progress
+3. Clear instructions for resuming
+4. The exact `/exarchos:resume` command to use

package/commands/cleanup.md

@@ -0,0 +1,99 @@
+---
+description: Resolve merged workflow to completed state
+---
+
+# Cleanup
+
+Resolve merged workflow: "$ARGUMENTS"
+
+## Workflow Position
+
+```
+/exarchos:ideate → [CONFIRM] → /exarchos:plan → /exarchos:delegate → /exarchos:review → /exarchos:synthesize → [CONFIRM] → merge → /exarchos:cleanup
+                                                                                                                                                                       ▲▲▲▲▲▲▲▲▲▲▲▲▲▲▲▲▲
+```
+
+This command is the **post-merge cleanup** entry point. Use after PR stack has merged to resolve workflow state to `completed`.
+
+## Skill Reference
+
+Follow the cleanup skill: `@skills/cleanup/SKILL.md`
+
+## Prerequisites
+
+- [ ] Workflow exists (any non-terminal phase)
+- [ ] All PRs in the stack are merged
+
+## Process
+
+### Step 1: Identify Workflow
+
+Read workflow state:
+```typescript
+mcp__exarchos__exarchos_workflow({ action: "get", featureId: "<feature-id>" })
+```
+
+If no `$ARGUMENTS` provided, list active workflows:
+```typescript
+mcp__exarchos__exarchos_view({ action: "pipeline" })
+```
+
+### Step 2: Verify PR Merge Status
+
+Query GitHub for merged PRs associated with this workflow:
+```bash
+gh pr view <number> --json state,mergedAt,headRefName,url
+```
+
+> Or use GitHub MCP `pull_request_read` if available.
+
+Collect:
+- `prUrl` — PR URL(s) that were merged
+- `mergedBranches` — branch names that were merged
+
+### Step 3: Invoke Cleanup Action
+
+```typescript
+mcp__exarchos__exarchos_workflow({
+  action: "cleanup",
+  featureId: "<feature-id>",
+  mergeVerified: true,
+  prUrl: "<collected-pr-url>",
+  mergedBranches: ["<branch-1>", "<branch-2>"]
+})
+```
+
+### Step 4: Worktree Cleanup
+
+Remove worktrees associated with the workflow:
+```bash
+# For each worktree in state
+git worktree remove .worktrees/<worktree-name>
+git worktree prune
+```
+
+### Step 5: Branch Sync
+
+Sync Graphite branches to remove merged ones:
+```bash
+gt sync --force
+```
+
+## Output
+
+When complete:
+```markdown
+## Cleanup Complete
+
+Feature: <featureId>
+Previous phase: <phase> → completed
+PRs merged: <count>
+Worktrees removed: <count>
+Branches synced: ✓
+```
+
+## Error Handling
+
+- **Workflow not found:** "No workflow found for '<featureId>'. Check active workflows with pipeline view."
+- **PRs not merged:** "Cannot cleanup — PR #<number> is not merged. Merge all PRs first or use `/cancel` to abandon."
+- **Already completed:** "Workflow '<featureId>' is already completed. No cleanup needed."

package/commands/debug.md

@@ -0,0 +1,145 @@
+---
+description: Start debug workflow for bugs and regressions
+---
+
+# Debug
+
+Start debug workflow for: "$ARGUMENTS"
+
+## Workflow Overview
+
+Debug workflows are **investigation-first**: understand the problem before fixing it.
+
+```
+/exarchos:debug → Triage → Investigate → [Fix] → Validate → [CONFIRM] → merge
+                              │
+                ┌─────────────┼─────────────┐
+                │             │             │
+           --hotfix      (default)     --escalate
+                │             │             │
+           Fast path    Thorough path   → /exarchos:ideate
+    (15 min)     (full RCA)
+```
+
+**Single human checkpoint:** Merge confirmation (after fix is validated).
+
+## Skill Reference
+
+Follow the debug skill: `@skills/debug/SKILL.md`
+
+## Command Variants
+
+### Default: Thorough Track
+
+```bash
+/debug "Users report cart total is wrong after removing items"
+```
+
+Full investigation with RCA documentation.
+
+### Fast Path: Hotfix Track
+
+```bash
+/debug --hotfix "Production login is returning 500 errors"
+```
+
+Time-boxed investigation (15 min), minimal ceremony.
+
+### Escalate: Feature Workflow Handoff
+
+```bash
+/debug --escalate "This requires redesigning the auth system"
+```
+
+Hands off to `/exarchos:ideate` with preserved context.
+
+### Mid-Workflow: Switch to Thorough
+
+```bash
+/debug --switch-thorough
+```
+
+Switch from hotfix to thorough track during investigation.
+
+## Process
+
+### Step 1: Initialize State
+
+Initialize workflow state using `mcp__exarchos__exarchos_workflow` with `action: "init"`:
+- Set `featureId` to `debug-<issue-slug>`
+- Set `workflowType` to "debug"
+
+Then update the track using `mcp__exarchos__exarchos_workflow` with `action: "set"`:
+- Set `track` to "hotfix" or "thorough" based on triage
+
+### Step 2: Triage
+
+Gather context using `@skills/debug/references/triage-questions.md`:
+
+1. **What is the symptom?**
+2. **Can it be reproduced?**
+3. **What is the impact/urgency?**
+4. **What area of code is likely affected?**
+
+Select track based on urgency and complexity.
+
+### Step 3: Execute Track
+
+**Hotfix Track:**
+- Investigate (15 min max)
+- Implement minimal fix
+- Smoke test
+- Merge checkpoint
+
+**Thorough Track:**
+- Investigate (no time limit)
+- Document RCA
+- Design fix approach
+- Implement with TDD
+- Spec review
+- Create PR
+- Merge checkpoint
+
+## Arguments
+
+| Argument | Effect |
+|----------|--------|
+| `<description>` | Bug description for triage context |
+| `--hotfix` | Select hotfix track (P0 urgency) |
+| `--escalate` | Hand off to /exarchos:ideate workflow |
+| `--switch-thorough` | Switch from hotfix to thorough mid-workflow |
+
+## State Management
+
+Debug workflows use extended state schema. See `@skills/debug/references/state-schema.md`.
+
+Key fields:
+- `workflowType: "debug"`
+- `track: "hotfix" | "thorough"`
+- `urgency: { level, justification }`
+- `triage: { symptom, reproduction, affectedArea, impact }`
+- `investigation: { rootCause, findings }`
+
+## Auto-Chain Behavior
+
+Debug workflows auto-chain through phases with ONE human checkpoint.
+
+**Both tracks:**
+```
+[all phases auto-chain] → merge confirmation (HUMAN)
+```
+
+## Resume Support
+
+Debug workflows resume like feature workflows:
+
+```bash
+/exarchos:resume ~/.claude/workflow-state/debug-<issue-slug>.state.json
+```
+
+## Related
+
+- RCA template: `@skills/debug/references/rca-template.md`
+- Triage questions: `@skills/debug/references/triage-questions.md`
+- Investigation checklist: `@skills/debug/references/investigation-checklist.md`
+- State schema: `@skills/debug/references/state-schema.md`

package/commands/delegate.md

@@ -0,0 +1,56 @@
+---
+description: Dispatch tasks to Claude Code subagents
+---
+
+# Delegate
+
+Delegate tasks for: "$ARGUMENTS"
+
+## Workflow Position
+
+```
+/exarchos:ideate → [CONFIRM] → /exarchos:plan → /exarchos:delegate → /exarchos:review → /exarchos:synthesize → [CONFIRM] → merge
+                                                       ▲▲▲▲▲▲▲▲▲▲▲▲▲▲▲▲▲▲                                            │
+                                    │                                    │
+                      ON FAIL ──────┤                                    │
+                      --pr-fixes ───┴────────────────────────────────────┘
+```
+
+Auto-invokes `/exarchos:review` after tasks complete (or `/exarchos:synthesize` for `--pr-fixes` mode).
+
+## Invocation Modes
+
+| Flag | Source | Use Case |
+|------|--------|----------|
+| (none) | Implementation plan | Initial task delegation |
+| `--fixes` | Review issues | Address spec/quality failures |
+| `--pr-fixes` | PR comments | Address human review feedback |
+
+## Skill References
+
+Follow the delegation skill for full process details: `@skills/delegation/SKILL.md`
+
+Supporting references:
+- Git worktrees: `@skills/git-worktrees/SKILL.md`
+- Implementer template: `@skills/delegation/references/implementer-prompt.md`
+- Fixer template: `@skills/delegation/references/fixer-prompt.md`
+- Fix mode: `@skills/delegation/references/fix-mode.md`
+- PR fixes mode: `@skills/delegation/references/pr-fixes-mode.md`
+- Parallel strategy: `@skills/delegation/references/parallel-strategy.md`
+
+## Idempotency
+
+Before delegating, check task status:
+1. Read tasks from state file
+2. Skip tasks where `status == "complete"`
+3. Only dispatch pending/failed tasks
+4. If all tasks already complete, skip to auto-chain
+
+## Auto-Chain
+
+After all delegated tasks complete, **auto-continue immediately** (no user confirmation needed).
+
+- **Normal / --fixes mode:** Set phase to "review", invoke `Skill({ skill: "exarchos:review", args: "$STATE_FILE" })`
+- **--pr-fixes mode:** Set phase to "synthesize", invoke `Skill({ skill: "exarchos:synthesize", args: "$PR_URL" })`
+
+This is NOT a human checkpoint. State is saved automatically for recovery after context compaction.

package/commands/ideate.md

@@ -0,0 +1,82 @@
+---
+description: Start collaborative design exploration for a feature or problem
+---
+
+# Ideate
+
+Begin brainstorming session for: "$ARGUMENTS"
+
+## Workflow Overview
+
+This command is the **entry point** of the development workflow:
+
+```
+/exarchos:ideate → /exarchos:plan → [CONFIRM] → /exarchos:delegate → /exarchos:review → /exarchos:synthesize → [CONFIRM] → merge
+  ▲▲▲▲▲▲▲▲▲▲▲▲▲▲     (auto)            ↑             (auto)              (auto)             (auto)                     │
+                        │                     ▲                         │
+                        │   ON FAIL ──────────┤                         │
+                        │   --pr-fixes ───────┴─────────────────────────┘
+                        └──────────── ON BLOCKED ───────────────────────┘
+```
+
+**Confirmation points:**
+- After `/exarchos:plan` (plan-review): User confirms implementation plan before delegation begins
+- After `/exarchos:synthesize`: User confirms before PR is merged (or requests feedback fixes)
+
+## Skill Reference
+
+Follow the brainstorming skill: `@skills/brainstorming/SKILL.md`
+
+## Process
+
+### Phase 1: Understanding
+Ask clarifying questions (one at a time):
+1. What problem are we solving?
+2. What constraints exist?
+3. What patterns already exist in the codebase?
+4. Who/what will consume this?
+5. What does success look like?
+
+### Phase 2: Exploration
+Present 2-3 distinct approaches with:
+- Approach description
+- Pros and cons
+- Best use case
+- Recommendation with rationale
+
+### Phase 3: Design Presentation
+After user selects approach:
+- Write detailed design (200-300 word sections)
+- Include diagrams if helpful
+- Save to `docs/designs/YYYY-MM-DD-<feature>.md`
+
+## State Management
+
+Initialize workflow state at the start using `mcp__exarchos__exarchos_workflow` with `action: "init"` and the featureId.
+
+After saving design, update state using `mcp__exarchos__exarchos_workflow` with `action: "set"`:
+- Set `artifacts.design` to the design path
+- Set `phase` to "plan"
+
+## Output
+
+Save design to `docs/designs/YYYY-MM-DD-<feature>.md` and capture the path as `$DESIGN_PATH`.
+
+## Auto-Chain
+
+After saving the design document, **auto-continue to planning** (no user confirmation here):
+
+1. Update state with design path and phase using `mcp__exarchos__exarchos_workflow` with `action: "set"`:
+   - Set `artifacts.design` to the design document path
+   - Set `phase` to "plan"
+
+2. Output: "Design saved. Auto-continuing to implementation planning..."
+
+3. Invoke immediately:
+   ```typescript
+   Skill({ skill: "exarchos:plan", args: "$DESIGN_PATH" })
+   ```
+
+This is NOT a human checkpoint. The human checkpoint occurs after plan review (plan-design delta analysis), before delegation.
+
+**Workflow continues:** `/exarchos:ideate` → `/exarchos:plan` → plan-review → [HUMAN CHECKPOINT] → `/exarchos:delegate`

package/commands/plan.md

@@ -0,0 +1,150 @@
+---
+description: Create TDD implementation plan from design document
+---
+
+# Plan
+
+Create implementation plan for: "$ARGUMENTS"
+
+## Workflow Position
+
+```text
+/exarchos:ideate → /exarchos:plan → [CONFIRM] → /exarchos:delegate → /exarchos:review → /exarchos:synthesize → [CONFIRM] → merge
+                       ▲▲▲▲▲▲▲▲▲▲▲▲▲▲       ↑
+                  plan-review
+```
+
+After plan is saved, runs plan-review (delta analysis). User confirms at plan-review checkpoint before delegation.
+
+## Skill Reference
+
+Follow the implementation-planning skill: `@skills/implementation-planning/SKILL.md`
+
+## Iron Law
+
+> **NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST**
+
+## Process
+
+### Step 1: Analyze Design
+Read the design document and identify:
+- Core behaviors to implement
+- Data structures needed
+- API endpoints/interfaces
+- Integration points
+- Edge cases
+
+### Step 2: Decompose into Tasks
+Create tasks with:
+- 2-5 minute granularity
+- [RED], [GREEN], [REFACTOR] phases
+- Test file paths
+- Expected test names (Method_Scenario_Outcome)
+- Dependencies
+
+### Step 3: Identify Parallelization
+Group tasks into:
+- Sequential chains (dependencies)
+- Parallel-safe groups (can run in worktrees)
+
+### Step 4: Save Plan
+Write to `docs/plans/YYYY-MM-DD-<feature>.md`
+
+## Task Format
+
+```markdown
+### Task [N]: [Description]
+**Phase:** RED → GREEN → REFACTOR
+
+1. [RED] Write test: `TestName_Scenario_Outcome`
+   - File: `path/to/test.ts`
+   - Expected failure: [reason]
+
+2. [GREEN] Implement minimum code
+   - File: `path/to/impl.ts`
+
+3. [REFACTOR] Clean up if needed
+
+**Dependencies:** [Task IDs or None]
+**Parallelizable:** [Yes/No]
+```
+
+## State Management
+
+After saving plan, update state with tasks using `mcp__exarchos__exarchos_workflow` with `action: "set"`:
+- Set `artifacts.plan` to the plan path
+- Set `tasks` to an array of task objects (id, title, status, branch)
+- Set `phase` to "plan-review"
+
+## Output
+
+Save plan to `docs/plans/YYYY-MM-DD-<feature>.md` and capture the path as `$PLAN_PATH`.
+
+## Idempotency
+
+Before planning, check if plan already exists:
+1. Read state file for `.artifacts.plan`
+2. If plan file exists and is valid, skip planning
+3. Auto-chain directly to delegate
+
+## Auto-Chain
+
+After saving the implementation plan, **auto-continue to plan-review**:
+
+1. Update state: `.phase = "plan-review"`
+2. Output: "Plan saved to `$PLAN_PATH` with [N] tasks. Running plan-design coverage analysis..."
+3. Run plan-review (delta analysis):
+   - Re-read design document
+   - Compare each design section against planned tasks
+   - Generate coverage report with any gaps identified
+   - Present to user with recommendation
+
+## Plan Review: Auto-Loop on Gaps
+
+Plan-review performs delta analysis and **auto-loops** back to `/exarchos:plan` if gaps are found (similar to `/exarchos:review` → `/exarchos:delegate --fixes`):
+
+```text
+/exarchos:plan → plan-review → [gaps?] → /exarchos:plan --revise (auto-loop)
+                      ↓
+                 [no gaps]
+                      ↓
+            [HUMAN: approve?] ← checkpoint
+                      ↓
+                 /exarchos:delegate
+```
+
+### On Gaps Found (Auto-Loop)
+
+If plan-review finds missing coverage:
+
+1. Update state with gaps using `mcp__exarchos__exarchos_workflow` with `action: "set"`:
+   - Set `planReview.gapsFound` to true
+   - Set `planReview.gaps` to an array of gap descriptions
+
+2. Auto-invoke:
+   ```typescript
+   Skill({ skill: "exarchos:plan", args: "--revise $DESIGN_PATH" })
+   ```
+
+The `--revise` flag provides gap context for targeted plan updates.
+
+### On No Gaps (Human Checkpoint)
+
+If plan-review finds complete coverage:
+
+1. Display coverage report showing:
+   - Design sections covered by tasks
+   - Confirmation that all requirements are planned
+
+2. **PAUSE for user input**: "Plan covers all design requirements. Approve and continue to delegation? (yes/no)"
+
+3. **On approval**, use `mcp__exarchos__exarchos_workflow` with `action: "set"`:
+   - Set `planReview.approved` to true
+   - Set `phase` to "delegate"
+
+   Then invoke:
+   ```typescript
+   Skill({ skill: "exarchos:delegate", args: "$PLAN_PATH" })
+   ```
+
+From here, workflow runs autonomously until PR merge confirmation.