deepwork 0.5.1__tar.gz → 0.7.0a1__tar.gz

{deepwork-0.5.1 → deepwork-0.7.0a1}/.claude/settings.json

@@ -95,55 +95,20 @@
       "Bash(npm:*)",
       "Bash(npx:*)",
       "Edit(./**)",
-      "Read(./.deepwork/tmp/**)",
-      "Edit(./.deepwork/tmp/**)",
-      "Write(./.deepwork/tmp/**)",
-      "Skill(commit)",
-      "Skill(commit.review)",
-      "Skill(commit.test)",
-      "Skill(commit.lint)",
-      "Skill(commit.commit_and_push)",
-      "Skill(deepwork_jobs)",
-      "Skill(deepwork_jobs.define)",
-      "Skill(deepwork_jobs.review_job_spec)",
-      "Skill(deepwork_jobs.implement)",
-      "Skill(deepwork_jobs.learn)",
-      "Skill(add_platform)",
-      "Skill(add_platform.research)",
-      "Skill(add_platform.add_capabilities)",
-      "Skill(add_platform.implement)",
-      "Skill(add_platform.verify)",
-      "Skill(update)",
-      "Skill(update.job)",
-      "Skill(manual_tests)",
-      "Skill(manual_tests.run_not_fire_tests)",
-      "Skill(manual_tests.run_fire_tests)",
-      "Skill(deepwork_rules)",
-      "Skill(deepwork_rules.define)",
-      "Bash(deepwork rules clear_queue)",
-      "Bash(rm -rf .deepwork/tmp/rules/queue/*.json)",
-      "Skill(manual_tests.reset)",
-      "Skill(manual_tests.infinite_block_tests)",
       "Read(./.deepwork/**)",
       "Edit(./.deepwork/**)",
       "Write(./.deepwork/**)",
       "Bash(deepwork:*)",
-      "Bash(.claude/hooks/commit_job_git_commit.sh:*)",
-      "Bash(./.deepwork/jobs/deepwork_jobs/make_new_job.sh:*)"
+      "Bash(./.deepwork/jobs/deepwork_jobs/make_new_job.sh:*)",
+      "WebSearch",
+      "Skill(deepwork)",
+      "mcp__deepwork__get_workflows",
+      "mcp__deepwork__start_workflow",
+      "mcp__deepwork__finished_step",
+      "mcp__deepwork__abort_workflow"
     ]
   },
   "hooks": {
-    "PreToolUse": [
-      {
-        "matcher": "Bash",
-        "hooks": [
-          {
-            "type": "command",
-            "command": ".claude/hooks/block_bash_with_instructions.sh"
-          }
-        ]
-      }
-    ],
     "SessionStart": [
       {
         "matcher": "",
@@ -154,39 +119,6 @@
           }
         ]
       }
-    ],
-    "UserPromptSubmit": [
-      {
-        "matcher": "",
-        "hooks": [
-          {
-            "type": "command",
-            "command": ".deepwork/jobs/deepwork_rules/hooks/user_prompt_submit.sh"
-          }
-        ]
-      }
-    ],
-    "Stop": [
-      {
-        "matcher": "",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "deepwork hook rules_check"
-          }
-        ]
-      }
-    ],
-    "SubagentStop": [
-      {
-        "matcher": "",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "deepwork hook rules_check"
-          }
-        ]
-      }
     ]
   }
 }

deepwork-0.7.0a1/.claude/skills/deepwork/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: deepwork
+description: "Start or continue DeepWork workflows using MCP tools"
+---
+
+# DeepWork Workflow Manager
+
+Execute multi-step workflows with quality gate checkpoints.
+
+> **IMPORTANT**: Use the DeepWork MCP server tools. All workflow operations
+> are performed through MCP tool calls and following the instructions they return,
+> not by reading instructions from files.
+
+## How to Use
+
+1. Call `get_workflows` to discover available workflows
+2. Call `start_workflow` with goal, job_name, and workflow_name
+3. Follow the step instructions returned
+4. Call `finished_step` with your outputs when done
+5. Handle the response: `needs_work`, `next_step`, or `workflow_complete`
+
+## Intent Parsing
+
+When the user invokes `/deepwork`, parse their intent:
+1. **ALWAYS**: Call `get_workflows` to discover available workflows
+2. Based on the available flows and what the user said in their request, proceed:
+    - **Explicit workflow**: `/deepwork <a workflow name>` → start the `<a workflow name>` workflow
+    - **General request**: `/deepwork <a request>` → infer best match from available workflows
+    - **No context**: `/deepwork` alone → ask user to choose from available workflows

