Unsupervisedcom
diff --git a/‎library/jobs/README.md‎
Lines changed: 53 additions & 12 deletions b/‎library/jobs/README.md‎
Lines changed: 53 additions & 12 deletions
diff --git a/‎library/jobs/platform_engineer/readme.md‎
Lines changed: 24 additions & 0 deletions b/‎library/jobs/platform_engineer/readme.md‎
Lines changed: 24 additions & 0 deletions
diff --git a/‎library/jobs/repo/readme.md‎
Lines changed: 24 additions & 0 deletions b/‎library/jobs/repo/readme.md‎
Lines changed: 24 additions & 0 deletions
diff --git a/‎library/jobs/research/readme.md‎
Lines changed: 24 additions & 0 deletions b/‎library/jobs/research/readme.md‎
Lines changed: 24 additions & 0 deletions
diff --git a/‎library/jobs/spec_driven_development/readme.md‎
Lines changed: 24 additions & 0 deletions b/‎library/jobs/spec_driven_development/readme.md‎
Lines changed: 24 additions & 0 deletions
diff --git a/‎src/deepwork/standard_jobs/deepwork_jobs/AGENTS.md‎
Lines changed: 13 additions & 2 deletions b/‎src/deepwork/standard_jobs/deepwork_jobs/AGENTS.md‎
Lines changed: 13 additions & 2 deletions
diff --git a/‎src/deepwork/standard_jobs/deepwork_jobs/job.yml‎
Lines changed: 9 additions & 8 deletions b/‎src/deepwork/standard_jobs/deepwork_jobs/job.yml‎
Lines changed: 9 additions & 8 deletions
diff --git a/‎src/deepwork/standard_jobs/deepwork_jobs/steps/learn.md‎
Lines changed: 38 additions & 6 deletions b/‎src/deepwork/standard_jobs/deepwork_jobs/steps/learn.md‎
Lines changed: 38 additions & 6 deletions
@@ -1,12 +1,40 @@
-# Job Library
+# Shared Jobs
 
-This directory contains a public library of example jobs that you can use as starting points for your own workflows. Each job demonstrates best practices for structuring multi-step tasks with DeepWork.
+DeepWork includes a library of reusable jobs that any project can adopt. These are pre-built, multi-step workflows covering common tasks like research, repository setup, platform engineering, and spec-driven development.
+
+## Enabling Shared Jobs
+
+The fastest way to add shared jobs to your project is with the `/deepwork` skill:
+
+```
+/deepwork shared_jobs
+```
+
+This walks you through configuring `DEEPWORK_ADDITIONAL_JOBS_FOLDERS` so the DeepWork plugin discovers library jobs at runtime alongside your local jobs. By default, jobs are referenced in-place from a checkout of the DeepWork repo, so you always get the latest version, though you can still copy them into your project when you want to customize them.
+
+## Available Jobs
+
+| Job | Description |
+|-----|-------------|
+| [Research](./research) | Multi-workflow research suite — deep investigation, quick summaries, material ingestion, and reproduction planning |
+| [Platform Engineer](./platform_engineer) | Incident response, observability, CI/CD, releases, security, cost management, and infrastructure |
+| [Repo](./repo) | Audit and configure repositories — labels, branch protection, milestones, and boards |
+| [Spec-Driven Development](./spec_driven_development) | Build features through executable specifications: constitution, specify, clarify, plan, tasks, implement |
+
+## How It Works
+
+Shared jobs are stored in the `library/jobs/` directory of the DeepWork repository. When you run the `shared_jobs` workflow, it:
+
+1. **Detects your setup** — checks for an existing local DeepWork checkout or sparse clone
+2. **Configures the source** — sets up a sparse checkout in `.deepwork/upstream/` or points to an existing local clone
+3. **Sets the environment variable** — adds `DEEPWORK_ADDITIONAL_JOBS_FOLDERS` to your `flake.nix` shellHook (or shell profile)
+4. **Discovers jobs** — library jobs appear in `/deepwork` alongside your local and standard jobs
 
 ## Purpose
 
 The job library provides:
 
-- **Inspiration**: See how others have structured complex workflows
+- **Ready-to-use workflows**: Start using proven multi-step workflows immediately
 - **Templates**: Copy and adapt jobs for your own use cases
 - **Learning**: Understand the job definition format through real examples
 
@@ -131,20 +159,33 @@ git clone https://github.com/Unsupervisedcom/deepwork.git .deepwork/upstream
 shellHook = ''
   export REPO_ROOT=$(git rev-parse --show-toplevel)
 
