Add multi-workflow support to job definition guidance

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

@@ -225,6 +225,8 @@ When defining steps, identify any that require specialized tools:
 
 **Browser Automation**: If any step involves web scraping, form filling, interactive browsing, UI testing, or research requiring website visits, ask the user what browser tools they have available. For Claude Code users, **Claude in Chrome** (Anthropic's browser extension) has been tested with DeepWork and is recommended for new users. Don't assume a default—confirm the tool before designing browser-dependent steps.
 
+**Multiple Workflows**: Most jobs have a single workflow, but consider defining multiple workflows when different parts need to happen at different points in time—for example, an analysis workflow that produces a report for human review, then a separate execution workflow to act on approved items. Other examples: `provision` + `teardown` for environment management, or `gather_data` + `finalize_report` for phased work. If the job needs multiple workflows, define them in a `workflows` section in job.yml.
+
 ### Step 3: Validate the Workflow
 
 After gathering information about all steps:
@@ -383,44 +385,36 @@ Claude: Great. Now for the "Research each one" step:
 
 [After gathering all information:]
 
-Claude: Let me summarize the workflow I've designed based on our conversation:
+Claude: Let me summarize the workflow I've designed:
 
 **Job: competitive_research**
 Summary: Systematic competitive analysis workflow for product positioning
 
 Description:
-A comprehensive workflow for analyzing competitors in your market segment. This job helps product teams understand the competitive landscape by systematically identifying competitors, researching their offerings, creating comparison matrices, and developing strategic positioning recommendations.
-
-The workflow produces:
-- A vetted list of key competitors
-- Detailed research notes on each competitor
-- A comparison matrix highlighting key differentiators
-- Strategic positioning recommendations
-
-Designed for product teams conducting quarterly competitive analysis.
+A comprehensive workflow for analyzing competitors in your market segment. Helps product teams understand the competitive landscape through systematic identification, research, comparison, and positioning recommendations.
 
 **Steps:**
 
-Step 1: identify_competitors
-- Input: market_segment (user), product_category (user)
-- Output: competitors_list.md (5-7 competitors with descriptions)
+1. **identify_competitors**
+   - Input: market_segment (user), product_category (user)
+   - Output: competitive_research/competitors_list.md
 
-Step 2: research_competitors
-- Input: competitors_list.md (from step 1)
-- Output: research_notes.md (detailed findings for each competitor)
-- Depends on: identify_competitors
+2. **research_competitors**
+   - Input: competitors_list.md (from step 1)
+   - Output: competitive_research/research_notes.md
+   - Depends on: identify_competitors
 
-Step 3: comparative_analysis
-- Input: research_notes.md (from step 2)
-- Output: comparison_matrix.md (side-by-side analysis)
-- Depends on: research_competitors
+3. **comparative_analysis**
+   - Input: research_notes.md (from step 2)
+   - Output: competitive_research/comparison_matrix.md
+   - Depends on: research_competitors
 
-Step 4: positioning_recommendations
-- Input: comparison_matrix.md (from step 3)
-- Output: positioning_report.md (strategic recommendations)
-- Depends on: comparative_analysis
+4. **positioning_recommendations**
+   - Input: comparison_matrix.md (from step 3)
+   - Output: competitive_research/positioning_report.md
+   - Depends on: comparative_analysis
 
-Does this accurately capture your workflow? Any changes needed?
+Does this accurately capture your workflow?
 
 User: Yes, that's perfect!
 
@@ -523,7 +517,8 @@ Use branch format: `deepwork/deepwork_jobs-[instance]-YYYYMMDD`
   7. **Valid Dependencies**: Dependencies must reference existing step IDs with no circular references
   8. **Input Consistency**: File inputs with `from_step` must reference a step that is in the dependencies array
   9. **Output Paths**: Outputs must be valid filenames or paths within the main repo directory structure, never in dot-directories like `.deepwork/`. Use specific, descriptive paths that lend themselves to glob patterns (e.g., `competitive_research/acme_corp/swot.md` or `operations/reports/2026-01/spending_analysis.md`). Parameterized paths like `[competitor_name]/` are encouraged for per-entity outputs. Avoid generic names (`output.md`, `analysis.md`) and transient-sounding paths (`temp/`, `draft.md`). Supporting materials for a final output should go in a peer `_dataroom` folder (e.g., `spending_analysis_dataroom/`).
-  10. **Concise Instructions**: The content of the file, particularly the description, must not have excessively redundant information. It should be concise and to the point given that extra tokens will confuse the AI.
+  10. **Valid Workflows**: If a `workflows` section is present, each workflow must have a unique name (lowercase_underscores), a summary, and a steps array. All step IDs referenced in workflows must exist in the steps section. Multiple workflows can share steps and define different execution paths through the same step set.
+  11. **Concise Instructions**: The content of the file, particularly the description, must not have excessively redundant information. It should be concise and to the point given that extra tokens will confuse the AI.
 
   <details>
   <summary>Example Document Structure</summary>
@@ -556,6 +551,36 @@ Use branch format: `deepwork/deepwork_jobs-[instance]-YYYYMMDD`
       changes: "Added quality validation hooks"
   ```
 
+  ### Workflows (Optional)
+
+  Jobs can define multiple workflows that use different combinations of the same steps:
+
+  ```yaml
+  workflows:
+    - name: full_analysis
+      summary: "Complete analysis with all steps"
+      steps:
+        - identify
+        - research
+        - analyze
+        - report
+
+    - name: quick_summary
+      summary: "Rapid analysis skipping deep research"
+      steps:
+        - identify
+        - report
+
+    - name: refresh
+      summary: "Update existing research"
+      steps:
+        - research
+        - analyze
+        - report
+  ```
+
+  If the `workflows` section is omitted, all steps form a single implicit workflow.
+
   ### Steps Array
 
   ```yaml
@@ -641,6 +666,7 @@ Use branch format: `deepwork/deepwork_jobs-[instance]-YYYYMMDD`
   3. **Unique step IDs**: No two steps can have the same id
   4. **Valid file paths**: Output paths must not contain invalid characters and should be in the main repo (not dot-directories)
   5. **Instructions files exist**: Each `instructions_file` path should have a corresponding file created
+  6. **Valid workflow references**: If workflows are defined, all step IDs in workflow steps arrays must exist in the steps section
 
   ## Example: Complete Job Specification
 
@@ -659,6 +685,21 @@ Use branch format: `deepwork/deepwork_jobs-[instance]-YYYYMMDD`
     - Comparison matrix
     - Strategic positioning report
 
+  # Multiple workflows using the same steps
+  workflows:
+    - name: full_analysis
+      summary: "Complete competitive analysis with all steps"
+      steps:
+        - identify_competitors
+        - research_competitors
+        - positioning_report
+
+    - name: quick_summary
+      summary: "Rapid analysis skipping deep research"
+      steps:
+        - identify_competitors
+        - positioning_report
+
   changelog:
     - version: "1.0.0"
       changes: "Initial job creation"

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

@@ -277,7 +277,8 @@ Use branch format: `deepwork/deepwork_jobs-[instance]-YYYYMMDD`
   7. **Valid Dependencies**: Dependencies must reference existing step IDs with no circular references
   8. **Input Consistency**: File inputs with `from_step` must reference a step that is in the dependencies array
   9. **Output Paths**: Outputs must be valid filenames or paths within the main repo directory structure, never in dot-directories like `.deepwork/`. Use specific, descriptive paths that lend themselves to glob patterns (e.g., `competitive_research/acme_corp/swot.md` or `operations/reports/2026-01/spending_analysis.md`). Parameterized paths like `[competitor_name]/` are encouraged for per-entity outputs. Avoid generic names (`output.md`, `analysis.md`) and transient-sounding paths (`temp/`, `draft.md`). Supporting materials for a final output should go in a peer `_dataroom` folder (e.g., `spending_analysis_dataroom/`).
-  10. **Concise Instructions**: The content of the file, particularly the description, must not have excessively redundant information. It should be concise and to the point given that extra tokens will confuse the AI.
+  10. **Valid Workflows**: If a `workflows` section is present, each workflow must have a unique name (lowercase_underscores), a summary, and a steps array. All step IDs referenced in workflows must exist in the steps section. Multiple workflows can share steps and define different execution paths through the same step set.
+  11. **Concise Instructions**: The content of the file, particularly the description, must not have excessively redundant information. It should be concise and to the point given that extra tokens will confuse the AI.
 
   <details>
   <summary>Example Document Structure</summary>
@@ -310,6 +311,36 @@ Use branch format: `deepwork/deepwork_jobs-[instance]-YYYYMMDD`
       changes: "Added quality validation hooks"
   ```
 
+  ### Workflows (Optional)
+
+  Jobs can define multiple workflows that use different combinations of the same steps:
+
+  ```yaml
+  workflows:
+    - name: full_analysis
+      summary: "Complete analysis with all steps"
+      steps:
+        - identify
+        - research
+        - analyze
+        - report
+
+    - name: quick_summary
+      summary: "Rapid analysis skipping deep research"
+      steps:
+        - identify
+        - report
+
+    - name: refresh
+      summary: "Update existing research"
+      steps:
+        - research
+        - analyze
+        - report
+  ```
+
+  If the `workflows` section is omitted, all steps form a single implicit workflow.
+
   ### Steps Array
 
   ```yaml
@@ -395,6 +426,7 @@ Use branch format: `deepwork/deepwork_jobs-[instance]-YYYYMMDD`
   3. **Unique step IDs**: No two steps can have the same id
   4. **Valid file paths**: Output paths must not contain invalid characters and should be in the main repo (not dot-directories)
   5. **Instructions files exist**: Each `instructions_file` path should have a corresponding file created
+  6. **Valid workflow references**: If workflows are defined, all step IDs in workflow steps arrays must exist in the steps section
 
   ## Example: Complete Job Specification
 
@@ -413,6 +445,21 @@ Use branch format: `deepwork/deepwork_jobs-[instance]-YYYYMMDD`
     - Comparison matrix
     - Strategic positioning report
 
+  # Multiple workflows using the same steps
+  workflows:
+    - name: full_analysis
+      summary: "Complete competitive analysis with all steps"
+      steps:
+        - identify_competitors
+        - research_competitors
+        - positioning_report
+
+    - name: quick_summary
+      summary: "Rapid analysis skipping deep research"
+      steps:
+        - identify_competitors
+        - positioning_report
+
   changelog:
     - version: "1.0.0"
       changes: "Initial job creation"

.deepwork/doc_specs/job_spec.md

@@ -24,6 +24,8 @@ quality_criteria:
     description: "File inputs with `from_step` must reference a step that is in the dependencies array"
   - name: Output Paths
     description: "Outputs must be valid filenames or paths within the main repo directory structure, never in dot-directories like `.deepwork/`. Use specific, descriptive paths that lend themselves to glob patterns (e.g., `competitive_research/acme_corp/swot.md` or `operations/reports/2026-01/spending_analysis.md`). Parameterized paths like `[competitor_name]/` are encouraged for per-entity outputs. Avoid generic names (`output.md`, `analysis.md`) and transient-sounding paths (`temp/`, `draft.md`). Supporting materials for a final output should go in a peer `_dataroom` folder (e.g., `spending_analysis_dataroom/`)."
+  - name: Valid Workflows
+    description: "If a `workflows` section is present, each workflow must have a unique name (lowercase_underscores), a summary, and a steps array. All step IDs referenced in workflows must exist in the steps section. Multiple workflows can share steps and define different execution paths through the same step set."
   - name: Concise Instructions
     description: "The content of the file, particularly the description, must not have excessively redundant information. It should be concise and to the point given that extra tokens will confuse the AI."
 ---
@@ -55,6 +57,36 @@ changelog:
     changes: "Added quality validation hooks"
 ```
 
+### Workflows (Optional)
+
+Jobs can define multiple workflows that use different combinations of the same steps:
+
+```yaml
+workflows:
+  - name: full_analysis
+    summary: "Complete analysis with all steps"
+    steps:
+      - identify
+      - research
+      - analyze
+      - report
+
+  - name: quick_summary
+    summary: "Rapid analysis skipping deep research"
+    steps:
+      - identify
+      - report
+
+  - name: refresh
+    summary: "Update existing research"
+    steps:
+      - research
+      - analyze
+      - report
+```
+
+If the `workflows` section is omitted, all steps form a single implicit workflow.
+
 ### Steps Array
 
 ```yaml
@@ -140,6 +172,7 @@ steps:
 3. **Unique step IDs**: No two steps can have the same id
 4. **Valid file paths**: Output paths must not contain invalid characters and should be in the main repo (not dot-directories)
 5. **Instructions files exist**: Each `instructions_file` path should have a corresponding file created
+6. **Valid workflow references**: If workflows are defined, all step IDs in workflow steps arrays must exist in the steps section
 
 ## Example: Complete Job Specification
 
@@ -158,6 +191,21 @@ description: |
   - Comparison matrix
   - Strategic positioning report
 
+# Multiple workflows using the same steps
+workflows:
+  - name: full_analysis
+    summary: "Complete competitive analysis with all steps"
+    steps:
+      - identify_competitors
+      - research_competitors
+      - positioning_report
+
+  - name: quick_summary
+    summary: "Rapid analysis skipping deep research"
+    steps:
+      - identify_competitors
+      - positioning_report
+
 changelog:
   - version: "1.0.0"
     changes: "Initial job creation"

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

@@ -24,6 +24,8 @@ quality_criteria:
     description: "File inputs with `from_step` must reference a step that is in the dependencies array"
   - name: Output Paths
     description: "Outputs must be valid filenames or paths within the main repo directory structure, never in dot-directories like `.deepwork/`. Use specific, descriptive paths that lend themselves to glob patterns (e.g., `competitive_research/acme_corp/swot.md` or `operations/reports/2026-01/spending_analysis.md`). Parameterized paths like `[competitor_name]/` are encouraged for per-entity outputs. Avoid generic names (`output.md`, `analysis.md`) and transient-sounding paths (`temp/`, `draft.md`). Supporting materials for a final output should go in a peer `_dataroom` folder (e.g., `spending_analysis_dataroom/`)."
+  - name: Valid Workflows
+    description: "If a `workflows` section is present, each workflow must have a unique name (lowercase_underscores), a summary, and a steps array. All step IDs referenced in workflows must exist in the steps section. Multiple workflows can share steps and define different execution paths through the same step set."
   - name: Concise Instructions
     description: "The content of the file, particularly the description, must not have excessively redundant information. It should be concise and to the point given that extra tokens will confuse the AI."
 ---
@@ -55,6 +57,36 @@ changelog:
     changes: "Added quality validation hooks"
 ```
 
+### Workflows (Optional)
+
+Jobs can define multiple workflows that use different combinations of the same steps:
+
+```yaml
+workflows:
+  - name: full_analysis
+    summary: "Complete analysis with all steps"
+    steps:
+      - identify
+      - research
+      - analyze
+      - report
+
+  - name: quick_summary
+    summary: "Rapid analysis skipping deep research"
+    steps:
+      - identify
+      - report
+
+  - name: refresh
+    summary: "Update existing research"
+    steps:
+      - research
+      - analyze
+      - report
+```
+
+If the `workflows` section is omitted, all steps form a single implicit workflow.
+
 ### Steps Array
 
 ```yaml
@@ -140,6 +172,7 @@ steps:
 3. **Unique step IDs**: No two steps can have the same id
 4. **Valid file paths**: Output paths must not contain invalid characters and should be in the main repo (not dot-directories)
 5. **Instructions files exist**: Each `instructions_file` path should have a corresponding file created
+6. **Valid workflow references**: If workflows are defined, all step IDs in workflow steps arrays must exist in the steps section
 
 ## Example: Complete Job Specification
 
@@ -158,6 +191,21 @@ description: |
   - Comparison matrix
   - Strategic positioning report
 
+# Multiple workflows using the same steps
+workflows:
+  - name: full_analysis
+    summary: "Complete competitive analysis with all steps"
+    steps:
+      - identify_competitors
+      - research_competitors
+      - positioning_report
+
+  - name: quick_summary
+    summary: "Rapid analysis skipping deep research"
+    steps:
+      - identify_competitors
+      - positioning_report
+
 changelog:
   - version: "1.0.0"
     changes: "Initial job creation"