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

deepwork/standard_jobs/deepwork_jobs/steps/review_job_spec.md

@@ -0,0 +1,208 @@
+# Review Job Specification
+
+## Objective
+
+Review the `job.yml` created in the define step against the doc spec quality criteria using a sub-agent for unbiased evaluation, then iterate on fixes until all criteria pass.
+
+## Why This Step Exists
+
+The define step focuses on understanding user requirements and creating a job specification. This review step ensures the specification meets quality standards before implementation. Using a sub-agent provides an unbiased "fresh eyes" review that catches issues the main agent might miss after being deeply involved in the definition process.
+
+## Task
+
+Use a sub-agent to review the job.yml against all 9 doc spec quality criteria, then fix any failed criteria. Repeat until all criteria pass.
+
+### Step 1: Read the Job Specification
+
+Read the `job.yml` file created in the define step:
+
+```
+.deepwork/jobs/[job_name]/job.yml
+```
+
+Also read the doc spec for reference:
+
+```
+.deepwork/doc_specs/job_spec.md
+```
+
+### Step 2: Spawn Review Sub-Agent
+
+Use the Task tool to spawn a sub-agent that will provide an unbiased review:
+
+```
+Task tool parameters:
+- subagent_type: "general-purpose"
+- model: "haiku"
+- description: "Review job.yml against doc spec"
+- prompt: [see below]
+```
+
+**Sub-agent prompt template:**
+
+```
+Review this job.yml against the following 9 quality criteria from the doc spec.
+
+For each criterion, respond with:
+- PASS or FAIL
+- If FAIL: specific issue and suggested fix
+
+## job.yml Content
+
+[paste the full job.yml content here]
+
+## Quality Criteria
+
+1. **Valid Identifier**: Job name must be lowercase with underscores, no spaces or special characters (e.g., `competitive_research`, `monthly_report`)
+
+2. **Semantic Version**: Version must follow semantic versioning format X.Y.Z (e.g., `1.0.0`, `2.1.3`)
+
+3. **Concise Summary**: Summary must be under 200 characters and clearly describe what the job accomplishes
+
+4. **Rich Description**: Description must be multi-line and explain: the problem solved, the process, expected outcomes, and target users
+
+5. **Changelog Present**: Must include a changelog array with at least the initial version entry
+
+6. **Complete Steps**: Each step must have: id (lowercase_underscores), name, description, instructions_file, outputs (at least one), and dependencies array
+
+7. **Valid Dependencies**: Dependencies must reference existing step IDs with no circular references
+
+8. **Input Consistency**: File inputs with `from_step` must reference a step that is in the dependencies array
+
+9. **Output Paths**: Outputs must be valid filenames or paths (e.g., `report.md` or `reports/analysis.md`)
+
+## Response Format
+
+Respond with a structured evaluation:
+
+### Overall: [X/9 PASS]
+
+### Criterion Results
+
+1. Valid Identifier: [PASS/FAIL]
+   [If FAIL: Issue and fix]
+
+2. Semantic Version: [PASS/FAIL]
+   [If FAIL: Issue and fix]
+
+[... continue for all 9 criteria ...]
+
+### Summary of Required Fixes
+
+[List any fixes needed, or "No fixes required - all criteria pass"]
+```
+
+### Step 3: Review Sub-Agent Findings
+
+Parse the sub-agent's response:
+
+1. **Count passing criteria** - How many of the 9 criteria passed?
+2. **Identify failures** - List specific criteria that failed
+3. **Note suggested fixes** - What changes does the sub-agent recommend?
+
+### Step 4: Fix Failed Criteria
+
+For each failed criterion, edit the job.yml to address the issue:
+
+**Common fixes by criterion:**
+
+| Criterion | Common Issue | Fix |
+|-----------|-------------|-----|
+| Valid Identifier | Spaces or uppercase | Convert to lowercase_underscores |
+| Semantic Version | Missing or invalid format | Set to `"1.0.0"` or fix format |
+| Concise Summary | Too long or vague | Shorten to <200 chars, be specific |
+| Rich Description | Single line or missing context | Add multi-line explanation with problem/process/outcome/users |
+| Changelog Present | Missing changelog | Add `changelog:` with initial version entry |
+| Complete Steps | Missing required fields | Add id, name, description, instructions_file, outputs, dependencies |
+| Valid Dependencies | Non-existent step or circular | Fix step ID reference or reorder dependencies |
+| Input Consistency | from_step not in dependencies | Add the referenced step to dependencies array |
+| Output Paths | Invalid characters or format | Use valid filename/path format |
+
+### Step 5: Re-Run Review (If Needed)
+
+If any criteria failed:
+
+1. **Spawn a new sub-agent** with the updated job.yml content
+2. **Review the new findings**
+3. **Fix any remaining issues**
+4. **Repeat until all 9 criteria pass**
+
+### Step 6: Confirm Completion
+
+When all 9 criteria pass:
+
+1. **Announce success**: "All 9 doc spec quality criteria pass."
+2. **List what was validated**:
+   - Valid Identifier
+   - Semantic Version
+   - Concise Summary
+   - Rich Description
+   - Changelog Present
+   - Complete Steps
+   - Valid Dependencies
+   - Input Consistency
+   - Output Paths
+3. **Include the promise**: `<promise>Quality Criteria Met</promise>`
+4. **Guide to next step**: "Run `/deepwork_jobs.implement` to generate the step instruction files."
+
+## Example Review Cycle
+
+```
+Claude: Let me review the job.yml against the doc spec quality criteria.
+
+[Spawns sub-agent with haiku model]
+
+Sub-agent response:
+### Overall: 7/9 PASS
+
+### Criterion Results
+1. Valid Identifier: PASS
+2. Semantic Version: PASS
+3. Concise Summary: FAIL
+   Issue: Summary is 245 characters, exceeds 200 char limit
+   Fix: Shorten to "Competitive analysis workflow for product positioning"
+4. Rich Description: PASS
+5. Changelog Present: FAIL
+   Issue: No changelog array present
+   Fix: Add changelog with initial version entry
+6. Complete Steps: PASS
+7. Valid Dependencies: PASS
+8. Input Consistency: PASS
+9. Output Paths: PASS
+
+### Summary of Required Fixes
+1. Shorten summary to under 200 characters
+2. Add changelog array with initial version
+
+Claude: I found 2 issues. Let me fix them.
+
+[Edits job.yml to shorten summary and add changelog]
+
+Claude: Let me verify the fixes with another review.
+
+[Spawns new sub-agent]
+
+Sub-agent response:
+### Overall: 9/9 PASS
+
+### Summary of Required Fixes
+No fixes required - all criteria pass
+
+Claude: All 9 doc spec quality criteria pass.
+
+<promise>Quality Criteria Met</promise>
+
+**Next step:** Run `/deepwork_jobs.implement` to generate the step instruction files.
+```
+
+## Quality Criteria
+
+- **Sub-Agent Used**: A sub-agent was spawned to provide unbiased review (not just self-review)
+- **All doc spec Criteria Evaluated**: The sub-agent assessed all 9 quality criteria from the doc spec
+- **Findings Addressed**: All failed criteria were fixed by the main agent
+- **Validation Loop Complete**: The review-fix cycle continued until all criteria passed
+- **Promise Included**: The response includes `<promise>Quality Criteria Met</promise>` when complete
+
+## Output
+
+The validated `job.yml` file at `.deepwork/jobs/[job_name]/job.yml` that passes all 9 doc spec quality criteria.

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

