deepwork 0.1.1__tar.gz → 0.2.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (162) hide show
  1. {deepwork-0.1.1 → deepwork-0.2.0}/.claude/commands/deepwork_jobs.define.md +52 -78
  2. {deepwork-0.1.1 → deepwork-0.2.0}/.claude/commands/deepwork_jobs.implement.md +51 -246
  3. {deepwork-0.1.1 → deepwork-0.2.0}/.claude/commands/deepwork_jobs.learn.md +7 -65
  4. {deepwork-0.1.1 → deepwork-0.2.0}/.claude/commands/deepwork_policy.define.md +27 -3
  5. deepwork-0.2.0/.claude/commands/update.job.md +206 -0
  6. deepwork-0.2.0/.deepwork/jobs/deepwork_jobs/AGENTS.md +60 -0
  7. {deepwork-0.1.1/src/deepwork/standard_jobs → deepwork-0.2.0/.deepwork/jobs}/deepwork_jobs/job.yml +21 -14
  8. deepwork-0.2.0/.deepwork/jobs/deepwork_jobs/make_new_job.sh +134 -0
  9. {deepwork-0.1.1 → deepwork-0.2.0}/.deepwork/jobs/deepwork_jobs/steps/define.md +35 -63
  10. {deepwork-0.1.1/src/deepwork/standard_jobs → deepwork-0.2.0/.deepwork/jobs}/deepwork_jobs/steps/implement.md +36 -237
  11. {deepwork-0.1.1/src/deepwork/standard_jobs → deepwork-0.2.0/.deepwork/jobs}/deepwork_jobs/steps/learn.md +4 -62
  12. deepwork-0.2.0/.deepwork/jobs/deepwork_jobs/templates/agents.md.template +32 -0
  13. deepwork-0.2.0/.deepwork/jobs/deepwork_jobs/templates/job.yml.example +73 -0
  14. deepwork-0.2.0/.deepwork/jobs/deepwork_jobs/templates/job.yml.template +56 -0
  15. deepwork-0.2.0/.deepwork/jobs/deepwork_jobs/templates/step_instruction.md.example +82 -0
  16. deepwork-0.2.0/.deepwork/jobs/deepwork_jobs/templates/step_instruction.md.template +58 -0
  17. {deepwork-0.1.1/src/deepwork/standard_jobs → deepwork-0.2.0/.deepwork/jobs}/deepwork_policy/job.yml +3 -1
  18. {deepwork-0.1.1 → deepwork-0.2.0}/.deepwork/jobs/deepwork_policy/steps/define.md +27 -3
  19. deepwork-0.2.0/.deepwork/jobs/update/job.yml +42 -0
  20. deepwork-0.2.0/.deepwork/jobs/update/steps/job.md +73 -0
  21. {deepwork-0.1.1 → deepwork-0.2.0}/.gemini/commands/deepwork_jobs/define.toml +36 -64
  22. {deepwork-0.1.1 → deepwork-0.2.0}/.gemini/commands/deepwork_jobs/implement.toml +45 -240
  23. {deepwork-0.1.1 → deepwork-0.2.0}/.gemini/commands/deepwork_jobs/learn.toml +7 -65
  24. {deepwork-0.1.1 → deepwork-0.2.0}/.gemini/commands/deepwork_policy/define.toml +27 -3
  25. deepwork-0.2.0/.gemini/commands/update/job.toml +162 -0
  26. deepwork-0.2.0/.github/workflows/README.md +100 -0
  27. {deepwork-0.1.1 → deepwork-0.2.0}/.github/workflows/cla.yml +16 -2
  28. deepwork-0.2.0/.github/workflows/claude-code-test.yml +364 -0
  29. {deepwork-0.1.1 → deepwork-0.2.0}/.github/workflows/validate.yml +8 -1
  30. {deepwork-0.1.1 → deepwork-0.2.0}/CHANGELOG.md +24 -2
  31. deepwork-0.2.0/CLA/version_1/CLA_SIGNATORIES.md +20 -0
  32. {deepwork-0.1.1 → deepwork-0.2.0}/PKG-INFO +2 -1
  33. {deepwork-0.1.1 → deepwork-0.2.0}/README.md +1 -0
  34. {deepwork-0.1.1 → deepwork-0.2.0}/claude.md +15 -0
  35. {deepwork-0.1.1 → deepwork-0.2.0}/doc/architecture.md +10 -9
  36. {deepwork-0.1.1 → deepwork-0.2.0}/pyproject.toml +1 -1
  37. {deepwork-0.1.1 → deepwork-0.2.0}/src/deepwork/cli/install.py +48 -0
  38. deepwork-0.2.0/src/deepwork/standard_jobs/deepwork_jobs/AGENTS.md +60 -0
  39. {deepwork-0.1.1/.deepwork/jobs → deepwork-0.2.0/src/deepwork/standard_jobs}/deepwork_jobs/job.yml +8 -5
  40. deepwork-0.2.0/src/deepwork/standard_jobs/deepwork_jobs/make_new_job.sh +134 -0
  41. {deepwork-0.1.1 → deepwork-0.2.0}/src/deepwork/standard_jobs/deepwork_jobs/steps/define.md +20 -57
  42. {deepwork-0.1.1/.deepwork/jobs → deepwork-0.2.0/src/deepwork/standard_jobs}/deepwork_jobs/steps/implement.md +40 -237
  43. {deepwork-0.1.1/.deepwork/jobs → deepwork-0.2.0/src/deepwork/standard_jobs}/deepwork_jobs/steps/learn.md +4 -62
  44. deepwork-0.2.0/src/deepwork/standard_jobs/deepwork_jobs/steps/supplemental_file_references.md +40 -0
  45. deepwork-0.2.0/src/deepwork/standard_jobs/deepwork_jobs/templates/agents.md.template +32 -0
  46. deepwork-0.2.0/src/deepwork/standard_jobs/deepwork_jobs/templates/job.yml.example +73 -0
  47. deepwork-0.2.0/src/deepwork/standard_jobs/deepwork_jobs/templates/job.yml.template +56 -0
  48. deepwork-0.2.0/src/deepwork/standard_jobs/deepwork_jobs/templates/step_instruction.md.example +82 -0
  49. deepwork-0.2.0/src/deepwork/standard_jobs/deepwork_jobs/templates/step_instruction.md.template +58 -0
  50. deepwork-0.1.1/.deepwork/jobs/deepwork_policy/hooks/capture_work_tree.sh → deepwork-0.2.0/src/deepwork/standard_jobs/deepwork_policy/hooks/capture_prompt_work_tree.sh +3 -2
  51. {deepwork-0.1.1/.deepwork/jobs → deepwork-0.2.0/src/deepwork/standard_jobs}/deepwork_policy/hooks/policy_stop_hook.sh +3 -19
  52. deepwork-0.2.0/src/deepwork/standard_jobs/deepwork_policy/hooks/user_prompt_submit.sh +16 -0
  53. deepwork-0.2.0/src/deepwork/templates/default_policy.yml +53 -0
  54. deepwork-0.2.0/tests/e2e/__init__.py +1 -0
  55. deepwork-0.2.0/tests/e2e/test_claude_code_integration.py +325 -0
  56. deepwork-0.2.0/tests/fixtures/jobs/fruits/job.yml +40 -0
  57. deepwork-0.2.0/tests/fixtures/jobs/fruits/steps/classify.md +83 -0
  58. deepwork-0.2.0/tests/fixtures/jobs/fruits/steps/identify.md +64 -0
  59. deepwork-0.2.0/tests/integration/test_fruits_workflow.py +189 -0
  60. {deepwork-0.1.1 → deepwork-0.2.0}/tests/integration/test_install_flow.py +52 -0
  61. deepwork-0.2.0/tests/shell_script_tests/README.md +76 -0
  62. deepwork-0.2.0/tests/shell_script_tests/__init__.py +1 -0
  63. deepwork-0.2.0/tests/shell_script_tests/conftest.py +115 -0
  64. deepwork-0.2.0/tests/shell_script_tests/test_capture_prompt_work_tree.py +257 -0
  65. deepwork-0.2.0/tests/shell_script_tests/test_hooks_json_format.py +363 -0
  66. deepwork-0.2.0/tests/shell_script_tests/test_make_new_job.py +313 -0
  67. deepwork-0.2.0/tests/shell_script_tests/test_policy_stop_hook.py +287 -0
  68. deepwork-0.2.0/tests/shell_script_tests/test_user_prompt_submit.py +166 -0
  69. {deepwork-0.1.1 → deepwork-0.2.0}/uv.lock +1 -1
  70. deepwork-0.1.1/.deepwork/jobs/deepwork_policy/hooks/get_changed_files.sh +0 -30
  71. deepwork-0.1.1/.deepwork/jobs/deepwork_policy/hooks/user_prompt_submit.sh +0 -17
  72. deepwork-0.1.1/CLA/version_1/CLA_SIGNATORIES.md +0 -25
  73. {deepwork-0.1.1 → deepwork-0.2.0}/.claude/commands/AGENTS.md +0 -0
  74. {deepwork-0.1.1 → deepwork-0.2.0}/.claude/commands/add_platform.add_capabilities.md +0 -0
  75. {deepwork-0.1.1 → deepwork-0.2.0}/.claude/commands/add_platform.implement.md +0 -0
  76. {deepwork-0.1.1 → deepwork-0.2.0}/.claude/commands/add_platform.research.md +0 -0
  77. {deepwork-0.1.1 → deepwork-0.2.0}/.claude/commands/add_platform.verify.md +0 -0
  78. {deepwork-0.1.1 → deepwork-0.2.0}/.claude/settings.json +0 -0
  79. {deepwork-0.1.1 → deepwork-0.2.0}/.deepwork/.gitignore +0 -0
  80. {deepwork-0.1.1 → deepwork-0.2.0}/.deepwork/config.yml +0 -0
  81. {deepwork-0.1.1 → deepwork-0.2.0}/.deepwork/jobs/add_platform/job.yml +0 -0
  82. {deepwork-0.1.1 → deepwork-0.2.0}/.deepwork/jobs/add_platform/steps/add_capabilities.md +0 -0
  83. {deepwork-0.1.1 → deepwork-0.2.0}/.deepwork/jobs/add_platform/steps/implement.md +0 -0
  84. {deepwork-0.1.1 → deepwork-0.2.0}/.deepwork/jobs/add_platform/steps/research.md +0 -0
  85. {deepwork-0.1.1 → deepwork-0.2.0}/.deepwork/jobs/add_platform/steps/verify.md +0 -0
  86. {deepwork-0.1.1/src/deepwork/standard_jobs → deepwork-0.2.0/.deepwork/jobs}/deepwork_jobs/steps/supplemental_file_references.md +0 -0
  87. {deepwork-0.1.1/src/deepwork/standard_jobs → deepwork-0.2.0/.deepwork/jobs}/deepwork_policy/hooks/capture_prompt_work_tree.sh +0 -0
  88. {deepwork-0.1.1 → deepwork-0.2.0}/.deepwork/jobs/deepwork_policy/hooks/global_hooks.yml +0 -0
  89. {deepwork-0.1.1/src/deepwork/standard_jobs → deepwork-0.2.0/.deepwork/jobs}/deepwork_policy/hooks/policy_stop_hook.sh +0 -0
  90. {deepwork-0.1.1/src/deepwork/standard_jobs → deepwork-0.2.0/.deepwork/jobs}/deepwork_policy/hooks/user_prompt_submit.sh +0 -0
  91. {deepwork-0.1.1 → deepwork-0.2.0}/.deepwork.policy.yml +0 -0
  92. {deepwork-0.1.1 → deepwork-0.2.0}/.gemini/commands/add_platform/add_capabilities.toml +0 -0
  93. {deepwork-0.1.1 → deepwork-0.2.0}/.gemini/commands/add_platform/implement.toml +0 -0
  94. {deepwork-0.1.1 → deepwork-0.2.0}/.gemini/commands/add_platform/research.toml +0 -0
  95. {deepwork-0.1.1 → deepwork-0.2.0}/.gemini/commands/add_platform/verify.toml +0 -0
  96. {deepwork-0.1.1 → deepwork-0.2.0}/.gemini/commands/deepwork_jobs/refine.toml +0 -0
  97. {deepwork-0.1.1 → deepwork-0.2.0}/.github/workflows/release.yml +0 -0
  98. {deepwork-0.1.1 → deepwork-0.2.0}/.gitignore +0 -0
  99. {deepwork-0.1.1 → deepwork-0.2.0}/CLA/version_1/CLA.md +0 -0
  100. {deepwork-0.1.1 → deepwork-0.2.0}/CONTRIBUTING.md +0 -0
  101. {deepwork-0.1.1 → deepwork-0.2.0}/LICENSE.md +0 -0
  102. {deepwork-0.1.1 → deepwork-0.2.0}/doc/platforms/gemini/cli_configuration.md +0 -0
  103. {deepwork-0.1.1 → deepwork-0.2.0}/doc/platforms/gemini/hooks_system.md +0 -0
  104. {deepwork-0.1.1 → deepwork-0.2.0}/job_library/README.md +0 -0
  105. {deepwork-0.1.1 → deepwork-0.2.0}/shell.nix +0 -0
  106. {deepwork-0.1.1 → deepwork-0.2.0}/src/deepwork/__init__.py +0 -0
  107. {deepwork-0.1.1 → deepwork-0.2.0}/src/deepwork/cli/__init__.py +0 -0
  108. {deepwork-0.1.1 → deepwork-0.2.0}/src/deepwork/cli/main.py +0 -0
  109. {deepwork-0.1.1 → deepwork-0.2.0}/src/deepwork/cli/sync.py +0 -0
  110. {deepwork-0.1.1 → deepwork-0.2.0}/src/deepwork/core/__init__.py +0 -0
  111. {deepwork-0.1.1 → deepwork-0.2.0}/src/deepwork/core/adapters.py +0 -0
  112. {deepwork-0.1.1 → deepwork-0.2.0}/src/deepwork/core/detector.py +0 -0
  113. {deepwork-0.1.1 → deepwork-0.2.0}/src/deepwork/core/generator.py +0 -0
  114. {deepwork-0.1.1 → deepwork-0.2.0}/src/deepwork/core/hooks_syncer.py +0 -0
  115. {deepwork-0.1.1 → deepwork-0.2.0}/src/deepwork/core/parser.py +0 -0
  116. {deepwork-0.1.1 → deepwork-0.2.0}/src/deepwork/core/policy_parser.py +0 -0
  117. {deepwork-0.1.1 → deepwork-0.2.0}/src/deepwork/hooks/__init__.py +0 -0
  118. {deepwork-0.1.1 → deepwork-0.2.0}/src/deepwork/hooks/evaluate_policies.py +0 -0
  119. {deepwork-0.1.1 → deepwork-0.2.0}/src/deepwork/schemas/__init__.py +0 -0
  120. {deepwork-0.1.1 → deepwork-0.2.0}/src/deepwork/schemas/job_schema.py +0 -0
  121. {deepwork-0.1.1 → deepwork-0.2.0}/src/deepwork/schemas/policy_schema.py +0 -0
  122. {deepwork-0.1.1 → deepwork-0.2.0}/src/deepwork/standard_jobs/deepwork_policy/hooks/global_hooks.yml +0 -0
  123. {deepwork-0.1.1/.deepwork/jobs → deepwork-0.2.0/src/deepwork/standard_jobs}/deepwork_policy/job.yml +0 -0
  124. {deepwork-0.1.1 → deepwork-0.2.0}/src/deepwork/standard_jobs/deepwork_policy/steps/define.md +0 -0
  125. {deepwork-0.1.1 → deepwork-0.2.0}/src/deepwork/templates/__init__.py +0 -0
  126. {deepwork-0.1.1 → deepwork-0.2.0}/src/deepwork/templates/claude/command-job-step.md.jinja +0 -0
  127. {deepwork-0.1.1 → deepwork-0.2.0}/src/deepwork/templates/gemini/command-job-step.toml.jinja +0 -0
  128. {deepwork-0.1.1 → deepwork-0.2.0}/src/deepwork/utils/__init__.py +0 -0
  129. {deepwork-0.1.1 → deepwork-0.2.0}/src/deepwork/utils/fs.py +0 -0
  130. {deepwork-0.1.1 → deepwork-0.2.0}/src/deepwork/utils/git.py +0 -0
  131. {deepwork-0.1.1 → deepwork-0.2.0}/src/deepwork/utils/validation.py +0 -0
  132. {deepwork-0.1.1 → deepwork-0.2.0}/src/deepwork/utils/yaml_utils.py +0 -0
  133. {deepwork-0.1.1 → deepwork-0.2.0}/tests/__init__.py +0 -0
  134. {deepwork-0.1.1 → deepwork-0.2.0}/tests/conftest.py +0 -0
  135. {deepwork-0.1.1 → deepwork-0.2.0}/tests/fixtures/jobs/complex_job/job.yml +0 -0
  136. {deepwork-0.1.1 → deepwork-0.2.0}/tests/fixtures/jobs/complex_job/steps/comparative_report.md +0 -0
  137. {deepwork-0.1.1 → deepwork-0.2.0}/tests/fixtures/jobs/complex_job/steps/identify_competitors.md +0 -0
  138. {deepwork-0.1.1 → deepwork-0.2.0}/tests/fixtures/jobs/complex_job/steps/primary_research.md +0 -0
  139. {deepwork-0.1.1 → deepwork-0.2.0}/tests/fixtures/jobs/complex_job/steps/secondary_research.md +0 -0
  140. {deepwork-0.1.1 → deepwork-0.2.0}/tests/fixtures/jobs/invalid_job/job.yml +0 -0
  141. {deepwork-0.1.1 → deepwork-0.2.0}/tests/fixtures/jobs/simple_job/job.yml +0 -0
  142. {deepwork-0.1.1 → deepwork-0.2.0}/tests/fixtures/jobs/simple_job/steps/single_step.md +0 -0
  143. {deepwork-0.1.1 → deepwork-0.2.0}/tests/fixtures/policies/empty_policy.yml +0 -0
  144. {deepwork-0.1.1 → deepwork-0.2.0}/tests/fixtures/policies/instructions/security_review.md +0 -0
  145. {deepwork-0.1.1 → deepwork-0.2.0}/tests/fixtures/policies/invalid_missing_instructions.yml +0 -0
  146. {deepwork-0.1.1 → deepwork-0.2.0}/tests/fixtures/policies/invalid_missing_trigger.yml +0 -0
  147. {deepwork-0.1.1 → deepwork-0.2.0}/tests/fixtures/policies/multiple_policies.yml +0 -0
  148. {deepwork-0.1.1 → deepwork-0.2.0}/tests/fixtures/policies/policy_with_instructions_file.yml +0 -0
  149. {deepwork-0.1.1 → deepwork-0.2.0}/tests/fixtures/policies/valid_policy.yml +0 -0
  150. {deepwork-0.1.1 → deepwork-0.2.0}/tests/integration/test_full_workflow.py +0 -0
  151. {deepwork-0.1.1 → deepwork-0.2.0}/tests/unit/test_adapters.py +0 -0
  152. {deepwork-0.1.1 → deepwork-0.2.0}/tests/unit/test_detector.py +0 -0
  153. {deepwork-0.1.1 → deepwork-0.2.0}/tests/unit/test_evaluate_policies.py +0 -0
  154. {deepwork-0.1.1 → deepwork-0.2.0}/tests/unit/test_fs.py +0 -0
  155. {deepwork-0.1.1 → deepwork-0.2.0}/tests/unit/test_generator.py +0 -0
  156. {deepwork-0.1.1 → deepwork-0.2.0}/tests/unit/test_git.py +0 -0
  157. {deepwork-0.1.1 → deepwork-0.2.0}/tests/unit/test_hooks_syncer.py +0 -0
  158. {deepwork-0.1.1 → deepwork-0.2.0}/tests/unit/test_parser.py +0 -0
  159. {deepwork-0.1.1 → deepwork-0.2.0}/tests/unit/test_policy_parser.py +0 -0
  160. {deepwork-0.1.1 → deepwork-0.2.0}/tests/unit/test_stop_hooks.py +0 -0
  161. {deepwork-0.1.1 → deepwork-0.2.0}/tests/unit/test_validation.py +0 -0
  162. {deepwork-0.1.1 → deepwork-0.2.0}/tests/unit/test_yaml_utils.py +0 -0
