deepwork 0.1.0__py3-none-any.whl → 0.2.0__py3-none-any.whl

deepwork/standard_jobs/deepwork_jobs/steps/learn.md

@@ -0,0 +1,288 @@
+# Learn from Job Execution
+
+## 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.
+
+## 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
+
+### Step 1: Analyze Conversation for Job Executions
+
+1. **Scan the conversation** for DeepWork slash commands that were run
+   - Look for patterns like `/job_name.step_id`
+   - Identify which jobs and steps were executed
+   - Note the order of execution
+
+2. **Identify the working folder**
+   - Should be clear from conversation history where work was done
+   - If unclear, run `git diff` to see where changes were made on the branch
+
+3. **If no job was specified**, ask the user:
+   - "Which DeepWork job would you like me to learn from?"
+   - List available jobs from `.deepwork/jobs/`
+
+### Step 2: Identify Points of Confusion and Inefficiency
+
+Review the conversation for:
+
+1. **Confusion signals**
+   - Questions the agent asked that shouldn't have been necessary
+   - Misunderstandings about what a step required
+   - Incorrect outputs that needed correction
+   - Ambiguous instructions that led to wrong interpretations
+
+2. **Inefficiency signals**
+   - Extra steps or iterations that were needed
+   - Information that had to be repeated
+   - Context that was missing from instructions
+   - Dependencies that weren't clear
+
+3. **Error patterns**
+   - Failed validations and why they failed
+   - Quality criteria that were misunderstood
+   - Edge cases that weren't handled
+
+4. **Success patterns**
+   - What worked particularly well
+   - Efficient approaches worth preserving
+   - Good examples that could be added to instructions
+
+### Step 3: Classify Learnings
+
+For each learning identified, determine if it is:
+
+**Generalizable** (should improve instructions):
+- Would help ANY future run of this job
+- Addresses unclear or missing guidance
+- Fixes incorrect assumptions in instructions
+- Adds helpful examples or context
+- Examples:
+  - "Step instructions should mention that X format is required"
+  - "Quality criteria should include checking for Y"
+  - "Add example of correct output format"
+
+**Bespoke** (should go in AGENTS.md):
+- Specific to THIS project/codebase/run
+- Depends on local conventions or structure
+- References specific files or paths
+- Would not apply to other uses of this job
+- Examples:
+  - "In this codebase, API endpoints are in `src/api/`"
+  - "This project uses camelCase for function names"
+  - "The main config file is at `config/settings.yml`"
+
+### Step 4: Update Job Instructions (Generalizable Learnings)
+
+For each generalizable learning:
+
+1. **Locate the instruction file**
+   - Path: `.deepwork/jobs/[job_name]/steps/[step_id].md`
+
+2. **Make targeted improvements**
+   - Add missing context or clarification
+   - Include helpful examples
+   - Clarify ambiguous instructions
+   - Update quality criteria if needed
+
+3. **Keep instructions concise**
+   - Avoid redundancy - don't repeat the same guidance in multiple places
+   - Be direct - remove verbose explanations that don't add value
+   - Prefer bullet points over paragraphs where appropriate
+
+4. **Preserve instruction structure**
+   - Keep existing sections (Objective, Task, Process, Output Format, Quality Criteria)
+   - Add to appropriate sections rather than restructuring
+   - Maintain consistency with other steps
+
+5. **Track changes for changelog**
+   - Note what was changed and why
+   - Prepare changelog entry for job.yml
+
+### Step 4b: Extract Shared Content into Referenced Files
+
+Review all instruction files for the job and identify content that:
+- Appears in multiple step instructions (duplicated)
+- Is lengthy and could be extracted for clarity
+- Would benefit from being maintained in one place
+
+**Extract to shared files:**
+
+1. **Create shared files** in `.deepwork/jobs/[job_name]/steps/shared/`
+   - `conventions.md` - Coding/formatting conventions used across steps
+   - `examples.md` - Common examples referenced by multiple steps
+   - `schemas.md` - Data structures or formats used throughout
+
+2. **Reference from instructions** using markdown includes or explicit references:
+   ```markdown
+   ## Conventions
+
+   Follow the conventions defined in `shared/conventions.md`.
+   ```
+
+3. **Benefits of extraction:**
+   - Single source of truth - update once, applies everywhere
+   - Shorter instruction files - easier to read and maintain
+   - Consistent guidance across steps
+
+### Step 5: Create/Update AGENTS.md (Bespoke Learnings)
+
+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
+   - This ensures the knowledge is available when working in that context
+   - If uncertain, place at the project root
+
+2. **Use file references where possible**
+   - Instead of duplicating information, reference source files
+   - This keeps AGENTS.md in sync as the codebase evolves
+   - Pattern: "See `path/to/file.ext` for [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
+   - Always prefer file references over inline content
+   - Use line numbers when referencing specific code: `file.ext:42`
+   - Group related learnings together
+
+### Step 6: Update Job Version and Changelog
+
+If instruction files were modified:
+
+1. **Bump version in job.yml**
+   - Patch version (0.0.x) for instruction improvements
+   - Minor version (0.x.0) if quality criteria changed
+
+2. **Add changelog entry**
+   ```yaml
+   - version: "[new_version]"
+     changes: "Improved [step] instructions based on execution learnings: [brief description]"
+   ```
+
+### Step 7: Sync and Relay Instructions
+
+1. **Run deepwork sync** (if instructions were modified)
+   ```bash
+   deepwork sync
+   ```
+
+2. **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)
+
+## File Reference Patterns
+
+When adding entries to AGENTS.md, prefer these patterns:
+
+**Good (references)**:
+```markdown
+- API endpoints follow REST conventions. See `src/api/routes.ts` for examples.
+- Error handling pattern: See `src/utils/errors.ts:15-30`
+- Configuration schema: Defined in `config/schema.json`
+```
+
+**Avoid (duplicating)**:
+```markdown
+- API endpoints should return JSON with this format: { status: ..., data: ... }
+- Error handling should use try/catch with custom error classes
+- Configuration requires these fields: name, version, ...
+```
+
+## Quality Criteria
+
+- Conversation has been analyzed for job executions
+- Points of confusion and inefficiency are identified
+- Learnings are correctly classified (generalizable vs bespoke)
+- Job instructions updated for generalizable improvements
+- Instructions are concise - no redundancy or unnecessary verbosity
+- 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
+- When all criteria are met, include `<promise>✓ Quality Criteria Met</promise>`
+
+## Example Dialog
+
+```
+User: /deepwork_jobs.learn
+
+Claude: I'll analyze this conversation for learnings from DeepWork job executions.
+
+**Conversation Analysis**
+
+I found the following job executions:
+1. `/competitive_research.identify_competitors` - Completed
+2. `/competitive_research.research_competitors` - Completed with 2 iterations
+3. `/competitive_research.comparative_analysis` - Completed
+
+**Identified Issues**
+
+1. **Confusion in step 2**: The instructions didn't specify that competitor research should include pricing information. This caused an extra iteration.
+
+2. **Missing context**: The agent had to ask about the industry focus, which should have been carried forward from step 1.
+
+**Classification**
+
+- Generalizable: Add pricing to research requirements in instructions
+- Bespoke: This project focuses on B2B SaaS in the HR tech space
+
+**Actions Taken**
+
+1. Updated `.deepwork/jobs/competitive_research/steps/research_competitors.md`:
+   - Added "Include pricing information (tiers, models, approximate ranges)" to research requirements
+   - Added note about carrying forward industry context from previous step
+
+2. Created `./competitive_research_output/AGENTS.md`:
+   ```markdown
+   # Project Context for Competitive Research
+
+   ## Job-Specific Context
+
+   ### competitive_research
+
+   #### Industry Focus
+   - Domain: B2B SaaS, HR Technology sector
+   - See `identify_competitors_output.md` for market definition
+
+   #### Competitors Identified
+   - Reference: `competitor_list.md` for full details
+
+   ## Last Updated
+   - Date: 2024-01-15
+   - From conversation about: Initial competitive analysis run
+   ```
+
+3. Updated job.yml version to 1.0.1 with changelog entry
+
+4. Ran `deepwork sync`
+
+**Summary**
+
+Updated job instructions and created AGENTS.md with bespoke learnings. To get the updated commands, type 'exit' then run 'claude --resume'.
+```
+
+## Handling Edge Cases
+
+**No job executions found**:
+- Ask user which job they'd like to analyze
+- Or offer to review available jobs
+
+**Multiple jobs executed**:
+- Analyze each job separately
+- Create separate AGENTS.md entries or files as appropriate
+
+**AGENTS.md already exists**:
+- Read existing content
+- Append new learnings to appropriate sections
+- Update "Last Updated" section
+
+**No issues found**:
+- Document what worked well
+- Consider if any successful patterns should be added to instructions as examples
+
+**Sensitive information**:
+- Never include secrets, credentials, or PII in AGENTS.md
+- Reference config files instead of including values

