deepwork 0.4.0__py3-none-any.whl → 0.7.0__py3-none-any.whl

deepwork/schemas/job.schema.json

@@ -0,0 +1,347 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://deepwork.dev/schemas/job.schema.json",
+  "title": "DeepWork Job Definition",
+  "description": "Schema for DeepWork job.yml files. Jobs are multi-step workflows executed by AI agents.",
+  "type": "object",
+  "required": ["name", "version", "summary", "steps"],
+  "additionalProperties": false,
+  "properties": {
+    "name": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9_]*$",
+      "description": "Job name (lowercase letters, numbers, underscores, must start with letter). Example: 'competitive_research'"
+    },
+    "version": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+$",
+      "description": "Semantic version (e.g., '1.0.0')"
+    },
+    "summary": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 200,
+      "description": "Brief one-line summary of what this job accomplishes. Used in skill descriptions."
+    },
+    "description": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Detailed multi-line description of the job's purpose, process, and goals"
+    },
+    "workflows": {
+      "type": "array",
+      "description": "Named workflows that group steps into multi-step sequences. Workflows define execution order.",
+      "items": {
+        "$ref": "#/$defs/workflow"
+      }
+    },
+    "changelog": {
+      "type": "array",
+      "description": "Version history documenting changes to the job definition",
+      "items": {
+        "$ref": "#/$defs/changelogEntry"
+      }
+    },
+    "steps": {
+      "type": "array",
+      "minItems": 1,
+      "description": "List of steps in the job. Each step becomes a skill/command.",
+      "items": {
+        "$ref": "#/$defs/step"
+      }
+    }
+  },
+  "$defs": {
+    "stepId": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9_]*$",
+      "description": "Step identifier (lowercase letters, numbers, underscores, must start with letter)"
+    },
+    "workflow": {
+      "type": "object",
+      "required": ["name", "summary", "steps"],
+      "additionalProperties": false,
+      "description": "A named workflow grouping steps into a sequence",
+      "properties": {
+        "name": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9_]*$",
+          "description": "Workflow name (lowercase letters, numbers, underscores)"
+        },
+        "summary": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 200,
+          "description": "Brief one-line summary of what this workflow accomplishes"
+        },
+        "steps": {
+          "type": "array",
+          "minItems": 1,
+          "description": "Ordered list of step entries. Each entry is either a step ID (string) or an array of step IDs for concurrent execution.",
+          "items": {
+            "$ref": "#/$defs/workflowStepEntry"
+          }
+        }
+      }
+    },
+    "workflowStepEntry": {
+      "oneOf": [
+        {
+          "$ref": "#/$defs/stepId"
+        },
+        {
+          "type": "array",
+          "minItems": 1,
+          "description": "Array of step IDs that can be executed concurrently",
+          "items": {
+            "$ref": "#/$defs/stepId"
+          }
+        }
+      ]
+    },
+    "changelogEntry": {
+      "type": "object",
+      "required": ["version", "changes"],
+      "additionalProperties": false,
+      "properties": {
+        "version": {
+          "type": "string",
+          "pattern": "^\\d+\\.\\d+\\.\\d+$",
+          "description": "Version number for this change"
+        },
+        "changes": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Description of changes made in this version"
+        }
+      }
+    },
+    "step": {
+      "type": "object",
+      "required": ["id", "name", "description", "instructions_file", "outputs"],
+      "additionalProperties": false,
+      "description": "A single step in a job, representing one unit of work",
+      "properties": {
+        "id": {
+          "$ref": "#/$defs/stepId",
+          "description": "Unique step identifier within this job"
+        },
+        "name": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Human-readable display name for the step"
+        },
+        "description": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Description of what this step does. Used in skill descriptions."
+        },
+        "instructions_file": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Path to instructions markdown file (relative to job directory). Example: 'steps/research.md'"
+        },
+        "inputs": {
+          "type": "array",
+          "description": "List of inputs required by this step (user parameters or files from previous steps)",
+          "items": {
+            "$ref": "#/$defs/stepInput"
+          }
+        },
+        "outputs": {
+          "type": "array",
+          "minItems": 1,
+          "description": "List of output files/directories produced by this step",
+          "items": {
+            "$ref": "#/$defs/stepOutput"
+          }
+        },
+        "dependencies": {
+          "type": "array",
+          "description": "List of step IDs this step depends on. Dependencies must complete before this step runs.",
+          "items": {
+            "type": "string"
+          },
+          "default": []
+        },
+        "hooks": {
+          "$ref": "#/$defs/hooks",
+          "description": "Lifecycle hooks for validation and actions at different points in step execution"
+        },
+        "stop_hooks": {
+          "type": "array",
+          "description": "DEPRECATED: Use hooks.after_agent instead. Legacy stop hooks for quality validation loops.",
+          "items": {
+            "$ref": "#/$defs/hookAction"
+          }
+        },
+        "exposed": {
+          "type": "boolean",
+          "description": "If true, step is user-invocable in menus/commands. If false, step is hidden (only reachable via workflows or dependencies). Default: false",
+          "default": false
+        },
+        "hidden": {
+          "type": "boolean",
+          "description": "If true, step is hidden from menus. Alias for exposed: false. Default: false",
+          "default": false
+        },
+        "quality_criteria": {
+          "type": "array",
+          "description": "Declarative quality criteria for evaluating step outputs. Rendered with standard evaluation framing.",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "agent": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Agent type for this step (e.g., 'general-purpose'). When set, the skill uses context forking and delegates to the specified agent type."
+        }
+      }
+    },
+    "stepInput": {
+      "oneOf": [
+        {
+          "$ref": "#/$defs/userParameterInput"
+        },
+        {
+          "$ref": "#/$defs/fileInput"
+        }
+      ]
+    },
+    "userParameterInput": {
+      "type": "object",
+      "required": ["name", "description"],
+      "additionalProperties": false,
+      "description": "A user-provided parameter input that will be requested at runtime",
+      "properties": {
+        "name": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Parameter name (used as variable name)"
+        },
+        "description": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Description shown to user when requesting this input"
+        }
+      }
+    },
+    "fileInput": {
+      "type": "object",
+      "required": ["file", "from_step"],
+      "additionalProperties": false,
+      "description": "A file input from a previous step's output",
+      "properties": {
+        "file": {
+          "type": "string",
+          "minLength": 1,
+          "description": "File name to consume from the source step's outputs"
+        },
+        "from_step": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Step ID that produces this file. Must be in the dependencies list."
+        }
+      }
+    },
+    "stepOutput": {
+      "oneOf": [
+        {
+          "type": "string",
+          "minLength": 1,
+          "description": "Simple output file path (backward compatible format)"
+        },
+        {
+          "$ref": "#/$defs/outputWithDocSpec"
+        }
+      ]
+    },
+    "outputWithDocSpec": {
+      "type": "object",
+      "required": ["file"],
+      "additionalProperties": false,
+      "description": "Output file with optional document specification reference",
+      "properties": {
+        "file": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Output file path"
+        },
+        "doc_spec": {
+          "type": "string",
+          "pattern": "^\\.deepwork/doc_specs/[a-z][a-z0-9_-]*\\.md$",
+          "description": "Path to doc spec file defining the expected document structure. Example: '.deepwork/doc_specs/report.md'"
+        }
+      }
+    },
+    "hooks": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Lifecycle hooks triggered at different points in step execution",
+      "properties": {
+        "after_agent": {
+          "type": "array",
+          "description": "Hooks triggered after the agent finishes. Used for quality validation loops.",
+          "items": {
+            "$ref": "#/$defs/hookAction"
+          }
+        },
+        "before_tool": {
+          "type": "array",
+          "description": "Hooks triggered before a tool is used. Used for pre-action checks.",
+          "items": {
+            "$ref": "#/$defs/hookAction"
+          }
+        },
+        "before_prompt": {
+          "type": "array",
+          "description": "Hooks triggered when user submits a prompt. Used for input validation.",
+          "items": {
+            "$ref": "#/$defs/hookAction"
+          }
+        }
+      }
+    },
+    "hookAction": {
+      "type": "object",
+      "description": "A hook action - exactly one of: prompt (inline text), prompt_file (external file), or script (shell script)",
+      "oneOf": [
+        {
+          "required": ["prompt"],
+          "additionalProperties": false,
+          "properties": {
+            "prompt": {
+              "type": "string",
+              "minLength": 1,
+              "description": "Inline prompt text for validation/action"
+            }
+          }
+        },
+        {
+          "required": ["prompt_file"],
+          "additionalProperties": false,
+          "properties": {
+            "prompt_file": {
+              "type": "string",
+              "minLength": 1,
+              "description": "Path to prompt file (relative to job directory)"
+            }
+          }
+        },
+        {
+          "required": ["script"],
+          "additionalProperties": false,
+          "properties": {
+            "script": {
+              "type": "string",
+              "minLength": 1,
+              "description": "Path to shell script (relative to job directory)"
+            }
+          }
+        }
+      ]
+    }
+  }
+}

