Merge branch 'main' into copilot/fix-ci-action-failure

Author: ncrmro

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

@@ -126,10 +126,63 @@ For each major phase they mentioned, ask structured questions to gather details:
    - Where should each output be saved? (filename/path)
    - Should outputs be organized in subdirectories? (e.g., `reports/`, `data/`, `drafts/`)
    - Will other steps need this output?
-
-   **Important**: Output paths should always be within the main repository directory structure, not in dot-directories like `.deepwork/`. Dot-directories are for configuration and job definitions, not for job outputs. Use paths like `research/competitors/report.md` rather than `.deepwork/outputs/report.md`.
    - **Does this output have a doc spec?** If a doc spec was created in Step 1.6/1.7, reference it for the appropriate output
 
+   #### Work Product Storage Guidelines
+
+   **Key principle**: Job outputs belong in the main repository directory structure, not in dot-directories. The `.deepwork/` directory is for job definitions and configuration only.
+
+   **Why this matters**:
+   - **Version control**: Work products in the main repo are tracked by git and visible in PRs
+   - **Discoverability**: Team members can find outputs without knowing about DeepWork internals
+   - **Tooling compatibility**: IDEs, search tools, and CI/CD work naturally with standard paths
+   - **Glob patterns**: Well-structured paths enable powerful file matching (e.g., `competitive_research/**/*.md`)
+
+   **Good output path patterns**:
+   ```
+   competitive_research/competitors_list.md
+   competitive_research/acme_corp/research.md
+   operations/reports/2026-01/spending_analysis.md
+   docs/api/endpoints.md
+   ```
+
+   **Avoid these patterns**:
+   ```
+   .deepwork/outputs/report.md          # Hidden in dot-directory
+   output.md                            # Too generic, no context
+   research.md                          # Unclear which research
+   temp/draft.md                        # Transient-sounding paths
+   ```
+
+   **Organizing multi-file outputs**:
+   - Use the job name as a top-level folder when outputs are job-specific
+   - Use parameterized paths for per-entity outputs: `competitive_research/[competitor_name]/`
+   - Match existing project conventions when extending a codebase
+
+   **When to include dates in paths**:
+   - **Include date** for periodic outputs where each version is retained (e.g., monthly reports, quarterly reviews, weekly summaries). These accumulate over time and historical versions remain useful.
+     ```
+     operations/reports/2026-01/spending_analysis.md              # Monthly report - keep history
+     hr/employees/[employee_name]/quarterly_reviews/2026-Q1.pdf   # Per-employee quarterly review
+     ```
+   - **Omit date** for current-state outputs that represent the latest understanding and get updated in place. Previous versions live in git history, not separate files.
+     ```
+     competitive_research/acme_corp/swot.md  # Current SWOT - updated over time
+     docs/architecture/overview.md           # Living document
+     ```
+
+   **Supporting materials and intermediate outputs**:
+   - Content generated in earlier steps to support the final output (research notes, data extracts, drafts) should be placed in a `_dataroom` folder that is a peer to the final output
+   - Name the dataroom folder by replacing the file extension with `_dataroom`
+     ```
+     operations/reports/2026-01/spending_analysis.md           # Final output
+     operations/reports/2026-01/spending_analysis_dataroom/    # Supporting materials
+         raw_data.csv
+         vendor_breakdown.md
+         notes.md
+     ```
+   - This keeps supporting materials organized and discoverable without cluttering the main output location
+
 4. **Step Dependencies**
    - Which previous steps must complete before this one?
    - Are there any ordering constraints?
@@ -139,6 +192,19 @@ For each major phase they mentioned, ask structured questions to gather details:
    - Are there any quality checks or validation needed?
    - What makes a good vs. bad output for this step?
 
