workflow-agent-spec

Agent Specification: Workflow Agent

1. Agent Overview

| Attribute | Value | |-----------|-------| | **Name** | Workflow Agent | | **ID** | research-workflow-agent | | **Purpose** | Orchestrate multi-stage research pipelines, manage DAG-based task dependencies, track progress, and handle failures with recovery | | **Lifecycle Stage** | Orchestration (coordinates all stages) | | **Model** | sonnet | | **Version** | 1.0.0 | | **Status** | Draft |

Description

The Workflow Agent is the conductor of the Research Framework orchestra, orchestrating complex multi-stage workflows from discovery through archival. It creates and executes DAG-based (Directed Acyclic Graph) task dependencies, manages parallel execution with configurable concurrency, tracks real-time progress, handles stage failures with retry and recovery options, and generates comprehensive workflow reports. The agent enables users to complete complex research tasks (e.g., "comprehensive literature review on topic X") with a single command.

2. Capabilities

Primary Capabilities

| Capability | Description | NFR Reference | |------------|-------------|---------------| | DAG Construction | Build task dependency graphs from workflow templates | BR-WF-001 | | Stage Orchestration | Execute stages in correct order with dependency enforcement | NFR-WF-03 | | Parallel Execution | Run independent tasks concurrently with limits | NFR-WF-02 | | Progress Tracking | Real-time status updates and time estimation | NFR-WF-04 | | Failure Recovery | Resume from checkpoints, skip/retry failed tasks | NFR-WF-03 | | Workflow Reporting | Generate completion reports with metrics | NFR-WF-05 |

Secondary Capabilities

| Capability | Description | |------------|-------------| | Dynamic Target Adjustment | Increase sources if quality filtering reduces count | | Timeout Management | Enforce and extend stage timeouts | | Partial Workflow | Execute subset of stages per user request | | Workflow Templates | Pre-defined patterns for common research tasks |

3. Tools

Required Tools

| Tool | Purpose | Permission | |------|---------|------------| | Bash | Execute agent commands, manage processes | Execute | | Read | Access workflow templates, status files | Read | | Write | Save status, reports, checkpoints | Write | | Glob | Find workflow artifacts | Read |

Agent Communication

| Agent | Interaction Type | |-------|------------------| | Discovery Agent | Task assignment, result collection | | Acquisition Agent | Task assignment, result collection | | Documentation Agent | Task assignment, result collection | | Quality Agent | Task assignment, result collection | | Citation Agent | Task assignment, result collection | | Archival Agent | Task assignment, result collection | | Provenance Agent | Event notification |

4. Triggers

Manual Triggers

| Trigger | Command | Description | |---------|---------|-------------| | Full Workflow | `aiwg research workflow "topic" --deliverable TYPE` | Execute complete pipeline | | Resume Workflow | `aiwg research workflow --resume WF-ID` | Resume from checkpoint | | Partial Workflow | `aiwg research workflow --stages "discovery,documentation"` | Execute subset | | Workflow Status | `aiwg research workflow --status WF-ID` | Check progress | | Abort Workflow | `aiwg research workflow --abort WF-ID` | Cancel execution |

Internal Triggers

| Trigger | Condition | Action | |---------|-----------|--------| | Stage Complete | Agent reports success | Start dependent stages | | Stage Failed | Agent reports failure | Prompt for recovery action | | Quality Gate | Quality scores available | Filter or supplement sources | | Timeout | Stage exceeds limit | Prompt for extension/abort |

5. Inputs/Outputs

Inputs

| Input | Format | Source | Validation | |-------|--------|--------|------------| | Research Topic | String | User command | Non-empty | | Deliverable Type | Enum | User command | Valid type | | Source Target | Integer | Optional flag | 1-100 range | | Quality Threshold | Integer | Optional flag | 0-100 range | | Stage Selection | Array | Optional flag | Valid stage names | | Workflow ID | String | Resume command | Valid WF-ID exists |

Outputs

| Output | Format | Location | Retention | |--------|--------|----------|-----------| | Workflow Status | JSON | `.aiwg/research/workflows/{WF-ID}-status.json` | Permanent | | Workflow Summary | Markdown | `.aiwg/research/workflows/{WF-ID}-summary.md` | Permanent | | Research Deliverable | Markdown | `.aiwg/research/outputs/` | Permanent | | Stage Logs | Text | `.aiwg/research/workflows/{WF-ID}-logs/` | 30 days | | DAG Visualization | DOT | `.aiwg/research/workflows/{WF-ID}-dag.dot` | Permanent |

Output Schema: Workflow Status JSON

{
  "workflow_id": "WF-2026-01-25-001",
  "topic": "Agentic AI frameworks",
  "deliverable": "comprehensive-literature-review",
  "status": "IN_PROGRESS",
  "progress_percent": 67,
  "start_time": "2026-01-25T10:00:00Z",
  "estimated_completion": "2026-01-25T12:15:00Z",
  "stages": [
    {
      "stage_id": 1,
      "name": "Discovery",
      "status": "COMPLETE",
      "start_time": "2026-01-25T10:00:00Z",
      "end_time": "2026-01-25T10:15:00Z",
      "items_processed": 25,
      "items_total": 25
    },
    {
      "stage_id": 2,
      "name": "Acquisition",
      "status": "COMPLETE",
      "start_time": "2026-01-25T10:15:00Z",
      "end_time": "2026-01-25T10:45:00Z",
      "items_processed": 25,
      "items_total": 25
    },
    {
      "stage_id": 3,
      "name": "Documentation",
      "status": "COMPLETE",
      "start_time": "2026-01-25T10:45:00Z",
      "end_time": "2026-01-25T11:15:00Z",
      "items_processed": 25,
      "items_total": 25
    },
    {
      "stage_id": 4,
      "name": "Quality",
      "status": "IN_PROGRESS",
      "start_time": "2026-01-25T11:15:00Z",
      "items_processed": 15,
      "items_total": 25
    },
    {
      "stage_id": 5,
      "name": "Integratio