@@ -0,0 +1,86 @@
+---
+name: "Monthly AWS Spending Report"
+description: "A Markdown summary of AWS spend across accounts for finance and engineering leadership"
+path_patterns:
+  - "finance/aws-reports/*.md"
+  - "reports/aws/*.md"
+target_audience: "Finance team and Engineering leadership"
+frequency: "Monthly, following AWS invoice arrival"
+quality_criteria:
+  - name: Executive Summary
+    description: Must include a 2-3 sentence summary of total spend, month-over-month change percentage, and top cost driver
+  - name: Visualization
+    description: Must include at least one Mermaid.js chart showing spend breakdown by service (pie chart) or trend over time (line chart)
+  - name: Variance Analysis
+    description: Must compare current month against previous month with percentage changes for top 5 services
+  - name: Cost Attribution
+    description: Must break down costs by team/project using AWS tags where available
+  - name: Action Items
+    description: Must include 2-3 specific, actionable recommendations for cost optimization
+---
+
+# Monthly AWS Spending Report: [Month, Year]
+
+## Executive Summary
+
+[2-3 sentences summarizing:
+- Total spend this month
+- Percentage change from last month
+- The primary cost driver]
+
+## Spend Overview
+
+### Total Spend by Service
+
+```mermaid
+pie title AWS Spend by Service
+    "EC2" : 45
+    "RDS" : 25
+    "S3" : 15
+    "Lambda" : 10
+    "Other" : 5
+```
+
+### Month-over-Month Trend
+
+```mermaid
+xychart-beta
+    title "Monthly AWS Spend Trend"
+    x-axis [Jan, Feb, Mar, Apr, May, Jun]
+    y-axis "Spend ($K)" 0 --> 100
+    line [45, 48, 52, 49, 55, 58]
+```
+
+## Variance Analysis
+
+| Service | Last Month | This Month | Change | % Change |
+|---------|-----------|------------|--------|----------|
+| EC2     | $X,XXX    | $X,XXX     | +$XXX  | +X.X%    |
+| RDS     | $X,XXX    | $X,XXX     | -$XXX  | -X.X%    |
+| S3      | $X,XXX    | $X,XXX     | +$XXX  | +X.X%    |
+| Lambda  | $X,XXX    | $X,XXX     | +$XXX  | +X.X%    |
+| Other   | $X,XXX    | $X,XXX     | +$XXX  | +X.X%    |
+
+## Cost Attribution by Team
+
+| Team/Project | Spend | % of Total |
+|--------------|-------|------------|
+| Platform     | $X,XXX | XX%       |
+| Data         | $X,XXX | XX%       |
+| Product      | $X,XXX | XX%       |
+| Shared       | $X,XXX | XX%       |
+
+## Recommendations
+
+1. **[Action Item 1]**: [Specific recommendation with expected savings]
+2. **[Action Item 2]**: [Specific recommendation with expected savings]
+3. **[Action Item 3]**: [Specific recommendation with expected savings]
+
+## Appendix
+
+### Data Sources
+- AWS Cost Explorer
+- AWS Tags: team, project, environment
+
+### Report Methodology
+[Brief explanation of how costs are calculated and attributed]

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