{deepwork-0.5.1 → deepwork-0.7.0a1}/.deepwork/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

{deepwork-0.5.1 → deepwork-0.7.0a1}/.deepwork/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

deepwork-0.7.0a1/.deepwork/jobs/deepwork_jobs/job.yml

@@ -0,0 +1,225 @@
+# yaml-language-server: $schema=.deepwork/schemas/job.schema.json
+name: deepwork_jobs
+version: "1.2.1"
+summary: "Creates and manages multi-step AI workflows. Use when defining, implementing, testing, or improving DeepWork jobs."
+description: |
+  Core commands for managing DeepWork jobs. These commands help you define new multi-step
+  workflows, test them on real use cases, and learn from running them.
+
+  The `new_job` workflow guides you through the full lifecycle of creating a new job:
+  1. **Define**: Gather requirements through structured questions and create job.yml
+  2. **Implement**: Generate step instruction files and sync slash commands
+  3. **Test**: Run the workflow on a real use case, critique output, and iterate with user
+  4. **Iterate**: Review what happened and improve the job definition based on learnings
+
+  The `learn` skill reflects on conversations where DeepWork jobs were run, identifies
+  confusion or inefficiencies, and improves job instructions. It also captures bespoke
+  learnings specific to the current run into AGENTS.md files in the working folder.
+
+workflows:
+  - name: new_job
+    summary: "Create a new DeepWork job from scratch through definition, implementation, testing, and iteration"
+    steps:
+      - define
+      - implement
+      - test
+      - iterate
+
+  - name: repair
+    summary: "Clean up and migrate DeepWork configurations from prior versions"
+    steps:
+      - fix_settings
+      - fix_jobs
+      - errata
+
+  - name: learn
+    summary: "Analyze conversation history to improve job instructions and capture learnings"
+    steps:
+      - learn
+
+changelog:
+  - version: "1.2.1"
+    changes: "Removed deprecated exposed field from learn step; added learn workflow to make step accessible via MCP"
+  - version: "1.2.0"
+    changes: "Added repair workflow with fix_settings, fix_jobs, and errata steps for migrating old DeepWork configurations to current format"
+  - version: "1.1.0"
+    changes: "Added test and iterate steps to new_job workflow; test runs the workflow on a real use case and gathers feedback; iterate improves the job definition based on what happened"
+  - version: "1.0.1"
+    changes: "Removed review_job_spec step from new_job workflow; implement now follows directly from define"
+  - version: "1.0.0"
+    changes: "Added workflows section to distinguish new_job workflow (define→review_job_spec→implement) from standalone learn skill"
+  - version: "0.1.0"
+    changes: "Initial version"
+  - version: "0.2.0"
+    changes: "Replaced refine command with learn command for conversation-driven improvement"
+  - version: "0.3.0"
+    changes: "Added make_new_job.sh script and templates directory; updated instructions to reference templates instead of inline examples"
+  - version: "0.4.0"
+    changes: "Removed implementation_summary and learning_summary outputs; simplified step outputs"
+  - version: "0.5.0"
+    changes: "Standardized on 'ask structured questions' phrasing for user input; Updated quality criteria hooks to verify phrase usage; Added guidance in implement.md to use phrase in generated instructions"
+  - version: "0.6.0"
+    changes: "Added doc spec support; define.md now detects document-oriented workflows and guides doc spec creation; learn.md now identifies and applies doc spec-related improvements"
+  - version: "0.7.0"
+    changes: "Added job.yml doc spec; define step now outputs job.yml with doc_spec reference for quality validation"
+  - version: "0.8.0"
+    changes: "Added review_job_spec step between define and implement for doc spec-based quality validation using sub-agent review"
+  - version: "0.9.0"
+    changes: "Improved skill descriptions with third-person voice and 'Use when...' triggers for better discoverability"
+
+steps:
+  - id: define
+    name: "Define Job Specification"
+    description: "Creates a job.yml specification by gathering workflow requirements through structured questions. Use when starting a new multi-step workflow."
+    instructions_file: steps/define.md
+    inputs:
+      - name: job_purpose
+        description: "What complex task or workflow are you trying to accomplish?"
+    outputs:
+      - file: job.yml
+        doc_spec: .deepwork/doc_specs/job_spec.md
+    dependencies: []
+  - id: implement
+    name: "Implement Job Steps"
+    description: "Generates step instruction files and syncs slash commands from the job.yml specification. Use after defining a job."
+    instructions_file: steps/implement.md
+    inputs:
+      - file: job.yml
+        from_step: define
+    outputs:
+      - steps/
+    dependencies:
+      - define
+    quality_criteria:
+      - "**Complete Instructions**: Are ALL step instruction files complete (not stubs or placeholders)?"
+      - "**Specific & Actionable**: Are instructions tailored to each step's purpose, not generic?"
+      - "**Output Examples**: Does each instruction file show what good output looks like?"
+      - "**Quality Criteria**: Does each instruction file define quality criteria for its outputs?"
+      - "**Ask Structured Questions**: Do step instructions that gather user input explicitly use the phrase \"ask structured questions\"?"
+
+  - id: test
+    name: "Test the New Workflow"
+    description: "Tests the newly created workflow by running it on a real use case, critiquing the output, and iterating until the user is satisfied. Use after implementing a job."
+    instructions_file: steps/test.md
+    inputs:
+      - file: job.yml
+        from_step: define
+      - file: steps/
+        from_step: implement
+    outputs:
+      - test_feedback.md
+    dependencies:
+      - define
+      - implement
+    quality_criteria:
+      - "**User Informed**: Did the agent explain the workflow is ready and ask what to test it on?"
+      - "**Workflow Invoked**: Was the new workflow actually run on the user's test case via MCP?"
+      - "**Output Critiqued**: Did the agent identify up to 3 top issues with the output?"
+      - "**User Feedback Gathered**: Did the agent ask the user about each issue and gather additional feedback?"
+      - "**Corrections Made**: Were all requested corrections applied to the output?"
+      - "**User Satisfied**: Did the user confirm the output meets their needs?"
+
+  - id: iterate
+    name: "Iterate on Workflow Design"
+    description: "Reviews the test run conversation and improves the job definition based on what happened. Use after testing a newly created job."
+    instructions_file: steps/iterate.md
+    inputs:
+      - file: job.yml
+        from_step: define
+      - file: steps/
+        from_step: implement
+    outputs:
+      - job.yml
+      - steps/
+    dependencies:
+      - define
+      - implement
+      - test
+    quality_criteria:
+      - "**Conversation Reviewed**: Did the agent analyze the test run for inefficiencies and issues?"
+      - "**Instructions Improved**: Were step instructions updated to address identified problems?"
+      - "**Quality Criteria Updated**: Were quality criteria adjusted to better match user expectations?"
+      - "**Tool Usage Considered**: Did the agent consider if different tools would improve the workflow?"
+      - "**Recap Provided**: Did the agent summarize what was improved and why?"
+
+  - id: learn
+    name: "Learn from Job Execution"
+    description: "Analyzes conversation history to improve job instructions and capture learnings. Use after running a job to refine it."
+    instructions_file: steps/learn.md
+    inputs:
+      - name: job_name
+        description: "Name of the job that was run (optional - will auto-detect from conversation)"
+    outputs:
+      - AGENTS.md
+    dependencies: []
+    quality_criteria:
+      - "**Conversation Analyzed**: Did the agent review the conversation for DeepWork job executions?"
+      - "**Confusion Identified**: Did the agent identify points of confusion, errors, or inefficiencies?"
+      - "**Instructions Improved**: Were job instructions updated to address identified issues?"
+      - "**Instructions Concise**: Are instructions free of redundancy and unnecessary verbosity?"
+      - "**Shared Content Extracted**: Is lengthy/duplicated content extracted into referenced files?"
+      - "**doc spec Reviewed (if applicable)**: For jobs with doc spec outputs, were doc spec-related learnings identified?"
+      - "**doc spec Updated (if applicable)**: Were doc spec files updated with improved quality criteria or structure?"
+      - "**Bespoke Learnings Captured**: Were run-specific learnings added to AGENTS.md?"
+      - "**File References Used**: Do AGENTS.md entries reference other files where appropriate?"
+      - "**Working Folder Correct**: Is AGENTS.md in the correct working folder for the job?"
+      - "**Generalizable Separated**: Are generalizable improvements in instructions, not AGENTS.md?"
+
+  - id: fix_settings
+    name: "Fix Settings Files"
+    description: "Cleans up .claude/settings.json and related configuration files, removing legacy permissions, duplicate hooks, and hardcoded paths from prior DeepWork versions."
+    instructions_file: steps/fix_settings.md
+    inputs: []
+    outputs:
+      - .claude/settings.json
+    dependencies: []
+    quality_criteria:
+      - "**DeepWork Skills Removed**: Are `Skill(...)` entries matching jobs in `.deepwork/jobs/` removed?"
+      - "**Non-DeepWork Skills Preserved**: Are skills NOT matching DeepWork jobs left intact?"
+      - "**make_new_job.sh Preserved**: Is the `Bash(...)` permission for `make_new_job.sh` preserved (if present)?"
+      - "**Rules Hooks Removed**: Are all DeepWork Rules hooks and permissions removed?"
+      - "**Duplicate Hooks Removed**: Are duplicate hook entries consolidated or removed?"
+      - "**Hardcoded Paths Removed**: Are user-specific hardcoded paths (like `/Users/*/...`) removed?"
+      - "**Deprecated Commands Removed**: Are deprecated commands like `deepwork hook *` removed?"
+      - "**Valid JSON**: Is settings.json still valid JSON after modifications?"
+      - "**Backup Created**: Was a backup of the original settings created before modifications?"
+
+  - id: fix_jobs
+    name: "Fix Job Definitions"
+    description: "Updates job.yml files and step instructions to current DeepWork format, removing deprecated fields and migrating to new structures."
+    instructions_file: steps/fix_jobs.md
+    inputs:
+      - file: .claude/settings.json
+        from_step: fix_settings
+    outputs:
+      - .deepwork/jobs/
+    dependencies:
+      - fix_settings
+    quality_criteria:
+      - "**Exposed Field Addressed**: Are `exposed: true` fields removed or noted as deprecated?"
+      - "**Stop Hooks Migrated**: Are `stop_hooks` migrated to `hooks.after_agent` format?"
+      - "**Removed Steps Cleaned**: Are references to removed steps (like `review_job_spec`) updated?"
+      - "**Orphaned Steps Fixed**: For jobs with no workflows, is there a single workflow (named after the job) containing all steps? For jobs with existing workflows, does each orphan get its own workflow (named after the step)?"
+      - "**Valid YAML**: Are all job.yml files valid YAML?"
+
+  - id: errata
+    name: "Clean Up Errata"
+    description: "Removes obsolete files and folders from prior DeepWork versions, including old skill directories, temp files, and deprecated configurations."
+    instructions_file: steps/errata.md
+    inputs:
+      - file: .deepwork/jobs/
+        from_step: fix_jobs
+    outputs:
+      - repair_summary.md
+    dependencies:
+      - fix_settings
+      - fix_jobs
+    quality_criteria:
+      - "**Legacy Job Skills Removed**: Are legacy skill folders for each job removed from `.claude/skills/` and `.gemini/skills/`?"
+      - "**Deepwork Skill Preserved**: Does the `deepwork` skill folder still exist in `.claude/skills/deepwork/`?"
+      - "**Temp Files Cleaned**: Are `.deepwork/tmp/` contents cleaned appropriately?"
+      - "**Rules Folder Removed**: Is `.deepwork/rules/` folder backed up and removed (fully deprecated)?"
+      - "**Rules Job Removed**: Is `.deepwork/jobs/deepwork_rules/` removed if present?"
+      - "**Config Version Updated**: Is `.deepwork/config.yml` using current version format?"
+      - "**Summary Provided**: Is a repair_summary.md file created documenting all changes made?"
+      - "**Git Status Clean**: Are changes ready to be committed (no untracked garbage files)?"

