@lvlup-sw/exarchos 2.4.3 → 2.6.0

package/skills/codex/delegation/references/workflow-steps.md

@@ -0,0 +1,131 @@
+---
+name: workflow-steps
+---
+
+# Delegation Workflow Steps
+
+## Step 1: Prepare Environment
+
+For parallel tasks, create worktrees:
+```bash
+git worktree add .worktrees/task-001 feature/task-001
+cd .worktrees/task-001 && npm install
+```
+
+## Step 2: Extract Task Details
+
+From implementation plan, extract for each task:
+- Full task description
+- Files to create/modify
+- Test file paths
+- Expected test names
+- Dependencies
+
+## Step 3: Create TodoWrite Entries
+
+Track all delegated tasks:
+```typescript
+TodoWrite({
+  todos: [
+    { content: "Task 001: User model", status: "in_progress", activeForm: "Implementing user model" },
+    { content: "Task 002: Auth endpoints", status: "pending", activeForm: "Implementing auth endpoints" }
+  ]
+})
+```
+
+## Step 4: Dispatch Implementers
+
+**Parallel dispatch:**
+```typescript
+// Launch multiple in single message for parallel execution
+Task({
+  subagent_type: "general-purpose",
+  model: "opus",
+  run_in_background: true,
+  description: "Implement task 001",
+  prompt: "[Full implementer prompt]"
+})
+
+Task({
+  subagent_type: "general-purpose",
+  model: "opus",
+  run_in_background: true,
+  description: "Implement task 002",
+  prompt: "[Full implementer prompt]"
+})
+```
+
+### Agent Teams Dispatch (enhanced)
+
+When using `--mode agent-team`:
+1. **Pre-delegation intelligence:** Query `exarchos_view team_performance` for historical metrics
+2. **Team creation:** Create team with named teammates, each assigned to a worktree
+3. **Task list setup:** Create native Claude Code tasks with dependency annotations
+4. **Natural language delegation:** Describe tasks to teammates with full implementer prompt content (MUST include Commit Strategy section with `git commit`/`git push` instructions)
+5. **Event emission:** Append `team.spawned` event with `event.data`: teamSize, teammateNames, taskCount, dispatchMode
+
+Teammates self-coordinate via shared task list. No `Task()` calls needed.
+
+## Step 5: Monitor Progress
+
+For background tasks:
+```typescript
+TaskOutput({ task_id: "task-001-id", block: true })
+```
+
+### Agent Teams Monitoring (enhanced)
+
+When using `--mode agent-team`:
+- Teammates visible in tmux split panes
+- `TeammateIdle` hook auto-runs quality gates (typecheck, tests, clean worktree)
+- On quality pass: emits `team.task.completed` event with performance data
+- On quality fail: exit code 2 sends feedback, emits `team.task.failed` event
+- Hook scans task graph for newly unblocked tasks for teammates to claim
+- Orchestrator monitors via `exarchos_view delegation_timeline` for bottleneck detection
+
+## Step 6: Collect Results
+
+When tasks complete, run the post-delegation check:
+
+```typescript
+exarchos_orchestrate({
+  action: "post_delegation_check",
+  stateFile: "<path-to-state.json>",
+  repoRoot: "<project-root>"
+})
+```
+
+**Validates:**
+- State file exists and is valid JSON
+- Tasks array has entries
+- All tasks report "complete" status
+- Per-worktree test runs pass (unless `--skip-tests`)
+- State file consistency (all tasks have id and status fields)
+
+**On `passed: true`:** All delegation results collected and verified. Update TodoWrite status, then check if schema sync is needed (Step 7) and proceed to review phase.
+
+**On `passed: false`:** Failures detected. Review the per-task status report. Address incomplete tasks or failing tests before proceeding.
+
+### Agent Teams Collection (enhanced)
+
+When using `--mode agent-team`:
+- `TeammateIdle` hook bridges real-time Agent Teams with persistent Exarchos state
+- On quality gate pass: task marked "complete" + `team.task.completed` event emitted
+- On quality gate fail: exit code 2 sends feedback + `team.task.failed` event emitted
+- Rich event data: taskId, teammateName, durationMs, filesChanged, testsPassed
+- After all teammates finish: append `team.disbanded` event with summary metrics
+- Run `exarchos_orchestrate({ action: "post_delegation_check" })` as usual for final validation
+
+## Step 7: Schema Sync (Auto-Detection)
+
+After all tasks complete, check if API files were modified:
+
+```typescript
+exarchos_orchestrate({
+  action: "needs_schema_sync",
+  repoRoot: "<path>"
+})
+```
+
+**On `passed: true`:** No sync needed — proceed to review.
+**On `passed: false`:** Sync needed — API files modified (`*Endpoints.cs`, `Models/*.cs`, `Requests/*.cs`, `Responses/*.cs`, `Dtos/*.cs`). Run `npm run sync:schemas` and commit before proceeding.