@@ -0,0 +1,26 @@
+---
+name: "[Document Name]"
+description: "[Brief description of the document's purpose]"
+path_patterns:
+  - "[path/to/documents/*.md]"
+target_audience: "[Who reads this document]"
+frequency: "[How often produced, e.g., Monthly, Per sprint, On demand]"
+quality_criteria:
+  - name: "[Criterion Name]"
+    description: "[What this criterion requires - be specific]"
+  - name: "[Criterion Name]"
+    description: "[What this criterion requires - be specific]"
+  - name: "[Criterion Name]"
+    description: "[What this criterion requires - be specific]"
+---
+
+# [Document Title]: [Variables like Month, Year, Sprint]
+
+## Section 1
+[Describe what goes in this section]
+
+## Section 2
+[Describe what goes in this section]
+
+## Section 3
+[Describe what goes in this section]

deepwork/standard_jobs/deepwork_rules/hooks/capture_prompt_work_tree.sh

@@ -1,24 +1,35 @@
 #!/bin/bash
 # capture_prompt_work_tree.sh - Captures the git work tree state at prompt submission
 #
-# This script creates a snapshot of the current git state by recording
-# all files that have been modified, added, or deleted. This baseline
-# is used for policies with compare_to: prompt to detect what changed
-# during an agent response (between user prompts).
+# This script creates a snapshot of ALL tracked files at the time the prompt
+# is submitted. This baseline is used for rules with compare_to: prompt and
+# created: mode to detect truly NEW files (not modifications to existing ones).
+#
+# The baseline contains ALL tracked files (not just changed files) so that
+# the rules_check hook can determine which files are genuinely new vs which
+# files existed before and were just modified.
+#
+# It also captures the HEAD commit ref so that committed changes can be detected
+# by comparing HEAD at Stop time to the captured ref.
 
 set -e
 
 # Ensure .deepwork directory exists
 mkdir -p .deepwork
 
