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

deepwork/standard_jobs/deepwork_jobs/job.yml

@@ -1,12 +1,12 @@
 name: deepwork_jobs
-version: "0.2.0"
+version: "0.5.0"
 summary: "DeepWork job management commands"
 description: |
   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,
+  asking structured 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
@@ -18,6 +18,12 @@ changelog:
     changes: "Initial version"
   - version: "0.2.0"
     changes: "Replaced refine command with learn command for conversation-driven improvement"
+  - version: "0.3.0"
+    changes: "Added make_new_job.sh script and templates directory; updated instructions to reference templates instead of inline examples"
+  - version: "0.4.0"
+    changes: "Removed implementation_summary and learning_summary outputs; simplified step outputs"
+  - version: "0.5.0"
+    changes: "Standardized on 'ask structured questions' phrasing for user input; Updated quality criteria hooks to verify phrase usage; Added guidance in implement.md to use phrase in generated instructions"
 
 steps:
   - id: define
@@ -30,21 +36,15 @@ steps:
     outputs:
       - job.yml
     dependencies: []
-    hooks:
-      after_agent:
-        - prompt: |
-            Verify the job.yml output meets ALL quality criteria before completing:
-
-            1. **User Understanding**: Did you fully understand the user's workflow through interactive Q&A?
-            2. **Clear Inputs/Outputs**: Does every step have clearly defined inputs and outputs?
-            3. **Logical Dependencies**: Do step dependencies make sense and avoid circular references?
-            4. **Concise Summary**: Is the summary under 200 characters and descriptive?
-            5. **Rich Description**: Does the description provide enough context for future refinement?
-            6. **Valid Schema**: Does the job.yml follow the required schema (name, version, summary, steps)?
-            7. **File Created**: Has the job.yml file been created in `.deepwork/jobs/[job_name]/job.yml`?
-
-            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.
+    quality_criteria:
+      - "**User Understanding**: Did the agent fully understand the user's workflow by asking structured questions?"
+      - "**Structured Questions Used**: Did the agent ask structured questions (using the AskUserQuestion tool) to gather user input?"
+      - "**Clear Inputs/Outputs**: Does every step have clearly defined inputs and outputs?"
+      - "**Logical Dependencies**: Do step dependencies make sense and avoid circular references?"
+      - "**Concise Summary**: Is the summary under 200 characters and descriptive?"
+      - "**Rich Description**: Does the description provide enough context for future refinement?"
+      - "**Valid Schema**: Does the job.yml follow the required schema (name, version, summary, steps)?"
+      - "**File Created**: Has the job.yml file been created in `.deepwork/jobs/[job_name]/job.yml`?"
 
   - id: implement
     name: "Implement Job Steps"
@@ -54,54 +54,39 @@ steps:
       - file: job.yml
         from_step: define
     outputs:
-      - implementation_summary.md
+      - steps/
     dependencies:
       - define
-    hooks:
-      after_agent:
-        - prompt: |
-            Verify the implementation meets ALL quality criteria before completing:
-
-            1. **Directory Structure**: Is `.deepwork/jobs/[job_name]/` created correctly?
-            2. **Complete Instructions**: Are ALL step instruction files complete (not stubs or placeholders)?
-            3. **Specific & Actionable**: Are instructions tailored to each step's purpose, not generic?
-            4. **Output Examples**: Does each instruction file show what good output looks like?
-            5. **Quality Criteria**: Does each instruction file define quality criteria for its outputs?
-            6. **Sync Complete**: Has `deepwork sync` been run successfully?
-            7. **Commands Available**: Are the slash-commands generated in `.claude/commands/`?
-            8. **Summary Created**: Has `implementation_summary.md` been created?
-            9. **Policies Considered**: Have you thought about whether policies would benefit this job?
-               - If relevant policies were identified, did you explain them and offer to run `/deepwork_policy.define`?
-               - Not every job needs policies - only suggest when genuinely helpful.
-
-            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.
+    quality_criteria:
+      - "**Directory Structure**: Is `.deepwork/jobs/[job_name]/` created correctly?"
+      - "**Complete Instructions**: Are ALL step instruction files complete (not stubs or placeholders)?"
+      - "**Specific & Actionable**: Are instructions tailored to each step's purpose, not generic?"
+      - "**Output Examples**: Does each instruction file show what good output looks like?"
+      - "**Quality Criteria**: Does each instruction file define quality criteria for its outputs?"
+      - "**Ask Structured Questions**: Do step instructions that gather user input explicitly use the phrase \"ask structured questions\"?"
+      - "**Sync Complete**: Has `deepwork sync` been run successfully?"
+      - "**Commands Available**: Are the slash-commands generated in `.claude/commands/`?"
+      - "**Rules Considered**: Has the agent thought about whether rules would benefit this job? If relevant rules were identified, did they explain them and offer to run `/deepwork_rules.define`? Not every job needs rules - only suggest when genuinely helpful."
 
   - id: learn
     name: "Learn from Job Execution"
     description: "Reflect on conversation to improve job instructions and capture learnings"
     instructions_file: steps/learn.md