package/skills/codex/delegation/references/worktree-enforcement.md

@@ -0,0 +1,71 @@
+---
+name: worktree-enforcement
+---
+
+# Worktree Enforcement (MANDATORY)
+
+All implementation tasks MUST run in isolated worktrees, not the main project root.
+
+## Why Worktrees Are Required
+
+- **Isolation:** Prevents merge conflicts between parallel tasks
+- **Safety:** Protects main project state
+- **Parallelism:** Enables multiple subagents to work simultaneously
+- **Recovery:** Easy rollback via branch deletion
+
+## Pre-Dispatch Checklist
+
+Before dispatching ANY implementer, run the worktree setup script:
+
+```typescript
+exarchos_orchestrate({
+  action: "setup_worktree",
+  repoRoot: "<project-root>",
+  taskId: "<task-id>",
+  taskName: "<task-name>"
+})
+```
+
+**Validates:**
+- `.worktrees/` is gitignored (adds to `.gitignore` if missing)
+- Feature branch created (`feature/<task-id>-<task-name>` from base branch)
+- Git worktree added at `.worktrees/<task-id>-<task-name>`
+- `npm install` ran in worktree
+- Baseline tests pass in worktree
+
+**On `passed: true`:** Worktree is ready. Proceed with implementer dispatch.
+
+**On `passed: false`:** Setup failed. Review the checklist output for which step failed. Fix the issue before dispatching.
+
+## Worktree State Tracking
+
+Track worktrees in the workflow state file using `mcp__plugin_exarchos_exarchos__exarchos_workflow` with `action: "set"`:
+- Set `worktrees.<worktree-id>` to an object containing `branch`, `status`, and either `taskId` (single task) or `tasks` (array of task IDs for multi-task worktrees)
+
+## Implementer Prompt Requirements
+
+Include in ALL implementer prompts:
+
+1. **Absolute worktree path** as Working Directory
+2. **Worktree verification block** (from implementer-prompt.md template)
+3. **Abort instructions** if not in worktree
+
+## Native Worktree Isolation
+
+When the `exarchos-implementer` agent definition includes `isolation: worktree` in its frontmatter, Claude Code handles worktree creation natively. The `prepare_delegation` action accepts `nativeIsolation: true` to skip manual worktree creation while preserving quality pre-checks. The worktree verification in the agent system prompt remains as defense-in-depth.
+
+When using native isolation:
+- Claude Code creates and manages the worktree lifecycle
+- The `prepare_delegation` action skips `setup-worktree.sh` but still validates state, checks quality signals, and detects benchmarks
+- The worktree verification block in the implementer prompt acts as a safety net — if native isolation fails silently, the agent self-aborts rather than modifying the main project root
+
+## Anti-Patterns
+
+| Don't | Do Instead |
+|-------|------------|
+| Make subagents read plan files | Provide full task text in prompt |
+| Use default model for coding | Specify `model: "opus"` |
+| Send sequential Task calls | Batch parallel tasks in one message |
+| Skip worktree for parallel work | Create isolated worktrees |
+| Forget to track in TodoWrite | Update status for every task |
+| Skip TDD requirements | Include TDD instructions in prompt |

package/skills/codex/dogfood/SKILL.md