{deepwork-0.5.1/src/deepwork/standard_jobs → deepwork-0.7.0a1/.deepwork/jobs}/deepwork_jobs/steps/define.md

@@ -61,11 +61,16 @@ When creating a doc spec, gather the following information:
    - How often is it produced? (frequency)
 
 3. **Quality Criteria** (3-5 criteria, each with name and description)
+
+   **Important**: Doc spec quality criteria define requirements for the **output document itself**, not the process of creating it. Focus on what the finished document must contain or achieve.
+
    Examples for a spending report:
    - **Visualization**: Must include charts showing spend breakdown by service
    - **Variance Analysis**: Must compare current month against previous with percentages
    - **Action Items**: Must include recommended cost optimization actions
 
+   **Note**: When a doc spec is created for a step's output, the step should generally NOT have separate `quality_criteria` in the job.yml. The doc spec's criteria cover output quality. Only add step-level quality_criteria if there are essential process requirements (e.g., "must use specific tool"), and minimize these when possible.
+
 4. **Document Structure**
    - What sections should it have?
    - Any required elements (tables, charts, summaries)?
@@ -76,7 +81,7 @@ Create the doc spec file at `.deepwork/doc_specs/[doc_spec_name].md`:
 
 **Template reference**: See `.deepwork/jobs/deepwork_jobs/templates/doc_spec.md.template` for the standard structure.
 
