deepwork_job reworked with the expert

Author: nhorton

.claude/skills/deepwork_jobs.define/SKILL.md

@@ -24,117 +24,54 @@ agent: deepwork-jobs
 
 ## Objective
 
-Create a `job.yml` specification file by thoroughly understanding the user's workflow requirements through structured questions.
+Create a `job.yml` specification file that defines the structure of a new DeepWork job by understanding the user's workflow requirements through interactive questions.
 
 ## Task
 
-Guide the user through defining a job specification by asking structured questions. **Do not attempt to create the specification without first fully understanding the user's needs.**
+Guide the user through defining a job specification by asking structured questions. The output is **only** the `job.yml` file - step instruction files are created in the `implement` step.
 
-The output of this step is **only** the `job.yml` file. Step instruction files are created in the `implement` step.
+### Process
 
-### Step 1: Understand the Job Purpose
+1. **Understand the job purpose**
+   - Ask structured questions about the overall goal, domain, and frequency
+   - Understand what success looks like and who the audience is
+   - Identify the major phases of the workflow
 
-Ask structured questions to understand what the user wants to accomplish:
+2. **Detect document-oriented workflows**
+   - Look for patterns: "report", "summary", "monthly", "for stakeholders"
+   - If detected, offer to create a doc spec for consistent quality
+   - Use `.deepwork/doc_specs/job_spec.md` as a reference example
 
-1. **What is the overall goal of this workflow?**
-   - What complex task are they trying to accomplish?
-   - What domain is this in? (e.g., research, marketing, development, reporting)
+3. **Define each step**
+   - For each phase, gather: purpose, inputs, outputs, dependencies
+   - Ask about output file paths and organization
+   - Consider whether steps need agent delegation
 
-2. **What does success look like?**
-   - What's the final deliverable or outcome?
-   - Who is the audience for the output?
+4. **Validate the workflow**
+   - Summarize the complete workflow
+   - Check for gaps in inputs/outputs between steps
+   - Confirm job name, summary, and version
 
-3. **What are the major phases?**
-   - What are the distinct stages from start to finish?
-   - Are there any dependencies between phases?
+5. **Create the job specification**
+   - Run `make_new_job.sh` to create directory structure:
+     ```bash
+     .deepwork/jobs/deepwork_jobs/make_new_job.sh [job_name]
+     ```
+   - Create `job.yml` at `.deepwork/jobs/[job_name]/job.yml`
 
-### Step 2: Detect Document-Oriented Workflows
+### Key Guidelines
 
-Check for document-focused patterns in the user's description:
-- Keywords: "report", "summary", "document", "monthly", "quarterly"
-- Final deliverable is a specific document type
-- Recurring documents with consistent structure
-
-**If detected**, inform the user and ask if they want to:
-- Create a doc spec for consistent document quality
-- Use an existing doc spec from `.deepwork/doc_specs/`
-- Skip doc spec and proceed with simple outputs
-
-See the expert's documentation on doc specs for the full schema and examples.
-
-### Step 3: Define Each Step
-
-For each major phase, gather:
-
-1. **Step Purpose**: What does this step accomplish?
-2. **Inputs**: User parameters or files from previous steps
-3. **Outputs**: Files or artifacts produced (see Work Product Guidelines below)
-4. **Dependencies**: Which previous steps must complete first?
-5. **Quality Criteria**: What makes a good vs. bad output?
-6. **Agent Delegation**: Should this step run in a forked context?
-
-#### Work Product Storage Guidelines
-
-Job outputs belong in the main repository directory structure, not in dot-directories.
-
-**Good patterns**:
-```
-competitive_research/competitors_list.md
-operations/reports/2026-01/spending_analysis.md
-```
-
-**Avoid**:
-```
-.deepwork/outputs/report.md    # Hidden in dot-directory
-output.md                       # Too generic
-```
-
-**Date in paths**: Include for periodic outputs (monthly reports), omit for living documents.
-
-**Supporting materials**: Place in `_dataroom` folder as peer to final output:
-```
-operations/reports/2026-01/spending_analysis.md
-operations/reports/2026-01/spending_analysis_dataroom/
-    raw_data.csv
-    notes.md
-```
-
-### Step 4: Validate the Workflow
-
-After gathering all information:
-
-1. **Review the flow** - Summarize and show how outputs feed into the next step
-2. **Check for gaps** - Missing inputs, unused outputs, circular dependencies
-3. **Confirm details** - Job name, summary (max 200 chars), description, version
-
-### Step 5: Create the Job Specification
-
-**First, create the directory structure**:
-```bash
-.deepwork/jobs/deepwork_jobs/make_new_job.sh [job_name]
-```
-
-**Then create `job.yml`** at `.deepwork/jobs/[job_name]/job.yml`
-
-Refer to the expert for the complete job.yml schema. Key validation rules:
-- Job name: lowercase, underscores only, no spaces
-- Version: semantic versioning (start with 1.0.0)
-- Summary: max 200 characters
-- File inputs: `from_step` must be in dependencies
-- At least one output per step
-
-**Templates**:
-- `.deepwork/jobs/deepwork_jobs/templates/job.yml.template` - Structure
-- `.deepwork/jobs/deepwork_jobs/templates/job.yml.example` - Complete example
+- **Ask structured questions** using the AskUserQuestion tool
+- **Work products go in main repo**, not `.deepwork/` (for discoverability)
+- **Use dates in paths** for periodic outputs that accumulate
+- **Use `_dataroom` folders** for supporting materials
+- Reference templates in `.deepwork/jobs/deepwork_jobs/templates/`
 
 ## Output
 
