deepwork 0.1.1__py3-none-any.whl → 0.3.0__py3-none-any.whl

deepwork/standard_jobs/deepwork_jobs/steps/implement.md

@@ -8,10 +8,31 @@ Generate the DeepWork job directory structure and instruction files for each ste
 
 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.
 
-### Step 1: Read and Validate the Specification
+### Step 1: Create Directory Structure Using Script
+
+Run the `make_new_job.sh` script to create the standard directory structure:
+
+```bash
+.deepwork/jobs/deepwork_jobs/make_new_job.sh [job_name]
+```
+
+This creates:
+- `.deepwork/jobs/[job_name]/` - Main job directory
+- `.deepwork/jobs/[job_name]/steps/` - Step instruction files
+- `.deepwork/jobs/[job_name]/hooks/` - Custom validation scripts (with .gitkeep)
+- `.deepwork/jobs/[job_name]/templates/` - Example file formats (with .gitkeep)
+- `.deepwork/jobs/[job_name]/AGENTS.md` - Job management guidance
+
+**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:
+```bash
+mkdir -p .deepwork/jobs/[job_name]/hooks .deepwork/jobs/[job_name]/templates
+touch .deepwork/jobs/[job_name]/hooks/.gitkeep .deepwork/jobs/[job_name]/templates/.gitkeep
+```
+
+### Step 2: Read and Validate the Specification
 
 1. **Locate the job.yml file**
-   - 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)
+   - Read `.deepwork/jobs/[job_name]/job.yml` from the define step
    - Parse the YAML content
 
 2. **Validate the specification**
@@ -25,83 +46,20 @@ Read the `job.yml` specification file and create all the necessary files to make
    - List of all steps with their details
    - Understand the workflow structure
 
-### Step 2: Create Directory Structure
-
-Create the job directory in `.deepwork/jobs/[job_name]/`:
-
-```bash
-mkdir -p .deepwork/jobs/[job_name]/steps
-```
-
-Files to create:
-- `.deepwork/jobs/[job_name]/job.yml`
-- `.deepwork/jobs/[job_name]/steps/[step_id].md` - One for each step
-
 ### Step 3: Generate Step Instruction Files
 
 For each step in the job.yml, create a comprehensive instruction file at `.deepwork/jobs/[job_name]/steps/[step_id].md`.
 
-Each instruction file should follow this structure:
-
-```markdown
-# [Step Name]
-
-## Objective
-
-[Clear statement of what this step accomplishes, derived from the step's description]
-
-## Task
-
-[Detailed instructions for completing this step, based on:
-- The step's purpose
-- Expected inputs and outputs
-- The job's overall context
-]
-
-### Process
-
-[Break down the step into substeps. Use the information gathered during define about:
-- What needs to be done
-- What makes a good output
-- Any quality criteria
-]
+**Template reference**: See `.deepwork/jobs/deepwork_jobs/templates/step_instruction.md.template` for the standard structure.
 
-1. [Substep 1]
-2. [Substep 2]
-3. [Substep 3]
+**Complete example**: See `.deepwork/jobs/deepwork_jobs/templates/step_instruction.md.example` for a fully worked example.
 
-[If this step has user inputs, explain how to gather them]
-[If this step has file inputs, explain how to use them]
-
-## Output Format
-
-### [output_filename_1]
-
-[Description of what should be in this output file]
-
-**Structure**:
-```[file format]
-[Example or template of what the output should look like]
-```
-
-[Repeat for each output file]
-
-## Quality Criteria
-
-[List what makes this step's output high quality:
-- Completeness checks
-- Format requirements
-- Content requirements
-]
-
-- [Quality criterion 1]
-- [Quality criterion 2]
-- [Quality criterion 3]
-
-## Context
-
-[Provide context from the job's overall description to help understand why this step matters and how it fits into the bigger picture]
-```
+**Available templates in `.deepwork/jobs/deepwork_jobs/templates/`:**
+- `job.yml.template` - Job specification structure
+- `step_instruction.md.template` - Step instruction file structure
+- `agents.md.template` - AGENTS.md file structure
+- `job.yml.example` - Complete job specification example
+- `step_instruction.md.example` - Complete step instruction example
 
 **Guidelines for generating instructions:**
 
@@ -111,6 +69,7 @@ Each instruction file should follow this structure:
 4. **Explain the "why"** - Help the user understand the step's role in the workflow
 5. **Quality over quantity** - Detailed, actionable instructions are better than vague ones
 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