+6. **Agent Delegation** (optional)
+   - Should this step be executed by a specific agent type?
+   - Use the `agent` field when the step should run in a forked context with a specific agent
+   - When `agent` is set, the generated skill automatically includes `context: fork`
+   - Available agent types:
+     - `general-purpose` - Standard agent for multi-step tasks
+
+   ```yaml
+   steps:
+     - id: research_step
+       agent: general-purpose  # Delegates to the general-purpose agent
+   ```
+
 **Note**: You're gathering this information to understand what instructions will be needed, but you won't create the instruction files yet - that happens in the `implement` step.
 
 #### Doc Spec-Aware Output Format
@@ -410,16 +476,6 @@ After creating the file:
 2. Recommend that they review the job.yml file
 3. Tell them to run `/deepwork_jobs.review_job_spec` next
 
-## Quality Criteria
-
-- Asked structured questions to fully understand user requirements
-- User fully understands what job they're creating
-- All steps have clear inputs and outputs
-- Dependencies make logical sense
-- Summary is concise and descriptive
-- Description provides rich context for future refinement
-- Specification is valid YAML and follows the schema
-- Ready for implementation step
 
 
 ### Job Context
@@ -466,7 +522,7 @@ Use branch format: `deepwork/deepwork_jobs-[instance]-YYYYMMDD`
   6. **Complete Steps**: Each step must have: id (lowercase_underscores), name, description, instructions_file, outputs (at least one), and dependencies array
   7. **Valid Dependencies**: Dependencies must reference existing step IDs with no circular references
   8. **Input Consistency**: File inputs with `from_step` must reference a step that is in the dependencies array
-  9. **Output Paths**: Outputs must be valid filenames or paths within the main repo (not in dot-directories). Use specific, descriptive paths that lend themselves to glob patterns, e.g., `competitive_research/competitors_list.md` or `competitive_research/[competitor_name]/research.md`. Avoid generic names like `output.md`.
+  9. **Output Paths**: Outputs must be valid filenames or paths within the main repo directory structure, never in dot-directories like `.deepwork/`. Use specific, descriptive paths that lend themselves to glob patterns (e.g., `competitive_research/acme_corp/swot.md` or `operations/reports/2026-01/spending_analysis.md`). Parameterized paths like `[competitor_name]/` are encouraged for per-entity outputs. Avoid generic names (`output.md`, `analysis.md`) and transient-sounding paths (`temp/`, `draft.md`). Supporting materials for a final output should go in a peer `_dataroom` folder (e.g., `spending_analysis_dataroom/`).
   10. **Concise Instructions**: The content of the file, particularly the description, must not have excessively redundant information. It should be concise and to the point given that extra tokens will confuse the AI.
 
   <details>
@@ -535,6 +591,19 @@ Use branch format: `deepwork/deepwork_jobs-[instance]-YYYYMMDD`
       exposed: true                 # Makes step available without running dependencies
   ```
 
+  ### Agent Delegation
+
+  When a step should be executed by a specific agent type, use the `agent` field. This automatically sets `context: fork` in the generated skill.
+
+  ```yaml
+  steps:
+    - id: research_step
+      agent: general-purpose        # Delegates to the general-purpose agent
+  ```
+
+  Available agent types:
+  - `general-purpose` - Standard agent for multi-step tasks
+
   ### Quality Hooks
 
   ```yaml
@@ -644,32 +713,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. **User Understanding**: Did the agent fully understand the user's workflow by asking structured questions?
-2. **Structured Questions Used**: Did the agent ask structured questions (using the AskUserQuestion tool) to gather user input?
-3. **Document Detection**: For document-oriented workflows, did the agent detect patterns and offer doc spec creation?
-4. **doc spec Created (if applicable)**: If a doc spec was needed, was it created in `.deepwork/doc_specs/[doc_spec_name].md` with proper quality criteria?
-5. **doc spec References**: Are document outputs properly linked to their doc specs using `{file, doc_spec}` format?
-6. **Valid Against doc spec**: Does the job.yml conform to the job.yml doc spec quality criteria (valid identifier, semantic version, concise summary, rich description, complete steps, valid dependencies)?
-7. **Clear Inputs/Outputs**: Does every step have clearly defined inputs and outputs?
-8. **Logical Dependencies**: Do step dependencies make sense and avoid circular references?
-9. **Concise Summary**: Is the summary under 200 characters and descriptive?
-10. **Rich Description**: Does the description provide enough context for future refinement?
-11. **Valid Schema**: Does the job.yml follow the required schema (name, version, summary, steps)?
-12. **File Created**: Has the job.yml file been created in `.deepwork/jobs/[job_name]/job.yml`?
-**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

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