-The validated `job.yml` file at `.deepwork/jobs/[job_name]/job.yml`.
+Create `.deepwork/jobs/[job_name]/job.yml` following the doc spec at `.deepwork/doc_specs/job_spec.md`.
 
-After creating the file:
-1. Inform the user that the specification is complete
-2. Recommend they review the job.yml file
-3. Tell them to run `/deepwork_jobs.review_job_spec` next
+After creating the file, tell the user to run `/deepwork_jobs.review_job_spec` next.
 
 
 ### Job Context

.claude/skills/deepwork_jobs.implement/SKILL.md

@@ -28,108 +28,65 @@ Before proceeding, confirm these steps are complete:
 
 ## Objective
 
-Generate the DeepWork job directory structure and instruction files for each step based on the validated `job.yml` specification.
+Generate the step instruction files for each step based on the validated `job.yml` specification, then sync to create the slash commands.
 
 ## Task
 
-Read the `job.yml` specification and create all necessary files to make the job functional.
+Read the job.yml and create comprehensive instruction files for each step.
 
-### Step 1: Create Directory Structure
+### Process
 
-Run the setup script:
-```bash
-.deepwork/jobs/deepwork_jobs/make_new_job.sh [job_name]
-```
+1. **Create directory structure** (if needed)
+   ```bash
+   .deepwork/jobs/deepwork_jobs/make_new_job.sh [job_name]
+   ```
 
-This creates:
-- `.deepwork/jobs/[job_name]/steps/` - Step instruction files
-- `.deepwork/jobs/[job_name]/hooks/` - Validation scripts
-- `.deepwork/jobs/[job_name]/templates/` - Example file formats
-- `.deepwork/jobs/[job_name]/AGENTS.md` - Job management guidance
+2. **Read and validate the specification**
+   - Read `.deepwork/jobs/[job_name]/job.yml`
+   - Extract job name, description, and step details
+   - Understand the workflow structure
 
-**Note**: If directory already exists from define step, create missing subdirectories manually.
+3. **Generate step instruction files**
+   - Create `.deepwork/jobs/[job_name]/steps/[step_id].md` for each step
+   - Use templates in `.deepwork/jobs/deepwork_jobs/templates/` as reference
+   - Each file must include: Objective, Task, Process, Output Format, Quality Criteria
 
-### Step 2: Read and Validate the Specification
+4. **Sync skills**
+   ```bash
+   deepwork sync
+   ```
 
-1. Read `.deepwork/jobs/[job_name]/job.yml`
-2. Validate structure (name, version, summary, description, steps)
-3. Check dependencies are valid and non-circular
-4. Extract step details for instruction generation
+5. **Consider rules for the new job**
+   - Think about whether rules would help maintain quality
+   - If relevant, explain and offer to run `/deepwork_rules.define`
 