@@ -11,13 +11,14 @@ hooks:
11
11
 
12
12
  Verify the job.yml output meets ALL quality criteria before completing:
13
13
 
14
- 1. **User Understanding**: Did you fully understand the user's workflow through interactive Q&A?
15
- 2. **Clear Inputs/Outputs**: Does every step have clearly defined inputs and outputs?
16
- 3. **Logical Dependencies**: Do step dependencies make sense and avoid circular references?
17
- 4. **Concise Summary**: Is the summary under 200 characters and descriptive?
18
- 5. **Rich Description**: Does the description provide enough context for future refinement?
19
- 6. **Valid Schema**: Does the job.yml follow the required schema (name, version, summary, steps)?
20
- 7. **File Created**: Has the job.yml file been created in `.deepwork/jobs/[job_name]/job.yml`?
14
+ 1. **User Understanding**: Did you fully understand the user's workflow by asking structured questions?
15
+ 2. **Structured Questions Used**: Did you ask structured questions (using the AskUserQuestion tool) to gather user input?
16
+ 3. **Clear Inputs/Outputs**: Does every step have clearly defined inputs and outputs?
17
+ 4. **Logical Dependencies**: Do step dependencies make sense and avoid circular references?
18
+ 5. **Concise Summary**: Is the summary under 200 characters and descriptive?
19
+ 6. **Rich Description**: Does the description provide enough context for future refinement?
20
+ 7. **Valid Schema**: Does the job.yml follow the required schema (name, version, summary, steps)?
21
+ 8. **File Created**: Has the job.yml file been created in `.deepwork/jobs/[job_name]/job.yml`?
21
22
 