-**Complete example**: See `.deepwork/jobs/deepwork_jobs/templates/doc_spec.md.example` for a fully worked example.
+**Complete example**: See `.deepwork/doc_specs/job_spec.md` for a fully worked example (the doc spec for job.yml files).
 
 After creating the doc spec, proceed to Step 2 with the doc spec reference for the final step's output.
 
@@ -101,10 +106,63 @@ For each major phase they mentioned, ask structured questions to gather details:
    - Where should each output be saved? (filename/path)
    - Should outputs be organized in subdirectories? (e.g., `reports/`, `data/`, `drafts/`)
    - Will other steps need this output?
-
-   **Important**: Output paths should always be within the main repository directory structure, not in dot-directories like `.deepwork/`. Dot-directories are for configuration and job definitions, not for job outputs. Use paths like `research/competitors/report.md` rather than `.deepwork/outputs/report.md`.
    - **Does this output have a doc spec?** If a doc spec was created in Step 1.6/1.7, reference it for the appropriate output
 
+   #### Work Product Storage Guidelines
+
+   **Key principle**: Job outputs belong in the main repository directory structure, not in dot-directories. The `.deepwork/` directory is for job definitions and configuration only.
+
+   **Why this matters**:
+   - **Version control**: Work products in the main repo are tracked by git and visible in PRs
+   - **Discoverability**: Team members can find outputs without knowing about DeepWork internals
+   - **Tooling compatibility**: IDEs, search tools, and CI/CD work naturally with standard paths
+   - **Glob patterns**: Well-structured paths enable powerful file matching (e.g., `competitive_research/**/*.md`)
+
+   **Good output path patterns**:
+   ```
+   competitive_research/competitors_list.md
+   competitive_research/acme_corp/research.md
+   operations/reports/2026-01/spending_analysis.md
+   docs/api/endpoints.md
+   ```
+
+   **Avoid these patterns**:
+   ```
+   .deepwork/outputs/report.md          # Hidden in dot-directory
+   output.md                            # Too generic, no context
+   research.md                          # Unclear which research
+   temp/draft.md                        # Transient-sounding paths
+   ```
+
+   **Organizing multi-file outputs**:
+   - Use the job name as a top-level folder when outputs are job-specific
+   - Use parameterized paths for per-entity outputs: `competitive_research/[competitor_name]/`
+   - Match existing project conventions when extending a codebase
+
+   **When to include dates in paths**:
+   - **Include date** for periodic outputs where each version is retained (e.g., monthly reports, quarterly reviews, weekly summaries). These accumulate over time and historical versions remain useful.
+     ```
+     operations/reports/2026-01/spending_analysis.md              # Monthly report - keep history
+     hr/employees/[employee_name]/quarterly_reviews/2026-Q1.pdf   # Per-employee quarterly review
+     ```
+   - **Omit date** for current-state outputs that represent the latest understanding and get updated in place. Previous versions live in git history, not separate files.
+     ```
+     competitive_research/acme_corp/swot.md  # Current SWOT - updated over time
+     docs/architecture/overview.md           # Living document
+     ```
+
+   **Supporting materials and intermediate outputs**:
+   - Content generated in earlier steps to support the final output (research notes, data extracts, drafts) should be placed in a `_dataroom` folder that is a peer to the final output
+   - Name the dataroom folder by replacing the file extension with `_dataroom`
+     ```
+     operations/reports/2026-01/spending_analysis.md           # Final output
+     operations/reports/2026-01/spending_analysis_dataroom/    # Supporting materials
+         raw_data.csv
+         vendor_breakdown.md
+         notes.md
+     ```
+   - This keeps supporting materials organized and discoverable without cluttering the main output location
+
 4. **Step Dependencies**
    - Which previous steps must complete before this one?
    - Are there any ordering constraints?
