deepwork 0.1.0__tar.gz → 0.1.1__tar.gz

{deepwork-0.1.0 → deepwork-0.1.1}/.claude/commands/deepwork_jobs.define.md

@@ -44,14 +44,15 @@ hooks:
 ## Job Overview
 
 Core commands for managing DeepWork jobs. These commands help you define new multi-step
-workflows and refine existing ones.
+workflows and learn from running them.
 
 The `define` command guides you through an interactive process to create a new job by
 asking detailed questions about your workflow, understanding each step's inputs and outputs,
 and generating all necessary files.
 
-The `refine` command helps you modify existing jobs safely by understanding what you want
-to change, validating the impact, and ensuring consistency across your workflow.
+The `learn` command reflects on conversations where DeepWork jobs were run, identifies
+confusion or inefficiencies, and improves job instructions. It also captures bespoke
+learnings specific to the current run into AGENTS.md files in the working folder.
 
 
 

{deepwork-0.1.0 → deepwork-0.1.1}/.claude/commands/deepwork_jobs.implement.md

@@ -48,14 +48,15 @@ hooks:
 ## Job Overview
 
 Core commands for managing DeepWork jobs. These commands help you define new multi-step
-workflows and refine existing ones.
+workflows and learn from running them.
 
 The `define` command guides you through an interactive process to create a new job by
 asking detailed questions about your workflow, understanding each step's inputs and outputs,
 and generating all necessary files.
 
-The `refine` command helps you modify existing jobs safely by understanding what you want
-to change, validating the impact, and ensuring consistency across your workflow.
+The `learn` command reflects on conversations where DeepWork jobs were run, identifies
+confusion or inefficiencies, and improves job instructions. It also captures bespoke
+learnings specific to the current run into AGENTS.md files in the working folder.
 
 
 ## Prerequisites
@@ -230,11 +231,9 @@ This will:
 - Generate slash-commands for each step
 - Make the commands available in `.claude/commands/` (or appropriate platform directory)
 
-### Step 6: Reload Commands
+### Step 6: Relay Reload Instructions
 
-Instruct the user to reload commands in their current session:
-- Run `/reload` command (if available)
-- Or restart the Claude session
+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).
 
 ### Step 7: Consider Policies for the New Job
 
@@ -460,7 +459,7 @@ After running `deepwork sync`, the following slash-commands are now available:
 
 ## Next Steps
 
-1. **Reload commands**: Run `/reload` or restart your Claude session
+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
 
@@ -487,7 +486,7 @@ Before marking this step complete, ensure:
 - [ ] Each instruction file is complete and actionable
 - [ ] `deepwork sync` executed successfully
 - [ ] Commands generated in platform directory
-- [ ] User informed of next steps (reload commands)
+- [ ] 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`
@@ -578,13 +577,13 @@ After completing this step:
 2. **Inform the user**:
    - Step 2 of 3 is complete
    - Outputs created: implementation_summary.md
-   - Ready to proceed to next step: `/deepwork_jobs.refine`
+   - Ready to proceed to next step: `/deepwork_jobs.learn`
 
 ## Next Step
 
 To continue the workflow, run:
 ```
