@lvlup-sw/exarchos 2.5.0 → 2.6.0

package/skills/codex/brainstorming/SKILL.md

@@ -0,0 +1,182 @@
+---
+name: brainstorming
+description: "Collaborative design exploration for new features and architecture decisions. Triggers: 'brainstorm', 'ideate', 'explore options', or /ideate. Presents 2-3 approaches with trade-offs, documents chosen approach. Do NOT use for implementation planning or code review. Requires no existing design document — use /plan if one exists."
+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
+
+For a complete worked example, see `references/worked-example.md`.
+
+## 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 with numbered requirements.
+
+Document the chosen approach using the structure in `references/design-template.md`. Sections of 200-300 words max. Use diagrams for complex flows.
+
+**Requirements format (MANDATORY):**
+- Use numbered requirement identifiers: `DR-1`, `DR-2`, ..., `DR-N`
+- Each requirement MUST have an `**Acceptance criteria:**` block with concrete, testable criteria
+- At least one requirement MUST address error handling, failure modes, or edge cases
+- These DR-N identifiers are provenance anchors — implementation plans trace tasks to them
+
+**Save Location:** `docs/designs/YYYY-MM-DD-<feature>.md`
+
+## Iteration Limits
+
+**Design iterations: max 3.** If Phase 2 (Exploration) cycles through 3 rounds of presenting approaches without the user converging on a choice, pause and summarize the trade-offs for the user to make a final decision.
+
+The user can override: `ideate --max-iterations 5`
+
+## 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"`, `workflowType: "feature"`, 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"
+```
+
+### Phase Transitions and Guards
+
+This skill is the entry point for the **feature workflow** (`workflowType: "feature"`). The full lifecycle is:
+
+```
+ideate → plan → plan-review → delegate ⇄ review → synthesize → completed
+```
+
+For the full transition table, consult `@skills/workflow-state/references/phase-transitions.md`.
+
+### Schema Discovery
+
+Use `exarchos_workflow({ action: "describe", actions: ["set", "init"] })` for
+parameter schemas and `exarchos_workflow({ action: "describe", playbook: "feature" })`
+for phase transitions, guards, and playbook guidance.
+
+## Completion Verification
+
+Run the ideation artifact verification:
+
+```typescript
+mcp__exarchos__exarchos_orchestrate({
+  action: "check_design_completeness",
+  featureId: "<featureId>",
+  designPath: "docs/designs/YYYY-MM-DD-<feature>.md"
+})
+```
+
+**On `passed: true`:** All completion criteria met — proceed to gate check.
+**On `passed: false`:** Missing artifacts — review output and complete before continuing. If the check is advisory (`advisory: true`), emit a warning but do not block auto-chain.
+
+## Adversarial Gate Check (ideate → plan)
+
+After artifact verification passes, run the design completeness gate check. This is the D1 (spec fidelity) lightweight adversarial check at the ideate → plan boundary.
+
+```typescript
+mcp__exarchos__exarchos_orchestrate({
+  action: "check_design_completeness",
+  featureId: "<id>",
+  designPath: "<path>"
+})
+```
+
+The handler returns a structured result: `{ passed, advisory, findings[], checkCount, passCount, failCount }`.
+
+- **`passed=true`:** Design complete — all requirements have acceptance criteria and error coverage.
+- **`passed=false, advisory=true`:** Findings detected. These are advisory — they do NOT block the auto-chain to `plan`. Present `result.data.findings` to the user alongside the transition message.
+
+Gate events (`gate.executed`) are emitted automatically by the handler — no manual event emission is needed.
+
+## Transition
+
+After brainstorming completes, **auto-continue to planning** (no user confirmation):
+
+### Pre-Chain Validation (MANDATORY)
+
+Before invoking `plan`:
+1. Verify `artifacts.design` exists in workflow state
+2. Verify the design file exists on disk: `test -f "$DESIGN_PATH"`
+3. Run `mcp__exarchos__exarchos_orchestrate({ action: "check_design_completeness", featureId: "<id>", designPath: "<path>" })` (advisory — record findings but don't block)
+4. If steps 1 or 2 fail: "Design artifact not found, cannot auto-chain to plan"
+
+### Chain Steps
+
+1. Update state: `action: "set", featureId: "<id>", updates: { "artifacts": { "design": "<path>" } }, phase: "plan"`
+
+2. If `result.data.passed === false` and `result.data.advisory === true`: Output `result.data.findings` summary, then: "Advisory findings noted. Auto-continuing to implementation planning..."
+   If `result.data.passed === true`: Output: "Design complete. Auto-continuing to implementation planning..."
+
+3. Invoke immediately:
+   ```typescript
+   [Invoke the exarchos:plan skill with args: <design-path>]
+   ```
+
+This is NOT a human checkpoint. The human checkpoint occurs at plan-review (plan approval) and synthesize (merge confirmation).
+
+**Workflow continues:** `ideate` -> `plan` -> plan-review -> [HUMAN CHECKPOINT] -> `delegate` -> `review` -> `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/codex/brainstorming/references/design-template.md