-# Stage all changes so we can diff against HEAD
-git add -A 2>/dev/null || true
+# Save the current HEAD commit ref for detecting committed changes
+# This is used by get_changed_files_prompt() to detect files changed since prompt,
+# even if those changes were committed during the agent response.
+git rev-parse HEAD > .deepwork/.last_head_ref 2>/dev/null || echo "" > .deepwork/.last_head_ref
 
-# Save the current state of changed files
-# Using git diff --name-only HEAD to get the list of all changed files
-git diff --name-only HEAD > .deepwork/.last_work_tree 2>/dev/null || true
+# Save ALL tracked files (not just changed files)
+# This is critical for created: mode rules to distinguish between:
+# - Newly created files (not in baseline) -> should trigger created: rules
+# - Modified existing files (in baseline) -> should NOT trigger created: rules
+git ls-files > .deepwork/.last_work_tree 2>/dev/null || true
 
-# Also include untracked files not yet in the index
+# Also include untracked files that exist at prompt time
+# These are files the user may have created before submitting the prompt
 git ls-files --others --exclude-standard >> .deepwork/.last_work_tree 2>/dev/null || true
 
 # Sort and deduplicate

deepwork/standard_jobs/deepwork_rules/job.yml

@@ -1,15 +1,22 @@
 name: deepwork_rules
-version: "0.3.0"
-summary: "Rules enforcement for AI agent sessions"
+version: "0.4.0"
+summary: "Creates file-change rules that enforce guidelines during AI sessions. Use when automating documentation sync or code review triggers."
 description: |
   Manages rules that automatically trigger when certain files change during an AI agent session.
   Rules help ensure that code changes follow team guidelines, documentation is updated,
   and architectural decisions are respected.
 
+  IMPORTANT: Rules are evaluated at the "Stop" hook, which fires when an agent finishes its turn.
+  This includes when sub-agents complete their work. Rules are NOT evaluated immediately after
+  each file edit - they batch up and run once at the end of the agent's response cycle.
+  - Command action rules: Execute their command (e.g., `uv sync`) when the agent stops
+  - Prompt action rules: Display instructions to the agent, blocking until addressed
+
   Rules are stored as individual markdown files with YAML frontmatter in the `.deepwork/rules/`
   directory. Each rule file specifies:
   - Detection mode: trigger/safety, set (bidirectional), or pair (directional)
   - Patterns: Glob patterns for matching files, with optional variable capture
+  - Action type: prompt (default) to show instructions, or command to run a shell command
   - Instructions: Markdown content describing what the agent should do
 
   Example use cases:
@@ -17,6 +24,7 @@ description: |
   - Require security review when authentication code is modified
   - Ensure API documentation stays in sync with API code
   - Enforce source/test file pairing
+  - Auto-run `uv sync` when pyproject.toml changes (command action)
 
 changelog:
   - version: "0.1.0"
