workflow-spec

RagCode Agent Workflow Spec (v1)

RagCode Agent Workflows orchestrate multiple AI agents (codex, claude, gemini, grok, or any CLI in .ragcode/agents/agents.json) through a validated DAG. A workflow is a JSON file: explicit, reviewable, and validation-friendly.

This is a flexible workflow engine, not a fixed multi-agent command. The presets (consult, plan-execute-review, gemini-claude-codex-review) are convenience starting points — the engine supports arbitrary role-to-agent assignment, serial and parallel stages, review/fix loops, and explicit write permissions.

File location

Workflow specs live in .ragcode/agents/workflows/. Create the structure with:

ragcode agents init .

Spec shape

{
  "version": 1,
  "name": "gemini-claude-codex-review",
  "description": "Gemini plans, Claude analyzes and breaks down, Codex implements, Claude reviews.",
  "agents": {
    "planner":  { "provider": "gemini", "adapter": "cli", "role": "planning" },
    "analyst":  { "provider": "claude", "adapter": "cli", "role": "analysis_and_breakdown" },
    "executor": { "provider": "codex",  "adapter": "cli", "role": "implementation" },
    "reviewer": { "provider": "claude", "adapter": "cli", "role": "code_review" }
  },
  "workflow": [
    { "id": "plan",      "agent": "planner",  "kind": "plan",      "mode": "read_only", "output": "plan.md",
      "memoryPolicy": { "read": { "mode": "auto", "maxItems": 5, "maxChars": 6000 } } },
    { "id": "breakdown", "agent": "analyst",  "kind": "breakdown", "mode": "read_only", "dependsOn": ["plan"], "input": ["plan.md"], "output": "tasks.json" },
    { "id": "implement", "agent": "executor", "kind": "implement", "mode": "write", "dependsOn": ["breakdown"], "input": ["tasks.json"],
      "output": ["patch.diff", "test-report.json"],
      "writePolicy": { "mode": "workspace", "allowedPaths": ["src/**", "tests/**", "docs/**"] } },
    { "id": "review", "agent": "reviewer", "kind": "review", "mode": "read_only", "dependsOn": ["implement"], "input": ["patch.diff", "test-report.json"],
      "output": "review.json",
      "memoryPolicy": { "read": { "mode": "required" }, "write": { "mode": "verified", "allowedTypes": ["decision", "feedback"], "maxCandidates": 2 } },
      "toolPolicy": { "requiredCapabilities": ["ragcode.memory.read"] },
      "completionPolicy": { "requiredStructuredFields": ["verdict", "usedMemoryIds"], "requiredToolCalls": ["memory_query"], "requireMemoryContribution": true, "resultArtifactFormat": "json" },
      "resultArtifact": { "source": "final_text", "name": "review-result.json", "required": true },
      "gate": { "type": "review", "passRequired": true, "onFail": "implement_fix", "maxLoops": 3 } },
    { "id": "implement_fix", "agent": "executor", "kind": "fix", "mode": "write", "dependsOn": ["review"], "input": ["review.json"],
      "output": ["patch.diff", "test-report.json"],
      "writePolicy": { "mode": "workspace", "allowedPaths": ["src/**", "tests/**", "docs/**"] } }
  ],
  "finalGate": { "type": "verification", "commands": ["npm run check", "npm test"], "required": true }
}