deepwork/standard_jobs/deepwork_jobs/steps/supplemental_file_references.md

@@ -0,0 +1,40 @@
+# Supplementary Reference Files
+
+Step instructions can include additional `.md` files in the `steps/` directory. These supplementary files are useful for:
+
+- Providing detailed examples or templates that would clutter the main instruction file
+- Sharing common reference material across multiple steps
+- Including technical specifications, API documentation, or style guides
+
+## How to Use
+
+1. Place additional `.md` files in the `steps/` directory alongside the main step instruction files
+2. Reference them in your step instructions using the **full path from the project root**
+
+## Example
+
+If you have a job called `my_job` and want to include an API specification template:
+
+1. Create the file at `.deepwork/jobs/my_job/steps/api_spec.md`
+2. Reference it in your step instructions like this:
+
+```markdown
+Use the template in `.deepwork/jobs/my_job/steps/api_spec.md` to structure your API endpoints.
+```
+
+## Path Format
+
+Always use the full relative path from the project root:
+
+```
+.deepwork/jobs/[job_name]/steps/[filename].md
+```
+
+For example:
+- `.deepwork/jobs/competitive_research/steps/competitor_template.md`
+- `.deepwork/jobs/api_design/steps/endpoint_schema.md`
+- `.deepwork/jobs/onboarding/steps/checklist_template.md`
+
+## Benefits
+
+Using supplementary files keeps your main step instructions focused and readable while allowing you to provide detailed reference material when needed. The AI agent can read these files during execution to get additional context.

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

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