deepwork/schemas/job_schema.py

@@ -1,247 +1,35 @@
-"""JSON Schema definition for job definitions."""
+"""JSON Schema loader for job definitions.
 
+This module loads the job.schema.json file and provides it as a Python dict
+for use with jsonschema validation.
+"""
+
+import json
+from pathlib import Path
 from typing import Any
 
 # Supported lifecycle hook events (generic names, mapped to platform-specific by adapters)
 # These values must match SkillLifecycleHook enum in adapters.py
 LIFECYCLE_HOOK_EVENTS = ["after_agent", "before_tool", "before_prompt"]
 
-# Schema definition for a single hook action (prompt, prompt_file, or script)
-HOOK_ACTION_SCHEMA: dict[str, Any] = {
-    "type": "object",
-    "oneOf": [
-        {
-            "required": ["prompt"],
-            "properties": {
-                "prompt": {
-                    "type": "string",
-                    "minLength": 1,
-                    "description": "Inline prompt for validation/action",
-                },
-            },
-            "additionalProperties": False,
-        },
-        {
-            "required": ["prompt_file"],
-            "properties": {
-                "prompt_file": {
-                    "type": "string",
-                    "minLength": 1,
-                    "description": "Path to prompt file (relative to job directory)",
-                },
-            },
-            "additionalProperties": False,
-        },
-        {
-            "required": ["script"],
-            "properties": {
-                "script": {
-                    "type": "string",
-                    "minLength": 1,
-                    "description": "Path to shell script (relative to job directory)",
-                },
-            },
-            "additionalProperties": False,
-        },
-    ],
-}
+# Path to the JSON schema file
+_SCHEMA_FILE = Path(__file__).parent / "job.schema.json"
+
+
+def _load_schema() -> dict[str, Any]:
+    """Load the JSON schema from file."""
+    with open(_SCHEMA_FILE) as f:
+        return json.load(f)
+
+
+# Load the schema at module import time
+JOB_SCHEMA: dict[str, Any] = _load_schema()
+
+
+def get_schema_path() -> Path:
+    """Get the path to the JSON schema file.
 
-# JSON Schema for job.yml files
-JOB_SCHEMA: dict[str, Any] = {
-    "$schema": "http://json-schema.org/draft-07/schema#",
-    "type": "object",
-    "required": ["name", "version", "summary", "steps"],
-    "properties": {
-        "name": {
-            "type": "string",
-            "pattern": "^[a-z][a-z0-9_]*$",
-            "description": "Job name (lowercase letters, numbers, underscores, must start with letter)",
-        },
-        "version": {
-            "type": "string",
-            "pattern": r"^\d+\.\d+\.\d+$",
-            "description": "Semantic version (e.g., 1.0.0)",
-        },
-        "summary": {
-            "type": "string",
-            "minLength": 1,
-            "maxLength": 200,
-            "description": "Brief one-line summary of what this job accomplishes",
-        },
-        "description": {
-            "type": "string",
-            "minLength": 1,
-            "description": "Detailed multi-line description of the job's purpose, process, and goals",
-        },
-        "changelog": {
-            "type": "array",
-            "description": "Version history and changes to the job",
-            "items": {
-                "type": "object",
-                "required": ["version", "changes"],
-                "properties": {
-                    "version": {
-                        "type": "string",
-                        "pattern": r"^\d+\.\d+\.\d+$",
-                        "description": "Version number for this change",
-                    },
-                    "changes": {
-                        "type": "string",
-                        "minLength": 1,
-                        "description": "Description of changes made in this version",
-                    },
-                },
-                "additionalProperties": False,
-            },
-        },
-        "steps": {
-            "type": "array",
-            "minItems": 1,
-            "description": "List of steps in the job",
-            "items": {
-                "type": "object",
-                "required": ["id", "name", "description", "instructions_file", "outputs"],
-                "properties": {
-                    "id": {
-                        "type": "string",
-                        "pattern": "^[a-z][a-z0-9_]*$",
-                        "description": "Step ID (unique within job)",
-                    },
-                    "name": {
-                        "type": "string",
-                        "minLength": 1,
-                        "description": "Human-readable step name",
-                    },
-                    "description": {
-                        "type": "string",
-                        "minLength": 1,
-                        "description": "Step description",
-                    },
-                    "instructions_file": {
-                        "type": "string",
-                        "minLength": 1,
-                        "description": "Path to instructions file (relative to job directory)",
-                    },
-                    "inputs": {
-                        "type": "array",
-                        "description": "List of inputs (user parameters or files from previous steps)",
-                        "items": {
-                            "type": "object",
-                            "oneOf": [
-                                {
-                                    "required": ["name", "description"],
-                                    "properties": {
-                                        "name": {
-                                            "type": "string",
-                                            "description": "Input parameter name",
-                                        },
-                                        "description": {
-                                            "type": "string",
-                                            "description": "Input parameter description",
-                                        },
-                                    },
-                                    "additionalProperties": False,
-                                },
-                                {
-                                    "required": ["file", "from_step"],
-                                    "properties": {
-                                        "file": {
-                                            "type": "string",
-                                            "description": "File name from previous step",
-                                        },
-                                        "from_step": {
-                                            "type": "string",
-                                            "description": "Step ID that produces this file",
-                                        },
-                                    },
-                                    "additionalProperties": False,
-                                },
-                            ],
-                        },
-                    },
-                    "outputs": {
-                        "type": "array",
-                        "description": "List of output files/directories, optionally with document type references",
-                        "items": {
-                            "oneOf": [
-                                {
-                                    "type": "string",
-                                    "minLength": 1,
-                                    "description": "Simple output file path (backward compatible)",
-                                },
-                                {
-                                    "type": "object",
-                                    "required": ["file"],
-                                    "properties": {
-                                        "file": {
-                                            "type": "string",
-                                            "minLength": 1,
-                                            "description": "Output file path",
-                                        },
-                                        "doc_spec": {
-                                            "type": "string",
-                                            "pattern": r"^\.deepwork/doc_specs/[a-z][a-z0-9_-]*\.md$",
-                                            "description": "Path to doc spec file",
-                                        },
-                                    },
-                                    "additionalProperties": False,
-                                },
-                            ],
-                        },
-                    },
-                    "dependencies": {
-                        "type": "array",
-                        "description": "List of step IDs this step depends on",
-                        "items": {
-                            "type": "string",
-                        },
-                        "default": [],
-                    },
-                    "hooks": {
-                        "type": "object",
-                        "description": "Lifecycle hooks for this step, keyed by event type",
-                        "properties": {
-                            "after_agent": {
-                                "type": "array",
-                                "description": "Hooks triggered after the agent finishes (quality validation)",
-                                "items": HOOK_ACTION_SCHEMA,
-                            },
-                            "before_tool": {
-                                "type": "array",
-                                "description": "Hooks triggered before a tool is used",
-                                "items": HOOK_ACTION_SCHEMA,
-                            },
-                            "before_prompt": {
-                                "type": "array",
-                                "description": "Hooks triggered when user submits a prompt",
-                                "items": HOOK_ACTION_SCHEMA,
-                            },
-                        },
-                        "additionalProperties": False,
-                    },
-                    # DEPRECATED: Use hooks.after_agent instead
-                    "stop_hooks": {
-                        "type": "array",
-                        "description": "DEPRECATED: Use hooks.after_agent instead. Stop hooks for quality validation loops.",
-                        "items": HOOK_ACTION_SCHEMA,
-                    },
-                    "exposed": {
-                        "type": "boolean",
-                        "description": "If true, skill is user-invocable in menus. Default: false (hidden from menus).",
-                        "default": False,
-                    },
-                    "quality_criteria": {
-                        "type": "array",
-                        "description": "Declarative quality criteria. Rendered with standard evaluation framing.",
-                        "items": {
-                            "type": "string",
-                            "minLength": 1,
-                        },
-                    },
-                },
-                "additionalProperties": False,
-            },
-        },
-    },
-    "additionalProperties": False,
-}
+    Returns:
+        Path to job.schema.json
+    """
+    return _SCHEMA_FILE