22
23
  If ANY criterion is not met, continue working to address it.
23
24
  If ALL criteria are satisfied, include `<promise>✓ Quality Criteria Met</promise>` in your response.
@@ -47,7 +48,7 @@ Core commands for managing DeepWork jobs. These commands help you define new mul
47
48
  workflows and learn from running them.
48
49
 
49
50
  The `define` command guides you through an interactive process to create a new job by
50
- asking detailed questions about your workflow, understanding each step's inputs and outputs,
51
+ asking structured questions about your workflow, understanding each step's inputs and outputs,
51
52
  and generating all necessary files.
52
53
 
53
54
  The `learn` command reflects on conversations where DeepWork jobs were run, identifies
@@ -66,13 +67,15 @@ Create a `job.yml` specification file that defines the structure of a new DeepWo
66
67
 
67
68
  ## Task
68
69
 
69
- Guide the user through defining a job specification by asking clarifying questions. **Do not attempt to create the specification without first fully understanding the user's needs.**
70
+ Guide the user through defining a job specification by asking structured questions. **Do not attempt to create the specification without first fully understanding the user's needs.**
71
+
72
+ **Important**: Use the AskUserQuestion tool to ask structured questions when gathering information from the user. This provides a better user experience with clear options and guided choices.
70
73
 