@@ -0,0 +1,56 @@
+# DeepWork Job Specification Template
+#
+# This template shows the structure of a job.yml file.
+# Replace placeholders in [brackets] with actual values.
+
+name: [job_name]
+version: "1.0.0"
+summary: "[Brief one-line summary of what this job accomplishes - max 200 chars]"
+description: |
+  [Detailed multi-line description of the job's purpose, process, and goals.
+
+  This should explain:
+  - What problem this workflow solves
+  - What the overall process looks like
+  - What the end result will be
+  - Who the intended users are
+  - Any important context about the workflow]
+
+changelog:
+  - version: "1.0.0"
+    changes: "Initial job creation"
+
+steps:
+  - id: [step_id]
+    name: "[Step Name]"
+    description: "[What this step does]"
+    instructions_file: steps/[step_id].md
+    inputs:
+      - name: [param_name]
+        description: "[What user needs to provide]"
+      # OR for file inputs from previous steps:
+      # - file: [filename_or_path]
+      #   from_step: [previous_step_id]
+    outputs:
+      - [output_filename_or_path]  # e.g., "report.md" or "reports/analysis.md"
+    dependencies: []  # List of step IDs that must complete first
+    # Optional: Quality validation hooks
+    hooks:
+      after_agent:
+        - prompt: |
+            Verify this step's output meets quality criteria:
+            1. [Criterion 1]
+            2. [Criterion 2]
+            If ALL criteria are met, include `<promise>✓ Quality Criteria Met</promise>`.
+
+  - id: [another_step]
+    name: "[Another Step]"
+    description: "[What this step does]"
+    instructions_file: steps/[another_step].md
+    inputs:
+      - file: [output_filename_or_path]
+        from_step: [step_id]
+    outputs:
+      - [another_output_path]
+    dependencies:
+      - [step_id]  # This step requires the previous step

deepwork/standard_jobs/deepwork_jobs/templates/step_instruction.md.example

@@ -0,0 +1,82 @@
+# Example: Identify Competitors Step Instruction
+#
+# This is a complete example of a step instruction file for reference.
+
+# 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
+- When all criteria are met, include `<promise>✓ Quality Criteria Met</promise>` in your response
+
+## 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.

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

@@ -0,0 +1,58 @@
+# [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
+]
+
+1. [Substep 1]
+2. [Substep 2]
+3. [Substep 3]
+
+[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]
+- When all criteria are met, include `<promise>✓ Quality Criteria Met</promise>` in your response
+
+## Context
+
+[Provide context from the job's overall description to help understand why this step matters and how it fits into the bigger picture]

deepwork/standard_jobs/deepwork_policy/hooks/{capture_work_tree.sh → capture_prompt_work_tree.sh}

@@ -1,9 +1,10 @@
 #!/bin/bash
-# capture_work_tree.sh - Captures the current git work tree state
+# capture_prompt_work_tree.sh - Captures the git work tree state at prompt submission
 #
 # This script creates a snapshot of the current git state by recording
 # all files that have been modified, added, or deleted. This baseline
-# is used later to detect what changed during an agent session.
+# is used for policies with compare_to: prompt to detect what changed
+# during an agent response (between user prompts).
 
 set -e