+    exposed: true
     inputs:
       - name: job_name
         description: "Name of the job that was run (optional - will auto-detect from conversation)"
     outputs:
-      - learning_summary.md
+      - AGENTS.md
     dependencies: []
-    hooks:
-      after_agent:
-        - prompt: |
-            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.
+    quality_criteria:
+      - "**Conversation Analyzed**: Did the agent review the conversation for DeepWork job executions?"
+      - "**Confusion Identified**: Did the agent identify points of confusion, errors, or inefficiencies?"
+      - "**Instructions Improved**: Were job instructions updated to address identified issues?"
+      - "**Instructions Concise**: Are instructions free of redundancy and unnecessary verbosity?"
+      - "**Shared Content Extracted**: Is lengthy/duplicated content extracted into referenced files?"
+      - "**Bespoke Learnings Captured**: Were run-specific learnings added to AGENTS.md?"
+      - "**File References Used**: Do AGENTS.md entries reference other files where appropriate?"
+      - "**Working Folder Correct**: Is AGENTS.md in the correct working folder for the job?"
+      - "**Generalizable Separated**: Are generalizable improvements in instructions, not AGENTS.md?"
+      - "**Sync Complete**: Has `deepwork sync` been run if instructions were modified?"

deepwork/standard_jobs/deepwork_jobs/make_new_job.sh

@@ -0,0 +1,134 @@
+#!/usr/bin/env bash
+#
+# make_new_job.sh - Create directory structure for a new DeepWork job
+#
+# Usage: ./make_new_job.sh <job_name>
+#
+
+set -euo pipefail
+
+# Color output helpers
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m' # No Color
+
+info() {
+    echo -e "${GREEN}[INFO]${NC} $1"
+}
+
+warn() {
+    echo -e "${YELLOW}[WARN]${NC} $1"
+}
+
+error() {
+    echo -e "${RED}[ERROR]${NC} $1"
+    exit 1
+}
+
+# Validate job name format
+validate_job_name() {
+    local name="$1"
+    if [[ ! "$name" =~ ^[a-z][a-z0-9_]*$ ]]; then
+        error "Invalid job name '$name'. Must be lowercase, start with a letter, and contain only letters, numbers, and underscores."
+    fi
+}
+
+# Main script
+main() {
+    if [[ $# -lt 1 ]]; then
+        echo "Usage: $0 <job_name>"
+        echo ""
+        echo "Creates the directory structure for a new DeepWork job."
+        echo ""
+        echo "Arguments:"
+        echo "  job_name    Name of the job (lowercase, underscores allowed)"
+        echo ""
+        echo "Example:"
+        echo "  $0 competitive_research"
+        exit 1
+    fi
+
+    local job_name="$1"
+    validate_job_name "$job_name"
+
+    # Determine the base path - look for .deepwork directory
+    local base_path
+    if [[ -d ".deepwork/jobs" ]]; then
+        base_path=".deepwork/jobs"
+    elif [[ -d "../.deepwork/jobs" ]]; then
+        base_path="../.deepwork/jobs"
+    else
+        # Create from current directory
+        base_path=".deepwork/jobs"
+        mkdir -p "$base_path"
+    fi
+
+    local job_path="${base_path}/${job_name}"
+
+    # Check if job already exists
+    if [[ -d "$job_path" ]]; then
+        error "Job '$job_name' already exists at $job_path"
+    fi
+
+    info "Creating job directory structure for '$job_name'..."
+
+    # Create main job directory and subdirectories
+    mkdir -p "$job_path"
+    mkdir -p "$job_path/steps"
+    mkdir -p "$job_path/hooks"
+    mkdir -p "$job_path/templates"
+
+    # Add .gitkeep files to empty directories
+    touch "$job_path/hooks/.gitkeep"
+    touch "$job_path/templates/.gitkeep"
+
+    # Create AGENTS.md file
+    cat > "$job_path/AGENTS.md" << 'EOF'
+# Job Management
+
+This folder and its subfolders are managed using the `deepwork_jobs` slash commands.
+
+## Recommended Commands
+
+- `/deepwork_jobs.define` - Create or modify the job.yml specification
+- `/deepwork_jobs.implement` - Generate step instruction files from the specification
+- `/deepwork_jobs.learn` - Improve instructions based on execution learnings
+
+## Directory Structure
+
+```
+.
+├── AGENTS.md          # This file - project context and guidance
+├── job.yml            # Job specification (created by /deepwork_jobs.define)
+├── steps/             # Step instruction files (created by /deepwork_jobs.implement)
+│   └── *.md           # One file per step
+├── hooks/             # Custom validation scripts and prompts
+│   └── *.md|*.sh      # Hook files referenced in job.yml
+└── templates/         # Example file formats and templates
+    └── *.md|*.yml     # Templates referenced in step instructions
+```
+
+## Editing Guidelines
+
+1. **Use slash commands** for structural changes (adding steps, modifying job.yml)
+2. **Direct edits** are fine for minor instruction tweaks
+3. **Run `/deepwork_jobs.learn`** after executing job steps to capture improvements
+4. **Run `deepwork sync`** after any changes to regenerate commands
+EOF
+
+    info "Created directory structure:"
+    echo "  $job_path/"
+    echo "  ├── AGENTS.md"
+    echo "  ├── steps/"
+    echo "  ├── hooks/.gitkeep"
+    echo "  └── templates/.gitkeep"
+
+    echo ""
+    info "Next steps:"
+    echo "  1. Run '/deepwork_jobs.define' to create the job.yml specification"
+    echo "  2. Run '/deepwork_jobs.implement' to generate step instructions"
+    echo "  3. Run 'deepwork sync' to create slash commands"
+}
+
+main "$@"

deepwork/standard_jobs/deepwork_jobs/steps/define.md

@@ -6,13 +6,15 @@ Create a `job.yml` specification file that defines the structure of a new DeepWo
 
 ## Task
 
-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.**
+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.**
+
+**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.
 
 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`).
 
 ### Step 1: Understand the Job Purpose
 
-Start by asking questions to understand what the user wants to accomplish:
+Start by asking structured questions to understand what the user wants to accomplish:
 
 1. **What is the overall goal of this workflow?**
    - What complex task are they trying to accomplish?
@@ -31,7 +33,7 @@ Start by asking questions to understand what the user wants to accomplish:
 
 ### Step 2: Define Each Step
 
-For each major phase they mentioned, ask detailed questions:
+For each major phase they mentioned, ask structured questions to gather details:
 
 1. **Step Purpose**
    - What exactly does this step accomplish?
@@ -92,7 +94,7 @@ After gathering information about all steps:
 
 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.
 
-**Ask the user about quality validation:**
+**Ask structured questions about quality validation:**
 - "Are there specific quality criteria that must be met for this step?"
 - "Would you like the agent to validate its work before completing?"
 - "What would make you send the work back for revision?"
@@ -135,68 +137,31 @@ stop_hooks:
 
 **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).
 
-### Step 5: Create the job.yml Specification
-
-Only after you have complete understanding, create the `job.yml` file:
+### Step 5: Create the Job Directory and Specification
 
-**File Location**: `.deepwork/jobs/[job_name]/job.yml`
+Only after you have complete understanding, create the job directory and `job.yml` file:
 
-(Where `[job_name]` is the name of the NEW job you're creating, e.g., `.deepwork/jobs/competitive_research/job.yml`)
+**First, create the directory structure** using the `make_new_job.sh` script:
 
-**Format**:
-```yaml
-name: [job_name]
-version: "1.0.0"
-summary: "[Brief one-line summary of what this job accomplishes]"
-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
-    stop_hooks:
-      - 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
+```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/` - For step instruction files
+- `.deepwork/jobs/[job_name]/hooks/` - For custom validation scripts
+- `.deepwork/jobs/[job_name]/templates/` - For example file formats
+- `.deepwork/jobs/[job_name]/AGENTS.md` - Job management guidance
+
+**Then create the job.yml file** at `.deepwork/jobs/[job_name]/job.yml`
+
+(Where `[job_name]` is the name of the NEW job you're creating, e.g., `competitive_research`)
+
+**Template reference**: See `.deepwork/jobs/deepwork_jobs/templates/job.yml.template` for the standard structure.
+
+**Complete example**: See `.deepwork/jobs/deepwork_jobs/templates/job.yml.example` for a fully worked example.
+
 **Important**:
 - Use lowercase with underscores for job name and step IDs
 - Ensure file inputs reference steps in dependencies
@@ -318,11 +283,11 @@ Run `/deepwork_jobs.implement` to generate the instruction files for each step b
 ## Important Guidelines
 
 1. **Focus on specification only** - Don't create instruction files yet
-2. **Ask clarifying questions** - Never skip the discovery phase
+2. **Ask structured questions** - Never skip the discovery phase; use the AskUserQuestion tool
 3. **Rich context in description** - This helps with future refinement
 4. **Validate understanding** - Summarize and confirm before creating
 5. **Use examples** - Help users understand what good specifications look like
-6. **Understand file organization** - Always ask where outputs should be saved and if subdirectories are needed
+6. **Understand file organization** - Always ask structured questions about where outputs should be saved and if subdirectories are needed
 
 ## Validation Rules
 
@@ -356,6 +321,7 @@ After creating the file:
 
 ## Quality Criteria
 
+- Asked structured questions to fully understand user requirements
 - User fully understands what job they're creating
 - All steps have clear inputs and outputs
 - Dependencies make logical sense