@@ -114,6 +172,21 @@ For each major phase they mentioned, ask structured questions to gather details:
    - Are there any quality checks or validation needed?
    - What makes a good vs. bad output for this step?
 
+   **Important**: Quality criteria belong in the `quality_criteria` field of job.yml, NOT in the step details. When skills are generated, quality criteria are automatically included in the output. Do not duplicate them in step instructions or details—this causes redundancy and confusion.
+
+6. **Agent Delegation** (optional)
+   - Should this step be executed by a specific agent type?
+   - Use the `agent` field when the step should run in a forked context with a specific agent
+   - When `agent` is set, the generated skill automatically includes `context: fork`
+   - Available agent types:
+     - `general-purpose` - Standard agent for multi-step tasks
+
+   ```yaml
+   steps:
+     - id: research_step
+       agent: general-purpose  # Delegates to the general-purpose agent
+   ```
+
 **Note**: You're gathering this information to understand what instructions will be needed, but you won't create the instruction files yet - that happens in the `implement` step.
 
 #### Doc Spec-Aware Output Format
@@ -154,49 +227,53 @@ After gathering information about all steps:
    - Job description (detailed multi-line explanation)
    - Version number (start with 1.0.0)
 
-### Step 4: Define Quality Validation (Stop Hooks)
+### Step 4: Define Quality Validation Hooks
 
