Exarchos workflow tool pitfalls and workarounds

[rsalus]

Summary

Documenting recurring issues encountered when using the Exarchos workflow state management tools (mcp__plugin_exarchos_exarchos__exarchos_workflow). These caused delays during the e2e-wiring and refactor-remove-mockdata workflows.

Pitfalls

1. Task completion guard blocks phase transition

Error: Guard 'all-tasks-complete' failed: all-tasks-complete not satisfied: 10 task(s) incomplete

Cause: When using team-based delegation, agents update the TeamCreate task list — but the exarchos workflow state has its OWN separate tasks array that must also be updated. The team task list and workflow state tasks are independent.

Fix: Before transitioning to review phase, explicitly set all workflow state tasks to status: "complete":

{
  "action": "set",
  "featureId": "...",
  "updates": { "tasks": [{ "id": "1", "status": "complete" }, ...] }
}

Then transition phase separately.

2. Reviews must be an object, not an array

Error: Write-time validation failed: Expected object, received array when setting reviews

Cause: The reviews field expects a keyed object, not an array.

Fix: Use object with named keys:

{
  "reviews": {
    "spec-compliance": { "status": "pass", "issues": [] },
    "code-quality": { "status": "pass", "issues": [] }
  }
}

3. Refactor workflow has specific phase names

Error: No transition from 'explore' to 'plan' and No transition from 'brief' to 'plan'

Cause: Refactor workflows use different phase names than feature workflows. The valid transitions are:

• explore → brief (requires scope-assessment-complete guard)
• brief → overhaul-plan (requires overhaul-track-selected guard)
• brief → polish-implement (requires polish-track-selected guard)

Fix: For overhaul refactors, use overhaul-plan instead of plan.

4. Graphite gt track times out (interactive)

Error: gt track --force times out via MCP tool

Cause: gt track prompts interactively to select a parent branch.

Fix: Use the legacy gt branch track --parent main <branch-name> command via Bash instead of the MCP tool:

gt branch track --parent main e2e-wiring

5. Intelligence endpoint URL mismatch

Error: POST /api/analyze HTTP/1.1 404 Not Found

Cause: Python FastAPI mounts the router at /analyze (in main.py), but IntelligenceClient.cs called /api/analyze.

Fix: Always check main.py for the actual include_router prefix before hardcoding URLs.

Impact

Each of these caused 1-3 wasted tool calls and required workarounds. Documenting here so future sessions can avoid them.