71
74
  The output of this step is **only** the `job.yml` file - a complete specification of the workflow. The actual step instruction files will be created in the next step (`implement`).
72
75
 
73
76
  ### Step 1: Understand the Job Purpose
74
77
 
75
- Start by asking questions to understand what the user wants to accomplish:
78
+ Start by asking structured questions to understand what the user wants to accomplish:
76
79
 
77
80
  1. **What is the overall goal of this workflow?**
78
81
  - What complex task are they trying to accomplish?
@@ -91,7 +94,7 @@ Start by asking questions to understand what the user wants to accomplish:
91
94
 
92
95
  ### Step 2: Define Each Step
93
96
 
94
- For each major phase they mentioned, ask detailed questions:
97
+ For each major phase they mentioned, ask structured questions to gather details:
95
98
 
96
99
  1. **Step Purpose**
97
100
  - What exactly does this step accomplish?
@@ -122,6 +125,12 @@ For each major phase they mentioned, ask detailed questions:
122
125
 
123
126
  **Note**: You're gathering this information to understand what instructions will be needed, but you won't create the instruction files yet - that happens in the `implement` step.
124
127
 
128
+ ### Capability Considerations
129
+
130
+ When defining steps, identify any that require specialized tools:
131
+
132
+ **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.
133
+
125
134
  ### Step 3: Validate the Workflow