-For each step, consider whether it would benefit from **quality validation loops**. Stop hooks allow the AI agent to iteratively refine its work until quality criteria are met.
+For each step, consider whether it would benefit from **quality validation loops**. Quality hooks allow the AI agent to iteratively refine its work until quality criteria are met.
 
 **Ask structured questions about quality validation:**
 - "Are there specific quality criteria that must be met for this step?"
 - "Would you like the agent to validate its work before completing?"
 - "What would make you send the work back for revision?"
 
-**Stop hooks are particularly valuable for:**
+**Quality hooks are particularly valuable for:**
 - Steps with complex outputs that need multiple checks
 - Steps where quality is critical (final deliverables)
 - Steps with subjective quality criteria that benefit from AI self-review
 
-**Three types of stop hooks are supported:**
+**Three types of hooks are supported:**
 
 1. **Inline Prompt** (`prompt`) - Best for simple quality criteria
    ```yaml
-   stop_hooks:
-     - prompt: |
-         Verify the output meets these criteria:
-         1. Contains at least 5 competitors
-         2. Each competitor has a description
-         3. Selection rationale is clear
+   hooks:
+     after_agent:
+       - prompt: |
+           Verify the output meets these criteria:
+           1. Contains at least 5 competitors
+           2. Each competitor has a description
+           3. Selection rationale is clear
    ```
 
 2. **Prompt File** (`prompt_file`) - For detailed/reusable criteria
    ```yaml
-   stop_hooks:
-     - prompt_file: hooks/quality_check.md
+   hooks:
+     after_agent:
+       - prompt_file: hooks/quality_check.md
    ```
 
 3. **Script** (`script`) - For programmatic validation (tests, linting)
    ```yaml
-   stop_hooks:
-     - script: hooks/run_tests.sh
+   hooks:
+     after_agent:
+       - script: hooks/run_tests.sh
    ```
 
 **Multiple hooks can be combined:**
 ```yaml
-stop_hooks:
-  - script: hooks/lint_output.sh
-  - prompt: "Verify the content is comprehensive and well-organized"
+hooks:
+  after_agent:
+    - script: hooks/lint_output.sh
+    - prompt: "Verify the content is comprehensive and well-organized"
 ```
 
 **Encourage prompt-based hooks** - They leverage the AI's ability to understand context and make nuanced quality judgments. Script hooks are best for objective checks (syntax, format, tests).
@@ -343,7 +420,7 @@ Claude: Great! Creating the job.yml specification now...
 - .deepwork/jobs/competitive_research/job.yml
 
 **Next step:**
-Run `/deepwork_jobs.review_job_spec` to validate the specification against quality criteria.
+Implement the job to generate step instruction files.
 ```
 
 ## Important Guidelines
@@ -383,15 +460,5 @@ The complete YAML specification file (example shown in Step 5 above).
 After creating the file:
 1. Inform the user that the specification is complete
 2. Recommend that they review the job.yml file
-3. Tell them to run `/deepwork_jobs.review_job_spec` next
-
-## Quality Criteria
-
-- Asked structured questions to fully understand user requirements
-- User fully understands what job they're creating
-- All steps have clear inputs and outputs
-- Dependencies make logical sense
-- Summary is concise and descriptive
-- Description provides rich context for future refinement
-- Specification is valid YAML and follows the schema
-- Ready for implementation step
+3. Tell them the next step is to implement the job (generate step instruction files)
+