deepwork 0.1.0__py3-none-any.whl

deepwork/standard_jobs/deepwork_policy/steps/define.md

@@ -0,0 +1,174 @@
+# Define Policy
+
+## Objective
+
+Create or update policy entries in the `.deepwork.policy.yml` file to enforce team guidelines, documentation requirements, or other constraints when specific files change.
+
+## Task
+
+Guide the user through defining a new policy by asking clarifying questions. **Do not create the policy without first understanding what they want to enforce.**
+
+### Step 1: Understand the Policy Purpose
+
+Start by asking questions to understand what the user wants to enforce:
+
+1. **What guideline or constraint should this policy enforce?**
+   - What situation triggers the need for action?
+   - What files or directories, when changed, should trigger this policy?
+   - Examples: "When config files change", "When API code changes", "When database schema changes"
+
+2. **What action should be taken?**
+   - What should the agent do when the policy triggers?
+   - Update documentation? Perform a security review? Update tests?
+   - Is there a specific file or process that needs attention?
+
+3. **Are there any "safety" conditions?**
+   - Are there files that, if also changed, mean the policy doesn't need to fire?
+   - For example: If config changes AND install_guide.md changes, assume docs are already updated
+   - This prevents redundant prompts when the user has already done the right thing
+
+### Step 2: Define the Trigger Patterns
+
+Help the user define glob patterns for files that should trigger the policy:
+
+**Common patterns:**
+- `src/**/*.py` - All Python files in src directory (recursive)
+- `app/config/**/*` - All files in app/config directory
+- `*.md` - All markdown files in root
+- `src/api/**/*` - All files in the API directory
+- `migrations/**/*.sql` - All SQL migrations
+
+**Pattern syntax:**
+- `*` - Matches any characters within a single path segment
+- `**` - Matches any characters across multiple path segments (recursive)
+- `?` - Matches a single character
+
+### Step 3: Define Safety Patterns (Optional)
+
+If there are files that, when also changed, mean the policy shouldn't fire:
+
+**Examples:**
+- Policy: "Update install guide when config changes"
+  - Trigger: `app/config/**/*`
+  - Safety: `docs/install_guide.md` (if already updated, don't prompt)
+
+- Policy: "Security review for auth changes"
+  - Trigger: `src/auth/**/*`
+  - Safety: `SECURITY.md`, `docs/security_review.md`
+
+### Step 4: Write the Instructions
+
+Create clear, actionable instructions for what the agent should do when the policy fires.
+
+**Good instructions include:**
+- What to check or review
+- What files might need updating
+- Specific actions to take
+- Quality criteria for completion
+
+**Example:**
+```
+Configuration files have changed. Please:
+1. Review docs/install_guide.md for accuracy
+2. Update any installation steps that reference changed config
+3. Verify environment variable documentation is current
+4. Test that installation instructions still work
+```
+
+### Step 5: Create the Policy Entry
+
+Create or update `.deepwork.policy.yml` in the project root.
+
+**File Location**: `.deepwork.policy.yml` (root of project)
+
+**Format**:
+```yaml
+- name: "[Friendly name for the policy]"
+  trigger: "[glob pattern]"  # or array: ["pattern1", "pattern2"]
+  safety: "[glob pattern]"   # optional, or array
+  instructions: |
+    [Multi-line instructions for the agent...]
+```
+
+**Alternative with instructions_file**:
+```yaml
+- name: "[Friendly name for the policy]"
+  trigger: "[glob pattern]"
+  safety: "[glob pattern]"
+  instructions_file: "path/to/instructions.md"
+```
+
+### Step 6: Verify the Policy
+
+After creating the policy:
+
+1. **Check the YAML syntax** - Ensure valid YAML formatting
+2. **Test trigger patterns** - Verify patterns match intended files
+3. **Review instructions** - Ensure they're clear and actionable
+4. **Check for conflicts** - Ensure the policy doesn't conflict with existing ones
+
+## Example Policies
+
+### Update Documentation on Config Changes
+```yaml
+- name: "Update install guide on config changes"
+  trigger: "app/config/**/*"
+  safety: "docs/install_guide.md"
+  instructions: |
+    Configuration files have been modified. Please review docs/install_guide.md
+    and update it if any installation instructions need to change based on the
+    new configuration.
+```
+
+### Security Review for Auth Code
+```yaml
+- name: "Security review for authentication changes"
+  trigger:
+    - "src/auth/**/*"
+    - "src/security/**/*"
+  safety:
+    - "SECURITY.md"
+    - "docs/security_audit.md"
+  instructions: |
+    Authentication or security code has been changed. Please:
+    1. Review for hardcoded credentials or secrets
+    2. Check input validation on user inputs
+    3. Verify access control logic is correct
+    4. Update security documentation if needed
+```
+
+### API Documentation Sync
+```yaml
+- name: "API documentation update"
+  trigger: "src/api/**/*.py"
+  safety: "docs/api/**/*.md"
+  instructions: |
+    API code has changed. Please verify that API documentation in docs/api/
+    is up to date with the code changes. Pay special attention to:
+    - New or changed endpoints
+    - Modified request/response schemas
+    - Updated authentication requirements
+```
+
+## Output Format
+
+### .deepwork.policy.yml
+Create or update this file at the project root with the new policy entry.
+
+## Quality Criteria
+
+- Policy name is clear and descriptive
+- Trigger patterns accurately match the intended files
+- Safety patterns prevent unnecessary triggering
+- Instructions are actionable and specific
+- YAML is valid and properly formatted
+
+## Context
+
+Policies are evaluated automatically when you finish working on a task. The system:
+1. Tracks which files you changed during the session
+2. Checks if any changes match policy trigger patterns
+3. Skips policies where safety patterns also matched
+4. Prompts you with instructions for any triggered policies
+
+You can mark a policy as addressed by including `<promise>✓ Policy Name</promise>` in your response (replace Policy Name with the actual policy name). This tells the system you've already handled that policy's requirements.

deepwork/templates/__init__.py

@@ -0,0 +1 @@
+"""Skill templates for different AI platforms."""

deepwork/templates/claude/command-job-step.md.jinja

@@ -0,0 +1,210 @@
+---
+description: {{ step_description }}
+{% if hooks %}
+hooks:
+{% for event_name, event_hooks in hooks.items() %}
+  {{ event_name }}:
+    - hooks:
+{% for hook in event_hooks %}
+{% if hook.type == "script" %}
+        - type: command
+          command: ".deepwork/jobs/{{ job_name }}/{{ hook.path }}"
+{% else %}
+        - type: prompt
+          prompt: |
+{% if event_name == "Stop" %}
+            You must evaluate whether Claude has met all the below quality criteria for the request.
+
+            ## Quality Criteria
+
+            {{ hook.content | indent(12) }}
+
+            ## 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]"}
+{% else %}
+            {{ hook.content | indent(12) }}
+{% endif %}
+{% endif %}
+{% endfor %}
+{% endfor %}
+{% endif %}
+---
+
+# {{ job_name }}.{{ step_id }}
+
+{% if is_standalone %}
+**Standalone command** in the **{{ job_name }}** job - can be run anytime
+{% else %}
+**Step {{ step_number }} of {{ total_steps }}** in the **{{ job_name }}** workflow
+{% endif %}
+
+**Summary**: {{ job_summary }}
+
+{% if job_description %}
+## Job Overview
+
+{{ job_description }}
+{% endif %}
+
+{% if dependencies %}
+## Prerequisites
+
+This step requires completion of the following step(s):
+{% for dep in dependencies %}
+- `/{{ job_name }}.{{ dep }}`
+{% endfor %}
+
+Please ensure these steps have been completed before proceeding.
+{% endif %}
+
+## Instructions
+
+{{ instructions_content }}
+
+{% if user_inputs or file_inputs %}
+## Inputs
+
+{% if user_inputs %}
+### User Parameters
+
+Please gather the following information from the user:
+{% for input in user_inputs %}
+- **{{ input.name }}**: {{ input.description }}
+{% endfor %}
+{% endif %}
+
+{% if file_inputs %}
+### Required Files
+
+This step requires the following files from previous steps:
+{% for input in file_inputs %}
+- `{{ input.file }}` (from step `{{ input.from_step }}`)
+{% endfor %}
+
+Make sure to read and use these files as context for this step.
+{% endif %}
+{% endif %}
+
+## 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/{{ job_name }}-[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/{{ job_name }}-[instance]-$(date +%Y%m%d)
+   ```
+   Replace `[instance]` with a descriptive identifier (e.g., `acme`, `q1-launch`, etc.)
+
+## Output Requirements
+
+{% if outputs %}
+Create the following output(s):
+{% for output in outputs %}
+- `{{ output }}`{% if output.endswith('/') %} (directory){% endif %}
+{% endfor %}
+
+Ensure all outputs are:
+- Well-formatted and complete
+- Ready for review or use by subsequent steps
+{% else %}
+No specific files are output by this command.
+{% endif %}
+
+{% if stop_hooks %}
+## 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.
+
+{% for hook in stop_hooks %}
+{% if hook.type == "script" %}
+**Validation Script**: `.deepwork/jobs/{{ job_name }}/{{ hook.path }}`
+
+The validation script will be executed automatically when you attempt to complete this step.
+{% else %}
+### Quality Criteria{% if stop_hooks | length > 1 %} ({{ loop.index }}){% endif %}
+
+{{ hook.content }}
+{% endif %}
+{% endfor %}
+
+### 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.
+
+{% endif %}
+## Completion
+
+After completing this step:
+
+1. **Verify outputs**: Confirm all required files have been created
+
+2. **Inform the user**:
+{% if is_standalone %}
+   - The {{ step_id }} command is complete
+{% if outputs %}
+   - Outputs created: {{ outputs | join(', ') }}
+{% endif %}
+   - This command can be run again anytime to make further changes
+{% else %}
+   - Step {{ step_number }} of {{ total_steps }} is complete
+{% if outputs %}
+   - Outputs created: {{ outputs | join(', ') }}
+{% endif %}
+   {% if next_step %}
+   - Ready to proceed to next step: `/{{ job_name }}.{{ next_step }}`
+   {% else %}
+   - This is the final step - the job is complete!
+   {% endif %}
+{% endif %}
+
+{% if is_standalone %}
+## 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
+{% elif next_step %}
+## Next Step
+
+To continue the workflow, run:
+```
+/{{ job_name }}.{{ next_step }}
+```
+{% else %}
+## Workflow Complete
+
+This is the final step in the {{ job_name }} workflow. All outputs should now be complete and ready for review.
+
+Consider:
+- Reviewing all work products
+- Creating a pull request to merge the work branch
+- Documenting any insights or learnings
+{% endif %}
+
+---
+
+## Context Files
+
+- Job definition: `.deepwork/jobs/{{ job_name }}/job.yml`
+- Step instructions: `.deepwork/jobs/{{ job_name }}/{{ instructions_file }}`

deepwork/templates/gemini/command-job-step.toml.jinja

@@ -0,0 +1,169 @@
+# {{ job_name }}:{{ step_id }}
+#
+# {{ step_description }}
+#
+# Generated by DeepWork - do not edit manually
+
+description = "{{ step_description | replace('"', '\\"') }}"
+
+prompt = """
+# {{ job_name }}:{{ step_id }}
+
+{% if is_standalone %}
+**Standalone command** in the **{{ job_name }}** job - can be run anytime
+{% else %}
+**Step {{ step_number }} of {{ total_steps }}** in the **{{ job_name }}** workflow
+{% endif %}
+
+**Summary**: {{ job_summary }}
+
+{% if job_description %}
+## Job Overview
+
+{{ job_description }}
+{% endif %}
+
+{% if dependencies %}
+## Prerequisites
+
+This step requires completion of the following step(s):
+{% for dep in dependencies %}
+- `/{{ job_name }}:{{ dep }}`
+{% endfor %}
+
+Please ensure these steps have been completed before proceeding.
+{% endif %}
+
+## Instructions
+
+{{ instructions_content }}
+
+{% if user_inputs or file_inputs %}
+## Inputs
+
+{% if user_inputs %}
+### User Parameters
+
+Please gather the following information from the user:
+{% for input in user_inputs %}
+- **{{ input.name }}**: {{ input.description }}
+{% endfor %}
+{% endif %}
+
+{% if file_inputs %}
+### Required Files
+
+This step requires the following files from previous steps:
+{% for input in file_inputs %}
+- `{{ input.file }}` (from step `{{ input.from_step }}`)
+{% endfor %}
+
+Make sure to read and use these files as context for this step.
+{% endif %}
+{% endif %}
+
+## 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/{{ job_name }}-[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/{{ job_name }}-[instance]-$(date +%Y%m%d)
+   ```
+   Replace `[instance]` with a descriptive identifier (e.g., `acme`, `q1-launch`, etc.)
+
+## Output Requirements
+
+{% if outputs %}
+Create the following output(s):
+{% for output in outputs %}
+- `{{ output }}`{% if output.endswith('/') %} (directory){% endif %}
+
+{% endfor %}
+
+Ensure all outputs are:
+- Well-formatted and complete
+- Ready for review or use by subsequent steps
+{% else %}
+No specific files are output by this command.
+{% endif %}
+
+{% if stop_hooks %}
+## Quality Validation
+
+This step has quality criteria that should be verified before completion.
+
+{% for hook in stop_hooks %}
+{% if hook.type != "script" %}
+### Quality Criteria{% if stop_hooks | length > 1 %} ({{ loop.index }}){% endif %}
+
+{{ hook.content }}
+{% endif %}
+{% endfor %}
+
+**Note**: Gemini CLI does not support automated validation hooks. Please manually verify the criteria above before proceeding.
+
+{% endif %}
+## Completion
+
+After completing this step:
+
+1. **Verify outputs**: Confirm all required files have been created
+
+2. **Inform the user**:
+{% if is_standalone %}
+   - The {{ step_id }} command is complete
+{% if outputs %}
+   - Outputs created: {{ outputs | join(', ') }}
+{% endif %}
+   - This command can be run again anytime to make further changes
+{% else %}
+   - Step {{ step_number }} of {{ total_steps }} is complete
+{% if outputs %}
+   - Outputs created: {{ outputs | join(', ') }}
+{% endif %}
+   {% if next_step %}
+   - Ready to proceed to next step: `/{{ job_name }}:{{ next_step }}`
+   {% else %}
+   - This is the final step - the job is complete!
+   {% endif %}
+{% endif %}
+
+{% if is_standalone %}
+## 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
+{% elif next_step %}
+## Next Step
+
+To continue the workflow, run:
+```
+/{{ job_name }}:{{ next_step }}
+```
+{% else %}
+## Workflow Complete
+
+This is the final step in the {{ job_name }} workflow. All outputs should now be complete and ready for review.
+
+Consider:
+- Reviewing all work products
+- Creating a pull request to merge the work branch
+- Documenting any insights or learnings
+{% endif %}
+
+---
+
+## Context Files
+
+- Job definition: `.deepwork/jobs/{{ job_name }}/job.yml`
+- Step instructions: `.deepwork/jobs/{{ job_name }}/{{ instructions_file }}`
+"""

deepwork/utils/__init__.py

@@ -0,0 +1 @@
+"""Utility functions for DeepWork."""

deepwork/utils/fs.py

@@ -0,0 +1,128 @@
+"""Filesystem utilities for safe file operations."""
+
+import shutil
+from pathlib import Path
+
+
+def ensure_dir(path: Path | str) -> Path:
+    """
+    Create directory if it doesn't exist.
+
+    Args:
+        path: Directory path to create
+
+    Returns:
+        Path object for the created/existing directory
+    """
+    path_obj = Path(path)
+    path_obj.mkdir(parents=True, exist_ok=True)
+    return path_obj
+
+
+def safe_write(path: Path | str, content: str) -> None:
+    """
+    Write content to file, creating parent directories if needed.
+
+    Args:
+        path: File path to write to
+        content: Content to write
+
+    Raises:
+        OSError: If write operation fails
+    """
+    path_obj = Path(path)
+    ensure_dir(path_obj.parent)
+    path_obj.write_text(content, encoding="utf-8")
+
+
+def safe_read(path: Path | str) -> str | None:
+    """
+    Read content from file, return None if file doesn't exist.
+
+    Args:
+        path: File path to read from
+
+    Returns:
+        File content as string, or None if file doesn't exist
+
+    Raises:
+        OSError: If read operation fails for reasons other than file not existing
+    """
+    path_obj = Path(path)
+    if not path_obj.exists():
+        return None
+    return path_obj.read_text(encoding="utf-8")
+
+
+def copy_dir(src: Path | str, dst: Path | str, ignore_patterns: list[str] | None = None) -> None:
+    """
+    Recursively copy directory, optionally ignoring patterns.
+
+    Args:
+        src: Source directory path
+        dst: Destination directory path
+        ignore_patterns: Optional list of glob patterns to ignore
+
+    Raises:
+        FileNotFoundError: If source directory doesn't exist
+        OSError: If copy operation fails
+    """
+    src_path = Path(src)
+    dst_path = Path(dst)
+
+    if not src_path.exists():
+        raise FileNotFoundError(f"Source directory does not exist: {src_path}")
+
+    if not src_path.is_dir():
+        raise NotADirectoryError(f"Source is not a directory: {src_path}")
+
+    # Create ignore function if patterns provided
+    ignore_func = None
+    if ignore_patterns:
+
+        def _ignore(directory: str, contents: list[str]) -> set[str]:
+            ignored = set()
+            dir_path = Path(directory)
+            for item in contents:
+                item_path = dir_path / item
+                for pattern in ignore_patterns:
+                    if item_path.match(pattern):
+                        ignored.add(item)
+                        break
+            return ignored
+
+        ignore_func = _ignore
+
+    shutil.copytree(src_path, dst_path, ignore=ignore_func, dirs_exist_ok=True)
+
+
+def find_files(directory: Path | str, pattern: str) -> list[Path]:
+    """
+    Find files matching glob pattern in directory.
+
+    Args:
+        directory: Directory to search in
+        pattern: Glob pattern to match (e.g., "*.py", "**/*.md")
+
+    Returns:
+        List of matching file paths (sorted)
+
+    Raises:
+        FileNotFoundError: If directory doesn't exist
+    """
+    dir_path = Path(directory)
+
+    if not dir_path.exists():
+        raise FileNotFoundError(f"Directory does not exist: {dir_path}")
+
+    if not dir_path.is_dir():
+        raise NotADirectoryError(f"Path is not a directory: {dir_path}")
+
+    # Use rglob for ** patterns, otherwise use glob
+    if "**" in pattern:
+        matches = dir_path.glob(pattern)
+    else:
+        matches = dir_path.glob(pattern)
+
+    # Return only files, not directories, sorted by path
+    return sorted([p for p in matches if p.is_file()])