-/deepwork_jobs.refine
+/deepwork_jobs.learn
 ```
 
 ---

deepwork-0.1.1/.claude/commands/deepwork_jobs.learn.md

@@ -0,0 +1,499 @@
+---
+description: Reflect on conversation to improve job instructions and capture learnings
+hooks:
+  Stop:
+    - hooks:
+        - type: prompt
+          prompt: |
+            You must evaluate whether Claude has met all the below quality criteria for the request.
+
+            ## Quality Criteria
+
+            Verify the learning process meets ALL quality criteria before completing:
+
+            1. **Conversation Analyzed**: Did you review the conversation for DeepWork job executions?
+            2. **Confusion Identified**: Did you identify points of confusion, errors, or inefficiencies?
+            3. **Instructions Improved**: Were job instructions updated to address identified issues?
+            4. **Instructions Concise**: Are instructions free of redundancy and unnecessary verbosity?
+            5. **Shared Content Extracted**: Is lengthy/duplicated content extracted into referenced files?
+            6. **Bespoke Learnings Captured**: Were run-specific learnings added to AGENTS.md?
+            7. **File References Used**: Do AGENTS.md entries reference other files where appropriate?
+            8. **Working Folder Correct**: Is AGENTS.md in the correct working folder for the job?
+            9. **Generalizable Separated**: Are generalizable improvements in instructions, not AGENTS.md?
+            10. **Sync Complete**: Has `deepwork sync` been run if instructions were modified?
+
+            If ANY criterion is not met, continue working to address it.
+            If ALL criteria are satisfied, include `<promise>✓ Quality Criteria Met</promise>` in your response.
+
+
+            ## Instructions
+
+            Review the conversation and determine if ALL quality criteria above have been satisfied.
+            Look for evidence that each criterion has been addressed.
+
+            If the agent has included `<promise>✓ Quality Criteria Met</promise>` in their response AND
+            all criteria appear to be met, respond with: {"ok": true}
+
+            If criteria are NOT met AND the promise tag is missing, respond with:
+            {"ok": false, "reason": "Continue working. [specific feedback on what's wrong]"}
+---
+
+# deepwork_jobs.learn
+
+**Standalone command** in the **deepwork_jobs** job - can be run anytime
+
+**Summary**: DeepWork job management commands
+
+## Job Overview
+
+Core commands for managing DeepWork jobs. These commands help you define new multi-step
+workflows and learn from running them.
+
+The `define` command guides you through an interactive process to create a new job by
+asking detailed questions about your workflow, understanding each step's inputs and outputs,
+and generating all necessary files.
+
+The `learn` command reflects on conversations where DeepWork jobs were run, identifies
+confusion or inefficiencies, and improves job instructions. It also captures bespoke
+learnings specific to the current run into AGENTS.md files in the working folder.
+
+
+
+## Instructions
+
+# 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**:
+
+```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]
+```
+
+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 Summarize
+
+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)
+
+## 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
+- learning_summary.md documents all changes
+- 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**
+
+Created `learning_summary.md` documenting all changes. 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
+
+
+## Inputs
+
+### User Parameters
+
+Please gather the following information from the user:
+- **job_name**: Name of the job that was run (optional - will auto-detect from conversation)
+
+
+## Work Branch Management
+
+All work for this job should be done on a dedicated work branch:
+
+1. **Check current branch**:
+   - If already on a work branch for this job (format: `deepwork/deepwork_jobs-[instance]-[date]`), continue using it
+   - If on main/master, create a new work branch
+
+2. **Create work branch** (if needed):
+   ```bash
+   git checkout -b deepwork/deepwork_jobs-[instance]-$(date +%Y%m%d)
+   ```
+   Replace `[instance]` with a descriptive identifier (e.g., `acme`, `q1-launch`, etc.)
+
+## Output Requirements
+
+Create the following output(s):
+- `learning_summary.md`
+Ensure all outputs are:
+- Well-formatted and complete
+- Ready for review or use by subsequent steps
+
+## Quality Validation Loop
+
+This step uses an iterative quality validation loop. After completing your work, stop hook(s) will evaluate whether the outputs meet quality criteria. If criteria are not met, you will be prompted to continue refining.
+
+### Quality Criteria
+Verify the learning process meets ALL quality criteria before completing:
+
+1. **Conversation Analyzed**: Did you review the conversation for DeepWork job executions?
+2. **Confusion Identified**: Did you identify points of confusion, errors, or inefficiencies?
+3. **Instructions Improved**: Were job instructions updated to address identified issues?
+4. **Instructions Concise**: Are instructions free of redundancy and unnecessary verbosity?
+5. **Shared Content Extracted**: Is lengthy/duplicated content extracted into referenced files?
+6. **Bespoke Learnings Captured**: Were run-specific learnings added to AGENTS.md?
+7. **File References Used**: Do AGENTS.md entries reference other files where appropriate?
+8. **Working Folder Correct**: Is AGENTS.md in the correct working folder for the job?
+9. **Generalizable Separated**: Are generalizable improvements in instructions, not AGENTS.md?
+10. **Sync Complete**: Has `deepwork sync` been run if instructions were modified?
+
+If ANY criterion is not met, continue working to address it.
+If ALL criteria are satisfied, include `<promise>✓ Quality Criteria Met</promise>` in your response.
+
+
+### Completion Promise
+
+To signal that all quality criteria have been met, include this tag in your final response:
+
+```
+<promise>✓ Quality Criteria Met</promise>
+```
+
+**Important**: Only include this promise tag when you have verified that ALL quality criteria above are satisfied. The validation loop will continue until this promise is detected.
+
+## Completion
+
+After completing this step:
+
+1. **Verify outputs**: Confirm all required files have been created
+
+2. **Inform the user**:
+   - The learn command is complete
+   - Outputs created: learning_summary.md
+   - This command can be run again anytime to make further changes
+
+## Command Complete
+
+This is a standalone command that can be run anytime. The outputs are ready for use.
+
+Consider:
+- Reviewing the outputs
+- Running `deepwork sync` if job definitions were changed
+- Re-running this command later if further changes are needed
+
+---
+
+## Context Files
+
+- Job definition: `.deepwork/jobs/deepwork_jobs/job.yml`
+- Step instructions: `.deepwork/jobs/deepwork_jobs/steps/learn.md`

{deepwork-0.1.0 → deepwork-0.1.1}/.deepwork/jobs/deepwork_jobs/job.yml

@@ -1,20 +1,23 @@
 name: deepwork_jobs
-version: "0.1.0"
+version: "0.2.0"
 summary: "DeepWork job management commands"
 description: |
   Core commands for managing DeepWork jobs. These commands help you define new multi-step
-  workflows and refine existing ones.
+  workflows and learn from running them.
 
   The `define` command guides you through an interactive process to create a new job by
   asking detailed questions about your workflow, understanding each step's inputs and outputs,
   and generating all necessary files.
 
-  The `refine` command helps you modify existing jobs safely by understanding what you want
-  to change, validating the impact, and ensuring consistency across your workflow.
+  The `learn` command reflects on conversations where DeepWork jobs were run, identifies
+  confusion or inefficiencies, and improves job instructions. It also captures bespoke
+  learnings specific to the current run into AGENTS.md files in the working folder.
 
 changelog:
   - version: "0.1.0"
     changes: "Initial version"
+  - version: "0.2.0"
+    changes: "Replaced refine command with learn command for conversation-driven improvement"
 
 steps:
   - id: define
@@ -74,29 +77,31 @@ steps:
             If ANY criterion is not met, continue working to address it.
             If ALL criteria are satisfied, include `<promise>✓ Quality Criteria Met</promise>` in your response.
 
-  - id: refine
-    name: "Refine Existing Job"
-    description: "Modify an existing job definition"
-    instructions_file: steps/refine.md
+  - id: learn
+    name: "Learn from Job Execution"
+    description: "Reflect on conversation to improve job instructions and capture learnings"
+    instructions_file: steps/learn.md
     inputs:
       - name: job_name
-        description: "Name of the job to refine"
+        description: "Name of the job that was run (optional - will auto-detect from conversation)"
     outputs:
-      - job.yml
+      - learning_summary.md
     dependencies: []
     hooks:
       after_agent:
         - prompt: |
-            Verify the refinement meets ALL quality criteria before completing:
+            Verify the learning process meets ALL quality criteria before completing:
 
-            1. **Job Consistency**: Do the changes maintain overall job consistency?
-            2. **Valid Dependencies**: Are all step dependencies logically valid (no circular refs)?
-            3. **Semantic Versioning**: Was the version bumped appropriately (major/minor/patch)?
-            4. **Changelog Updated**: Is the changelog updated with a description of changes?
-            5. **User Understanding**: Does the user understand the impact of the changes?
-            6. **Breaking Changes**: Were any breaking changes clearly communicated?
-            7. **Files Updated**: Are all affected files (job.yml, step files) updated?
-            8. **Sync Complete**: Has `deepwork sync` been run to regenerate commands?
+            1. **Conversation Analyzed**: Did you review the conversation for DeepWork job executions?
+            2. **Confusion Identified**: Did you identify points of confusion, errors, or inefficiencies?
+            3. **Instructions Improved**: Were job instructions updated to address identified issues?
+            4. **Instructions Concise**: Are instructions free of redundancy and unnecessary verbosity?
+            5. **Shared Content Extracted**: Is lengthy/duplicated content extracted into referenced files?
+            6. **Bespoke Learnings Captured**: Were run-specific learnings added to AGENTS.md?
+            7. **File References Used**: Do AGENTS.md entries reference other files where appropriate?
+            8. **Working Folder Correct**: Is AGENTS.md in the correct working folder for the job?
+            9. **Generalizable Separated**: Are generalizable improvements in instructions, not AGENTS.md?
+            10. **Sync Complete**: Has `deepwork sync` been run if instructions were modified?
 
             If ANY criterion is not met, continue working to address it.
             If ALL criteria are satisfied, include `<promise>✓ Quality Criteria Met</promise>` in your response.