@lvlup-sw/exarchos 2.5.0 → 2.6.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "exarchos",
   "description": "A local-first SDLC workflow harness — structured, durable state for coding agents, with convergence gates, agent teams, and full audit trail.",
-  "version": "2.5.0",
+  "version": "2.6.0",
   "author": {
     "name": "LevelUp Software"
   },

package/README.md

@@ -52,6 +52,27 @@ npx @lvlup-sw/exarchos mcp
 npx create-exarchos
 ```
 
+### Installing skills for your agent
+
+Exarchos ships its skills as platform-agnostic source. To materialize the
+rendered bundle for a specific agent runtime, use `install-skills`:
+
+```bash
+exarchos install-skills --agent claude
+exarchos install-skills --agent codex
+exarchos install-skills --agent opencode
+exarchos install-skills --agent copilot
+exarchos install-skills --agent cursor
+exarchos install-skills --agent generic
+exarchos install-skills             # auto-detect from PATH + env vars
+```
+
+Auto-detection checks for known agent binaries on your `PATH` and for
+runtime-specific environment variables. If nothing is found, the generic
+bundle is installed and a message explains the fallback. If multiple
+agents are detected, an interactive prompt asks which one to target (or
+you can pass `--agent` explicitly).
+
 <details>
 <summary>Development setup</summary>
 

package/commands/dogfood.md

@@ -0,0 +1,31 @@
+---
+description: "Review failed tool calls in this session, diagnose root causes, and triage into code bug / docs issue / user error"
+---
+
+# Dogfood
+
+Triage session failures for: "$ARGUMENTS"
+
+## Skill Reference
+
+Follow the dogfood skill: `@skills/dogfood/SKILL.md`
+
+## Quick Start
+
+1. **Debug trace first** — Use MCP self-service tools to build a ground-truth picture:
+   - `exarchos_view pipeline` → identify active workflows
+   - `exarchos_workflow describe(topology, playbook)` → get HSM + phase playbooks
+   - `exarchos_event query` + `describe(emissionGuide)` → compare actual vs expected events
+   - `exarchos_orchestrate describe(actions)` + `runbook(phase)` → verify schemas, gates, step ordering
+   - `exarchos_view convergence, telemetry` → per-dimension pass rates, per-tool error rates
+2. Scan this conversation for failed calls to the 5 Exarchos MCP tools (supplementary)
+3. Cross-reference conversation errors with self-service evidence
+4. Check playbook adherence and runbook conformance
+5. Diagnose each failure using `references/root-cause-patterns.md`
+6. Categorize: **code bug**, **documentation issue**, or **user error**
+7. Present the report (include trace-only findings, playbook/runbook adherence)
+8. Offer to file GitHub issues for bugs and doc issues
+
+## Scope
+
+If `$ARGUMENTS` is provided, focus analysis on that workflow or tool. Otherwise, review all Exarchos tool failures in the current session.

package/commands/oneshot.md

@@ -0,0 +1,178 @@
+---
+description: Run a lightweight oneshot workflow — plan + TDD implement + optional PR
+---
+
+# Oneshot
+
+Start a lightweight oneshot workflow for: "$ARGUMENTS"
+
+## When to use
+
+Reach for `/exarchos:oneshot` when the change is:
+
+- Bounded — single file or 2-3 tightly-coupled files
+- Self-contained — no subagent dispatch needed
+- Obvious — no design exploration required
+- Small — direct-commit acceptable, or a single PR review will suffice
+
+Examples: typo fixes, dependency bumps, single-function null checks, CI YAML
+tweaks, config key renames, exploratory spikes.
+
+For anything cross-cutting, multi-file, or needing two-stage review, use
+`/exarchos:ideate` instead.
+
+## Skill Reference
+
+Follow the oneshot workflow skill: `@skills/oneshot-workflow/SKILL.md`
+
+## Iron Law
+
+> **NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST**
+
+TDD applies to oneshot workflows. There is no exemption for "small" changes —
+the test is what makes the change auditable.
+
+## Workflow position
+
+```
+plan ──► implementing ──┬── [direct-commit] ──► completed
+                        │
+                        └── [opt-in PR]     ──► synthesize ──► completed
+```
+
+Choice state at the end of `implementing` is decided by `synthesisPolicy`
+(set at init) plus any `synthesize.requested` events on the stream.
+
+## Process
+
+### Step 1: Init
+
+Initialize a oneshot workflow using
+`mcp__plugin_exarchos_exarchos__exarchos_workflow` with
+`action: "init"`, `workflowType: "oneshot"`, a `featureId`, and optionally
+`synthesisPolicy: "always" | "never" | "on-request"` (default: `"on-request"`).
+
+If the user has stated a clear preference ("I want a PR for this" → `always`;
+"don't open a PR" → `never`), pass it explicitly. Otherwise rely on the
+default and let the user opt in mid-implementing if they change their mind.
+
+### Step 2: Plan
+
+Produce a one-page plan with four sections:
+
+1. **Goal** — what the user is trying to accomplish (1-2 lines)
+2. **Approach** — implementation strategy (1-2 lines)
+3. **Files** — which files will change (1-5)
+4. **Tests** — which tests will be added (named, not described)
+
+Persist via `mcp__plugin_exarchos_exarchos__exarchos_workflow` with
+`action: "set"`:
+
+- Set `artifacts.plan` to the plan text
+- Set `oneshot.planSummary` to a one-line summary
+- Set `phase` to `"implementing"`
+
+### Step 3: Implementing — in-session TDD loop
+
+For each behavior in the plan:
+
+1. **[RED]** Write a failing test. Run it. Confirm it fails for the right reason.
+2. **[GREEN]** Write minimum code to pass. Run the test. Confirm green.
+3. **[REFACTOR]** Clean up while keeping tests green.
+
+Commit each cycle as a single atomic commit. No subagent dispatch — the main
+agent does the work directly.
+
+### Step 4: Mid-implementing opt-in (optional)
+
+If the user says something like "actually, let's open a PR for this" or "I
+want a review on this", call:
+
+```typescript
+mcp__plugin_exarchos_exarchos__exarchos_orchestrate({
+  action: "request_synthesize",
+  featureId: "<id>",
+  reason: "<why the user wants a PR>"
+})
+```
+
+This appends a `synthesize.requested` event. The workflow stays in
+`implementing` — the choice is only acted on at finalize.
+
+### Step 5: Finalize
+
+When all tests pass and typecheck is clean, call:
+
+```typescript
+mcp__plugin_exarchos_exarchos__exarchos_orchestrate({
+  action: "finalize_oneshot",
+  featureId: "<id>"
+})
+```
+
+The handler evaluates `synthesisPolicy` + events and transitions to either
+`synthesize` (PR path) or `completed` (direct-commit path). Outcomes:
+
+| Policy | Event present? | Resolved phase |
+|---|---|---|
+| `always` | (any) | `synthesize` |
+| `never` | (any) | `completed` |
+| `on-request` | yes | `synthesize` |
+| `on-request` | no | `completed` |
+
+### Step 6a: Direct-commit path (`completed`)
+
+Push the commits if not already pushed:
+
+```bash
+git push
+```
+
+Workflow is terminal — done.
+
+### Step 6b: Synthesize path
+
+Hand off to the standard synthesis flow: `@skills/synthesis/SKILL.md`. The
+existing `prepare_synthesis` / `validate_pr_body` / `gh pr create` machinery
+applies. After PR merge, the workflow transitions `synthesize → completed`.
+
+You do **not** need to run `/exarchos:delegate` or `/exarchos:review` for an
+opt-in oneshot synthesize — those phases are not in the oneshot playbook.
+
+## When NOT to use oneshot
+
+| Symptom | Use instead |
+|---|---|
+| Cross-cutting refactor | `/exarchos:refactor` or `/exarchos:ideate` |
+| Multi-file feature | `/exarchos:ideate` |
+| Needs design exploration | `/exarchos:ideate` |
+| Needs two-stage review | `/exarchos:ideate` |
+| Coordinates multiple agents | `/exarchos:ideate` + `/exarchos:delegate` |
+| Should land in stages | `/exarchos:ideate` (stacked PRs) |
+
+If you start a oneshot and discover it's bigger than expected: cancel and
+restart with `/exarchos:ideate`. Don't try to grow a oneshot into a feature
+workflow mid-stream.
+
+## Output
+
+Direct-commit path:
+```markdown
+## Oneshot Complete (direct-commit)
+
+Workflow: <featureId>
+Plan: <one-line summary>
+Tests added: N
+Commits: <hash list>
+Path: direct-commit
+```
+
+Synthesize path:
+```markdown
+## Oneshot Complete (synthesize)
+
+Workflow: <featureId>
+PR: <url>
+Tests: X pass | Build: 0 errors
+Path: synthesize → PR review → merge
+```

package/commands/prune.md

@@ -0,0 +1,90 @@
+---
+description: Prune stale workflows from the pipeline (dry-run → confirm → apply)
+---
+
+# Prune
+
+Prune stale non-terminal workflows from the pipeline. Wraps the `prune_stale_workflows` orchestrate action with an interactive dry-run-then-confirm flow.
+
+## When to Use
+
+Use `/exarchos:prune` when:
+- `exarchos_view pipeline` shows many inactive workflows
+- The pipeline has accumulated abandoned plans, debug branches, or one-shots
+- Periodic maintenance to keep the pipeline view actionable
+
+## Skill Reference
+
+Follow the prune-workflows skill: `@skills/prune-workflows/SKILL.md`
+
+## Process
+
+### Step 1: Dry-Run
+
+Invoke the orchestrate action in dry-run mode (default):
+
+```typescript
+mcp__plugin_exarchos_exarchos__exarchos_orchestrate({
+  action: "prune_stale_workflows",
+  args: { dryRun: true }
+})
+```
+
+### Step 2: Display Candidates
+
+Render a table of `candidates` (feature ID, type, phase, staleness in minutes) and `skipped` (feature ID, reason). If both are empty, report "No stale workflows to prune" and exit.
+
+### Step 3: Prompt
+
+Ask the user one of:
+- **proceed** — prune the listed candidates
+- **abort** — exit without changes
+- **force** — bypass safeguards and prune skipped workflows too
+
+### Step 4: Apply
+
+On `proceed`:
+```typescript
+mcp__plugin_exarchos_exarchos__exarchos_orchestrate({
+  action: "prune_stale_workflows",
+  args: { dryRun: false }
+})
+```
+
+On `force`:
+```typescript
+mcp__plugin_exarchos_exarchos__exarchos_orchestrate({
+  action: "prune_stale_workflows",
+  args: { dryRun: false, force: true }
+})
+```
+
+On `abort`: exit.
+
+### Step 5: Report
+
+Output the `pruned` array as a summary table along with any safeguards that were bypassed.
+
+## Output
+
+```markdown
+## Prune Complete
+
+**Pruned:** <count> workflows transitioned to cancelled
+**Skipped:** <count> workflows preserved by safeguards
+**Force bypass:** <yes/no>
+```
+
+## Safeguards
+
+By default the orchestrate handler skips workflows that have:
+- An open PR on the inferred branch (`open-pr`)
+- Recent commits in the last 24 hours (`active-branch`)
+
+`force: true` bypasses both, but the bypassed safeguard names are still recorded in the `workflow.pruned` event payload for audit.
+
+## Error Handling
+
+- **No state directory:** Initialize an exarchos workflow first.
+- **gh/git not available:** Safeguards short-circuit with errors; consider `force: true` after manually verifying no PRs are open.
+- **All workflows clean:** Output "No stale workflows to prune" and exit.