+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"
 
 ### Handling Stop Hooks
 
@@ -154,9 +113,9 @@ See `.deepwork/jobs/deepwork_jobs/steps/supplemental_file_references.md` for det
 
 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.
 
-### Step 5: Sync Commands
+### Step 5: Sync Skills
 
-Run `deepwork sync` to generate the slash-commands for this job:
+Run `deepwork sync` to generate the skills for this job:
 
 ```bash
 deepwork sync
@@ -164,26 +123,26 @@ deepwork sync
 
 This will:
 - Parse the job definition
-- Generate slash-commands for each step
-- Make the commands available in `.claude/commands/` (or appropriate platform directory)
+- Generate skills for each step
+- Make the skills available in `.claude/skills/` (or appropriate platform directory)
 
 ### Step 6: Relay Reload Instructions
 
-After running `deepwork sync`, look at the "To use the new commands" section in the output. **Relay these exact reload instructions to the user** so they know how to pick up the new commands. Don't just reference the sync output - tell them directly what they need to do (e.g., "Type 'exit' then run 'claude --resume'" for Claude Code, or "Run '/memory refresh'" for Gemini CLI).
+After running `deepwork sync`, look at the "To use the new skills" section in the output. **Relay these exact reload instructions to the user** so they know how to pick up the new skills. Don't just reference the sync output - tell them directly what they need to do (e.g., "Type 'exit' then run 'claude --resume'" for Claude Code, or "Run '/memory refresh'" for Gemini CLI).
 
-### Step 7: Consider Policies for the New Job
+### Step 7: Consider Rules for the New Job
 
-After implementing the job, consider whether there are **policies** that would help enforce quality or consistency when working with this job's domain.
+After implementing the job, consider whether there are **rules** that would help enforce quality or consistency when working with this job's domain.
 
-**What are policies?**
+**What are rules?**
 
-Policies are automated guardrails defined in `.deepwork.policy.yml` that trigger when certain files change during an AI session. They help ensure:
+Rules are automated guardrails stored as markdown files in `.deepwork/rules/` that trigger when certain files change during an AI session. They help ensure:
 - Documentation stays in sync with code
 - Team guidelines are followed
 - Architectural decisions are respected
 - Quality standards are maintained
 
-**When to suggest policies:**
+**When to suggest rules:**
 
 Think about the job you just implemented and ask:
 - Does this job produce outputs that other files depend on?
@@ -191,28 +150,28 @@ Think about the job you just implemented and ask:
 - Are there quality checks or reviews that should happen when certain files in this domain change?
 - Could changes to the job's output files impact other parts of the project?
 
-**Examples of policies that might make sense:**
+**Examples of rules that might make sense:**
 
-| Job Type | Potential Policy |
-|----------|------------------|
+| Job Type | Potential Rule |
+|----------|----------------|
 | API Design | "Update API docs when endpoint definitions change" |
 | Database Schema | "Review migrations when schema files change" |
 | Competitive Research | "Update strategy docs when competitor analysis changes" |
 | Feature Development | "Update changelog when feature files change" |
 | Configuration Management | "Update install guide when config files change" |
 
-**How to offer policy creation:**
+**How to offer rule creation:**
 
-If you identify one or more policies that would benefit the user, explain:
-1. **What the policy would do** - What triggers it and what action it prompts
+If you identify one or more rules that would benefit the user, explain:
+1. **What the rule would do** - What triggers it and what action it prompts
 2. **Why it would help** - How it prevents common mistakes or keeps things in sync
 3. **What files it would watch** - The trigger patterns
 
 Then ask the user:
 
-> "Would you like me to create this policy for you? I can run `/deepwork_policy.define` to set it up."
+> "Would you like me to create this rule for you? I can run `/deepwork_rules.define` to set it up."
 
-If the user agrees, invoke the `/deepwork_policy.define` command to guide them through creating the policy.
+If the user agrees, invoke the `/deepwork_rules.define` command to guide them through creating the rule.
 
 **Example dialogue:**
 
@@ -221,124 +180,21 @@ Based on the competitive_research job you just created, I noticed that when
 competitor analysis files change, it would be helpful to remind you to update
 your strategy documentation.
 
-I'd suggest a policy like:
+I'd suggest a rule like:
 - **Name**: "Update strategy when competitor analysis changes"
 - **Trigger**: `**/positioning_report.md`
 - **Action**: Prompt to review and update `docs/strategy.md`
 
-Would you like me to create this policy? I can run `/deepwork_policy.define` to set it up.
+Would you like me to create this rule? I can run `/deepwork_rules.define` to set it up.
 ```
 