-### Step 3: Generate Step Instruction Files
+### Instruction File Guidelines
 
-Create `.deepwork/jobs/[job_name]/steps/[step_id].md` for each step.
+- **Be specific** - tailor to each step's purpose, not generic advice
+- **Provide examples** - show what good output looks like
+- **Include quality criteria** - how to verify the step is complete
+- **Use "ask structured questions"** - for steps that gather user input
+- **Align with hooks** - if step has hooks, match the validation criteria
 
-**Templates**:
-- `.deepwork/jobs/deepwork_jobs/templates/step_instruction.md.template` - Structure
-- `.deepwork/jobs/deepwork_jobs/templates/step_instruction.md.example` - Complete example
+### Templates Available
 
-**Guidelines**:
-
-1. **Use the job description** - It provides crucial context
-2. **Be specific** - Tailor instructions to each step's purpose
-3. **Provide examples** - Show what good output looks like
-4. **Explain the "why"** - Help understand the step's role in the workflow
-5. **Ask structured questions** - When a step has user inputs, MUST use this phrase
-6. **Align with hooks** - If step has `hooks` defined, match quality criteria
-
-**Handling Hooks**:
-
-If a step has hooks defined, the instruction file should:
-- Mirror the quality criteria that hooks will validate
-- Be explicit about what success looks like
-- Mention the `<promise>Quality Criteria Met</promise>` pattern when criteria are met
-
-### Step 4: Verify job.yml Location
-
-Confirm `job.yml` exists at `.deepwork/jobs/[job_name]/job.yml`.
-
-### Step 5: Sync Skills
-
-Run:
-```bash
-deepwork sync
-```
-
-This generates skills for each step in `.claude/skills/` (or platform-specific directory).
-
-### Step 6: Consider Rules
-
-After implementing, consider whether **rules** would help enforce quality.
-
-**What are rules?**
-Automated guardrails in `.deepwork/rules/` that trigger when files change.
-
-**When to suggest rules**:
-- Job produces outputs that other files depend on
-- Documentation should stay in sync with outputs
-- Quality checks should happen when certain files change
-
-**Examples**:
-| Job Type | Potential Rule |
-|----------|----------------|
-| API Design | Update docs when endpoints change |
-| Database Schema | Review migrations when schema changes |
-| Competitive Research | Update strategy when analysis changes |
-
-If a rule would help, explain what it would do and offer to run `/deepwork_rules.define`.
+- `job.yml.template` - Job specification structure
+- `step_instruction.md.template` - Step instruction file structure
+- `agents.md.template` - AGENTS.md file structure
+- Examples: `job.yml.example`, `step_instruction.md.example`
 
 ## Completion Checklist
 
-Before marking complete:
-- [ ] job.yml validated and in place
-- [ ] All step instruction files created (complete, not stubs)
+- [ ] All step instruction files created (not stubs)
 - [ ] Instructions are specific and actionable
 - [ ] Output examples provided
-- [ ] Quality criteria defined for each step
-- [ ] User input steps use "ask structured questions"
+- [ ] Quality criteria defined
 - [ ] `deepwork sync` executed successfully
-- [ ] Skills available in platform directory
-- [ ] Considered relevant rules for job domain
+- [ ] Rules considered (suggest if genuinely helpful)
 
 ## Output
 
-Complete step instruction files at `.deepwork/jobs/[job_name]/steps/` and synced skills.
+Complete instruction files in `.deepwork/jobs/[job_name]/steps/` and synced skills in `.claude/skills/`.
 
 
 ### Job Context
@@ -171,29 +128,6 @@ Use branch format: `deepwork/deepwork_jobs-[instance]-YYYYMMDD`
 - 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. **Directory Structure**: Is `.deepwork/jobs/[job_name]/` created correctly?
-2. **Complete Instructions**: Are ALL step instruction files complete (not stubs or placeholders)?
-3. **Specific & Actionable**: Are instructions tailored to each step's purpose, not generic?
-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.
-**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