Add workflow-level agent field for sub-agent delegation (#239)

* Add optional workflow-level `agent` field for sub-agent delegation

When a workflow's `agent` field is set in job.yml, the `get_workflows`
MCP response includes a `how_to_invoke` field instructing callers to
delegate the entire workflow to a sub-agent of that type via the Task
tool. This is distinct from the existing step-level `agent` field —
this delegates the whole workflow, not individual steps.

Changes:
- Schema: added optional `agent` to `$defs/workflow`
- Parser: `Workflow.agent` field + `from_dict` update
- MCP: `WorkflowInfo.how_to_invoke` populated from `wf.agent`
- Docs: updated mcp_interface.md with new field + changelog
- Tests: 7 new tests across parser, validation, schemas, tools

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Update flake.lock

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Address review findings: specs, traceability, docs, lint fixes

- Add JOBS-REQ-002.8.8 for optional workflow `agent` field
- Add JOBS-REQ-001.2.6-8 for `how_to_invoke` in get_workflows response
- Add traceability comments to all new tests
- Update doc/architecture.md with workflow agent/how_to_invoke docs
- Fix pre-existing mypy issues in test files (lint review)
- Reformat f-string quoting in tools.py (ruff format)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Always populate how_to_invoke with invocation instructions

Instead of returning null when no agent is set, how_to_invoke now
always contains instructions: either to delegate via Task tool (when
agent is set) or to call start_workflow MCP tool directly (default).

Updated specs, docs, and tests to reflect the non-nullable field.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Use full MCP tool name in how_to_invoke instructions

Reference mcp__plugin_deepwork_deepwork__start_workflow instead of
generic "start_workflow DeepWork MCP tool" so agents can find the
exact tool to call.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: nhorton

doc/architecture.md

@@ -963,7 +963,7 @@ Lists all available workflows from `.deepwork/jobs/`.
 
 **Parameters**: None
 
-**Returns**: List of jobs with their workflows, steps, and summaries
+**Returns**: List of jobs with their workflows, steps, and summaries. Each `WorkflowInfo` includes a `how_to_invoke` field with invocation instructions: when the workflow's `agent` field is set in job.yml, it directs callers to delegate via the Task tool; otherwise, it directs callers to use the `start_workflow` MCP tool directly.
 
 #### 2. `start_workflow`
 Begins a new workflow session.

doc/mcp_interface.md

@@ -41,6 +41,7 @@ interface JobInfo {
 interface WorkflowInfo {
   name: string;              // Workflow identifier
   summary: string;           // Short description
+  how_to_invoke: string;        // Instructions for how to invoke this workflow
 }
 ```
 
@@ -397,6 +398,7 @@ Add to your `.mcp.json`:
 
 | Version | Changes |
 |---------|---------|
+| 1.8.0 | Added `how_to_invoke` field to `WorkflowInfo` in `get_workflows` response. Always populated with invocation instructions: when a workflow's `agent` field is set, directs callers to delegate via the Task tool; otherwise, directs callers to use the `start_workflow` MCP tool directly. Also added optional `agent` field to workflow definitions in job.yml. |
 | 1.7.0 | Added `mark_review_as_passed` tool for review pass caching. Instruction files now include an "After Review" section with the review ID. Reviews with a `.passed` marker are automatically skipped by `get_review_instructions`. |
 | 1.6.0 | Added `get_configured_reviews` tool for listing configured review rules without running the full pipeline. Supports optional file-based filtering. |
 | 1.5.0 | Added `get_review_instructions` tool (originally named `review`) for running `.deepreview`-based code reviews via MCP. Added `--platform` CLI option to `serve` command. |

flake.lock

@@ -28,9 +28,12 @@ The DeepWork MCP server exposes four tools to AI agents via the Model Context Pr
 3. The tool MUST return a dictionary with a `jobs` key containing a list of job info objects.
 4. Each job info object MUST contain `name`, `summary`, and `workflows` fields.
 5. Each workflow info object MUST contain `name` and `summary` fields.
-6. The tool MUST also return an `errors` key containing a list of job load error objects for any jobs that failed to parse.
-7. Each job load error object MUST contain `job_name`, `job_dir`, and `error` fields.
-8. The tool MUST load jobs from all configured job folders (see JOBS-REQ-008).
+6. Each workflow info object MUST contain a `how_to_invoke` field (string) with invocation instructions.
+7. When a workflow's `agent` field is set in job.yml, `how_to_invoke` MUST contain instructions for delegating the workflow to a sub-agent of the specified type via the Task tool. The instructions MUST include the agent type, job name, and workflow name.
+8. When a workflow's `agent` field is not set, `how_to_invoke` MUST contain instructions to call the `start_workflow` MCP tool directly with the job name and workflow name.
+9. The tool MUST also return an `errors` key containing a list of job load error objects for any jobs that failed to parse.
+10. Each job load error object MUST contain `job_name`, `job_dir`, and `error` fields.
+11. The tool MUST load jobs from all configured job folders (see JOBS-REQ-008).
 
 ### JOBS-REQ-001.3: start_workflow Tool
 

specs/deepwork/jobs/JOBS-REQ-001-mcp-workflow-tools.md

@@ -80,6 +80,7 @@ Job definitions are YAML files (`job.yml`) that declare multi-step workflows for
 5. Each workflow step entry MUST be either a step ID string (sequential execution) or an array of step ID strings (concurrent execution).
 6. When a step entry is a string, it SHALL be parsed as a `WorkflowStepEntry` with `is_concurrent=False`.
 7. When a step entry is a list, it SHALL be parsed as a `WorkflowStepEntry` with `is_concurrent=True`.
+8. Workflows MAY have an optional `agent` field. When present, it MUST be a non-empty string specifying the agent type for delegating the entire workflow to a sub-agent.
 
 ### JOBS-REQ-002.9: Semantic Validation - Dependencies
 

specs/deepwork/jobs/JOBS-REQ-002-job-definition-parsing.md

@@ -84,6 +84,11 @@
           "items": {
             "$ref": "#/$defs/workflowStepEntry"
           }
+        },
+        "agent": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Agent type to run the entire workflow in (e.g., 'general-purpose'). When set, the workflow is designed to be delegated wholesale to a sub-agent of this type via the Task tool. This is for workflows where the entire execution should happen in a sub-agent — not for delegating individual steps within a workflow (use step-level 'agent' for that)."
         }
       }
     },

src/deepwork/jobs/job.schema.json

@@ -59,6 +59,9 @@ class WorkflowInfo(BaseModel):
 
     name: str = Field(description="Workflow identifier")
     summary: str = Field(description="Short description of workflow")
+    how_to_invoke: str = Field(
+        description="Instructions for how to invoke this workflow (e.g., directly via MCP tools, or delegated to a sub-agent)",
+    )
 
 
 class JobInfo(BaseModel):

src/deepwork/jobs/mcp/schemas.py

@@ -97,13 +97,29 @@ def _job_to_info(self, job: JobDefinition) -> JobInfo:
             JobInfo with workflow details
         """
         # Convert workflows
-        workflows = [
-            WorkflowInfo(
-                name=wf.name,
-                summary=wf.summary,
+        workflows = []
+        for wf in job.workflows:
+            if wf.agent:
+                how_to_invoke = (
+                    f'Invoke as a Task using subagent_type="{wf.agent}" with a prompt '
+                    f"giving full context needed and instructions to call "
+                    f"`mcp__plugin_deepwork_deepwork__start_workflow` "
+                    f'(job_name="{job.name}", workflow_name="{wf.name}"). '
+                    f"If you do not have Task as an available tool, invoke the workflow directly."
+                )
+            else:
+                how_to_invoke = (
+                    f"Call `mcp__plugin_deepwork_deepwork__start_workflow` with "
+                    f'job_name="{job.name}" and workflow_name="{wf.name}", '
+                    f"then follow the step instructions it returns."
+                )
+            workflows.append(
+                WorkflowInfo(
+                    name=wf.name,
+                    summary=wf.summary,
+                    how_to_invoke=how_to_invoke,
+                )
             )
-            for wf in job.workflows
-        ]
 
         return JobInfo(
             name=job.name,

src/deepwork/jobs/mcp/tools.py

@@ -240,6 +240,10 @@ class Workflow:
     summary: str
     step_entries: list[WorkflowStepEntry]  # List of step entries (sequential or concurrent)
 
+    # Agent type for this workflow (e.g., "general-purpose"). When set, the entire
+    # workflow should be delegated to a sub-agent of this type via the Task tool.
+    agent: str | None = None
+
     @property
     def steps(self) -> list[str]:
         """Get flattened list of all step IDs for backward compatibility."""
@@ -270,6 +274,7 @@ def from_dict(cls, data: dict[str, Any]) -> "Workflow":
             name=data["name"],
             summary=data["summary"],
             step_entries=step_entries,
+            agent=data.get("agent"),
         )
 
 

src/deepwork/jobs/parser.py

@@ -9,6 +9,7 @@ common_job_info_provided_to_all_steps_at_runtime: |
 workflows:
   - name: full_analysis
     summary: "Complete analysis workflow with parallel research phase"
+    agent: "general-purpose"
     steps:
       - setup
       - [research_web, research_docs, research_interviews]