@@ -0,0 +1,235 @@
+---
+name: dogfood
+description: "Review failed Exarchos MCP tool calls from the current session, diagnose root causes, and categorize into code bug, documentation issue, or user error. Use when the user says 'dogfood', 'review failures', 'what went wrong', 'triage errors', or runs /dogfood. Scopes exclusively to Exarchos tools (exarchos_workflow, exarchos_event, exarchos_orchestrate, exarchos_view, exarchos_sync). Do NOT use for debugging application code or non-Exarchos tool failures."
+metadata:
+  author: exarchos
+  version: 2.0.0
+  mcp-server: exarchos
+  category: utility
+---
+
+# Dogfood Skill
+
+## Overview
+
+Retrospective analysis of Exarchos MCP tool usage. Uses the MCP server's own self-service capabilities as the primary diagnostic instrument — describe APIs, views, playbooks, and runbooks turned inward to diagnose failures.
+
+Three distinct failure modes require different fixes — code changes, documentation updates, or skill instruction improvements. Mixing them wastes effort.
+
+### Platform-Agnosticity
+
+Per `docs/designs/2026-03-09-platform-agnosticity.md`: the MCP server is the self-sufficient, platform-agnostic core. The debug trace relies entirely on MCP tools — not conversation introspection — so it works for any MCP client. Conversation scanning is supplementary.
+
+**Diagnostic self-service tools:** `describe(topology)` for HSM verification, `describe(playbook)` for adherence checks, `describe(eventTypes, emissionGuide)` for event schema/catalog comparison, `describe(actions)` for schema/gate metadata, `runbook(phase)` for step conformance, `pipeline`/`convergence`/`telemetry` views for health metrics.
+
+## Triggers
+
+Activate this skill when:
+- User runs `/dogfood` or `dogfood`
+- User asks "what went wrong this session" or "review the failures"
+- User wants to triage errors from a workflow run
+- End of a workflow session to capture learnings
+
+## Process
+
+### Step 1: Debug Trace via MCP Self-Service
+
+Query the MCP server's own self-service capabilities to build a ground-truth diagnostic picture. This is the primary investigation method — it uses the same tools any MCP client has access to.
+
+#### 1a. Identify Active Workflows
+
+Use `exarchos_view` with `action: "pipeline"` to get an aggregated view of active workflows with their phases and task counts.
+
+If `$ARGUMENTS` specifies a workflow or feature ID, scope to that workflow. Otherwise, inspect all non-terminal workflows.
+
+#### 1b. Inspect Workflow State and Topology
+
+For each relevant workflow:
+
+1. **Read state** — `exarchos_workflow get` to retrieve current phase, tasks, reviews, gate results.
+2. **Read topology** — `exarchos_workflow describe(topology: "<workflowType>")` to get the HSM definition. Compare the agent's phase transition attempts against valid transitions. Invalid transition attempts = documentation issue (skill prescribed wrong path) or user error.
+3. **Check guard prerequisites** — For `workflow.guard-failed` events, look up the guard in the topology to understand unmet preconditions.
+
+#### 1c. Playbook Adherence Check
+
+Use `exarchos_workflow describe(playbook: "<workflowType>")` to retrieve phase playbooks. For each phase executed, compare playbook's `tools`, `events`, `transitionCriteria`, `guardPrerequisites`, `humanCheckpoint`, and `compactGuidance` against what the agent actually did and what skill docs prescribe.
+
+**Playbook violations are diagnostic gold:**
+- Agent deviated and skill docs told it to → **documentation issue** (skill contradicts playbook)
+- Agent deviated and skill docs agree with playbook → **user error**
+- Playbook is wrong (prescribes invalid tools/events) → **code bug**
+
+#### 1d. Event Log Analysis
+
+Use `exarchos_event query(stream)` on the workflow's event stream. Look for:
+
+- **Rejected events** — absent from log despite agent attempts (corroborate with conversation errors)
+- **Missing events** — compare against playbook `events` field and `exarchos_event describe(emissionGuide: true)`. Missing model-emitted events = documentation gap or user error.
+- **Sequence anomalies** — wrong order, duplicates, or timeline gaps
+- **Schema mismatches** — use `describe(eventTypes: [...])` to get authoritative JSON Schema. Compare actual payloads against schema for semantically wrong fields.
+
+#### 1e. Orchestrate Action and Gate Analysis
+
+1. **Schema verification** — `exarchos_orchestrate describe(actions: [...])` for authoritative schemas. Compare agent's parameters against schema to detect stale skill docs or improvisation.
+2. **Gate metadata** — Describe output includes `{ blocking, dimension, autoEmits }`. Check: did the agent treat blocking/non-blocking correctly? Did expected auto-emissions fire?
+3. **Gate convergence** — `exarchos_view convergence` for per-dimension (D1-D5) pass rates. Low convergence suggests systemic gate issues.
+
+#### 1f. Runbook Conformance Check
+
+Use `exarchos_orchestrate runbook(phase)` to retrieve relevant runbooks. Check: step ordering, decision branch correctness (steps with `decide` fields), `onFail` directive adherence (`stop`/`continue`/`retry`), and `templateVars` completeness.
+
+#### 1g. Telemetry Review
+
+Use `exarchos_view telemetry` for per-tool performance. Flag: high error rates (systemic issues), high invocation counts (retry loops), and tools never invoked that the playbook prescribes.
+
+### Step 2: Scan Session for Failed Tool Calls
+
+Supplement the debug trace with client-side context — review conversation for failed Exarchos tool calls.
+
+**Note:** Platform-dependent step (requires conversation history). Skip on platforms without introspection; the debug trace is self-sufficient.
+
+**Target tools:** `exarchos_workflow`, `exarchos_event`, `exarchos_orchestrate`, `exarchos_view`, `exarchos_sync`
+
+**Error signals:** `INVALID_INPUT`, `VALIDATION_ERROR`, `BATCH_APPEND_FAILED`, Zod failures (`invalid_type`, `invalid_enum_value`, `unrecognized_keys`), `ENOENT`, `CLAIM_FAILED`, `SEQUENCE_CONFLICT`, CAS exhaustion, retry sequences, successful-after-retry calls.
+
+### Step 3: Diagnose Each Failure
+
+Merge debug trace and conversation scan findings. For each failure document:
+
+1. **What was attempted** — action, parameters, intent
+2. **What went wrong** — error message and validation path
+3. **Server-side evidence** — event log, state, describe output, views
+4. **Authoritative reference** — the self-service query providing ground truth (playbook, topology, schema, runbook)
+5. **Root cause** — per `references/root-cause-patterns.md`
+6. **Fix category** — code, docs, or user behavior
+
+Flag discrepancies only visible via server-side inspection as **trace-only findings**.
+
+### Step 4: Categorize into Buckets
+
+Assign each failure to exactly one root cause bucket:
+
+#### Bucket 1: Code Bug
+The MCP server, event store, or workflow engine has a defect.
+
+**Signals:** Schema rejects valid input (confirmed via `describe`), CAS failures with no concurrent writers, gate over-enforcement, identical-parameter retry succeeds (race condition), state corruption, topology/engine mismatch, auto-emission failure.
+
+**Action:** File bug issue with reproduction steps, expected vs actual, and suggested fix.
+
+#### Bucket 2: Documentation Issue
+Skill docs are wrong, incomplete, or out of sync with the MCP server's self-service output.
+
+**Signals:** Skill payload doesn't match `describe` schema, skill/playbook divergence, skill documents nonexistent topology paths, missing event types (compare emission guide), retry-based field discovery, runbook/skill contradictions, compactGuidance drift.
+
+**Action:** File docs issue with file:line, the discrepancy, and correct information from `describe` output.
+
+#### Bucket 3: User Error
+The agent misused a tool in a way both docs and `describe` output correctly describe.
+
+**Signals:** Format mismatch (confirmed by `describe` + docs agreement), invalid sequence (topology confirms), missing context both skill and playbook prescribe, runbook deviation without justification.
+
+**Action:** Note for skill improvement if errors are frequent.
+
+### Step 5: Generate Report
+
+Produce the report using the template from `references/report-template.md`. Include:
+- Summary counts per bucket
+- Debug trace summary (workflows inspected, events reviewed, describe queries issued, views consulted)
+- Each failure with full diagnosis (including authoritative self-service references)
+- Trace-only findings section (issues only visible via server-side inspection)
+- Playbook/runbook adherence summary
+- Actionable next steps (draft issue bodies for bugs/docs issues)
+
+### Step 6: Offer to File Issues
+
+For findings in the **Code Bug** and **Documentation Issue** buckets, offer to create GitHub issues:
+
+```bash
+gh issue create --title "<type>: <summary>" --body "<issue body>" --label "bug"
+```
+
+Only file issues with user confirmation — present the draft first.
+
+## Required Output Format
+
+```json
+{
+  "session_summary": {
+    "total_tool_calls": 0,
+    "failed_tool_calls": 0,
+    "failure_rate": "0%",
+    "debug_trace": {
+      "workflows_inspected": 0,
+      "events_reviewed": 0,
+      "describe_queries": 0,
+      "views_consulted": [],
+      "trace_only_findings": 0
+    }
+  },
+  "playbook_adherence": {
+    "phases_checked": 0,
+    "violations": [
+      {
+        "phase": "delegate",
+        "field": "events",
+        "expected": "team.spawned, team.task.assigned",
+        "actual": "none emitted",
+        "bucket": "documentation_issue"
+      }
+    ]
+  },
+  "runbook_conformance": {
+    "runbooks_checked": 0,
+    "deviations": []
+  },
+  "buckets": {
+    "code_bug": [],
+    "documentation_issue": [],
+    "user_error": []
+  },
+  "findings": [
+    {
+      "id": 1,
+      "bucket": "code_bug | documentation_issue | user_error",
+      "tool": "exarchos_workflow",
+      "action": "set",
+      "error": "INVALID_INPUT: ...",
+      "root_cause": "Schema rejects null branch on pending tasks",
+      "trace_evidence": "describe(actions: ['set']) shows branch as required string; event log confirms no task.updated event",
+      "authoritative_ref": "exarchos_workflow describe(actions: ['set']) → TaskSchema",
+      "severity": "HIGH | MEDIUM | LOW",
+      "suggested_fix": "Accept nullable branch in TaskSchema",
+      "issue_draft": {
+        "title": "bug: workflow task schema rejects null branch",
+        "labels": ["bug"],
+        "body": "..."
+      }
+    }
+  ],
+  "trace_only_findings": [
+    {
+      "id": "T1",
+      "description": "State drift: agent assumed phase was 'delegate' but server shows 'plan'",
+      "evidence": "exarchos_workflow get shows phase=plan; topology confirms plan→delegate requires planReviewComplete guard",
+      "authoritative_ref": "exarchos_workflow describe(topology: 'feature') → guards",
+      "bucket": "documentation_issue",
+      "suggested_fix": "Skill should instruct agent to verify phase via get before proceeding"
+    }
+  ]
+}
+```
+
+## Anti-Patterns
+
+| Don't | Do Instead |
+|-------|------------|
+| Skip the debug trace and only scan conversation | Always query MCP self-service tools first — conversation scan is supplementary |
+| Guess what the schema expects | Use `describe` to get authoritative schemas — they are the source of truth |
+| Assess playbook adherence from memory | Query `describe(playbook)` to get the actual prescribed tools, events, and criteria |
+| Assume the topology without checking | Query `describe(topology)` to get valid transitions, guards, and effects |
+| Blame the user when skill docs contradict the playbook | If skill docs diverge from playbook/describe output, it's a documentation issue |
+| File duplicate issues | Check existing open/closed issues before drafting |
+| Categorize retries as separate failures | Group retry sequences as a single finding |
+| Ignore successful-after-retry calls | These reveal friction even though they eventually worked |
+| Include non-Exarchos failures | Scope strictly to the 5 Exarchos tools — other MCP failures are out of scope |
+| Report conversation-only findings without trace corroboration | Cross-reference every finding with server-side state when possible |