@@ -150,11 +150,7 @@ This will:
 - Generate skills for each step
 - Make the skills available in `.claude/skills/` (or appropriate platform directory)
 
-### Step 6: 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.
 
@@ -245,8 +241,7 @@ Before marking this step complete, ensure:
 - [ ] Each instruction file is complete and actionable
 - [ ] `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

.claude/skills/deepwork_jobs.learn/SKILL.md

@@ -250,14 +250,12 @@ If instruction files were modified:
      changes: "Improved [step] instructions based on execution learnings: [brief description]"
    ```
 
-### Step 7: Sync and Relay Instructions
+### Step 7: Sync Skills
 
-1. **Run deepwork sync** (if instructions were modified)
-   ```bash
-   deepwork sync
-   ```
-
-2. **If skills were regenerated**, look at the "To use the new skills" section in the `deepwork sync` output and **relay these exact reload instructions to the user** (e.g., "Type 'exit' then run 'claude --resume'" for Claude Code)
+**Run deepwork sync** (if instructions were modified)
+```bash
+deepwork sync
+```
 
 ## File Reference Patterns
 
@@ -347,7 +345,7 @@ I found the following job executions:
 
 **Summary**
 
-Updated job instructions and created AGENTS.md with bespoke learnings. To get the updated skills, type 'exit' then run 'claude --resume'.
+Updated job instructions and created AGENTS.md with bespoke learnings.
 ```
 
 ## Handling Edge Cases

.claude/skills/deepwork_jobs.review_job_spec/SKILL.md

@@ -276,7 +276,7 @@ Use branch format: `deepwork/deepwork_jobs-[instance]-YYYYMMDD`
   6. **Complete Steps**: Each step must have: id (lowercase_underscores), name, description, instructions_file, outputs (at least one), and dependencies array
   7. **Valid Dependencies**: Dependencies must reference existing step IDs with no circular references
   8. **Input Consistency**: File inputs with `from_step` must reference a step that is in the dependencies array
-  9. **Output Paths**: Outputs must be valid filenames or paths within the main repo (not in dot-directories). Use specific, descriptive paths that lend themselves to glob patterns, e.g., `competitive_research/competitors_list.md` or `competitive_research/[competitor_name]/research.md`. Avoid generic names like `output.md`.
+  9. **Output Paths**: Outputs must be valid filenames or paths within the main repo directory structure, never in dot-directories like `.deepwork/`. Use specific, descriptive paths that lend themselves to glob patterns (e.g., `competitive_research/acme_corp/swot.md` or `operations/reports/2026-01/spending_analysis.md`). Parameterized paths like `[competitor_name]/` are encouraged for per-entity outputs. Avoid generic names (`output.md`, `analysis.md`) and transient-sounding paths (`temp/`, `draft.md`). Supporting materials for a final output should go in a peer `_dataroom` folder (e.g., `spending_analysis_dataroom/`).
   10. **Concise Instructions**: The content of the file, particularly the description, must not have excessively redundant information. It should be concise and to the point given that extra tokens will confuse the AI.
 
   <details>
@@ -345,6 +345,19 @@ Use branch format: `deepwork/deepwork_jobs-[instance]-YYYYMMDD`
       exposed: true                 # Makes step available without running dependencies
   ```
 
