@lvlup-sw/exarchos 2.0.1

package/settings.json

@@ -0,0 +1,47 @@
+{
+  "permissions": {
+    "allow": [
+      "Read",
+      "Write",
+      "Edit",
+      "Glob",
+      "Grep",
+      "NotebookEdit",
+      "Task",
+      "LSP",
+      "WebSearch",
+      "WebFetch",
+      "mcp__*",
+      "Bash(gt:*)",
+      "Bash(gh:*)",
+      "Bash(git:*)",
+      "Bash(npm:*)",
+      "Bash(npx:*)",
+      "Bash(yarn:*)",
+      "Bash(pnpm:*)",
+      "Bash(bun:*)",
+      "Bash(node:*)",
+      "Bash(docker:*)",
+      "Bash(docker-compose:*)",
+      "Bash(make:*)",
+      "Bash(ls:*)",
+      "Bash(cat:*)",
+      "Bash(find:*)",
+      "Bash(grep:*)",
+      "Bash(mkdir:*)",
+      "Bash(rm:*)",
+      "Bash(cp:*)",
+      "Bash(mv:*)",
+      "Bash(chmod:*)",
+      "Bash(ln:*)",
+      "Bash(echo:*)",
+      "Bash(pwd:*)",
+      "Bash(which:*)",
+      "Bash(env:*)",
+      "Bash(test:*)",
+      "Bash(diff:*)",
+      "Bash(jq:*)"
+    ]
+  },
+  "model": "claude-opus-4-6"
+}

