feat: Add agent delegation field to job.yml steps (#188)

When a step specifies an `agent` field (e.g., `agent: general-purpose`),
the generated skill will include `context: fork` and `agent: <value>`.
This enables steps to delegate execution to specific agent types.

Changes:
- Add `agent` field to Step class in parser.py
- Add `agent` to job schema validation in job_schema.py
- Pass agent to template context in generator.py
- Update Claude skill template to emit context: fork when agent is set
- Update job.yml.template with agent option comment
- Update job_spec.md doc spec with Agent Delegation section
- Update define.md step instructions with agent delegation guidance

https://claude.ai/code/session_01GaqLCGFqkvUsvpqUVqB9G9

Co-authored-by: Claude <[email protected]>

Author: nhorton

.claude/skills/deepwork_jobs.define/SKILL.md

@@ -192,6 +192,19 @@ For each major phase they mentioned, ask structured questions to gather details:
    - Are there any quality checks or validation needed?
    - What makes a good vs. bad output for this step?
 
+6. **Agent Delegation** (optional)
+   - Should this step be executed by a specific agent type?
+   - Use the `agent` field when the step should run in a forked context with a specific agent
+   - When `agent` is set, the generated skill automatically includes `context: fork`
+   - Available agent types:
+     - `general-purpose` - Standard agent for multi-step tasks
+
+   ```yaml
+   steps:
+     - id: research_step
+       agent: general-purpose  # Delegates to the general-purpose agent
+   ```
+
 **Note**: You're gathering this information to understand what instructions will be needed, but you won't create the instruction files yet - that happens in the `implement` step.
 
 #### Doc Spec-Aware Output Format
@@ -578,6 +591,19 @@ Use branch format: `deepwork/deepwork_jobs-[instance]-YYYYMMDD`
       exposed: true                 # Makes step available without running dependencies
   ```
 
+  ### Agent Delegation
+
+  When a step should be executed by a specific agent type, use the `agent` field. This automatically sets `context: fork` in the generated skill.
+
+  ```yaml
+  steps:
+    - id: research_step
+      agent: general-purpose        # Delegates to the general-purpose agent
+  ```
+
+  Available agent types:
+  - `general-purpose` - Standard agent for multi-step tasks
+
   ### Quality Hooks
 
   ```yaml

.claude/skills/deepwork_jobs.review_job_spec/SKILL.md

@@ -345,6 +345,19 @@ Use branch format: `deepwork/deepwork_jobs-[instance]-YYYYMMDD`
       exposed: true                 # Makes step available without running dependencies
   ```
 
+  ### Agent Delegation
+
+  When a step should be executed by a specific agent type, use the `agent` field. This automatically sets `context: fork` in the generated skill.
+
+  ```yaml
+  steps:
+    - id: research_step
+      agent: general-purpose        # Delegates to the general-purpose agent
+  ```
+
+  Available agent types:
+  - `general-purpose` - Standard agent for multi-step tasks
+
   ### Quality Hooks
 
   ```yaml

.deepwork/doc_specs/job_spec.md

@@ -90,6 +90,19 @@ steps:
     exposed: true                 # Makes step available without running dependencies
 ```
 
+### Agent Delegation
+
+When a step should be executed by a specific agent type, use the `agent` field. This automatically sets `context: fork` in the generated skill.
+
+```yaml
+steps:
+  - id: research_step
+    agent: general-purpose        # Delegates to the general-purpose agent
+```
+
+Available agent types:
+- `general-purpose` - Standard agent for multi-step tasks
+
 ### Quality Hooks
 
 ```yaml

.deepwork/jobs/deepwork_jobs/doc_specs/job_spec.md

@@ -90,6 +90,19 @@ steps:
     exposed: true                 # Makes step available without running dependencies
 ```
 
+### Agent Delegation
+
+When a step should be executed by a specific agent type, use the `agent` field. This automatically sets `context: fork` in the generated skill.
+
+```yaml
+steps:
+  - id: research_step
+    agent: general-purpose        # Delegates to the general-purpose agent
+```
+
+Available agent types:
+- `general-purpose` - Standard agent for multi-step tasks
+
 ### Quality Hooks
 
 ```yaml

.deepwork/jobs/deepwork_jobs/steps/define.md

@@ -172,6 +172,19 @@ For each major phase they mentioned, ask structured questions to gather details:
    - Are there any quality checks or validation needed?
    - What makes a good vs. bad output for this step?
 
+6. **Agent Delegation** (optional)
+   - Should this step be executed by a specific agent type?
+   - Use the `agent` field when the step should run in a forked context with a specific agent
+   - When `agent` is set, the generated skill automatically includes `context: fork`
+   - Available agent types:
+     - `general-purpose` - Standard agent for multi-step tasks
+
+   ```yaml
+   steps:
+     - id: research_step
+       agent: general-purpose  # Delegates to the general-purpose agent
+   ```
+
 **Note**: You're gathering this information to understand what instructions will be needed, but you won't create the instruction files yet - that happens in the `implement` step.
 
 #### Doc Spec-Aware Output Format

.deepwork/jobs/deepwork_jobs/templates/job.yml.template

@@ -34,6 +34,8 @@ steps:
     outputs:
       - [output_filename_or_path]  # e.g., "report.md" or "reports/analysis.md"
     dependencies: []  # List of step IDs that must complete first
+    # Optional: Delegate to a specific agent type (uses context: fork)
+    # agent: general-purpose  # or other agent type
     # Optional: Quality validation hooks
     hooks:
       after_agent:

.gemini/skills/deepwork_jobs/define.toml

@@ -192,6 +192,19 @@ For each major phase they mentioned, ask structured questions to gather details:
    - Are there any quality checks or validation needed?
    - What makes a good vs. bad output for this step?
 
+6. **Agent Delegation** (optional)
+   - Should this step be executed by a specific agent type?
+   - Use the `agent` field when the step should run in a forked context with a specific agent
+   - When `agent` is set, the generated skill automatically includes `context: fork`
+   - Available agent types:
+     - `general-purpose` - Standard agent for multi-step tasks
+
+   ```yaml
+   steps:
+     - id: research_step
+       agent: general-purpose  # Delegates to the general-purpose agent
+   ```
+
 **Note**: You're gathering this information to understand what instructions will be needed, but you won't create the instruction files yet - that happens in the `implement` step.
 
 #### Doc Spec-Aware Output Format

CHANGELOG.md

@@ -8,6 +8,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 ### Added
+- Agent delegation field for job.yml steps
+  - New `agent` field on steps allows specifying an agent type (e.g., `agent: general-purpose`)
+  - When `agent` is set, generated Claude Code skills automatically include `context: fork` and `agent:` in frontmatter
+  - Enables steps to delegate execution to specific agent types
+  - Updated `deepwork_jobs.define` step instructions with agent delegation guidance
+  - Updated `job_spec.md` doc spec with "Agent Delegation" section
 - Explicit workflow definitions in job.yml for distinguishing multi-step workflows from standalone skills
   - New `workflows` section in job.yml with `name`, `summary`, and ordered `steps` array
   - Workflows are shown separately from standalone skills in generated meta-skills

src/deepwork/core/generator.py

@@ -311,6 +311,7 @@ def _build_step_context(
             "hooks": hooks,  # New: all hooks by platform event name
             "stop_hooks": stop_hooks,  # Backward compat: after_agent hooks only
             "quality_criteria": step.quality_criteria,  # Declarative criteria with framing
+            "agent": step.agent,  # Agent type (e.g., "general-purpose") - triggers context: fork
         }
 
         # Add workflow context if step is part of a workflow

src/deepwork/core/parser.py

@@ -142,6 +142,9 @@ class Step:
     # Declarative quality criteria rendered with standard evaluation framing
     quality_criteria: list[str] = field(default_factory=list)
 
+    # Agent type for this step (e.g., "general-purpose"). When set, skill uses context: fork
+    agent: str | None = None
+
     @property
     def stop_hooks(self) -> list[HookAction]:
         """
@@ -180,6 +183,7 @@ def from_dict(cls, data: dict[str, Any]) -> "Step":
             hooks=hooks,
             exposed=data.get("exposed", False),
             quality_criteria=data.get("quality_criteria", []),
+            agent=data.get("agent"),
         )