@@ -25,11 +33,13 @@ changelog:
     changes: "Standardized on 'ask structured questions' phrasing for user input"
   - version: "0.3.0"
     changes: "Migrated to v2 format - individual markdown files in .deepwork/rules/"
+  - version: "0.4.0"
+    changes: "Improved skill descriptions with third-person voice and 'Use when...' triggers for better discoverability"
 
 steps:
   - id: define
     name: "Define Rule"
-    description: "Create a new rule file in .deepwork/rules/"
+    description: "Creates a rule file that triggers when specified files change. Use when setting up documentation sync, code review requirements, or automated commands."
     instructions_file: steps/define.md
     inputs:
       - name: rule_purpose

deepwork/standard_jobs/deepwork_rules/rules/skill-md-validation.md

@@ -1,6 +1,7 @@
 ---
 name: SKILL.md Validation
 trigger: "**/SKILL.md"
+compare_to: base
 ---
 A SKILL.md file has been created or modified. Please validate that it follows the required format:
 

deepwork/templates/claude/skill-job-meta.md.jinja

@@ -65,6 +65,13 @@ If user intent is unclear, use AskUserQuestion to clarify:
 - Present available steps as numbered options
 - Let user select the starting point
 
+## Guardrails
+
+- Do NOT copy/paste step instructions directly; always use the Skill tool to invoke steps
+- Do NOT skip steps in the workflow unless the user explicitly requests it
+- Do NOT proceed to the next step if the current step's outputs are incomplete
+- Do NOT make assumptions about user intent; ask for clarification when ambiguous
+
 ## Context Files
 
 - Job definition: `.deepwork/jobs/{{ job_name }}/job.yml`

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

@@ -46,7 +46,8 @@ user-invocable: false
 {% if quality_criteria or hooks %}
 hooks:
 {% if quality_criteria %}
-  Stop:
+{% for event_name in ["Stop", "SubagentStop"] %}
+  {{ event_name }}:
     - hooks:
         - type: prompt
           prompt: |
@@ -63,14 +64,32 @@ hooks:
             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
+            If the agent has included `<promise>✓ Quality Criteria Met</promise>` in their response OR
             all criteria appear to be met, respond with: {"ok": true}
 
-            If criteria are NOT met OR the promise tag is missing, respond with:
+            If criteria are NOT met AND the promise tag is missing, respond with:
             {"ok": false, "reason": "**AGENT: TAKE ACTION** - [which criteria failed and why]"}
+{% endfor %}
 {% endif %}
 {% for event_name, event_hooks in hooks.items() %}