+  ### Agent Delegation
+
+  When a step should be executed by a specific agent type, use the `agent` field. This automatically sets `context: fork` in the generated skill.
+
+  ```yaml
+  steps:
+    - id: research_step
+      agent: general-purpose        # Delegates to the general-purpose agent
+  ```
+
+  Available agent types:
+  - `general-purpose` - Standard agent for multi-step tasks
+
   ### Quality Hooks
 
   ```yaml

.deepwork/doc_specs/job_spec.md

@@ -23,7 +23,7 @@ quality_criteria:
   - name: Input Consistency
     description: "File inputs with `from_step` must reference a step that is in the dependencies array"
   - name: Output Paths
-    description: "Outputs must be valid filenames or paths within the main repo (not in dot-directories). Use specific, descriptive paths that lend themselves to glob patterns, e.g., `competitive_research/competitors_list.md` or `competitive_research/[competitor_name]/research.md`. Avoid generic names like `output.md`."
+    description: "Outputs must be valid filenames or paths within the main repo directory structure, never in dot-directories like `.deepwork/`. Use specific, descriptive paths that lend themselves to glob patterns (e.g., `competitive_research/acme_corp/swot.md` or `operations/reports/2026-01/spending_analysis.md`). Parameterized paths like `[competitor_name]/` are encouraged for per-entity outputs. Avoid generic names (`output.md`, `analysis.md`) and transient-sounding paths (`temp/`, `draft.md`). Supporting materials for a final output should go in a peer `_dataroom` folder (e.g., `spending_analysis_dataroom/`)."
   - name: Concise Instructions
     description: "The content of the file, particularly the description, must not have excessively redundant information. It should be concise and to the point given that extra tokens will confuse the AI."
 ---
@@ -90,6 +90,19 @@ steps:
     exposed: true                 # Makes step available without running dependencies
 ```
 
+### Agent Delegation
+
+When a step should be executed by a specific agent type, use the `agent` field. This automatically sets `context: fork` in the generated skill.
+
+```yaml
+steps:
+  - id: research_step
+    agent: general-purpose        # Delegates to the general-purpose agent
+```
+
+Available agent types:
+- `general-purpose` - Standard agent for multi-step tasks
+
 ### Quality Hooks
 
 ```yaml

.deepwork/jobs/deepwork_jobs/doc_specs/job_spec.md

@@ -23,7 +23,7 @@ quality_criteria:
   - name: Input Consistency
     description: "File inputs with `from_step` must reference a step that is in the dependencies array"
   - name: Output Paths
-    description: "Outputs must be valid filenames or paths within the main repo (not in dot-directories). Use specific, descriptive paths that lend themselves to glob patterns, e.g., `competitive_research/competitors_list.md` or `competitive_research/[competitor_name]/research.md`. Avoid generic names like `output.md`."
+    description: "Outputs must be valid filenames or paths within the main repo directory structure, never in dot-directories like `.deepwork/`. Use specific, descriptive paths that lend themselves to glob patterns (e.g., `competitive_research/acme_corp/swot.md` or `operations/reports/2026-01/spending_analysis.md`). Parameterized paths like `[competitor_name]/` are encouraged for per-entity outputs. Avoid generic names (`output.md`, `analysis.md`) and transient-sounding paths (`temp/`, `draft.md`). Supporting materials for a final output should go in a peer `_dataroom` folder (e.g., `spending_analysis_dataroom/`)."
   - name: Concise Instructions
     description: "The content of the file, particularly the description, must not have excessively redundant information. It should be concise and to the point given that extra tokens will confuse the AI."
 ---
@@ -90,6 +90,19 @@ steps:
     exposed: true                 # Makes step available without running dependencies
 ```
 
+### Agent Delegation
+
+When a step should be executed by a specific agent type, use the `agent` field. This automatically sets `context: fork` in the generated skill.
+
+```yaml
+steps:
+  - id: research_step
+    agent: general-purpose        # Delegates to the general-purpose agent
+```
+
+Available agent types:
+- `general-purpose` - Standard agent for multi-step tasks
+
 ### Quality Hooks
 
 ```yaml