deepwork 0.5.1__py3-none-any.whl → 0.7.0a1__py3-none-any.whl

deepwork/standard_jobs/deepwork_jobs/job.yml

@@ -1,19 +1,53 @@
+# yaml-language-server: $schema=.deepwork/schemas/job.schema.json
 name: deepwork_jobs
-version: "0.9.0"
-summary: "Creates and manages multi-step AI workflows. Use when defining, implementing, or improving 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 and learn from running them.
+  workflows, test them on real use cases, and learn from running them.
 
-  The `define` command guides you through an interactive process to create a new job by
-  asking structured questions about your workflow, understanding each step's inputs and outputs,
-  and generating all necessary files.
+  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` command reflects on conversations where DeepWork jobs were run, identifies
+  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"
@@ -45,65 +79,73 @@ steps:
       - 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:
-      - "**User Understanding**: Did the agent fully understand the user's workflow by asking structured questions?"
-      - "**Structured Questions Used**: Did the agent ask structured questions (using the AskUserQuestion tool) to gather user input?"
-      - "**Document Detection**: For document-oriented workflows, did the agent detect patterns and offer doc spec creation?"
-      - "**doc spec Created (if applicable)**: If a doc spec was needed, was it created in `.deepwork/doc_specs/[doc_spec_name].md` with proper quality criteria?"
-      - "**doc spec References**: Are document outputs properly linked to their doc specs using `{file, doc_spec}` format?"
-      - "**Valid Against doc spec**: Does the job.yml conform to the job.yml doc spec quality criteria (valid identifier, semantic version, concise summary, rich description, complete steps, valid dependencies)?"
-      - "**Clear Inputs/Outputs**: Does every step have clearly defined inputs and outputs?"
-      - "**Logical Dependencies**: Do step dependencies make sense and avoid circular references?"
-      - "**Concise Summary**: Is the summary under 200 characters and descriptive?"
-      - "**Rich Description**: Does the description provide enough context for future refinement?"
-      - "**Valid Schema**: Does the job.yml follow the required schema (name, version, summary, steps)?"
-      - "**File Created**: Has the job.yml file been created in `.deepwork/jobs/[job_name]/job.yml`?"
+      - "**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: review_job_spec
-    name: "Review Job Specification"
-    description: "Reviews job.yml against quality criteria using a sub-agent for unbiased validation. Use after defining a job specification."
-    instructions_file: steps/review_job_spec.md
+  - 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:
-      - file: job.yml
-        doc_spec: .deepwork/doc_specs/job_spec.md
+      - test_feedback.md
     dependencies:
       - define
+      - implement
     quality_criteria:
-      - "**Sub-Agent Used**: Was a sub-agent spawned to provide unbiased review?"
-      - "**All doc spec Criteria Evaluated**: Did the sub-agent assess all 9 quality criteria?"
-      - "**Findings Addressed**: Were all failed criteria addressed by the main agent?"
-      - "**Validation Loop Complete**: Did the review-fix cycle continue until all criteria passed?"
+      - "**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: implement
-    name: "Implement Job Steps"
-    description: "Generates step instruction files and syncs slash commands from the job.yml specification. Use after job spec review passes."
-    instructions_file: steps/implement.md
+  - 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: review_job_spec
+        from_step: define
+      - file: steps/
+        from_step: implement
     outputs:
+      - job.yml
       - steps/
     dependencies:
-      - review_job_spec
+      - define
+      - implement
+      - test
     quality_criteria:
-      - "**Directory Structure**: Is `.deepwork/jobs/[job_name]/` created correctly?"
-      - "**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\"?"
-      - "**Sync Complete**: Has `deepwork sync` been run successfully?"
-      - "**Commands Available**: Are the slash-commands generated in `.claude/commands/`?"
-      - "**Rules Considered**: Has the agent thought about whether rules would benefit this job? If relevant rules were identified, did they explain them and offer to run `/deepwork_rules.define`? Not every job needs rules - only suggest when genuinely helpful."
+      - "**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
-    exposed: true
     inputs:
       - name: job_name
         description: "Name of the job that was run (optional - will auto-detect from conversation)"
@@ -122,4 +164,62 @@ steps:
       - "**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?"
-      - "**Sync Complete**: Has `deepwork sync` been run if instructions were modified?"
+
+  - 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/standard_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)
+

deepwork/standard_jobs/deepwork_jobs/steps/errata.md

@@ -0,0 +1,154 @@
+# Clean Up Errata
+
+## Objective
+
+Remove obsolete files and folders from prior DeepWork versions. This final step cleans up artifacts that are no longer used by the MCP-based system.
+
+## Task
+
+Identify and clean up deprecated files and folders.
+
+### Step 1: Remove Legacy Job Skill Folders
+
+Old DeepWork versions created individual skill folders for each job and step. These need to be removed while preserving the main `deepwork` skill folder.
+
+**Process:**
+
+1. **List all jobs** in `.deepwork/jobs/`:
+   ```bash
+   ls .deepwork/jobs/
+   ```
+
+2. **For each job**, kick off a sub-agent to find and remove legacy skill folders. The sub-agent should:
+   - Search in both `.claude/skills/` and `.gemini/skills/`
+   - Find folders matching:
+     - `{job_name}/` - folder named exactly like the job
+     - `{job_name}.*/` - folders starting with the job name followed by a period (e.g., `my_job.step1/`, `my_job.step2/`)
+   - Remove each matching folder
+   - Report what was removed
+
+   **Example commands for a job named `competitive_research`:**
+   ```bash
+   # Find and remove from .claude/skills/
+   rm -rf .claude/skills/competitive_research/ 2>/dev/null
+   rm -rf .claude/skills/competitive_research.*/ 2>/dev/null
+
+   # Find and remove from .gemini/skills/
+   rm -rf .gemini/skills/competitive_research/ 2>/dev/null
+   rm -rf .gemini/skills/competitive_research.*/ 2>/dev/null
+   ```
+
+3. **Run sub-agents in parallel** - one for each job to speed up the process.
+
+4. **Verify the `deepwork` skill folder remains:**
+   ```bash
+   ls -d .claude/skills/deepwork/ 2>/dev/null || echo "ERROR: deepwork skill missing!"
+   ls -d .gemini/skills/deepwork/ 2>/dev/null || echo "WARNING: gemini deepwork skill missing (may not have been installed)"
+   ```
+
+   **CRITICAL:** The `deepwork` skill folder in `.claude/skills/deepwork/` MUST still exist after cleanup. If it is missing, something went wrong - do NOT proceed and investigate what happened.
+
+**What this removes:**
+```
+.claude/skills/
+├── competitive_research/     <- REMOVE (legacy job folder)
+├── competitive_research.discover/  <- REMOVE (legacy step folder)
+├── competitive_research.analyze/   <- REMOVE (legacy step folder)
+├── deepwork/                 <- KEEP (current MCP entry point)
+└── some_other_job/           <- REMOVE (legacy job folder)
+```
+
+**Do NOT remove:**
+- `.claude/skills/deepwork/` - This is the current MCP-based skill entry point
+- `.gemini/skills/deepwork/` - Same for Gemini
+- Any skill folders that don't match job names in `.deepwork/jobs/`
+
+### Step 2: Clean Temp Files
+
+Check `.deepwork/tmp/` for accumulated temporary files:
+
+```bash
+ls -la .deepwork/tmp/ 2>/dev/null || echo "No tmp folder"
+```
+
+**Safe to delete:**
+- `.deepwork/tmp/rules/queue/*.json` - Old rules queue files
+- Any files older than 7 days
+- Empty subdirectories
+
+**Be careful with:**
+- Files that might be in-progress work
+- Anything with recent modification times
+
+```bash
+# Clean old queue files
+rm -rf .deepwork/tmp/rules/queue/*.json 2>/dev/null
+
+# Remove empty directories
+find .deepwork/tmp -type d -empty -delete 2>/dev/null
+```
+
+### Step 3: Remove Rules Folder (Fully Deprecated)
+
+DeepWork Rules have been completely removed from the system. Delete the `.deepwork/rules/` folder and all related items:
+
+```bash
+rm -rf .deepwork/rules/ 2>/dev/null
+rm -rf .deepwork/tmp/rules/ 2>/dev/null
+rm -rf .deepwork/jobs/deepwork_rules/ 2>/dev/null
+```
+
+### Step 4: Update Config Version
+
+Check `.deepwork/config.yml` for outdated version format:
+
+```bash
+cat .deepwork/config.yml
+```
+
+**Old format:**
+```yaml
+version: 1.0.0
+platforms:
+- claude
+```
+
+**Current format:**
+```yaml
+version: "1.0"
+platforms:
+  - claude
+```
+
+Update if needed to match current schema expectations.
+
+### Step 5: Remove Other Obsolete Files
+
+Check for and remove other obsolete files:
+
+| File/Pattern | Description | Action |
+|--------------|-------------|--------|
+| `.deepwork/.last_head_ref` | Git state tracking | Keep (used by MCP) |
+| `.deepwork/.last_work_tree` | Git state tracking | Keep (used by MCP) |
+| `.deepwork/.gitignore` | Ignore patterns | Review and update |
+| `.claude/commands/` | Generated commands | Keep (current system) |
+| `.claude/settings.local.json` | Local overrides | Keep (user settings) |
+
+### Step 6: Verify Git Status
+
+Check that the cleanup hasn't left untracked garbage:
+
+```bash
+git status
+```
+
+**Review:**
+- Deleted files should show as deleted
+- No new untracked files should appear (unless intentionally created)
+- Backup files (`.backup`) should be in `.gitignore` or cleaned up
+
+## Important Notes
+
+1. **Always back up before deleting** - User data is irreplaceable
+2. **Ask before destructive actions** - When in doubt, ask the user
+3. **Don't auto-commit** - Let the user review and commit changes themselves