[Feature]: Reusable Workflow Orchestration with Audit Trail

# [Feature]: Reusable Workflow Orchestration with Audit Trail

## Problem

QwenPaw already has multi-agent (`chat_with_agent`, `spawn_subagent`) and scheduling (`qwenpaw cron`). But there's no way to **define a reusable, multi-step workflow** that orchestrates these agents in a structured way, with full audit trail.

Currently, users rely on prompt-driven coordination — which is not reproducible, not auditable, and not API-triggerable.

### What's missing

| Capability | Current | Needed |
|---|---|---|
| Define a multi-step workflow once, run many times | ❌ | ✅ |
| Trigger via cron / API / chat command | Partial (cron only) | ✅ All three |
| Per-step input/output logging | ❌ | ✅ |
| Human approval gates between steps | `/approval` exists but not workflow-bound | ✅ |
| Resume from failed step | ❌ | ✅ |
| Query past runs (what ran, what passed, what failed) | ❌ | ✅ |

## Proposal

A **thin orchestration layer** on top of existing capabilities — not a new agent loop or plan engine.

### 1. Workflow Definition (YAML)

```yaml
name: content-pipeline
description: Research → Write → Image → Preflight
trigger:
- cron: "0 8 * * 1-5"
- api: POST /api/workflows/content-pipeline/run

steps:
- id: research
agent: research-agent
input: "Find trending topics this week"
output_to: topic_pool.json

- id: write
agent: writer-agent
depends_on: research
input: "Write articles based on {{research.output}}"

- id: preflight
agent: web-eng-agent
depends_on: write
require_approval: true

audit:
log_inputs: true
log_outputs: true
retention_days: 90
```

### 2. Trigger Sources

| Source | How |
|---|---|
| **Cron** | Reuse existing cron engine; set `trigger_source = workflow` |
| **API** | `POST /api/workflows/{name}/run` → returns `run_id` |
| **Manual** | Chat command: `/workflow run content-pipeline` |

### 3. Audit Trail

Each run automatically records:
- `run_id`, trigger source, timestamp, initiator
- Per-step: input, output, status, duration, agent used
- Approval gates: who approved, when, or denied
- Failure point + resume capability (re-run from failed step)

Query interface: `/workflow runs content-pipeline --last 10`

### 4. Schema (minimal)

```
workflow_definitions → id, yaml_content, version, created_at
workflow_runs → run_id, workflow_id, status, current_step, trigger_source, started_at, finished_at
workflow_step_runs → run_id, step_id, agent_id, status, input, output, started_at, finished_at
workflow_events → run_id, seq, event_type, payload, created_at
```

## Why This Approach

- **Doesn't change the existing multi-agent architecture** — it's a scheduler + logger on top
- **Reuses cron, `chat_with_agent`, and `/approval`** — no new subsystem needed
- **Familiar YAML definition** — same model as GitHub Actions / GitLab CI
- **Low implementation cost** — 4 tables + a runner loop + API endpoint

## Real-World Use Case

Content production pipeline:
1. Research agent → keyword mining + topic pool
2. Writer agent → draft articles based on research output
3. Image agent → generate illustrations
4. Web engineer agent → preflight check → **await human approval** → deploy

This workflow should run daily on cron, be triggerable via API for on-demand runs, and every execution should be fully auditable.

## References

- #508 (Multi-Agent Orchestration Gateway) — resolved by multi-agent support; this is the next layer
- #3224 (CoPaw Agent Teams) — covers AI-driven team formation; this proposal is about user-defined workflows
- #3873 (Workflow orchestration tools) — closed as "no plan"; this is a more specific, lower-cost proposal

## Acknowledgements

Inspired by real-world multi-agent workflow patterns seen in production deployments of QwenPaw.