deepwork/standard_jobs/deepwork_jobs/doc_specs/job_spec.md

@@ -23,7 +23,7 @@ quality_criteria:
   - name: Input Consistency
     description: "File inputs with `from_step` must reference a step that is in the dependencies array"
   - name: Output Paths
-    description: "Outputs must be valid filenames or paths within the main repo (not in dot-directories). Use specific, descriptive paths that lend themselves to glob patterns, e.g., `competitive_research/competitors_list.md` or `competitive_research/[competitor_name]/research.md`. Avoid generic names like `output.md`."
+    description: "Outputs must be valid filenames or paths within the main repo directory structure, never in dot-directories like `.deepwork/`. Use specific, descriptive paths that lend themselves to glob patterns (e.g., `competitive_research/acme_corp/swot.md` or `operations/reports/2026-01/spending_analysis.md`). Parameterized paths like `[competitor_name]/` are encouraged for per-entity outputs. Avoid generic names (`output.md`, `analysis.md`) and transient-sounding paths (`temp/`, `draft.md`). Supporting materials for a final output should go in a peer `_dataroom` folder (e.g., `spending_analysis_dataroom/`)."
   - name: Concise Instructions
     description: "The content of the file, particularly the description, must not have excessively redundant information. It should be concise and to the point given that extra tokens will confuse the AI."
 ---
@@ -82,14 +82,19 @@ steps:
 
 ## Optional Fields
 
-### Exposed Steps
+### Agent Delegation
+
+When a step should be executed by a specific agent type, use the `agent` field. This automatically sets `context: fork` in the generated skill.
 
 ```yaml
 steps:
-  - id: learn
-    exposed: true                 # Makes step available without running dependencies
+  - id: research_step
+    agent: general-purpose        # Delegates to the general-purpose agent
 ```
 
+Available agent types:
+- `general-purpose` - Standard agent for multi-step tasks
+
 ### Quality Hooks
 
 ```yaml
@@ -109,17 +114,6 @@ steps:
         - script: hooks/run_tests.sh
 ```
 
-### Stop Hooks (Legacy)
-
-```yaml
-steps:
-  - id: step_id
-    stop_hooks:
-      - prompt: "Validation prompt..."
-      - prompt_file: hooks/check.md
-      - script: hooks/validate.sh
-```
-
 ## Validation Rules
 
 1. **No circular dependencies**: Step A cannot depend on Step B if Step B depends on Step A