diff --git a/.claude/skills/deepwork_jobs.define/SKILL.md b/.claude/skills/deepwork_jobs.define/SKILL.md index 4db98176..0215a6c7 100644 --- a/.claude/skills/deepwork_jobs.define/SKILL.md +++ b/.claude/skills/deepwork_jobs.define/SKILL.md @@ -150,6 +150,8 @@ For each major phase they mentioned, ask structured questions to gather details: - Where should each output be saved? (filename/path) - Should outputs be organized in subdirectories? (e.g., `reports/`, `data/`, `drafts/`) - Will other steps need this output? + + **Important**: Output paths should always be within the main repository directory structure, not in dot-directories like `.deepwork/`. Dot-directories are for configuration and job definitions, not for job outputs. Use paths like `research/competitors/report.md` rather than `.deepwork/outputs/report.md`. - **Does this output have a doc spec?** If a doc spec was created in Step 1.6/1.7, reference it for the appropriate output 4. **Step Dependencies** @@ -488,7 +490,7 @@ Use branch format: `deepwork/deepwork_jobs-[instance]-YYYYMMDD` 6. **Complete Steps**: Each step must have: id (lowercase_underscores), name, description, instructions_file, outputs (at least one), and dependencies array 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 (e.g., `report.md` or `reports/analysis.md`) + 9. **Output Paths**: Outputs must be valid filenames or paths within the main repo (not in dot-directories). Use specific, descriptive paths that lend themselves to glob patterns, e.g., `competitive_research/competitors_list.md` or `competitive_research/[competitor_name]/research.md`. Avoid generic names like `output.md`. 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.
@@ -538,10 +540,10 @@ Use branch format: `deepwork/deepwork_jobs-[instance]-YYYYMMDD` - file: output.md from_step: previous_step_id outputs: - - filename.md # simple filename - - reports/analysis.md # path with directory + - competitive_research/competitors_list.md # descriptive path + - competitive_research/[competitor_name]/research.md # parameterized path # With doc spec reference: - - file: report.md + - file: competitive_research/final_report.md doc_spec: .deepwork/doc_specs/report_type.md dependencies: - previous_step_id # steps that must complete first @@ -592,7 +594,7 @@ Use branch format: `deepwork/deepwork_jobs-[instance]-YYYYMMDD` 1. **No circular dependencies**: Step A cannot depend on Step B if Step B depends on Step A 2. **File inputs require dependencies**: If a step uses `from_step: X`, then X must be in its dependencies 3. **Unique step IDs**: No two steps can have the same id - 4. **Valid file paths**: Output paths must not contain invalid characters + 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 ## Example: Complete Job Specification @@ -627,7 +629,7 @@ Use branch format: `deepwork/deepwork_jobs-[instance]-YYYYMMDD` - name: product_category description: "The product category" outputs: - - competitors_list.md + - competitive_research/competitors_list.md dependencies: [] - id: research_competitors @@ -635,10 +637,10 @@ Use branch format: `deepwork/deepwork_jobs-[instance]-YYYYMMDD` description: "Deep dive research on each identified competitor" instructions_file: steps/research_competitors.md inputs: - - file: competitors_list.md + - file: competitive_research/competitors_list.md from_step: identify_competitors outputs: - - research_notes.md + - competitive_research/[competitor_name]/research.md dependencies: - identify_competitors @@ -647,10 +649,10 @@ Use branch format: `deepwork/deepwork_jobs-[instance]-YYYYMMDD` description: "Strategic positioning recommendations" instructions_file: steps/positioning_report.md inputs: - - file: research_notes.md + - file: competitive_research/[competitor_name]/research.md from_step: research_competitors outputs: - - file: positioning_report.md + - file: competitive_research/positioning_report.md doc_spec: .deepwork/doc_specs/positioning_report.md dependencies: - research_competitors diff --git a/.claude/skills/deepwork_jobs.learn/SKILL.md b/.claude/skills/deepwork_jobs.learn/SKILL.md index 149409b1..da29dad5 100644 --- a/.claude/skills/deepwork_jobs.learn/SKILL.md +++ b/.claude/skills/deepwork_jobs.learn/SKILL.md @@ -50,13 +50,13 @@ hooks: ## Objective -Think deeply about this task. Reflect on the current conversation to identify learnings from DeepWork job executions, improve job instructions with generalizable insights, and capture bespoke (run-specific) learnings in AGENTS.md files in the appropriate working folder. +Think deeply about this task. Reflect on the current conversation to identify learnings from DeepWork job executions, improve job instructions with generalizable insights, and capture bespoke (run-specific) learnings in AGENTS.md files in the deepest common folder that would contain all work on the topic in the future. ## Task Analyze the conversation history to extract learnings and improvements, then apply them appropriately: - **Generalizable learnings** → Update job instruction files -- **Bespoke learnings** (specific to this run) → Add to AGENTS.md in working folder +- **Bespoke learnings** (specific to this run) → Add to AGENTS.md in the deepest common folder for the topic ### Step 1: Analyze Conversation for Job Executions @@ -65,7 +65,8 @@ Analyze the conversation history to extract learnings and improvements, then app - Identify which jobs and steps were executed - Note the order of execution -2. **Identify the working folder** +2. **Identify the target folder** + - This should be the deepest common folder that would contain all work on the topic in the future - Should be clear from conversation history where work was done - If unclear, run `git diff` to see where changes were made on the branch @@ -249,7 +250,7 @@ quality_criteria: The AGENTS.md file captures project-specific knowledge that helps future agent runs. 1. **Determine the correct location** - - Place AGENTS.md in the working folder where job outputs live + - Place AGENTS.md in the deepest common folder that would contain all work on the topic in the future - This ensures the knowledge is available when working in that context - If uncertain, place at the project root @@ -317,7 +318,7 @@ When adding entries to AGENTS.md, prefer these patterns: - Shared/lengthy content extracted into referenced files where appropriate - AGENTS.md created/updated with bespoke learnings - File references used instead of duplicating content -- AGENTS.md is in the correct working folder +- AGENTS.md is in the correct folder (the deepest common folder for the topic) - When all criteria are met, include `✓ Quality Criteria Met` ## Example Dialog diff --git a/.claude/skills/deepwork_jobs.review_job_spec/SKILL.md b/.claude/skills/deepwork_jobs.review_job_spec/SKILL.md index fb331c00..85a881b1 100644 --- a/.claude/skills/deepwork_jobs.review_job_spec/SKILL.md +++ b/.claude/skills/deepwork_jobs.review_job_spec/SKILL.md @@ -297,7 +297,7 @@ Use branch format: `deepwork/deepwork_jobs-[instance]-YYYYMMDD` 6. **Complete Steps**: Each step must have: id (lowercase_underscores), name, description, instructions_file, outputs (at least one), and dependencies array 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 (e.g., `report.md` or `reports/analysis.md`) + 9. **Output Paths**: Outputs must be valid filenames or paths within the main repo (not in dot-directories). Use specific, descriptive paths that lend themselves to glob patterns, e.g., `competitive_research/competitors_list.md` or `competitive_research/[competitor_name]/research.md`. Avoid generic names like `output.md`. 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.
@@ -347,10 +347,10 @@ Use branch format: `deepwork/deepwork_jobs-[instance]-YYYYMMDD` - file: output.md from_step: previous_step_id outputs: - - filename.md # simple filename - - reports/analysis.md # path with directory + - competitive_research/competitors_list.md # descriptive path + - competitive_research/[competitor_name]/research.md # parameterized path # With doc spec reference: - - file: report.md + - file: competitive_research/final_report.md doc_spec: .deepwork/doc_specs/report_type.md dependencies: - previous_step_id # steps that must complete first @@ -401,7 +401,7 @@ Use branch format: `deepwork/deepwork_jobs-[instance]-YYYYMMDD` 1. **No circular dependencies**: Step A cannot depend on Step B if Step B depends on Step A 2. **File inputs require dependencies**: If a step uses `from_step: X`, then X must be in its dependencies 3. **Unique step IDs**: No two steps can have the same id - 4. **Valid file paths**: Output paths must not contain invalid characters + 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 ## Example: Complete Job Specification @@ -436,7 +436,7 @@ Use branch format: `deepwork/deepwork_jobs-[instance]-YYYYMMDD` - name: product_category description: "The product category" outputs: - - competitors_list.md + - competitive_research/competitors_list.md dependencies: [] - id: research_competitors @@ -444,10 +444,10 @@ Use branch format: `deepwork/deepwork_jobs-[instance]-YYYYMMDD` description: "Deep dive research on each identified competitor" instructions_file: steps/research_competitors.md inputs: - - file: competitors_list.md + - file: competitive_research/competitors_list.md from_step: identify_competitors outputs: - - research_notes.md + - competitive_research/[competitor_name]/research.md dependencies: - identify_competitors @@ -456,10 +456,10 @@ Use branch format: `deepwork/deepwork_jobs-[instance]-YYYYMMDD` description: "Strategic positioning recommendations" instructions_file: steps/positioning_report.md inputs: - - file: research_notes.md + - file: competitive_research/[competitor_name]/research.md from_step: research_competitors outputs: - - file: positioning_report.md + - file: competitive_research/positioning_report.md doc_spec: .deepwork/doc_specs/positioning_report.md dependencies: - research_competitors diff --git a/.deepwork/doc_specs/job_spec.md b/.deepwork/doc_specs/job_spec.md index 46b32e7d..4ee860b9 100644 --- a/.deepwork/doc_specs/job_spec.md +++ b/.deepwork/doc_specs/job_spec.md @@ -23,7 +23,7 @@ quality_criteria: - name: Input Consistency 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 (e.g., `report.md` or `reports/analysis.md`)" + description: "Outputs must be valid filenames or paths within the main repo (not in dot-directories). Use specific, descriptive paths that lend themselves to glob patterns, e.g., `competitive_research/competitors_list.md` or `competitive_research/[competitor_name]/research.md`. Avoid generic names like `output.md`." - 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." --- @@ -71,10 +71,10 @@ steps: - file: output.md from_step: previous_step_id outputs: - - filename.md # simple filename - - reports/analysis.md # path with directory + - competitive_research/competitors_list.md # descriptive path + - competitive_research/[competitor_name]/research.md # parameterized path # With doc spec reference: - - file: report.md + - file: competitive_research/final_report.md doc_spec: .deepwork/doc_specs/report_type.md dependencies: - previous_step_id # steps that must complete first @@ -125,7 +125,7 @@ steps: 1. **No circular dependencies**: Step A cannot depend on Step B if Step B depends on Step A 2. **File inputs require dependencies**: If a step uses `from_step: X`, then X must be in its dependencies 3. **Unique step IDs**: No two steps can have the same id -4. **Valid file paths**: Output paths must not contain invalid characters +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 ## Example: Complete Job Specification @@ -160,7 +160,7 @@ steps: - name: product_category description: "The product category" outputs: - - competitors_list.md + - competitive_research/competitors_list.md dependencies: [] - id: research_competitors @@ -168,10 +168,10 @@ steps: description: "Deep dive research on each identified competitor" instructions_file: steps/research_competitors.md inputs: - - file: competitors_list.md + - file: competitive_research/competitors_list.md from_step: identify_competitors outputs: - - research_notes.md + - competitive_research/[competitor_name]/research.md dependencies: - identify_competitors @@ -180,10 +180,10 @@ steps: description: "Strategic positioning recommendations" instructions_file: steps/positioning_report.md inputs: - - file: research_notes.md + - file: competitive_research/[competitor_name]/research.md from_step: research_competitors outputs: - - file: positioning_report.md + - file: competitive_research/positioning_report.md doc_spec: .deepwork/doc_specs/positioning_report.md dependencies: - research_competitors diff --git a/.deepwork/jobs/deepwork_jobs/doc_specs/job_spec.md b/.deepwork/jobs/deepwork_jobs/doc_specs/job_spec.md index 46b32e7d..4ee860b9 100644 --- a/.deepwork/jobs/deepwork_jobs/doc_specs/job_spec.md +++ b/.deepwork/jobs/deepwork_jobs/doc_specs/job_spec.md @@ -23,7 +23,7 @@ quality_criteria: - name: Input Consistency 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 (e.g., `report.md` or `reports/analysis.md`)" + description: "Outputs must be valid filenames or paths within the main repo (not in dot-directories). Use specific, descriptive paths that lend themselves to glob patterns, e.g., `competitive_research/competitors_list.md` or `competitive_research/[competitor_name]/research.md`. Avoid generic names like `output.md`." - 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." --- @@ -71,10 +71,10 @@ steps: - file: output.md from_step: previous_step_id outputs: - - filename.md # simple filename - - reports/analysis.md # path with directory + - competitive_research/competitors_list.md # descriptive path + - competitive_research/[competitor_name]/research.md # parameterized path # With doc spec reference: - - file: report.md + - file: competitive_research/final_report.md doc_spec: .deepwork/doc_specs/report_type.md dependencies: - previous_step_id # steps that must complete first @@ -125,7 +125,7 @@ steps: 1. **No circular dependencies**: Step A cannot depend on Step B if Step B depends on Step A 2. **File inputs require dependencies**: If a step uses `from_step: X`, then X must be in its dependencies 3. **Unique step IDs**: No two steps can have the same id -4. **Valid file paths**: Output paths must not contain invalid characters +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 ## Example: Complete Job Specification @@ -160,7 +160,7 @@ steps: - name: product_category description: "The product category" outputs: - - competitors_list.md + - competitive_research/competitors_list.md dependencies: [] - id: research_competitors @@ -168,10 +168,10 @@ steps: description: "Deep dive research on each identified competitor" instructions_file: steps/research_competitors.md inputs: - - file: competitors_list.md + - file: competitive_research/competitors_list.md from_step: identify_competitors outputs: - - research_notes.md + - competitive_research/[competitor_name]/research.md dependencies: - identify_competitors @@ -180,10 +180,10 @@ steps: description: "Strategic positioning recommendations" instructions_file: steps/positioning_report.md inputs: - - file: research_notes.md + - file: competitive_research/[competitor_name]/research.md from_step: research_competitors outputs: - - file: positioning_report.md + - file: competitive_research/positioning_report.md doc_spec: .deepwork/doc_specs/positioning_report.md dependencies: - research_competitors diff --git a/.deepwork/jobs/deepwork_jobs/steps/define.md b/.deepwork/jobs/deepwork_jobs/steps/define.md index 0d5533a1..f94bee50 100644 --- a/.deepwork/jobs/deepwork_jobs/steps/define.md +++ b/.deepwork/jobs/deepwork_jobs/steps/define.md @@ -101,6 +101,8 @@ For each major phase they mentioned, ask structured questions to gather details: - Where should each output be saved? (filename/path) - Should outputs be organized in subdirectories? (e.g., `reports/`, `data/`, `drafts/`) - Will other steps need this output? + + **Important**: Output paths should always be within the main repository directory structure, not in dot-directories like `.deepwork/`. Dot-directories are for configuration and job definitions, not for job outputs. Use paths like `research/competitors/report.md` rather than `.deepwork/outputs/report.md`. - **Does this output have a doc spec?** If a doc spec was created in Step 1.6/1.7, reference it for the appropriate output 4. **Step Dependencies** diff --git a/.deepwork/jobs/deepwork_jobs/steps/learn.md b/.deepwork/jobs/deepwork_jobs/steps/learn.md index 2ba2703c..3fddf37d 100644 --- a/.deepwork/jobs/deepwork_jobs/steps/learn.md +++ b/.deepwork/jobs/deepwork_jobs/steps/learn.md @@ -2,13 +2,13 @@ ## Objective -Think deeply about this task. Reflect on the current conversation to identify learnings from DeepWork job executions, improve job instructions with generalizable insights, and capture bespoke (run-specific) learnings in AGENTS.md files in the appropriate working folder. +Think deeply about this task. Reflect on the current conversation to identify learnings from DeepWork job executions, improve job instructions with generalizable insights, and capture bespoke (run-specific) learnings in AGENTS.md files in the deepest common folder that would contain all work on the topic in the future. ## Task Analyze the conversation history to extract learnings and improvements, then apply them appropriately: - **Generalizable learnings** → Update job instruction files -- **Bespoke learnings** (specific to this run) → Add to AGENTS.md in working folder +- **Bespoke learnings** (specific to this run) → Add to AGENTS.md in the deepest common folder for the topic ### Step 1: Analyze Conversation for Job Executions @@ -17,7 +17,8 @@ Analyze the conversation history to extract learnings and improvements, then app - Identify which jobs and steps were executed - Note the order of execution -2. **Identify the working folder** +2. **Identify the target folder** + - This should be the deepest common folder that would contain all work on the topic in the future - Should be clear from conversation history where work was done - If unclear, run `git diff` to see where changes were made on the branch @@ -201,7 +202,7 @@ quality_criteria: The AGENTS.md file captures project-specific knowledge that helps future agent runs. 1. **Determine the correct location** - - Place AGENTS.md in the working folder where job outputs live + - Place AGENTS.md in the deepest common folder that would contain all work on the topic in the future - This ensures the knowledge is available when working in that context - If uncertain, place at the project root @@ -269,7 +270,7 @@ When adding entries to AGENTS.md, prefer these patterns: - Shared/lengthy content extracted into referenced files where appropriate - AGENTS.md created/updated with bespoke learnings - File references used instead of duplicating content -- AGENTS.md is in the correct working folder +- AGENTS.md is in the correct folder (the deepest common folder for the topic) - When all criteria are met, include `✓ Quality Criteria Met` ## Example Dialog diff --git a/.gemini/skills/deepwork_jobs/define.toml b/.gemini/skills/deepwork_jobs/define.toml index 91905d82..61dec612 100644 --- a/.gemini/skills/deepwork_jobs/define.toml +++ b/.gemini/skills/deepwork_jobs/define.toml @@ -121,6 +121,8 @@ For each major phase they mentioned, ask structured questions to gather details: - Where should each output be saved? (filename/path) - Should outputs be organized in subdirectories? (e.g., `reports/`, `data/`, `drafts/`) - Will other steps need this output? + + **Important**: Output paths should always be within the main repository directory structure, not in dot-directories like `.deepwork/`. Dot-directories are for configuration and job definitions, not for job outputs. Use paths like `research/competitors/report.md` rather than `.deepwork/outputs/report.md`. - **Does this output have a doc spec?** If a doc spec was created in Step 1.6/1.7, reference it for the appropriate output 4. **Step Dependencies** @@ -459,7 +461,7 @@ Use branch format: `deepwork/deepwork_jobs-[instance]-YYYYMMDD` 6. **Complete Steps**: Each step must have: id (lowercase_underscores), name, description, instructions_file, outputs (at least one), and dependencies array 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 (e.g., `report.md` or `reports/analysis.md`) + 9. **Output Paths**: Outputs must be valid filenames or paths within the main repo (not in dot-directories). Use specific, descriptive paths that lend themselves to glob patterns, e.g., `competitive_research/competitors_list.md` or `competitive_research/[competitor_name]/research.md`. Avoid generic names like `output.md`. 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. ## Quality Validation (Manual) diff --git a/.gemini/skills/deepwork_jobs/learn.toml b/.gemini/skills/deepwork_jobs/learn.toml index 1d2d2960..8f093881 100644 --- a/.gemini/skills/deepwork_jobs/learn.toml +++ b/.gemini/skills/deepwork_jobs/learn.toml @@ -22,13 +22,13 @@ prompt = """ ## Objective -Think deeply about this task. Reflect on the current conversation to identify learnings from DeepWork job executions, improve job instructions with generalizable insights, and capture bespoke (run-specific) learnings in AGENTS.md files in the appropriate working folder. +Think deeply about this task. Reflect on the current conversation to identify learnings from DeepWork job executions, improve job instructions with generalizable insights, and capture bespoke (run-specific) learnings in AGENTS.md files in the deepest common folder that would contain all work on the topic in the future. ## Task Analyze the conversation history to extract learnings and improvements, then apply them appropriately: - **Generalizable learnings** → Update job instruction files -- **Bespoke learnings** (specific to this run) → Add to AGENTS.md in working folder +- **Bespoke learnings** (specific to this run) → Add to AGENTS.md in the deepest common folder for the topic ### Step 1: Analyze Conversation for Job Executions @@ -37,7 +37,8 @@ Analyze the conversation history to extract learnings and improvements, then app - Identify which jobs and steps were executed - Note the order of execution -2. **Identify the working folder** +2. **Identify the target folder** + - This should be the deepest common folder that would contain all work on the topic in the future - Should be clear from conversation history where work was done - If unclear, run `git diff` to see where changes were made on the branch @@ -221,7 +222,7 @@ quality_criteria: The AGENTS.md file captures project-specific knowledge that helps future agent runs. 1. **Determine the correct location** - - Place AGENTS.md in the working folder where job outputs live + - Place AGENTS.md in the deepest common folder that would contain all work on the topic in the future - This ensures the knowledge is available when working in that context - If uncertain, place at the project root @@ -289,7 +290,7 @@ When adding entries to AGENTS.md, prefer these patterns: - Shared/lengthy content extracted into referenced files where appropriate - AGENTS.md created/updated with bespoke learnings - File references used instead of duplicating content -- AGENTS.md is in the correct working folder +- AGENTS.md is in the correct folder (the deepest common folder for the topic) - When all criteria are met, include `✓ Quality Criteria Met` ## Example Dialog diff --git a/.gemini/skills/deepwork_jobs/review_job_spec.toml b/.gemini/skills/deepwork_jobs/review_job_spec.toml index b24bfa55..b9bed849 100644 --- a/.gemini/skills/deepwork_jobs/review_job_spec.toml +++ b/.gemini/skills/deepwork_jobs/review_job_spec.toml @@ -276,7 +276,7 @@ Use branch format: `deepwork/deepwork_jobs-[instance]-YYYYMMDD` 6. **Complete Steps**: Each step must have: id (lowercase_underscores), name, description, instructions_file, outputs (at least one), and dependencies array 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 (e.g., `report.md` or `reports/analysis.md`) + 9. **Output Paths**: Outputs must be valid filenames or paths within the main repo (not in dot-directories). Use specific, descriptive paths that lend themselves to glob patterns, e.g., `competitive_research/competitors_list.md` or `competitive_research/[competitor_name]/research.md`. Avoid generic names like `output.md`. 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. ## Quality Validation (Manual) 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 46b32e7d..4ee860b9 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 @@ -23,7 +23,7 @@ quality_criteria: - name: Input Consistency 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 (e.g., `report.md` or `reports/analysis.md`)" + description: "Outputs must be valid filenames or paths within the main repo (not in dot-directories). Use specific, descriptive paths that lend themselves to glob patterns, e.g., `competitive_research/competitors_list.md` or `competitive_research/[competitor_name]/research.md`. Avoid generic names like `output.md`." - 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." --- @@ -71,10 +71,10 @@ steps: - file: output.md from_step: previous_step_id outputs: - - filename.md # simple filename - - reports/analysis.md # path with directory + - competitive_research/competitors_list.md # descriptive path + - competitive_research/[competitor_name]/research.md # parameterized path # With doc spec reference: - - file: report.md + - file: competitive_research/final_report.md doc_spec: .deepwork/doc_specs/report_type.md dependencies: - previous_step_id # steps that must complete first @@ -125,7 +125,7 @@ steps: 1. **No circular dependencies**: Step A cannot depend on Step B if Step B depends on Step A 2. **File inputs require dependencies**: If a step uses `from_step: X`, then X must be in its dependencies 3. **Unique step IDs**: No two steps can have the same id -4. **Valid file paths**: Output paths must not contain invalid characters +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 ## Example: Complete Job Specification @@ -160,7 +160,7 @@ steps: - name: product_category description: "The product category" outputs: - - competitors_list.md + - competitive_research/competitors_list.md dependencies: [] - id: research_competitors @@ -168,10 +168,10 @@ steps: description: "Deep dive research on each identified competitor" instructions_file: steps/research_competitors.md inputs: - - file: competitors_list.md + - file: competitive_research/competitors_list.md from_step: identify_competitors outputs: - - research_notes.md + - competitive_research/[competitor_name]/research.md dependencies: - identify_competitors @@ -180,10 +180,10 @@ steps: description: "Strategic positioning recommendations" instructions_file: steps/positioning_report.md inputs: - - file: research_notes.md + - file: competitive_research/[competitor_name]/research.md from_step: research_competitors outputs: - - file: positioning_report.md + - file: competitive_research/positioning_report.md doc_spec: .deepwork/doc_specs/positioning_report.md dependencies: - research_competitors diff --git a/src/deepwork/standard_jobs/deepwork_jobs/steps/define.md b/src/deepwork/standard_jobs/deepwork_jobs/steps/define.md index 0d5533a1..f94bee50 100644 --- a/src/deepwork/standard_jobs/deepwork_jobs/steps/define.md +++ b/src/deepwork/standard_jobs/deepwork_jobs/steps/define.md @@ -101,6 +101,8 @@ For each major phase they mentioned, ask structured questions to gather details: - Where should each output be saved? (filename/path) - Should outputs be organized in subdirectories? (e.g., `reports/`, `data/`, `drafts/`) - Will other steps need this output? + + **Important**: Output paths should always be within the main repository directory structure, not in dot-directories like `.deepwork/`. Dot-directories are for configuration and job definitions, not for job outputs. Use paths like `research/competitors/report.md` rather than `.deepwork/outputs/report.md`. - **Does this output have a doc spec?** If a doc spec was created in Step 1.6/1.7, reference it for the appropriate output 4. **Step Dependencies** diff --git a/src/deepwork/standard_jobs/deepwork_jobs/steps/learn.md b/src/deepwork/standard_jobs/deepwork_jobs/steps/learn.md index 2ba2703c..3fddf37d 100644 --- a/src/deepwork/standard_jobs/deepwork_jobs/steps/learn.md +++ b/src/deepwork/standard_jobs/deepwork_jobs/steps/learn.md @@ -2,13 +2,13 @@ ## Objective -Think deeply about this task. Reflect on the current conversation to identify learnings from DeepWork job executions, improve job instructions with generalizable insights, and capture bespoke (run-specific) learnings in AGENTS.md files in the appropriate working folder. +Think deeply about this task. Reflect on the current conversation to identify learnings from DeepWork job executions, improve job instructions with generalizable insights, and capture bespoke (run-specific) learnings in AGENTS.md files in the deepest common folder that would contain all work on the topic in the future. ## Task Analyze the conversation history to extract learnings and improvements, then apply them appropriately: - **Generalizable learnings** → Update job instruction files -- **Bespoke learnings** (specific to this run) → Add to AGENTS.md in working folder +- **Bespoke learnings** (specific to this run) → Add to AGENTS.md in the deepest common folder for the topic ### Step 1: Analyze Conversation for Job Executions @@ -17,7 +17,8 @@ Analyze the conversation history to extract learnings and improvements, then app - Identify which jobs and steps were executed - Note the order of execution -2. **Identify the working folder** +2. **Identify the target folder** + - This should be the deepest common folder that would contain all work on the topic in the future - Should be clear from conversation history where work was done - If unclear, run `git diff` to see where changes were made on the branch @@ -201,7 +202,7 @@ quality_criteria: The AGENTS.md file captures project-specific knowledge that helps future agent runs. 1. **Determine the correct location** - - Place AGENTS.md in the working folder where job outputs live + - Place AGENTS.md in the deepest common folder that would contain all work on the topic in the future - This ensures the knowledge is available when working in that context - If uncertain, place at the project root @@ -269,7 +270,7 @@ When adding entries to AGENTS.md, prefer these patterns: - Shared/lengthy content extracted into referenced files where appropriate - AGENTS.md created/updated with bespoke learnings - File references used instead of duplicating content -- AGENTS.md is in the correct working folder +- AGENTS.md is in the correct folder (the deepest common folder for the topic) - When all criteria are met, include `✓ Quality Criteria Met` ## Example Dialog