-**Note:** Not every job needs policies. Only suggest them when they would genuinely help maintain consistency or quality. Don't force policies where they don't make sense.
+**Note:** Not every job needs rules. Only suggest them when they would genuinely help maintain consistency or quality. Don't force rules where they don't make sense.
 
 ## Example Implementation
 
-**Given this job.yml:**
-```yaml
-name: competitive_research
-version: "1.0.0"
-summary: "Systematic competitive analysis workflow"
-description: |
-  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:
-  - id: identify_competitors
-    name: "Identify Competitors"
-    description: "Identify 5-7 key competitors in the target market"
-    instructions_file: steps/identify_competitors.md
-    inputs:
-      - name: market_segment
-        description: "The market segment to analyze"
-      - name: product_category
-        description: "The product category"
-    outputs:
-      - competitors_list.md
-    dependencies: []
-```
-
-**Generate this instruction file** (`.deepwork/jobs/competitive_research/steps/identify_competitors.md`):
-
-```markdown
-# Identify Competitors
-
-## Objective
-
-Identify 5-7 key competitors in the target market segment to analyze for competitive positioning.
-
-## Task
-
-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.
-
-### Process
-
-1. **Understand the market context**
-   - Review the market segment provided by the user
-   - Understand the product category boundaries
-   - Consider direct and indirect competitors
-
-2. **Research competitors**
-   - Search for companies in this space
-   - Look for market leaders and emerging players
-   - Consider different competitive dimensions (features, price, target market)
-
-3. **Select 5-7 key competitors**
-   - Prioritize direct competitors
-   - Include at least one market leader
-   - Include 1-2 emerging/innovative players
-   - Ensure diversity in the competitive set
-
-4. **Document each competitor**
-   - Company name
-   - Brief description (2-3 sentences)
-   - Why they're a relevant competitor
-   - Primary competitive dimension
-
-## Output Format
-
-### competitors_list.md
-
-A markdown document listing each competitor with context.
-
-**Structure**:
-```markdown
-# Competitor Analysis: [Market Segment]
-
-## Market Context
-- **Segment**: [market segment]
-- **Category**: [product category]
-- **Analysis Date**: [current date]
-
-## Identified Competitors
-
-### 1. [Competitor Name]
-**Description**: [2-3 sentence description of what they do]
-
-**Why Relevant**: [Why they're a key competitor in this space]
-
-**Competitive Dimension**: [What they compete on - e.g., price, features, market segment]
-
-[Repeat for each competitor, 5-7 total]
-
-## Selection Rationale
-
-[Brief paragraph explaining why these specific competitors were chosen and what dimensions of competition they represent]
-```
-
-## Quality Criteria
-
-- 5-7 competitors identified (not too few, not too many)
-- Mix of established and emerging players
-- All competitors are genuinely relevant to the market segment
-- Each competitor has clear, specific description
-- Selection rationale explains the competitive landscape
-- Output is well-formatted and ready for use by next step
-
-## Context
-
-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.
-```
+For a complete worked example showing a job.yml and corresponding step instruction file, see:
+- **Job specification**: `.deepwork/jobs/deepwork_jobs/templates/job.yml.example`
+- **Step instruction**: `.deepwork/jobs/deepwork_jobs/templates/step_instruction.md.example`
 
 ## Important Guidelines
 
@@ -357,63 +213,6 @@ Before running `deepwork sync`, verify:
 - All step instruction files exist (one per step)
 - No file system errors
 
-## Output Format
-
-### implementation_summary.md
-
-After successful implementation, create a summary:
-
-```markdown
-# Job Implementation Complete: [job_name]
-
-## Overview
-
-Successfully implemented the **[job_name]** workflow with [N] steps.
-
-**Summary**: [job summary]
-
-**Version**: [version]
-
-## Files Created
-
-### Job Definition
-- `.deepwork/jobs/[job_name]/job.yml`
-
-### Step Instructions
-- `.deepwork/jobs/[job_name]/steps/[step1_id].md`
-- `.deepwork/jobs/[job_name]/steps/[step2_id].md`
-[... list all step files ...]
-
-
-## Generated Commands
-
-After running `deepwork sync`, the following slash-commands are now available:
-
-- `/[job_name].[step1_id]` - [step description]
-- `/[job_name].[step2_id]` - [step description]
-[... list all commands ...]
-
-## Next Steps
-
-1. **Reload commands**: [Include the specific reload instructions from the `deepwork sync` output here]
-2. **Start the workflow**: Run `/[job_name].[first_step_id]` to begin
-3. **Test the job**: Try executing the first step to ensure everything works
-
-## Job Structure
-
-[Show the workflow diagram with step names and dependencies]
-
-Step 1: [step_name]
-  ↓
-Step 2: [step_name]
-  ↓
-Step 3: [step_name]
-  ↓
-[Final output]
-
-The job is now ready for use!
-```
-
 ## Completion Checklist
 
 Before marking this step complete, ensure:
@@ -421,11 +220,10 @@ Before marking this step complete, ensure:
 - [ ] All step instruction files created
 - [ ] Each instruction file is complete and actionable
 - [ ] `deepwork sync` executed successfully
-- [ ] Commands generated in platform directory
+- [ ] Skills generated in platform directory
 - [ ] User informed to follow reload instructions from `deepwork sync`
-- [ ] implementation_summary.md created
-- [ ] Considered whether policies would benefit this job (Step 7)
-- [ ] If policies suggested, offered to run `/deepwork_policy.define`
+- [ ] Considered whether rules would benefit this job (Step 7)
+- [ ] If rules suggested, offered to run `/deepwork_rules.define`
 
 ## Quality Criteria
 
@@ -434,6 +232,7 @@ Before marking this step complete, ensure:
 - Instructions are specific and actionable
 - Output examples are provided in each instruction file
 - Quality criteria defined for each step
+- Steps with user inputs explicitly use "ask structured questions" phrasing
 - Sync completed successfully
-- Commands available for use
-- Thoughtfully considered relevant policies for the job domain
+- Skills available for use
+- Thoughtfully considered relevant rules for the job domain

deepwork/standard_jobs/deepwork_jobs/steps/learn.md

@@ -142,42 +142,7 @@ The AGENTS.md file captures project-specific knowledge that helps future agent r
    - This keeps AGENTS.md in sync as the codebase evolves
    - Pattern: "See `path/to/file.ext` for [description]"
 
-3. **AGENTS.md structure**:
-
-```markdown
-# Project Context for [Job Name]
-
-## Codebase Structure
-
-<!-- Reference files rather than duplicating content -->
-- Project structure: See `README.md` for overview
-- API documentation: See `docs/api.md`
-- Configuration: See `config/README.md`
-
-## Conventions
-
-### Naming Conventions
-- [Convention]: See example in `path/to/example.ext:LINE`
-
-### File Organization
-- [Pattern]: Reference `path/to/pattern/`
-
-## Job-Specific Context
-
-### [Job Name]
-
-#### [Step Name]
-- [Learning]: Reference `relevant/file.ext`
-- [Context]: [Brief explanation with file reference]
-
-## Known Issues and Workarounds
-
-- [Issue]: [Workaround with file reference if applicable]
-
-## Last Updated
-- Date: [YYYY-MM-DD]
-- From conversation about: [Brief description]
-```
+3. **AGENTS.md structure**: See `.deepwork/jobs/deepwork_jobs/templates/agents.md.template` for the standard format.
 
 4. **Writing entries**
    - Be concise but specific
@@ -199,36 +164,14 @@ If instruction files were modified:
      changes: "Improved [step] instructions based on execution learnings: [brief description]"
    ```
 
-### Step 7: Sync and Summarize
+### Step 7: Sync and Relay Instructions
 
 1. **Run deepwork sync** (if instructions were modified)
    ```bash
    deepwork sync
    ```
 
-2. **Create learning_summary.md** in the working folder:
-   ```markdown
-   # Learning Summary
-
-   ## Job Analyzed
-   - Job: [job_name]
-   - Steps executed: [list of steps]
-
-   ## Generalizable Improvements Made
-   - [Step]: [What was improved]
-
-   ## Bespoke Learnings Captured
-   - Location: [path to AGENTS.md]
-   - Entries added: [list of entries]
-
-   ## Files Modified
-   - [List of files changed]
-
-   ## Recommendations
-   - [Any additional suggestions]
-   ```
-
-3. **If commands were regenerated**, look at the "To use the new commands" section in the `deepwork sync` output and **relay these exact reload instructions to the user** (e.g., "Type 'exit' then run 'claude --resume'" for Claude Code)
+2. **If skills were regenerated**, look at the "To use the new skills" section in the `deepwork sync` output and **relay these exact reload instructions to the user** (e.g., "Type 'exit' then run 'claude --resume'" for Claude Code)
 
 ## File Reference Patterns
 
@@ -259,7 +202,6 @@ When adding entries to AGENTS.md, prefer these patterns:
 - AGENTS.md created/updated with bespoke learnings
 - File references used instead of duplicating content
 - AGENTS.md is in the correct working folder
-- learning_summary.md documents all changes
 - When all criteria are met, include `<promise>✓ Quality Criteria Met</promise>`
 
 ## Example Dialog
@@ -319,7 +261,7 @@ I found the following job executions:
 
 **Summary**
 
-Created `learning_summary.md` documenting all changes. To get the updated commands, type 'exit' then run 'claude --resume'.
+Updated job instructions and created AGENTS.md with bespoke learnings. To get the updated skills, type 'exit' then run 'claude --resume'.
 ```
 
 ## Handling Edge Cases

deepwork/standard_jobs/deepwork_jobs/templates/agents.md.template

@@ -0,0 +1,32 @@
+# Project Context for [Job Name]
+
+## Codebase Structure
+
+<!-- Reference files rather than duplicating content -->
+- Project structure: See `README.md` for overview
+- API documentation: See `docs/api.md`
+- Configuration: See `config/README.md`
+
+## Conventions
+
+### Naming Conventions
+- [Convention]: See example in `path/to/example.ext:LINE`
+
+### File Organization
+- [Pattern]: Reference `path/to/pattern/`
+
+## Job-Specific Context
+
+### [Job Name]
+
+#### [Step Name]
+- [Learning]: Reference `relevant/file.ext`
+- [Context]: [Brief explanation with file reference]
+
+## Known Issues and Workarounds
+
+- [Issue]: [Workaround with file reference if applicable]
+
+## Last Updated
+- Date: [YYYY-MM-DD]
+- From conversation about: [Brief description]

deepwork/standard_jobs/deepwork_jobs/templates/job.yml.example

@@ -0,0 +1,73 @@
+# Example: Competitive Research Job
+#
+# This is a complete example of a job.yml file for reference.
+
+name: competitive_research
+version: "1.0.0"
+summary: "Systematic competitive analysis workflow"
+description: |
+  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.
+
+changelog:
+  - version: "1.0.0"
+    changes: "Initial job creation"
+
+steps:
+  - id: identify_competitors
+    name: "Identify Competitors"
+    description: "Identify 5-7 key competitors in the target market"
+    instructions_file: steps/identify_competitors.md
+    inputs:
+      - name: market_segment
+        description: "The market segment to analyze"
+      - name: product_category
+        description: "The product category"
+    outputs:
+      - competitors_list.md
+    dependencies: []
+
+  - id: research_competitors
+    name: "Research Competitors"
+    description: "Deep dive research on each identified competitor"
+    instructions_file: steps/research_competitors.md
+    inputs:
+      - file: competitors_list.md
+        from_step: identify_competitors
+    outputs:
+      - research_notes.md
+    dependencies:
+      - identify_competitors
+    hooks:
+      after_agent:
+        - prompt: |
+            Verify the research meets criteria:
+            1. Each competitor has at least 3 data points
+            2. Sources are cited
+            3. Information is current (within last year)
+            If ALL criteria are met, include `<promise>✓ Quality Criteria Met</promise>`.
+
+  - id: comparative_analysis
+    name: "Comparative Analysis"
+    description: "Create side-by-side comparison matrix"
+    instructions_file: steps/comparative_analysis.md
+    inputs:
+      - file: research_notes.md
+        from_step: research_competitors
+    outputs:
+      - comparison_matrix.md
+    dependencies:
+      - research_competitors
+
+  - id: positioning_recommendations
+    name: "Positioning Recommendations"
+    description: "Strategic positioning recommendations based on analysis"
+    instructions_file: steps/positioning_recommendations.md
+    inputs:
+      - file: comparison_matrix.md
+        from_step: comparative_analysis
+    outputs:
+      - positioning_report.md
+    dependencies:
+      - comparative_analysis