-  # Clone DeepWork library jobs if not present
-  if [ ! -d "$REPO_ROOT/.deepwork/upstream" ]; then
-    git clone --sparse --filter=blob:none \
-      https://github.com/Unsupervisedcom/deepwork.git \
-      "$REPO_ROOT/.deepwork/upstream"
-    git -C "$REPO_ROOT/.deepwork/upstream" sparse-checkout set --cone library/jobs/
+  # Prefer local deepwork checkout, fall back to existing sparse checkout
+  if [ -d "$REPO_ROOT/../deepwork/library/jobs" ]; then
+    export DEEPWORK_ADDITIONAL_JOBS_FOLDERS="''${DEEPWORK_ADDITIONAL_JOBS_FOLDERS:+$DEEPWORK_ADDITIONAL_JOBS_FOLDERS:}$REPO_ROOT/../deepwork/library/jobs"
+  elif [ -d "$REPO_ROOT/.deepwork/upstream/library/jobs" ]; then
+    export DEEPWORK_ADDITIONAL_JOBS_FOLDERS="''${DEEPWORK_ADDITIONAL_JOBS_FOLDERS:+$DEEPWORK_ADDITIONAL_JOBS_FOLDERS:}$REPO_ROOT/.deepwork/upstream/library/jobs"
+  else
+    echo "DeepWork library jobs not found. Run '/deepwork shared_jobs' to set them up." >&2
   fi
-
-  export DEEPWORK_ADDITIONAL_JOBS_FOLDERS="$REPO_ROOT/.deepwork/upstream/library/jobs"
 '';
 ```
 
 Library jobs now appear in `/deepwork` alongside your local and standard jobs.
 
+To initially set up or update the sparse checkout:
+
+```bash
+REPO_ROOT="$(git rev-parse --show-toplevel)"
+if [ ! -d "$REPO_ROOT/.deepwork/upstream" ]; then
+  git clone --sparse --filter=blob:none \
+    https://github.com/Unsupervisedcom/deepwork.git \
+    "$REPO_ROOT/.deepwork/upstream"
+  git -C "$REPO_ROOT/.deepwork/upstream" sparse-checkout set --cone library/jobs/
+else
+  git -C "$REPO_ROOT/.deepwork/upstream" pull --ff-only
+fi
+```
+
 ### Sparse Checkout (Specific Jobs Only)
 
 If you only need certain library jobs, use a sparse checkout to minimize disk usage:
@@ -177,7 +218,7 @@ When you use a library job and discover improvements, you can contribute them ba
 ### The Learn Flow
 
 1. Run the library job in your project as normal
-2. Run `/deepwork deepwork_jobs learn` — the learn step classifies improvements as:
+2. Run `/deepwork learn` — the learn step classifies improvements as:
    - **Generalizable**: Improvements that benefit all users (update the library job)
    - **Bespoke**: Improvements specific to your project (update your local `AGENTS.md`)
 
 
@@ -16,6 +16,30 @@ This job covers the full lifecycle of platform engineering work:
 - **Infrastructure**: Audit documentation, plan migrations, convert imperative to declarative
 - **Error tracking**: Set up exception monitoring (Sentry, etc.)
 
+## Quick Start
+
+If you haven't already, enable shared library jobs in your project:
+
+```
+/deepwork shared_jobs
+```
+
+Natural language is matched to the `platform_engineer` job's `incident_investigation` workflow. Triages the incident, gathers logs and metrics, and produces a structured incident report.
+
+```
+/deepwork the staging deploy is returning 502s, investigate
+```
+
+Or create a Claude skill for quick access, then use it:
+
+```
+/deepwork create a /platform.investigate skill that runs the platform_engineer job's incident_investigation workflow
+```
+
+```
+/platform.investigate the staging deploy is returning 502s
+```
+
 ## Workflows
 
 | Workflow | When to Use |
 
@@ -11,6 +11,30 @@ Two workflows are provided:
 1. **setup** — Make a repo ready for work: create missing labels, check branch protection, verify milestones and boards
 2. **doctor** — Audit existing state and fix drift: find duplicates, enable missing protections, correct label drift, reconcile board items
 
+## Quick Start
+
+If you haven't already, enable shared library jobs in your project:
+
+```
+/deepwork shared_jobs
+```
+
+Runs the `setup` workflow from the `repo` job. Detects your git provider and ensures labels, branch protection, milestones, and boards match team conventions.
+
+```
+/deepwork repo setup
+```
+
+Or create a Claude skill for quick access, then use it:
+
+```
+/deepwork create a /repo.setup skill that runs the repo job's setup workflow
+```
+
+```
+/repo.setup
+```
+
 ## Provider Support
 
 The job detects the provider from `git remote get-url origin`:
 
@@ -44,6 +44,30 @@ Ingest research material, analyze for reproducible claims, and create an enginee
 ingest_material → analyze → plan
 ```
 