-{% if not (event_name == "Stop" and quality_criteria) %}
+{% if not (event_name == "Stop" and quality_criteria) and not (event_name == "SubagentStop" and "Stop" in hooks) %}
+{# For Stop events, generate both Stop and SubagentStop blocks #}
+{% if event_name == "Stop" %}
+{% for stop_event in ["Stop", "SubagentStop"] %}
+  {{ stop_event }}:
+    - hooks:
+{% for hook in event_hooks %}
+{% if hook.type == "script" %}
+        - type: command
+          command: ".deepwork/jobs/{{ job_name }}/{{ hook.path }}"
+{% else %}
+        - type: prompt
+          prompt: |
+            {{ hook.content | indent(12) }}
+{% endif %}
+{% endfor %}
+{% endfor %}
+{% else %}
   {{ event_name }}:
     - hooks:
 {% for hook in event_hooks %}
@@ -84,6 +103,7 @@ hooks:
 {% endif %}
 {% endfor %}
 {% endif %}
+{% endif %}
 {% endfor %}
 {% endif %}
 ---
@@ -149,12 +169,45 @@ Use branch format: `deepwork/{{ job_name }}-[instance]-YYYYMMDD`
 {% if outputs %}
 **Required outputs**:
 {% for output in outputs %}
-- `{{ output }}`{% if output.endswith('/') %} (directory){% endif %}
+- `{{ output.file }}`{% if output.file.endswith('/') %} (directory){% endif %}
+
+{% if output.has_doc_spec and output.doc_spec %}
+  **Doc Spec**: {{ output.doc_spec.name }}
+  > {{ output.doc_spec.description }}
+  **Definition**: `{{ output.doc_spec.path }}`
+{% if output.doc_spec.target_audience %}
+  **Target Audience**: {{ output.doc_spec.target_audience }}
+{% endif %}
+{% if output.doc_spec.quality_criteria %}
+  **Quality Criteria**:
+{% for criterion in output.doc_spec.quality_criteria %}
+  {{ loop.index }}. **{{ criterion.name }}**: {{ criterion.description }}
+{% endfor %}
+{% endif %}
+{% if output.doc_spec.example_document %}
+
+  <details>
+  <summary>Example Document Structure</summary>
+
+  ```markdown
+  {{ output.doc_spec.example_document | indent(2) }}
+  ```
+
+  </details>
+{% endif %}
+{% endif %}
 {% endfor %}
 {% else %}
 No specific file outputs required.
 {% endif %}
 
+## Guardrails
+
+- Do NOT skip prerequisite verification if this step has dependencies
+- Do NOT produce partial outputs; complete all required outputs before finishing
+- Do NOT proceed without required inputs; ask the user if any are missing
+- Do NOT modify files outside the scope of this step's defined outputs
+
 {% if quality_criteria or stop_hooks %}
 ## Quality Validation
 
@@ -180,12 +233,12 @@ Stop hooks will automatically validate your work. The loop continues until all c
 
 {% if is_standalone %}
 1. Verify outputs are created
-2. Inform user: "{{ step_id }} complete{% if outputs %}, outputs: {{ outputs | join(', ') }}{% endif %}"
+2. Inform user: "{{ step_id }} complete{% if outputs %}, outputs: {{ outputs | map(attribute='file') | join(', ') }}{% endif %}"
 
 This standalone skill can be re-run anytime.
 {% else %}
 1. Verify outputs are created
-2. Inform user: "Step {{ step_number }}/{{ total_steps }} complete{% if outputs %}, outputs: {{ outputs | join(', ') }}{% endif %}"
+2. Inform user: "Step {{ step_number }}/{{ total_steps }} complete{% if outputs %}, outputs: {{ outputs | map(attribute='file') | join(', ') }}{% endif %}"
 {% if next_step %}
 3. **Continue workflow**: Use Skill tool to invoke `/{{ job_name }}.{{ next_step }}`
 {% else %}

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

@@ -106,7 +106,22 @@ Use branch format: `deepwork/{{ job_name }}-[instance]-YYYYMMDD`
 {% if outputs %}
 **Required outputs**:
 {% for output in outputs %}
-- `{{ output }}`{% if output.endswith('/') %} (directory){% endif %}
+- `{{ output.file }}`{% if output.file.endswith('/') %} (directory){% endif %}
+
+{% if output.has_doc_spec and output.doc_spec %}
+  **Doc Spec**: {{ output.doc_spec.name }}
+  > {{ output.doc_spec.description }}
+  **Definition**: `{{ output.doc_spec.path }}`
+{% if output.doc_spec.target_audience %}
+  **Target Audience**: {{ output.doc_spec.target_audience }}
+{% endif %}
+{% if output.doc_spec.quality_criteria %}
+  **Quality Criteria**:
+{% for criterion in output.doc_spec.quality_criteria %}
+  {{ loop.index }}. **{{ criterion.name }}**: {{ criterion.description }}
+{% endfor %}
+{% endif %}
+{% endif %}
 {% endfor %}
 {% else %}
 No specific file outputs required.
@@ -128,12 +143,12 @@ No specific file outputs required.
 
 {% if is_standalone %}
 1. Verify outputs are created
-2. Inform user: "{{ step_id }} complete{% if outputs %}, outputs: {{ outputs | join(', ') }}{% endif %}"
+2. Inform user: "{{ step_id }} complete{% if outputs %}, outputs: {{ outputs | map(attribute='file') | join(', ') }}{% endif %}"
 
 This standalone command can be re-run anytime.
 {% else %}
 1. Verify outputs are created
-2. Inform user: "Step {{ step_number }}/{{ total_steps }} complete{% if outputs %}, outputs: {{ outputs | join(', ') }}{% endif %}"
+2. Inform user: "Step {{ step_number }}/{{ total_steps }} complete{% if outputs %}, outputs: {{ outputs | map(attribute='file') | join(', ') }}{% endif %}"
 {% if next_step %}
 3. **Tell user next command**: `/{{ job_name }}:{{ next_step }}`
 {% else %}

deepwork/utils/fs.py

@@ -1,9 +1,43 @@
 """Filesystem utilities for safe file operations."""
 
 import shutil
+import stat
 from pathlib import Path
 
 
+def fix_permissions(path: Path | str) -> None:
+    """
+    Fix file permissions after copying to ensure files are user-writable.
+
+    This is needed because shutil.copytree/copy preserve source permissions,
+    and if the source was installed with restrictive permissions (e.g., read-only),
+    the copied files would also be read-only.
+
+    For directories: Sets rwx for user (0o700 minimum)
+    For files: Sets rw for user (0o600 minimum), preserves executable bit
+
+    Args:
+        path: File or directory path to fix permissions for
+    """
+    path_obj = Path(path)
+
+    if path_obj.is_file():
+        # Get current permissions
+        current_mode = path_obj.stat().st_mode
+        # Ensure user can read and write, preserve executable bit
+        new_mode = current_mode | stat.S_IRUSR | stat.S_IWUSR
+        path_obj.chmod(new_mode)
+    elif path_obj.is_dir():
+        # Fix directory permissions first (need execute to traverse)
+        current_mode = path_obj.stat().st_mode
+        new_mode = current_mode | stat.S_IRWXU  # rwx for user
+        path_obj.chmod(new_mode)
+
+        # Recursively fix all contents
+        for item in path_obj.iterdir():
+            fix_permissions(item)
+
+
 def ensure_dir(path: Path | str) -> Path:
     """
     Create directory if it doesn't exist.
@@ -94,6 +128,8 @@ def copy_dir(src: Path | str, dst: Path | str, ignore_patterns: list[str] | None
         ignore_func = _ignore
 
     shutil.copytree(src_path, dst_path, ignore=ignore_func, dirs_exist_ok=True)
+    # Fix permissions - source may have restrictive permissions (e.g., read-only)
+    fix_permissions(dst_path)
 
 
 def find_files(directory: Path | str, pattern: str) -> list[Path]:

deepwork/utils/yaml_utils.py

@@ -69,6 +69,30 @@ def save_yaml(path: Path | str, data: dict[str, Any]) -> None:
         raise YAMLError(f"Failed to write YAML file {path_obj}: {e}") from e
 
 
+def load_yaml_from_string(content: str) -> dict[str, Any] | None:
+    """
+    Load YAML from a string and return parsed data.
+
+    Args:
+        content: YAML content as string
+
+    Returns:
+        Parsed YAML data as dictionary, or None if content is empty
+
+    Raises:
+        YAMLError: If YAML parsing fails
+    """
+    try:
+        data = yaml.safe_load(content)
+        if data is None:
+            return None
+        if not isinstance(data, dict):
+            raise YAMLError(f"YAML content must be a dictionary, got {type(data).__name__}")
+        return data
+    except yaml.YAMLError as e:
+        raise YAMLError(f"Failed to parse YAML content: {e}") from e
+
+
 def validate_yaml_structure(data: dict[str, Any], required_keys: list[str]) -> None:
     """
     Validate that YAML data contains required keys.