@@ -0,0 +1,107 @@
+# 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]
+
+## Requirements
+
+### DR-1: [Requirement name]
+
+[Description of the requirement]
+
+**Acceptance criteria:**
+- [Criterion 1]
+- [Criterion 2]
+
+### DR-2: [Requirement name]
+
+[Description]
+
+**Acceptance criteria:**
+- [Criterion 1]
+- [Criterion 2]
+
+### DR-N: Error handling and edge cases
+
+[Error/failure/boundary conditions]
+
+**Acceptance criteria:**
+- [Error case 1]
+- [Edge case 1]
+
+## 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]
+```
+
+### Requirement Format Rules
+
+- **Numbered IDs:** Use `DR-N` (Design Requirement) format. `REQ-N` and `R-N` are also accepted.
+- **Acceptance criteria:** Every requirement MUST have a `**Acceptance criteria:**` block with concrete, testable criteria.
+- **Structured criteria preferred:** For behavioral requirements, use Given/When/Then format. These become executable acceptance tests during planning:
+  ```markdown
+  **Acceptance criteria:**
+  - Given [precondition]
+    When [action]
+    Then [expected outcome]
+    And [additional outcome]
+  ```
+  Bullet-point criteria are still valid for non-behavioral requirements (performance constraints, configuration, etc.).
+- **Error/edge cases:** At least one requirement must address error handling, failure modes, or boundary conditions. Don't design only the happy path.
+- **Provenance anchors:** These DR-N identifiers become traceability anchors — implementation plans map tasks to them (`Implements: DR-1`), and the feature audit traces code and tests back to them.
+
+## 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/codex/brainstorming/references/worked-example.md

@@ -0,0 +1,58 @@
+---
+name: brainstorming-worked-example
+description: "Complete trace of the brainstorming skill in action, showing happy path and pivot recovery."
+---
+
+# Worked Example: Brainstorming — Event Deduplication
+
+## Context
+
+Feature: event store deduplication for the Exarchos MCP server. The user runs `/exarchos:ideate` to explore approaches.
+
+## Phase 1: Understanding
+
+**Agent:** "What problem are we solving?"
+**User:** "Duplicate events in the JSONL store when agents retry after timeouts."
+
+**Agent:** "What constraints exist?"
+**User:** "Must not break existing event streams. Append-only store, no rewriting."
+
+**Agent:** "What patterns already exist in the codebase?"
+**User:** "Events have timestamps and stream IDs but no unique event IDs."
+
+## Phase 2: Exploration
+
+**Agent presents three approaches:**
+
+### Option 1: Idempotency Keys
+Add a unique `eventId` field. Writers generate UUIDs; readers skip duplicates.
+- **Pros:** Simple, no schema migration needed.
+- **Cons:** Requires all callers to generate IDs.
+
+### Option 2: Content Hashing
+Hash `stream + type + timestamp + payload` to detect duplicates at write time.
+- **Pros:** No caller changes. Automatic.
+- **Cons:** Hash collisions possible. Slightly slower writes.
+
+### Option 3: Write-Ahead Log
+Buffer events in a WAL, flush deduplicated batches.
+- **Pros:** Strongest guarantees. Enables batching.
+- **Cons:** Significant complexity. Overkill for append-only JSONL.
+
+**Agent recommends Option 1** — simplest, aligns with event-sourcing conventions.
+
+## Pivot: User Rejects All Approaches
+
+**User:** "These all add complexity. Can we just make the timeout longer?"
+
+**Agent:** "Longer timeouts reduce retries but don't eliminate duplicates from network issues or process restarts. However, we can combine your instinct with a minimal approach: add idempotency keys (Option 1) but make them optional — readers tolerate duplicates, and the key is only used when callers choose to deduplicate. This keeps the default path unchanged."
+
+**User:** "That works. Proceed with optional idempotency keys."
+
+## Phase 3: Design Presentation
+
+Agent writes design document to `docs/designs/2026-02-28-event-deduplication.md` covering: problem statement, chosen approach (optional idempotency keys), technical design (UUID generation, reader-side dedup), integration points (event append tool, view tool), testing strategy (duplicate detection tests, backward compatibility).
+
+**State update:** `artifacts.design` set to design path, phase transitions to `plan`.
+
+**Agent:** "Design saved. Auto-continuing to implementation planning..."

package/skills/codex/cleanup/SKILL.md

@@ -0,0 +1,169 @@
+---
+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: completed
+---
+
+# 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.
+
+## Batch Pruning for Stale Workflows
+
+For bulk cleanup of accumulated stale or abandoned workflows (as opposed to resolving a single merged workflow), use `@skills/prune-workflows/SKILL.md`. That skill invokes `exarchos_orchestrate prune_stale_workflows` in dry-run mode, displays candidates, and applies after user confirmation. Safeguards automatically skip workflows with open PRs or recent commits.
+
+**Rule of thumb:** cleanup is per-workflow (one merged feature → `completed`); prune is bulk (N inactive workflows → `cancelled`). They are complementary, not alternatives.
+
+## 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`.
+
+### 2.5. Post-Merge Regression Check (Advisory)
+
+After verifying merge status, run the post-merge regression check:
+
+```typescript
+exarchos_orchestrate({
+  action: "check_post_merge",
+  featureId: "<id>",
+  prUrl: "<url>",
+  mergeSha: "<sha>"
+})
+```
+
+This check is **advisory** — findings are reported but do not block cleanup. If findings are detected, log them for the user's awareness before proceeding.
+
+### 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
+git fetch --prune
+git branch -d <merged-branch-1> <merged-branch-2> ...
+```
+
+### 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 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/codex/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 stacked PR set, 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 — `git fetch --prune` will handle it.