+## Quick Start
+
+If you haven't already, enable shared library jobs in your project:
+
+```
+/deepwork shared_jobs
+```
+
+Natural language is matched to the `research` job's `research` workflow. Scopes the question, gathers from multiple platforms, synthesizes findings, and produces a report with bibliography.
+
+```
+/deepwork do a deep research run on growing plants in lunar regolith
+```
+
+Or create a Claude skill for quick access, then use it:
+
+```
+/deepwork create a /research.deep skill that runs the research job's research workflow
+```
+
+```
+/research.deep growing plants in lunar regolith
+```
+
 ## Prerequisites
 
 - For **research** workflow: Browser tool access if using external platforms (Gemini, ChatGPT, etc.)
 
@@ -15,6 +15,30 @@ The workflow progresses through six steps:
 5. **Tasks** - Break the plan into ordered, actionable development tasks
 6. **Implement** - Execute tasks to deliver the complete feature
 
+## Quick Start
+
+If you haven't already, enable shared library jobs in your project:
+
+```
+/deepwork shared_jobs
+```
+
+Runs the `spec_driven_development` workflow starting at the `specify` step. Walks through constitution, specify, clarify, plan, tasks, and implement.
+
+```
+/deepwork spec_driven_development specify
+```
+
+Or create a Claude skill for quick access, then use it:
+
+```
+/deepwork create a /spec.specify skill that runs the spec_driven_development job's specify workflow
+```
+
+```
+/spec.specify
+```
+
 ## When to Use
 
 This workflow is ideal for:
 
@@ -82,7 +82,18 @@ Key details:
 - Bump patch version (0.0.x) for instruction improvements
 - Bump minor version (0.x.0) for new features or structural changes
 
+### Learn Workflow: External Job Repo Handling (v1.7.0)
+
+The learn workflow now detects when a job being updated lives in an external git repository (via `DEEPWORK_ADDITIONAL_JOBS_FOLDERS`) and handles commits/pushes to that repo separately.
+
+Key design decisions:
+- Uses `job_dir` from MCP response as the authoritative path — never assumes `.deepwork/jobs/`
+- Detects external repos by comparing `git rev-parse --show-toplevel` of job_dir vs project root
+- Asks user preference for push strategy (direct to main, PR from branch, PR from fork)
+- Designed for keystone development mode where `~/.keystone/*/deepwork/library/jobs/` is the additional folder
+- Quality criteria "External Repo Handled" auto-passes for local jobs
+
 ## Last Updated
 
-- Date: 2026-03-21
-- From conversation about: Adding library job Nix devshell detection to the repair workflow's errata step
+- Date: 2026-03-23
+- From conversation about: Adding DEEPWORK_ADDITIONAL_JOBS_FOLDERS awareness to the learn workflow
@@ -1,6 +1,6 @@
 # yaml-language-server: $schema=.deepwork/schemas/job.schema.json
 name: deepwork_jobs
-version: "1.6.0"
+version: "1.7.0"
 summary: "Creates and manages multi-step AI workflows. Use when defining, implementing, testing, or improving DeepWork jobs."
 common_job_info_provided_to_all_steps_at_runtime: |
   Core commands for managing DeepWork jobs. These commands help you define new multi-step
@@ -199,6 +199,7 @@ steps:
           "Bespoke Learnings Captured": "Run-specific learnings were added to AGENTS.md."
           "File References Used": "AGENTS.md entries reference other files where appropriate."
           "Working Folder Correct": "AGENTS.md is in the correct working folder for the job."
+          "External Repo Handled": "If the job lives in an external repo (via DEEPWORK_ADDITIONAL_JOBS_FOLDERS), changes were committed and pushed per the user's preference. If the job is local, this criterion auto-passes."
 
   - id: fix_settings
     name: "Fix Settings Files"
@@ -276,21 +277,21 @@ steps:
 
   - id: sync_shared_jobs
     name: "Sync Shared Jobs"
-    description: "Installs library jobs from the DeepWork shared job library into the project. Supports remote (GitHub) and local source paths."
+    description: "Configures DEEPWORK_ADDITIONAL_JOBS_FOLDERS to reference library jobs from a local checkout or sparse clone. Never copies jobs into .deepwork/jobs/."
     instructions_file: steps/sync_shared_jobs.md
     inputs:
       - name: source
-        description: "Source for library jobs: 'remote' for GitHub, or a local path to a DeepWork repo checkout"
+        description: "Source for library jobs: 'local' for an existing deepwork checkout, 'remote' for sparse-checkout clone, or a custom path"
     outputs:
-      installed_jobs:
+      available_jobs:
         type: files
-        description: "The job.yml files of newly installed library jobs"
+        description: "The job.yml files available via the configured library path"
         required: true
     dependencies: []
     reviews:
