fix: align job creation directory with MCP server project root

make_new_job.sh used git rev-parse --show-toplevel to decide where to
create jobs, while the MCP server uses listRoots for discovery. These
diverge when the session root differs from the git root (nested repos,
cd changes, non-git parent dirs), causing newly created jobs to be
invisible to get_workflows/start_workflow.

Add project_root to ActiveStepInfo so agents always know the MCP
server's canonical root. Change make_new_job.sh to require
--project-root instead of inferring it from git.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: nhorton

specs/deepwork/jobs/JOBS-REQ-001-mcp-workflow-tools.md

@@ -42,7 +42,7 @@ The DeepWork MCP server exposes workflow tools to AI agents via the Model Contex
 7. The tool MUST create a new workflow session via `StateManager`.
 8. The tool MUST resolve input values for the first step from provided `inputs` and previous step outputs.
 9. The tool MUST mark the first step as started with resolved input values.
-10. The response MUST contain a `begin_step` (`ActiveStepInfo`) with: `session_id`, `step_id`, `job_dir`, `step_expected_outputs`, `step_inputs`, `step_instructions`, `common_job_info`.
+10. The response MUST contain a `begin_step` (`ActiveStepInfo`) with: `session_id`, `step_id`, `project_root`, `job_dir`, `step_expected_outputs`, `step_inputs`, `step_instructions`, `common_job_info`. The `project_root` field MUST be the absolute path the MCP server uses for job discovery and `.deepwork/` operations.
 11. The response MUST contain a `stack` field and an `important_note` field instructing the agent to clarify ambiguous requests.
 12. Each expected output MUST include `name`, `type`, `description`, `required`, and `syntax_for_finished_step_tool`.
 

src/deepwork/jobs/mcp/schemas.py

@@ -228,6 +228,11 @@ class ActiveStepInfo(BaseModel):
         )
     )
     step_id: str = Field(description="Name of the current step")
+    project_root: str = Field(
+        description="Absolute path to the MCP server's project root. "
+        "Use this as the base directory for .deepwork/ operations "
+        "(e.g. creating jobs at [project_root]/.deepwork/jobs/)."
+    )
     job_dir: str = Field(
         description="Absolute path to the job directory. Templates, scripts, "
         "and other files referenced in step instructions live here."

src/deepwork/jobs/mcp/tools.py

@@ -388,6 +388,7 @@ def _build_active_step_info(
         return ActiveStepInfo(
             session_id=session_id,
             step_id=step.name,
+            project_root=str(self.project_root),
             job_dir=str(job.job_dir),
             step_expected_outputs=step_outputs,
             step_inputs=step_inputs,

src/deepwork/standard_jobs/deepwork_jobs/job.yml

@@ -348,17 +348,17 @@ workflows:
 
           Only after you have complete understanding, create the job directory and `job.yml` file.
 
-          **Note**: `[job_dir]` refers to the `job_dir` path returned in the workflow response when this workflow was started. It points to the directory containing this job's definition, scripts, and templates.
+          **Note**: `[job_dir]` refers to the `job_dir` path returned in the workflow response when this workflow was started. It points to the directory containing this job's definition, scripts, and templates. `[project_root]` refers to the `project_root` path from the same response — the MCP server's canonical root directory.
 
           **First, create the directory structure** using the `make_new_job.sh` script:
 
           ```bash
-          [job_dir]/make_new_job.sh [job_name]
+          [job_dir]/make_new_job.sh --project-root [project_root] [job_name]
           ```
 
-          **Then create the job.yml file** at `.deepwork/jobs/[job_name]/job.yml`
+          **Then create the job.yml file** at `[project_root]/.deepwork/jobs/[job_name]/job.yml`
 
-          (Where `[job_name]` is the name of the NEW job you're creating, e.g., `competitive_research`. Replace `[job_dir]` with the actual `job_dir` path from the workflow response.)
+          (Where `[job_name]` is the name of the NEW job you're creating, e.g., `competitive_research`. Replace `[job_dir]` and `[project_root]` with the actual paths from the workflow response.)
 
           **Template reference**: See `[job_dir]/templates/job.yml.template` for the standard structure.
 

src/deepwork/standard_jobs/deepwork_jobs/make_new_job.sh

@@ -2,22 +2,24 @@
 #
 # make_new_job.sh - Create directory structure for a new DeepWork job
 #
-# Usage: ./make_new_job.sh <job_name>
+# Usage: ./make_new_job.sh --project-root DIR <job_name>
 #
 # Input:
-#   job_name - Lowercase name using only letters, numbers, and underscores.
-#              Must start with a letter.
+#   --project-root DIR - Required. The MCP server's project root directory.
+#                        Jobs are created at DIR/.deepwork/jobs/<job_name>/.
+#   job_name           - Lowercase name using only letters, numbers, and
+#                        underscores. Must start with a letter.
 #
 # Output:
-#   Creates .deepwork/jobs/<job_name>/ at the git repository root with
+#   Creates .deepwork/jobs/<job_name>/ under the specified project root with
 #   subdirectories: hooks/, templates/, scripts/, plus AGENTS.md
 #   and optionally .deepreview (if template.deepreview exists alongside
 #   this script).
 #
 # Exit codes:
 #   0 - Success
 #   1 - Usage error (missing args, invalid job name, job already exists,
-#       not a git repository)
+#       missing --project-root)
 #
 
 set -euo pipefail
@@ -54,28 +56,52 @@ main() {
     local script_dir
     script_dir="$(cd "$(dirname "$0")" && pwd)"
 
+    # Parse --project-root flag
+    local project_root=""
+    while [[ $# -gt 0 ]]; do
+        case "$1" in
+            --project-root)
+                if [[ $# -lt 2 ]]; then
+                    error "--project-root requires a directory argument"
+                fi
+                project_root="$2"
+                shift 2
+                ;;
+            -*)
+                error "Unknown option: $1"
+                ;;
+            *)
+                break
+                ;;
+        esac
+    done
+
+    if [[ -z "$project_root" ]]; then
+        error "--project-root is required. Pass the project_root from the MCP workflow response."
+    fi
+
+    if [[ ! -d "$project_root" ]]; then
+        error "Project root directory does not exist: $project_root"
+    fi
+
     if [[ $# -lt 1 ]]; then
-        echo "Usage: $0 <job_name>"
+        echo "Usage: $0 --project-root DIR <job_name>"
         echo ""
         echo "Creates the directory structure for a new DeepWork job."
         echo ""
         echo "Arguments:"
-        echo "  job_name    Name of the job (lowercase, underscores allowed)"
+        echo "  --project-root DIR   Project root directory (required)"
+        echo "  job_name             Name of the job (lowercase, underscores allowed)"
         echo ""
         echo "Example:"
-        echo "  $0 competitive_research"
+        echo "  $0 --project-root /path/to/project competitive_research"
         exit 1
     fi
 
     local job_name="$1"
     validate_job_name "$job_name"
 
-    # Determine the base path by anchoring to the git repository root
-    local repo_root
-    if ! repo_root="$(git rev-parse --show-toplevel 2>/dev/null)"; then
-        error "Not inside a git repository. Run this from within a git repo."
-    fi
-    local base_path="${repo_root}/.deepwork/jobs"
+    local base_path="${project_root}/.deepwork/jobs"
     mkdir -p "$base_path"
 
     local job_path="${base_path}/${job_name}"

tests/unit/jobs/mcp/test_schemas.py

@@ -217,6 +217,7 @@ def test_basic_step_info(self) -> None:
         step_info = ActiveStepInfo(
             session_id="abc123",
             step_id="step1",
+            project_root="/tmp/project",
             job_dir="/tmp/test_job",
             step_expected_outputs=expected,
             step_inputs=step_inputs,
@@ -226,6 +227,7 @@ def test_basic_step_info(self) -> None:
 
         assert step_info.session_id == "abc123"
         assert step_info.step_id == "step1"
+        assert step_info.project_root == "/tmp/project"
         assert step_info.job_dir == "/tmp/test_job"
         assert len(step_info.step_expected_outputs) == 1
         assert step_info.step_expected_outputs[0].name == "output.md"
@@ -242,6 +244,7 @@ def test_default_step_inputs(self) -> None:
         step_info = ActiveStepInfo(
             session_id="abc123",
             step_id="step1",
+            project_root="/tmp/project",
             job_dir="/tmp/test_job",
             step_expected_outputs=[
                 ExpectedOutput(
@@ -262,6 +265,7 @@ def test_default_common_job_info(self) -> None:
         step_info = ActiveStepInfo(
             session_id="abc123",
             step_id="step1",
+            project_root="/tmp/project",
             job_dir="/tmp/test_job",
             step_expected_outputs=[
                 ExpectedOutput(
@@ -287,6 +291,7 @@ def test_basic_response(self) -> None:
             begin_step=ActiveStepInfo(
                 session_id="abc123",
                 step_id="step1",
+                project_root="/tmp/project",
                 job_dir="/tmp/test_job",
                 step_expected_outputs=[
                     ExpectedOutput(
@@ -328,6 +333,7 @@ def test_next_step_status(self) -> None:
             begin_step=ActiveStepInfo(
                 session_id="abc123",
                 step_id="step2",
+                project_root="/tmp/project",
                 job_dir="/tmp/test_job",
                 step_expected_outputs=[
                     ExpectedOutput(

tests/unit/jobs/mcp/test_server.py

@@ -267,6 +267,7 @@ async def test_start_workflow_delegates_to_tools(self, tmp_path: Path) -> None:
                 begin_step=ActiveStepInfo(
                     session_id="sess-1",
                     step_id="step1",
+                    project_root=str(tmp_path),
                     job_dir="/tmp/jobs/myjob",
                     step_instructions="Do the thing",
                     step_expected_outputs=[],
@@ -304,6 +305,7 @@ async def test_start_workflow_with_inputs_and_agent_id(self, tmp_path: Path) ->
                 begin_step=ActiveStepInfo(
                     session_id="s",
                     step_id="s1",
+                    project_root=str(tmp_path),
                     job_dir="/tmp/jobs/j",
                     step_instructions="go",
                     step_expected_outputs=[],
@@ -418,6 +420,7 @@ async def test_go_to_step_delegates(self, tmp_path: Path) -> None:
                 begin_step=ActiveStepInfo(
                     session_id="s",
                     step_id="step1",
+                    project_root=str(tmp_path),
                     job_dir="/tmp/jobs/j",
                     step_instructions="Redo",
                     step_expected_outputs=[],

tests/unit/jobs/mcp/test_tools.py

@@ -219,6 +219,7 @@ async def test_creates_session_and_returns_first_step(self, tools: WorkflowTools
 
         assert step.session_id == SESSION_ID
         assert step.step_id == "step1"
+        assert step.project_root == str(tools.project_root)
         assert "Do the first step" in step.step_instructions
         assert len(step.step_expected_outputs) == 1
         assert step.step_expected_outputs[0].name == "output1"