diff --git a/.claude/skills/deepwork_jobs.define/SKILL.md b/.claude/skills/deepwork_jobs.define/SKILL.md index f1469253..f7e0f485 100644 --- a/.claude/skills/deepwork_jobs.define/SKILL.md +++ b/.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.
Example Document Structure @@ -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" diff --git a/.claude/skills/deepwork_jobs.review_job_spec/SKILL.md b/.claude/skills/deepwork_jobs.review_job_spec/SKILL.md index 51b8ed54..8a6e57be 100644 --- a/.claude/skills/deepwork_jobs.review_job_spec/SKILL.md +++ b/.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.
Example Document Structure @@ -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" diff --git a/.deepwork/doc_specs/job_spec.md b/.deepwork/doc_specs/job_spec.md index b880bb17..ff3cd1cc 100644 --- a/.deepwork/doc_specs/job_spec.md +++ b/.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" diff --git a/.deepwork/jobs/deepwork_jobs/doc_specs/job_spec.md b/.deepwork/jobs/deepwork_jobs/doc_specs/job_spec.md index b880bb17..ff3cd1cc 100644 --- a/.deepwork/jobs/deepwork_jobs/doc_specs/job_spec.md +++ b/.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" diff --git a/.deepwork/jobs/deepwork_jobs/steps/define.md b/.deepwork/jobs/deepwork_jobs/steps/define.md index 31de7440..b6798628 100644 --- a/.deepwork/jobs/deepwork_jobs/steps/define.md +++ b/.deepwork/jobs/deepwork_jobs/steps/define.md @@ -205,6 +205,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: @@ -363,44 +365,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! diff --git a/.deepwork/jobs/deepwork_jobs/templates/job.yml.example b/.deepwork/jobs/deepwork_jobs/templates/job.yml.example index 7cc6e3bb..61784053 100644 --- a/.deepwork/jobs/deepwork_jobs/templates/job.yml.example +++ b/.deepwork/jobs/deepwork_jobs/templates/job.yml.example @@ -1,6 +1,7 @@ # Example: Competitive Research Job # # This is a complete example of a job.yml file for reference. +# It demonstrates multiple workflows using the same set of steps. name: competitive_research version: "1.0.0" @@ -10,6 +11,34 @@ description: | Helps product teams understand the competitive landscape through systematic identification, research, comparison, and positioning recommendations. + This job provides three workflows: + - full_analysis: Complete end-to-end competitive analysis + - quick_summary: Rapid analysis skipping deep research + - refresh_research: Update research on existing competitors + +# Multiple workflows allow different paths through the same steps +workflows: + - name: full_analysis + summary: "Complete competitive analysis with all steps" + steps: + - identify_competitors + - research_competitors + - comparative_analysis + - positioning_recommendations + + - name: quick_summary + summary: "Rapid analysis skipping deep research" + steps: + - identify_competitors + - positioning_recommendations + + - name: refresh_research + summary: "Update research on existing competitors" + steps: + - research_competitors + - comparative_analysis + - positioning_recommendations + changelog: - version: "1.0.0" changes: "Initial job creation" diff --git a/.deepwork/jobs/deepwork_jobs/templates/job.yml.template b/.deepwork/jobs/deepwork_jobs/templates/job.yml.template index 7dcf34e9..9eb2d86f 100644 --- a/.deepwork/jobs/deepwork_jobs/templates/job.yml.template +++ b/.deepwork/jobs/deepwork_jobs/templates/job.yml.template @@ -16,6 +16,23 @@ description: | - Who the intended users are - Any important context about the workflow] +# Optional: Define multiple workflows using different combinations of steps +# If omitted, all steps form a single implicit workflow +workflows: + - name: [workflow_name] + summary: "[Brief description of this workflow variant]" + steps: + - [step_id_1] + - [step_id_2] + - [step_id_3] + + # Additional workflow example (optional - include only if multiple workflows needed) + # - name: [another_workflow] + # summary: "[Description of this alternative workflow]" + # steps: + # - [step_id_1] + # - [step_id_3] # Can skip steps or use different combinations + changelog: - version: "1.0.0" changes: "Initial job creation" diff --git a/.gemini/skills/deepwork_jobs/define.toml b/.gemini/skills/deepwork_jobs/define.toml index 8a705168..9f893d44 100644 --- a/.gemini/skills/deepwork_jobs/define.toml +++ b/.gemini/skills/deepwork_jobs/define.toml @@ -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. ## On Completion diff --git a/.gemini/skills/deepwork_jobs/review_job_spec.toml b/.gemini/skills/deepwork_jobs/review_job_spec.toml index 265eb151..178c287c 100644 --- a/.gemini/skills/deepwork_jobs/review_job_spec.toml +++ b/.gemini/skills/deepwork_jobs/review_job_spec.toml @@ -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. ## Quality Validation (Manual) diff --git a/CHANGELOG.md b/CHANGELOG.md index 14c28e77..07b1d5ce 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -20,6 +20,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Step skills now display workflow context (e.g., "Step 2/3 in new_job workflow") - Standalone skills are clearly marked as "can be run anytime" - Backward compatible: jobs without `workflows` section use dependency-based detection +- Enhanced `deepwork_jobs.define` with guidance for creating jobs with multiple workflows + - New Step 2.5 asks structured questions about workflow organization + - Updated example dialog demonstrates multi-workflow discovery conversation + - Templates and doc_specs updated with `workflows` section examples and validation criteria ### Changed - Skill templates now show workflow-aware progress (e.g., "new_job step 2/3 complete") diff --git a/src/deepwork/standard_jobs/deepwork_jobs/doc_specs/job_spec.md b/src/deepwork/standard_jobs/deepwork_jobs/doc_specs/job_spec.md index b880bb17..ff3cd1cc 100644 --- a/src/deepwork/standard_jobs/deepwork_jobs/doc_specs/job_spec.md +++ b/src/deepwork/standard_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" diff --git a/src/deepwork/standard_jobs/deepwork_jobs/steps/define.md b/src/deepwork/standard_jobs/deepwork_jobs/steps/define.md index 31de7440..b6798628 100644 --- a/src/deepwork/standard_jobs/deepwork_jobs/steps/define.md +++ b/src/deepwork/standard_jobs/deepwork_jobs/steps/define.md @@ -205,6 +205,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: @@ -363,44 +365,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! diff --git a/src/deepwork/standard_jobs/deepwork_jobs/templates/job.yml.example b/src/deepwork/standard_jobs/deepwork_jobs/templates/job.yml.example index 7cc6e3bb..61784053 100644 --- a/src/deepwork/standard_jobs/deepwork_jobs/templates/job.yml.example +++ b/src/deepwork/standard_jobs/deepwork_jobs/templates/job.yml.example @@ -1,6 +1,7 @@ # Example: Competitive Research Job # # This is a complete example of a job.yml file for reference. +# It demonstrates multiple workflows using the same set of steps. name: competitive_research version: "1.0.0" @@ -10,6 +11,34 @@ description: | Helps product teams understand the competitive landscape through systematic identification, research, comparison, and positioning recommendations. + This job provides three workflows: + - full_analysis: Complete end-to-end competitive analysis + - quick_summary: Rapid analysis skipping deep research + - refresh_research: Update research on existing competitors + +# Multiple workflows allow different paths through the same steps +workflows: + - name: full_analysis + summary: "Complete competitive analysis with all steps" + steps: + - identify_competitors + - research_competitors + - comparative_analysis + - positioning_recommendations + + - name: quick_summary + summary: "Rapid analysis skipping deep research" + steps: + - identify_competitors + - positioning_recommendations + + - name: refresh_research + summary: "Update research on existing competitors" + steps: + - research_competitors + - comparative_analysis + - positioning_recommendations + changelog: - version: "1.0.0" changes: "Initial job creation" diff --git a/src/deepwork/standard_jobs/deepwork_jobs/templates/job.yml.template b/src/deepwork/standard_jobs/deepwork_jobs/templates/job.yml.template index 7dcf34e9..9eb2d86f 100644 --- a/src/deepwork/standard_jobs/deepwork_jobs/templates/job.yml.template +++ b/src/deepwork/standard_jobs/deepwork_jobs/templates/job.yml.template @@ -16,6 +16,23 @@ description: | - Who the intended users are - Any important context about the workflow] +# Optional: Define multiple workflows using different combinations of steps +# If omitted, all steps form a single implicit workflow +workflows: + - name: [workflow_name] + summary: "[Brief description of this workflow variant]" + steps: + - [step_id_1] + - [step_id_2] + - [step_id_3] + + # Additional workflow example (optional - include only if multiple workflows needed) + # - name: [another_workflow] + # summary: "[Description of this alternative workflow]" + # steps: + # - [step_id_1] + # - [step_id_3] # Can skip steps or use different combinations + changelog: - version: "1.0.0" changes: "Initial job creation"