-      - run_each: installed_jobs
+      - run_each: available_jobs
         quality_criteria:
           "Valid Job Definition": "The job.yml is valid YAML with required fields (name, version, summary, steps)."
           "Step Files Present": "All instructions_file paths referenced in job.yml exist."
-          "No Conflict": "Existing job handling was clean (new install, or user approved overwrite)."
-          "Sync Completed": "deepwork sync was run after installation."
+          "Referenced Not Copied": "Library jobs are referenced via DEEPWORK_ADDITIONAL_JOBS_FOLDERS, not copied into .deepwork/jobs/."
+          "Env Var Configured": "DEEPWORK_ADDITIONAL_JOBS_FOLDERS is set for persistence (flake.nix, shellHook, or equivalent)."
@@ -17,14 +17,20 @@ Analyze the conversation history to extract learnings and improvements, then app
    - Identify which jobs and steps were executed
    - Note the order of execution
 
-2. **Identify the target folder**
+2. **Locate the job directory using `job_dir`**
+   - The MCP server returns `job_dir` (absolute path) when starting workflows — use this as the authoritative location
+   - The job may live in `.deepwork/jobs/`, `src/deepwork/standard_jobs/`, or an **external folder** via `DEEPWORK_ADDITIONAL_JOBS_FOLDERS`
+   - Check if `job_dir` is inside the current project's git repo or in a **separate git repository** (e.g. a library checkout at `~/.keystone/*/deepwork/library/jobs/`)
+   - If `job_dir` is in a different git repo, note this — you'll need to handle commits/pushes separately in Step 8
+
+3. **Identify the AGENTS.md target folder**
    - This should be the deepest common folder that would contain all work on the topic in the future
    - Should be clear from conversation history where work was done
    - If unclear, run `git diff` to see where changes were made on the branch
 
-3. **If no job was specified**, ask the user:
+4. **If no job was specified**, ask the user:
    - "Which DeepWork job would you like me to learn from?"
-   - List available jobs from `.deepwork/jobs/`
+   - List available jobs (call `get_workflows` to see all discovered jobs)
 
 ### Step 2: Identify Points of Confusion and Inefficiency
 
@@ -80,8 +86,9 @@ For each learning identified, determine if it is:
 
 For each generalizable learning:
 
-1. **Locate the instruction file**
-   - Path: `.deepwork/jobs/[job_name]/steps/[step_id].md`
+1. **Locate the instruction file using `job_dir`**
+   - Path: `<job_dir>/steps/[step_id].md` (where `job_dir` was identified in Step 1)
+   - Do NOT assume `.deepwork/jobs/` — the job may live in an external folder
 
 2. **Make targeted improvements**
    - Add missing context or clarification
@@ -109,7 +116,7 @@ Review all instruction files for the job and identify content that:
 
 **Extract to shared files:**
 
-1. **Create shared files** in `.deepwork/jobs/[job_name]/steps/shared/`
+1. **Create shared files** in `<job_dir>/steps/shared/`
    - `conventions.md` - Coding/formatting conventions used across steps
    - `examples.md` - Common examples referenced by multiple steps
    - `schemas.md` - Data structures or formats used throughout
@@ -172,6 +179,31 @@ If instruction files were modified:
    - Patch version (0.0.x) for instruction improvements
    - Minor version (0.x.0) if quality criteria changed
 
+### Step 8: Commit and Push Changes to External Job Repos
+
+If `job_dir` is in a **separate git repository** (outside the current project), you need to commit and push those changes independently.
+
+1. **Detect the external repo**
+   - Run `git -C <job_dir> rev-parse --show-toplevel` to find the repo root
+   - If it differs from the current project root, the job lives in an external repo
+
+2. **Commit changes in the external repo**
+   - `cd` to the external repo root
+   - Stage only the changed job files using a repo-relative path (e.g. `git -C <repo_root> add <relative_job_dir>/`)
+   - Create a commit following Conventional Commits: `fix(jobs): improve <job_name> instructions from learn workflow`
+
+3. **Push strategy — ask the user**
+   - Ask: "The job `<job_name>` lives in an external repo at `<repo_root>`. How would you like to push these changes?"
+     - **Direct push to main**: Commit on main and push (for collaborators who prefer clean history)
+     - **PR from branch**: Create a feature branch, push, and open a PR (for non-collaborators or when review is desired)
+     - **PR from fork**: Fork the repo, push to fork, and open a PR (for non-collaborators without write access)
+   - If the user has previously expressed a preference, follow it without asking again
+
+4. **Execute the chosen strategy**
+   - For direct push: `git push origin main`
+   - For PR: Create branch `deepwork/learn-<job_name>`, push with `-u`, open PR via `gh pr create`
+   - For fork PR: Use `gh repo fork`, push to fork, open PR against upstream
+
 ## File Reference Patterns
 
 When adding entries to AGENTS.md, prefer these patterns: