deepwork 0.3.1__py3-none-any.whl → 0.5.1__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

@@ -8,12 +8,20 @@
 # 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
 
+# 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 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

deepwork/standard_jobs/deepwork_rules/job.yml

@@ -1,6 +1,6 @@
 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,
@@ -33,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/templates/claude/AGENTS.md

@@ -0,0 +1,38 @@
+# Claude Templates - Agent Notes
+
+Notes for AI agents working on Claude Code jinja templates.
+
+## Prompt-Based Stop Hooks - NOT WORKING
+
+**IMPORTANT: Prompt-based stop hooks (`type: prompt` for Stop/SubagentStop events) do not currently work properly in Claude Code.**
+
+Reference: https://github.com/anthropics/claude-code/issues/20221
+
+### What This Means
+
+- Do NOT use `type: prompt` hooks for Stop or SubagentStop events in templates
+- The quality validation loop pattern that relies on prompt hooks will not function as expected
+- Instead, instruct agents to use a sub-agent (e.g., Haiku) to review their work against quality criteria
+
+### Workaround
+
+Instead of prompt-based stop hooks, templates should include explicit instructions in the command content directing the agent to:
+
+1. Have a sub-agent using Haiku review the work against the specified quality criteria
+2. Fix any valid issues raised by the sub-agent
+3. Have the sub-agent review again until all valid feedback is handled
+
+### Future Reversal
+
+If prompt-based stop hooks are fixed in Claude Code (check the issue above for updates), this guidance should be reversed and prompt hooks can be re-enabled in templates.
+
+## Historical Context (Prompt Hooks - When They Work)
+
+The following guidance applies IF prompt hooks start working again:
+
+When writing prompt-based hooks (e.g., Stop hooks with `type: prompt`):
+
+- **Do NOT include instructions on how to return responses** (e.g., "respond with JSON", "return `{"ok": true}`"). Claude Code's internal instructions already specify the expected response format for prompt hooks.
+- Adding redundant response format instructions can cause conflicts or confusion with the built-in behavior. i.e. the hook will not block the agent from stopping.
+
+Reference: https://github.com/anthropics/claude-code/issues/11786

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

@@ -40,52 +40,51 @@ Template Variables:
 ---
 name: {{ job_name }}.{{ step_id }}
 description: "{{ step_description }}"
-{% if not exposed %}
+{%- if not exposed %}
 user-invocable: false
-{% endif %}
-{% if quality_criteria or hooks %}
+{%- endif %}{#- if not exposed #}
+{#-
+  NOTE: Prompt-based stop hooks do not currently work in Claude Code.
+  See: https://github.com/anthropics/claude-code/issues/20221
+  Only command/script hooks are generated here. Prompt hooks are filtered out.
+  Quality validation is handled via sub-agent review in the instructions section.
+#}
+{%- if hooks -%}
+{%- set has_command_hooks = namespace(value=false) -%}
+{%- for event_name, event_hooks in hooks.items() -%}
+{%- for hook in event_hooks -%}
+{%- if hook.type == "script" -%}
+{%- set has_command_hooks.value = true -%}
+{%- endif -%}{#- if hook.type == "script" #}
+{%- endfor -%}{#- for hook in event_hooks #}
+{%- endfor -%}{#- for event_name, event_hooks in hooks.items() #}
+{%- if has_command_hooks.value %}
 hooks:
-{% if quality_criteria %}
-  Stop:
+{%- for event_name, event_hooks in hooks.items() %}
+{%- set script_hooks = event_hooks | selectattr("type", "equalto", "script") | list %}
+{%- if script_hooks -%}
+{#- For Stop events, generate both Stop and SubagentStop blocks #}
+{%- if event_name == "Stop" %}
+{%- for stop_event in ["Stop", "SubagentStop"] %}
+  {{ stop_event }}:
     - hooks:
-        - type: prompt
-          prompt: |
-            You must evaluate whether Claude has met all the below quality criteria for the request.
-
-            ## Quality Criteria
-
-{% for criterion in quality_criteria %}
-            {{ loop.index }}. {{ criterion }}
-{% endfor %}
-
-            ## 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 OR the promise tag is missing, respond with:
-            {"ok": false, "reason": "**AGENT: TAKE ACTION** - [which criteria failed and why]"}
-{% endif %}
-{% for event_name, event_hooks in hooks.items() %}
-{% if not (event_name == "Stop" and quality_criteria) %}
+{%- for hook in script_hooks %}
+        - type: command
+          command: ".deepwork/jobs/{{ job_name }}/{{ hook.path }}"
+{%- endfor %}{#- for hook in script_hooks #}
+{%- endfor %}{#- for stop_event in ["Stop", "SubagentStop"] #}
+{%- elif event_name != "SubagentStop" or "Stop" not in hooks %}
   {{ event_name }}:
     - hooks:
-{% for hook in event_hooks %}
-{% if hook.type == "script" %}
+{%- for hook in script_hooks %}
         - type: command
           command: ".deepwork/jobs/{{ job_name }}/{{ hook.path }}"
-{% else %}
-        - type: prompt
-          prompt: |
-            {{ hook.content | indent(12) }}
-{% endif %}
-{% endfor %}
-{% endif %}
-{% endfor %}
-{% endif %}
+{%- endfor %}{#- for hook in script_hooks #}
+{%- endif %}{#- if event_name == "Stop" #}
+{%- endif %}{#- if script_hooks #}
+{%- endfor %}{#- for event_name, event_hooks in hooks.items() #}
+{%- endif %}{#- if has_command_hooks.value #}
+{%- endif %}{#- if hooks #}
 ---
 
 # {{ job_name }}.{{ step_id }}
@@ -94,7 +93,7 @@ hooks:
 **Standalone skill** - can be run anytime
 {% else %}
 **Step {{ step_number }}/{{ total_steps }}** in **{{ job_name }}** workflow
-{% endif %}
+{% endif %}{#- if is_standalone #}
 
 > {{ job_summary }}
 
@@ -104,8 +103,8 @@ hooks:
 Before proceeding, confirm these steps are complete:
 {% for dep in dependencies %}
 - `/{{ job_name }}.{{ dep }}`
-{% endfor %}
-{% endif %}
+{% endfor %}{#- for dep in dependencies #}
+{% endif %}{#- if dependencies #}
 
 ## Instructions
 
@@ -117,7 +116,7 @@ Before proceeding, confirm these steps are complete:
 ### Job Context
 
 {{ job_description }}
-{% endif %}
+{% endif %}{#- if job_description #}
 
 {% if user_inputs or file_inputs %}
 ## Required Inputs
@@ -126,16 +125,16 @@ Before proceeding, confirm these steps are complete:
 **User Parameters** - Gather from user before starting:
 {% for input in user_inputs %}
 - **{{ input.name }}**: {{ input.description }}
-{% endfor %}
-{% endif %}
+{% endfor %}{#- for input in user_inputs #}
+{% endif %}{#- if user_inputs #}
 
 {% if file_inputs %}
 **Files from Previous Steps** - Read these first:
 {% for input in file_inputs %}
 - `{{ input.file }}` (from `{{ input.from_step }}`)
-{% endfor %}
-{% endif %}
-{% endif %}
+{% endfor %}{#- for input in file_inputs #}
+{% endif %}{#- if file_inputs #}
+{% endif %}{#- if user_inputs or file_inputs #}
 
 ## Work Branch
 
@@ -149,49 +148,87 @@ Use branch format: `deepwork/{{ job_name }}-[instance]-YYYYMMDD`
 {% if outputs %}
 **Required outputs**:
 {% for output in outputs %}
-- `{{ output }}`{% if output.endswith('/') %} (directory){% endif %}
-{% endfor %}
+- `{{ 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.target_audience #}
+{% if output.doc_spec.quality_criteria %}
+  **Quality Criteria**:
+{% for criterion in output.doc_spec.quality_criteria %}
+  {{ loop.index }}. **{{ criterion.name }}**: {{ criterion.description }}
+{% endfor %}{#- for criterion in output.doc_spec.quality_criteria #}
+{% endif %}{#- if output.doc_spec.quality_criteria #}
+{% if output.doc_spec.example_document %}
+
+  <details>
+  <summary>Example Document Structure</summary>
+
+  ```markdown
+  {{ output.doc_spec.example_document | indent(2) }}
+  ```
+
+  </details>
+{% endif %}{#- if output.doc_spec.example_document #}
+{% endif %}{#- if output.has_doc_spec and output.doc_spec #}
+{% endfor %}{#- for output in outputs #}
 {% else %}
 No specific file outputs required.
-{% endif %}
+{% endif %}{#- if outputs #}
 
-{% if quality_criteria or stop_hooks %}
-## Quality Validation
+## Guardrails
 
-Stop hooks will automatically validate your work. The loop continues until all criteria pass.
+- 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 %}
-**Criteria (all must be satisfied)**:
-{% for criterion in quality_criteria %}
-{{ loop.index }}. {{ criterion }}
-{% endfor %}
-{% endif %}
+## Quality Validation
 
-{% for hook in stop_hooks %}
-{% if hook.type == "script" %}
-**Validation script**: `.deepwork/jobs/{{ job_name }}/{{ hook.path }}` (runs automatically)
-{% endif %}
-{% endfor %}
+**Before completing this step, you MUST have your work reviewed against the quality criteria below.**
 
-**To complete**: Include `<promise>✓ Quality Criteria Met</promise>` in your final response only after verifying ALL criteria are satisfied.
+Use a sub-agent (Haiku model) to review your work against these criteria:
 
-{% endif %}
+**Criteria (all must be satisfied)**:
+{% for criterion in quality_criteria -%}
+{{ loop.index }}. {{ criterion }}
+{% endfor %}{#- for criterion in quality_criteria #}
+**Review Process**:
+1. Once you believe your work is complete, spawn a sub-agent using Haiku to review your work against the quality criteria above
+2. The sub-agent should examine your outputs and verify each criterion is met
+3. If the sub-agent identifies valid issues, fix them
+4. Have the sub-agent review again until all valid feedback has been addressed
+5. Only mark the step complete when the sub-agent confirms all criteria are satisfied
+
+{% endif %}{#- if quality_criteria #}
+{% if stop_hooks -%}
+{% for hook in stop_hooks -%}
+{% if hook.type == "script" -%}
+**Validation script**: `.deepwork/jobs/{{ job_name }}/{{ hook.path }}` (runs automatically)
+{% endif -%}{#- if hook.type == "script" #}
+{% endfor %}{#- for hook in stop_hooks #}
+{% endif %}{#- if stop_hooks #}
 ## On Completion
 
 {% 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 %}
 3. **Workflow complete**: All steps finished. Consider creating a PR to merge the work branch.
-{% endif %}
-{% endif %}
+{% endif %}{#- if next_step #}
+{% endif %}{#- if is_standalone #}
 
 ---