diff --git a/.claude/settings.json b/.claude/settings.json
index cf4e3c4c..d296f9ae 100644
--- a/.claude/settings.json
+++ b/.claude/settings.json
@@ -130,7 +130,8 @@
"Bash(deepwork:*)",
"Bash(.claude/hooks/commit_job_git_commit.sh:*)",
"Bash(./.deepwork/jobs/deepwork_jobs/make_new_job.sh:*)",
- "WebSearch"
+ "WebSearch",
+ "Skill(deepwork_jobs.tools)"
]
},
"hooks": {
diff --git a/.claude/skills/deepwork_jobs.define/SKILL.md b/.claude/skills/deepwork_jobs.define/SKILL.md
index a6ec07d3..4d48e917 100644
--- a/.claude/skills/deepwork_jobs.define/SKILL.md
+++ b/.claude/skills/deepwork_jobs.define/SKILL.md
@@ -7,9 +7,9 @@ user-invocable: false
# deepwork_jobs.define
-**Step 1/3** in **new_job** workflow
+**Step 1/4** in **new_job** workflow
-> Create a new DeepWork job from scratch through definition, review, and implementation
+> Create a new DeepWork job from scratch through definition, review, tools verification, and implementation
> Creates and manages multi-step AI workflows. Use when defining, implementing, or improving DeepWork jobs.
@@ -424,7 +424,7 @@ workflows and learn from running them.
The `new_job` workflow guides you through defining and implementing a new job by
asking structured questions about your workflow, understanding each step's inputs and outputs,
-reviewing the specification, and generating all necessary files.
+reviewing the specification, verifying required techniques, and generating all necessary files.
The `learn` skill reflects on conversations where DeepWork jobs were run, identifies
confusion or inefficiencies, and improves job instructions. It also captures bespoke
@@ -668,7 +668,7 @@ Use a sub-agent (Haiku model) to review your work against these criteria:
## On Completion
1. Verify outputs are created
-2. Inform user: "new_job step 1/3 complete, outputs: job.yml"
+2. Inform user: "new_job step 1/4 complete, outputs: job.yml"
3. **Continue workflow**: Use Skill tool to invoke `/deepwork_jobs.review_job_spec`
---
diff --git a/.claude/skills/deepwork_jobs.implement/SKILL.md b/.claude/skills/deepwork_jobs.implement/SKILL.md
index c9510269..b74af104 100644
--- a/.claude/skills/deepwork_jobs.implement/SKILL.md
+++ b/.claude/skills/deepwork_jobs.implement/SKILL.md
@@ -1,15 +1,15 @@
---
name: deepwork_jobs.implement
-description: "Generates step instruction files and syncs slash commands from the job.yml specification. Use after job spec review passes."
+description: "Generates step instruction files and syncs slash commands from the job.yml specification. Use after tools verification passes."
user-invocable: false
---
# deepwork_jobs.implement
-**Step 3/3** in **new_job** workflow
+**Step 4/4** in **new_job** workflow
-> Create a new DeepWork job from scratch through definition, review, and implementation
+> Create a new DeepWork job from scratch through definition, review, tools verification, and implementation
> Creates and manages multi-step AI workflows. Use when defining, implementing, or improving DeepWork jobs.
@@ -17,43 +17,25 @@ user-invocable: false
Before proceeding, confirm these steps are complete:
- `/deepwork_jobs.review_job_spec`
+- `/deepwork_jobs.tools`
## Instructions
-**Goal**: Generates step instruction files and syncs slash commands from the job.yml specification. Use after job spec review passes.
+**Goal**: Generates step instruction files and syncs slash commands from the job.yml specification. Use after tools verification passes.
# Implement Job Steps
## Objective
-Generate the DeepWork job directory structure and instruction files for each step based on the validated `job.yml` specification from the review_job_spec step.
+Generate step instruction files for each step based on the validated `job.yml` specification from the review_job_spec step.
## Task
-Read the `job.yml` specification file and create all the necessary files to make the job functional, including directory structure and step instruction files. Then sync the commands to make them available.
+Read the `job.yml` specification file and create all the necessary step instruction files to make the job functional. Then sync the commands to make them available.
-### Step 1: Create Directory Structure Using Script
+**Note:** The `define` step already creates the directory structure using `make_new_job.sh`, so you don't need to create directories here.
-Run the `make_new_job.sh` script to create the standard directory structure:
-
-```bash
-.deepwork/jobs/deepwork_jobs/make_new_job.sh [job_name]
-```
-
-This creates:
-- `.deepwork/jobs/[job_name]/` - Main job directory
-- `.deepwork/jobs/[job_name]/steps/` - Step instruction files
-- `.deepwork/jobs/[job_name]/hooks/` - Custom validation scripts (with .gitkeep)
-- `.deepwork/jobs/[job_name]/templates/` - Example file formats (with .gitkeep)
-- `.deepwork/jobs/[job_name]/AGENTS.md` - Job management guidance
-
-**Note**: If the directory already exists (e.g., job.yml was created by define step), you can skip this step or manually create the additional directories:
-```bash
-mkdir -p .deepwork/jobs/[job_name]/hooks .deepwork/jobs/[job_name]/templates
-touch .deepwork/jobs/[job_name]/hooks/.gitkeep .deepwork/jobs/[job_name]/templates/.gitkeep
-```
-
-### Step 2: Read and Validate the Specification
+### Step 1: Read and Validate the Specification
1. **Locate the job.yml file**
- Read `.deepwork/jobs/[job_name]/job.yml` from the review_job_spec step
@@ -70,7 +52,7 @@ touch .deepwork/jobs/[job_name]/hooks/.gitkeep .deepwork/jobs/[job_name]/templat
- List of all steps with their details
- Understand the workflow structure
-### Step 3: Generate Step Instruction Files
+### Step 2: Generate Step Instruction Files
For each step in the job.yml, create a comprehensive instruction file at `.deepwork/jobs/[job_name]/steps/[step_id].md`.
@@ -94,6 +76,7 @@ For each step in the job.yml, create a comprehensive instruction file at `.deepw
5. **Quality over quantity** - Detailed, actionable instructions are better than vague ones
6. **Align with stop hooks** - If the step has `stop_hooks` defined, ensure the quality criteria in the instruction file match the validation criteria in the hooks
7. **Ask structured questions** - When a step has user inputs, the instructions MUST explicitly tell the agent to "ask structured questions" using the AskUserQuestion tool to gather that information. Never use generic phrasing like "ask the user" - always use "ask structured questions"
+8. **Reference techniques** - When a step requires external tools, include a reference to the relevant technique created in the `tools` step. See the section below on "Incorporating Techniques"
### Handling Stop Hooks
@@ -133,11 +116,55 @@ Step instructions can include additional `.md` files in the `steps/` directory f
See `.deepwork/jobs/deepwork_jobs/steps/supplemental_file_references.md` for detailed documentation and examples.
-### Step 4: Verify job.yml Location
+### Incorporating Techniques
+
+The `tools` step (which runs before `implement`) creates reusable techniques in `.deepwork/techniques/`. When generating step instructions, **reference these techniques** for any step that requires external tools.
+
+Techniques are synced to platform skill directories with a `dwt_` prefix (e.g., `making_pdfs` becomes `/dwt_making_pdfs`), so agents can invoke them directly.
+
+**How to incorporate techniques:**
+
+1. **Check what techniques exist:**
+ ```bash
+ ls .deepwork/techniques/
+ ```
+
+2. **Reference relevant techniques in step instructions:**
+ When a step uses an external tool (e.g., PDF generation, image processing), add a reference like:
+
+ ```markdown
+ ## Required Techniques
+
+ This step requires external tools. Use the following techniques:
+ - `/dwt_making_pdfs` - How to generate PDF output
+ - `/dwt_resizing_images` - How to resize and optimize images
+
+ See `.deepwork/techniques/[technique_name]/SKILL.md` for detailed usage instructions.
+ ```
+
+3. **Include key commands inline when helpful:**
+ For frequently-used commands, you can quote the essential invocation from the technique:
+
+ ```markdown
+ To convert markdown to PDF, use:
+ ```bash
+ pandoc input.md -o output.pdf --pdf-engine=xelatex
+ ```
+ See `/dwt_making_pdfs` (or `.deepwork/techniques/making_pdfs/SKILL.md`) for full documentation and troubleshooting.
+ ```
+
+**Why this matters:**
+- Step instructions stay focused on workflow logic
+- Techniques are documented once and synced to all platforms
+- Agents can invoke techniques directly as skills (e.g., `/dwt_making_pdfs`)
+- If techniques change, only the `.deepwork/techniques/` folder needs updating
+- New users can refer to technique SKILL.md files for installation help
+
+### Step 3: Verify job.yml Location
Verify that `job.yml` is in the correct location at `.deepwork/jobs/[job_name]/job.yml`. The define and review_job_spec steps should have created and validated it. If for some reason it's not there, you may need to create or move it.
-### Step 5: Sync Skills
+### Step 4: Sync Skills
Run `deepwork sync` to generate the skills for this job:
@@ -150,11 +177,11 @@ This will:
- Generate skills for each step
- Make the skills available in `.claude/skills/` (or appropriate platform directory)
-### Step 6: Relay Reload Instructions
+### Step 5: Relay Reload Instructions
After running `deepwork sync`, look at the "To use the new skills" section in the output. **Relay these exact reload instructions to the user** so they know how to pick up the new skills. Don't just reference the sync output - tell them directly what they need to do (e.g., "Type 'exit' then run 'claude --resume'" for Claude Code, or "Run '/memory refresh'" for Gemini CLI).
-### Step 7: Consider Rules for the New Job
+### Step 6: Consider Rules for the New Job
After implementing the job, consider whether there are **rules** that would help enforce quality or consistency when working with this job's domain.
@@ -243,10 +270,11 @@ Before marking this step complete, ensure:
- [ ] job.yml validated and copied to job directory
- [ ] All step instruction files created
- [ ] Each instruction file is complete and actionable
+- [ ] Steps requiring external tools reference techniques from `.deepwork/techniques/`
- [ ] `deepwork sync` executed successfully
- [ ] Skills generated in platform directory
- [ ] User informed to follow reload instructions from `deepwork sync`
-- [ ] Considered whether rules would benefit this job (Step 7)
+- [ ] Considered whether rules would benefit this job (Step 6)
- [ ] If rules suggested, offered to run `/deepwork_rules.define`
## Quality Criteria
@@ -257,6 +285,7 @@ Before marking this step complete, ensure:
- Output examples are provided in each instruction file
- Quality criteria defined for each step
- Steps with user inputs explicitly use "ask structured questions" phrasing
+- Steps requiring external tools reference the appropriate techniques from `.deepwork/techniques/`
- Sync completed successfully
- Skills available for use
- Thoughtfully considered relevant rules for the job domain
@@ -269,7 +298,7 @@ workflows and learn from running them.
The `new_job` workflow guides you through defining and implementing a new job by
asking structured questions about your workflow, understanding each step's inputs and outputs,
-reviewing the specification, and generating all necessary files.
+reviewing the specification, verifying required techniques, and generating all necessary files.
The `learn` skill reflects on conversations where DeepWork jobs were run, identifies
confusion or inefficiencies, and improves job instructions. It also captures bespoke
@@ -314,9 +343,10 @@ Use a sub-agent (Haiku model) to review your work against these criteria:
4. **Output Examples**: Does each instruction file show what good output looks like?
5. **Quality Criteria**: Does each instruction file define quality criteria for its outputs?
6. **Ask Structured Questions**: Do step instructions that gather user input explicitly use the phrase "ask structured questions"?
-7. **Sync Complete**: Has `deepwork sync` been run successfully?
-8. **Commands Available**: Are the slash-commands generated in `.claude/commands/`?
-9. **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.
+7. **Techniques Referenced**: Do steps requiring external tools reference the appropriate techniques from `.deepwork/techniques/`?
+8. **Sync Complete**: Has `deepwork sync` been run successfully?
+9. **Commands Available**: Are the slash-commands generated in `.claude/commands/`?
+10. **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.
**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
@@ -327,7 +357,7 @@ Use a sub-agent (Haiku model) to review your work against these criteria:
## On Completion
1. Verify outputs are created
-2. Inform user: "new_job step 3/3 complete, outputs: steps/"
+2. Inform user: "new_job step 4/4 complete, outputs: steps/"
3. **new_job workflow complete**: All steps finished. Consider creating a PR to merge the work branch.
---
diff --git a/.claude/skills/deepwork_jobs.learn/SKILL.md b/.claude/skills/deepwork_jobs.learn/SKILL.md
index f2db5a56..8eccbb33 100644
--- a/.claude/skills/deepwork_jobs.learn/SKILL.md
+++ b/.claude/skills/deepwork_jobs.learn/SKILL.md
@@ -1,6 +1,6 @@
---
name: deepwork_jobs.learn
-description: "Analyzes conversation history to improve job instructions and capture learnings. Use after running a job to refine it."
+description: "Analyzes conversation history to improve job instructions, techniques, and capture learnings. Use after running a job to refine it."
---
@@ -13,7 +13,7 @@ description: "Analyzes conversation history to improve job instructions and capt
## Instructions
-**Goal**: Analyzes conversation history to improve job instructions and capture learnings. Use after running a job to refine it.
+**Goal**: Analyzes conversation history to improve job instructions, techniques, and capture learnings. Use after running a job to refine it.
# Learn from Job Execution
@@ -92,6 +92,16 @@ For each learning identified, determine if it is:
- "Quality criterion 'Visualization' needs clearer requirements"
- "Documents need a section for action items"
+**Technique-Related** (should improve or create techniques):
+- Improvements to how external tools are used
+- Better installation or usage instructions
+- New tools discovered during execution
+- Workarounds or troubleshooting tips
+- Examples:
+ - "The PDF generation command needs an extra flag for better formatting"
+ - "Found a better tool for web scraping that handles dynamic content"
+ - "Installation steps needed adjustment for macOS"
+
**Bespoke** (should go in AGENTS.md):
- Specific to THIS project/codebase/run
- Depends on local conventions or structure
@@ -214,6 +224,73 @@ quality_criteria:
description: Include Mermaid.js charts showing spend breakdown by service and month-over-month trend
```
+### Step 4.6: Create/Update Techniques (Technique-Related Learnings)
+
+If technique-related learnings were identified, update or create techniques in `.deepwork/techniques/`:
+
+1. **For existing techniques** (update):
+ - Locate the technique folder: `.deepwork/techniques/[technique_name]/`
+ - Update the `SKILL.md` file with improvements:
+ - Better usage examples
+ - Additional command-line options
+ - Troubleshooting tips discovered during execution
+ - Workarounds for edge cases
+
+2. **For new techniques** (create):
+ - Create a new folder: `.deepwork/techniques/[technique_name]/`
+ - Create a `SKILL.md` file following the Claude Skills format:
+ ```markdown
+ ---
+ name: technique_name
+ description: "Brief description of what this technique accomplishes"
+ ---
+
+ # Technique Name
+
+ ## Purpose
+ What this technique accomplishes and when to use it.
+
+ ## Tool
+ - **Name**: Tool name
+ - **Type**: CLI tool / MCP server / Browser extension / API
+ - **Version**: Known working version
+
+ ## Installation
+ [Installation instructions for different platforms]
+
+ ## Verification
+ [How to verify the tool is working]
+
+ ## Usage
+ [Usage examples and common options]
+
+ ## Troubleshooting
+ [Common issues and solutions]
+
+ ## Alternatives Considered
+ [Other tools that were considered]
+ ```
+ - Include any helper scripts or assets in the technique folder
+
+3. **After updating/creating techniques**, run `deepwork sync` to sync them to platform skill directories with the `dwt_` prefix.
+
+**Example technique update:**
+```markdown
+# Before (in SKILL.md)
+## Usage
+```bash
+pandoc input.md -o output.pdf
+```
+
+# After (improved based on learnings)
+## Usage
+```bash
+pandoc input.md -o output.pdf --pdf-engine=xelatex -V geometry:margin=1in
+```
+
+**Note**: The `--pdf-engine=xelatex` flag is required for Unicode support. The margin setting prevents text from running off the page.
+```
+
### Step 5: Create/Update AGENTS.md (Bespoke Learnings)
The AGENTS.md file captures project-specific knowledge that helps future agent runs.
@@ -281,13 +358,15 @@ When adding entries to AGENTS.md, prefer these patterns:
- Conversation has been analyzed for job executions
- Points of confusion and inefficiency are identified
-- Learnings are correctly classified (generalizable vs bespoke)
+- Learnings are correctly classified (generalizable vs technique-related vs bespoke)
- Job instructions updated for generalizable improvements
- Instructions are concise - no redundancy or unnecessary verbosity
- Shared/lengthy content extracted into referenced files where appropriate
+- Techniques created/updated for technique-related improvements
- AGENTS.md created/updated with bespoke learnings
- File references used instead of duplicating content
- AGENTS.md is in the correct folder (the deepest common folder for the topic)
+- `deepwork sync` run if instructions or techniques were modified
- When all criteria are met, include `✓ Quality Criteria Met`
## Example Dialog
@@ -381,7 +460,7 @@ workflows and learn from running them.
The `new_job` workflow guides you through defining and implementing a new job by
asking structured questions about your workflow, understanding each step's inputs and outputs,
-reviewing the specification, and generating all necessary files.
+reviewing the specification, verifying required techniques, and generating all necessary files.
The `learn` skill reflects on conversations where DeepWork jobs were run, identifies
confusion or inefficiencies, and improves job instructions. It also captures bespoke
@@ -405,6 +484,7 @@ Use branch format: `deepwork/deepwork_jobs-[instance]-YYYYMMDD`
**Required outputs**:
- `AGENTS.md`
+- `.deepwork/techniques/` (directory)
## Guardrails
@@ -422,16 +502,18 @@ Use a sub-agent (Haiku model) to review your work against these criteria:
**Criteria (all must be satisfied)**:
1. **Conversation Analyzed**: Did the agent review the conversation for DeepWork job executions?
2. **Confusion Identified**: Did the agent identify points of confusion, errors, or inefficiencies?
-3. **Instructions Improved**: Were job instructions updated to address identified issues?
-4. **Instructions Concise**: Are instructions free of redundancy and unnecessary verbosity?
-5. **Shared Content Extracted**: Is lengthy/duplicated content extracted into referenced files?
-6. **doc spec Reviewed (if applicable)**: For jobs with doc spec outputs, were doc spec-related learnings identified?
-7. **doc spec Updated (if applicable)**: Were doc spec files updated with improved quality criteria or structure?
-8. **Bespoke Learnings Captured**: Were run-specific learnings added to AGENTS.md?
-9. **File References Used**: Do AGENTS.md entries reference other files where appropriate?
-10. **Working Folder Correct**: Is AGENTS.md in the correct working folder for the job?
-11. **Generalizable Separated**: Are generalizable improvements in instructions, not AGENTS.md?
-12. **Sync Complete**: Has `deepwork sync` been run if instructions were modified?
+3. **Learnings Classified**: Were learnings classified as generalizable, technique-related, or bespoke?
+4. **Instructions Improved**: Were job instructions updated to address identified issues?
+5. **Instructions Concise**: Are instructions free of redundancy and unnecessary verbosity?
+6. **Shared Content Extracted**: Is lengthy/duplicated content extracted into referenced files?
+7. **doc spec Reviewed (if applicable)**: For jobs with doc spec outputs, were doc spec-related learnings identified?
+8. **doc spec Updated (if applicable)**: Were doc spec files updated with improved quality criteria or structure?
+9. **Techniques Created/Updated (if applicable)**: Were new techniques created or existing ones improved based on tool usage learnings?
+10. **Bespoke Learnings Captured**: Were run-specific learnings added to AGENTS.md?
+11. **File References Used**: Do AGENTS.md entries reference other files where appropriate?
+12. **Working Folder Correct**: Is AGENTS.md in the correct working folder for the job?
+13. **Generalizable Separated**: Are generalizable improvements in instructions, not AGENTS.md?
+14. **Sync Complete**: Has `deepwork sync` been run if instructions or techniques were modified?
**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
@@ -442,7 +524,7 @@ Use a sub-agent (Haiku model) to review your work against these criteria:
## On Completion
1. Verify outputs are created
-2. Inform user: "learn complete, outputs: AGENTS.md"
+2. Inform user: "learn complete, outputs: AGENTS.md, .deepwork/techniques/"
This standalone skill can be re-run anytime.
diff --git a/.claude/skills/deepwork_jobs.review_job_spec/SKILL.md b/.claude/skills/deepwork_jobs.review_job_spec/SKILL.md
index 99a565ef..a59bf374 100644
--- a/.claude/skills/deepwork_jobs.review_job_spec/SKILL.md
+++ b/.claude/skills/deepwork_jobs.review_job_spec/SKILL.md
@@ -7,9 +7,9 @@ user-invocable: false
# deepwork_jobs.review_job_spec
-**Step 2/3** in **new_job** workflow
+**Step 2/4** in **new_job** workflow
-> Create a new DeepWork job from scratch through definition, review, and implementation
+> Create a new DeepWork job from scratch through definition, review, tools verification, and implementation
> Creates and manages multi-step AI workflows. Use when defining, implementing, or improving DeepWork jobs.
@@ -239,7 +239,7 @@ workflows and learn from running them.
The `new_job` workflow guides you through defining and implementing a new job by
asking structured questions about your workflow, understanding each step's inputs and outputs,
-reviewing the specification, and generating all necessary files.
+reviewing the specification, verifying required techniques, and generating all necessary files.
The `learn` skill reflects on conversations where DeepWork jobs were run, identifies
confusion or inefficiencies, and improves job instructions. It also captures bespoke
@@ -475,8 +475,8 @@ Use a sub-agent (Haiku model) to review your work against these criteria:
## On Completion
1. Verify outputs are created
-2. Inform user: "new_job step 2/3 complete, outputs: job.yml"
-3. **Continue workflow**: Use Skill tool to invoke `/deepwork_jobs.implement`
+2. Inform user: "new_job step 2/4 complete, outputs: job.yml"
+3. **Continue workflow**: Use Skill tool to invoke `/deepwork_jobs.tools`
---
diff --git a/.claude/skills/deepwork_jobs.tools/SKILL.md b/.claude/skills/deepwork_jobs.tools/SKILL.md
new file mode 100644
index 00000000..34ddfbc1
--- /dev/null
+++ b/.claude/skills/deepwork_jobs.tools/SKILL.md
@@ -0,0 +1,307 @@
+---
+name: deepwork_jobs.tools
+description: "Verifies required techniques are available and documents how to use them. Use after job spec review to ensure implementation can succeed."
+user-invocable: false
+
+---
+
+# deepwork_jobs.tools
+
+**Step 3/4** in **new_job** workflow
+
+> Create a new DeepWork job from scratch through definition, review, tools verification, and implementation
+
+> Creates and manages multi-step AI workflows. Use when defining, implementing, or improving DeepWork jobs.
+
+## Prerequisites (Verify First)
+
+Before proceeding, confirm these steps are complete:
+- `/deepwork_jobs.review_job_spec`
+
+## Instructions
+
+**Goal**: Verifies required techniques are available and documents how to use them. Use after job spec review to ensure implementation can succeed.
+
+# Verify and Document Techniques
+
+## Objective
+
+Verify that all external tools and capabilities required by the job are available and working, find alternatives if needed, and create reusable **techniques** for future reference.
+
+## Task
+
+Analyze the job specification to determine what techniques are needed, then spawn parallel sub-agents to test, configure, and document each technique.
+
+### Step 1: Analyze the Job for Required Techniques
+
+Read the `job.yml` file and examine each step to identify tasks that require external tools or capabilities beyond the agent's built-in abilities.
+
+**Look for steps that involve:**
+- File format conversion (PDF, DOCX, HTML, etc.)
+- Data processing (CSV, JSON, XML transformations)
+- Media manipulation (images, audio, video)
+- Web browsing or site access (via browser extensions like Chrome MCP)
+- External API calls or web requests
+- Build processes (compilers, bundlers)
+- Testing frameworks
+- Database operations
+- Container or virtualization tools
+
+**Types of tools and capabilities to consider:**
+- **CLI tools**: Command-line programs (pandoc, ffmpeg, imagemagick, etc.)
+- **MCP servers**: Model Context Protocol servers that extend agent capabilities (browser control, database access, etc.)
+- **Browser extensions**: Chrome extensions or similar for web interaction
+- **Language runtimes**: Python, Node.js, Ruby, etc. with specific packages
+- **External services**: APIs that require authentication or setup
+
+**For each step, create a requirements list:**
+- What the step needs to accomplish
+- What external tools or capabilities might be required
+- What the expected input/output formats are
+
+### Step 2: Spawn Parallel Sub-Agents for Each Technique
+
+For each technique you identified, spawn a sub-agent **in parallel** to handle testing and documentation. This allows all techniques to be verified concurrently.
+
+**Sub-agent prompt template (customize for each technique):**
+
+```
+You are verifying and documenting a technique for the "[TECHNIQUE_NAME]" process in a DeepWork job.
+
+## Technique Requirement
+
+[Describe what this specific technique needs to accomplish]
+
+## Your Tasks
+
+1. **Test if a tool exists** - Check if a tool is available that can accomplish this technique
+2. **Verify it works** - Run a simple test to confirm functionality
+3. **Find alternatives if needed** - If the tool is missing or broken, research and test alternatives until you have a working solution
+4. **Create the technique** - Create a folder in `.deepwork/techniques/[technique_name]/` with:
+ - `SKILL.md` - The main technique skill file following the Claude Skills format:
+ ```markdown
+ ---
+ name: technique_name
+ description: "Brief description of what this technique accomplishes"
+ ---
+
+ # Technique Name
+
+ ## Purpose
+ What this technique accomplishes and when to use it.
+
+ ## Tool
+ - **Name**: Tool name (e.g., pandoc, playwright)
+ - **Type**: CLI tool / MCP server / Browser extension / API
+ - **Version**: Known working version
+
+ ## Installation
+
+ ### macOS
+ ```bash
+ brew install tool-name
+ ```
+
+ ### Ubuntu/Debian
+ ```bash
+ apt-get install tool-name
+ ```
+
+ ### pip/npm (if applicable)
+ ```bash
+ pip install tool-name
+ ```
+
+ ## Verification
+ ```bash
+ tool-name --version
+ ```
+
+ ## Usage
+
+ ### Basic Example
+ ```bash
+ tool-name input.md -o output.pdf
+ ```
+
+ ### Common Options
+ - `-o, --output`: Output file path
+ - Other relevant options...
+
+ ## Troubleshooting
+ Common issues and solutions.
+
+ ## Alternatives Considered
+ - Alternative 1: Why not chosen
+ - Alternative 2: Why not chosen
+ ```
+ - Any helper scripts or assets the technique needs (e.g., `convert.py`, `template.html`)
+
+## Output Location
+
+Create the technique in: `.deepwork/techniques/[technique_name]/`
+
+Use descriptive, process-focused names like `making_pdfs`, `accessing_websites`, `creating_charts` (NOT tool names like `pandoc`, `playwright`).
+
+## Success Criteria
+
+- The technique has a working tool
+- Created `.deepwork/techniques/[technique_name]/SKILL.md`
+- Included any necessary helper scripts or assets in the same folder
+```
+
+**Example:** If you identified 3 techniques (making PDFs, accessing websites, creating charts), spawn 3 sub-agents in parallel:
+- Sub-agent 1: "making_pdfs" technique
+- Sub-agent 2: "accessing_websites" technique
+- Sub-agent 3: "creating_charts" technique
+
+### Step 3: Review Sub-Agent Outputs
+
+After all sub-agents complete:
+
+1. **Verify all techniques are covered** - Check that each identified need has a technique folder
+2. **Spot-check the documentation** - Ensure the SKILL.md files are complete and accurate
+3. **Verify tools work together** - If techniques depend on each other, confirm compatibility
+
+### Step 4: Run Sync
+
+After all techniques are created, run `deepwork sync` to copy them to the platform skill directories (`.claude/skills/`, `.gemini/skills/`) with the `dwt_` prefix.
+
+## Example
+
+For a job that creates research reports from web sources:
+
+**Step 1 output (your analysis):**
+```
+Required techniques:
+1. Accessing websites - Need to browse and extract data from web pages
+2. Creating charts - Need to generate visualizations from data
+3. Making PDFs - Need to convert markdown reports to PDF format
+```
+
+**Step 2:** Spawn 3 parallel sub-agents, one for each technique
+
+**Step 3:** Verify all sub-agents created their techniques:
+```
+.deepwork/techniques/
+├── accessing_websites/
+│ └── SKILL.md
+├── creating_charts/
+│ ├── SKILL.md
+│ └── chart_helper.py
+└── making_pdfs/
+ └── SKILL.md
+```
+
+**Step 4:** Run `deepwork sync` to sync techniques to platforms
+
+## Output
+
+After completing this step, you should have:
+
+1. **techniques/ directory** with technique folders:
+ ```
+ .deepwork/techniques/
+ ├── [technique_1]/
+ │ ├── SKILL.md
+ │ └── [optional assets]
+ ├── [technique_2]/
+ │ ├── SKILL.md
+ │ └── [optional assets]
+ └── ...
+ ```
+
+2. **Synced skills** in platform directories (after running `deepwork sync`):
+ ```
+ .claude/skills/
+ ├── dwt_[technique_1]/
+ │ └── SKILL.md
+ └── dwt_[technique_2]/
+ └── SKILL.md
+ ```
+
+3. **Confidence that all techniques work** and the job can be implemented successfully
+
+## Quality Criteria
+
+- All job steps have been analyzed for technique requirements
+- Parallel sub-agents were spawned for each technique requiring tooling
+- Every required tool has been tested and verified working
+- Each required technique has a working solution (original tool or alternative)
+- Techniques are organized by PROCESS name, not by tool name
+- Each technique folder contains a SKILL.md following the Claude Skills format
+- Helper scripts and assets are stored alongside SKILL.md in the technique folder
+- All techniques have been verified to work together
+- `deepwork sync` was run to sync techniques to platform skill directories
+- When all criteria are met, include `✓ Quality Criteria Met` in your response
+
+
+### Job Context
+
+Core commands for managing DeepWork jobs. These commands help you define new multi-step
+workflows and learn from running them.
+
+The `new_job` workflow guides you through defining and implementing a new job by
+asking structured questions about your workflow, understanding each step's inputs and outputs,
+reviewing the specification, verifying required techniques, and generating all necessary files.
+
+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.
+
+
+## Required Inputs
+
+
+**Files from Previous Steps** - Read these first:
+- `job.yml` (from `review_job_spec`)
+
+## Work Branch
+
+Use branch format: `deepwork/deepwork_jobs-[instance]-YYYYMMDD`
+
+- If on a matching work branch: continue using it
+- If on main/master: create new branch with `git checkout -b deepwork/deepwork_jobs-[instance]-$(date +%Y%m%d)`
+
+## Outputs
+
+**Required outputs**:
+- `.deepwork/techniques/` (directory)
+
+## 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
+
+## Quality Validation
+
+**Before completing this step, you MUST have your work reviewed against the quality criteria below.**
+
+Use a sub-agent (Haiku model) to review your work against these criteria:
+
+**Criteria (all must be satisfied)**:
+1. **Tasks Analyzed**: Were all job steps reviewed to identify required techniques (CLI tools, MCP servers, browser extensions, etc.)?
+2. **Parallel Sub-Agents**: Were parallel sub-agents spawned for each technique requiring tooling?
+3. **Had Working Technique**: Does each required technique have a working solution (original tool or alternative)?
+4. **Technique Created**: Was a technique folder created in `.deepwork/techniques/` for each technique (e.g., making_pdfs/, not pandoc/)?
+5. **SKILL.md Format**: Does each technique folder contain a SKILL.md file following the Claude Skills format?
+6. **Assets Included**: Are helper scripts and assets stored alongside SKILL.md in the technique folder?
+7. **Sync Complete**: Was `deepwork sync` run to sync techniques to platform skill directories?
+**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
+
+## On Completion
+
+1. Verify outputs are created
+2. Inform user: "new_job step 3/4 complete, outputs: .deepwork/techniques/"
+3. **Continue workflow**: Use Skill tool to invoke `/deepwork_jobs.implement`
+
+---
+
+**Reference files**: `.deepwork/jobs/deepwork_jobs/job.yml`, `.deepwork/jobs/deepwork_jobs/steps/tools.md`
\ No newline at end of file
diff --git a/.claude/skills/deepwork_jobs/SKILL.md b/.claude/skills/deepwork_jobs/SKILL.md
index ec2526f5..b95fa840 100644
--- a/.claude/skills/deepwork_jobs/SKILL.md
+++ b/.claude/skills/deepwork_jobs/SKILL.md
@@ -14,7 +14,7 @@ workflows and learn from running them.
The `new_job` workflow guides you through defining and implementing a new job by
asking structured questions about your workflow, understanding each step's inputs and outputs,
-reviewing the specification, and generating all necessary files.
+reviewing the specification, verifying required techniques, and generating all necessary files.
The `learn` skill reflects on conversations where DeepWork jobs were run, identifies
confusion or inefficiencies, and improves job instructions. It also captures bespoke
@@ -25,12 +25,13 @@ learnings specific to the current run into AGENTS.md files in the working folder
### new_job
-Create a new DeepWork job from scratch through definition, review, and implementation
+Create a new DeepWork job from scratch through definition, review, tools verification, and implementation
**Steps in order**:
1. **define** - Creates a job.yml specification by gathering workflow requirements through structured questions. Use when starting a new multi-step workflow.
2. **review_job_spec** - Reviews job.yml against quality criteria using a sub-agent for unbiased validation. Use after defining a job specification.
-3. **implement** - Generates step instruction files and syncs slash commands from the job.yml specification. Use after job spec review passes.
+3. **tools** - Verifies required techniques are available and documents how to use them. Use after job spec review to ensure implementation can succeed.
+4. **implement** - Generates step instruction files and syncs slash commands from the job.yml specification. Use after tools verification passes.
**Start workflow**: `/deepwork_jobs.define`
@@ -38,7 +39,7 @@ Create a new DeepWork job from scratch through definition, review, and implement
These skills can be run independently at any time:
-- **learn** - Analyzes conversation history to improve job instructions and capture learnings. Use after running a job to refine it.
+- **learn** - Analyzes conversation history to improve job instructions, techniques, and capture learnings. Use after running a job to refine it.
Command: `/deepwork_jobs.learn`
diff --git a/.deepwork/jobs/deepwork_jobs/job.yml b/.deepwork/jobs/deepwork_jobs/job.yml
index 1cb38621..59222ac4 100644
--- a/.deepwork/jobs/deepwork_jobs/job.yml
+++ b/.deepwork/jobs/deepwork_jobs/job.yml
@@ -1,5 +1,5 @@
name: deepwork_jobs
-version: "1.0.0"
+version: "1.1.0"
summary: "Creates and manages multi-step AI workflows. Use when defining, implementing, or improving DeepWork jobs."
description: |
Core commands for managing DeepWork jobs. These commands help you define new multi-step
@@ -7,7 +7,7 @@ description: |
The `new_job` workflow guides you through defining and implementing a new job by
asking structured questions about your workflow, understanding each step's inputs and outputs,
- reviewing the specification, and generating all necessary files.
+ reviewing the specification, verifying required techniques, and generating all necessary files.
The `learn` skill reflects on conversations where DeepWork jobs were run, identifies
confusion or inefficiencies, and improves job instructions. It also captures bespoke
@@ -15,13 +15,16 @@ description: |
workflows:
- name: new_job
- summary: "Create a new DeepWork job from scratch through definition, review, and implementation"
+ summary: "Create a new DeepWork job from scratch through definition, review, tools verification, and implementation"
steps:
- define
- review_job_spec
+ - tools
- implement
changelog:
+ - version: "1.1.0"
+ changes: "Added tools step to new_job workflow for verifying and documenting techniques; implement step no longer creates directory structure (define does this)"
- 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"
@@ -87,9 +90,29 @@ steps:
- "**Findings Addressed**: Were all failed criteria addressed by the main agent?"
- "**Validation Loop Complete**: Did the review-fix cycle continue until all criteria passed?"
+ - id: tools
+ name: "Verify and Document Techniques"
+ description: "Verifies required techniques are available and documents how to use them. Use after job spec review to ensure implementation can succeed."
+ instructions_file: steps/tools.md
+ inputs:
+ - file: job.yml
+ from_step: review_job_spec
+ outputs:
+ - .deepwork/techniques/
+ dependencies:
+ - review_job_spec
+ quality_criteria:
+ - "**Tasks Analyzed**: Were all job steps reviewed to identify required techniques (CLI tools, MCP servers, browser extensions, etc.)?"
+ - "**Parallel Sub-Agents**: Were parallel sub-agents spawned for each technique requiring tooling?"
+ - "**Had Working Technique**: Does each required technique have a working solution (original tool or alternative)?"
+ - "**Technique Created**: Was a technique folder created in `.deepwork/techniques/` for each technique (e.g., making_pdfs/, not pandoc/)?"
+ - "**SKILL.md Format**: Does each technique folder contain a SKILL.md file following the Claude Skills format?"
+ - "**Assets Included**: Are helper scripts and assets stored alongside SKILL.md in the technique folder?"
+ - "**Sync Complete**: Was `deepwork sync` run to sync techniques to platform skill directories?"
+
- 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."
+ description: "Generates step instruction files and syncs slash commands from the job.yml specification. Use after tools verification passes."
instructions_file: steps/implement.md
inputs:
- file: job.yml
@@ -98,6 +121,7 @@ steps:
- steps/
dependencies:
- review_job_spec
+ - tools
quality_criteria:
- "**Directory Structure**: Is `.deepwork/jobs/[job_name]/` created correctly?"
- "**Complete Instructions**: Are ALL step instruction files complete (not stubs or placeholders)?"
@@ -105,13 +129,14 @@ steps:
- "**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\"?"
+ - "**Techniques Referenced**: Do steps requiring external tools reference the appropriate techniques from `.deepwork/techniques/`?"
- "**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."
- 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."
+ description: "Analyzes conversation history to improve job instructions, techniques, and capture learnings. Use after running a job to refine it."
instructions_file: steps/learn.md
exposed: true
inputs:
@@ -119,17 +144,20 @@ steps:
description: "Name of the job that was run (optional - will auto-detect from conversation)"
outputs:
- AGENTS.md
+ - .deepwork/techniques/
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?"
+ - "**Learnings Classified**: Were learnings classified as generalizable, technique-related, or bespoke?"
- "**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?"
+ - "**Techniques Created/Updated (if applicable)**: Were new techniques created or existing ones improved based on tool usage learnings?"
- "**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?"
- - "**Sync Complete**: Has `deepwork sync` been run if instructions were modified?"
+ - "**Sync Complete**: Has `deepwork sync` been run if instructions or techniques were modified?"
diff --git a/.deepwork/jobs/deepwork_jobs/steps/implement.md b/.deepwork/jobs/deepwork_jobs/steps/implement.md
index bf1683b1..d4dc81d6 100644
--- a/.deepwork/jobs/deepwork_jobs/steps/implement.md
+++ b/.deepwork/jobs/deepwork_jobs/steps/implement.md
@@ -2,34 +2,15 @@
## Objective
-Generate the DeepWork job directory structure and instruction files for each step based on the validated `job.yml` specification from the review_job_spec step.
+Generate step instruction files for each step based on the validated `job.yml` specification from the review_job_spec step.
## Task
-Read the `job.yml` specification file and create all the necessary files to make the job functional, including directory structure and step instruction files. Then sync the commands to make them available.
+Read the `job.yml` specification file and create all the necessary step instruction files to make the job functional. Then sync the commands to make them available.
-### Step 1: Create Directory Structure Using Script
+**Note:** The `define` step already creates the directory structure using `make_new_job.sh`, so you don't need to create directories here.
-Run the `make_new_job.sh` script to create the standard directory structure:
-
-```bash
-.deepwork/jobs/deepwork_jobs/make_new_job.sh [job_name]
-```
-
-This creates:
-- `.deepwork/jobs/[job_name]/` - Main job directory
-- `.deepwork/jobs/[job_name]/steps/` - Step instruction files
-- `.deepwork/jobs/[job_name]/hooks/` - Custom validation scripts (with .gitkeep)
-- `.deepwork/jobs/[job_name]/templates/` - Example file formats (with .gitkeep)
-- `.deepwork/jobs/[job_name]/AGENTS.md` - Job management guidance
-
-**Note**: If the directory already exists (e.g., job.yml was created by define step), you can skip this step or manually create the additional directories:
-```bash
-mkdir -p .deepwork/jobs/[job_name]/hooks .deepwork/jobs/[job_name]/templates
-touch .deepwork/jobs/[job_name]/hooks/.gitkeep .deepwork/jobs/[job_name]/templates/.gitkeep
-```
-
-### Step 2: Read and Validate the Specification
+### Step 1: Read and Validate the Specification
1. **Locate the job.yml file**
- Read `.deepwork/jobs/[job_name]/job.yml` from the review_job_spec step
@@ -46,7 +27,7 @@ touch .deepwork/jobs/[job_name]/hooks/.gitkeep .deepwork/jobs/[job_name]/templat
- List of all steps with their details
- Understand the workflow structure
-### Step 3: Generate Step Instruction Files
+### Step 2: Generate Step Instruction Files
For each step in the job.yml, create a comprehensive instruction file at `.deepwork/jobs/[job_name]/steps/[step_id].md`.
@@ -70,6 +51,7 @@ For each step in the job.yml, create a comprehensive instruction file at `.deepw
5. **Quality over quantity** - Detailed, actionable instructions are better than vague ones
6. **Align with stop hooks** - If the step has `stop_hooks` defined, ensure the quality criteria in the instruction file match the validation criteria in the hooks
7. **Ask structured questions** - When a step has user inputs, the instructions MUST explicitly tell the agent to "ask structured questions" using the AskUserQuestion tool to gather that information. Never use generic phrasing like "ask the user" - always use "ask structured questions"
+8. **Reference techniques** - When a step requires external tools, include a reference to the relevant technique created in the `tools` step. See the section below on "Incorporating Techniques"
### Handling Stop Hooks
@@ -109,11 +91,55 @@ Step instructions can include additional `.md` files in the `steps/` directory f
See `.deepwork/jobs/deepwork_jobs/steps/supplemental_file_references.md` for detailed documentation and examples.
-### Step 4: Verify job.yml Location
+### Incorporating Techniques
+
+The `tools` step (which runs before `implement`) creates reusable techniques in `.deepwork/techniques/`. When generating step instructions, **reference these techniques** for any step that requires external tools.
+
+Techniques are synced to platform skill directories with a `dwt_` prefix (e.g., `making_pdfs` becomes `/dwt_making_pdfs`), so agents can invoke them directly.
+
+**How to incorporate techniques:**
+
+1. **Check what techniques exist:**
+ ```bash
+ ls .deepwork/techniques/
+ ```
+
+2. **Reference relevant techniques in step instructions:**
+ When a step uses an external tool (e.g., PDF generation, image processing), add a reference like:
+
+ ```markdown
+ ## Required Techniques
+
+ This step requires external tools. Use the following techniques:
+ - `/dwt_making_pdfs` - How to generate PDF output
+ - `/dwt_resizing_images` - How to resize and optimize images
+
+ See `.deepwork/techniques/[technique_name]/SKILL.md` for detailed usage instructions.
+ ```
+
+3. **Include key commands inline when helpful:**
+ For frequently-used commands, you can quote the essential invocation from the technique:
+
+ ```markdown
+ To convert markdown to PDF, use:
+ ```bash
+ pandoc input.md -o output.pdf --pdf-engine=xelatex
+ ```
+ See `/dwt_making_pdfs` (or `.deepwork/techniques/making_pdfs/SKILL.md`) for full documentation and troubleshooting.
+ ```
+
+**Why this matters:**
+- Step instructions stay focused on workflow logic
+- Techniques are documented once and synced to all platforms
+- Agents can invoke techniques directly as skills (e.g., `/dwt_making_pdfs`)
+- If techniques change, only the `.deepwork/techniques/` folder needs updating
+- New users can refer to technique SKILL.md files for installation help
+
+### Step 3: Verify job.yml Location
Verify that `job.yml` is in the correct location at `.deepwork/jobs/[job_name]/job.yml`. The define and review_job_spec steps should have created and validated it. If for some reason it's not there, you may need to create or move it.
-### Step 5: Sync Skills
+### Step 4: Sync Skills
Run `deepwork sync` to generate the skills for this job:
@@ -126,11 +152,11 @@ This will:
- Generate skills for each step
- Make the skills available in `.claude/skills/` (or appropriate platform directory)
-### Step 6: Relay Reload Instructions
+### Step 5: Relay Reload Instructions
After running `deepwork sync`, look at the "To use the new skills" section in the output. **Relay these exact reload instructions to the user** so they know how to pick up the new skills. Don't just reference the sync output - tell them directly what they need to do (e.g., "Type 'exit' then run 'claude --resume'" for Claude Code, or "Run '/memory refresh'" for Gemini CLI).
-### Step 7: Consider Rules for the New Job
+### Step 6: Consider Rules for the New Job
After implementing the job, consider whether there are **rules** that would help enforce quality or consistency when working with this job's domain.
@@ -219,10 +245,11 @@ Before marking this step complete, ensure:
- [ ] job.yml validated and copied to job directory
- [ ] All step instruction files created
- [ ] Each instruction file is complete and actionable
+- [ ] Steps requiring external tools reference techniques from `.deepwork/techniques/`
- [ ] `deepwork sync` executed successfully
- [ ] Skills generated in platform directory
- [ ] User informed to follow reload instructions from `deepwork sync`
-- [ ] Considered whether rules would benefit this job (Step 7)
+- [ ] Considered whether rules would benefit this job (Step 6)
- [ ] If rules suggested, offered to run `/deepwork_rules.define`
## Quality Criteria
@@ -233,6 +260,7 @@ Before marking this step complete, ensure:
- Output examples are provided in each instruction file
- Quality criteria defined for each step
- Steps with user inputs explicitly use "ask structured questions" phrasing
+- Steps requiring external tools reference the appropriate techniques from `.deepwork/techniques/`
- Sync completed successfully
- Skills available for use
- Thoughtfully considered relevant rules for the job domain
diff --git a/.deepwork/jobs/deepwork_jobs/steps/learn.md b/.deepwork/jobs/deepwork_jobs/steps/learn.md
index 3fddf37d..d83a592e 100644
--- a/.deepwork/jobs/deepwork_jobs/steps/learn.md
+++ b/.deepwork/jobs/deepwork_jobs/steps/learn.md
@@ -75,6 +75,16 @@ For each learning identified, determine if it is:
- "Quality criterion 'Visualization' needs clearer requirements"
- "Documents need a section for action items"
+**Technique-Related** (should improve or create techniques):
+- Improvements to how external tools are used
+- Better installation or usage instructions
+- New tools discovered during execution
+- Workarounds or troubleshooting tips
+- Examples:
+ - "The PDF generation command needs an extra flag for better formatting"
+ - "Found a better tool for web scraping that handles dynamic content"
+ - "Installation steps needed adjustment for macOS"
+
**Bespoke** (should go in AGENTS.md):
- Specific to THIS project/codebase/run
- Depends on local conventions or structure
@@ -197,6 +207,73 @@ quality_criteria:
description: Include Mermaid.js charts showing spend breakdown by service and month-over-month trend
```
+### Step 4.6: Create/Update Techniques (Technique-Related Learnings)
+
+If technique-related learnings were identified, update or create techniques in `.deepwork/techniques/`:
+
+1. **For existing techniques** (update):
+ - Locate the technique folder: `.deepwork/techniques/[technique_name]/`
+ - Update the `SKILL.md` file with improvements:
+ - Better usage examples
+ - Additional command-line options
+ - Troubleshooting tips discovered during execution
+ - Workarounds for edge cases
+
+2. **For new techniques** (create):
+ - Create a new folder: `.deepwork/techniques/[technique_name]/`
+ - Create a `SKILL.md` file following the Claude Skills format:
+ ```markdown
+ ---
+ name: technique_name
+ description: "Brief description of what this technique accomplishes"
+ ---
+
+ # Technique Name
+
+ ## Purpose
+ What this technique accomplishes and when to use it.
+
+ ## Tool
+ - **Name**: Tool name
+ - **Type**: CLI tool / MCP server / Browser extension / API
+ - **Version**: Known working version
+
+ ## Installation
+ [Installation instructions for different platforms]
+
+ ## Verification
+ [How to verify the tool is working]
+
+ ## Usage
+ [Usage examples and common options]
+
+ ## Troubleshooting
+ [Common issues and solutions]
+
+ ## Alternatives Considered
+ [Other tools that were considered]
+ ```
+ - Include any helper scripts or assets in the technique folder
+
+3. **After updating/creating techniques**, run `deepwork sync` to sync them to platform skill directories with the `dwt_` prefix.
+
+**Example technique update:**
+```markdown
+# Before (in SKILL.md)
+## Usage
+```bash
+pandoc input.md -o output.pdf
+```
+
+# After (improved based on learnings)
+## Usage
+```bash
+pandoc input.md -o output.pdf --pdf-engine=xelatex -V geometry:margin=1in
+```
+
+**Note**: The `--pdf-engine=xelatex` flag is required for Unicode support. The margin setting prevents text from running off the page.
+```
+
### Step 5: Create/Update AGENTS.md (Bespoke Learnings)
The AGENTS.md file captures project-specific knowledge that helps future agent runs.
@@ -264,13 +341,15 @@ When adding entries to AGENTS.md, prefer these patterns:
- Conversation has been analyzed for job executions
- Points of confusion and inefficiency are identified
-- Learnings are correctly classified (generalizable vs bespoke)
+- Learnings are correctly classified (generalizable vs technique-related vs bespoke)
- Job instructions updated for generalizable improvements
- Instructions are concise - no redundancy or unnecessary verbosity
- Shared/lengthy content extracted into referenced files where appropriate
+- Techniques created/updated for technique-related improvements
- AGENTS.md created/updated with bespoke learnings
- File references used instead of duplicating content
- AGENTS.md is in the correct folder (the deepest common folder for the topic)
+- `deepwork sync` run if instructions or techniques were modified
- When all criteria are met, include `✓ Quality Criteria Met`
## Example Dialog
diff --git a/.deepwork/jobs/deepwork_jobs/steps/tools.md b/.deepwork/jobs/deepwork_jobs/steps/tools.md
new file mode 100644
index 00000000..273c34bf
--- /dev/null
+++ b/.deepwork/jobs/deepwork_jobs/steps/tools.md
@@ -0,0 +1,212 @@
+# Verify and Document Techniques
+
+## Objective
+
+Verify that all external tools and capabilities required by the job are available and working, find alternatives if needed, and create reusable **techniques** for future reference.
+
+## Task
+
+Analyze the job specification to determine what techniques are needed, then spawn parallel sub-agents to test, configure, and document each technique.
+
+### Step 1: Analyze the Job for Required Techniques
+
+Read the `job.yml` file and examine each step to identify tasks that require external tools or capabilities beyond the agent's built-in abilities.
+
+**Look for steps that involve:**
+- File format conversion (PDF, DOCX, HTML, etc.)
+- Data processing (CSV, JSON, XML transformations)
+- Media manipulation (images, audio, video)
+- Web browsing or site access (via browser extensions like Chrome MCP)
+- External API calls or web requests
+- Build processes (compilers, bundlers)
+- Testing frameworks
+- Database operations
+- Container or virtualization tools
+
+**Types of tools and capabilities to consider:**
+- **CLI tools**: Command-line programs (pandoc, ffmpeg, imagemagick, etc.)
+- **MCP servers**: Model Context Protocol servers that extend agent capabilities (browser control, database access, etc.)
+- **Browser extensions**: Chrome extensions or similar for web interaction
+- **Language runtimes**: Python, Node.js, Ruby, etc. with specific packages
+- **External services**: APIs that require authentication or setup
+
+**For each step, create a requirements list:**
+- What the step needs to accomplish
+- What external tools or capabilities might be required
+- What the expected input/output formats are
+
+### Step 2: Spawn Parallel Sub-Agents for Each Technique
+
+For each technique you identified, spawn a sub-agent **in parallel** to handle testing and documentation. This allows all techniques to be verified concurrently.
+
+**Sub-agent prompt template (customize for each technique):**
+
+```
+You are verifying and documenting a technique for the "[TECHNIQUE_NAME]" process in a DeepWork job.
+
+## Technique Requirement
+
+[Describe what this specific technique needs to accomplish]
+
+## Your Tasks
+
+1. **Test if a tool exists** - Check if a tool is available that can accomplish this technique
+2. **Verify it works** - Run a simple test to confirm functionality
+3. **Find alternatives if needed** - If the tool is missing or broken, research and test alternatives until you have a working solution
+4. **Create the technique** - Create a folder in `.deepwork/techniques/[technique_name]/` with:
+ - `SKILL.md` - The main technique skill file following the Claude Skills format:
+ ```markdown
+ ---
+ name: technique_name
+ description: "Brief description of what this technique accomplishes"
+ ---
+
+ # Technique Name
+
+ ## Purpose
+ What this technique accomplishes and when to use it.
+
+ ## Tool
+ - **Name**: Tool name (e.g., pandoc, playwright)
+ - **Type**: CLI tool / MCP server / Browser extension / API
+ - **Version**: Known working version
+
+ ## Installation
+
+ ### macOS
+ ```bash
+ brew install tool-name
+ ```
+
+ ### Ubuntu/Debian
+ ```bash
+ apt-get install tool-name
+ ```
+
+ ### pip/npm (if applicable)
+ ```bash
+ pip install tool-name
+ ```
+
+ ## Verification
+ ```bash
+ tool-name --version
+ ```
+
+ ## Usage
+
+ ### Basic Example
+ ```bash
+ tool-name input.md -o output.pdf
+ ```
+
+ ### Common Options
+ - `-o, --output`: Output file path
+ - Other relevant options...
+
+ ## Troubleshooting
+ Common issues and solutions.
+
+ ## Alternatives Considered
+ - Alternative 1: Why not chosen
+ - Alternative 2: Why not chosen
+ ```
+ - Any helper scripts or assets the technique needs (e.g., `convert.py`, `template.html`)
+
+## Output Location
+
+Create the technique in: `.deepwork/techniques/[technique_name]/`
+
+Use descriptive, process-focused names like `making_pdfs`, `accessing_websites`, `creating_charts` (NOT tool names like `pandoc`, `playwright`).
+
+## Success Criteria
+
+- The technique has a working tool
+- Created `.deepwork/techniques/[technique_name]/SKILL.md`
+- Included any necessary helper scripts or assets in the same folder
+```
+
+**Example:** If you identified 3 techniques (making PDFs, accessing websites, creating charts), spawn 3 sub-agents in parallel:
+- Sub-agent 1: "making_pdfs" technique
+- Sub-agent 2: "accessing_websites" technique
+- Sub-agent 3: "creating_charts" technique
+
+### Step 3: Review Sub-Agent Outputs
+
+After all sub-agents complete:
+
+1. **Verify all techniques are covered** - Check that each identified need has a technique folder
+2. **Spot-check the documentation** - Ensure the SKILL.md files are complete and accurate
+3. **Verify tools work together** - If techniques depend on each other, confirm compatibility
+
+### Step 4: Run Sync
+
+After all techniques are created, run `deepwork sync` to copy them to the platform skill directories (`.claude/skills/`, `.gemini/skills/`) with the `dwt_` prefix.
+
+## Example
+
+For a job that creates research reports from web sources:
+
+**Step 1 output (your analysis):**
+```
+Required techniques:
+1. Accessing websites - Need to browse and extract data from web pages
+2. Creating charts - Need to generate visualizations from data
+3. Making PDFs - Need to convert markdown reports to PDF format
+```
+
+**Step 2:** Spawn 3 parallel sub-agents, one for each technique
+
+**Step 3:** Verify all sub-agents created their techniques:
+```
+.deepwork/techniques/
+├── accessing_websites/
+│ └── SKILL.md
+├── creating_charts/
+│ ├── SKILL.md
+│ └── chart_helper.py
+└── making_pdfs/
+ └── SKILL.md
+```
+
+**Step 4:** Run `deepwork sync` to sync techniques to platforms
+
+## Output
+
+After completing this step, you should have:
+
+1. **techniques/ directory** with technique folders:
+ ```
+ .deepwork/techniques/
+ ├── [technique_1]/
+ │ ├── SKILL.md
+ │ └── [optional assets]
+ ├── [technique_2]/
+ │ ├── SKILL.md
+ │ └── [optional assets]
+ └── ...
+ ```
+
+2. **Synced skills** in platform directories (after running `deepwork sync`):
+ ```
+ .claude/skills/
+ ├── dwt_[technique_1]/
+ │ └── SKILL.md
+ └── dwt_[technique_2]/
+ └── SKILL.md
+ ```
+
+3. **Confidence that all techniques work** and the job can be implemented successfully
+
+## Quality Criteria
+
+- All job steps have been analyzed for technique requirements
+- Parallel sub-agents were spawned for each technique requiring tooling
+- Every required tool has been tested and verified working
+- Each required technique has a working solution (original tool or alternative)
+- Techniques are organized by PROCESS name, not by tool name
+- Each technique folder contains a SKILL.md following the Claude Skills format
+- Helper scripts and assets are stored alongside SKILL.md in the technique folder
+- All techniques have been verified to work together
+- `deepwork sync` was run to sync techniques to platform skill directories
+- When all criteria are met, include `✓ Quality Criteria Met` in your response
diff --git a/.deepwork/techniques/AGENTS.md b/.deepwork/techniques/AGENTS.md
new file mode 100644
index 00000000..55b71a15
--- /dev/null
+++ b/.deepwork/techniques/AGENTS.md
@@ -0,0 +1,150 @@
+# DeepWork Techniques
+
+This folder contains reusable **techniques** - documented processes for accomplishing specific tasks using external tools. Techniques follow the Claude Skills format and are automatically synced to AI agent configuration directories (`.claude/skills/`, `.gemini/skills/`) with a `dwt_` prefix.
+
+## Purpose
+
+Techniques capture knowledge about how to accomplish processes that require external tools, MCP servers, or specific workflows. They are:
+
+- **Reusable**: Once created, a technique can be used across multiple jobs
+- **Documented**: Each technique includes installation and usage instructions
+- **Portable**: Techniques are synced to all configured AI platforms
+
+## Format
+
+Each technique is a folder containing skill files that follow the Claude Skills format:
+
+```
+techniques/
+├── AGENTS.md # This file
+├── making_pdfs/
+│ └── SKILL.md # Main technique skill
+├── accessing_websites/
+│ └── SKILL.md
+└── [technique_name]/
+ └── SKILL.md
+```
+
+### SKILL.md Format (Claude Skills)
+
+```markdown
+---
+name: technique_name
+description: "Brief description of what this technique accomplishes"
+---
+
+# Technique Name
+
+## Purpose
+
+What this technique accomplishes and when to use it.
+
+## Tool
+
+- **Name**: Tool name (e.g., pandoc, playwright)
+- **Type**: CLI tool / MCP server / Browser extension / API
+- **Version**: Known working version
+
+## Installation
+
+How to install the required tool:
+
+### macOS
+\`\`\`bash
+brew install tool-name
+\`\`\`
+
+### Ubuntu/Debian
+\`\`\`bash
+apt-get install tool-name
+\`\`\`
+
+### pip/npm
+\`\`\`bash
+pip install tool-name
+# or
+npm install -g tool-name
+\`\`\`
+
+## Verification
+
+How to verify the tool is installed correctly:
+
+\`\`\`bash
+tool-name --version
+\`\`\`
+
+## Usage
+
+### Basic Example
+
+\`\`\`bash
+tool-name input.md -o output.pdf
+\`\`\`
+
+### Common Options
+
+- `-o, --output`: Output file path
+- `-f, --format`: Output format
+
+### Example Workflow
+
+1. Prepare input files
+2. Run the tool
+3. Verify output
+
+## Troubleshooting
+
+Common issues and solutions:
+
+### Issue 1: Tool not found
+- Ensure tool is in PATH
+- Try reinstalling
+
+## Assets
+
+If this technique requires helper scripts or templates, they should be stored
+alongside the SKILL.md file:
+
+```
+technique_name/
+├── SKILL.md
+├── convert.py # Helper script
+└── template.html # Template file
+```
+
+Reference these assets using relative paths in the SKILL.md.
+
+## Alternatives Considered
+
+Other tools that could accomplish this process:
+- Alternative 1: Brief note on why not chosen
+- Alternative 2: Brief note on why not chosen
+```
+
+## Syncing
+
+Techniques are automatically synced by `deepwork sync`:
+
+1. Techniques from `.deepwork/techniques/` are copied to platform skill directories
+2. Folder names are prefixed with `dwt_` (e.g., `making_pdfs` becomes `dwt_making_pdfs`)
+3. Stale `dwt_` prefixed folders (no longer in techniques) are removed
+4. This ensures platform skills stay in sync with the techniques folder
+
+## Creating Techniques
+
+Techniques are created by the `deepwork_jobs` workflow:
+
+- **`/deepwork_jobs.tools`** step creates techniques when verifying tools for a job
+- **`/deepwork_jobs.learn`** step can refine existing techniques based on execution learnings
+
+You can also create techniques manually by adding a new folder with a `SKILL.md` file.
+
+## Invocation
+
+Once synced, techniques can be invoked as skills:
+
+- **Claude Code**: `/dwt_making_pdfs`
+- **Gemini CLI**: `/dwt_making_pdfs`
+
+The `dwt_` prefix indicates these are DeepWork-managed techniques.
diff --git a/.gemini/skills/deepwork_jobs/define.toml b/.gemini/skills/deepwork_jobs/define.toml
index 745062f3..aab8803c 100644
--- a/.gemini/skills/deepwork_jobs/define.toml
+++ b/.gemini/skills/deepwork_jobs/define.toml
@@ -9,7 +9,7 @@ description = "Creates a job.yml specification by gathering workflow requirement
prompt = """
# deepwork_jobs:define
-**Step 1/4** in **deepwork_jobs** workflow
+**Step 1/5** in **deepwork_jobs** workflow
> Creates and manages multi-step AI workflows. Use when defining, implementing, or improving DeepWork jobs.
@@ -424,7 +424,7 @@ workflows and learn from running them.
The `new_job` workflow guides you through defining and implementing a new job by
asking structured questions about your workflow, understanding each step's inputs and outputs,
-reviewing the specification, and generating all necessary files.
+reviewing the specification, verifying required techniques, and generating all necessary files.
The `learn` skill reflects on conversations where DeepWork jobs were run, identifies
confusion or inefficiencies, and improves job instructions. It also captures bespoke
@@ -484,7 +484,7 @@ Use branch format: `deepwork/deepwork_jobs-[instance]-YYYYMMDD`
## On Completion
1. Verify outputs are created
-2. Inform user: "Step 1/4 complete, outputs: job.yml"
+2. Inform user: "Step 1/5 complete, outputs: job.yml"
3. **Tell user next command**: `/deepwork_jobs:review_job_spec`
---
diff --git a/.gemini/skills/deepwork_jobs/implement.toml b/.gemini/skills/deepwork_jobs/implement.toml
index 582751ef..760cd982 100644
--- a/.gemini/skills/deepwork_jobs/implement.toml
+++ b/.gemini/skills/deepwork_jobs/implement.toml
@@ -1,15 +1,15 @@
# deepwork_jobs:implement
#
-# Generates step instruction files and syncs slash commands from the job.yml specification. Use after job spec review passes.
+# Generates step instruction files and syncs slash commands from the job.yml specification. Use after tools verification passes.
#
# Generated by DeepWork - do not edit manually
-description = "Generates step instruction files and syncs slash commands from the job.yml specification. Use after job spec review passes."
+description = "Generates step instruction files and syncs slash commands from the job.yml specification. Use after tools verification passes."
prompt = """
# deepwork_jobs:implement
-**Step 3/4** in **deepwork_jobs** workflow
+**Step 4/5** in **deepwork_jobs** workflow
> Creates and manages multi-step AI workflows. Use when defining, implementing, or improving DeepWork jobs.
@@ -17,43 +17,25 @@ prompt = """
Before proceeding, confirm these steps are complete:
- `/deepwork_jobs:review_job_spec`
+- `/deepwork_jobs:tools`
## Instructions
-**Goal**: Generates step instruction files and syncs slash commands from the job.yml specification. Use after job spec review passes.
+**Goal**: Generates step instruction files and syncs slash commands from the job.yml specification. Use after tools verification passes.
# Implement Job Steps
## Objective
-Generate the DeepWork job directory structure and instruction files for each step based on the validated `job.yml` specification from the review_job_spec step.
+Generate step instruction files for each step based on the validated `job.yml` specification from the review_job_spec step.
## Task
-Read the `job.yml` specification file and create all the necessary files to make the job functional, including directory structure and step instruction files. Then sync the commands to make them available.
+Read the `job.yml` specification file and create all the necessary step instruction files to make the job functional. Then sync the commands to make them available.
-### Step 1: Create Directory Structure Using Script
+**Note:** The `define` step already creates the directory structure using `make_new_job.sh`, so you don't need to create directories here.
-Run the `make_new_job.sh` script to create the standard directory structure:
-
-```bash
-.deepwork/jobs/deepwork_jobs/make_new_job.sh [job_name]
-```
-
-This creates:
-- `.deepwork/jobs/[job_name]/` - Main job directory
-- `.deepwork/jobs/[job_name]/steps/` - Step instruction files
-- `.deepwork/jobs/[job_name]/hooks/` - Custom validation scripts (with .gitkeep)
-- `.deepwork/jobs/[job_name]/templates/` - Example file formats (with .gitkeep)
-- `.deepwork/jobs/[job_name]/AGENTS.md` - Job management guidance
-
-**Note**: If the directory already exists (e.g., job.yml was created by define step), you can skip this step or manually create the additional directories:
-```bash
-mkdir -p .deepwork/jobs/[job_name]/hooks .deepwork/jobs/[job_name]/templates
-touch .deepwork/jobs/[job_name]/hooks/.gitkeep .deepwork/jobs/[job_name]/templates/.gitkeep
-```
-
-### Step 2: Read and Validate the Specification
+### Step 1: Read and Validate the Specification
1. **Locate the job.yml file**
- Read `.deepwork/jobs/[job_name]/job.yml` from the review_job_spec step
@@ -70,7 +52,7 @@ touch .deepwork/jobs/[job_name]/hooks/.gitkeep .deepwork/jobs/[job_name]/templat
- List of all steps with their details
- Understand the workflow structure
-### Step 3: Generate Step Instruction Files
+### Step 2: Generate Step Instruction Files
For each step in the job.yml, create a comprehensive instruction file at `.deepwork/jobs/[job_name]/steps/[step_id].md`.
@@ -94,6 +76,7 @@ For each step in the job.yml, create a comprehensive instruction file at `.deepw
5. **Quality over quantity** - Detailed, actionable instructions are better than vague ones
6. **Align with stop hooks** - If the step has `stop_hooks` defined, ensure the quality criteria in the instruction file match the validation criteria in the hooks
7. **Ask structured questions** - When a step has user inputs, the instructions MUST explicitly tell the agent to "ask structured questions" using the AskUserQuestion tool to gather that information. Never use generic phrasing like "ask the user" - always use "ask structured questions"
+8. **Reference techniques** - When a step requires external tools, include a reference to the relevant technique created in the `tools` step. See the section below on "Incorporating Techniques"
### Handling Stop Hooks
@@ -133,11 +116,55 @@ Step instructions can include additional `.md` files in the `steps/` directory f
See `.deepwork/jobs/deepwork_jobs/steps/supplemental_file_references.md` for detailed documentation and examples.
-### Step 4: Verify job.yml Location
+### Incorporating Techniques
+
+The `tools` step (which runs before `implement`) creates reusable techniques in `.deepwork/techniques/`. When generating step instructions, **reference these techniques** for any step that requires external tools.
+
+Techniques are synced to platform skill directories with a `dwt_` prefix (e.g., `making_pdfs` becomes `/dwt_making_pdfs`), so agents can invoke them directly.
+
+**How to incorporate techniques:**
+
+1. **Check what techniques exist:**
+ ```bash
+ ls .deepwork/techniques/
+ ```
+
+2. **Reference relevant techniques in step instructions:**
+ When a step uses an external tool (e.g., PDF generation, image processing), add a reference like:
+
+ ```markdown
+ ## Required Techniques
+
+ This step requires external tools. Use the following techniques:
+ - `/dwt_making_pdfs` - How to generate PDF output
+ - `/dwt_resizing_images` - How to resize and optimize images
+
+ See `.deepwork/techniques/[technique_name]/SKILL.md` for detailed usage instructions.
+ ```
+
+3. **Include key commands inline when helpful:**
+ For frequently-used commands, you can quote the essential invocation from the technique:
+
+ ```markdown
+ To convert markdown to PDF, use:
+ ```bash
+ pandoc input.md -o output.pdf --pdf-engine=xelatex
+ ```
+ See `/dwt_making_pdfs` (or `.deepwork/techniques/making_pdfs/SKILL.md`) for full documentation and troubleshooting.
+ ```
+
+**Why this matters:**
+- Step instructions stay focused on workflow logic
+- Techniques are documented once and synced to all platforms
+- Agents can invoke techniques directly as skills (e.g., `/dwt_making_pdfs`)
+- If techniques change, only the `.deepwork/techniques/` folder needs updating
+- New users can refer to technique SKILL.md files for installation help
+
+### Step 3: Verify job.yml Location
Verify that `job.yml` is in the correct location at `.deepwork/jobs/[job_name]/job.yml`. The define and review_job_spec steps should have created and validated it. If for some reason it's not there, you may need to create or move it.
-### Step 5: Sync Skills
+### Step 4: Sync Skills
Run `deepwork sync` to generate the skills for this job:
@@ -150,11 +177,11 @@ This will:
- Generate skills for each step
- Make the skills available in `.claude/skills/` (or appropriate platform directory)
-### Step 6: Relay Reload Instructions
+### Step 5: Relay Reload Instructions
After running `deepwork sync`, look at the "To use the new skills" section in the output. **Relay these exact reload instructions to the user** so they know how to pick up the new skills. Don't just reference the sync output - tell them directly what they need to do (e.g., "Type 'exit' then run 'claude --resume'" for Claude Code, or "Run '/memory refresh'" for Gemini CLI).
-### Step 7: Consider Rules for the New Job
+### Step 6: Consider Rules for the New Job
After implementing the job, consider whether there are **rules** that would help enforce quality or consistency when working with this job's domain.
@@ -243,10 +270,11 @@ Before marking this step complete, ensure:
- [ ] job.yml validated and copied to job directory
- [ ] All step instruction files created
- [ ] Each instruction file is complete and actionable
+- [ ] Steps requiring external tools reference techniques from `.deepwork/techniques/`
- [ ] `deepwork sync` executed successfully
- [ ] Skills generated in platform directory
- [ ] User informed to follow reload instructions from `deepwork sync`
-- [ ] Considered whether rules would benefit this job (Step 7)
+- [ ] Considered whether rules would benefit this job (Step 6)
- [ ] If rules suggested, offered to run `/deepwork_rules.define`
## Quality Criteria
@@ -257,6 +285,7 @@ Before marking this step complete, ensure:
- Output examples are provided in each instruction file
- Quality criteria defined for each step
- Steps with user inputs explicitly use "ask structured questions" phrasing
+- Steps requiring external tools reference the appropriate techniques from `.deepwork/techniques/`
- Sync completed successfully
- Skills available for use
- Thoughtfully considered relevant rules for the job domain
@@ -269,7 +298,7 @@ workflows and learn from running them.
The `new_job` workflow guides you through defining and implementing a new job by
asking structured questions about your workflow, understanding each step's inputs and outputs,
-reviewing the specification, and generating all necessary files.
+reviewing the specification, verifying required techniques, and generating all necessary files.
The `learn` skill reflects on conversations where DeepWork jobs were run, identifies
confusion or inefficiencies, and improves job instructions. It also captures bespoke
@@ -305,13 +334,14 @@ Use branch format: `deepwork/deepwork_jobs-[instance]-YYYYMMDD`
4. **Output Examples**: Does each instruction file show what good output looks like?
5. **Quality Criteria**: Does each instruction file define quality criteria for its outputs?
6. **Ask Structured Questions**: Do step instructions that gather user input explicitly use the phrase "ask structured questions"?
-7. **Sync Complete**: Has `deepwork sync` been run successfully?
-8. **Commands Available**: Are the slash-commands generated in `.claude/commands/`?
-9. **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.
+7. **Techniques Referenced**: Do steps requiring external tools reference the appropriate techniques from `.deepwork/techniques/`?
+8. **Sync Complete**: Has `deepwork sync` been run successfully?
+9. **Commands Available**: Are the slash-commands generated in `.claude/commands/`?
+10. **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.
## On Completion
1. Verify outputs are created
-2. Inform user: "Step 3/4 complete, outputs: steps/"
+2. Inform user: "Step 4/5 complete, outputs: steps/"
3. **Workflow complete**: All steps finished. Consider creating a PR to merge the work branch.
---
diff --git a/.gemini/skills/deepwork_jobs/index.toml b/.gemini/skills/deepwork_jobs/index.toml
index 6756ea88..9f588327 100644
--- a/.gemini/skills/deepwork_jobs/index.toml
+++ b/.gemini/skills/deepwork_jobs/index.toml
@@ -18,7 +18,7 @@ workflows and learn from running them.
The `new_job` workflow guides you through defining and implementing a new job by
asking structured questions about your workflow, understanding each step's inputs and outputs,
-reviewing the specification, and generating all necessary files.
+reviewing the specification, verifying required techniques, and generating all necessary files.
The `learn` skill reflects on conversations where DeepWork jobs were run, identifies
confusion or inefficiencies, and improves job instructions. It also captures bespoke
@@ -31,9 +31,11 @@ learnings specific to the current run into AGENTS.md files in the working folder
Command: `/deepwork_jobs:define`
2. **review_job_spec** - Reviews job.yml against quality criteria using a sub-agent for unbiased validation. Use after defining a job specification. (requires: define)
Command: `/deepwork_jobs:review_job_spec`
-3. **implement** - Generates step instruction files and syncs slash commands from the job.yml specification. Use after job spec review passes. (requires: review_job_spec)
+3. **tools** - Verifies required techniques are available and documents how to use them. Use after job spec review to ensure implementation can succeed. (requires: review_job_spec)
+ Command: `/deepwork_jobs:tools`
+4. **implement** - Generates step instruction files and syncs slash commands from the job.yml specification. Use after tools verification passes. (requires: review_job_spec, tools)
Command: `/deepwork_jobs:implement`
-4. **learn** - Analyzes conversation history to improve job instructions and capture learnings. Use after running a job to refine it.
+5. **learn** - Analyzes conversation history to improve job instructions, techniques, and capture learnings. Use after running a job to refine it.
Command: `/deepwork_jobs:learn`
## Execution Instructions
@@ -43,6 +45,7 @@ learnings specific to the current run into AGENTS.md files in the working folder
Parse any text following `/deepwork_jobs` to determine user intent:
- "define" or related terms → start at `/deepwork_jobs:define`
- "review_job_spec" or related terms → start at `/deepwork_jobs:review_job_spec`
+- "tools" or related terms → start at `/deepwork_jobs:tools`
- "implement" or related terms → start at `/deepwork_jobs:implement`
- "learn" or related terms → start at `/deepwork_jobs:learn`
diff --git a/.gemini/skills/deepwork_jobs/learn.toml b/.gemini/skills/deepwork_jobs/learn.toml
index e4d7d9a9..dfabbcd7 100644
--- a/.gemini/skills/deepwork_jobs/learn.toml
+++ b/.gemini/skills/deepwork_jobs/learn.toml
@@ -1,10 +1,10 @@
# deepwork_jobs:learn
#
-# Analyzes conversation history to improve job instructions and capture learnings. Use after running a job to refine it.
+# Analyzes conversation history to improve job instructions, techniques, and capture learnings. Use after running a job to refine it.
#
# Generated by DeepWork - do not edit manually
-description = "Analyzes conversation history to improve job instructions and capture learnings. Use after running a job to refine it."
+description = "Analyzes conversation history to improve job instructions, techniques, and capture learnings. Use after running a job to refine it."
prompt = """
# deepwork_jobs:learn
@@ -16,7 +16,7 @@ prompt = """
## Instructions
-**Goal**: Analyzes conversation history to improve job instructions and capture learnings. Use after running a job to refine it.
+**Goal**: Analyzes conversation history to improve job instructions, techniques, and capture learnings. Use after running a job to refine it.
# Learn from Job Execution
@@ -95,6 +95,16 @@ For each learning identified, determine if it is:
- "Quality criterion 'Visualization' needs clearer requirements"
- "Documents need a section for action items"
+**Technique-Related** (should improve or create techniques):
+- Improvements to how external tools are used
+- Better installation or usage instructions
+- New tools discovered during execution
+- Workarounds or troubleshooting tips
+- Examples:
+ - "The PDF generation command needs an extra flag for better formatting"
+ - "Found a better tool for web scraping that handles dynamic content"
+ - "Installation steps needed adjustment for macOS"
+
**Bespoke** (should go in AGENTS.md):
- Specific to THIS project/codebase/run
- Depends on local conventions or structure
@@ -217,6 +227,73 @@ quality_criteria:
description: Include Mermaid.js charts showing spend breakdown by service and month-over-month trend
```
+### Step 4.6: Create/Update Techniques (Technique-Related Learnings)
+
+If technique-related learnings were identified, update or create techniques in `.deepwork/techniques/`:
+
+1. **For existing techniques** (update):
+ - Locate the technique folder: `.deepwork/techniques/[technique_name]/`
+ - Update the `SKILL.md` file with improvements:
+ - Better usage examples
+ - Additional command-line options
+ - Troubleshooting tips discovered during execution
+ - Workarounds for edge cases
+
+2. **For new techniques** (create):
+ - Create a new folder: `.deepwork/techniques/[technique_name]/`
+ - Create a `SKILL.md` file following the Claude Skills format:
+ ```markdown
+ ---
+ name: technique_name
+ description: "Brief description of what this technique accomplishes"
+ ---
+
+ # Technique Name
+
+ ## Purpose
+ What this technique accomplishes and when to use it.
+
+ ## Tool
+ - **Name**: Tool name
+ - **Type**: CLI tool / MCP server / Browser extension / API
+ - **Version**: Known working version
+
+ ## Installation
+ [Installation instructions for different platforms]
+
+ ## Verification
+ [How to verify the tool is working]
+
+ ## Usage
+ [Usage examples and common options]
+
+ ## Troubleshooting
+ [Common issues and solutions]
+
+ ## Alternatives Considered
+ [Other tools that were considered]
+ ```
+ - Include any helper scripts or assets in the technique folder
+
+3. **After updating/creating techniques**, run `deepwork sync` to sync them to platform skill directories with the `dwt_` prefix.
+
+**Example technique update:**
+```markdown
+# Before (in SKILL.md)
+## Usage
+```bash
+pandoc input.md -o output.pdf
+```
+
+# After (improved based on learnings)
+## Usage
+```bash
+pandoc input.md -o output.pdf --pdf-engine=xelatex -V geometry:margin=1in
+```
+
+**Note**: The `--pdf-engine=xelatex` flag is required for Unicode support. The margin setting prevents text from running off the page.
+```
+
### Step 5: Create/Update AGENTS.md (Bespoke Learnings)
The AGENTS.md file captures project-specific knowledge that helps future agent runs.
@@ -284,13 +361,15 @@ When adding entries to AGENTS.md, prefer these patterns:
- Conversation has been analyzed for job executions
- Points of confusion and inefficiency are identified
-- Learnings are correctly classified (generalizable vs bespoke)
+- Learnings are correctly classified (generalizable vs technique-related vs bespoke)
- Job instructions updated for generalizable improvements
- Instructions are concise - no redundancy or unnecessary verbosity
- Shared/lengthy content extracted into referenced files where appropriate
+- Techniques created/updated for technique-related improvements
- AGENTS.md created/updated with bespoke learnings
- File references used instead of duplicating content
- AGENTS.md is in the correct folder (the deepest common folder for the topic)
+- `deepwork sync` run if instructions or techniques were modified
- When all criteria are met, include `✓ Quality Criteria Met`
## Example Dialog
@@ -384,7 +463,7 @@ workflows and learn from running them.
The `new_job` workflow guides you through defining and implementing a new job by
asking structured questions about your workflow, understanding each step's inputs and outputs,
-reviewing the specification, and generating all necessary files.
+reviewing the specification, verifying required techniques, and generating all necessary files.
The `learn` skill reflects on conversations where DeepWork jobs were run, identifies
confusion or inefficiencies, and improves job instructions. It also captures bespoke
@@ -408,6 +487,7 @@ Use branch format: `deepwork/deepwork_jobs-[instance]-YYYYMMDD`
**Required outputs**:
- `AGENTS.md`
+- `.deepwork/techniques/` (directory)
## Quality Validation (Manual)
@@ -416,20 +496,22 @@ Use branch format: `deepwork/deepwork_jobs-[instance]-YYYYMMDD`
**Criteria (all must be satisfied)**:
1. **Conversation Analyzed**: Did the agent review the conversation for DeepWork job executions?
2. **Confusion Identified**: Did the agent identify points of confusion, errors, or inefficiencies?
-3. **Instructions Improved**: Were job instructions updated to address identified issues?
-4. **Instructions Concise**: Are instructions free of redundancy and unnecessary verbosity?
-5. **Shared Content Extracted**: Is lengthy/duplicated content extracted into referenced files?
-6. **doc spec Reviewed (if applicable)**: For jobs with doc spec outputs, were doc spec-related learnings identified?
-7. **doc spec Updated (if applicable)**: Were doc spec files updated with improved quality criteria or structure?
-8. **Bespoke Learnings Captured**: Were run-specific learnings added to AGENTS.md?
-9. **File References Used**: Do AGENTS.md entries reference other files where appropriate?
-10. **Working Folder Correct**: Is AGENTS.md in the correct working folder for the job?
-11. **Generalizable Separated**: Are generalizable improvements in instructions, not AGENTS.md?
-12. **Sync Complete**: Has `deepwork sync` been run if instructions were modified?
+3. **Learnings Classified**: Were learnings classified as generalizable, technique-related, or bespoke?
+4. **Instructions Improved**: Were job instructions updated to address identified issues?
+5. **Instructions Concise**: Are instructions free of redundancy and unnecessary verbosity?
+6. **Shared Content Extracted**: Is lengthy/duplicated content extracted into referenced files?
+7. **doc spec Reviewed (if applicable)**: For jobs with doc spec outputs, were doc spec-related learnings identified?
+8. **doc spec Updated (if applicable)**: Were doc spec files updated with improved quality criteria or structure?
+9. **Techniques Created/Updated (if applicable)**: Were new techniques created or existing ones improved based on tool usage learnings?
+10. **Bespoke Learnings Captured**: Were run-specific learnings added to AGENTS.md?
+11. **File References Used**: Do AGENTS.md entries reference other files where appropriate?
+12. **Working Folder Correct**: Is AGENTS.md in the correct working folder for the job?
+13. **Generalizable Separated**: Are generalizable improvements in instructions, not AGENTS.md?
+14. **Sync Complete**: Has `deepwork sync` been run if instructions or techniques were modified?
## On Completion
1. Verify outputs are created
-2. Inform user: "learn complete, outputs: AGENTS.md"
+2. Inform user: "learn complete, outputs: AGENTS.md, .deepwork/techniques/"
This standalone command can be re-run anytime.
diff --git a/.gemini/skills/deepwork_jobs/review_job_spec.toml b/.gemini/skills/deepwork_jobs/review_job_spec.toml
index 4e321d57..0bef18aa 100644
--- a/.gemini/skills/deepwork_jobs/review_job_spec.toml
+++ b/.gemini/skills/deepwork_jobs/review_job_spec.toml
@@ -9,7 +9,7 @@ description = "Reviews job.yml against quality criteria using a sub-agent for un
prompt = """
# deepwork_jobs:review_job_spec
-**Step 2/4** in **deepwork_jobs** workflow
+**Step 2/5** in **deepwork_jobs** workflow
> Creates and manages multi-step AI workflows. Use when defining, implementing, or improving DeepWork jobs.
@@ -239,7 +239,7 @@ workflows and learn from running them.
The `new_job` workflow guides you through defining and implementing a new job by
asking structured questions about your workflow, understanding each step's inputs and outputs,
-reviewing the specification, and generating all necessary files.
+reviewing the specification, verifying required techniques, and generating all necessary files.
The `learn` skill reflects on conversations where DeepWork jobs were run, identifies
confusion or inefficiencies, and improves job instructions. It also captures bespoke
@@ -291,8 +291,8 @@ Use branch format: `deepwork/deepwork_jobs-[instance]-YYYYMMDD`
## On Completion
1. Verify outputs are created
-2. Inform user: "Step 2/4 complete, outputs: job.yml"
-3. **Tell user next command**: `/deepwork_jobs:implement`
+2. Inform user: "Step 2/5 complete, outputs: job.yml"
+3. **Tell user next command**: `/deepwork_jobs:tools`
---
diff --git a/.gemini/skills/deepwork_jobs/tools.toml b/.gemini/skills/deepwork_jobs/tools.toml
new file mode 100644
index 00000000..c0be05fd
--- /dev/null
+++ b/.gemini/skills/deepwork_jobs/tools.toml
@@ -0,0 +1,292 @@
+# deepwork_jobs:tools
+#
+# Verifies required techniques are available and documents how to use them. Use after job spec review to ensure implementation can succeed.
+#
+# Generated by DeepWork - do not edit manually
+
+description = "Verifies required techniques are available and documents how to use them. Use after job spec review to ensure implementation can succeed."
+
+prompt = """
+# deepwork_jobs:tools
+
+**Step 3/5** in **deepwork_jobs** workflow
+
+> Creates and manages multi-step AI workflows. Use when defining, implementing, or improving DeepWork jobs.
+
+## Prerequisites (Verify First)
+
+Before proceeding, confirm these steps are complete:
+- `/deepwork_jobs:review_job_spec`
+
+## Instructions
+
+**Goal**: Verifies required techniques are available and documents how to use them. Use after job spec review to ensure implementation can succeed.
+
+# Verify and Document Techniques
+
+## Objective
+
+Verify that all external tools and capabilities required by the job are available and working, find alternatives if needed, and create reusable **techniques** for future reference.
+
+## Task
+
+Analyze the job specification to determine what techniques are needed, then spawn parallel sub-agents to test, configure, and document each technique.
+
+### Step 1: Analyze the Job for Required Techniques
+
+Read the `job.yml` file and examine each step to identify tasks that require external tools or capabilities beyond the agent's built-in abilities.
+
+**Look for steps that involve:**
+- File format conversion (PDF, DOCX, HTML, etc.)
+- Data processing (CSV, JSON, XML transformations)
+- Media manipulation (images, audio, video)
+- Web browsing or site access (via browser extensions like Chrome MCP)
+- External API calls or web requests
+- Build processes (compilers, bundlers)
+- Testing frameworks
+- Database operations
+- Container or virtualization tools
+
+**Types of tools and capabilities to consider:**
+- **CLI tools**: Command-line programs (pandoc, ffmpeg, imagemagick, etc.)
+- **MCP servers**: Model Context Protocol servers that extend agent capabilities (browser control, database access, etc.)
+- **Browser extensions**: Chrome extensions or similar for web interaction
+- **Language runtimes**: Python, Node.js, Ruby, etc. with specific packages
+- **External services**: APIs that require authentication or setup
+
+**For each step, create a requirements list:**
+- What the step needs to accomplish
+- What external tools or capabilities might be required
+- What the expected input/output formats are
+
+### Step 2: Spawn Parallel Sub-Agents for Each Technique
+
+For each technique you identified, spawn a sub-agent **in parallel** to handle testing and documentation. This allows all techniques to be verified concurrently.
+
+**Sub-agent prompt template (customize for each technique):**
+
+```
+You are verifying and documenting a technique for the "[TECHNIQUE_NAME]" process in a DeepWork job.
+
+## Technique Requirement
+
+[Describe what this specific technique needs to accomplish]
+
+## Your Tasks
+
+1. **Test if a tool exists** - Check if a tool is available that can accomplish this technique
+2. **Verify it works** - Run a simple test to confirm functionality
+3. **Find alternatives if needed** - If the tool is missing or broken, research and test alternatives until you have a working solution
+4. **Create the technique** - Create a folder in `.deepwork/techniques/[technique_name]/` with:
+ - `SKILL.md` - The main technique skill file following the Claude Skills format:
+ ```markdown
+ ---
+ name: technique_name
+ description: "Brief description of what this technique accomplishes"
+ ---
+
+ # Technique Name
+
+ ## Purpose
+ What this technique accomplishes and when to use it.
+
+ ## Tool
+ - **Name**: Tool name (e.g., pandoc, playwright)
+ - **Type**: CLI tool / MCP server / Browser extension / API
+ - **Version**: Known working version
+
+ ## Installation
+
+ ### macOS
+ ```bash
+ brew install tool-name
+ ```
+
+ ### Ubuntu/Debian
+ ```bash
+ apt-get install tool-name
+ ```
+
+ ### pip/npm (if applicable)
+ ```bash
+ pip install tool-name
+ ```
+
+ ## Verification
+ ```bash
+ tool-name --version
+ ```
+
+ ## Usage
+
+ ### Basic Example
+ ```bash
+ tool-name input.md -o output.pdf
+ ```
+
+ ### Common Options
+ - `-o, --output`: Output file path
+ - Other relevant options...
+
+ ## Troubleshooting
+ Common issues and solutions.
+
+ ## Alternatives Considered
+ - Alternative 1: Why not chosen
+ - Alternative 2: Why not chosen
+ ```
+ - Any helper scripts or assets the technique needs (e.g., `convert.py`, `template.html`)
+
+## Output Location
+
+Create the technique in: `.deepwork/techniques/[technique_name]/`
+
+Use descriptive, process-focused names like `making_pdfs`, `accessing_websites`, `creating_charts` (NOT tool names like `pandoc`, `playwright`).
+
+## Success Criteria
+
+- The technique has a working tool
+- Created `.deepwork/techniques/[technique_name]/SKILL.md`
+- Included any necessary helper scripts or assets in the same folder
+```
+
+**Example:** If you identified 3 techniques (making PDFs, accessing websites, creating charts), spawn 3 sub-agents in parallel:
+- Sub-agent 1: "making_pdfs" technique
+- Sub-agent 2: "accessing_websites" technique
+- Sub-agent 3: "creating_charts" technique
+
+### Step 3: Review Sub-Agent Outputs
+
+After all sub-agents complete:
+
+1. **Verify all techniques are covered** - Check that each identified need has a technique folder
+2. **Spot-check the documentation** - Ensure the SKILL.md files are complete and accurate
+3. **Verify tools work together** - If techniques depend on each other, confirm compatibility
+
+### Step 4: Run Sync
+
+After all techniques are created, run `deepwork sync` to copy them to the platform skill directories (`.claude/skills/`, `.gemini/skills/`) with the `dwt_` prefix.
+
+## Example
+
+For a job that creates research reports from web sources:
+
+**Step 1 output (your analysis):**
+```
+Required techniques:
+1. Accessing websites - Need to browse and extract data from web pages
+2. Creating charts - Need to generate visualizations from data
+3. Making PDFs - Need to convert markdown reports to PDF format
+```
+
+**Step 2:** Spawn 3 parallel sub-agents, one for each technique
+
+**Step 3:** Verify all sub-agents created their techniques:
+```
+.deepwork/techniques/
+├── accessing_websites/
+│ └── SKILL.md
+├── creating_charts/
+│ ├── SKILL.md
+│ └── chart_helper.py
+└── making_pdfs/
+ └── SKILL.md
+```
+
+**Step 4:** Run `deepwork sync` to sync techniques to platforms
+
+## Output
+
+After completing this step, you should have:
+
+1. **techniques/ directory** with technique folders:
+ ```
+ .deepwork/techniques/
+ ├── [technique_1]/
+ │ ├── SKILL.md
+ │ └── [optional assets]
+ ├── [technique_2]/
+ │ ├── SKILL.md
+ │ └── [optional assets]
+ └── ...
+ ```
+
+2. **Synced skills** in platform directories (after running `deepwork sync`):
+ ```
+ .claude/skills/
+ ├── dwt_[technique_1]/
+ │ └── SKILL.md
+ └── dwt_[technique_2]/
+ └── SKILL.md
+ ```
+
+3. **Confidence that all techniques work** and the job can be implemented successfully
+
+## Quality Criteria
+
+- All job steps have been analyzed for technique requirements
+- Parallel sub-agents were spawned for each technique requiring tooling
+- Every required tool has been tested and verified working
+- Each required technique has a working solution (original tool or alternative)
+- Techniques are organized by PROCESS name, not by tool name
+- Each technique folder contains a SKILL.md following the Claude Skills format
+- Helper scripts and assets are stored alongside SKILL.md in the technique folder
+- All techniques have been verified to work together
+- `deepwork sync` was run to sync techniques to platform skill directories
+- When all criteria are met, include `✓ Quality Criteria Met` in your response
+
+
+### Job Context
+
+Core commands for managing DeepWork jobs. These commands help you define new multi-step
+workflows and learn from running them.
+
+The `new_job` workflow guides you through defining and implementing a new job by
+asking structured questions about your workflow, understanding each step's inputs and outputs,
+reviewing the specification, verifying required techniques, and generating all necessary files.
+
+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.
+
+
+## Required Inputs
+
+
+**Files from Previous Steps** - Read these first:
+- `job.yml` (from `review_job_spec`)
+
+## Work Branch
+
+Use branch format: `deepwork/deepwork_jobs-[instance]-YYYYMMDD`
+
+- If on a matching work branch: continue using it
+- If on main/master: create new branch with `git checkout -b deepwork/deepwork_jobs-[instance]-$(date +%Y%m%d)`
+
+## Outputs
+
+**Required outputs**:
+- `.deepwork/techniques/` (directory)
+
+## Quality Validation (Manual)
+
+**NOTE**: Gemini CLI does not support automated validation. Manually verify criteria before completing.
+
+**Criteria (all must be satisfied)**:
+1. **Tasks Analyzed**: Were all job steps reviewed to identify required techniques (CLI tools, MCP servers, browser extensions, etc.)?
+2. **Parallel Sub-Agents**: Were parallel sub-agents spawned for each technique requiring tooling?
+3. **Had Working Technique**: Does each required technique have a working solution (original tool or alternative)?
+4. **Technique Created**: Was a technique folder created in `.deepwork/techniques/` for each technique (e.g., making_pdfs/, not pandoc/)?
+5. **SKILL.md Format**: Does each technique folder contain a SKILL.md file following the Claude Skills format?
+6. **Assets Included**: Are helper scripts and assets stored alongside SKILL.md in the technique folder?
+7. **Sync Complete**: Was `deepwork sync` run to sync techniques to platform skill directories?
+## On Completion
+
+1. Verify outputs are created
+2. Inform user: "Step 3/5 complete, outputs: .deepwork/techniques/"
+3. **Tell user next command**: `/deepwork_jobs:implement`
+
+---
+
+**Reference files**: `.deepwork/jobs/deepwork_jobs/job.yml`, `.deepwork/jobs/deepwork_jobs/steps/tools.md`
+"""
\ No newline at end of file
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9fbcd172..459a3e5e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -14,12 +14,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- Step skills now display workflow context (e.g., "Step 2/3 in new_job workflow")
- Standalone skills are clearly marked as "can be run anytime"
- Backward compatible: jobs without `workflows` section use dependency-based detection
+- New `tools` step in `deepwork_jobs` workflow for verifying and documenting techniques
+ - Analyzes job steps to identify required external tools (PDF generation, data processing, etc.)
+ - Spawns parallel sub-agents to test each tool and find alternatives if missing
+ - Creates reusable techniques in `.deepwork/techniques/` following Claude Skills format
+ - Techniques are synced to platform skill directories with `dwt_` prefix
### Changed
- Skill templates now show workflow-aware progress (e.g., "new_job step 2/3 complete")
- Meta-skill template reorganized to show "Workflows" and "Standalone Skills" sections separately
-- Updated `deepwork_jobs` standard job to v1.0.0 with explicit `new_job` workflow
+- Updated `deepwork_jobs` standard job to v1.1.0 with `tools` step in `new_job` workflow
- SessionStart hook now skips non-initial sessions (resume, compact/clear) by checking the `source` field in stdin JSON, reducing noise and redundant checks
+- `deepwork_jobs.implement` step no longer creates directory structure (already done by `define` step)
+- `deepwork_jobs.implement` now references techniques when generating step instructions
### Fixed
- Fixed skill template generating malformed YAML frontmatter with fields concatenated on single lines
diff --git a/doc/architecture.md b/doc/architecture.md
index cafd92c3..6e16611d 100644
--- a/doc/architecture.md
+++ b/doc/architecture.md
@@ -63,6 +63,8 @@ deepwork/ # DeepWork tool repository
│ │ │ └── skill-job-step.md.jinja
│ │ ├── gemini/
│ │ └── copilot/
+│ ├── techniques/ # Bundled technique AGENTS.md template
+│ │ └── AGENTS.md # Explains the techniques system
│ ├── standard_jobs/ # Built-in job definitions
│ │ ├── deepwork_jobs/
│ │ │ ├── job.yml
@@ -286,17 +288,31 @@ my-project/ # User's project (target)
├── .claude/ # Claude Code directory
│ ├── settings.json # Includes installed hooks
│ └── skills/ # Skill files
-│ ├── deepwork_jobs.define.md # Core DeepWork skills
-│ ├── deepwork_jobs.implement.md
-│ ├── deepwork_jobs.refine.md
-│ ├── deepwork_rules.define.md # Rule management
-│ ├── competitive_research.identify_competitors.md
+│ ├── deepwork_jobs/ # Core DeepWork meta-skill
+│ ├── deepwork_jobs.define/ # Core DeepWork step skills
+│ ├── deepwork_jobs.tools/
+│ ├── deepwork_jobs.implement/
+│ ├── deepwork_jobs.learn/
+│ ├── deepwork_rules/ # Rule management
+│ ├── deepwork_rules.define/
+│ ├── dwt_making_pdfs/ # Technique skills (dwt_ prefix)
+│ │ └── SKILL.md
+│ ├── dwt_web_scraping/
+│ │ ├── SKILL.md
+│ │ └── scraper.py
│ └── ...
├── .deepwork/ # DeepWork configuration
│ ├── config.yml # Platform config
│ ├── .gitignore # Ignores tmp/ directory
-│ ├── doc_specs/ # Doc specs (document specifications)
+│ ├── doc_specs/ # Doc specs (document specifications)
│ │ └── monthly_aws_report.md
+│ ├── techniques/ # Reusable technique skills (synced to platforms)
+│ │ ├── AGENTS.md # Explains the techniques system
+│ │ ├── making_pdfs/
+│ │ │ └── SKILL.md # Claude Skills format
+│ │ └── web_scraping/
+│ │ ├── SKILL.md
+│ │ └── scraper.py # Helper script (asset)
│ ├── rules/ # Rule definitions (v2 format)
│ │ ├── source-test-pairing.md
│ │ ├── format-python.md
@@ -773,8 +789,8 @@ When all steps are done, remind the user they should:
DeepWork includes a built-in job called `deepwork_jobs` for managing jobs. It provides:
**Workflows** (multi-step sequences):
-- **`new_job`** workflow: `define` → `review_job_spec` → `implement`
- - Creates complete job definitions through interactive Q&A, validation, and file generation
+- **`new_job`** workflow: `define` → `review_job_spec` → `tools` → `implement`
+ - Creates complete job definitions through interactive Q&A, validation, technique verification, and file generation
**Standalone Skills** (can be run anytime):
- **`/deepwork_jobs.learn`** - Analyzes conversations to improve job instructions and capture learnings
@@ -1304,6 +1320,126 @@ See `doc/doc-specs.md` for complete documentation.
---
+## Techniques
+
+Techniques are reusable, documented processes for accomplishing specific tasks using external tools. They follow the Claude Skills format and are automatically synced to AI platform skill directories.
+
+### Purpose
+
+Techniques capture knowledge about how to use external tools, MCP servers, or specific workflows. They are:
+
+- **Reusable**: Once created, a technique can be used across multiple jobs
+- **Documented**: Each technique includes installation, usage, and troubleshooting instructions
+- **Portable**: Techniques are synced to all configured AI platforms with a `dwt_` prefix
+
+### Technique File Format
+
+Techniques are stored in `.deepwork/techniques/[technique_name]/` folders, each containing:
+
+- `SKILL.md` - Main technique skill file (Claude Skills format)
+- Optional asset files (helper scripts, templates, etc.)
+
+**Example SKILL.md:**
+
+```markdown
+---
+name: making_pdfs
+description: "Convert markdown documents to PDF format"
+---
+
+# Making PDFs
+
+## Purpose
+Convert markdown documents to professionally formatted PDF files.
+
+## Tool
+- **Name**: pandoc
+- **Type**: CLI tool
+- **Version**: 3.0+
+
+## Installation
+
+### macOS
+```bash
+brew install pandoc
+brew install basictex # For PDF output
+```
+
+### Ubuntu/Debian
+```bash
+apt-get install pandoc texlive-latex-base
+```
+
+## Verification
+```bash
+pandoc --version
+```
+
+## Usage
+
+### Basic Example
+```bash
+pandoc input.md -o output.pdf
+```
+
+### With Better Formatting
+```bash
+pandoc input.md -o output.pdf --pdf-engine=xelatex -V geometry:margin=1in
+```
+
+## Troubleshooting
+
+### "xelatex not found"
+Install a LaTeX distribution (basictex on macOS, texlive on Linux).
+
+## Alternatives Considered
+- **wkhtmltopdf**: Good for HTML, but requires HTML conversion first
+- **weasyprint**: Python-based, but fewer formatting options
+```
+
+### Syncing Techniques
+
+When `deepwork sync` runs:
+
+1. Techniques from `.deepwork/techniques/` are copied to platform skill directories
+2. Folder names are prefixed with `dwt_` (e.g., `making_pdfs` → `dwt_making_pdfs`)
+3. Stale `dwt_` folders (no longer in techniques) are removed
+4. For Gemini, `SKILL.md` is converted to `index.toml`
+
+**Result:**
+```
+.claude/skills/
+├── dwt_making_pdfs/
+│ └── SKILL.md
+├── dwt_web_scraping/
+│ ├── SKILL.md
+│ └── scraper.py
+└── ...
+```
+
+### Workflow Integration
+
+**Creation**: The `/deepwork_jobs.tools` step creates techniques when verifying tools for a job:
+1. Analyzes job steps for required tools
+2. Spawns parallel sub-agents to test and document each technique
+3. Creates technique folders in `.deepwork/techniques/`
+4. Runs `deepwork sync` to sync to platforms
+
+**Refinement**: The `/deepwork_jobs.learn` step can refine techniques:
+1. Identifies technique-related learnings during job execution
+2. Updates existing technique SKILL.md files
+3. Creates new techniques for tools discovered during execution
+
+### Invocation
+
+Once synced, techniques can be invoked as skills:
+- **Claude Code**: `/dwt_making_pdfs`
+- **Gemini CLI**: `:dwt_making_pdfs`
+
+The `dwt_` prefix indicates these are DeepWork-managed techniques.
+
+---
+
### Rule Schema
Rules are validated against a JSON Schema:
diff --git a/src/deepwork/cli/install.py b/src/deepwork/cli/install.py
index 19bec4f8..6082ca76 100644
--- a/src/deepwork/cli/install.py
+++ b/src/deepwork/cli/install.py
@@ -149,6 +149,37 @@ def _create_tmp_directory(deepwork_dir: Path) -> None:
)
+def _create_techniques_directory(deepwork_dir: Path) -> bool:
+ """
+ Create the techniques directory with AGENTS.md explaining the format.
+
+ Techniques are reusable documented processes that use external tools.
+ They follow the Claude Skills format and are synced to AI platform directories.
+
+ Args:
+ deepwork_dir: Path to .deepwork directory
+
+ Returns:
+ True if the directory was created, False if it already existed
+ """
+ techniques_dir = deepwork_dir / "techniques"
+
+ if techniques_dir.exists():
+ return False
+
+ # Create the techniques directory
+ ensure_dir(techniques_dir)
+
+ # Copy AGENTS.md from the source techniques directory
+ source_agents_md = Path(__file__).parent.parent / "techniques" / "AGENTS.md"
+ if source_agents_md.exists():
+ dest_agents_md = techniques_dir / "AGENTS.md"
+ shutil.copy(source_agents_md, dest_agents_md)
+ fix_permissions(dest_agents_md)
+
+ return True
+
+
def _create_rules_directory(project_path: Path) -> bool:
"""
Create the v2 rules directory structure with example templates.
@@ -364,7 +395,13 @@ def _install_deepwork(platform_name: str | None, project_path: Path) -> None:
_create_tmp_directory(deepwork_dir)
console.print(" [green]✓[/green] Created .deepwork/tmp/.gitkeep")
- # Step 3e: Create rules directory with v2 templates
+ # Step 3e: Create techniques directory for reusable tool documentation
+ if _create_techniques_directory(deepwork_dir):
+ console.print(" [green]✓[/green] Created .deepwork/techniques/ with AGENTS.md")
+ else:
+ console.print(" [dim]•[/dim] .deepwork/techniques/ already exists")
+
+ # Step 3f: Create rules directory with v2 templates
if _create_rules_directory(project_path):
console.print(" [green]✓[/green] Created .deepwork/rules/ with example templates")
else:
diff --git a/src/deepwork/cli/sync.py b/src/deepwork/cli/sync.py
index 00588dcd..c0f338a1 100644
--- a/src/deepwork/cli/sync.py
+++ b/src/deepwork/cli/sync.py
@@ -1,5 +1,6 @@
"""Sync command for DeepWork CLI."""
+import shutil
from pathlib import Path
import click
@@ -10,9 +11,12 @@
from deepwork.core.generator import SkillGenerator
from deepwork.core.hooks_syncer import collect_job_hooks, sync_hooks_to_platform
from deepwork.core.parser import parse_job_definition
-from deepwork.utils.fs import ensure_dir
+from deepwork.utils.fs import ensure_dir, fix_permissions
from deepwork.utils.yaml_utils import load_yaml
+# Prefix for DeepWork-managed technique folders in platform skill directories
+TECHNIQUE_PREFIX = "dwt_"
+
console = Console()
@@ -22,6 +26,138 @@ class SyncError(Exception):
pass
+def sync_techniques_to_platform(
+ techniques_dir: Path, skills_dir: Path, adapter: AgentAdapter
+) -> tuple[int, int]:
+ """
+ Sync techniques from .deepwork/techniques/ to platform skill directory.
+
+ Copies technique folders with a 'dwt_' prefix and removes stale dwt_ folders
+ that no longer have corresponding techniques.
+
+ Args:
+ techniques_dir: Path to .deepwork/techniques/ directory
+ skills_dir: Path to platform skills directory (e.g., .claude/skills/)
+ adapter: The agent adapter for platform-specific handling
+
+ Returns:
+ Tuple of (synced_count, removed_count)
+ """
+ synced_count = 0
+ removed_count = 0
+
+ # Get current technique names (directories with SKILL.md or index.toml)
+ current_techniques: set[str] = set()
+ if techniques_dir.exists():
+ for technique_dir in techniques_dir.iterdir():
+ if technique_dir.is_dir() and not technique_dir.name.startswith("."):
+ # Check for SKILL.md (Claude) or any .toml file (Gemini)
+ has_skill = (technique_dir / "SKILL.md").exists() or any(
+ technique_dir.glob("*.toml")
+ )
+ if has_skill:
+ current_techniques.add(technique_dir.name)
+
+ # Find existing dwt_ prefixed folders in skills directory
+ existing_dwt_folders: set[str] = set()
+ if skills_dir.exists():
+ for item in skills_dir.iterdir():
+ if item.is_dir() and item.name.startswith(TECHNIQUE_PREFIX):
+ # Extract the technique name without prefix
+ technique_name = item.name[len(TECHNIQUE_PREFIX) :]
+ existing_dwt_folders.add(technique_name)
+
+ # Remove stale dwt_ folders (no longer in techniques)
+ stale_techniques = existing_dwt_folders - current_techniques
+ for stale_name in stale_techniques:
+ stale_dir = skills_dir / f"{TECHNIQUE_PREFIX}{stale_name}"
+ try:
+ shutil.rmtree(stale_dir)
+ removed_count += 1
+ except FileNotFoundError:
+ # Directory was already removed (race condition), skip
+ pass
+
+ # Copy/update current techniques
+ for technique_name in current_techniques:
+ source_dir = techniques_dir / technique_name
+ dest_dir = skills_dir / f"{TECHNIQUE_PREFIX}{technique_name}"
+
+ # Convert SKILL.md to platform-specific format if needed
+ _copy_technique(source_dir, dest_dir, adapter)
+ synced_count += 1
+
+ return synced_count, removed_count
+
+
+def _copy_technique(source_dir: Path, dest_dir: Path, adapter: AgentAdapter) -> None:
+ """
+ Copy a technique folder to the destination with platform-specific handling.
+
+ Args:
+ source_dir: Source technique directory
+ dest_dir: Destination directory in platform skills folder
+ adapter: Agent adapter for platform-specific handling
+ """
+ # Remove existing destination if present
+ if dest_dir.exists():
+ shutil.rmtree(dest_dir)
+
+ # Copy the entire directory
+ shutil.copytree(source_dir, dest_dir)
+ fix_permissions(dest_dir)
+
+ # Handle Gemini-specific conversion (SKILL.md -> index.toml)
+ if adapter.name == "gemini":
+ skill_md = dest_dir / "SKILL.md"
+ if skill_md.exists():
+ _convert_skill_md_to_toml(skill_md, dest_dir / "index.toml")
+ skill_md.unlink()
+
+
+def _convert_skill_md_to_toml(skill_md: Path, toml_path: Path) -> None:
+ """
+ Convert a SKILL.md file to Gemini's TOML format.
+
+ This is a simple conversion that extracts the frontmatter and content.
+
+ Args:
+ skill_md: Path to the SKILL.md file
+ toml_path: Path to write the TOML file
+ """
+ content = skill_md.read_text()
+
+ # Parse frontmatter
+ name = ""
+ description = ""
+ body = content
+
+ if content.startswith("---"):
+ parts = content.split("---", 2)
+ if len(parts) >= 3:
+ frontmatter = parts[1].strip()
+ body = parts[2].strip()
+
+ # Simple YAML parsing for name and description
+ for line in frontmatter.split("\n"):
+ if line.startswith("name:"):
+ name = line.split(":", 1)[1].strip().strip('"\'')
+ elif line.startswith("description:"):
+ description = line.split(":", 1)[1].strip().strip('"\'')
+
+ # Escape special characters in description for TOML
+ description = description.replace("\\", "\\\\").replace('"', '\\"')
+
+ # Write TOML format (matches Gemini CLI expected format)
+ toml_content = f'''description = "{description}"
+
+prompt = """
+{body}
+"""
+'''
+ toml_path.write_text(toml_content)
+
+
@click.command()
@click.option(
"--path",
@@ -117,7 +253,6 @@ def sync_skills(project_path: Path) -> None:
# Sync each platform
generator = SkillGenerator()
stats = {"platforms": 0, "skills": 0, "hooks": 0}
- synced_adapters: list[AgentAdapter] = []
for platform_name in platforms:
try:
@@ -183,8 +318,29 @@ def sync_skills(project_path: Path) -> None:
except Exception as e:
console.print(f" [red]✗[/red] Failed to sync skill permissions: {e}")
+ # Sync techniques to platform
+ techniques_dir = deepwork_dir / "techniques"
+ if techniques_dir.exists():
+ console.print(" [dim]•[/dim] Syncing techniques...")
+ try:
+ synced, removed = sync_techniques_to_platform(
+ techniques_dir, skills_dir, adapter
+ )
+ stats["techniques_synced"] = stats.get("techniques_synced", 0) + synced
+ stats["techniques_removed"] = stats.get("techniques_removed", 0) + removed
+ if synced > 0 or removed > 0:
+ msg_parts = []
+ if synced > 0:
+ msg_parts.append(f"{synced} synced")
+ if removed > 0:
+ msg_parts.append(f"{removed} removed")
+ console.print(f" [green]✓[/green] Techniques: {', '.join(msg_parts)}")
+ else:
+ console.print(" [dim]•[/dim] No techniques to sync")
+ except Exception as e:
+ console.print(f" [red]✗[/red] Failed to sync techniques: {e}")
+
stats["platforms"] += 1
- synced_adapters.append(adapter)
# Summary
console.print()
@@ -199,13 +355,9 @@ def sync_skills(project_path: Path) -> None:
table.add_row("Total skills", str(stats["skills"]))
if stats["hooks"] > 0:
table.add_row("Hooks synced", str(stats["hooks"]))
+ if stats.get("techniques_synced", 0) > 0:
+ table.add_row("Techniques synced", str(stats["techniques_synced"]))
+ if stats.get("techniques_removed", 0) > 0:
+ table.add_row("Techniques removed", str(stats["techniques_removed"]))
console.print(table)
- console.print()
-
- # Show reload instructions for each synced platform
- if synced_adapters and stats["skills"] > 0:
- console.print("[bold]To use the new skills:[/bold]")
- for adapter in synced_adapters:
- console.print(f" [cyan]{adapter.display_name}:[/cyan] {adapter.reload_instructions}")
- console.print()
diff --git a/src/deepwork/standard_jobs/deepwork_jobs/job.yml b/src/deepwork/standard_jobs/deepwork_jobs/job.yml
index 1cb38621..e0ff0c04 100644
--- a/src/deepwork/standard_jobs/deepwork_jobs/job.yml
+++ b/src/deepwork/standard_jobs/deepwork_jobs/job.yml
@@ -1,5 +1,5 @@
name: deepwork_jobs
-version: "1.0.0"
+version: "1.1.0"
summary: "Creates and manages multi-step AI workflows. Use when defining, implementing, or improving DeepWork jobs."
description: |
Core commands for managing DeepWork jobs. These commands help you define new multi-step
@@ -7,7 +7,7 @@ description: |
The `new_job` workflow guides you through defining and implementing a new job by
asking structured questions about your workflow, understanding each step's inputs and outputs,
- reviewing the specification, and generating all necessary files.
+ reviewing the specification, verifying required techniques, and generating all necessary files.
The `learn` skill reflects on conversations where DeepWork jobs were run, identifies
confusion or inefficiencies, and improves job instructions. It also captures bespoke
@@ -15,13 +15,16 @@ description: |
workflows:
- name: new_job
- summary: "Create a new DeepWork job from scratch through definition, review, and implementation"
+ summary: "Create a new DeepWork job from scratch through definition, review, tools verification, and implementation"
steps:
- define
- review_job_spec
+ - tools
- implement
changelog:
+ - version: "1.1.0"
+ changes: "Added tools step to new_job workflow for verifying and documenting techniques; implement step no longer creates directory structure (define does this)"
- 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"
@@ -87,9 +90,30 @@ steps:
- "**Findings Addressed**: Were all failed criteria addressed by the main agent?"
- "**Validation Loop Complete**: Did the review-fix cycle continue until all criteria passed?"
+ - id: tools
+ name: "Verify and Document Techniques"
+ description: "Verifies required techniques are available and documents how to use them. Use after job spec review to ensure implementation can succeed."
+ instructions_file: steps/tools.md
+ inputs:
+ - file: job.yml
+ from_step: review_job_spec
+ outputs:
+ - .deepwork/techniques/
+ dependencies:
+ - review_job_spec
+ quality_criteria:
+ - "**Tasks Analyzed**: Were all job steps reviewed to identify required techniques (CLI tools, MCP servers, browser extensions, etc.)?"
+ - "**Parallel Sub-Agents**: Were parallel sub-agents spawned for each technique requiring tooling?"
+ - "**Open Source Preferred**: Were open source/free tools preferred when no existing capability was available?"
+ - "**Had Working Technique**: Does each required technique have a working solution (original tool or alternative)?"
+ - "**Technique Created**: Was a technique folder created in `.deepwork/techniques/` for each technique (e.g., making_pdfs/, not pandoc/)?"
+ - "**SKILL.md Format**: Does each technique folder contain a SKILL.md file following the Claude Skills format?"
+ - "**Assets Included**: Are helper scripts and assets stored alongside SKILL.md in the technique folder?"
+ - "**Sync Complete**: Was `deepwork sync` run to sync techniques to platform skill directories?"
+
- 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."
+ description: "Generates step instruction files and syncs slash commands from the job.yml specification. Use after tools verification passes."
instructions_file: steps/implement.md
inputs:
- file: job.yml
@@ -98,6 +122,7 @@ steps:
- steps/
dependencies:
- review_job_spec
+ - tools
quality_criteria:
- "**Directory Structure**: Is `.deepwork/jobs/[job_name]/` created correctly?"
- "**Complete Instructions**: Are ALL step instruction files complete (not stubs or placeholders)?"
@@ -105,13 +130,14 @@ steps:
- "**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\"?"
+ - "**Techniques Referenced**: Do steps requiring external tools reference the appropriate techniques from `.deepwork/techniques/`?"
- "**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."
- 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."
+ description: "Analyzes conversation history to improve job instructions, techniques, and capture learnings. Use after running a job to refine it."
instructions_file: steps/learn.md
exposed: true
inputs:
@@ -119,17 +145,20 @@ steps:
description: "Name of the job that was run (optional - will auto-detect from conversation)"
outputs:
- AGENTS.md
+ - .deepwork/techniques/
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?"
+ - "**Learnings Classified**: Were learnings classified as generalizable, technique-related, or bespoke?"
- "**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?"
+ - "**Techniques Created/Updated (if applicable)**: Were new techniques created or existing ones improved based on tool usage learnings?"
- "**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?"
- - "**Sync Complete**: Has `deepwork sync` been run if instructions were modified?"
+ - "**Sync Complete**: Has `deepwork sync` been run if instructions or techniques were modified?"
diff --git a/src/deepwork/standard_jobs/deepwork_jobs/steps/implement.md b/src/deepwork/standard_jobs/deepwork_jobs/steps/implement.md
index bf1683b1..d4dc81d6 100644
--- a/src/deepwork/standard_jobs/deepwork_jobs/steps/implement.md
+++ b/src/deepwork/standard_jobs/deepwork_jobs/steps/implement.md
@@ -2,34 +2,15 @@
## Objective
-Generate the DeepWork job directory structure and instruction files for each step based on the validated `job.yml` specification from the review_job_spec step.
+Generate step instruction files for each step based on the validated `job.yml` specification from the review_job_spec step.
## Task
-Read the `job.yml` specification file and create all the necessary files to make the job functional, including directory structure and step instruction files. Then sync the commands to make them available.
+Read the `job.yml` specification file and create all the necessary step instruction files to make the job functional. Then sync the commands to make them available.
-### Step 1: Create Directory Structure Using Script
+**Note:** The `define` step already creates the directory structure using `make_new_job.sh`, so you don't need to create directories here.
-Run the `make_new_job.sh` script to create the standard directory structure:
-
-```bash
-.deepwork/jobs/deepwork_jobs/make_new_job.sh [job_name]
-```
-
-This creates:
-- `.deepwork/jobs/[job_name]/` - Main job directory
-- `.deepwork/jobs/[job_name]/steps/` - Step instruction files
-- `.deepwork/jobs/[job_name]/hooks/` - Custom validation scripts (with .gitkeep)
-- `.deepwork/jobs/[job_name]/templates/` - Example file formats (with .gitkeep)
-- `.deepwork/jobs/[job_name]/AGENTS.md` - Job management guidance
-
-**Note**: If the directory already exists (e.g., job.yml was created by define step), you can skip this step or manually create the additional directories:
-```bash
-mkdir -p .deepwork/jobs/[job_name]/hooks .deepwork/jobs/[job_name]/templates
-touch .deepwork/jobs/[job_name]/hooks/.gitkeep .deepwork/jobs/[job_name]/templates/.gitkeep
-```
-
-### Step 2: Read and Validate the Specification
+### Step 1: Read and Validate the Specification
1. **Locate the job.yml file**
- Read `.deepwork/jobs/[job_name]/job.yml` from the review_job_spec step
@@ -46,7 +27,7 @@ touch .deepwork/jobs/[job_name]/hooks/.gitkeep .deepwork/jobs/[job_name]/templat
- List of all steps with their details
- Understand the workflow structure
-### Step 3: Generate Step Instruction Files
+### Step 2: Generate Step Instruction Files
For each step in the job.yml, create a comprehensive instruction file at `.deepwork/jobs/[job_name]/steps/[step_id].md`.
@@ -70,6 +51,7 @@ For each step in the job.yml, create a comprehensive instruction file at `.deepw
5. **Quality over quantity** - Detailed, actionable instructions are better than vague ones
6. **Align with stop hooks** - If the step has `stop_hooks` defined, ensure the quality criteria in the instruction file match the validation criteria in the hooks
7. **Ask structured questions** - When a step has user inputs, the instructions MUST explicitly tell the agent to "ask structured questions" using the AskUserQuestion tool to gather that information. Never use generic phrasing like "ask the user" - always use "ask structured questions"
+8. **Reference techniques** - When a step requires external tools, include a reference to the relevant technique created in the `tools` step. See the section below on "Incorporating Techniques"
### Handling Stop Hooks
@@ -109,11 +91,55 @@ Step instructions can include additional `.md` files in the `steps/` directory f
See `.deepwork/jobs/deepwork_jobs/steps/supplemental_file_references.md` for detailed documentation and examples.
-### Step 4: Verify job.yml Location
+### Incorporating Techniques
+
+The `tools` step (which runs before `implement`) creates reusable techniques in `.deepwork/techniques/`. When generating step instructions, **reference these techniques** for any step that requires external tools.
+
+Techniques are synced to platform skill directories with a `dwt_` prefix (e.g., `making_pdfs` becomes `/dwt_making_pdfs`), so agents can invoke them directly.
+
+**How to incorporate techniques:**
+
+1. **Check what techniques exist:**
+ ```bash
+ ls .deepwork/techniques/
+ ```
+
+2. **Reference relevant techniques in step instructions:**
+ When a step uses an external tool (e.g., PDF generation, image processing), add a reference like:
+
+ ```markdown
+ ## Required Techniques
+
+ This step requires external tools. Use the following techniques:
+ - `/dwt_making_pdfs` - How to generate PDF output
+ - `/dwt_resizing_images` - How to resize and optimize images
+
+ See `.deepwork/techniques/[technique_name]/SKILL.md` for detailed usage instructions.
+ ```
+
+3. **Include key commands inline when helpful:**
+ For frequently-used commands, you can quote the essential invocation from the technique:
+
+ ```markdown
+ To convert markdown to PDF, use:
+ ```bash
+ pandoc input.md -o output.pdf --pdf-engine=xelatex
+ ```
+ See `/dwt_making_pdfs` (or `.deepwork/techniques/making_pdfs/SKILL.md`) for full documentation and troubleshooting.
+ ```
+
+**Why this matters:**
+- Step instructions stay focused on workflow logic
+- Techniques are documented once and synced to all platforms
+- Agents can invoke techniques directly as skills (e.g., `/dwt_making_pdfs`)
+- If techniques change, only the `.deepwork/techniques/` folder needs updating
+- New users can refer to technique SKILL.md files for installation help
+
+### Step 3: Verify job.yml Location
Verify that `job.yml` is in the correct location at `.deepwork/jobs/[job_name]/job.yml`. The define and review_job_spec steps should have created and validated it. If for some reason it's not there, you may need to create or move it.
-### Step 5: Sync Skills
+### Step 4: Sync Skills
Run `deepwork sync` to generate the skills for this job:
@@ -126,11 +152,11 @@ This will:
- Generate skills for each step
- Make the skills available in `.claude/skills/` (or appropriate platform directory)
-### Step 6: Relay Reload Instructions
+### Step 5: Relay Reload Instructions
After running `deepwork sync`, look at the "To use the new skills" section in the output. **Relay these exact reload instructions to the user** so they know how to pick up the new skills. Don't just reference the sync output - tell them directly what they need to do (e.g., "Type 'exit' then run 'claude --resume'" for Claude Code, or "Run '/memory refresh'" for Gemini CLI).
-### Step 7: Consider Rules for the New Job
+### Step 6: Consider Rules for the New Job
After implementing the job, consider whether there are **rules** that would help enforce quality or consistency when working with this job's domain.
@@ -219,10 +245,11 @@ Before marking this step complete, ensure:
- [ ] job.yml validated and copied to job directory
- [ ] All step instruction files created
- [ ] Each instruction file is complete and actionable
+- [ ] Steps requiring external tools reference techniques from `.deepwork/techniques/`
- [ ] `deepwork sync` executed successfully
- [ ] Skills generated in platform directory
- [ ] User informed to follow reload instructions from `deepwork sync`
-- [ ] Considered whether rules would benefit this job (Step 7)
+- [ ] Considered whether rules would benefit this job (Step 6)
- [ ] If rules suggested, offered to run `/deepwork_rules.define`
## Quality Criteria
@@ -233,6 +260,7 @@ Before marking this step complete, ensure:
- Output examples are provided in each instruction file
- Quality criteria defined for each step
- Steps with user inputs explicitly use "ask structured questions" phrasing
+- Steps requiring external tools reference the appropriate techniques from `.deepwork/techniques/`
- Sync completed successfully
- Skills available for use
- Thoughtfully considered relevant rules for the job domain
diff --git a/src/deepwork/standard_jobs/deepwork_jobs/steps/learn.md b/src/deepwork/standard_jobs/deepwork_jobs/steps/learn.md
index 3fddf37d..d83a592e 100644
--- a/src/deepwork/standard_jobs/deepwork_jobs/steps/learn.md
+++ b/src/deepwork/standard_jobs/deepwork_jobs/steps/learn.md
@@ -75,6 +75,16 @@ For each learning identified, determine if it is:
- "Quality criterion 'Visualization' needs clearer requirements"
- "Documents need a section for action items"
+**Technique-Related** (should improve or create techniques):
+- Improvements to how external tools are used
+- Better installation or usage instructions
+- New tools discovered during execution
+- Workarounds or troubleshooting tips
+- Examples:
+ - "The PDF generation command needs an extra flag for better formatting"
+ - "Found a better tool for web scraping that handles dynamic content"
+ - "Installation steps needed adjustment for macOS"
+
**Bespoke** (should go in AGENTS.md):
- Specific to THIS project/codebase/run
- Depends on local conventions or structure
@@ -197,6 +207,73 @@ quality_criteria:
description: Include Mermaid.js charts showing spend breakdown by service and month-over-month trend
```
+### Step 4.6: Create/Update Techniques (Technique-Related Learnings)
+
+If technique-related learnings were identified, update or create techniques in `.deepwork/techniques/`:
+
+1. **For existing techniques** (update):
+ - Locate the technique folder: `.deepwork/techniques/[technique_name]/`
+ - Update the `SKILL.md` file with improvements:
+ - Better usage examples
+ - Additional command-line options
+ - Troubleshooting tips discovered during execution
+ - Workarounds for edge cases
+
+2. **For new techniques** (create):
+ - Create a new folder: `.deepwork/techniques/[technique_name]/`
+ - Create a `SKILL.md` file following the Claude Skills format:
+ ```markdown
+ ---
+ name: technique_name
+ description: "Brief description of what this technique accomplishes"
+ ---
+
+ # Technique Name
+
+ ## Purpose
+ What this technique accomplishes and when to use it.
+
+ ## Tool
+ - **Name**: Tool name
+ - **Type**: CLI tool / MCP server / Browser extension / API
+ - **Version**: Known working version
+
+ ## Installation
+ [Installation instructions for different platforms]
+
+ ## Verification
+ [How to verify the tool is working]
+
+ ## Usage
+ [Usage examples and common options]
+
+ ## Troubleshooting
+ [Common issues and solutions]
+
+ ## Alternatives Considered
+ [Other tools that were considered]
+ ```
+ - Include any helper scripts or assets in the technique folder
+
+3. **After updating/creating techniques**, run `deepwork sync` to sync them to platform skill directories with the `dwt_` prefix.
+
+**Example technique update:**
+```markdown
+# Before (in SKILL.md)
+## Usage
+```bash
+pandoc input.md -o output.pdf
+```
+
+# After (improved based on learnings)
+## Usage
+```bash
+pandoc input.md -o output.pdf --pdf-engine=xelatex -V geometry:margin=1in
+```
+
+**Note**: The `--pdf-engine=xelatex` flag is required for Unicode support. The margin setting prevents text from running off the page.
+```
+
### Step 5: Create/Update AGENTS.md (Bespoke Learnings)
The AGENTS.md file captures project-specific knowledge that helps future agent runs.
@@ -264,13 +341,15 @@ When adding entries to AGENTS.md, prefer these patterns:
- Conversation has been analyzed for job executions
- Points of confusion and inefficiency are identified
-- Learnings are correctly classified (generalizable vs bespoke)
+- Learnings are correctly classified (generalizable vs technique-related vs bespoke)
- Job instructions updated for generalizable improvements
- Instructions are concise - no redundancy or unnecessary verbosity
- Shared/lengthy content extracted into referenced files where appropriate
+- Techniques created/updated for technique-related improvements
- AGENTS.md created/updated with bespoke learnings
- File references used instead of duplicating content
- AGENTS.md is in the correct folder (the deepest common folder for the topic)
+- `deepwork sync` run if instructions or techniques were modified
- When all criteria are met, include `✓ Quality Criteria Met`
## Example Dialog
diff --git a/src/deepwork/standard_jobs/deepwork_jobs/steps/tools.md b/src/deepwork/standard_jobs/deepwork_jobs/steps/tools.md
new file mode 100644
index 00000000..1a431fae
--- /dev/null
+++ b/src/deepwork/standard_jobs/deepwork_jobs/steps/tools.md
@@ -0,0 +1,216 @@
+# Verify and Document Techniques
+
+## Objective
+
+Verify that all external tools and capabilities required by the job are available and working, find alternatives if needed, and create reusable **techniques** for future reference.
+
+## Task
+
+Analyze the job specification to determine what techniques are needed, then spawn parallel sub-agents to test, configure, and document each technique.
+
+### Step 1: Analyze the Job for Required Techniques
+
+Read the `job.yml` file and examine each step to identify tasks that require external tools or capabilities beyond the agent's built-in abilities.
+
+**Look for steps that involve:**
+- File format conversion (PDF, DOCX, HTML, etc.)
+- Data processing (CSV, JSON, XML transformations)
+- Media manipulation (images, audio, video)
+- Web browsing or site access (via browser extensions like Chrome MCP)
+- External API calls or web requests
+- Build processes (compilers, bundlers)
+- Testing frameworks
+- Database operations
+- Container or virtualization tools
+
+**Types of tools and capabilities to consider:**
+- **CLI tools**: Command-line programs (pandoc, ffmpeg, imagemagick, etc.)
+- **MCP servers**: Model Context Protocol servers that extend agent capabilities (browser control, database access, etc.)
+- **Browser extensions**: Chrome extensions or similar for web interaction
+- **Language runtimes**: Python, Node.js, Ruby, etc. with specific packages
+- **External services**: APIs that require authentication or setup
+
+**Tool Selection Principle:**
+When no tool is currently available for a technique, **prefer open source and free tools** by default. Only suggest paid or proprietary tools if the user explicitly requests them or if no viable free alternative exists.
+
+**For each step, create a requirements list:**
+- What the step needs to accomplish
+- What external tools or capabilities might be required
+- What the expected input/output formats are
+
+### Step 2: Spawn Parallel Sub-Agents for Each Technique
+
+For each technique you identified, spawn a sub-agent **in parallel** to handle testing and documentation. This allows all techniques to be verified concurrently.
+
+**Sub-agent prompt template (customize for each technique):**
+
+```
+You are verifying and documenting a technique for the "[TECHNIQUE_NAME]" process in a DeepWork job.
+
+## Technique Requirement
+
+[Describe what this specific technique needs to accomplish]
+
+## Your Tasks
+
+1. **Test if a tool exists** - Check if a tool is available that can accomplish this technique
+2. **Verify it works** - Run a simple test to confirm functionality
+3. **Find alternatives if needed** - If the tool is missing or broken, research and test alternatives until you have a working solution. **Prefer open source and free tools** by default; only suggest paid/proprietary tools if explicitly requested or no viable free alternative exists.
+4. **Create the technique** - Create a folder in `.deepwork/techniques/[technique_name]/` with:
+ - `SKILL.md` - The main technique skill file following the Claude Skills format:
+ ```markdown
+ ---
+ name: technique_name
+ description: "Brief description of what this technique accomplishes"
+ ---
+
+ # Technique Name
+
+ ## Purpose
+ What this technique accomplishes and when to use it.
+
+ ## Tool
+ - **Name**: Tool name (e.g., pandoc, playwright)
+ - **Type**: CLI tool / MCP server / Browser extension / API
+ - **Version**: Known working version
+
+ ## Installation
+
+ ### macOS
+ ```bash
+ brew install tool-name
+ ```
+
+ ### Ubuntu/Debian
+ ```bash
+ apt-get install tool-name
+ ```
+
+ ### pip/npm (if applicable)
+ ```bash
+ pip install tool-name
+ ```
+
+ ## Verification
+ ```bash
+ tool-name --version
+ ```
+
+ ## Usage
+
+ ### Basic Example
+ ```bash
+ tool-name input.md -o output.pdf
+ ```
+
+ ### Common Options
+ - `-o, --output`: Output file path
+ - Other relevant options...
+
+ ## Troubleshooting
+ Common issues and solutions.
+
+ ## Alternatives Considered
+ - Alternative 1: Why not chosen
+ - Alternative 2: Why not chosen
+ ```
+ - Any helper scripts or assets the technique needs (e.g., `convert.py`, `template.html`)
+
+## Output Location
+
+Create the technique in: `.deepwork/techniques/[technique_name]/`
+
+Use descriptive, process-focused names like `making_pdfs`, `accessing_websites`, `creating_charts` (NOT tool names like `pandoc`, `playwright`).
+
+## Success Criteria
+
+- The technique has a working tool
+- Created `.deepwork/techniques/[technique_name]/SKILL.md`
+- Included any necessary helper scripts or assets in the same folder
+```
+
+**Example:** If you identified 3 techniques (making PDFs, accessing websites, creating charts), spawn 3 sub-agents in parallel:
+- Sub-agent 1: "making_pdfs" technique
+- Sub-agent 2: "accessing_websites" technique
+- Sub-agent 3: "creating_charts" technique
+
+### Step 3: Review Sub-Agent Outputs
+
+After all sub-agents complete:
+
+1. **Verify all techniques are covered** - Check that each identified need has a technique folder
+2. **Spot-check the documentation** - Ensure the SKILL.md files are complete and accurate
+3. **Verify tools work together** - If techniques depend on each other, confirm compatibility
+
+### Step 4: Run Sync
+
+After all techniques are created, run `deepwork sync` to copy them to the platform skill directories (`.claude/skills/`, `.gemini/skills/`) with the `dwt_` prefix.
+
+## Example
+
+For a job that creates research reports from web sources:
+
+**Step 1 output (your analysis):**
+```
+Required techniques:
+1. Accessing websites - Need to browse and extract data from web pages
+2. Creating charts - Need to generate visualizations from data
+3. Making PDFs - Need to convert markdown reports to PDF format
+```
+
+**Step 2:** Spawn 3 parallel sub-agents, one for each technique
+
+**Step 3:** Verify all sub-agents created their techniques:
+```
+.deepwork/techniques/
+├── accessing_websites/
+│ └── SKILL.md
+├── creating_charts/
+│ ├── SKILL.md
+│ └── chart_helper.py
+└── making_pdfs/
+ └── SKILL.md
+```
+
+**Step 4:** Run `deepwork sync` to sync techniques to platforms
+
+## Output
+
+After completing this step, you should have:
+
+1. **techniques/ directory** with technique folders:
+ ```
+ .deepwork/techniques/
+ ├── [technique_1]/
+ │ ├── SKILL.md
+ │ └── [optional assets]
+ ├── [technique_2]/
+ │ ├── SKILL.md
+ │ └── [optional assets]
+ └── ...
+ ```
+
+2. **Synced skills** in platform directories (after running `deepwork sync`):
+ ```
+ .claude/skills/
+ ├── dwt_[technique_1]/
+ │ └── SKILL.md
+ └── dwt_[technique_2]/
+ └── SKILL.md
+ ```
+
+3. **Confidence that all techniques work** and the job can be implemented successfully
+
+## Quality Criteria
+
+- All job steps have been analyzed for technique requirements
+- Parallel sub-agents were spawned for each technique requiring tooling
+- Every required tool has been tested and verified working
+- Each required technique has a working solution (original tool or alternative)
+- Open source/free tools were preferred when no existing capability was available
+- Techniques are organized by PROCESS name, not by tool name
+- Each technique folder contains a SKILL.md following the Claude Skills format
+- Helper scripts and assets are stored alongside SKILL.md in the technique folder
+- All techniques have been verified to work together
+- `deepwork sync` was run to sync techniques to platform skill directories
+- When all criteria are met, include `✓ Quality Criteria Met` in your response
diff --git a/src/deepwork/techniques/AGENTS.md b/src/deepwork/techniques/AGENTS.md
new file mode 100644
index 00000000..55b71a15
--- /dev/null
+++ b/src/deepwork/techniques/AGENTS.md
@@ -0,0 +1,150 @@
+# DeepWork Techniques
+
+This folder contains reusable **techniques** - documented processes for accomplishing specific tasks using external tools. Techniques follow the Claude Skills format and are automatically synced to AI agent configuration directories (`.claude/skills/`, `.gemini/skills/`) with a `dwt_` prefix.
+
+## Purpose
+
+Techniques capture knowledge about how to accomplish processes that require external tools, MCP servers, or specific workflows. They are:
+
+- **Reusable**: Once created, a technique can be used across multiple jobs
+- **Documented**: Each technique includes installation and usage instructions
+- **Portable**: Techniques are synced to all configured AI platforms
+
+## Format
+
+Each technique is a folder containing skill files that follow the Claude Skills format:
+
+```
+techniques/
+├── AGENTS.md # This file
+├── making_pdfs/
+│ └── SKILL.md # Main technique skill
+├── accessing_websites/
+│ └── SKILL.md
+└── [technique_name]/
+ └── SKILL.md
+```
+
+### SKILL.md Format (Claude Skills)
+
+```markdown
+---
+name: technique_name
+description: "Brief description of what this technique accomplishes"
+---
+
+# Technique Name
+
+## Purpose
+
+What this technique accomplishes and when to use it.
+
+## Tool
+
+- **Name**: Tool name (e.g., pandoc, playwright)
+- **Type**: CLI tool / MCP server / Browser extension / API
+- **Version**: Known working version
+
+## Installation
+
+How to install the required tool:
+
+### macOS
+\`\`\`bash
+brew install tool-name
+\`\`\`
+
+### Ubuntu/Debian
+\`\`\`bash
+apt-get install tool-name
+\`\`\`
+
+### pip/npm
+\`\`\`bash
+pip install tool-name
+# or
+npm install -g tool-name
+\`\`\`
+
+## Verification
+
+How to verify the tool is installed correctly:
+
+\`\`\`bash
+tool-name --version
+\`\`\`
+
+## Usage
+
+### Basic Example
+
+\`\`\`bash
+tool-name input.md -o output.pdf
+\`\`\`
+
+### Common Options
+
+- `-o, --output`: Output file path
+- `-f, --format`: Output format
+
+### Example Workflow
+
+1. Prepare input files
+2. Run the tool
+3. Verify output
+
+## Troubleshooting
+
+Common issues and solutions:
+
+### Issue 1: Tool not found
+- Ensure tool is in PATH
+- Try reinstalling
+
+## Assets
+
+If this technique requires helper scripts or templates, they should be stored
+alongside the SKILL.md file:
+
+```
+technique_name/
+├── SKILL.md
+├── convert.py # Helper script
+└── template.html # Template file
+```
+
+Reference these assets using relative paths in the SKILL.md.
+
+## Alternatives Considered
+
+Other tools that could accomplish this process:
+- Alternative 1: Brief note on why not chosen
+- Alternative 2: Brief note on why not chosen
+```
+
+## Syncing
+
+Techniques are automatically synced by `deepwork sync`:
+
+1. Techniques from `.deepwork/techniques/` are copied to platform skill directories
+2. Folder names are prefixed with `dwt_` (e.g., `making_pdfs` becomes `dwt_making_pdfs`)
+3. Stale `dwt_` prefixed folders (no longer in techniques) are removed
+4. This ensures platform skills stay in sync with the techniques folder
+
+## Creating Techniques
+
+Techniques are created by the `deepwork_jobs` workflow:
+
+- **`/deepwork_jobs.tools`** step creates techniques when verifying tools for a job
+- **`/deepwork_jobs.learn`** step can refine existing techniques based on execution learnings
+
+You can also create techniques manually by adding a new folder with a `SKILL.md` file.
+
+## Invocation
+
+Once synced, techniques can be invoked as skills:
+
+- **Claude Code**: `/dwt_making_pdfs`
+- **Gemini CLI**: `/dwt_making_pdfs`
+
+The `dwt_` prefix indicates these are DeepWork-managed techniques.
diff --git a/tests/integration/test_install_flow.py b/tests/integration/test_install_flow.py
index d0638275..10b8442c 100644
--- a/tests/integration/test_install_flow.py
+++ b/tests/integration/test_install_flow.py
@@ -186,6 +186,61 @@ def test_install_is_idempotent(self, mock_claude_project: Path) -> None:
assert (claude_dir / "deepwork_jobs.define" / "SKILL.md").exists()
assert (claude_dir / "deepwork_jobs.learn" / "SKILL.md").exists()
+ def test_install_creates_techniques_directory(self, mock_claude_project: Path) -> None:
+ """Test that install creates the techniques directory with AGENTS.md."""
+ runner = CliRunner()
+
+ result = runner.invoke(
+ cli,
+ ["install", "--platform", "claude", "--path", str(mock_claude_project)],
+ catch_exceptions=False,
+ )
+
+ assert result.exit_code == 0
+ assert ".deepwork/techniques/ with AGENTS.md" in result.output
+
+ # Verify techniques directory was created
+ techniques_dir = mock_claude_project / ".deepwork" / "techniques"
+ assert techniques_dir.exists()
+
+ # Verify AGENTS.md was created
+ agents_file = techniques_dir / "AGENTS.md"
+ assert agents_file.exists()
+ content = agents_file.read_text()
+ assert "DeepWork Techniques" in content
+ assert "Claude Skills format" in content
+
+ def test_install_preserves_existing_techniques_directory(
+ self, mock_claude_project: Path
+ ) -> None:
+ """Test that install doesn't overwrite existing techniques directory."""
+ runner = CliRunner()
+
+ # Create a custom techniques directory before install
+ techniques_dir = mock_claude_project / ".deepwork" / "techniques"
+ techniques_dir.mkdir(parents=True)
+ custom_technique_dir = techniques_dir / "my_custom_technique"
+ custom_technique_dir.mkdir()
+ custom_skill = custom_technique_dir / "SKILL.md"
+ custom_content = """---
+name: my_custom_technique
+---
+Custom technique content.
+"""
+ custom_skill.write_text(custom_content)
+
+ result = runner.invoke(
+ cli,
+ ["install", "--platform", "claude", "--path", str(mock_claude_project)],
+ catch_exceptions=False,
+ )
+
+ assert result.exit_code == 0
+ assert ".deepwork/techniques/ already exists" in result.output
+
+ # Verify original content is preserved
+ assert custom_skill.read_text() == custom_content
+
def test_install_creates_rules_directory(self, mock_claude_project: Path) -> None:
"""Test that install creates the v2 rules directory with example templates."""
runner = CliRunner()
diff --git a/tests/unit/test_techniques_sync.py b/tests/unit/test_techniques_sync.py
new file mode 100644
index 00000000..52f7112e
--- /dev/null
+++ b/tests/unit/test_techniques_sync.py
@@ -0,0 +1,448 @@
+"""Unit tests for techniques sync functionality."""
+
+from pathlib import Path
+
+import pytest
+
+from deepwork.cli.sync import (
+ TECHNIQUE_PREFIX,
+ _convert_skill_md_to_toml,
+ _copy_technique,
+ sync_techniques_to_platform,
+)
+from deepwork.core.adapters import ClaudeAdapter, GeminiAdapter
+
+
+class TestSyncTechniquesToPlatform:
+ """Tests for sync_techniques_to_platform function."""
+
+ def test_sync_single_technique_to_claude(self, temp_dir: Path) -> None:
+ """Test syncing a single technique to Claude skills directory."""
+ # Setup
+ techniques_dir = temp_dir / ".deepwork" / "techniques"
+ skills_dir = temp_dir / ".claude" / "skills"
+ techniques_dir.mkdir(parents=True)
+ skills_dir.mkdir(parents=True)
+
+ # Create a technique
+ technique_dir = techniques_dir / "making_pdfs"
+ technique_dir.mkdir()
+ skill_content = """---
+name: making_pdfs
+description: "Convert documents to PDF format"
+---
+
+# Making PDFs
+
+This technique uses pandoc to convert markdown to PDF.
+"""
+ (technique_dir / "SKILL.md").write_text(skill_content)
+
+ adapter = ClaudeAdapter(project_root=temp_dir)
+
+ # Execute
+ synced, removed = sync_techniques_to_platform(techniques_dir, skills_dir, adapter)
+
+ # Verify
+ assert synced == 1
+ assert removed == 0
+ dest_dir = skills_dir / f"{TECHNIQUE_PREFIX}making_pdfs"
+ assert dest_dir.exists()
+ assert (dest_dir / "SKILL.md").exists()
+ assert (dest_dir / "SKILL.md").read_text() == skill_content
+
+ def test_sync_technique_with_assets(self, temp_dir: Path) -> None:
+ """Test syncing a technique that includes asset files."""
+ techniques_dir = temp_dir / ".deepwork" / "techniques"
+ skills_dir = temp_dir / ".claude" / "skills"
+ techniques_dir.mkdir(parents=True)
+ skills_dir.mkdir(parents=True)
+
+ # Create a technique with assets
+ technique_dir = techniques_dir / "chart_generation"
+ technique_dir.mkdir()
+ (technique_dir / "SKILL.md").write_text("---\nname: chart_generation\n---\n# Chart Gen")
+ (technique_dir / "generate_chart.py").write_text("#!/usr/bin/env python\nprint('chart')")
+ (technique_dir / "template.html").write_text("template")
+
+ adapter = ClaudeAdapter(project_root=temp_dir)
+
+ # Execute
+ synced, removed = sync_techniques_to_platform(techniques_dir, skills_dir, adapter)
+
+ # Verify all files are copied
+ assert synced == 1
+ dest_dir = skills_dir / f"{TECHNIQUE_PREFIX}chart_generation"
+ assert (dest_dir / "SKILL.md").exists()
+ assert (dest_dir / "generate_chart.py").exists()
+ assert (dest_dir / "template.html").exists()
+
+ def test_sync_multiple_techniques(self, temp_dir: Path) -> None:
+ """Test syncing multiple techniques at once."""
+ techniques_dir = temp_dir / ".deepwork" / "techniques"
+ skills_dir = temp_dir / ".claude" / "skills"
+ techniques_dir.mkdir(parents=True)
+ skills_dir.mkdir(parents=True)
+
+ # Create multiple techniques
+ for name in ["making_pdfs", "web_scraping", "image_processing"]:
+ technique_dir = techniques_dir / name
+ technique_dir.mkdir()
+ (technique_dir / "SKILL.md").write_text(f"---\nname: {name}\n---\n# {name}")
+
+ adapter = ClaudeAdapter(project_root=temp_dir)
+
+ # Execute
+ synced, removed = sync_techniques_to_platform(techniques_dir, skills_dir, adapter)
+
+ # Verify
+ assert synced == 3
+ assert removed == 0
+ for name in ["making_pdfs", "web_scraping", "image_processing"]:
+ assert (skills_dir / f"{TECHNIQUE_PREFIX}{name}").exists()
+
+ def test_removes_stale_techniques(self, temp_dir: Path) -> None:
+ """Test that stale dwt_ folders are removed."""
+ techniques_dir = temp_dir / ".deepwork" / "techniques"
+ skills_dir = temp_dir / ".claude" / "skills"
+ techniques_dir.mkdir(parents=True)
+ skills_dir.mkdir(parents=True)
+
+ # Create a technique
+ technique_dir = techniques_dir / "making_pdfs"
+ technique_dir.mkdir()
+ (technique_dir / "SKILL.md").write_text("---\nname: making_pdfs\n---\n# PDF")
+
+ # Create stale dwt_ folders (no longer in techniques)
+ stale_dir1 = skills_dir / f"{TECHNIQUE_PREFIX}old_technique"
+ stale_dir1.mkdir()
+ (stale_dir1 / "SKILL.md").write_text("stale")
+
+ stale_dir2 = skills_dir / f"{TECHNIQUE_PREFIX}another_old"
+ stale_dir2.mkdir()
+ (stale_dir2 / "SKILL.md").write_text("also stale")
+
+ adapter = ClaudeAdapter(project_root=temp_dir)
+
+ # Execute
+ synced, removed = sync_techniques_to_platform(techniques_dir, skills_dir, adapter)
+
+ # Verify
+ assert synced == 1
+ assert removed == 2
+ assert (skills_dir / f"{TECHNIQUE_PREFIX}making_pdfs").exists()
+ assert not stale_dir1.exists()
+ assert not stale_dir2.exists()
+
+ def test_updates_existing_technique(self, temp_dir: Path) -> None:
+ """Test that existing techniques are updated."""
+ techniques_dir = temp_dir / ".deepwork" / "techniques"
+ skills_dir = temp_dir / ".claude" / "skills"
+ techniques_dir.mkdir(parents=True)
+ skills_dir.mkdir(parents=True)
+
+ # Create existing dwt_ folder with old content
+ existing_dir = skills_dir / f"{TECHNIQUE_PREFIX}making_pdfs"
+ existing_dir.mkdir()
+ (existing_dir / "SKILL.md").write_text("old content")
+
+ # Create updated technique
+ technique_dir = techniques_dir / "making_pdfs"
+ technique_dir.mkdir()
+ new_content = "---\nname: making_pdfs\n---\n# Updated PDF technique"
+ (technique_dir / "SKILL.md").write_text(new_content)
+
+ adapter = ClaudeAdapter(project_root=temp_dir)
+
+ # Execute
+ synced, removed = sync_techniques_to_platform(techniques_dir, skills_dir, adapter)
+
+ # Verify content was updated
+ assert synced == 1
+ assert removed == 0
+ assert (skills_dir / f"{TECHNIQUE_PREFIX}making_pdfs" / "SKILL.md").read_text() == new_content
+
+ def test_ignores_non_dwt_folders(self, temp_dir: Path) -> None:
+ """Test that non-dwt_ prefixed folders are not touched."""
+ techniques_dir = temp_dir / ".deepwork" / "techniques"
+ skills_dir = temp_dir / ".claude" / "skills"
+ techniques_dir.mkdir(parents=True)
+ skills_dir.mkdir(parents=True)
+
+ # Create a technique
+ technique_dir = techniques_dir / "making_pdfs"
+ technique_dir.mkdir()
+ (technique_dir / "SKILL.md").write_text("---\nname: making_pdfs\n---\n# PDF")
+
+ # Create non-dwt_ folder (should not be touched)
+ other_dir = skills_dir / "my_custom_skill"
+ other_dir.mkdir()
+ (other_dir / "SKILL.md").write_text("custom skill")
+
+ adapter = ClaudeAdapter(project_root=temp_dir)
+
+ # Execute
+ synced, removed = sync_techniques_to_platform(techniques_dir, skills_dir, adapter)
+
+ # Verify other folder still exists
+ assert synced == 1
+ assert removed == 0
+ assert other_dir.exists()
+ assert (other_dir / "SKILL.md").read_text() == "custom skill"
+
+ def test_skips_directories_without_skill_file(self, temp_dir: Path) -> None:
+ """Test that directories without SKILL.md are not synced."""
+ techniques_dir = temp_dir / ".deepwork" / "techniques"
+ skills_dir = temp_dir / ".claude" / "skills"
+ techniques_dir.mkdir(parents=True)
+ skills_dir.mkdir(parents=True)
+
+ # Create valid technique
+ valid_dir = techniques_dir / "valid_technique"
+ valid_dir.mkdir()
+ (valid_dir / "SKILL.md").write_text("---\nname: valid\n---\n# Valid")
+
+ # Create invalid technique (no SKILL.md)
+ invalid_dir = techniques_dir / "invalid_technique"
+ invalid_dir.mkdir()
+ (invalid_dir / "README.md").write_text("not a skill")
+
+ adapter = ClaudeAdapter(project_root=temp_dir)
+
+ # Execute
+ synced, removed = sync_techniques_to_platform(techniques_dir, skills_dir, adapter)
+
+ # Verify only valid technique was synced
+ assert synced == 1
+ assert (skills_dir / f"{TECHNIQUE_PREFIX}valid_technique").exists()
+ assert not (skills_dir / f"{TECHNIQUE_PREFIX}invalid_technique").exists()
+
+ def test_handles_empty_techniques_dir(self, temp_dir: Path) -> None:
+ """Test handling when techniques directory is empty."""
+ techniques_dir = temp_dir / ".deepwork" / "techniques"
+ skills_dir = temp_dir / ".claude" / "skills"
+ techniques_dir.mkdir(parents=True)
+ skills_dir.mkdir(parents=True)
+
+ # Create a stale dwt_ folder
+ stale_dir = skills_dir / f"{TECHNIQUE_PREFIX}old"
+ stale_dir.mkdir()
+ (stale_dir / "SKILL.md").write_text("stale")
+
+ adapter = ClaudeAdapter(project_root=temp_dir)
+
+ # Execute
+ synced, removed = sync_techniques_to_platform(techniques_dir, skills_dir, adapter)
+
+ # Verify stale was removed
+ assert synced == 0
+ assert removed == 1
+ assert not stale_dir.exists()
+
+ def test_handles_nonexistent_techniques_dir(self, temp_dir: Path) -> None:
+ """Test handling when techniques directory doesn't exist."""
+ techniques_dir = temp_dir / ".deepwork" / "techniques"
+ skills_dir = temp_dir / ".claude" / "skills"
+ skills_dir.mkdir(parents=True)
+
+ # Create a stale dwt_ folder
+ stale_dir = skills_dir / f"{TECHNIQUE_PREFIX}old"
+ stale_dir.mkdir()
+
+ adapter = ClaudeAdapter(project_root=temp_dir)
+
+ # Execute
+ synced, removed = sync_techniques_to_platform(techniques_dir, skills_dir, adapter)
+
+ # Verify stale was removed even without techniques dir
+ assert synced == 0
+ assert removed == 1
+
+
+class TestGeminiTechniqueSync:
+ """Tests for Gemini-specific technique syncing."""
+
+ def test_converts_skill_md_to_toml(self, temp_dir: Path) -> None:
+ """Test that SKILL.md is converted to index.toml for Gemini."""
+ techniques_dir = temp_dir / ".deepwork" / "techniques"
+ skills_dir = temp_dir / ".gemini" / "skills"
+ techniques_dir.mkdir(parents=True)
+ skills_dir.mkdir(parents=True)
+
+ # Create a technique with SKILL.md
+ technique_dir = techniques_dir / "making_pdfs"
+ technique_dir.mkdir()
+ skill_content = """---
+name: making_pdfs
+description: "Convert documents to PDF format"
+---
+
+# Making PDFs
+
+This technique uses pandoc.
+"""
+ (technique_dir / "SKILL.md").write_text(skill_content)
+
+ adapter = GeminiAdapter(project_root=temp_dir)
+
+ # Execute
+ synced, removed = sync_techniques_to_platform(techniques_dir, skills_dir, adapter)
+
+ # Verify
+ assert synced == 1
+ dest_dir = skills_dir / f"{TECHNIQUE_PREFIX}making_pdfs"
+ assert dest_dir.exists()
+ # SKILL.md should be replaced with index.toml
+ assert not (dest_dir / "SKILL.md").exists()
+ assert (dest_dir / "index.toml").exists()
+
+ # Verify TOML content (Gemini format: description + prompt, no name)
+ toml_content = (dest_dir / "index.toml").read_text()
+ assert 'description = "Convert documents to PDF format"' in toml_content
+ assert 'prompt = """' in toml_content
+ assert "# Making PDFs" in toml_content
+ # Should not include name field
+ assert "name =" not in toml_content
+
+ def test_preserves_assets_for_gemini(self, temp_dir: Path) -> None:
+ """Test that asset files are preserved for Gemini."""
+ techniques_dir = temp_dir / ".deepwork" / "techniques"
+ skills_dir = temp_dir / ".gemini" / "skills"
+ techniques_dir.mkdir(parents=True)
+ skills_dir.mkdir(parents=True)
+
+ # Create a technique with assets
+ technique_dir = techniques_dir / "chart_generation"
+ technique_dir.mkdir()
+ (technique_dir / "SKILL.md").write_text("---\nname: charts\n---\n# Charts")
+ (technique_dir / "helper.py").write_text("print('helper')")
+
+ adapter = GeminiAdapter(project_root=temp_dir)
+
+ # Execute
+ synced, _ = sync_techniques_to_platform(techniques_dir, skills_dir, adapter)
+
+ # Verify assets are preserved
+ dest_dir = skills_dir / f"{TECHNIQUE_PREFIX}chart_generation"
+ assert (dest_dir / "index.toml").exists()
+ assert (dest_dir / "helper.py").exists()
+
+
+class TestConvertSkillMdToToml:
+ """Tests for _convert_skill_md_to_toml function."""
+
+ def test_converts_complete_frontmatter(self, temp_dir: Path) -> None:
+ """Test conversion with complete frontmatter."""
+ skill_md = temp_dir / "SKILL.md"
+ skill_md.write_text("""---
+name: my_technique
+description: "A useful technique"
+---
+
+# My Technique
+
+Content here.
+""")
+ toml_path = temp_dir / "index.toml"
+
+ _convert_skill_md_to_toml(skill_md, toml_path)
+
+ content = toml_path.read_text()
+ assert 'description = "A useful technique"' in content
+ assert 'prompt = """' in content
+ assert "# My Technique" in content
+ assert "Content here." in content
+ # Should not include name field (Gemini format)
+ assert "name =" not in content
+
+ def test_handles_missing_frontmatter(self, temp_dir: Path) -> None:
+ """Test conversion when frontmatter is missing."""
+ skill_md = temp_dir / "SKILL.md"
+ skill_md.write_text("# No Frontmatter\n\nJust content.")
+ toml_path = temp_dir / "index.toml"
+
+ _convert_skill_md_to_toml(skill_md, toml_path)
+
+ content = toml_path.read_text()
+ assert 'description = ""' in content
+ assert "# No Frontmatter" in content
+
+ def test_handles_quoted_values(self, temp_dir: Path) -> None:
+ """Test conversion with quoted YAML values."""
+ skill_md = temp_dir / "SKILL.md"
+ skill_md.write_text("""---
+name: 'single_quoted'
+description: "double_quoted"
+---
+
+Body
+""")
+ toml_path = temp_dir / "index.toml"
+
+ _convert_skill_md_to_toml(skill_md, toml_path)
+
+ content = toml_path.read_text()
+ assert 'description = "double_quoted"' in content
+ # Should not include name field (Gemini format)
+ assert "name =" not in content
+
+ def test_escapes_special_characters_in_description(self, temp_dir: Path) -> None:
+ """Test that special characters in description are escaped for TOML."""
+ skill_md = temp_dir / "SKILL.md"
+ skill_md.write_text("""---
+name: special_chars
+description: 'A "quoted" string with backslash \\ char'
+---
+
+Body content.
+""")
+ toml_path = temp_dir / "index.toml"
+
+ _convert_skill_md_to_toml(skill_md, toml_path)
+
+ content = toml_path.read_text()
+ # Backslash should be escaped to \\
+ # Quote should be escaped to \"
+ assert 'description = "A \\"quoted\\" string with backslash \\\\ char"' in content
+
+
+class TestCopyTechnique:
+ """Tests for _copy_technique function."""
+
+ def test_copies_all_files(self, temp_dir: Path) -> None:
+ """Test that all files are copied."""
+ source_dir = temp_dir / "source"
+ dest_dir = temp_dir / "dest"
+ source_dir.mkdir()
+
+ (source_dir / "SKILL.md").write_text("skill")
+ (source_dir / "helper.py").write_text("helper")
+ subdir = source_dir / "templates"
+ subdir.mkdir()
+ (subdir / "template.html").write_text("template")
+
+ adapter = ClaudeAdapter(project_root=temp_dir)
+ _copy_technique(source_dir, dest_dir, adapter)
+
+ assert (dest_dir / "SKILL.md").exists()
+ assert (dest_dir / "helper.py").exists()
+ assert (dest_dir / "templates" / "template.html").exists()
+
+ def test_replaces_existing_destination(self, temp_dir: Path) -> None:
+ """Test that existing destination is replaced."""
+ source_dir = temp_dir / "source"
+ dest_dir = temp_dir / "dest"
+ source_dir.mkdir()
+ dest_dir.mkdir()
+
+ # Existing content that should be replaced
+ (dest_dir / "old_file.txt").write_text("old")
+
+ # New content
+ (source_dir / "SKILL.md").write_text("new skill")
+
+ adapter = ClaudeAdapter(project_root=temp_dir)
+ _copy_technique(source_dir, dest_dir, adapter)
+
+ assert not (dest_dir / "old_file.txt").exists()
+ assert (dest_dir / "SKILL.md").exists()