package/skills/codex/dogfood/references/report-template.md

@@ -0,0 +1,109 @@
+# Dogfood Report Template
+
+```markdown
+## Dogfood Report
+
+**Session:** [workflow name or description]
+**Date:** [ISO 8601]
+**Workflow type:** [feature | debug | refactor | ad-hoc]
+
+### Summary
+
+| Metric | Value |
+|--------|-------|
+| Total Exarchos tool calls | X |
+| Failed tool calls | Y |
+| Failure rate | Z% |
+| Code bugs found | A |
+| Documentation issues found | B |
+| User errors found | C |
+
+### Debug Trace Summary
+
+| Metric | Value |
+|--------|-------|
+| Workflows inspected | X |
+| Events reviewed | Y |
+| Describe queries issued | Z |
+| Views consulted | [pipeline, convergence, telemetry, ...] |
+| Trace-only findings | W |
+
+### Playbook Adherence
+
+| Phase | Tools | Events | Transition Criteria | Guards | Verdict |
+|-------|-------|--------|-------------------|--------|---------|
+| [phase] | [match/mismatch] | [match/mismatch] | [match/mismatch] | [match/mismatch] | [OK/VIOLATION] |
+
+**Violations:**
+- [phase]: [playbook says X, agent did Y — bucket: documentation_issue/user_error]
+
+### Runbook Conformance
+
+| Runbook | Steps Executed | Deviations | Verdict |
+|---------|---------------|------------|---------|
+| [id] | X/Y | [list] | [OK/DEVIATED] |
+
+### Code Bugs
+
+#### [CB-1] [Title]
+- **Tool:** `exarchos_workflow` action `set`
+- **Error:** `INVALID_INPUT: ...`
+- **Root cause:** [diagnosis]
+- **Trace evidence:** [what describe/view/event query revealed]
+- **Authoritative ref:** [e.g., `describe(actions: ['set']) → TaskSchema`]
+- **Impact:** [blocked workflow / degraded experience / minor friction]
+- **Suggested fix:** [specific code change]
+- **Files:** [file:line references]
+
+### Documentation Issues
+
+#### [DOC-1] [Title]
+- **Tool:** `exarchos_event` action `append`
+- **Error:** `VALIDATION_ERROR: invalid_enum_value`
+- **Root cause:** [diagnosis — what the docs say vs what describe output shows]
+- **Trace evidence:** [describe output vs skill doc content]
+- **Authoritative ref:** [e.g., `describe(eventTypes: ['team.spawned']) → JSON Schema`]
+- **Skill/Reference:** [skills/X/SKILL.md:line or references/Y.md:line]
+- **Source of truth:** [describe action + servers/exarchos-mcp/src/file.ts:line]
+- **Suggested fix:** [update docs to match describe output]
+
+### User Errors
+
+#### [UE-1] [Title]
+- **Tool:** `exarchos_orchestrate` action `check_tdd_compliance`
+- **Error:** [error message]
+- **What happened:** [agent did X]
+- **What should have happened:** [both docs and describe agree on Y]
+- **Authoritative ref:** [confirm docs match describe/topology/playbook]
+- **Skill improvement:** [if the error is common, suggest making the skill clearer]
+
+### Trace-Only Findings
+
+Issues discovered solely through debug trace (not visible in conversation errors):
+
+#### [T-1] [Title]
+- **Discovery method:** [describe comparison / event log analysis / view query / playbook check]
+- **Evidence:** [what the trace revealed]
+- **Authoritative ref:** [which self-service query provided the ground truth]
+- **Bucket:** [code_bug / documentation_issue]
+- **Impact:** [silent data loss / state drift / stale guidance / playbook-skill divergence]
+- **Suggested fix:** [specific change]
+
+### Issue Drafts
+
+Ready-to-file issue bodies for Code Bugs and Documentation Issues:
+
+#### Issue: [CB-1 title]
+```
+gh issue create --title "bug: [summary]" --label "bug" --body "..."
+```
+
+#### Issue: [DOC-1 title]
+```
+gh issue create --title "docs: [summary]" --label "bug" --body "..."
+```
+
+### Patterns & Trends
+
+[Observations about recurring failure modes, systemic issues, or improvements to the dogfood process itself]
+```