126
135
 
127
136
  After gathering information about all steps:
@@ -146,7 +155,7 @@ After gathering information about all steps:
146
155
 
147
156
  For each step, consider whether it would benefit from **quality validation loops**. Stop hooks allow the AI agent to iteratively refine its work until quality criteria are met.
148
157
 
149
- **Ask the user about quality validation:**
158
+ **Ask structured questions about quality validation:**
150
159
  - "Are there specific quality criteria that must be met for this step?"
151
160
  - "Would you like the agent to validate its work before completing?"
152
161
  - "What would make you send the work back for revision?"
@@ -189,68 +198,31 @@ stop_hooks:
189
198
 
190
199
  **Encourage prompt-based hooks** - They leverage the AI's ability to understand context and make nuanced quality judgments. Script hooks are best for objective checks (syntax, format, tests).
191
200
 
192
- ### Step 5: Create the job.yml Specification
193
-
194
- Only after you have complete understanding, create the `job.yml` file:
201
+ ### Step 5: Create the Job Directory and Specification
195
202
 
196
- **File Location**: `.deepwork/jobs/[job_name]/job.yml`
203
+ Only after you have complete understanding, create the job directory and `job.yml` file:
197
204
 
198
- (Where `[job_name]` is the name of the NEW job you're creating, e.g., `.deepwork/jobs/competitive_research/job.yml`)
205
+ **First, create the directory structure** using the `make_new_job.sh` script:
199
206
 
200
- **Format**:
201
- ```yaml
202
- name: [job_name]
203
- version: "1.0.0"
204
- summary: "[Brief one-line summary of what this job accomplishes]"
205
- description: |
206
- [Detailed multi-line description of the job's purpose, process, and goals.
207
-
208
- This should explain:
209
- - What problem this workflow solves
210
- - What the overall process looks like
211
- - What the end result will be
212
- - Who the intended users are
213
- - Any important context about the workflow]
214
-
215
- changelog:
216
- - version: "1.0.0"
217
- changes: "Initial job creation"
218
-
219
- steps:
220
- - id: [step_id]
221
- name: "[Step Name]"
222
- description: "[What this step does]"
223
- instructions_file: steps/[step_id].md
224
- inputs:
225
- - name: [param_name]
226
- description: "[What user needs to provide]"
227
- # OR for file inputs from previous steps:
228
- # - file: [filename_or_path]
229
- # from_step: [previous_step_id]
230
- outputs:
231
- - [output_filename_or_path] # e.g., "report.md" or "reports/analysis.md"
232
- dependencies: [] # List of step IDs that must complete first
233
- # Optional: Quality validation hooks
234
- stop_hooks:
235
- - prompt: |
236
- Verify this step's output meets quality criteria:
237
- 1. [Criterion 1]
238
- 2. [Criterion 2]
239
- If ALL criteria are met, include `<promise>✓ Quality Criteria Met</promise>`.
240
-
241
- - id: [another_step]
242
- name: "[Another Step]"
243
- description: "[What this step does]"
244
- instructions_file: steps/[another_step].md
245
- inputs:
246
- - file: [output_filename_or_path]
247
- from_step: [step_id]
248
- outputs:
249
- - [another_output_path]
250
- dependencies:
251
- - [step_id] # This step requires the previous step
207
+ ```bash
208
+ .deepwork/jobs/deepwork_jobs/make_new_job.sh [job_name]
252
209
  ```
253
210
 
211
+ This creates:
212
+ - `.deepwork/jobs/[job_name]/` - Main job directory
213
+ - `.deepwork/jobs/[job_name]/steps/` - For step instruction files
214
+ - `.deepwork/jobs/[job_name]/hooks/` - For custom validation scripts
215
+ - `.deepwork/jobs/[job_name]/templates/` - For example file formats
216
+ - `.deepwork/jobs/[job_name]/AGENTS.md` - Job management guidance
217
+
218
+ **Then create the job.yml file** at `.deepwork/jobs/[job_name]/job.yml`
219
+
220
+ (Where `[job_name]` is the name of the NEW job you're creating, e.g., `competitive_research`)
221
+
222
+ **Template reference**: See `.deepwork/jobs/deepwork_jobs/templates/job.yml.template` for the standard structure.
223
+
224
+ **Complete example**: See `.deepwork/jobs/deepwork_jobs/templates/job.yml.example` for a fully worked example.
225
+
254
226
  **Important**:
255
227
  - Use lowercase with underscores for job name and step IDs
256
228
  - Ensure file inputs reference steps in dependencies
@@ -372,11 +344,11 @@ Run `/deepwork_jobs.implement` to generate the instruction files for each step b
372
344
  ## Important Guidelines
373
345
 
374
346
  1. **Focus on specification only** - Don't create instruction files yet
375
- 2. **Ask clarifying questions** - Never skip the discovery phase
347
+ 2. **Ask structured questions** - Never skip the discovery phase; use the AskUserQuestion tool
376
348
  3. **Rich context in description** - This helps with future refinement
377
349
  4. **Validate understanding** - Summarize and confirm before creating
378
350
  5. **Use examples** - Help users understand what good specifications look like
379
- 6. **Understand file organization** - Always ask where outputs should be saved and if subdirectories are needed
351
+ 6. **Understand file organization** - Always ask structured questions about where outputs should be saved and if subdirectories are needed
380
352
 
381
353
  ## Validation Rules
382
354
 
@@ -410,6 +382,7 @@ After creating the file:
410
382
 
411
383
  ## Quality Criteria
412
384
 
385
+ - Asked structured questions to fully understand user requirements
413
386
  - User fully understands what job they're creating
414
387
  - All steps have clear inputs and outputs
415
388
  - Dependencies make logical sense
@@ -456,13 +429,14 @@ This step uses an iterative quality validation loop. After completing your work,
456
429
  ### Quality Criteria
457
430
  Verify the job.yml output meets ALL quality criteria before completing:
458
431
 
459
- 1. **User Understanding**: Did you fully understand the user's workflow through interactive Q&A?
460
- 2. **Clear Inputs/Outputs**: Does every step have clearly defined inputs and outputs?
461
- 3. **Logical Dependencies**: Do step dependencies make sense and avoid circular references?
462
- 4. **Concise Summary**: Is the summary under 200 characters and descriptive?
463
- 5. **Rich Description**: Does the description provide enough context for future refinement?
464
- 6. **Valid Schema**: Does the job.yml follow the required schema (name, version, summary, steps)?
465
- 7. **File Created**: Has the job.yml file been created in `.deepwork/jobs/[job_name]/job.yml`?
432
+ 1. **User Understanding**: Did you fully understand the user's workflow by asking structured questions?
433
+ 2. **Structured Questions Used**: Did you ask structured questions (using the AskUserQuestion tool) to gather user input?
434
+ 3. **Clear Inputs/Outputs**: Does every step have clearly defined inputs and outputs?
435
+ 4. **Logical Dependencies**: Do step dependencies make sense and avoid circular references?
436
+ 5. **Concise Summary**: Is the summary under 200 characters and descriptive?
437
+ 6. **Rich Description**: Does the description provide enough context for future refinement?
438
+ 7. **Valid Schema**: Does the job.yml follow the required schema (name, version, summary, steps)?
439
+ 8. **File Created**: Has the job.yml file been created in `.deepwork/jobs/[job_name]/job.yml`?
466
440
 
467
441
  If ANY criterion is not met, continue working to address it.
468
442
  If ALL criteria are satisfied, include `<promise>✓ Quality Criteria Met</promise>` in your response.
@@ -16,9 +16,9 @@ hooks:
16
16
  3. **Specific & Actionable**: Are instructions tailored to each step's purpose, not generic?
17
17
  4. **Output Examples**: Does each instruction file show what good output looks like?
18
18
  5. **Quality Criteria**: Does each instruction file define quality criteria for its outputs?
19
- 6. **Sync Complete**: Has `deepwork sync` been run successfully?
20
- 7. **Commands Available**: Are the slash-commands generated in `.claude/commands/`?
21
- 8. **Summary Created**: Has `implementation_summary.md` been created?
19
+ 6. **Ask Structured Questions**: Do step instructions that gather user input explicitly use the phrase "ask structured questions"?
20
+ 7. **Sync Complete**: Has `deepwork sync` been run successfully?
21
+ 8. **Commands Available**: Are the slash-commands generated in `.claude/commands/`?
22
22
  9. **Policies Considered**: Have you thought about whether policies would benefit this job?
23
23
  - If relevant policies were identified, did you explain them and offer to run `/deepwork_policy.define`?
24
24
  - Not every job needs policies - only suggest when genuinely helpful.
@@ -51,7 +51,7 @@ Core commands for managing DeepWork jobs. These commands help you define new mul
51
51
  workflows and learn from running them.
52
52
 
53
53
  The `define` command guides you through an interactive process to create a new job by
54
- asking detailed questions about your workflow, understanding each step's inputs and outputs,
54
+ asking structured questions about your workflow, understanding each step's inputs and outputs,
55
55
  and generating all necessary files.
56
56
 
57
57
  The `learn` command reflects on conversations where DeepWork jobs were run, identifies
@@ -78,10 +78,31 @@ Generate the DeepWork job directory structure and instruction files for each ste
78
78
 
79
79
  Read the `job.yml` specification file and create all the necessary files to make the job functional, including directory structure and step instruction files. Then sync the commands to make them available.
80
80
 
81
- ### Step 1: Read and Validate the Specification
81
+ ### Step 1: Create Directory Structure Using Script
82
+
83
+ Run the `make_new_job.sh` script to create the standard directory structure:
84
+
85
+ ```bash
86
+ .deepwork/jobs/deepwork_jobs/make_new_job.sh [job_name]
87
+ ```
88
+
89
+ This creates:
90
+ - `.deepwork/jobs/[job_name]/` - Main job directory
91
+ - `.deepwork/jobs/[job_name]/steps/` - Step instruction files
92
+ - `.deepwork/jobs/[job_name]/hooks/` - Custom validation scripts (with .gitkeep)
93
+ - `.deepwork/jobs/[job_name]/templates/` - Example file formats (with .gitkeep)
94
+ - `.deepwork/jobs/[job_name]/AGENTS.md` - Job management guidance
95
+
96
+ **Note**: If the directory already exists (e.g., job.yml was created by define step), you can skip this step or manually create the additional directories:
97
+ ```bash
98
+ mkdir -p .deepwork/jobs/[job_name]/hooks .deepwork/jobs/[job_name]/templates
99
+ touch .deepwork/jobs/[job_name]/hooks/.gitkeep .deepwork/jobs/[job_name]/templates/.gitkeep
100
+ ```
101
+
102
+ ### Step 2: Read and Validate the Specification
82
103
 
83
104
  1. **Locate the job.yml file**
84
- - Read `.deepwork/jobs/[job_name]/job.yml` from the define step (Where `[job_name]` is the name of the new job that was created in the define step)
105
+ - Read `.deepwork/jobs/[job_name]/job.yml` from the define step
85
106
  - Parse the YAML content
86
107
 
87
108
  2. **Validate the specification**
@@ -95,83 +116,20 @@ Read the `job.yml` specification file and create all the necessary files to make
95
116
  - List of all steps with their details
96
117
  - Understand the workflow structure
97
118
 
98
- ### Step 2: Create Directory Structure
99
-
100
- Create the job directory in `.deepwork/jobs/[job_name]/`:
101
-
102
- ```bash
103
- mkdir -p .deepwork/jobs/[job_name]/steps
104
- ```
105
-
106
- Files to create:
107
- - `.deepwork/jobs/[job_name]/job.yml`
108
- - `.deepwork/jobs/[job_name]/steps/[step_id].md` - One for each step
109
-
110
119
  ### Step 3: Generate Step Instruction Files
111
120
 
112
121
  For each step in the job.yml, create a comprehensive instruction file at `.deepwork/jobs/[job_name]/steps/[step_id].md`.
113
122
 
114
- Each instruction file should follow this structure:
115
-
116
- ```markdown
117
- # [Step Name]
118
-
119
- ## Objective
120
-
121
- [Clear statement of what this step accomplishes, derived from the step's description]
122
-
123
- ## Task
124
-
125
- [Detailed instructions for completing this step, based on:
126
- - The step's purpose
127
- - Expected inputs and outputs
128
- - The job's overall context
129
- ]
130
-
131
- ### Process
132
-
133
- [Break down the step into substeps. Use the information gathered during define about:
134
- - What needs to be done
135
- - What makes a good output
136
- - Any quality criteria
137
- ]
123
+ **Template reference**: See `.deepwork/jobs/deepwork_jobs/templates/step_instruction.md.template` for the standard structure.
138
124
 
139
- 1. [Substep 1]
140
- 2. [Substep 2]
141
- 3. [Substep 3]
125
+ **Complete example**: See `.deepwork/jobs/deepwork_jobs/templates/step_instruction.md.example` for a fully worked example.
142
126
 
143
- [If this step has user inputs, explain how to gather them]
144
- [If this step has file inputs, explain how to use them]
145
-
146
- ## Output Format
147
-
148
- ### [output_filename_1]
149
-
150
- [Description of what should be in this output file]
151
-
152
- **Structure**:
153
- ```[file format]
154
- [Example or template of what the output should look like]
155
- ```
156
-
157
- [Repeat for each output file]
158
-
159
- ## Quality Criteria
160
-
161
- [List what makes this step's output high quality:
162
- - Completeness checks
163
- - Format requirements
164
- - Content requirements
165
- ]
166
-
167
- - [Quality criterion 1]
168
- - [Quality criterion 2]
169
- - [Quality criterion 3]
170
-
171
- ## Context
172
-
173
- [Provide context from the job's overall description to help understand why this step matters and how it fits into the bigger picture]
174
- ```
127
+ **Available templates in `.deepwork/jobs/deepwork_jobs/templates/`:**
128
+ - `job.yml.template` - Job specification structure
129
+ - `step_instruction.md.template` - Step instruction file structure
130
+ - `agents.md.template` - AGENTS.md file structure
131
+ - `job.yml.example` - Complete job specification example
132
+ - `step_instruction.md.example` - Complete step instruction example
175
133
 
176
134
  **Guidelines for generating instructions:**
177
135
 
@@ -181,6 +139,7 @@ Each instruction file should follow this structure:
181
139
  4. **Explain the "why"** - Help the user understand the step's role in the workflow
182
140
  5. **Quality over quantity** - Detailed, actionable instructions are better than vague ones
183
141
  6. **Align with stop hooks** - If the step has `stop_hooks` defined, ensure the quality criteria in the instruction file match the validation criteria in the hooks
142
+ 7. **Ask structured questions** - When a step has user inputs, the instructions MUST explicitly tell the agent to "ask structured questions" using the AskUserQuestion tool to gather that information. Never use generic phrasing like "ask the user" - always use "ask structured questions"
184
143
 
185
144
  ### Handling Stop Hooks
186
145
 
@@ -214,6 +173,12 @@ If a step in the job.yml has `stop_hooks` defined, the generated instruction fil
214
173
 
215
174
  This alignment ensures the AI agent knows exactly what will be validated and can self-check before completing.
216
175
 
176
+ ### Using Supplementary Reference Files
177
+
178
+ Step instructions can include additional `.md` files in the `steps/` directory for detailed examples, templates, or reference material. Reference them using the full path from the project root.
179
+
180
+ See `.deepwork/jobs/deepwork_jobs/steps/supplemental_file_references.md` for detailed documentation and examples.
181
+
217
182
  ### Step 4: Verify job.yml Location
218
183
 
219
184
  Verify that `job.yml` is in the correct location at `.deepwork/jobs/[job_name]/job.yml`. The define step should have created it there. If for some reason it's not there, you may need to create or move it.
@@ -297,112 +262,9 @@ Would you like me to create this policy? I can run `/deepwork_policy.define` to
297
262
 
298
263
  ## Example Implementation
299
264
 
300
- **Given this job.yml:**
301
- ```yaml
302
- name: competitive_research
303
- version: "1.0.0"
304
- summary: "Systematic competitive analysis workflow"
305
- description: |
306
- A comprehensive workflow for analyzing competitors in your market segment.
307
- Helps product teams understand the competitive landscape through systematic
308
- identification, research, comparison, and positioning recommendations.
309
-
310
- steps:
311
- - id: identify_competitors
312
- name: "Identify Competitors"
313
- description: "Identify 5-7 key competitors in the target market"
314
- instructions_file: steps/identify_competitors.md
315
- inputs:
316
- - name: market_segment
317
- description: "The market segment to analyze"
318
- - name: product_category
319
- description: "The product category"
320
- outputs:
321
- - competitors_list.md
322
- dependencies: []
323
- ```
324
-
325
- **Generate this instruction file** (`.deepwork/jobs/competitive_research/steps/identify_competitors.md`):
326
-
327
- ```markdown
328
- # Identify Competitors
329
-
330
- ## Objective
331
-
332
- Identify 5-7 key competitors in the target market segment to analyze for competitive positioning.
333
-
334
- ## Task
335
-
336
- Research and identify the most relevant competitors in the specified market segment and product category. Focus on companies that directly compete for the same customer base and solve similar problems.
337
-
338
- ### Process
339
-
340
- 1. **Understand the market context**
341
- - Review the market segment provided by the user
342
- - Understand the product category boundaries
343
- - Consider direct and indirect competitors
344
-
345
- 2. **Research competitors**
346
- - Search for companies in this space
347
- - Look for market leaders and emerging players
348
- - Consider different competitive dimensions (features, price, target market)
349
-
350
- 3. **Select 5-7 key competitors**
351
- - Prioritize direct competitors
352
- - Include at least one market leader
353
- - Include 1-2 emerging/innovative players
354
- - Ensure diversity in the competitive set
355
-
356
- 4. **Document each competitor**
357
- - Company name
358
- - Brief description (2-3 sentences)
359
- - Why they're a relevant competitor
360
- - Primary competitive dimension
361
-
362
- ## Output Format
363
-
364
- ### competitors_list.md
365
-
366
- A markdown document listing each competitor with context.
367
-
368
- **Structure**:
369
- ```markdown
370
- # Competitor Analysis: [Market Segment]
371
-
372
- ## Market Context
373
- - **Segment**: [market segment]
374
- - **Category**: [product category]
375
- - **Analysis Date**: [current date]
376
-
377
- ## Identified Competitors
378
-
379
- ### 1. [Competitor Name]
380
- **Description**: [2-3 sentence description of what they do]
381
-
382
- **Why Relevant**: [Why they're a key competitor in this space]
383
-
384
- **Competitive Dimension**: [What they compete on - e.g., price, features, market segment]
385
-
386
- [Repeat for each competitor, 5-7 total]
387
-
388
- ## Selection Rationale
389
-
390
- [Brief paragraph explaining why these specific competitors were chosen and what dimensions of competition they represent]
391
- ```
392
-
393
- ## Quality Criteria
394
-
395
- - 5-7 competitors identified (not too few, not too many)
396
- - Mix of established and emerging players
397
- - All competitors are genuinely relevant to the market segment
398
- - Each competitor has clear, specific description
399
- - Selection rationale explains the competitive landscape
400
- - Output is well-formatted and ready for use by next step
401
-
402
- ## Context
403
-
404
- This is the foundation step for competitive analysis. The competitors identified here will be deeply researched in subsequent steps, so it's important to choose the right set. Focus on competitors that will provide strategic insights for positioning decisions.
405
- ```
265
+ For a complete worked example showing a job.yml and corresponding step instruction file, see:
266
+ - **Job specification**: `.deepwork/jobs/deepwork_jobs/templates/job.yml.example`
267
+ - **Step instruction**: `.deepwork/jobs/deepwork_jobs/templates/step_instruction.md.example`
406
268
 
407
269
  ## Important Guidelines
408
270
 
@@ -421,63 +283,6 @@ Before running `deepwork sync`, verify:
421
283
  - All step instruction files exist (one per step)
422
284
  - No file system errors
423
285
 
424
- ## Output Format
425
-
426
- ### implementation_summary.md
427
-
428
- After successful implementation, create a summary:
429
-
430
- ```markdown
431
- # Job Implementation Complete: [job_name]
432
-
433
- ## Overview
434
-
435
- Successfully implemented the **[job_name]** workflow with [N] steps.
436
-
437
- **Summary**: [job summary]
438
-
439
- **Version**: [version]
440
-
441
- ## Files Created
442
-
443
- ### Job Definition
444
- - `.deepwork/jobs/[job_name]/job.yml`
445
-
446
- ### Step Instructions
447
- - `.deepwork/jobs/[job_name]/steps/[step1_id].md`
448
- - `.deepwork/jobs/[job_name]/steps/[step2_id].md`
449
- [... list all step files ...]
450
-
451
-
452
- ## Generated Commands
453
-
454
- After running `deepwork sync`, the following slash-commands are now available:
455
-
456
- - `/[job_name].[step1_id]` - [step description]
457
- - `/[job_name].[step2_id]` - [step description]
458
- [... list all commands ...]
459
-
460
- ## Next Steps
461
-
462
- 1. **Reload commands**: [Include the specific reload instructions from the `deepwork sync` output here]
463
- 2. **Start the workflow**: Run `/[job_name].[first_step_id]` to begin
464
- 3. **Test the job**: Try executing the first step to ensure everything works
465
-
466
- ## Job Structure
467
-
468
- [Show the workflow diagram with step names and dependencies]
469
-
470
- Step 1: [step_name]
471
-
472
- Step 2: [step_name]
473
-
474
- Step 3: [step_name]
475
-
476
- [Final output]
477
-
478
- The job is now ready for use!
479
- ```
480
-
481
286
  ## Completion Checklist
482
287
 
483
288
  Before marking this step complete, ensure:
@@ -487,7 +292,6 @@ Before marking this step complete, ensure:
487
292
  - [ ] `deepwork sync` executed successfully
488
293
  - [ ] Commands generated in platform directory
489
294
  - [ ] User informed to follow reload instructions from `deepwork sync`
490
- - [ ] implementation_summary.md created
491
295
  - [ ] Considered whether policies would benefit this job (Step 7)
492
296
  - [ ] If policies suggested, offered to run `/deepwork_policy.define`
493
297
 
@@ -498,6 +302,7 @@ Before marking this step complete, ensure:
498
302
  - Instructions are specific and actionable
499
303
  - Output examples are provided in each instruction file
500
304
  - Quality criteria defined for each step
305
+ - Steps with user inputs explicitly use "ask structured questions" phrasing
501
306
  - Sync completed successfully
502
307
  - Commands available for use
503
308
  - Thoughtfully considered relevant policies for the job domain
@@ -530,7 +335,7 @@ All work for this job should be done on a dedicated work branch:
530
335
  ## Output Requirements
531
336
 
532
337
  Create the following output(s):
533
- - `implementation_summary.md`
338
+ - `steps/` (directory)
534
339
  Ensure all outputs are:
535
340
  - Well-formatted and complete
536
341
  - Ready for review or use by subsequent steps
@@ -547,9 +352,9 @@ Verify the implementation meets ALL quality criteria before completing:
547
352
  3. **Specific & Actionable**: Are instructions tailored to each step's purpose, not generic?
548
353
  4. **Output Examples**: Does each instruction file show what good output looks like?
549
354
  5. **Quality Criteria**: Does each instruction file define quality criteria for its outputs?
550
- 6. **Sync Complete**: Has `deepwork sync` been run successfully?
551
- 7. **Commands Available**: Are the slash-commands generated in `.claude/commands/`?
552
- 8. **Summary Created**: Has `implementation_summary.md` been created?
355
+ 6. **Ask Structured Questions**: Do step instructions that gather user input explicitly use the phrase "ask structured questions"?
356
+ 7. **Sync Complete**: Has `deepwork sync` been run successfully?
357
+ 8. **Commands Available**: Are the slash-commands generated in `.claude/commands/`?
553
358
  9. **Policies Considered**: Have you thought about whether policies would benefit this job?
554
359
  - If relevant policies were identified, did you explain them and offer to run `/deepwork_policy.define`?
555
360
  - Not every job needs policies - only suggest when genuinely helpful.
@@ -576,7 +381,7 @@ After completing this step:
576
381
 
577
382
  2. **Inform the user**:
578
383
  - Step 2 of 3 is complete
579
- - Outputs created: implementation_summary.md
384
+ - Outputs created: steps/
580
385
  - Ready to proceed to next step: `/deepwork_jobs.learn`
581
386
 
582
387
  ## Next Step