package/skills/brainstorming/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: brainstorming
+description: "Collaborative design exploration for new features and architecture decisions. Use when the user says \"let's brainstorm\", \"let's ideate\", \"explore options\", or runs /ideate. Presents 2-3 distinct approaches with trade-offs, then documents the chosen approach as a design document. Do NOT use for implementation planning or code review. Use when no design document exists yet for the target feature. Do NOT use if a design document already exists — use /plan instead."
+metadata:
+  author: exarchos
+  version: 1.0.0
+  mcp-server: exarchos
+  category: workflow
+  phase-affinity: ideate
+---
+
+# Brainstorming Skill
+
+## Overview
+
+Collaborative design exploration for new features, architecture decisions, and complex problem-solving.
+
+## Triggers
+
+Activate this skill when:
+- User says "let's brainstorm", "let's ideate", or "let's explore"
+- User runs `/ideate` command
+- User wants to discuss design options before implementation
+- A problem has multiple valid solutions needing evaluation
+
+## Three-Phase Process
+
+### Phase 1: Understanding
+
+**Goal:** Deeply understand the problem before proposing solutions.
+
+**Rules:**
+- Ask ONE question at a time
+- Wait for response before asking next question
+- Focus on: goals, constraints, existing patterns, user preferences
+- Maximum 5 questions before moving to exploration
+
+**Question Types:**
+1. "What problem are we solving?" (core need)
+2. "What constraints exist?" (time, tech, compatibility)
+3. "What patterns already exist in the codebase?" (consistency)
+4. "Who/what will consume this?" (users, APIs, other systems)
+5. "What does success look like?" (acceptance criteria)
+
+### Phase 2: Exploration
+
+**Goal:** Present 2-3 distinct approaches with trade-offs.
+
+Use the approach format from `references/design-template.md`. Present genuinely different approaches with honest trade-offs. Recommend one option with rationale.
+
+### Phase 3: Design Presentation
+
+**Goal:** Document the chosen approach in detail.
+
+Document the chosen approach using the structure in `references/design-template.md`. Sections of 200-300 words max. Use diagrams for complex flows.
+
+**Save Location:** `docs/designs/YYYY-MM-DD-<feature>.md`
+
+## Anti-Patterns
+
+| Don't | Do Instead |
+|-------|------------|
+| Jump to solution immediately | Ask clarifying questions first |
+| Present only one option | Always show 2-3 alternatives |
+| Hide drawbacks of preferred option | Be transparent about trade-offs |
+| Write walls of text | Use 200-300 word sections max |
+| Ignore existing patterns | Reference codebase conventions |
+| Skip documentation | Save design to docs/designs/ |
+
+## State Management
+
+This skill manages workflow state for context persistence.
+
+### On Start (before Phase 1)
+
+Initialize workflow state using `mcp__exarchos__exarchos_workflow` with `action: "init"` and the featureId.
+
+This creates a state file tracked by the MCP server.
+
+### On Design Save (after Phase 3)
+
+```
+action: "set", featureId: "<id>", updates: { "artifacts": { "design": "<path>" } }, phase: "plan"
+```
+
+## Completion Verification
+
+Run the ideation artifact verification:
+
+```bash
+scripts/verify-ideate-artifacts.sh --state-file <state-file> --docs-dir docs/designs
+```
+
+**On exit 0:** All completion criteria met — proceed to /exarchos:plan.
+**On exit 1:** Missing artifacts — review output and complete before continuing.
+
+## Transition
+
+After brainstorming completes, **auto-continue to planning** (no user confirmation):
+
+### Pre-Chain Validation (MANDATORY)
+
+Before invoking `/exarchos:plan`:
+1. Verify `artifacts.design` exists in workflow state
+2. Verify the design file exists on disk: `test -f "$DESIGN_PATH"`
+3. If either fails: "Design artifact not found, cannot auto-chain to /exarchos:plan"
+
+### Chain Steps
+
+1. Update state: `action: "set", featureId: "<id>", updates: { "artifacts": { "design": "<path>" } }, phase: "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 at plan-review (plan approval) and synthesize (merge confirmation).
+
+**Workflow continues:** `/exarchos:ideate` -> `/exarchos:plan` -> plan-review -> [HUMAN CHECKPOINT] -> `/exarchos:delegate` -> `/exarchos:review` -> `/exarchos:synthesize` -> [HUMAN CHECKPOINT]
+
+## Exarchos Integration
+
+When Exarchos MCP tools are available:
+
+1. **At workflow start:** Auto-emitted by `exarchos_workflow` `action: "init"` — do NOT manually append `workflow.started`

package/skills/brainstorming/references/design-template.md

@@ -0,0 +1,65 @@
+# Design Document Template
+
+Save to: `docs/designs/YYYY-MM-DD-<feature>.md`
+
+## Approach Format (Phase 2)
+
+Present 2-3 approaches using this format:
+
+```markdown
+### Option [N]: [Name]
+
+**Approach:** [2-3 sentence description]
+
+**Pros:**
+- [Benefit 1]
+- [Benefit 2]
+
+**Cons:**
+- [Drawback 1]
+- [Drawback 2]
+
+**Best when:** [Scenario where this option excels]
+```
+
+Rules:
+- Present genuinely different approaches (not variations of same idea)
+- Be honest about trade-offs
+- Include at least one "simple but limited" option
+- Include at least one "flexible but complex" option
+- Recommend one option but explain why
+
+## Design Document Structure (Phase 3)
+
+Write sections of 200-300 words maximum. Use diagrams (ASCII or Mermaid) for complex flows. Reference existing codebase patterns.
+
+```markdown
+# Design: [Feature Name]
+
+## Problem Statement
+[What we're solving and why]
+
+## Chosen Approach
+[Selected option with rationale]
+
+## Technical Design
+[Implementation details, data structures, APIs]
+
+## Integration Points
+[How this connects to existing code]
+
+## Testing Strategy
+[How we'll verify it works]
+
+## Open Questions
+[Decisions deferred or needing input]
+```
+
+## Exploration Quality Gate
+
+Stop Phase 2 when ALL are true:
+- [ ] 2-3 approaches documented
+- [ ] Each answers design questions from Phase 1
+- [ ] Approaches differ in at least 2 of: {data structure, API design, complexity}
+- [ ] Trade-offs are honest and specific
+- [ ] One approach recommended with rationale

package/skills/cleanup/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: cleanup
+description: "Post-merge workflow resolution. Verifies PR merge status, backfills synthesis metadata, force-resolves review statuses, transitions to completed, and cleans up worktrees/branches. Use when the user says 'cleanup', 'resolve workflow', 'mark as done', or runs /cleanup. Do NOT use before PRs are merged."
+metadata:
+  author: exarchos
+  version: 1.0.0
+  mcp-server: exarchos
+  category: workflow
+  phase-affinity: cleanup
+---
+
+# Cleanup Skill
+
+## Overview
+
+Resolve merged workflows to `completed` state in a single operation. Replaces the manual multi-step process of navigating HSM guards after PR stacks merge.
+
+## Triggers
+
+Activate this skill when:
+- User runs `/cleanup` command
+- User says "cleanup", "resolve workflow", "mark as done"
+- PR stack has merged and workflow needs resolution
+- User wants to close out a completed feature
+
+## Prerequisites
+
+- Active workflow in any non-terminal phase
+- All PRs merged on GitHub
+
+## Process
+
+### 1. Identify Target Workflow
+
+Read workflow state to get current phase and metadata:
+```typescript
+mcp__exarchos__exarchos_workflow({ action: "get", featureId: "<id>" })
+```
+
+If featureId not provided, use pipeline view to list active workflows:
+```typescript
+mcp__exarchos__exarchos_view({ action: "pipeline" })
+```
+
+### 2. Verify Merge Status
+
+For each PR associated with the workflow, verify it is merged.
+
+**Primary method** — gh CLI:
+```bash
+gh pr view <number> --json state,mergedAt,headRefName
+```
+
+> Or use GitHub MCP `pull_request_read` if available.
+
+Collect from merged PRs:
+- `prUrl`: The PR URL (or array of URLs for stacked PRs)
+- `mergedBranches`: The head branch names that were merged
+
+**Safety check:** If ANY PR is not merged, abort with clear error message.
+
+For detailed verification guidance, see `references/merge-verification.md`.
+
+### 3. Invoke Cleanup Action
+
+Call the MCP cleanup action with collected data:
+```typescript
+mcp__exarchos__exarchos_workflow({
+  action: "cleanup",
+  featureId: "<id>",
+  mergeVerified: true,
+  prUrl: "<url-or-array>",
+  mergedBranches: ["branch1", "branch2"]
+})
+```
+
+This single call:
+- Backfills `synthesis.prUrl` and `synthesis.mergedBranches`
+- Force-resolves all blocking review statuses to `approved`
+- Transitions to `completed` via universal cleanup path
+- Emits `workflow.cleanup` event to event store
+
+### 4. Worktree Cleanup
+
+Remove all worktrees associated with the workflow:
+```bash
+# Read worktrees from state (already captured in step 1)
+git worktree remove .worktrees/<name>
+git worktree prune
+```
+
+Handle gracefully if worktrees are already removed.
+
+### 5. Branch Sync
+
+Remove merged local branches:
+```bash
+gt sync --force
+```
+
+### 6. Report Completion
+
+Output summary:
+```markdown
+## Cleanup Complete
+
+**Feature:** <featureId>
+**Transition:** <previousPhase> → completed
+**PRs merged:** <count>
+**Worktrees removed:** <count>
+**Branches synced:** ✓
+```
+
+## Dry Run
+
+Use `dryRun: true` to preview what cleanup would do without modifying state:
+```typescript
+mcp__exarchos__exarchos_workflow({
+  action: "cleanup",
+  featureId: "<id>",
+  mergeVerified: true,
+  dryRun: true
+})
+```
+
+## Error Handling
+
+| Error | Cause | Resolution |
+|-------|-------|------------|
+| STATE_NOT_FOUND | Invalid featureId | Check pipeline view for active workflows |
+| ALREADY_COMPLETED | Workflow already done | No action needed |
+| INVALID_TRANSITION | Workflow is cancelled | Cannot cleanup cancelled workflows |
+| GUARD_FAILED | mergeVerified is false | Verify PRs are merged before cleanup |
+
+## Anti-Patterns
+
+| Don't | Do Instead |
+|-------|------------|
+| Use cleanup as escape hatch during implementation | Only use after PRs are merged |
+| Skip merge verification | Always verify via GitHub API |
+| Manually navigate HSM guards post-merge | Use /exarchos:cleanup |
+| Leave worktrees after cleanup | Include worktree removal in process |
+
+## Exarchos Integration
+
+The cleanup action auto-emits events — do NOT manually emit:
+- `workflow.cleanup` — emitted by the MCP cleanup action for the phase change to completed

package/skills/cleanup/references/merge-verification.md

@@ -0,0 +1,40 @@
+---
+name: merge-verification
+---
+
+# Merge Verification Guide
+
+## Why Verify?
+
+The cleanup action trusts the `mergeVerified` flag — it does not query GitHub itself. The orchestrator (skill) is responsible for verification. This separation keeps the MCP server free of GitHub API dependencies.
+
+## Verification Methods
+
+### gh CLI (Primary)
+
+```bash
+gh pr view 123 --json state,mergedAt,headRefName
+# Check: .state == "MERGED" and .mergedAt is not null
+```
+
+> Or use GitHub MCP `pull_request_read` if available for structured data.
+
+### For Stacked PRs
+
+When verifying a Graphite stack, check ALL PRs in the stack:
+
+```bash
+# List PRs for the branch stack
+gh pr list --head "feature/*" --json number,state,headRefName
+```
+
+Collect from each merged PR:
+- `number` — for logging
+- `headRefName` — for `mergedBranches` array
+- PR URL — for `prUrl` (use array if multiple)
+
+## Edge Cases
+
+- **Partially merged stack:** If some PRs are merged and others are not, abort cleanup. All PRs must be merged.
+- **Squash-merged PRs:** The branch name may differ from what's in the worktree. Use the PR's `headRefName` field.
+- **Already-deleted branches:** GitHub may have auto-deleted branches after merge. This is fine — `gt sync` will handle it.

package/skills/debug/SKILL.md

@@ -0,0 +1,204 @@
+---
+name: debug
+description: "Bug investigation and fix workflow with hotfix and thorough tracks. Use when the user says 'debug', 'fix bug', 'investigate issue', 'something is broken', 'debug this issue', or runs /debug. Hotfix track for quick fixes, thorough track for complex bugs requiring root cause analysis. Do NOT use for feature development or planned refactoring. Do NOT escalate to /ideate unless the fix requires architectural redesign — implementation complexity alone is not sufficient reason to escalate."
+metadata:
+  author: exarchos
+  version: 1.0.0
+  mcp-server: exarchos
+  category: workflow
+  phase-affinity:
+    - triage
+    - investigate
+    - rca
+    - design
+    - implement
+    - validate
+    - review
+    - synthesize
+---
+
+# Debug Workflow Skill
+
+## Overview
+
+Investigation-first workflow for debugging and regression fixes. Provides two tracks based on urgency: hotfix (fast, minimal ceremony) and thorough (rigorous, full RCA documentation).
+
+## Triggers
+
+Activate this skill when:
+- User runs `/debug` command
+- User reports a bug or regression
+- User needs to investigate an error
+- User says "fix this bug" or similar
+
+**Disambiguation:** If the user says "fix" or "clean up" — use `/debug` when something is *broken* (error, crash, wrong behavior). Use `/refactor` when the code *works* but needs structural improvement.
+
+## Workflow Overview
+
+```
+                              /exarchos:debug
+                                 │
+                            ┌────┴────┐
+                            │ Triage  │
+                            └────┬────┘
+                                 │
+               ┌─────────────────┼─────────────────┐
+               │                 │                 │
+          --hotfix            (default)       --escalate
+               │                 │                 │
+               ▼                 ▼                 ▼
+      ┌────────────────┐  ┌─────────────┐   ┌──────────┐
+      │  Hotfix Track  │  │   Thorough  │   │ /exarchos:ideate  │
+      │                │  │    Track    │   │ handoff  │
+      └────────────────┘  └─────────────┘   └──────────┘
+```
+
+## Command Interface
+
+### Start Debug Workflow
+
+```bash
+# Default: thorough track
+/debug "Description of the bug"
+
+# Fast path: hotfix track
+/debug --hotfix "Production is down - users can't login"
+
+# Escalate to feature workflow
+/debug --escalate "This needs architectural changes"
+```
+
+### Mid-Workflow Commands
+
+These are user-facing commands (the orchestrator resolves them to namespaced form internally):
+
+```bash
+# Switch from hotfix to thorough (during investigation)
+/debug --switch-thorough
+
+# Escalate to /ideate (manual handoff)
+/debug --escalate "Reason for escalation"
+
+# Resume after context compaction
+/resume
+```
+
+## Track Comparison
+
+| Aspect | Hotfix | Thorough |
+|--------|--------|----------|
+| Urgency | P0 (production down) | P1/P2 (normal priority) |
+| Investigation | 15 min time-boxed | No time limit |
+| RCA Document | No (minimal in state) | Yes (full docs/rca/) |
+| Worktree | No (in-place fix) | Yes (isolated) |
+| Review | Smoke test only | Spec review |
+| Human Checkpoints | 1 (merge) | 1 (merge) |
+
+## Hotfix Track
+
+Fix production issues ASAP. Speed over ceremony.
+
+**Phases:** Triage (see `references/triage-questions.md`) -> Investigate (15 min max) -> Implement (no worktree) -> Validate -> Merge
+
+### Investigation Timer
+
+1. On hotfix track selection: record `investigation.startedAt` in state
+2. After each major finding: check elapsed time
+3. At 15 min mark: emit `investigation.timeout` event, pause for user confirmation
+   - Switch to thorough track? (yes/no)
+
+For detailed phase instructions, see `references/hotfix-track.md`.
+
+## Thorough Track
+
+Fix bugs with proper rigor. Full RCA documentation.
+
+**Phases:** Triage -> Investigate -> RCA -> Design -> Implement (worktree + TDD) -> Review -> Synthesize -> Merge
+
+For detailed phase instructions, see `references/thorough-track.md`. For systematic investigation methodology, see `references/investigation-checklist.md`.
+
+### Track Switching
+
+- **Hotfix -> Thorough:** When investigation timer expires (15 min). All findings preserved.
+- **Thorough -> Escalate:** When fix requires architectural changes. Hand off to `/exarchos:ideate`.
+
+For detailed switching logic, see `references/thorough-track.md`.
+
+## Auto-Chain Behavior
+
+Both tracks have ONE human checkpoint: merge confirmation.
+
+**Hotfix auto-chain:**
+```
+triage → investigate → implement → validate → [HUMAN: merge]
+         (auto)        (auto)       (auto)
+```
+
+**Thorough auto-chain:**
+```
+triage → investigate → rca → design → implement → review → synthesize → [HUMAN: merge]
+         (auto)        (auto) (auto)   (auto)      (auto)   (auto)
+```
+
+## State Management
+
+Initialize debug workflow:
+```
+action: "init", featureId: "debug-<issue-slug>", workflowType: "debug"
+```
+
+See `@skills/debug/references/state-schema.md` for full schema.
+
+## Integration Points
+
+### With /resume
+
+Debug workflows resume like feature workflows:
+```bash
+/resume ~/.claude/workflow-state/debug-<issue-slug>.state.json
+```
+
+### With Existing Skills
+
+- Uses spec-review skill for thorough track review phase
+- Uses synthesis skill for PR creation
+- Uses git-worktrees skill for thorough track implementation
+
+### With MCP Workflow State Tools
+
+Extended to support:
+- `workflowType: "debug"` field
+- Debug-specific phases handled by the SessionStart hook (which determines next action on resume)
+- Debug context provided by the SessionStart hook on session start
+
+## Completion Criteria
+
+### Hotfix Complete
+
+- [ ] Root cause identified (even if briefly)
+- [ ] Minimal fix applied
+- [ ] Affected tests pass
+- [ ] Follow-up RCA task created
+- [ ] Changes merged
+
+### Thorough Complete
+
+- [ ] Full RCA documented in docs/rca/ (use `references/rca-template.md`)
+- [ ] Fix matches RCA findings
+- [ ] TDD implementation with tests
+- [ ] Spec review passed
+- [ ] PR merged
+
+## Anti-Patterns
+
+| Don't | Do Instead |
+|-------|------------|
+| Start coding before understanding bug | Investigate first, always |
+| Skip RCA on thorough track | Document for future learning |
+| Exceed 15 min on hotfix investigation | Switch to thorough track |
+| Add features during bug fix | Scope creep - only fix the bug |
+| Skip tests because "it's just a fix" | Fixes need tests to prevent regression |
+
+## Troubleshooting
+
+See `references/troubleshooting.md` for MCP tool failures, state desync, investigation timeouts, and track switching issues.