From 26b43d351bcd896f7c60c53aa56591b74cc622e8 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 13 Feb 2026 15:47:24 +0000 Subject: [PATCH 1/7] feat: support multiple job folders with DEEPWORK_ADDITIONAL_JOBS_FOLDERS env var Job discovery now searches multiple directories instead of only .deepwork/jobs/. The default search path is: 1. /.deepwork/jobs (project-local / user-created jobs) 2. /standard_jobs (built-in jobs shipped with DeepWork) Additional folders can be appended via the DEEPWORK_ADDITIONAL_JOBS_FOLDERS environment variable (colon-delimited list of paths). Standard jobs are no longer copied into .deepwork/jobs/ during install; they are loaded directly from the package source. The sync command removes the legacy .deepwork/jobs/deepwork_jobs copy for migration. https://claude.ai/code/session_01KU818enCNqHLbrqtdyCXUV --- src/deepwork/cli/install.py | 6 +- src/deepwork/cli/sync.py | 54 +++++++-- src/deepwork/core/jobs.py | 100 ++++++++++++++++ src/deepwork/mcp/tools.py | 26 ++--- tests/unit/mcp/test_tools.py | 13 ++- tests/unit/test_jobs.py | 215 +++++++++++++++++++++++++++++++++++ 6 files changed, 383 insertions(+), 31 deletions(-) create mode 100644 src/deepwork/core/jobs.py create mode 100644 tests/unit/test_jobs.py diff --git a/src/deepwork/cli/install.py b/src/deepwork/cli/install.py index 2dfc980d..1dd6a423 100644 --- a/src/deepwork/cli/install.py +++ b/src/deepwork/cli/install.py @@ -314,9 +314,9 @@ def _install_deepwork(platform_name: str | None, project_path: Path) -> None: console.print("[yellow]→[/yellow] Installing schemas...") _install_schemas(schemas_dir, project_path) - # Step 3c: Inject standard jobs (core job definitions) - console.print("[yellow]→[/yellow] Installing core job definitions...") - _inject_deepwork_jobs(jobs_dir, project_path) + # Note: Standard jobs (deepwork_jobs) are no longer copied into + # .deepwork/jobs/ during install. They are loaded directly from + # the package's standard_jobs directory at runtime. # Step 3d: Create .gitignore for temporary files _create_deepwork_gitignore(deepwork_dir) diff --git a/src/deepwork/cli/sync.py b/src/deepwork/cli/sync.py index 80441f6d..6ade4aae 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 dataclasses import dataclass, field from pathlib import Path @@ -10,6 +11,7 @@ from deepwork.core.adapters import AgentAdapter from deepwork.core.generator import SkillGenerator from deepwork.core.hooks_syncer import collect_job_hooks, sync_hooks_to_platform +from deepwork.core.jobs import get_job_folders from deepwork.core.parser import parse_job_definition from deepwork.utils.fs import ensure_dir from deepwork.utils.yaml_utils import load_yaml @@ -38,6 +40,25 @@ def has_warnings(self) -> bool: return len(self.warnings) > 0 +def _migrate_remove_synced_standard_jobs(deepwork_dir: Path) -> None: + """Remove standard jobs that were previously synced into .deepwork/jobs/. + + Standard jobs are now loaded directly from the package source, so the + copied ``deepwork_jobs`` folder inside ``.deepwork/jobs/`` is no longer + needed. This helper silently removes it when present to keep existing + installs tidy. + """ + synced_standard = deepwork_dir / "jobs" / "deepwork_jobs" + if synced_standard.exists(): + try: + shutil.rmtree(synced_standard) + console.print( + " [dim]•[/dim] Removed legacy .deepwork/jobs/deepwork_jobs (now loaded from package)" + ) + except OSError: + pass # best-effort cleanup + + @click.command() @click.option( "--path", @@ -136,12 +157,21 @@ def sync_skills(project_path: Path) -> SyncResult: all_skill_paths_by_platform[platform_name] = all_skill_paths - # Discover jobs - jobs_dir = deepwork_dir / "jobs" - if not jobs_dir.exists(): - job_dirs = [] - else: - job_dirs = [d for d in jobs_dir.iterdir() if d.is_dir() and (d / "job.yml").exists()] + # Migration: remove synced standard jobs from .deepwork/jobs/ since they + # are now loaded directly from the package's standard_jobs directory. + _migrate_remove_synced_standard_jobs(deepwork_dir) + + # Discover jobs from all configured job folders + job_folders = get_job_folders(project_path) + job_dirs: list[Path] = [] + seen_names: set[str] = set() + for folder in job_folders: + if not folder.exists() or not folder.is_dir(): + continue + for d in sorted(folder.iterdir()): + if d.is_dir() and (d / "job.yml").exists() and d.name not in seen_names: + job_dirs.append(d) + seen_names.add(d.name) console.print(f"\n[yellow]→[/yellow] Found {len(job_dirs)} job(s) to sync") @@ -169,8 +199,16 @@ def sync_skills(project_path: Path) -> SyncResult: "[dim]The /deepwork skill is installed. Fix the job errors and run 'deepwork sync' again.[/dim]" ) - # Collect hooks from jobs (hooks collection is independent of job.yml parsing) - job_hooks_list = collect_job_hooks(jobs_dir) + # Collect hooks from jobs across all job folders + job_hooks_list: list = [] + seen_hook_jobs: set[str] = set() + for folder in job_folders: + if not folder.exists() or not folder.is_dir(): + continue + for jh in collect_job_hooks(folder): + if jh.job_name not in seen_hook_jobs: + job_hooks_list.append(jh) + seen_hook_jobs.add(jh.job_name) if job_hooks_list: console.print(f"\n[yellow]→[/yellow] Found {len(job_hooks_list)} job(s) with hooks") diff --git a/src/deepwork/core/jobs.py b/src/deepwork/core/jobs.py new file mode 100644 index 00000000..cb9436ac --- /dev/null +++ b/src/deepwork/core/jobs.py @@ -0,0 +1,100 @@ +"""Job folder discovery for DeepWork. + +Resolves the list of directories to scan for job definitions. The default +search path is: + +1. ``/.deepwork/jobs`` – project-local (user-created) jobs +2. ``/standard_jobs`` – built-in standard jobs shipped with DeepWork + +Additional directories can be appended via the ``DEEPWORK_ADDITIONAL_JOBS_FOLDERS`` +environment variable, which accepts a **colon-delimited** list of absolute paths. +""" + +from __future__ import annotations + +import logging +import os +from pathlib import Path + +from deepwork.core.parser import JobDefinition, ParseError, parse_job_definition + +logger = logging.getLogger("deepwork.core.jobs") + +# Environment variable for additional job folders (colon-delimited) +ENV_ADDITIONAL_JOBS_FOLDERS = "DEEPWORK_ADDITIONAL_JOBS_FOLDERS" + +# Location of built-in standard jobs inside the package +_STANDARD_JOBS_DIR = Path(__file__).parent.parent / "standard_jobs" + + +def get_job_folders(project_root: Path) -> list[Path]: + """Return the ordered list of directories to scan for job definitions. + + The order determines priority when the same job name appears in multiple + folders – the first directory that contains a matching job wins. + + Returns: + List of directory paths (may include non-existent paths which callers + should skip). + """ + folders: list[Path] = [ + project_root / ".deepwork" / "jobs", + _STANDARD_JOBS_DIR, + ] + + extra = os.environ.get(ENV_ADDITIONAL_JOBS_FOLDERS, "") + if extra: + for entry in extra.split(":"): + entry = entry.strip() + if entry: + folders.append(Path(entry)) + + return folders + + +def load_all_jobs(project_root: Path) -> list[JobDefinition]: + """Load all job definitions from all configured job folders. + + Jobs are discovered from each folder returned by :func:`get_job_folders`. + If two folders contain a job with the same directory name, the one from the + earlier folder wins (project-local overrides standard, etc.). + + Returns: + List of successfully parsed ``JobDefinition`` objects. + """ + seen_names: set[str] = set() + jobs: list[JobDefinition] = [] + + for folder in get_job_folders(project_root): + if not folder.exists() or not folder.is_dir(): + continue + + for job_dir in sorted(folder.iterdir()): + if not job_dir.is_dir() or not (job_dir / "job.yml").exists(): + continue + + if job_dir.name in seen_names: + continue + + try: + job = parse_job_definition(job_dir) + jobs.append(job) + seen_names.add(job_dir.name) + except ParseError as e: + logger.warning("Skipping invalid job '%s': %s", job_dir.name, e) + + return jobs + + +def find_job_dir(project_root: Path, job_name: str) -> Path | None: + """Find the directory for a specific job by name across all job folders. + + Returns the first matching directory, or ``None`` if not found. + """ + for folder in get_job_folders(project_root): + if not folder.exists() or not folder.is_dir(): + continue + candidate = folder / job_name + if candidate.is_dir() and (candidate / "job.yml").exists(): + return candidate + return None diff --git a/src/deepwork/mcp/tools.py b/src/deepwork/mcp/tools.py index cddcf80d..f89242f7 100644 --- a/src/deepwork/mcp/tools.py +++ b/src/deepwork/mcp/tools.py @@ -14,6 +14,7 @@ import aiofiles +from deepwork.core.jobs import find_job_dir, load_all_jobs from deepwork.core.parser import ( JobDefinition, OutputSpec, @@ -72,33 +73,18 @@ def __init__( "claude" uses Claude CLI subprocess. None means agent self-review. """ self.project_root = project_root - self.jobs_dir = project_root / ".deepwork" / "jobs" self.state_manager = state_manager self.quality_gate = quality_gate self.max_quality_attempts = max_quality_attempts self.external_runner = external_runner def _load_all_jobs(self) -> list[JobDefinition]: - """Load all job definitions from the jobs directory. + """Load all job definitions from all configured job folders. Returns: List of parsed JobDefinition objects """ - jobs: list[JobDefinition] = [] - - if not self.jobs_dir.exists(): - return jobs - - for job_dir in self.jobs_dir.iterdir(): - if job_dir.is_dir() and (job_dir / "job.yml").exists(): - try: - job = parse_job_definition(job_dir) - jobs.append(job) - except ParseError as e: - logger.warning("Skipping invalid job '%s': %s", job_dir.name, e) - continue - - return jobs + return load_all_jobs(self.project_root) def _job_to_info(self, job: JobDefinition) -> JobInfo: """Convert a JobDefinition to JobInfo for response. @@ -128,6 +114,8 @@ def _job_to_info(self, job: JobDefinition) -> JobInfo: def _get_job(self, job_name: str) -> JobDefinition: """Get a specific job by name. + Searches all configured job folders for the named job. + Args: job_name: Job name to find @@ -137,8 +125,8 @@ def _get_job(self, job_name: str) -> JobDefinition: Raises: ToolError: If job not found """ - job_dir = self.jobs_dir / job_name - if not job_dir.exists(): + job_dir = find_job_dir(self.project_root, job_name) + if job_dir is None: raise ToolError(f"Job not found: {job_name}") try: diff --git a/tests/unit/mcp/test_tools.py b/tests/unit/mcp/test_tools.py index 2cdd26c5..ca275805 100644 --- a/tests/unit/mcp/test_tools.py +++ b/tests/unit/mcp/test_tools.py @@ -15,6 +15,18 @@ from deepwork.mcp.tools import ToolError, WorkflowTools +@pytest.fixture(autouse=True) +def _isolate_job_folders(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None: + """Prevent tests from picking up real standard_jobs from the package. + + Each test gets only its own .deepwork/jobs/ directory. + """ + monkeypatch.setattr( + "deepwork.core.jobs.get_job_folders", + lambda project_root: [project_root / ".deepwork" / "jobs"], + ) + + @pytest.fixture def project_root(tmp_path: Path) -> Path: """Create a temporary project with a test job.""" @@ -114,7 +126,6 @@ class TestWorkflowTools: def test_init(self, tools: WorkflowTools, project_root: Path) -> None: """Test WorkflowTools initialization.""" assert tools.project_root == project_root - assert tools.jobs_dir == project_root / ".deepwork" / "jobs" def test_get_workflows(self, tools: WorkflowTools) -> None: """Test getting all workflows.""" diff --git a/tests/unit/test_jobs.py b/tests/unit/test_jobs.py new file mode 100644 index 00000000..9a8b6e08 --- /dev/null +++ b/tests/unit/test_jobs.py @@ -0,0 +1,215 @@ +"""Tests for job folder discovery (deepwork.core.jobs).""" + +from pathlib import Path + +import pytest + +from deepwork.core.jobs import ( + ENV_ADDITIONAL_JOBS_FOLDERS, + find_job_dir, + get_job_folders, + load_all_jobs, +) + + +def _create_minimal_job(parent: Path, job_name: str) -> Path: + """Create a minimal valid job directory for testing.""" + job_dir = parent / job_name + job_dir.mkdir(parents=True, exist_ok=True) + steps_dir = job_dir / "steps" + steps_dir.mkdir(exist_ok=True) + (steps_dir / "step1.md").write_text("# Step 1\n\nDo step 1.") + (job_dir / "job.yml").write_text( + f""" +name: {job_name} +version: "1.0.0" +summary: Test job {job_name} +description: A test job + +steps: + - id: step1 + name: Step 1 + description: First step + instructions_file: steps/step1.md + outputs: {{}} + reviews: [] + +workflows: + - name: main + summary: Main workflow + steps: + - step1 +""" + ) + return job_dir + + +class TestGetJobFolders: + """Tests for get_job_folders.""" + + def test_default_folders_include_project_jobs(self, tmp_path: Path) -> None: + folders = get_job_folders(tmp_path) + assert tmp_path / ".deepwork" / "jobs" in folders + + def test_default_folders_include_standard_jobs(self, tmp_path: Path) -> None: + from deepwork.core.jobs import _STANDARD_JOBS_DIR + + folders = get_job_folders(tmp_path) + assert _STANDARD_JOBS_DIR in folders + + def test_env_var_appends_folders( + self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch + ) -> None: + monkeypatch.setenv(ENV_ADDITIONAL_JOBS_FOLDERS, "/extra/a:/extra/b") + folders = get_job_folders(tmp_path) + assert Path("/extra/a") in folders + assert Path("/extra/b") in folders + # Defaults should still be present + assert tmp_path / ".deepwork" / "jobs" in folders + + def test_env_var_empty_is_ignored( + self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch + ) -> None: + monkeypatch.setenv(ENV_ADDITIONAL_JOBS_FOLDERS, "") + folders = get_job_folders(tmp_path) + # Should only have the two defaults + assert len(folders) == 2 + + def test_env_var_strips_whitespace( + self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch + ) -> None: + monkeypatch.setenv(ENV_ADDITIONAL_JOBS_FOLDERS, " /extra/a : /extra/b ") + folders = get_job_folders(tmp_path) + assert Path("/extra/a") in folders + assert Path("/extra/b") in folders + + +class TestLoadAllJobs: + """Tests for load_all_jobs.""" + + def test_loads_from_project_jobs( + self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch + ) -> None: + jobs_dir = tmp_path / ".deepwork" / "jobs" + _create_minimal_job(jobs_dir, "my_job") + monkeypatch.setattr( + "deepwork.core.jobs.get_job_folders", + lambda pr: [pr / ".deepwork" / "jobs"], + ) + jobs = load_all_jobs(tmp_path) + assert len(jobs) == 1 + assert jobs[0].name == "my_job" + + def test_loads_from_multiple_folders( + self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch + ) -> None: + folder_a = tmp_path / "folder_a" + folder_b = tmp_path / "folder_b" + _create_minimal_job(folder_a, "job_a") + _create_minimal_job(folder_b, "job_b") + monkeypatch.setattr( + "deepwork.core.jobs.get_job_folders", + lambda pr: [folder_a, folder_b], + ) + jobs = load_all_jobs(tmp_path) + names = {j.name for j in jobs} + assert names == {"job_a", "job_b"} + + def test_first_folder_wins_for_duplicate_name( + self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch + ) -> None: + folder_a = tmp_path / "folder_a" + folder_b = tmp_path / "folder_b" + _create_minimal_job(folder_a, "same_name") + _create_minimal_job(folder_b, "same_name") + # Patch folder_b's job to have a different summary so we can distinguish + (folder_b / "same_name" / "job.yml").write_text( + (folder_b / "same_name" / "job.yml") + .read_text() + .replace("Test job same_name", "SHOULD NOT APPEAR") + ) + monkeypatch.setattr( + "deepwork.core.jobs.get_job_folders", + lambda pr: [folder_a, folder_b], + ) + jobs = load_all_jobs(tmp_path) + assert len(jobs) == 1 + assert jobs[0].summary == "Test job same_name" + + def test_skips_nonexistent_folders( + self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch + ) -> None: + monkeypatch.setattr( + "deepwork.core.jobs.get_job_folders", + lambda pr: [tmp_path / "does_not_exist"], + ) + jobs = load_all_jobs(tmp_path) + assert len(jobs) == 0 + + def test_skips_invalid_jobs( + self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch + ) -> None: + folder = tmp_path / "jobs" + bad_job = folder / "bad_job" + bad_job.mkdir(parents=True) + (bad_job / "job.yml").write_text("invalid: [yaml") + monkeypatch.setattr( + "deepwork.core.jobs.get_job_folders", + lambda pr: [folder], + ) + jobs = load_all_jobs(tmp_path) + assert len(jobs) == 0 + + +class TestFindJobDir: + """Tests for find_job_dir.""" + + def test_finds_in_first_folder( + self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch + ) -> None: + folder = tmp_path / "jobs" + _create_minimal_job(folder, "target") + monkeypatch.setattr( + "deepwork.core.jobs.get_job_folders", + lambda pr: [folder], + ) + result = find_job_dir(tmp_path, "target") + assert result == folder / "target" + + def test_finds_in_second_folder( + self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch + ) -> None: + folder_a = tmp_path / "a" + folder_b = tmp_path / "b" + folder_a.mkdir() + _create_minimal_job(folder_b, "target") + monkeypatch.setattr( + "deepwork.core.jobs.get_job_folders", + lambda pr: [folder_a, folder_b], + ) + result = find_job_dir(tmp_path, "target") + assert result == folder_b / "target" + + def test_returns_none_when_not_found( + self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch + ) -> None: + monkeypatch.setattr( + "deepwork.core.jobs.get_job_folders", + lambda pr: [tmp_path], + ) + result = find_job_dir(tmp_path, "nonexistent") + assert result is None + + def test_prefers_first_folder_on_duplicate( + self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch + ) -> None: + folder_a = tmp_path / "a" + folder_b = tmp_path / "b" + _create_minimal_job(folder_a, "dup") + _create_minimal_job(folder_b, "dup") + monkeypatch.setattr( + "deepwork.core.jobs.get_job_folders", + lambda pr: [folder_a, folder_b], + ) + result = find_job_dir(tmp_path, "dup") + assert result == folder_a / "dup" From 9e6c80f4329228d15130c3447718d617083dfa08 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 13 Feb 2026 17:45:18 +0000 Subject: [PATCH 2/7] fix: remove stale .deepwork/jobs/deepwork_jobs references, expose job_dir in MCP - Add `job_dir` field to `ActiveStepInfo` so agents know the absolute path to the job directory (needed to find templates, scripts, etc.) - Remove stale `make_new_job.sh` permission from settings.json template - Update all standard job step instructions to use `/` instead of hardcoded `.deepwork/jobs/deepwork_jobs/` paths - Update AGENTS.md to reflect the single-location model - Update fix_settings quality criterion for stale permission cleanup - Delete the legacy .deepwork/jobs/deepwork_jobs/ directory (migration) - Update mcp_interface.md documentation https://claude.ai/code/session_01KU818enCNqHLbrqtdyCXUV --- .deepwork/jobs/deepwork_jobs/AGENTS.md | 89 ---- .deepwork/jobs/deepwork_jobs/job.yml | 283 ----------- .deepwork/jobs/deepwork_jobs/make_new_job.sh | 133 ------ .../research_report_job_best_practices.md | 184 -------- .deepwork/jobs/deepwork_jobs/steps/define.md | 443 ------------------ .deepwork/jobs/deepwork_jobs/steps/errata.md | 170 ------- .../jobs/deepwork_jobs/steps/fix_jobs.md | 307 ------------ .../jobs/deepwork_jobs/steps/fix_settings.md | 177 ------- .../jobs/deepwork_jobs/steps/implement.md | 121 ----- .deepwork/jobs/deepwork_jobs/steps/iterate.md | 226 --------- .deepwork/jobs/deepwork_jobs/steps/learn.md | 266 ----------- .../steps/supplemental_file_references.md | 40 -- .deepwork/jobs/deepwork_jobs/steps/test.md | 154 ------ .../templates/agents.md.template | 32 -- .../deepwork_jobs/templates/job.yml.example | 100 ---- .../deepwork_jobs/templates/job.yml.template | 71 --- .../templates/step_instruction.md.example | 82 ---- .../templates/step_instruction.md.template | 58 --- doc/mcp_interface.md | 1 + src/deepwork/mcp/schemas.py | 4 + src/deepwork/mcp/tools.py | 2 + .../standard_jobs/deepwork_jobs/AGENTS.md | 26 +- .../standard_jobs/deepwork_jobs/job.yml | 2 +- .../deepwork_jobs/steps/define.md | 10 +- .../deepwork_jobs/steps/fix_settings.md | 2 +- .../deepwork_jobs/steps/implement.md | 12 +- .../deepwork_jobs/steps/learn.md | 2 +- src/deepwork/templates/claude/settings.json | 1 - tests/unit/mcp/test_schemas.py | 5 + 29 files changed, 33 insertions(+), 2970 deletions(-) delete mode 100644 .deepwork/jobs/deepwork_jobs/AGENTS.md delete mode 100644 .deepwork/jobs/deepwork_jobs/job.yml delete mode 100755 .deepwork/jobs/deepwork_jobs/make_new_job.sh delete mode 100644 .deepwork/jobs/deepwork_jobs/research_report_job_best_practices.md delete mode 100644 .deepwork/jobs/deepwork_jobs/steps/define.md delete mode 100644 .deepwork/jobs/deepwork_jobs/steps/errata.md delete mode 100644 .deepwork/jobs/deepwork_jobs/steps/fix_jobs.md delete mode 100644 .deepwork/jobs/deepwork_jobs/steps/fix_settings.md delete mode 100644 .deepwork/jobs/deepwork_jobs/steps/implement.md delete mode 100644 .deepwork/jobs/deepwork_jobs/steps/iterate.md delete mode 100644 .deepwork/jobs/deepwork_jobs/steps/learn.md delete mode 100644 .deepwork/jobs/deepwork_jobs/steps/supplemental_file_references.md delete mode 100644 .deepwork/jobs/deepwork_jobs/steps/test.md delete mode 100644 .deepwork/jobs/deepwork_jobs/templates/agents.md.template delete mode 100644 .deepwork/jobs/deepwork_jobs/templates/job.yml.example delete mode 100644 .deepwork/jobs/deepwork_jobs/templates/job.yml.template delete mode 100644 .deepwork/jobs/deepwork_jobs/templates/step_instruction.md.example delete mode 100644 .deepwork/jobs/deepwork_jobs/templates/step_instruction.md.template diff --git a/.deepwork/jobs/deepwork_jobs/AGENTS.md b/.deepwork/jobs/deepwork_jobs/AGENTS.md deleted file mode 100644 index 576c1185..00000000 --- a/.deepwork/jobs/deepwork_jobs/AGENTS.md +++ /dev/null @@ -1,89 +0,0 @@ -# Project Context for deepwork_jobs - -This is the source of truth for the `deepwork_jobs` standard job. - -## Codebase Structure - -- Source location: `src/deepwork/standard_jobs/deepwork_jobs/` -- Working copy: `.deepwork/jobs/deepwork_jobs/` -- Templates: `templates/` directory within each location - -## Dual Location Maintenance - -**Important**: This job exists in two locations that must be kept in sync: - -1. **Source of truth**: `src/deepwork/standard_jobs/deepwork_jobs/` - - This is where changes should be made first - - Tracked in version control - -2. **Working copy**: `.deepwork/jobs/deepwork_jobs/` - - Must be updated after changes to source - - Used by the MCP server at runtime - -After making changes to the source, run `deepwork install` or manually copy: -```bash -cp src/deepwork/standard_jobs/deepwork_jobs/job.yml .deepwork/jobs/deepwork_jobs/ -cp src/deepwork/standard_jobs/deepwork_jobs/steps/*.md .deepwork/jobs/deepwork_jobs/steps/ -cp -r src/deepwork/standard_jobs/deepwork_jobs/templates/* .deepwork/jobs/deepwork_jobs/templates/ -``` - -## File Organization - -``` -deepwork_jobs/ -├── AGENTS.md # This file -├── job.yml # Job definition -├── make_new_job.sh # Script to create new job structure -├── steps/ -│ ├── define.md # Define step instructions -│ ├── implement.md # Implement step instructions -│ ├── test.md # Test step instructions -│ ├── iterate.md # Iterate step instructions -│ ├── learn.md # Learn step instructions -│ └── supplemental_file_references.md # Reference documentation -└── templates/ - ├── job.yml.template # Job spec structure - ├── step_instruction.md.template # Step instruction structure - ├── agents.md.template # AGENTS.md structure - ├── job.yml.example # Complete job example - └── step_instruction.md.example # Complete step example -``` - -## Quality Review Learnings - -These learnings come from running the `new_job` workflow to create the `github_outreach` job (2026-02-06). - -### Review Criteria Must Be Pragmatic - -The implement step's review criteria caused 6+ review iterations during the github_outreach job creation. Key problems and fixes: - -1. **"Ask Structured Questions" was applied to ALL steps** — even pure analysis/generation steps with no user input. Fixed in v1.4.0: criterion now auto-passes for steps that only have file inputs from prior steps (no name/description user inputs). - -2. **"Output Examples" was too strict** — demanded concrete filled-in examples in every step file, even when a template structure with `[bracket placeholders]` was sufficient. Fixed in v1.4.0: renamed to "Output Format Examples" and accepts templates. Concrete examples are encouraged but not required. - -3. **Contradictory review results** — In one case, all 6 individual criteria passed but the overall review still returned `needs_work`. This appears to be a reviewer model issue where the summary contradicts the per-criterion assessments. Added `additional_review_guidance` to clarify when criteria should auto-pass. - -### Quality Review Timeouts on Large Outputs - -Steps producing many files (25 analysis files) or very long files (700+ line playbook) exceeded the 120-second MCP timeout during quality review. The `quality_review_override_reason` parameter was needed to bypass these. - -Mitigation strategies documented in `define.md`: -- Use `run_each: step` instead of `run_each: ` for steps with many files -- Keep review criteria efficient to evaluate -- Note expected output volume in step descriptions - -### Dependency Validation Gaps - -The github_outreach `final_report` step had `analyze_repos` as a file input but was missing it from the `dependencies` list. This was caught at workflow start time but could have been caught earlier during the `implement` step. The define step's validation rules already mention this (`from_step must be in dependencies`) but it was missed during creation. - -## Version Management - -- Version is tracked in `job.yml` -- Bump patch version (0.0.x) for instruction improvements -- Bump minor version (0.x.0) for new features or structural changes -- Always update changelog when bumping version - -## Last Updated - -- Date: 2026-02-06 -- From conversation about: Learn workflow analyzing severe quality review issues in the new_job execution diff --git a/.deepwork/jobs/deepwork_jobs/job.yml b/.deepwork/jobs/deepwork_jobs/job.yml deleted file mode 100644 index 57baf9f1..00000000 --- a/.deepwork/jobs/deepwork_jobs/job.yml +++ /dev/null @@ -1,283 +0,0 @@ -# yaml-language-server: $schema=.deepwork/schemas/job.schema.json -name: deepwork_jobs -version: "1.4.0" -summary: "Creates and manages multi-step AI workflows. Use when defining, implementing, testing, or improving DeepWork jobs." -description: | - Core commands for managing DeepWork jobs. These commands help you define new multi-step - workflows, test them on real use cases, and learn from running them. - - The `new_job` workflow guides you through the full lifecycle of creating a new job: - 1. **Define**: Gather requirements through structured questions and create job.yml - 2. **Implement**: Generate step instruction files and sync slash commands - 3. **Test**: Run the workflow on a real use case, critique output, and iterate with user - 4. **Iterate**: Review what happened and improve the job definition based on learnings - - 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. - -workflows: - - name: new_job - summary: "Create a new DeepWork job from scratch through definition, implementation, testing, and iteration" - steps: - - define - - implement - - test - - iterate - - - name: repair - summary: "Clean up and migrate DeepWork configurations from prior versions" - steps: - - fix_settings - - fix_jobs - - errata - - - name: learn - summary: "Analyze conversation history to improve job instructions and capture learnings" - steps: - - learn - -changelog: - - version: "1.4.0" - changes: "Fixed implement step review criteria that caused severe friction: 'Ask Structured Questions' now auto-passes for steps without user inputs; 'Output Examples' renamed to 'Output Format Examples' and accepts template placeholders; added detailed review guidance to prevent misapplication of criteria" - - version: "1.3.0" - changes: "Migrated quality_criteria to reviews system with run_each targeting and map-format criteria" - - version: "1.2.1" - changes: "Removed deprecated exposed field from learn step; added learn workflow to make step accessible via MCP" - - version: "1.2.0" - changes: "Added repair workflow with fix_settings, fix_jobs, and errata steps for migrating old DeepWork configurations to current format" - - version: "1.1.0" - changes: "Added test and iterate steps to new_job workflow; test runs the workflow on a real use case and gathers feedback; iterate improves the job definition based on what happened" - - version: "1.0.1" - changes: "Removed review_job_spec step from new_job workflow; implement now follows directly from define" - - 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" - changes: "Initial version" - - version: "0.2.0" - changes: "Replaced refine command with learn command for conversation-driven improvement" - - version: "0.3.0" - changes: "Added make_new_job.sh script and templates directory; updated instructions to reference templates instead of inline examples" - - version: "0.4.0" - changes: "Removed implementation_summary and learning_summary outputs; simplified step outputs" - - version: "0.5.0" - changes: "Standardized on 'ask structured questions' phrasing for user input; Updated quality criteria hooks to verify phrase usage; Added guidance in implement.md to use phrase in generated instructions" - - version: "0.9.0" - changes: "Improved skill descriptions with third-person voice and 'Use when...' triggers for better discoverability" - -steps: - - id: define - name: "Define Job Specification" - description: "Creates a job.yml specification by gathering workflow requirements through structured questions. Use when starting a new multi-step workflow." - instructions_file: steps/define.md - inputs: - - name: job_purpose - description: "What complex task or workflow are you trying to accomplish?" - outputs: - job.yml: - type: file - description: "Definition of the job and its workflows" - required: true - dependencies: [] - reviews: - - run_each: job.yml - quality_criteria: - "Intermediate Deliverables": "Does the job break out across the logical steps such that there are reviewable intermediate deliverables?" - "Reviews": | - Are there reviews defined for each step? Do particularly critical documents have their own reviews? - Note that the reviewers do not have transcript access, so if the criteria are about the conversation, - then add a `.deepwork/tmp/[step_summary].md` step output file so the agent has a communication channel to the reviewer. - - - id: implement - name: "Implement Job Steps" - description: "Generates step instruction files and syncs slash commands from the job.yml specification. Use after defining a job." - instructions_file: steps/implement.md - inputs: - - file: job.yml - from_step: define - outputs: - step_instruction_files: - type: files - description: "Instruction Markdown files for each step" - required: true - dependencies: - - define - reviews: - - run_each: step_instruction_files - additional_review_guidance: "Read the job.yml file in the same job directory for context on how this instruction file fits into the larger workflow." - quality_criteria: - "Complete Instructions": "Is the instruction file complete (no stubs or placeholders)?" - "Specific & Actionable": "Are instructions tailored to the step's purpose, not generic?" - "Output Examples": "Does the instruction file show what good output looks like? This can be either template examples, or negative examples of what not to do. Only required if the step has ouputs" - "Quality Criteria": "Does the instruction file define quality criteria for its outputs?" - "Ask Structured Questions": "If this step gathers user input, do instructions explicitly use the phrase 'ask structured questions'? If the step has no user inputs, this criterion passes automatically." - "Prompt Engineering": "Does the instruction file follow Anthropic's best practices for prompt engineering?" - - - id: test - name: "Test the New Workflow" - description: "Tests the newly created workflow by running it on a real use case, critiquing the output, and iterating until the user is satisfied. Use after implementing a job." - instructions_file: steps/test.md - inputs: - - file: job.yml - from_step: define - - file: step_instruction_files - from_step: implement - outputs: - .deepwork/tmp/test_feedback.md: - type: file - description: "Feedback from testing the workflow on a real use case" - required: true - dependencies: - - define - - implement - reviews: - - run_each: step - quality_criteria: - "Workflow Invoked": "Was the new workflow actually run on the user's test case via MCP?" - "Output Critiqued": "Did the agent identify up to 3 top issues with the output?" - "User Feedback Gathered": "Did the agent ask the user about each issue and gather additional feedback?" - "Corrections Made": "Were all requested corrections applied to the output?" - "User Satisfied": "Did the user confirm the output meets their needs?" - - - id: iterate - name: "Iterate on Workflow Design" - description: "Reviews the test run conversation and improves the job definition based on what happened. Use after testing a newly created job." - instructions_file: steps/iterate.md - inputs: - - file: job.yml - from_step: define - - file: step_instruction_files - from_step: implement - - file: .deepwork/tmp/test_feedback.md - from_step: test - outputs: - job.yml: - type: file - description: "Updated job definition with improvements from test run" - required: true - step_instruction_files: - type: files - description: "Updated instruction Markdown files for each step" - required: true - scripts: - type: files - description: "Updated scripts to run parts of the job more efficiently" - required: false - dependencies: - - define - - implement - - test - reviews: [] - - - 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." - instructions_file: steps/learn.md - inputs: - - name: job_name - description: "Name of the job that was run (optional - will auto-detect from conversation)" - outputs: - AGENTS.md: - type: file - description: "Bespoke learnings and run-specific context for the working folder" - required: true - job.yml: - type: file - description: "Updated job definition with improvements from test run" - required: true - step_instruction_files: - type: files - description: "Updated instruction Markdown files for each step" - required: true - scripts: - type: files - description: "Updated scripts to run parts of the job more efficiently" - required: false - dependencies: [] - reviews: - - run_each: step - 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?" - "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?" - "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?" - - - id: fix_settings - name: "Fix Settings Files" - description: "Cleans up .claude/settings.json and related configuration files, removing legacy permissions, duplicate hooks, and hardcoded paths from prior DeepWork versions." - instructions_file: steps/fix_settings.md - inputs: [] - outputs: - settings.json: - type: file - description: "Cleaned up Claude settings file with legacy permissions removed" - required: true - dependencies: [] - reviews: - - run_each: step - quality_criteria: - "DeepWork Skills Removed": "Are `Skill(...)` entries matching jobs in `.deepwork/jobs/` removed?" - "Non-DeepWork Skills Preserved": "Are skills NOT matching DeepWork jobs left intact?" - "make_new_job.sh Preserved": "Is the `Bash(...)` permission for `make_new_job.sh` preserved (if present)?" - "Rules Hooks Removed": "Are all DeepWork Rules hooks and permissions removed?" - "Duplicate Hooks Removed": "Are duplicate hook entries consolidated or removed?" - "Hardcoded Paths Removed": "Are user-specific hardcoded paths (like `/Users/*/...`) removed?" - "Deprecated Commands Removed": "Are deprecated commands like `deepwork hook *` removed?" - "Valid JSON": "Is settings.json still valid JSON after modifications?" - "Backup Created": "Was a backup of the original settings created before modifications?" - - - id: fix_jobs - name: "Fix Job Definitions" - description: "Updates job.yml files and step instructions to current DeepWork format, removing deprecated fields and migrating to new structures." - instructions_file: steps/fix_jobs.md - inputs: - - file: settings.json - from_step: fix_settings - outputs: - job_definitions: - type: files - description: "Updated job.yml files and step instructions in current DeepWork format" - required: true - step_instruction_files: - type: files - description: "Updated step instruction files" - required: true - dependencies: - - fix_settings - reviews: - - run_each: step - additional_review_guidance: "Read the .claude/settings.json file for context on what settings were cleaned up in the prior step." - quality_criteria: - "Exposed Field Addressed": "Are `exposed: true` fields removed or noted as deprecated?" - "Stop Hooks Migrated": "Are `stop_hooks` migrated to `hooks.after_agent` format?" - "Removed Steps Cleaned": "Are references to removed steps (like `review_job_spec`) updated?" - "Orphaned Steps Fixed": "For jobs with no workflows, is there a single workflow (named after the job) containing all steps? For jobs with existing workflows, does each orphan get its own workflow (named after the step)?" - "Valid YAML": "Are all job.yml files valid YAML?" - - - id: errata - name: "Clean Up Errata" - description: "Removes obsolete files and folders from prior DeepWork versions, including old skill directories, temp files, and deprecated configurations." - instructions_file: steps/errata.md - outputs: {} - inputs: - - file: job_definitions - from_step: fix_jobs - dependencies: - - fix_settings - - fix_jobs - reviews: - - run_each: step - additional_review_guidance: "Check the .deepwork/jobs/ directory and .claude/skills/ directory to verify the cleanup was done correctly." - quality_criteria: - "Legacy Job Skills Removed": "Are legacy skill folders for each job removed from `.claude/skills/` and `.gemini/skills/`?" - "Deepwork Skill Preserved": "Does the `deepwork` skill folder still exist in `.claude/skills/deepwork/`?" - "Temp Files Cleaned": "Are `.deepwork/tmp/` contents cleaned appropriately?" - "Rules Folder Removed": "Is `.deepwork/rules/` folder backed up and removed (fully deprecated)?" - "Rules Job Removed": "Is `.deepwork/jobs/deepwork_rules/` removed if present?" - "Config Version Updated": "Is `.deepwork/config.yml` using current version format?" - "DeepWork Re-installed": "Was `deepwork install` run after cleanup, and does it complete without errors?" - "Git Status Clean": "Are changes ready to be committed (no untracked garbage files)?" diff --git a/.deepwork/jobs/deepwork_jobs/make_new_job.sh b/.deepwork/jobs/deepwork_jobs/make_new_job.sh deleted file mode 100755 index c87f40e8..00000000 --- a/.deepwork/jobs/deepwork_jobs/make_new_job.sh +++ /dev/null @@ -1,133 +0,0 @@ -#!/usr/bin/env bash -# -# make_new_job.sh - Create directory structure for a new DeepWork job -# -# Usage: ./make_new_job.sh -# - -set -euo pipefail - -# Color output helpers -RED='\033[0;31m' -GREEN='\033[0;32m' -YELLOW='\033[1;33m' -NC='\033[0m' # No Color - -info() { - echo -e "${GREEN}[INFO]${NC} $1" -} - -warn() { - echo -e "${YELLOW}[WARN]${NC} $1" -} - -error() { - echo -e "${RED}[ERROR]${NC} $1" - exit 1 -} - -# Validate job name format -validate_job_name() { - local name="$1" - if [[ ! "$name" =~ ^[a-z][a-z0-9_]*$ ]]; then - error "Invalid job name '$name'. Must be lowercase, start with a letter, and contain only letters, numbers, and underscores." - fi -} - -# Main script -main() { - if [[ $# -lt 1 ]]; then - echo "Usage: $0 " - 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 "" - echo "Example:" - echo " $0 competitive_research" - exit 1 - fi - - local job_name="$1" - validate_job_name "$job_name" - - # Determine the base path - look for .deepwork directory - local base_path - if [[ -d ".deepwork/jobs" ]]; then - base_path=".deepwork/jobs" - elif [[ -d "../.deepwork/jobs" ]]; then - base_path="../.deepwork/jobs" - else - # Create from current directory - base_path=".deepwork/jobs" - mkdir -p "$base_path" - fi - - local job_path="${base_path}/${job_name}" - - # Check if job already exists - if [[ -d "$job_path" ]]; then - error "Job '$job_name' already exists at $job_path" - fi - - info "Creating job directory structure for '$job_name'..." - - # Create main job directory and subdirectories - mkdir -p "$job_path" - mkdir -p "$job_path/steps" - mkdir -p "$job_path/hooks" - mkdir -p "$job_path/templates" - mkdir -p "$job_path/scripts" - - # Add .gitkeep files to empty directories - touch "$job_path/hooks/.gitkeep" - touch "$job_path/templates/.gitkeep" - touch "$job_path/scripts/.gitkeep" - - # Create AGENTS.md file - cat > "$job_path/AGENTS.md" << 'EOF' -# Job Management - -This folder and its subfolders are managed using `deepwork_jobs` workflows. - -## Recommended Workflows - -- `deepwork_jobs/new_job` - Full lifecycle: define → implement → test → iterate -- `deepwork_jobs/learn` - Improve instructions based on execution learnings -- `deepwork_jobs/repair` - Clean up and migrate from prior DeepWork versions - -## Directory Structure - -``` -. -├── AGENTS.md # This file - project context and guidance -├── job.yml # Job specification (created by define step) -├── steps/ # Step instruction files (created by implement step) -│ └── *.md # One file per step -├── hooks/ # Custom validation scripts and prompts -│ └── *.md|*.sh # Hook files referenced in job.yml -├── scripts/ # Reusable scripts and utilities created during job execution -│ └── *.sh|*.py # Helper scripts referenced in step instructions -└── templates/ # Example file formats and templates - └── *.md|*.yml # Templates referenced in step instructions -``` - -## Editing Guidelines - -1. **Use workflows** for structural changes (adding steps, modifying job.yml) -2. **Direct edits** are fine for minor instruction tweaks -3. **Run `deepwork_jobs/learn`** after executing job steps to capture improvements -4. **Run `deepwork install`** after any changes to regenerate commands -EOF - - info "Created directory structure:" - echo " $job_path/" - echo " ├── AGENTS.md" - echo " ├── steps/" - echo " ├── hooks/.gitkeep" - echo " ├── scripts/.gitkeep" - echo " └── templates/.gitkeep" -} - -main "$@" diff --git a/.deepwork/jobs/deepwork_jobs/research_report_job_best_practices.md b/.deepwork/jobs/deepwork_jobs/research_report_job_best_practices.md deleted file mode 100644 index 87e65615..00000000 --- a/.deepwork/jobs/deepwork_jobs/research_report_job_best_practices.md +++ /dev/null @@ -1,184 +0,0 @@ -# Research Report Job Best Practices - -Reference guide for designing DeepWork jobs that produce research reports, analytical documents, or similar investigative deliverables. Use this when defining jobs via the `define` step. - -## The General Pattern - -Most report-authoring jobs follow a five-phase structure. Not every job needs all five as separate steps, and some phases combine naturally, but understanding the full arc helps you design a job that doesn't skip critical work. - -### 1. Connect - -**Purpose**: Verify that the tools and data sources the job will rely on are actually accessible before any real work begins. - -This step is about validating prerequisites, not doing research. Common activities: - -- **Database connectivity**: Run a trivial query (`SELECT 1`, `SHOW TABLES`) to confirm credentials work and the schema is reachable. -- **Web search tools**: Confirm web search and browsing tools are enabled. If the job needs to read specific sites, verify they don't require login. If they do, get the user to authenticate (e.g., via Claude in Chrome) before proceeding. -- **API access**: Test API keys or tokens against a lightweight endpoint. -- **File access**: Confirm that input files, dashboards, or shared drives are readable. - -**Why a separate step?** A failed connection discovered midway through analysis wastes all prior work. Catching it upfront is cheap. That said, for simple jobs where the data source is obvious and reliable (e.g., "search the web for X"), this can be folded into the Align step as a quick check rather than standing alone. - -**Outputs**: A brief connectivity report or checklist confirming each source is accessible, plus any credentials or configuration notes for later steps. - -### 2. Align - -**Purpose**: Build enough understanding of the domain and the user's intent to scope the analysis correctly. - -This is a cyclical step: do light research, then ask clarifying questions, then refine understanding, repeat. It ends when both the agent and user agree on what "done" looks like. - -**The cycle**: - -1. **Light grounding research** - Just enough to ask smart questions. Not deep analysis. -2. **Clarify with the user** - Surface ambiguities and propose scope boundaries. -3. **Repeat** until there's shared understanding. - -**Example - Private data (SQL-centric)**: -- Run broad queries to get the lay of the land: total record counts, key column names, date ranges, apparent segmentation columns (e.g., `division`, `region`). -- Then ask the user: "I see 45,000 customer records across 3 divisions. Should we scope to a particular division? I'm defining churn as customers with no activity in 90 days - does that match your definition?" - -**Example - Public data (web-centric)**: -- Do broad searches to see what's out there. Notice the shape of results: are they news articles, academic papers, industry reports? What subtopics keep appearing? -- Then ask the user: "Results split between fast-fashion trends and haute couture analysis. Which direction? Also, should we focus on the current season or look at multi-year trends?" - -**Outputs**: A scoping document that captures the agreed-upon research questions, data sources, definitions, exclusions, and success criteria. This becomes the north star for the Analyze step. - -### 3. Analyze - -**Purpose**: The core research cycle. Query, record, synthesize, and deepen iteratively. - -This is where most of the work happens. The key discipline is maintaining structured working files so that nothing gets lost and the narrative builds progressively. - -**Working files to maintain**: - -| File | Purpose | -|------|---------| -| Query log | Every query/search with its results. What did you ask, what came back. Keeps work auditable and reproducible. | -| Questions & Answers | Running list of research questions. As you find answers, record them. As answers suggest new questions, add those. This drives the iterative deepening. | -| Draft report | The evolving narrative. Updated as new findings emerge. Forces you to synthesize as you go rather than dumping data at the end. | - -**The iterative deepening pattern**: - -Analysis should deepen in layers, not stay shallow across many topics. Each answer should prompt "why?" or "what drives that?" questions: - -- **Layer 1**: Top-level facts. "What was our AWS spend last month?" -> $10k. "How does that compare to prior month?" -> Up $1k. -- **Layer 2**: Decomposition. "What services drove the spend?" -> $8k EC2, $1k S3, $1k other. "Where was the increase?" -> All in EC2. -- **Layer 3**: Root causes. "Is our EC2 fleet well-utilized?" -> Many instances with attribute X are underutilized. "Are specific workloads driving the increase?" -> Yes, instances tagged `daily_sync_*` are up ~$2k. -- **Layer 4+**: Continue until you hit actionable findings or diminishing returns. - -**When to stop deepening**: When additional queries aren't changing the narrative, or when you've answered the questions from the Align step to a sufficient depth. But make sure that any questions that a reasonable business person is likely to ask when looking at your output are answered. - -**Outputs**: The working files above (query log, Q&A tracker, draft report), organized in the dataroom alongside the final output. - -### 4. Review (Not a Separate Step) - -Reviews are not a standalone phase but checkpoints woven into all the steps, especially the Analyze step. Use DeepWork's `reviews` mechanism in `job.yml` to define quality gates. - -**Reviews to consider for the Analyze phase**: - -- **Query completeness**: Are the key research questions from the scoping document all addressed? Are queries recorded with their results? -- **Draft coherence**: Does the draft report tell a logical story? Are sections connected rather than isolated findings? -- **Depth adequacy**: Has the analysis gone deep enough on the important threads? Are there obvious follow-up questions left unasked? -- **Citation integrity**: Are claims in the draft backed by specific queries/sources from the query log? - -**Reviews to consider for the Present phase** (see below): - -- **Visual quality**: Charts render correctly, no overlapping text, readable at intended size. -- **Content accuracy**: Citations preserved from draft, numbers match source data, arguments are logically sound. -- **Audience fit**: Language, detail level, and framing match the intended audience (executives vs. engineers vs. clients). -- **Format compliance**: Output matches the requested format (PDF renders correctly, HTML is responsive, slides have consistent styling). - -### 5. Present - -**Purpose**: Transform the draft into a polished final deliverable. - -The draft report from the Analyze step has the right content but may not be presentation-ready. This step focuses on the output experience. - -**Common activities**: - -- **Visualizations**: Generate charts, tables, or diagrams from the data. Fetch relevant images. Create infographics for key findings. -- **Formatting**: Convert to the final output format (PDF, HTML, slides, etc.). Apply styling and layout. -- **Narrative polish**: Tighten prose, add executive summary, ensure the document flows well for someone reading it cold. -- **Supporting materials**: Assemble appendices, data tables, methodology notes. - -**This step often requires multiple review cycles.** Visual outputs have failure modes that text-only drafts don't: overlapping labels, truncated legends, broken page breaks, images that don't load. Build in quality gates for visual review. - -**Outputs**: The final deliverable in its target format, plus any supporting materials. - -## Translating This Into a Job Definition - -### Step Structure Options - -**Minimal (3 steps)** - For straightforward reports with known data sources: -1. `scope` - Combines Connect + Align. Verify access, clarify requirements. -2. `research` - The Analyze phase with built-in review gates. -3. `report` - The Present phase with visual/format review gates. - -**Standard (4 steps)** - For most research reports: -1. `connect` - Verify data source access. -2. `scope` - Align on research questions and definitions. -3. `analyze` - Core research with iterative deepening. -4. `present` - Final deliverable production. - -**Comprehensive (5+ steps)** - For complex, multi-source reports: -1. `connect` - Verify all data source access. -2. `scope` - Align on research questions. -3. `gather` - Collect raw data across all sources (query log output). -4. `analyze` - Synthesize findings, build narrative (draft report output). -5. `present` - Polish and format final deliverable. - -### Output Organization - -Follow the dataroom pattern from the define step guidelines: - -``` -operations/reports/2026-01/spending_analysis.md # Final report -operations/reports/2026-01/spending_analysis_dataroom/ # Supporting materials - query_log.md # All queries and results - questions_and_answers.md # Research Q&A tracker - raw_data/ # Extracted data files - charts/ # Generated visualizations - draft.md # Working draft (for audit trail) -``` - -### Quality Gate Design - -Research reports benefit from **split reviews** that evaluate content and presentation separately: - -```yaml -reviews: - # Content review - is the analysis sound? - - run_each: final_report.md - quality_criteria: - "Claims Cited": "Is every factual claim backed by a specific source or query from the dataroom?" - "Questions Answered": "Are all research questions from the scoping document addressed?" - "Depth": "Does the analysis go beyond surface-level observations to root causes or actionable insights?" - - # Presentation review - is the output polished? - - run_each: final_report.md - quality_criteria: - "Readable Flow": "Does the document flow logically for someone reading it without prior context?" - "Audience Fit": "Is the language and detail level appropriate for the intended audience?" - "Visual Quality": "Do all charts, tables, and figures render correctly and add value?" -``` - -### Capability Considerations - -Research jobs frequently need specialized tools. During the `define` step, ask about: - -- **Database access**: What databases? What client tools or connection strings? -- **Web browsing**: Will sites require authentication? Is Claude in Chrome available? -- **File generation**: Does the final output need PDF/HTML rendering? What tools are available? -- **Data visualization**: What charting libraries or tools can the agent use? - -## Anti-Patterns to Avoid - -**Shallow breadth over deep analysis**: Covering 20 topics superficially is less valuable than covering 5 topics with layered depth. Design the Analyze step to encourage iterative deepening, not checklist completion. - -**Skipping the scoping step**: Jumping straight into analysis without aligning on definitions and scope almost always leads to rework. "Analyze our churn" means very different things depending on how churn is defined. - -**Query results only in memory**: If queries and their results aren't written to working files, they can't be reviewed, cited, or audited. The query log is not optional. - -**Draft report written at the end**: The draft should evolve throughout the Analyze step, not be assembled from notes after all research is complete. Writing the narrative as you go reveals gaps in the analysis early. - -**Conflating analysis with presentation**: Trying to produce a polished PDF while still figuring out the findings leads to wasted formatting work. Get the content right first, then make it pretty. diff --git a/.deepwork/jobs/deepwork_jobs/steps/define.md b/.deepwork/jobs/deepwork_jobs/steps/define.md deleted file mode 100644 index 78ac1223..00000000 --- a/.deepwork/jobs/deepwork_jobs/steps/define.md +++ /dev/null @@ -1,443 +0,0 @@ -# Define Job Specification - -## Objective - -Create a `job.yml` specification file that defines the structure of a new DeepWork job by thoroughly understanding the user's workflow requirements through an interactive question-and-answer process. - -## 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.** - -**Important**: Use the AskUserQuestion tool to ask structured questions when gathering information from the user. This provides a better user experience with clear options and guided choices. - -The output of this step is **only** the `job.yml` file - a complete specification of the workflow. The actual step instruction files will be created in the next step (`implement`). - -### Step 1: Understand the Job Purpose - -Start by asking structured questions to understand what the user wants to accomplish: - -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) - - How often will they run this workflow? - -2. **What does success look like?** - - What's the final deliverable or outcome? - - Who is the audience for the output? - - What quality criteria matter most? - -3. **What are the major phases?** - - Ask them to describe the workflow at a high level - - What are the distinct stages from start to finish? - - Are there any dependencies between phases? - -### Step 2: Define Each Step - -For each major phase they mentioned, ask structured questions to gather details: - -1. **Step Purpose** - - What exactly does this step accomplish? - - What is the input to this step? - - What is the output from this step? - -2. **Step Inputs** - - What information is needed to start this step? - - Does it need user-provided parameters? (e.g., topic, target audience) - - Does it need files from previous steps? - - What format should inputs be in? - -3. **Step Outputs** - - What files or artifacts does this step produce? - - What format should the output be in? (markdown, YAML, JSON, etc.) - - 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? - #### 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? - -5. **Step Process** (high-level understanding) - - What are the key activities in this step? - - Are there any quality checks or validation needed? - - What makes a good vs. bad output for this step? - - **Important**: When skills are generated, quality criteria are automatically included in the output. Do not duplicate them in step instructions or details—this causes redundancy and confusion. - -**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. - -### Capability Considerations - -When defining steps, identify any that require specialized tools: - -**Browser Automation**: If any step involves web scraping, form filling, interactive browsing, UI testing, or research requiring website visits, ask the user what browser tools they have available. For Claude Code users, **Claude in Chrome** (Anthropic's browser extension) has been tested with DeepWork and is recommended for new users. Don't assume a default—confirm the tool before designing browser-dependent steps. - -### Parallel Sub-Workflow Pattern - -When a workflow needs to apply a multi-step process to many items independently (e.g., research each of 5 competitors, review each of 12 pull requests, analyze each file in a directory), **do not inline the repeated logic as a single step**. Instead, use the parallel sub-workflow pattern: - -1. **Define a separate workflow** for the process that will be repeated. This workflow handles one item at a time (e.g., `research_one_competitor` with steps like `gather_data` → `analyze` → `write_summary`). - -2. **In the main workflow**, add a step whose instructions tell the agent to launch the sub-workflow once per item using sub-agents (via the Task tool). Since each item is independent, these sub-workflow runs execute in parallel. - -**Why this matters:** -- **Parallelism**: Independent items are processed concurrently instead of sequentially, dramatically reducing wall-clock time -- **Quality gates**: Each sub-workflow run goes through its own review cycle, so a bad result for one item doesn't block the others -- **Reusability**: The sub-workflow can be invoked on its own for ad-hoc single-item runs - -**How to structure it in `job.yml`:** - -```yaml -workflows: - - name: full_analysis - summary: "Research all competitors end-to-end" - steps: - - identify_competitors - - research_all # This step launches research_one in parallel - - synthesize - - - name: research_one - summary: "Deep-dive research on a single competitor" - steps: - - gather_data - - analyze - - write_summary -``` - -The `research_all` step's instructions should tell the agent to: -- Read the list of items from the prior step's output -- Launch `research_one` as a sub-workflow for each item using parallel sub-agents (Task tool) -- Collect the results and confirm all runs completed - -**When to recognize this pattern:** Look for language like "for each X, do Y" where Y involves more than one logical phase. If Y is a single simple action, a regular step with a loop is fine. If Y is itself a multi-step process with intermediate outputs worth reviewing, split it into a sub-workflow. - -### Step 3: Validate the Workflow - -After gathering information about all steps: - -1. **Review the flow** - - Summarize the complete workflow - - Show how outputs from one step feed into the next - - Ask if anything is missing - -2. **Check for gaps** - - Are there any steps where the input isn't clearly defined? - - Are there any outputs that aren't used by later steps? - - Are there circular dependencies? - -3. **Confirm details** - - Job name (lowercase, underscores, descriptive) - - Job summary (one clear sentence, max 200 chars) - - Job description (detailed multi-line explanation) - - Version number (start with 1.0.0) - -### Step 4: Define Quality Reviews - -For each step, define **reviews** that evaluate the step's outputs. Reviews run automatically when a step completes and provide quality validation loops. - -For intermediate outputs between steps, reviews let you make sure you don't go too far down the wrong path. Add reviews that confirm things that could cause problems later. For example, in a report creation process, you might have an intermediate step that performs a number of queries on the data and records the results so that later report-writing steps can synthesize that information into a coherent narrative. In this case, you would want to add a review that checks that the queries SQL matches up with the description of the queries in the job description. - -For final outputs, reviews let you make sure the output meets the user's expectations. For example, with a data-centric report job, you might have one review on the final output for consistency with style guidelines and tone and such, and a totally separate review on the data-backing to make sure the claims in the report are supported by the data from earlier steps and all have citations. - -**Any jobs with written final output must always have reviews**. Some suggested ones are: -- Ensure claims have citations and the citations are not hallucinated -- Ensure the output follows the style guidelines and tone -- Ensure the output is well-organized and easy to read -- Ensure obvious questions the content raises have answers provided -- Visual formatting is correct (for things like PDF or HTML where the visual output matters) -- That the content matches what the intended audience expects (i.e. executives vs engineers) - -**Reviews format:** - -Each review specifies `run_each` (what to review) and `quality_criteria` (a map of criterion name to question): - -```yaml -reviews: - - run_each: step # Review all outputs together - quality_criteria: - "Consistent Style": "Do all files follow the same structure?" - "Complete Coverage": "Are all required topics covered?" - - run_each: report_files # Review each file in a 'files'-type output individually - quality_criteria: - "Well Written": "Is the content clear and well-organized?" - "Data-Backed": "Are claims supported by data?" -``` - -**`run_each` options:** -- `step` — Review runs once with ALL output files -- `` where output is `type: file` — Review runs once with that specific file -- `` where output is `type: files` — Review runs once per file in the list - -**`additional_review_guidance`** (optional): Tells the reviewer what other files or context to look at when performing the review. Reviewers only see the step's output files by default — they do NOT automatically see inputs from prior steps. When a review needs context beyond the output files (e.g., checking that an output is consistent with a prior step's deliverable, or that it follows conventions in a config file), use this field to tell the reviewer what to read. - -```yaml -reviews: - - run_each: report_files - additional_review_guidance: "Read the comparison_matrix.md file for context on whether claims in the report are supported by the analysis data." - quality_criteria: - "Data-Backed": "Are recommendations supported by the competitive analysis data?" - - run_each: step_instruction_files - additional_review_guidance: "Read the job.yml file in the same job directory for context on how this instruction file fits into the larger workflow." - quality_criteria: - "Complete Instructions": "Is the instruction file complete?" -``` - -**When to use `additional_review_guidance`:** -- When a review criterion references data or context from a prior step's output -- When the reviewer needs to cross-check the output against a specification, config, or schema file -- When the review involves consistency checks between the current output and other project files -- When the criterion mentions something the reviewer can't assess from the output alone - -**When NOT to use it:** -- When all criteria can be evaluated by reading just the output files themselves (e.g., "Is it well-written?", "Are there spelling errors?") -- Don't use it to dump large amounts of content — keep guidance short and tell the reviewer *what to read*, not *what's in it* - -**Reviews are particularly valuable for:** -- Steps with complex outputs that need multiple quality checks -- Steps where quality is critical (final deliverables) -- Steps with subjective quality criteria that benefit from AI self-review -- Steps producing multiple files where each file needs individual review - -**Quality review timeout considerations:** -Each individual quality review call has a 120-second timeout. For `run_each: ` with `files`-type outputs, each file gets its own separate review call — so having many files does NOT cause timeout accumulation. Timeout risk is only for individual reviews that are complex, such as: -- Reviewing a single very large file (500+ lines) with many criteria -- Review criteria that require cross-referencing large amounts of context -For these cases: -- Keep review criteria focused and efficient to evaluate -- Consider using `run_each: step` (reviews all outputs together once) if the per-file reviews are unnecessary -- The agent can use `quality_review_override_reason` to bypass a timed-out review, but this loses the quality gate benefit - -**For steps with no quality checks needed, use an empty reviews list:** -```yaml -reviews: [] -``` - -### Step 5: Create the Job Directory and Specification - -Only after you have complete understanding, create the job directory and `job.yml` file: - -**First, create the directory structure** using the `make_new_job.sh` script: - -```bash -.deepwork/jobs/deepwork_jobs/make_new_job.sh [job_name] -``` - -**Then create the job.yml file** at `.deepwork/jobs/[job_name]/job.yml` - -(Where `[job_name]` is the name of the NEW job you're creating, e.g., `competitive_research`) - -**Template reference**: See `.deepwork/jobs/deepwork_jobs/templates/job.yml.template` for the standard structure. - -**Complete example**: See `.deepwork/jobs/deepwork_jobs/templates/job.yml.example` for a fully worked example. - -**Important**: -- Use lowercase with underscores for job name and step IDs -- Ensure file inputs reference steps in dependencies -- No circular dependencies -- At least one output per step -- The `summary` should be concise (max 200 chars) -- The `description` should provide rich context for future refinement -- Include a `changelog` section with an initial entry for version 1.0.0 - -## Example Dialog - -``` -Claude: I'll help you define a new DeepWork job. Let's start by understanding what you're trying to accomplish. - -What complex task or workflow are you trying to create? What's the overall goal? - -User: I want to create competitive research reports for my company - -Claude: Great! Let's dig into that. A few questions: - -1. What's the final deliverable? Is it a written report, a presentation, or something else? -2. Who is the audience? Your team, executives, clients? -3. How comprehensive should these reports be? - -User: It's a written report for our product team. Should be comprehensive - analyzing 3-5 competitors. - -Claude: Perfect. Now let's think about the major phases of creating this report. What are the main stages you go through? For example: -- Identifying which competitors to analyze? -- Gathering information about them? -- Analyzing the data? -- Writing the report? - -Or is your process different? - -User: Yes, that's close. I would say: -1. Identify competitors -2. Research each one -3. Create comparison analysis -4. Write positioning recommendations - -Claude: Excellent! Now let's define each step in detail. Starting with "Identify competitors": - -1. What inputs do you need to start? Do you already have a market segment in mind, or do you need to specify that? -2. What should the output look like? A list of competitor names? More detailed? -3. How many competitors should be identified? - -User: I need to specify the market segment and product category as inputs. The output should be a markdown file with 5-7 competitors and brief descriptions of each. - -Claude: Perfect. A few more questions about that output: -1. What should the file be called? Something like `competitors_list.md`? -2. Should it go in the project root, or in a subdirectory like `research/` or `data/`? - -User: Just call it `competitors_list.md` in the project root. - -Claude: Great. Now for the "Research each one" step: -1. Does it use the competitor list from the first step as input? -2. What kind of research - product features, pricing, marketing, all of the above? -3. What format should the research output be in? -4. Where should that research be saved? - -[continues for each step...] - -[After gathering all information:] - -Claude: Let me summarize the workflow I've designed based on our conversation: - -**Job: competitive_research** -Summary: Systematic competitive analysis workflow for product positioning - -Description: -A comprehensive workflow for analyzing competitors in your market segment. This job helps product teams understand the competitive landscape by systematically identifying competitors, researching their offerings, creating comparison matrices, and developing strategic positioning recommendations. - -The workflow produces: -- A vetted list of key competitors -- Detailed research notes on each competitor -- A comparison matrix highlighting key differentiators -- Strategic positioning recommendations - -Designed for product teams conducting quarterly competitive analysis. - -**Steps:** - -Step 1: identify_competitors -- Input: market_segment (user), product_category (user) -- Output: competitors_list.md (5-7 competitors with descriptions) - -Step 2: research_competitors -- Input: competitors_list.md (from step 1) -- Output: research_notes.md (detailed findings for each competitor) -- Depends on: identify_competitors - -Step 3: comparative_analysis -- Input: research_notes.md (from step 2) -- Output: comparison_matrix.md (side-by-side analysis) -- Depends on: research_competitors - -Step 4: positioning_recommendations -- Input: comparison_matrix.md (from step 3) -- Output: positioning_report.md (strategic recommendations) -- Depends on: comparative_analysis - -Does this accurately capture your workflow? Any changes needed? - -User: Yes, that's perfect! - -Claude: Great! Creating the job.yml specification now... - -[Creates .deepwork/jobs/competitive_research/job.yml with the complete spec] - -✓ Job specification created! - -**File created:** -- .deepwork/jobs/competitive_research/job.yml - -**Next step:** -Implement the job to generate step instruction files. -``` - -## Important Guidelines - -1. **Focus on specification only** - Don't create instruction files yet -2. **Ask structured questions** - Never skip the discovery phase; use the AskUserQuestion tool -3. **Rich context in description** - This helps with future refinement -4. **Validate understanding** - Summarize and confirm before creating -5. **Use examples** - Help users understand what good specifications look like -6. **Understand file organization** - Always ask structured questions about where outputs should be saved and if subdirectories are needed - -## Validation Rules - -Before creating the job.yml, ensure: -- Job name: lowercase, underscores, no spaces -- Version: semantic versioning (1.0.0) -- Summary: concise, under 200 characters -- Description: detailed, provides context -- Step IDs: unique, descriptive, lowercase with underscores -- Dependencies: must reference existing step IDs -- File inputs: `from_step` must be in dependencies -- At least one output per step -- Outputs can be filenames (e.g., `report.md`) or paths (e.g., `reports/analysis.md`) -- File paths in outputs should match where files will actually be created -- No circular dependencies - -## Output Format - -### job.yml - -The complete YAML specification file (example shown in Step 5 above). - -**Location**: `.deepwork/jobs/[job_name]/job.yml` - -(Where `[job_name]` is the name of the new job being created) - -After creating the file: -1. Inform the user that the specification is complete -2. Recommend that they review the job.yml file -3. Tell them the next step is to implement the job (generate step instruction files) - diff --git a/.deepwork/jobs/deepwork_jobs/steps/errata.md b/.deepwork/jobs/deepwork_jobs/steps/errata.md deleted file mode 100644 index 10245c62..00000000 --- a/.deepwork/jobs/deepwork_jobs/steps/errata.md +++ /dev/null @@ -1,170 +0,0 @@ -# Clean Up Errata - -## Objective - -Remove obsolete files and folders from prior DeepWork versions. This final step cleans up artifacts that are no longer used by the MCP-based system. - -## Task - -Identify and clean up deprecated files and folders. - -### Step 1: Remove Legacy Job Skill Folders - -Old DeepWork versions created individual skill folders for each job and step. These need to be removed while preserving the main `deepwork` skill folder. - -**Process:** - -1. **List all jobs** in `.deepwork/jobs/`: - ```bash - ls .deepwork/jobs/ - ``` - -2. **For each job**, kick off a sub-agent to find and remove legacy skill folders. The sub-agent should: - - Search in both `.claude/skills/` and `.gemini/skills/` - - Find folders matching: - - `{job_name}/` - folder named exactly like the job - - `{job_name}.*/` - folders starting with the job name followed by a period (e.g., `my_job.step1/`, `my_job.step2/`) - - Remove each matching folder - - Report what was removed - - **Example commands for a job named `competitive_research`:** - ```bash - # Find and remove from .claude/skills/ - rm -rf .claude/skills/competitive_research/ 2>/dev/null - rm -rf .claude/skills/competitive_research.*/ 2>/dev/null - - # Find and remove from .gemini/skills/ - rm -rf .gemini/skills/competitive_research/ 2>/dev/null - rm -rf .gemini/skills/competitive_research.*/ 2>/dev/null - ``` - -3. **Run sub-agents in parallel** - one for each job to speed up the process. - -4. **Verify the `deepwork` skill folder remains:** - ```bash - ls -d .claude/skills/deepwork/ 2>/dev/null || echo "ERROR: deepwork skill missing!" - ls -d .gemini/skills/deepwork/ 2>/dev/null || echo "WARNING: gemini deepwork skill missing (may not have been installed)" - ``` - - **CRITICAL:** The `deepwork` skill folder in `.claude/skills/deepwork/` MUST still exist after cleanup. If it is missing, something went wrong - do NOT proceed and investigate what happened. - -**What this removes:** -``` -.claude/skills/ -├── competitive_research/ <- REMOVE (legacy job folder) -├── competitive_research.discover/ <- REMOVE (legacy step folder) -├── competitive_research.analyze/ <- REMOVE (legacy step folder) -├── deepwork/ <- KEEP (current MCP entry point) -└── some_other_job/ <- REMOVE (legacy job folder) -``` - -**Do NOT remove:** -- `.claude/skills/deepwork/` - This is the current MCP-based skill entry point -- `.gemini/skills/deepwork/` - Same for Gemini -- Any skill folders that don't match job names in `.deepwork/jobs/` - -### Step 2: Clean Temp Files - -Check `.deepwork/tmp/` for accumulated temporary files: - -```bash -ls -la .deepwork/tmp/ 2>/dev/null || echo "No tmp folder" -``` - -**Safe to delete:** -- `.deepwork/tmp/rules/queue/*.json` - Old rules queue files -- Any files older than 7 days -- Empty subdirectories - -**Be careful with:** -- Files that might be in-progress work -- Anything with recent modification times - -```bash -# Clean old queue files -rm -rf .deepwork/tmp/rules/queue/*.json 2>/dev/null - -# Remove empty directories -find .deepwork/tmp -type d -empty -delete 2>/dev/null -``` - -### Step 3: Remove Rules Folder (Fully Deprecated) - -DeepWork Rules have been completely removed from the system. Delete the `.deepwork/rules/` folder and all related items: - -```bash -rm -rf .deepwork/rules/ 2>/dev/null -rm -rf .deepwork/tmp/rules/ 2>/dev/null -rm -rf .deepwork/jobs/deepwork_rules/ 2>/dev/null -``` - -### Step 4: Update Config Version - -Check `.deepwork/config.yml` for outdated version format: - -```bash -cat .deepwork/config.yml -``` - -**Old format:** -```yaml -version: 1.0.0 -platforms: -- claude -``` - -**Current format:** -```yaml -version: "1.0" -platforms: - - claude -``` - -Update if needed to match current schema expectations. - -### Step 5: Remove Other Obsolete Files - -Check for and remove other obsolete files: - -| File/Pattern | Description | Action | -|--------------|-------------|--------| -| `.deepwork/.last_head_ref` | Git state tracking | Keep (used by MCP) | -| `.deepwork/.last_work_tree` | Git state tracking | Keep (used by MCP) | -| `.deepwork/.gitignore` | Ignore patterns | Review and update | -| `.claude/commands/` | Generated commands | Keep (current system) | -| `.claude/settings.local.json` | Local overrides | Keep (user settings) | - -### Step 6: Re-install DeepWork - -After all cleanup is complete, re-run `deepwork install` to ensure configurations are current and consistent: - -```bash -deepwork install -``` - -**Then verify:** -1. Check that `.deepwork/config.yml` is valid and up to date -2. Check that `.claude/skills/deepwork/` exists and contains the expected skill entry point -3. Check that all jobs in `.deepwork/jobs/` have valid `job.yml` files -4. Run `deepwork install` a second time and confirm the output is clean (no errors or warnings) - -If any issues are found, fix them before proceeding. The goal is a clean, working DeepWork installation with no residual problems from the repair process. - -### Step 7: Verify Git Status - -Check that the cleanup hasn't left untracked garbage: - -```bash -git status -``` - -**Review:** -- Deleted files should show as deleted -- No new untracked files should appear (unless intentionally created) -- Backup files (`.backup`) should be in `.gitignore` or cleaned up - -## Important Notes - -1. **Always back up before deleting** - User data is irreplaceable -2. **Ask before destructive actions** - When in doubt, ask the user -3. **Don't auto-commit** - Let the user review and commit changes themselves diff --git a/.deepwork/jobs/deepwork_jobs/steps/fix_jobs.md b/.deepwork/jobs/deepwork_jobs/steps/fix_jobs.md deleted file mode 100644 index ccb5e4a4..00000000 --- a/.deepwork/jobs/deepwork_jobs/steps/fix_jobs.md +++ /dev/null @@ -1,307 +0,0 @@ -# Fix Job Definitions - -## Objective - -Update all job.yml files and step instructions in `.deepwork/jobs/` to the current DeepWork format. This step migrates deprecated fields, removes references to deleted steps, and ensures all jobs are compatible with the MCP-based workflow system. - -## Task - -Audit and repair all job definitions, migrating from legacy formats to current specifications. - -### Step 1: Inventory All Jobs - -List all jobs in the project: - -```bash -ls -la .deepwork/jobs/ -``` - -For each job directory, you'll need to check and potentially fix the `job.yml` file. - -### Step 1.5: Process Jobs in Parallel - -**For each job** (except `deepwork_jobs` which should be updated via `deepwork install`), kick off a sub-agent to audit and repair that job's `job.yml` file. The sub-agent should: - -1. Read the job's `job.yml` file -2. Check for and fix all issues described in Steps 2-6 below -3. Validate the YAML is still valid after changes -4. Report what was changed - -**Run sub-agents in parallel** - one for each job to speed up the process. - -**Example prompt for sub-agent:** -``` -Audit and repair the job at `.deepwork/jobs/[job_name]/job.yml`: -1. Remove any `exposed: true` fields from steps -2. Migrate `stop_hooks` to `hooks.after_agent` format -3. Remove references to deleted steps (like `review_job_spec`) -4. Fix orphaned steps by adding them to workflows -5. Migrate `outputs` from array format to map format with `type` and `description` -6. Update any `file` inputs that reference renamed output keys -7. Migrate `quality_criteria` arrays to `reviews` format (run_each + map criteria) -8. Bump version and add changelog entry if changes were made -9. Validate YAML syntax - -Report what changes were made. -``` - -### Step 2: Remove `exposed` Field - -The `exposed` field on steps no longer has any effect in MCP-based DeepWork. Steps are now only accessible through workflows. - -**Find and remove:** -```yaml -steps: - - id: some_step - exposed: true # REMOVE THIS LINE -``` - -If a step was `exposed: true` and is not in any workflow, it should either: -1. Be added to a workflow, OR -2. Be removed from the job entirely - -### Step 3: Migrate `stop_hooks` to `hooks.after_agent` - -The `stop_hooks` field is deprecated. Migrate to the new `hooks` structure: - -**Before (deprecated):** -```yaml -steps: - - id: my_step - stop_hooks: - - prompt: "Verify the output meets quality standards" -``` - -**After (current format):** -```yaml -steps: - - id: my_step - hooks: - after_agent: - - prompt: "Verify the output meets quality standards" -``` - -### Step 4: Remove References to Deleted Steps - -Check for references to steps that no longer exist in the standard jobs: - -**Steps that have been removed:** -- `review_job_spec` - Was removed from `deepwork_jobs` in v1.0.1 - -**What to fix:** -- Remove from workflow `steps` arrays -- Update `from_step` references in inputs -- Update `dependencies` arrays - -**Example fix:** -```yaml -# Before -workflows: - - name: new_job - steps: - - define - - review_job_spec # REMOVE - - implement - -steps: - - id: implement - inputs: - - file: job.yml - from_step: review_job_spec # CHANGE TO: define - dependencies: - - review_job_spec # CHANGE TO: define -``` - -### Step 5: Fix Orphaned Steps - -Steps not included in any workflow cannot be invoked via the MCP interface. - -**How to handle orphaned steps depends on whether the job has ANY workflows defined:** - -#### Case A: Job has NO workflows defined - -If the job has no `workflows:` section at all (or it's empty), create a **single workflow with the same name as the job** containing all steps in their defined order: - -```yaml -# For a job named "my_job" with steps: step_a, step_b, step_c -workflows: - - name: my_job # Same name as the job - summary: "Runs the complete my_job workflow" - steps: - - step_a - - step_b - - step_c -``` - -This preserves the original intent of the job as a sequential workflow. - -#### Case B: Job has SOME workflows defined - -If the job already has one or more workflows defined, but some steps are not included in any of them, create a **separate single-step workflow for each orphaned step** with the same name as the step: - -```yaml -# Existing workflows stay as-is, add new ones for orphans -workflows: - - name: existing_workflow - summary: "..." - steps: [...] - - # Add for each orphaned step: - - name: orphaned_step_name # Same name as the step - summary: "Runs the orphaned_step_name step" - steps: - - orphaned_step_name -``` - -This ensures all steps remain accessible via the MCP interface while preserving the existing workflow structure. - -### Step 6: Migrate `outputs` from Array Format to Map Format - -The `outputs` field on steps changed from an array of strings/objects to a map with typed entries. Every output must now have a key (identifier), a `type` (`file` or `files`), and a `description`. - -**Before (legacy array format):** -```yaml -steps: - - id: define - outputs: - - job.yml - - steps/ - - file: report.md - doc_spec: .deepwork/doc_specs/report.md -``` - -**After (current map format):** -```yaml -steps: - - id: define - outputs: - job.yml: - type: file - description: "The job definition file" - step_instruction_files: - type: files - description: "Instruction Markdown files for each step" - report.md: - type: file - description: "The generated report" -``` - -**Migration rules:** - -1. **Plain filename strings** (e.g., `- job.yml`, `- output.md`): Use the filename as the key, set `type: file`, add a `description`. -2. **Directory strings ending in `/`** (e.g., `- steps/`, `- competitor_profiles/`): Choose a descriptive key name (e.g., `step_instruction_files`, `competitor_profiles`), set `type: files`, add a `description`. -3. **Objects with `doc_spec`** (e.g., `- file: report.md` with `doc_spec: ...`): Drop the `doc_spec` field entirely, use the filename as the key, set `type: file`, add a `description`. -4. **`description` is required** on every output entry. Write a short sentence describing what the output contains. - -**Update `file` inputs that reference renamed outputs:** - -When a directory output key changes (e.g., `steps/` becomes `step_instruction_files`), any downstream step with a `file` input referencing the old name must be updated to use the new key. - -```yaml -# Before: input references old directory name -steps: - - id: implement - inputs: - - file: steps/ - from_step: define - -# After: input uses the new output key -steps: - - id: implement - inputs: - - file: step_instruction_files - from_step: define -``` - -### Step 7: Migrate `quality_criteria` to `reviews` - -The flat `quality_criteria` field on steps has been replaced by the `reviews` array. Each review specifies `run_each` (what to review) and `quality_criteria` as a map of criterion name to question. - -**Before (deprecated):** -```yaml -steps: - - id: my_step - quality_criteria: - - "**Complete**: Is the output complete?" - - "**Accurate**: Is the data accurate?" -``` - -**After (current format):** -```yaml -steps: - - id: my_step - reviews: - - run_each: step - quality_criteria: - "Complete": "Is the output complete?" - "Accurate": "Is the data accurate?" -``` - -**Migration rules:** - -1. **Parse the old format**: Each string typically follows `**Name**: Question` format. Extract the name (bold text) as the map key and the question as the value. -2. **Choose `run_each`**: Default to `step` (reviews all outputs together). If the step has a single primary output, consider using that output name instead. -3. **For steps with no quality_criteria**: Use `reviews: []` -4. **Remove the old field**: Delete the `quality_criteria` array entirely after migration. - -### Step 8: Update Version Numbers - -If you made significant changes to a job, bump its version number: - -```yaml -# Bump patch version for minor fixes -version: "1.0.0" -> version: "1.0.1" - -# Add changelog entry -changelog: - - version: "1.0.1" - changes: "Migrated to current DeepWork format; removed deprecated fields" -``` - -## Common Issues and Fixes - -### Issue: Step references non-existent step in `from_step` -``` -Error: Step 'implement' has file input from 'review_job_spec' but 'review_job_spec' is not in dependencies -``` -**Fix:** Update `from_step` to reference a step that still exists. - -### Issue: Workflow references non-existent step -``` -Error: Workflow 'new_job' references non-existent step 'review_job_spec' -``` -**Fix:** Remove the step from the workflow's `steps` array. - -### Issue: Orphaned step warning -``` -Warning: Job 'my_job' has steps not included in any workflow: standalone_step -``` -**Fix:** -- If the job has NO workflows: Create one workflow named `my_job` with all steps in order -- If the job has SOME workflows: Add a `standalone_step` workflow containing just that step - -### Issue: `outputs` is an array instead of an object -``` -Error: Step 'define' outputs should be an object but got array -``` -**Fix:** Convert from the legacy array format to the map format. Each array entry becomes a key in the map with `type` (`file` or `files`) and `description`. See Step 6 for detailed migration rules. Also update any `file` inputs in downstream steps if an output key was renamed. - -## Jobs to Check - -For each job in `.deepwork/jobs/`, check: - -| Check | What to Look For | -|-------|------------------| -| `exposed` field | Remove from all steps | -| `stop_hooks` | Migrate to `hooks.after_agent` | -| `outputs` format | Migrate from array to map with `type` and `description` | -| `quality_criteria` | Migrate to `reviews` with `run_each` and map-format criteria | -| Workflow steps | Remove references to deleted steps | -| Dependencies | Update to valid step IDs | -| File inputs | Update `from_step` references; update keys for renamed outputs | -| Version | Bump if changes were made | - -## Important Notes - -1. **Preserve custom logic** - When migrating hooks, preserve the prompt content -2. **Test after changes** - Validate YAML syntax after each job fix to catch errors early diff --git a/.deepwork/jobs/deepwork_jobs/steps/fix_settings.md b/.deepwork/jobs/deepwork_jobs/steps/fix_settings.md deleted file mode 100644 index d164b69e..00000000 --- a/.deepwork/jobs/deepwork_jobs/steps/fix_settings.md +++ /dev/null @@ -1,177 +0,0 @@ -# Fix Settings Files - -## Objective - -Clean up `.claude/settings.json` and related configuration files, removing legacy artifacts from prior DeepWork versions. This step ensures the Claude Code settings are free of deprecated permissions, duplicate hooks, and hardcoded paths. - -## Task - -Audit and repair the `.claude/settings.json` file, removing gunk accumulated from older DeepWork implementations. - -### Step 1: Create Backup - -Before making any changes, create a backup: - -```bash -cp .claude/settings.json .claude/settings.json.backup -``` - -### Step 2: Inventory DeepWork Jobs - -First, get the list of jobs that exist in `.deepwork/jobs/`: - -```bash -ls .deepwork/jobs/ -``` - -Note these job names - you will use them to identify which `Skill(...)` entries to remove. - -### Step 3: Remove DeepWork Skill Permissions - -Look for and **remove** `Skill(...)` permission entries that match DeepWork jobs. Only remove entries where the skill name matches a job in `.deepwork/jobs/`. - -**What to look for:** -```json -"permissions": { - "allow": [ - "Skill(deepwork_jobs)", // Remove if 'deepwork_jobs' is in .deepwork/jobs/ - "Skill(deepwork_jobs.define)", // Remove - matches job_name.step pattern - "Skill(competitive_research)", // Remove if 'competitive_research' is in .deepwork/jobs/ - "Skill(my_custom_skill)", // KEEP - not a DeepWork job - ... - ] -} -``` - -**IMPORTANT:** Only remove skills that: -- Exactly match a job name in `.deepwork/jobs/` (e.g., `Skill(job_name)`) -- Match the pattern `job_name.step_name` where `job_name` is in `.deepwork/jobs/` - -**DO NOT remove** skills that don't match DeepWork jobs - the user may have created these manually for other purposes. - -### Step 4: Remove Duplicate Hooks - -Check for duplicate hook entries in the `hooks` section. Prior versions sometimes added the same hook multiple times. - -**Example of duplicates to consolidate:** -```json -"hooks": { - "UserPromptSubmit": [ - { - "matcher": "", - "hooks": [{ "type": "command", "command": "some_command" }] - }, - { - "matcher": "", - "hooks": [{ "type": "command", "command": "some_command" }] // DUPLICATE - } - ] -} -``` - -Keep only one instance of each unique hook. - -### Step 5: Remove Hardcoded User Paths - -Search for and remove any hardcoded paths that reference specific user directories: - -**Patterns to find and remove:** -- `/Users/username/.local/pipx/venvs/deepwork/bin/python` -- `/home/username/.local/...` -- Any path containing a specific username - -These should either be removed or replaced with relative paths. - -### Step 6: Remove DeepWork Rules Hooks (Fully Deprecated) - -DeepWork Rules have been completely removed from the system. Remove ALL hooks related to rules: - -**Hooks to remove entirely:** -- Any hook with command `deepwork hook rules_check` -- Any hook with command containing `rules_check` -- Any hook referencing `.deepwork/jobs/deepwork_rules/hooks/` -- Any hook referencing `.deepwork/rules/` - -**Also remove these permissions if present:** -- `Skill(deepwork_rules)` -- `Skill(deepwork_rules.define)` -- `Bash(rm -rf .deepwork/tmp/rules/queue/*.json)` - -### Step 7: Remove Other Deprecated Commands - -Remove hooks referencing other deprecated DeepWork commands: - -**Commands to remove:** -- `deepwork hook *` - The entire hook subcommand is deprecated -- References to any `.deepwork/jobs/*/hooks/` scripts - -### Step 8: Clean Up Empty Sections - -If after cleanup any sections are empty, consider removing them: - -```json -// Remove if empty: -"hooks": { - "Stop": [] // Remove this empty array -} -``` - -### Step 9: Validate JSON - -After all edits, ensure the file is valid JSON: - -```bash -python -c "import json; json.load(open('.claude/settings.json'))" -``` - -If there are syntax errors, fix them before proceeding. - -## Example Before/After - -### Before (with gunk): -```json -{ - "hooks": { - "UserPromptSubmit": [ - { "matcher": "", "hooks": [{ "type": "command", "command": ".deepwork/jobs/deepwork_rules/hooks/user_prompt_submit.sh" }] }, - { "matcher": "", "hooks": [{ "type": "command", "command": ".deepwork/jobs/deepwork_rules/hooks/user_prompt_submit.sh" }] } - ], - "Stop": [ - { "matcher": "", "hooks": [{ "type": "command", "command": "deepwork hook rules_check" }] } - ], - "SubagentStop": [ - { "matcher": "", "hooks": [{ "type": "command", "command": "/Users/tyler/.local/pipx/venvs/deepwork/bin/python -m deepwork.hooks.rules_check" }] } - ] - }, - "permissions": { - "allow": [ - "Skill(competitive_research)", - "Skill(competitive_research.discover_competitors)", - "Skill(deepwork_jobs)", - "Skill(deepwork_jobs.define)", - "Read(./.deepwork/**)", - "WebSearch" - ] - } -} -``` - -### After (cleaned): -```json -{ - "hooks": {}, - "permissions": { - "allow": [ - "Read(./.deepwork/**)", - "WebSearch" - ] - } -} -``` - -## Important Notes - -1. **Don't remove non-DeepWork permissions** - Keep permissions like `WebSearch`, `Read(...)`, `Bash(...)` that aren't related to old DeepWork skills -2. **Preserve `make_new_job.sh`** - Keep any `Bash(...)` permission referencing `make_new_job.sh` (e.g., `Bash(.deepwork/jobs/deepwork_jobs/scripts/make_new_job.sh *)`) - this is a current DeepWork script -3. **Be conservative** - If unsure whether something is legacy, ask the user -4. **Document changes** - Note what was removed for the final summary diff --git a/.deepwork/jobs/deepwork_jobs/steps/implement.md b/.deepwork/jobs/deepwork_jobs/steps/implement.md deleted file mode 100644 index 73eeb365..00000000 --- a/.deepwork/jobs/deepwork_jobs/steps/implement.md +++ /dev/null @@ -1,121 +0,0 @@ -# Implement Job Steps - -## Objective - -Generate step instruction files for each step based on the `job.yml` specification from the define step. - -## Task - -Read the `job.yml` specification file created by the define step and generate comprehensive instruction files for each step. The define step has already created the job directory structure. - -### Step 1: Read and Validate the Specification - -1. **Locate the job.yml file** - - Read `.deepwork/jobs/[job_name]/job.yml` from the define step - - Parse the YAML content - -2. **Validate the specification** - - Ensure it follows the schema (name, version, summary, description, steps) - - Check that all dependencies reference existing steps - - Verify no circular dependencies - - Confirm file inputs match dependencies - -3. **Extract key information** - - Job name, version, summary, description - - List of all steps with their details - - Understand the workflow structure - -### 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`. - -**Template reference**: See `.deepwork/jobs/deepwork_jobs/templates/step_instruction.md.template` for the standard structure. - -**Complete example**: See `.deepwork/jobs/deepwork_jobs/templates/step_instruction.md.example` for a fully worked example. - -**Available templates in `.deepwork/jobs/deepwork_jobs/templates/`:** -- `job.yml.template` - Job specification structure -- `step_instruction.md.template` - Step instruction file structure -- `agents.md.template` - AGENTS.md file structure -- `job.yml.example` - Complete job specification example -- `step_instruction.md.example` - Complete step instruction example - -**Guidelines for generating instructions:** - -1. **Use the job description** - The detailed description from job.yml provides crucial context -2. **Be specific** - Don't write generic instructions; tailor them to the step's purpose -3. **Provide output format examples** - Include a markdown code block in an "Output Format" section showing the expected file structure. A template with `[bracket placeholders]` is acceptable. For complex outputs, also include a concrete filled-in example showing realistic data — this is especially valuable for the first step in a workflow where there's no prior output to reference. -4. **Explain the "why"** - Help the user understand the step's role in the workflow -5. **Quality over quantity** - Detailed, actionable instructions are better than vague ones -6. **Align with reviews** - If the step has `reviews` defined, ensure the quality criteria in the instruction file match the review criteria -7. **Ask structured questions (when applicable)** - When a step has user-provided inputs (name/description inputs in job.yml), the instructions MUST explicitly tell the agent to "ask structured questions" using the AskUserQuestion tool. Steps that only have file inputs from prior steps do NOT need this phrase — they process data without user interaction. -8. **Handle edge cases** - If inputs might be missing, ambiguous, or incomplete, tell the agent to ask structured questions to clarify how to proceed rather than guessing - -### Handling Reviews - -If a step in the job.yml has `reviews` defined, the generated instruction file should: - -1. **Mirror the quality criteria** - The "Quality Criteria" section should match what the reviews will validate -2. **Be explicit about success** - Help the agent understand when the step is truly complete -3. **Explain what's reviewed** - If reviews target specific outputs (via `run_each`), mention which outputs will be reviewed - -**Example: If the job.yml has:** -```yaml -- id: research_competitors - name: "Research Competitors" - reviews: - - run_each: research_notes.md - quality_criteria: - "Sufficient Data": "Does each competitor have at least 3 data points?" - "Sources Cited": "Are sources cited for key claims?" - "Current Information": "Is the information current (within last year)?" -``` - -**The instruction file should include:** -```markdown -## Quality Criteria - -- Each competitor has at least 3 distinct data points -- All information is sourced with citations -- Data is current (from within the last year) -``` - -This alignment ensures the AI agent knows exactly what will be validated and can self-check before completing. - -### Using Supplementary Reference Files - -Step instructions can include additional `.md` files in the `steps/` directory for detailed examples, templates, or reference material. Reference them using the full path from the project root. - -See `.deepwork/jobs/deepwork_jobs/steps/supplemental_file_references.md` for detailed documentation and examples. - -### Step 3: Verify Files - -Verify that all files are in their correct locations: -- `job.yml` at `.deepwork/jobs/[job_name]/job.yml` (created by define step) -- Step instruction files at `.deepwork/jobs/[job_name]/steps/[step_id].md` - -## Example Implementation - -For a complete worked example showing a job.yml and corresponding step instruction file, see: -- **Job specification**: `.deepwork/jobs/deepwork_jobs/templates/job.yml.example` -- **Step instruction**: `.deepwork/jobs/deepwork_jobs/templates/step_instruction.md.example` - -## Important Guidelines - -1. **Read the spec carefully** - Understand the job's intent from the description -2. **Generate complete instructions** - Don't create placeholder or stub files -3. **Maintain consistency** - Use the same structure for all step instruction files -4. **Provide examples** - Show what good output looks like -5. **Use context** - The job description provides valuable context for each step -6. **Be specific** - Tailor instructions to the specific step, not generic advice - -## Completion Checklist - -Before marking this step complete, ensure: -- [ ] job.yml validated and in job directory -- [ ] All step instruction files created -- [ ] Each instruction file is complete and actionable - -## Note: Workflow Availability - -Once the job.yml and step instruction files are created, the workflow is immediately available through the DeepWork MCP server. The MCP server reads job definitions directly from `.deepwork/jobs/` - no separate sync or installation step is required. \ No newline at end of file diff --git a/.deepwork/jobs/deepwork_jobs/steps/iterate.md b/.deepwork/jobs/deepwork_jobs/steps/iterate.md deleted file mode 100644 index 73dcb589..00000000 --- a/.deepwork/jobs/deepwork_jobs/steps/iterate.md +++ /dev/null @@ -1,226 +0,0 @@ -# Iterate on Workflow Design - -## Objective - -Review the test run conversation and improve the job definition based on what happened. This step closes the feedback loop by incorporating learnings from the test into the workflow itself, making future runs more efficient and producing better results. - -## Task - -Analyze the conversation history from the test step, identify areas for improvement, and update the job definition and step instructions accordingly. - -### Step 1: Review the Conversation History - -Carefully analyze the conversation from the test step, looking for: - -1. **Process Inefficiencies** - - Steps that took multiple attempts to complete - - Questions the agent had to ask that should have been in the instructions - - Unnecessary back-and-forth with the user - - Information that had to be repeated - -2. **Output Quality Issues** - - Issues identified during critique (from Step 3 of test) - - Corrections requested by the user - - Patterns in user feedback (what did they consistently want changed?) - -3. **Tool Usage Problems** - - Tools that didn't work as expected - - Missing tools that would have helped - - Inefficient tool sequences - -4. **Missing or Unclear Instructions** - - Ambiguities that led to wrong outputs - - Missing guidance that caused confusion - - Quality criteria that weren't clear enough - -### Step 2: Plan Improvements - -For each issue identified, determine the appropriate fix: - -| Issue Type | Solution Location | -|------------|-------------------| -| Process inefficiency | Update step instructions with clearer guidance | -| Output quality | Update quality criteria or add examples | -| Missing information | Add to step inputs or instructions | -| Tool problems | Suggest different tools in instructions | -| Unclear criteria | Rewrite quality criteria to be specific | - -**Prioritize improvements** that will have the most impact on future runs. Focus on: -- Issues that caused multiple iterations -- Problems that affected the final output quality -- Confusion that could be eliminated with clearer instructions - -### Step 3: Update Step Instructions - -For each step that needs improvement: - -1. **Read the current instruction file** at `.deepwork/jobs/[job_name]/steps/[step_id].md` - -2. **Make targeted improvements**: - - Add missing context or clarification - - Include examples of good output (use what worked in the test) - - Clarify ambiguous instructions - - Add tool recommendations if a different approach would be better - - Update quality criteria to match user expectations - -3. **Keep instructions concise**: - - Avoid redundancy - - Be direct and actionable - - Use bullet points where appropriate - -### Step 4: Update Reviews - -Review and update quality reviews in two places: - -1. **In step instruction files** - The "Quality Criteria" section should reflect what the user actually cared about during testing - -2. **In job.yml** - Update the `reviews` array on each step to: - - Remove criteria that weren't relevant - - Add criteria based on user feedback - - Make existing criteria more specific - - Adjust `run_each` targeting if outputs should be reviewed differently - -**Example improvement:** -```yaml -# Before -reviews: - - run_each: step - quality_criteria: - "Formatted Correctly": "Is the report formatted correctly?" - -# After -reviews: - - run_each: report.md - quality_criteria: - "Distinct Colors": "Does the report use distinct colors for each data series in charts?" - "Readable Tables": "Do tables have sufficient padding and font size for readability?" - "Clear Summary": "Is the executive summary understandable by non-technical readers?" -``` - -### Step 5: Consider Alternative Tools - -If any tools didn't work well during the test: - -1. **Identify the problem** - What went wrong? (slow, wrong output, hard to use) - -2. **Research alternatives** - What other tools could accomplish the same goal? - -3. **Update instructions** - If a better tool exists, update the step instructions to recommend it - -Examples: -- If web scraping was unreliable, suggest a specific browser automation approach -- If data processing was slow, suggest a different method or tool -- If file generation had issues, recommend a different library or format - -### Step 6: Update Job Version and Changelog - -After making improvements: - -1. **Bump the version** in `job.yml`: - - Patch version (x.x.1) for minor instruction tweaks - - Minor version (x.1.0) for quality criteria changes or significant improvements - -2. **Add a changelog entry** describing what was improved: - ```yaml - changelog: - - version: "1.0.1" - changes: "Improved [step] instructions based on test run: added examples, clarified criteria, updated tool recommendations" - ``` - -### Step 7: Provide Recap - -Summarize the improvements made: - -1. **List the issues identified** from the test run - -2. **Describe the changes made** to address each issue - -3. **Explain the expected impact** on future runs - -Example recap format: -``` -## Iteration Summary - -### Issues Identified -1. Chart colors were hard to distinguish -2. Tables were too small to read -3. Executive summary was too technical - -### Changes Made - -**gather_data step:** -- Added instruction to use distinct color palettes for charts -- Updated quality criteria to require readable table formatting - -**generate_report step:** -- Added example of good executive summary -- Updated quality criteria: "Summary understandable by non-technical stakeholders" - -**job.yml:** -- Updated version to 1.0.1 -- Added changelog entry - -### Expected Impact -Future runs should produce reports with better visual design and clearer summaries, reducing the need for post-generation corrections. -``` - -## Example Dialog - -``` -Claude: Let me review our test run and improve the workflow based on what happened. - -**Analyzing Test Conversation...** - -I identified the following issues from the test run: - -### Issues Found - -1. **Chart readability (gather_data step)**: The instructions didn't specify how to handle color choices for visualizations. During the test, we had to fix colors that were too similar. - -2. **Missing month-over-month comparison (analyze_trends step)**: The user wanted comparisons to previous periods, but this wasn't in the instructions. We had to add it after the fact. - -3. **Technical executive summary (generate_report step)**: The summary was too technical for non-technical stakeholders. The quality criteria didn't specify the audience clearly. - -4. **Table formatting (generate_report step)**: Tables were hard to read. No guidance on sizing or padding. - -### Changes Made - -**`.deepwork/jobs/monthly_report/steps/gather_data.md`:** -- Added: "Use distinct, high-contrast colors for chart data series. Avoid similar shades for different categories." -- Added to Quality Criteria: "Charts use visually distinct colors that are accessible to colorblind readers" - -**`.deepwork/jobs/monthly_report/steps/analyze_trends.md`:** -- Added: "Always include comparison to the same period in the previous month/quarter" -- Added input: "previous_period_data" to formalize this requirement - -**`.deepwork/jobs/monthly_report/steps/generate_report.md`:** -- Added example of good executive summary targeting non-technical readers -- Added: "Format tables with sufficient padding (at least 8px) and readable font size (minimum 11pt)" -- Updated Quality Criteria: - - "Executive summary is understandable by non-technical stakeholders" - - "Tables are readable with adequate padding and font size" - -**`.deepwork/jobs/monthly_report/job.yml`:** -- Version bumped to 1.0.1 -- Added changelog: "Improved visual design guidance and audience-appropriate writing based on test feedback" - -Done! The workflow has been updated. Changes are immediately available through the MCP server. - -### Expected Impact - -Future monthly reports should: -- Have better chart color choices from the start -- Include month-over-month comparisons automatically -- Have clearer executive summaries for leadership -- Have more readable tables - -This should significantly reduce the number of corrections needed after the initial output. -``` - -## Important Guidelines - -1. **Be specific** - Don't just note "instructions were unclear" - explain exactly what was unclear and how you fixed it -2. **Use test results as examples** - If something worked well in the test, add it as an example in the instructions -3. **Don't over-engineer** - Only add improvements that address actual problems from the test -4. **Maintain consistency** - Keep the same structure and style in instruction files -5. **Test-driven improvement** - Every change should trace back to something that happened in the test diff --git a/.deepwork/jobs/deepwork_jobs/steps/learn.md b/.deepwork/jobs/deepwork_jobs/steps/learn.md deleted file mode 100644 index 254a332d..00000000 --- a/.deepwork/jobs/deepwork_jobs/steps/learn.md +++ /dev/null @@ -1,266 +0,0 @@ -# Learn from Job Execution - -## Objective - -Think deeply about this task. Reflect on the current conversation to identify learnings from DeepWork job executions, improve job instructions with generalizable insights, and capture bespoke (run-specific) learnings in AGENTS.md files in the deepest common folder that would contain all work on the topic in the future. - -## Task - -Analyze the conversation history to extract learnings and improvements, then apply them appropriately: -- **Generalizable learnings** → Update job instruction files -- **Bespoke learnings** (specific to this run) → Add to AGENTS.md in the deepest common folder for the topic - -### Step 1: Analyze Conversation for Job Executions - -1. **Scan the conversation** for DeepWork slash commands that were run - - Look for patterns like `/job_name.step_id` - - Identify which jobs and steps were executed - - Note the order of execution - -2. **Identify the 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: - - "Which DeepWork job would you like me to learn from?" - - List available jobs from `.deepwork/jobs/` - -### Step 2: Identify Points of Confusion and Inefficiency - -Review the conversation for: - -1. **Confusion signals** - - Questions the agent asked that shouldn't have been necessary - - Misunderstandings about what a step required - - Incorrect outputs that needed correction - - Ambiguous instructions that led to wrong interpretations - -2. **Inefficiency signals** - - Extra steps or iterations that were needed - - Information that had to be repeated - - Context that was missing from instructions - - Dependencies that weren't clear - -3. **Error patterns** - - Failed validations and why they failed - - Quality criteria that were misunderstood - - Edge cases that weren't handled - -4. **Success patterns** - - What worked particularly well - - Efficient approaches worth preserving - - Good examples that could be added to instructions - -### Step 3: Classify Learnings - -For each learning identified, determine if it is: - -**Generalizable** (should improve instructions): -- Would help ANY future run of this job -- Addresses unclear or missing guidance -- Fixes incorrect assumptions in instructions -- Adds helpful examples or context -- Examples: - - "Step instructions should mention that X format is required" - - "Quality criteria should include checking for Y" - - "Add example of correct output format" - -**Bespoke** (should go in AGENTS.md): -- Specific to THIS project/codebase/run -- Depends on local conventions or structure -- References specific files or paths -- Would not apply to other uses of this job -- Examples: - - "In this codebase, API endpoints are in `src/api/`" - - "This project uses camelCase for function names" - - "The main config file is at `config/settings.yml`" - -### Step 4: Update Job Instructions (Generalizable Learnings) - -For each generalizable learning: - -1. **Locate the instruction file** - - Path: `.deepwork/jobs/[job_name]/steps/[step_id].md` - -2. **Make targeted improvements** - - Add missing context or clarification - - Include helpful examples - - Clarify ambiguous instructions - - Update quality criteria if needed - - If you identify problems in the outcomes of steps, those usually should be reflected in an update to the `reviews` for that step in `job.yml` (adjusting criteria names, questions, or `run_each` targeting) - -3. **Keep instructions concise** - - Avoid redundancy - don't repeat the same guidance in multiple places - - Be direct - remove verbose explanations that don't add value - - Prefer bullet points over paragraphs where appropriate - -4. **Preserve instruction structure** - - Keep existing sections (Objective, Task, Process, Output Format, Quality Criteria) - - Add to appropriate sections rather than restructuring - - Maintain consistency with other steps - -5. **Track changes for changelog** - - Note what was changed and why - - Prepare changelog entry for job.yml - -### Step 4b: Extract Shared Content into Referenced Files - -Review all instruction files for the job and identify content that: -- Appears in multiple step instructions (duplicated) -- Is lengthy and could be extracted for clarity -- Would benefit from being maintained in one place - -**Extract to shared files:** - -1. **Create shared files** in `.deepwork/jobs/[job_name]/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 - -2. **Reference from instructions** using markdown includes or explicit references: - ```markdown - ## Conventions - - Follow the conventions defined in `shared/conventions.md`. - ``` - -3. **Benefits of extraction:** - - Single source of truth - update once, applies everywhere - - Shorter instruction files - easier to read and maintain - - Consistent guidance across steps - -### Step 5: Create/Update AGENTS.md (Bespoke Learnings) - -The AGENTS.md file captures project-specific knowledge that helps future agent runs. - -1. **Determine the correct location** - - Place AGENTS.md in the deepest common folder that would contain all work on the topic in the future - - This ensures the knowledge is available when working in that context - - If uncertain, place at the project root - -2. **Use file references where possible** - - Instead of duplicating information, reference source files - - This keeps AGENTS.md in sync as the codebase evolves - - Pattern: "See `path/to/file.ext` for [description]" - -3. **AGENTS.md structure**: See `.deepwork/jobs/deepwork_jobs/templates/agents.md.template` for the standard format. - -4. **Writing entries** - - Be concise but specific - - Always prefer file references over inline content - - Use line numbers when referencing specific code: `file.ext:42` - - Group related learnings together - -### Step 6: Update Job Version and Changelog - -If instruction files were modified: - -1. **Bump version in job.yml** - - Patch version (0.0.x) for instruction improvements - - Minor version (0.x.0) if quality criteria changed - -2. **Add changelog entry** - ```yaml - - version: "[new_version]" - changes: "Improved [step] instructions based on execution learnings: [brief description]" - ``` - -## File Reference Patterns - -When adding entries to AGENTS.md, prefer these patterns: - -**Good (references)**: -```markdown -- API endpoints follow REST conventions. See `src/api/routes.ts` for examples. -- Error handling pattern: See `src/utils/errors.ts:15-30` -- Configuration schema: Defined in `config/schema.json` -``` - -**Avoid (duplicating)**: -```markdown -- API endpoints should return JSON with this format: { status: ..., data: ... } -- Error handling should use try/catch with custom error classes -- Configuration requires these fields: name, version, ... -``` - -## Example Dialog - -``` -User: [Invokes the learn workflow via MCP] - -Claude: I'll analyze this conversation for learnings from DeepWork job executions. - -**Conversation Analysis** - -I found the following job executions: -1. `/competitive_research.identify_competitors` - Completed -2. `/competitive_research.research_competitors` - Completed with 2 iterations -3. `/competitive_research.comparative_analysis` - Completed - -**Identified Issues** - -1. **Confusion in step 2**: The instructions didn't specify that competitor research should include pricing information. This caused an extra iteration. - -2. **Missing context**: The agent had to ask about the industry focus, which should have been carried forward from step 1. - -**Classification** - -- Generalizable: Add pricing to research requirements in instructions -- Bespoke: This project focuses on B2B SaaS in the HR tech space - -**Actions Taken** - -1. Updated `.deepwork/jobs/competitive_research/steps/research_competitors.md`: - - Added "Include pricing information (tiers, models, approximate ranges)" to research requirements - - Added note about carrying forward industry context from previous step - -2. Created `./competitive_research_output/AGENTS.md`: - ```markdown - # Project Context for Competitive Research - - ## Job-Specific Context - - ### competitive_research - - #### Industry Focus - - Domain: B2B SaaS, HR Technology sector - - See `identify_competitors_output.md` for market definition - - #### Competitors Identified - - Reference: `competitor_list.md` for full details - - ## Last Updated - - Date: 2024-01-15 - - From conversation about: Initial competitive analysis run - ``` - -3. Updated job.yml version to 1.0.1 with changelog entry - -**Summary** - -Updated job instructions and created AGENTS.md with bespoke learnings. -``` - -## Handling Edge Cases - -**No job executions found**: -- Ask user which job they'd like to analyze -- Or offer to review available jobs - -**Multiple jobs executed**: -- Analyze each job separately -- Create separate AGENTS.md entries or files as appropriate - -**AGENTS.md already exists**: -- Read existing content -- Append new learnings to appropriate sections -- Update "Last Updated" section - -**No issues found**: -- Document what worked well -- Consider if any successful patterns should be added to instructions as examples - -**Sensitive information**: -- Never include secrets, credentials, or PII in AGENTS.md -- Reference config files instead of including values diff --git a/.deepwork/jobs/deepwork_jobs/steps/supplemental_file_references.md b/.deepwork/jobs/deepwork_jobs/steps/supplemental_file_references.md deleted file mode 100644 index 81b6494a..00000000 --- a/.deepwork/jobs/deepwork_jobs/steps/supplemental_file_references.md +++ /dev/null @@ -1,40 +0,0 @@ -# Supplementary Reference Files - -Step instructions can include additional `.md` files in the `steps/` directory. These supplementary files are useful for: - -- Providing detailed examples or templates that would clutter the main instruction file -- Sharing common reference material across multiple steps -- Including technical specifications, API documentation, or style guides - -## How to Use - -1. Place additional `.md` files in the `steps/` directory alongside the main step instruction files -2. Reference them in your step instructions using the **full path from the project root** - -## Example - -If you have a job called `my_job` and want to include an API specification template: - -1. Create the file at `.deepwork/jobs/my_job/steps/api_spec.md` -2. Reference it in your step instructions like this: - -```markdown -Use the template in `.deepwork/jobs/my_job/steps/api_spec.md` to structure your API endpoints. -``` - -## Path Format - -Always use the full relative path from the project root: - -``` -.deepwork/jobs/[job_name]/steps/[filename].md -``` - -For example: -- `.deepwork/jobs/competitive_research/steps/competitor_template.md` -- `.deepwork/jobs/api_design/steps/endpoint_schema.md` -- `.deepwork/jobs/onboarding/steps/checklist_template.md` - -## Benefits - -Using supplementary files keeps your main step instructions focused and readable while allowing you to provide detailed reference material when needed. The AI agent can read these files during execution to get additional context. diff --git a/.deepwork/jobs/deepwork_jobs/steps/test.md b/.deepwork/jobs/deepwork_jobs/steps/test.md deleted file mode 100644 index 36d27128..00000000 --- a/.deepwork/jobs/deepwork_jobs/steps/test.md +++ /dev/null @@ -1,154 +0,0 @@ -# Test the New Workflow - -## Objective - -Run the newly created workflow on a real use case chosen by the user, critique the output, and iterate until the user is satisfied with the results. This step validates that the workflow works as intended before finalizing it. - -## Task - -Guide the user through testing their new workflow by running it on a real example, then critically evaluating the output and refining it based on user feedback. - -### Step 1: Announce Readiness and Gather Test Case - -The workflow is now implemented and ready to test. Use the AskUserQuestion tool to: - -1. **Inform the user** that the workflow is ready for a test run -2. **Ask what they'd like to test it on** - Get a specific, real use case - -Example question to ask: -``` -Your new workflow is ready to try out! What would you like to use it on for the first test run? - -Please describe a specific case you want to run through the workflow - ideally something you actually need done, so we can validate the workflow produces useful results. -``` - -**Important**: Get a concrete, specific test case. Vague responses like "just test it" should be followed up with clarifying questions to understand what inputs/context the workflow needs. - -### Step 2: Prepare and Run the Workflow - -1. **Prepare clean context** - Before invoking the workflow, consider compacting the conversation history (e.g., using `/compact` in Claude Code) to ensure the workflow starts with clean context focused on the test case. - -2. **Start the new workflow** - Use `start_workflow` through the DeepWork MCP server with the job name and workflow name to begin executing the workflow. - -3. **Complete the full workflow** - Continue through all steps of the workflow until it produces its final output. Use `finished_step` to progress through each step. - -4. **Note any issues during execution** - Pay attention to: - - Confusion or ambiguity in instructions - - Missing information that had to be asked for - - Steps that took longer than expected - - Awkward tool usage or process flow - -### Step 3: Critique the Output - -After the workflow completes, perform a self-critique of the output: - -1. **Review the final deliverable** - Read through all outputs produced by the workflow - -2. **Identify up to 3 top issues** - Look for problems such as: - - Missing information or sections - - Formatting issues (layout, structure, readability) - - Quality problems (vague content, errors, inconsistencies) - - Misalignment with what the user likely wanted - - Technical issues (broken links, malformed data, etc.) - -3. **Present each issue to the user** with a specific question asking if they want it fixed. For example: - ``` - I noticed a few things we could improve: - - 1. **Text overlap**: The PDF has some text overlapping images in a few places - shall I correct that? - - 2. **Missing summary**: The report doesn't have an executive summary at the top - would you like me to add one? - - 3. **Data formatting**: The numbers aren't consistently formatted (some have commas, some don't) - should I standardize them? - ``` - -4. **Make corrections** for any issues the user confirms they want fixed - -### Step 4: Gather Additional Feedback - -After addressing the identified issues: - -1. **Ask if the user has more comments** on the output: - ``` - I've made those corrections. Is there anything else you'd like me to change about the output? - ``` - -2. **Iterate on feedback** - Keep making corrections based on user feedback until they indicate they're satisfied - -3. **Confirm completion** - When the user says the output is good, confirm that testing is complete - -### Loop Behavior - -The feedback loop should continue until the user explicitly indicates satisfaction. Look for signals like: -- "Looks good" -- "That's fine" -- "I'm happy with it" -- "No more changes" -- "Perfect" - -If the user provides more feedback, address it and ask again. Don't assume satisfaction without explicit confirmation. - -## Example Dialog - -``` -Claude: Your new workflow is ready to try out! - -The `monthly_report` workflow has been implemented with these steps: -1. gather_data - Collects metrics from various sources -2. analyze_trends - Identifies patterns and insights -3. generate_report - Creates the final PDF report - -What would you like to use it on for the first test run? Please describe a specific report you need - for example, which month's data and any particular focus areas. - -User: Let's do the January 2026 engineering report, focusing on deployment frequency and incident response times. - -Claude: Great, let me run the workflow on your January 2026 engineering report. - -[Starting the monthly_report workflow via MCP...] - -[... workflow runs through all steps ...] - -Claude: The January 2026 Engineering Report has been generated. Let me review it for any issues. - -I noticed a few things we could improve: - -1. **Chart readability**: The deployment frequency chart uses very similar colors for different teams - shall I change to a more distinct color palette? - -2. **Missing context**: The incident response times don't include comparison to the previous month - would you like me to add month-over-month comparison? - -3. **Executive summary**: The summary is quite technical - should I add a simpler high-level overview for non-technical stakeholders? - -User: Yes to all three, please. - -Claude: Done! I've updated the report with: -- Distinct color palette for the deployment chart -- Month-over-month comparison for incident response times -- Added a non-technical executive summary - -Is there anything else you'd like me to change about the report? - -User: Can you make the tables larger? They're a bit hard to read. - -Claude: I've increased the table sizes for better readability. The font is now larger and there's more padding around cells. - -Is there anything else you'd like me to adjust? - -User: No, that looks great! - -Claude: Excellent! The test run is complete. The workflow successfully generated your January 2026 Engineering Report with all the refinements applied. - -**Test Summary:** -- Workflow ran successfully through all 3 steps -- Output required adjustments to chart colors, comparisons, and table sizing -- User is satisfied with the final result - -Ready to proceed to the iterate step to improve the workflow based on what we learned. -``` - -## Important Guidelines - -1. **Use real test cases** - Testing with actual data/needs validates the workflow better than hypothetical examples -2. **Be specific in critiques** - Don't say "formatting issues" - say exactly what's wrong and where -3. **Limit initial critique to 3 issues** - Too many issues at once is overwhelming; address more in the feedback loop -4. **Don't assume what user wants fixed** - Always ask before making corrections -5. **Iterate until satisfied** - Don't rush to completion; the user's satisfaction is the goal diff --git a/.deepwork/jobs/deepwork_jobs/templates/agents.md.template b/.deepwork/jobs/deepwork_jobs/templates/agents.md.template deleted file mode 100644 index c160921d..00000000 --- a/.deepwork/jobs/deepwork_jobs/templates/agents.md.template +++ /dev/null @@ -1,32 +0,0 @@ -# Project Context for [Job Name] - -## Codebase Structure - - -- Project structure: See `README.md` for overview -- API documentation: See `docs/api.md` -- Configuration: See `config/README.md` - -## Conventions - -### Naming Conventions -- [Convention]: See example in `path/to/example.ext:LINE` - -### File Organization -- [Pattern]: Reference `path/to/pattern/` - -## Job-Specific Context - -### [Job Name] - -#### [Step Name] -- [Learning]: Reference `relevant/file.ext` -- [Context]: [Brief explanation with file reference] - -## Known Issues and Workarounds - -- [Issue]: [Workaround with file reference if applicable] - -## Last Updated -- Date: [YYYY-MM-DD] -- From conversation about: [Brief description] diff --git a/.deepwork/jobs/deepwork_jobs/templates/job.yml.example b/.deepwork/jobs/deepwork_jobs/templates/job.yml.example deleted file mode 100644 index dac1aba8..00000000 --- a/.deepwork/jobs/deepwork_jobs/templates/job.yml.example +++ /dev/null @@ -1,100 +0,0 @@ -# Example: Competitive Research Job -# -# This is a complete example of a job.yml file for reference. - -name: competitive_research -version: "1.0.0" -summary: "Systematic competitive analysis workflow" -description: | - A comprehensive workflow for analyzing competitors in your market segment. - Helps product teams understand the competitive landscape through systematic - identification, research, comparison, and positioning recommendations. - -changelog: - - version: "1.0.0" - changes: "Initial job creation" - -workflows: - - name: full_analysis - summary: "Complete competitive research from identification to positioning" - steps: - - identify_competitors - - research_competitors - - comparative_analysis - - positioning_recommendations - -steps: - - id: identify_competitors - name: "Identify Competitors" - description: "Identify 5-7 key competitors in the target market" - instructions_file: steps/identify_competitors.md - inputs: - - name: market_segment - description: "The market segment to analyze" - - name: product_category - description: "The product category" - outputs: - competitors_list.md: - type: file - description: "Vetted list of direct and indirect competitors" - required: true - dependencies: [] - reviews: [] - - - id: research_competitors - name: "Research Competitors" - description: "Deep dive research on each identified competitor" - instructions_file: steps/research_competitors.md - inputs: - - file: competitors_list.md - from_step: identify_competitors - outputs: - research_notes.md: - type: file - description: "Detailed research notes on each competitor" - required: true - dependencies: - - identify_competitors - reviews: - - run_each: research_notes.md - quality_criteria: - "Sufficient Data": "Does each competitor have at least 3 data points?" - "Sources Cited": "Are sources cited for key claims?" - "Current Information": "Is the information current (within last year)?" - - - id: comparative_analysis - name: "Comparative Analysis" - description: "Create side-by-side comparison matrix" - instructions_file: steps/comparative_analysis.md - inputs: - - file: research_notes.md - from_step: research_competitors - outputs: - comparison_matrix.md: - type: file - description: "Side-by-side comparison matrix of all competitors" - required: true - dependencies: - - research_competitors - reviews: [] - - - id: positioning_recommendations - name: "Positioning Recommendations" - description: "Strategic positioning recommendations based on analysis" - instructions_file: steps/positioning_recommendations.md - inputs: - - file: comparison_matrix.md - from_step: comparative_analysis - outputs: - positioning_report.md: - type: file - description: "Strategic positioning recommendations" - required: true - dependencies: - - comparative_analysis - reviews: - - run_each: positioning_report.md - additional_review_guidance: "Read the comparison_matrix.md file to verify that recommendations are grounded in the competitive analysis data." - quality_criteria: - "Actionable": "Are recommendations specific and actionable?" - "Data-Backed": "Are recommendations supported by the competitive analysis data?" diff --git a/.deepwork/jobs/deepwork_jobs/templates/job.yml.template b/.deepwork/jobs/deepwork_jobs/templates/job.yml.template deleted file mode 100644 index f0f87bfb..00000000 --- a/.deepwork/jobs/deepwork_jobs/templates/job.yml.template +++ /dev/null @@ -1,71 +0,0 @@ -# DeepWork Job Specification Template -# -# This template shows the structure of a job.yml file. -# Replace placeholders in [brackets] with actual values. - -name: [job_name] -version: "1.0.0" -summary: "[Brief one-line summary of what this job accomplishes - max 200 chars]" -description: | - [Detailed multi-line description of the job's purpose, process, and goals. - - This should explain: - - What problem this workflow solves - - What the overall process looks like - - What the end result will be - - Who the intended users are - - Any important context about the workflow] - -changelog: - - version: "1.0.0" - changes: "Initial job creation" - -workflows: - - name: [workflow_name] - summary: "[What this workflow accomplishes]" - steps: - - [step_id] - - [another_step] - -steps: - - id: [step_id] - name: "[Step Name]" - description: "[What this step does]" - instructions_file: steps/[step_id].md - inputs: - - name: [param_name] - description: "[What user needs to provide]" - # OR for file inputs from previous steps: - # - file: [filename_or_path] - # from_step: [previous_step_id] - outputs: - [output_name]: - type: file - description: "[What this output contains]" - required: true - dependencies: [] # List of step IDs that must complete first - reviews: - - run_each: step # or a specific output name - # Optional: tell the reviewer what files to read for context - # additional_review_guidance: "Read the [filename] for context on [what]." - quality_criteria: - "[Criterion Name]": "[Question to evaluate]" - "[Another Criterion]": "[Another question]" - # Optional: Delegate to a specific agent type (uses context: fork) - # agent: general-purpose # or other agent type - - - id: [another_step] - name: "[Another Step]" - description: "[What this step does]" - instructions_file: steps/[another_step].md - inputs: - - file: [output_name] - from_step: [step_id] - outputs: - [another_output]: - type: file - description: "[What this output contains]" - required: true - dependencies: - - [step_id] # This step requires the previous step - reviews: [] # Empty if no quality checks needed diff --git a/.deepwork/jobs/deepwork_jobs/templates/step_instruction.md.example b/.deepwork/jobs/deepwork_jobs/templates/step_instruction.md.example deleted file mode 100644 index 4f53b788..00000000 --- a/.deepwork/jobs/deepwork_jobs/templates/step_instruction.md.example +++ /dev/null @@ -1,82 +0,0 @@ -# Example: Identify Competitors Step Instruction -# -# This is a complete example of a step instruction file for reference. - -# Identify Competitors - -## Objective - -Identify 5-7 key competitors in the target market segment to analyze for competitive positioning. - -## Task - -Research and identify the most relevant competitors in the specified market segment and product category. Focus on companies that directly compete for the same customer base and solve similar problems. - -### Process - -1. **Understand the market context** - - Review the market segment provided by the user - - Understand the product category boundaries - - Consider direct and indirect competitors - -2. **Research competitors** - - Search for companies in this space - - Look for market leaders and emerging players - - Consider different competitive dimensions (features, price, target market) - -3. **Select 5-7 key competitors** - - Prioritize direct competitors - - Include at least one market leader - - Include 1-2 emerging/innovative players - - Ensure diversity in the competitive set - -4. **Document each competitor** - - Company name - - Brief description (2-3 sentences) - - Why they're a relevant competitor - - Primary competitive dimension - -## Output Format - -### competitors_list.md - -A markdown document listing each competitor with context. - -**Structure**: -```markdown -# Competitor Analysis: [Market Segment] - -## Market Context -- **Segment**: [market segment] -- **Category**: [product category] -- **Analysis Date**: [current date] - -## Identified Competitors - -### 1. [Competitor Name] -**Description**: [2-3 sentence description of what they do] - -**Why Relevant**: [Why they're a key competitor in this space] - -**Competitive Dimension**: [What they compete on - e.g., price, features, market segment] - -[Repeat for each competitor, 5-7 total] - -## Selection Rationale - -[Brief paragraph explaining why these specific competitors were chosen and what dimensions of competition they represent] -``` - -## Quality Criteria - -- 5-7 competitors identified (not too few, not too many) -- Mix of established and emerging players -- All competitors are genuinely relevant to the market segment -- Each competitor has clear, specific description -- Selection rationale explains the competitive landscape -- Output is well-formatted and ready for use by next step -- When all criteria are met, include `✓ Quality Criteria Met` in your response - -## Context - -This is the foundation step for competitive analysis. The competitors identified here will be deeply researched in subsequent steps, so it's important to choose the right set. Focus on competitors that will provide strategic insights for positioning decisions. diff --git a/.deepwork/jobs/deepwork_jobs/templates/step_instruction.md.template b/.deepwork/jobs/deepwork_jobs/templates/step_instruction.md.template deleted file mode 100644 index ddd19213..00000000 --- a/.deepwork/jobs/deepwork_jobs/templates/step_instruction.md.template +++ /dev/null @@ -1,58 +0,0 @@ -# [Step Name] - -## Objective - -[Clear statement of what this step accomplishes, derived from the step's description] - -## Task - -[Detailed instructions for completing this step, based on: -- The step's purpose -- Expected inputs and outputs -- The job's overall context -] - -### Process - -[Break down the step into substeps. Use the information gathered during define about: -- What needs to be done -- What makes a good output -- Any quality criteria -] - -1. [Substep 1] -2. [Substep 2] -3. [Substep 3] - -[If this step has user inputs, explain how to gather them] -[If this step has file inputs, explain how to use them] - -## Output Format - -### [output_filename_1] - -[Description of what should be in this output file] - -**Structure**: -```[file format] -[Example or template of what the output should look like] -``` - -[Repeat for each output file] - -## Quality Criteria - -[List what makes this step's output high quality: -- Completeness checks -- Format requirements -- Content requirements -] - -- [Quality criterion 1] -- [Quality criterion 2] -- [Quality criterion 3] -- When all criteria are met, include `✓ Quality Criteria Met` in your response - -## Context - -[Provide context from the job's overall description to help understand why this step matters and how it fits into the bigger picture] diff --git a/doc/mcp_interface.md b/doc/mcp_interface.md index 2cc5014b..ec8c843a 100644 --- a/doc/mcp_interface.md +++ b/doc/mcp_interface.md @@ -152,6 +152,7 @@ interface ActiveStepInfo { session_id: string; // Unique session identifier branch_name: string; // Git branch for this workflow instance step_id: string; // ID of the current step + job_dir: string; // Absolute path to job directory (templates, scripts, etc.) step_expected_outputs: ExpectedOutput[]; // Expected outputs with type and format hints step_reviews: ReviewInfo[]; // Reviews to run when step completes step_instructions: string; // Instructions for the step diff --git a/src/deepwork/mcp/schemas.py b/src/deepwork/mcp/schemas.py index fe3746f8..347852b6 100644 --- a/src/deepwork/mcp/schemas.py +++ b/src/deepwork/mcp/schemas.py @@ -207,6 +207,10 @@ class ActiveStepInfo(BaseModel): session_id: str = Field(description="Unique session identifier") branch_name: str = Field(description="Git branch for this workflow instance") step_id: str = Field(description="ID of the current step") + job_dir: str = Field( + description="Absolute path to the job directory. Templates, scripts, " + "and other files referenced in step instructions live here." + ) step_expected_outputs: list[ExpectedOutput] = Field( description="Expected outputs for this step, including type and format hints" ) diff --git a/src/deepwork/mcp/tools.py b/src/deepwork/mcp/tools.py index f89242f7..75075df1 100644 --- a/src/deepwork/mcp/tools.py +++ b/src/deepwork/mcp/tools.py @@ -337,6 +337,7 @@ async def start_workflow(self, input_data: StartWorkflowInput) -> StartWorkflowR session_id=session.session_id, branch_name=session.branch_name, step_id=first_step_id, + job_dir=str(job.job_dir), step_expected_outputs=step_outputs, step_reviews=[ ReviewInfo( @@ -530,6 +531,7 @@ async def finished_step(self, input_data: FinishedStepInput) -> FinishedStepResp session_id=session.session_id, branch_name=session.branch_name, step_id=next_step_id, + job_dir=str(job.job_dir), step_expected_outputs=step_outputs, step_reviews=[ ReviewInfo( diff --git a/src/deepwork/standard_jobs/deepwork_jobs/AGENTS.md b/src/deepwork/standard_jobs/deepwork_jobs/AGENTS.md index 576c1185..abb9fe9f 100644 --- a/src/deepwork/standard_jobs/deepwork_jobs/AGENTS.md +++ b/src/deepwork/standard_jobs/deepwork_jobs/AGENTS.md @@ -5,27 +5,15 @@ This is the source of truth for the `deepwork_jobs` standard job. ## Codebase Structure - Source location: `src/deepwork/standard_jobs/deepwork_jobs/` -- Working copy: `.deepwork/jobs/deepwork_jobs/` -- Templates: `templates/` directory within each location +- Templates: `templates/` directory within the job directory +- Loaded at runtime directly from the package (no copy into `.deepwork/jobs/`) -## Dual Location Maintenance +## Location -**Important**: This job exists in two locations that must be kept in sync: - -1. **Source of truth**: `src/deepwork/standard_jobs/deepwork_jobs/` - - This is where changes should be made first - - Tracked in version control - -2. **Working copy**: `.deepwork/jobs/deepwork_jobs/` - - Must be updated after changes to source - - Used by the MCP server at runtime - -After making changes to the source, run `deepwork install` or manually copy: -```bash -cp src/deepwork/standard_jobs/deepwork_jobs/job.yml .deepwork/jobs/deepwork_jobs/ -cp src/deepwork/standard_jobs/deepwork_jobs/steps/*.md .deepwork/jobs/deepwork_jobs/steps/ -cp -r src/deepwork/standard_jobs/deepwork_jobs/templates/* .deepwork/jobs/deepwork_jobs/templates/ -``` +This job lives in the DeepWork package source at `src/deepwork/standard_jobs/deepwork_jobs/`. +It is loaded directly at runtime by the multi-folder job discovery system — there is no +separate "working copy" in `.deepwork/jobs/`. The MCP server returns the job directory path +as `job_dir` in workflow responses so agents can find templates and scripts. ## File Organization diff --git a/src/deepwork/standard_jobs/deepwork_jobs/job.yml b/src/deepwork/standard_jobs/deepwork_jobs/job.yml index 57baf9f1..ec8b9e61 100644 --- a/src/deepwork/standard_jobs/deepwork_jobs/job.yml +++ b/src/deepwork/standard_jobs/deepwork_jobs/job.yml @@ -222,7 +222,7 @@ steps: quality_criteria: "DeepWork Skills Removed": "Are `Skill(...)` entries matching jobs in `.deepwork/jobs/` removed?" "Non-DeepWork Skills Preserved": "Are skills NOT matching DeepWork jobs left intact?" - "make_new_job.sh Preserved": "Is the `Bash(...)` permission for `make_new_job.sh` preserved (if present)?" + "Stale make_new_job.sh Removed": "Are stale `Bash(...)` permissions referencing `.deepwork/jobs/deepwork_jobs/make_new_job.sh` removed?" "Rules Hooks Removed": "Are all DeepWork Rules hooks and permissions removed?" "Duplicate Hooks Removed": "Are duplicate hook entries consolidated or removed?" "Hardcoded Paths Removed": "Are user-specific hardcoded paths (like `/Users/*/...`) removed?" diff --git a/src/deepwork/standard_jobs/deepwork_jobs/steps/define.md b/src/deepwork/standard_jobs/deepwork_jobs/steps/define.md index 78ac1223..361c9f0f 100644 --- a/src/deepwork/standard_jobs/deepwork_jobs/steps/define.md +++ b/src/deepwork/standard_jobs/deepwork_jobs/steps/define.md @@ -270,19 +270,19 @@ reviews: [] Only after you have complete understanding, create the job directory and `job.yml` file: -**First, create the directory structure** using the `make_new_job.sh` script: +**First, create the directory structure** using the `make_new_job.sh` script located in this job's directory (the `job_dir` path from the workflow response): ```bash -.deepwork/jobs/deepwork_jobs/make_new_job.sh [job_name] +/make_new_job.sh [job_name] ``` **Then create the job.yml file** at `.deepwork/jobs/[job_name]/job.yml` -(Where `[job_name]` is the name of the NEW job you're creating, e.g., `competitive_research`) +(Where `[job_name]` is the name of the NEW job you're creating, e.g., `competitive_research`. Replace `` with the actual `job_dir` path from the workflow response.) -**Template reference**: See `.deepwork/jobs/deepwork_jobs/templates/job.yml.template` for the standard structure. +**Template reference**: See `/templates/job.yml.template` for the standard structure. -**Complete example**: See `.deepwork/jobs/deepwork_jobs/templates/job.yml.example` for a fully worked example. +**Complete example**: See `/templates/job.yml.example` for a fully worked example. **Important**: - Use lowercase with underscores for job name and step IDs diff --git a/src/deepwork/standard_jobs/deepwork_jobs/steps/fix_settings.md b/src/deepwork/standard_jobs/deepwork_jobs/steps/fix_settings.md index d164b69e..770d638f 100644 --- a/src/deepwork/standard_jobs/deepwork_jobs/steps/fix_settings.md +++ b/src/deepwork/standard_jobs/deepwork_jobs/steps/fix_settings.md @@ -172,6 +172,6 @@ If there are syntax errors, fix them before proceeding. ## Important Notes 1. **Don't remove non-DeepWork permissions** - Keep permissions like `WebSearch`, `Read(...)`, `Bash(...)` that aren't related to old DeepWork skills -2. **Preserve `make_new_job.sh`** - Keep any `Bash(...)` permission referencing `make_new_job.sh` (e.g., `Bash(.deepwork/jobs/deepwork_jobs/scripts/make_new_job.sh *)`) - this is a current DeepWork script +2. **Remove stale `make_new_job.sh` permissions** - Remove any `Bash(...)` permission referencing `.deepwork/jobs/deepwork_jobs/make_new_job.sh` — this script now lives in the package and is accessed via the `job_dir` path 3. **Be conservative** - If unsure whether something is legacy, ask the user 4. **Document changes** - Note what was removed for the final summary diff --git a/src/deepwork/standard_jobs/deepwork_jobs/steps/implement.md b/src/deepwork/standard_jobs/deepwork_jobs/steps/implement.md index 73eeb365..f87d8365 100644 --- a/src/deepwork/standard_jobs/deepwork_jobs/steps/implement.md +++ b/src/deepwork/standard_jobs/deepwork_jobs/steps/implement.md @@ -29,11 +29,11 @@ Read the `job.yml` specification file created by the define step and generate co For each step in the job.yml, create a comprehensive instruction file at `.deepwork/jobs/[job_name]/steps/[step_id].md`. -**Template reference**: See `.deepwork/jobs/deepwork_jobs/templates/step_instruction.md.template` for the standard structure. +**Template reference**: See `/templates/step_instruction.md.template` for the standard structure. -**Complete example**: See `.deepwork/jobs/deepwork_jobs/templates/step_instruction.md.example` for a fully worked example. +**Complete example**: See `/templates/step_instruction.md.example` for a fully worked example. -**Available templates in `.deepwork/jobs/deepwork_jobs/templates/`:** +**Available templates in `/templates/`** (replace `` with the `job_dir` path from the workflow response): - `job.yml.template` - Job specification structure - `step_instruction.md.template` - Step instruction file structure - `agents.md.template` - AGENTS.md file structure @@ -86,7 +86,7 @@ This alignment ensures the AI agent knows exactly what will be validated and can Step instructions can include additional `.md` files in the `steps/` directory for detailed examples, templates, or reference material. Reference them using the full path from the project root. -See `.deepwork/jobs/deepwork_jobs/steps/supplemental_file_references.md` for detailed documentation and examples. +See `/steps/supplemental_file_references.md` for detailed documentation and examples. ### Step 3: Verify Files @@ -97,8 +97,8 @@ Verify that all files are in their correct locations: ## Example Implementation For a complete worked example showing a job.yml and corresponding step instruction file, see: -- **Job specification**: `.deepwork/jobs/deepwork_jobs/templates/job.yml.example` -- **Step instruction**: `.deepwork/jobs/deepwork_jobs/templates/step_instruction.md.example` +- **Job specification**: `/templates/job.yml.example` +- **Step instruction**: `/templates/step_instruction.md.example` ## Important Guidelines diff --git a/src/deepwork/standard_jobs/deepwork_jobs/steps/learn.md b/src/deepwork/standard_jobs/deepwork_jobs/steps/learn.md index 254a332d..dc546110 100644 --- a/src/deepwork/standard_jobs/deepwork_jobs/steps/learn.md +++ b/src/deepwork/standard_jobs/deepwork_jobs/steps/learn.md @@ -144,7 +144,7 @@ The AGENTS.md file captures project-specific knowledge that helps future agent r - This keeps AGENTS.md in sync as the codebase evolves - Pattern: "See `path/to/file.ext` for [description]" -3. **AGENTS.md structure**: See `.deepwork/jobs/deepwork_jobs/templates/agents.md.template` for the standard format. +3. **AGENTS.md structure**: See `/templates/agents.md.template` for the standard format. 4. **Writing entries** - Be concise but specific diff --git a/src/deepwork/templates/claude/settings.json b/src/deepwork/templates/claude/settings.json index a85202f8..0359e5f6 100644 --- a/src/deepwork/templates/claude/settings.json +++ b/src/deepwork/templates/claude/settings.json @@ -5,7 +5,6 @@ "Edit(./.deepwork/**)", "Write(./.deepwork/**)", "Bash(deepwork:*)", - "Bash(./.deepwork/jobs/deepwork_jobs/make_new_job.sh:*)", "WebSearch", "mcp__deepwork__get_workflows", "mcp__deepwork__start_workflow", diff --git a/tests/unit/mcp/test_schemas.py b/tests/unit/mcp/test_schemas.py index 14e0e41a..9b6389dc 100644 --- a/tests/unit/mcp/test_schemas.py +++ b/tests/unit/mcp/test_schemas.py @@ -304,6 +304,7 @@ def test_basic_step_info(self) -> None: session_id="abc123", branch_name="deepwork/test-main-20240101", step_id="step1", + job_dir="/tmp/test_job", step_expected_outputs=expected, step_reviews=[ ReviewInfo( @@ -317,6 +318,7 @@ def test_basic_step_info(self) -> None: assert step_info.session_id == "abc123" assert step_info.branch_name == "deepwork/test-main-20240101" assert step_info.step_id == "step1" + 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" assert step_info.step_expected_outputs[0].type == "file" @@ -331,6 +333,7 @@ def test_default_reviews(self) -> None: session_id="abc123", branch_name="deepwork/test-main-20240101", step_id="step1", + job_dir="/tmp/test_job", step_expected_outputs=[ ExpectedOutput( name="output.md", @@ -356,6 +359,7 @@ def test_basic_response(self) -> None: session_id="abc123", branch_name="deepwork/test-main-20240101", step_id="step1", + job_dir="/tmp/test_job", step_expected_outputs=[ ExpectedOutput( name="output.md", @@ -408,6 +412,7 @@ def test_next_step_status(self) -> None: session_id="abc123", branch_name="deepwork/test-main-20240101", step_id="step2", + job_dir="/tmp/test_job", step_expected_outputs=[ ExpectedOutput( name="output2.md", From b2cf72fb84ec9b0698e68da0a120eb9dadcac64e Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 13 Feb 2026 18:53:14 +0000 Subject: [PATCH 3/7] chore: remove unused _inject_standard_job and _inject_deepwork_jobs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit These functions copied standard jobs into .deepwork/jobs/ during install, which is no longer done — standard jobs are loaded directly from the package at runtime. https://claude.ai/code/session_01KU818enCNqHLbrqtdyCXUV --- src/deepwork/cli/install.py | 66 ------------------------------------- 1 file changed, 66 deletions(-) diff --git a/src/deepwork/cli/install.py b/src/deepwork/cli/install.py index 1dd6a423..ceb2ed7c 100644 --- a/src/deepwork/cli/install.py +++ b/src/deepwork/cli/install.py @@ -54,72 +54,6 @@ def _install_schemas(schemas_dir: Path, project_path: Path) -> None: raise InstallError(f"Failed to install schemas: {e}") from e -def _inject_standard_job(job_name: str, jobs_dir: Path, project_path: Path) -> None: - """ - Inject a standard job definition into the project. - - Args: - job_name: Name of the standard job to inject - jobs_dir: Path to .deepwork/jobs directory - project_path: Path to project root (for relative path display) - - Raises: - InstallError: If injection fails - """ - # Find the standard jobs directory - standard_jobs_dir = Path(__file__).parent.parent / "standard_jobs" / job_name - - if not standard_jobs_dir.exists(): - raise InstallError( - f"Standard job '{job_name}' not found at {standard_jobs_dir}. " - "DeepWork installation may be corrupted." - ) - - # Target directory - target_dir = jobs_dir / job_name - - # Copy the entire directory - try: - if target_dir.exists(): - # Remove existing if present (for reinstall/upgrade) - shutil.rmtree(target_dir) - - shutil.copytree(standard_jobs_dir, target_dir) - # Fix permissions - source may have restrictive permissions (e.g., read-only) - fix_permissions(target_dir) - console.print( - f" [green]✓[/green] Installed {job_name} ({target_dir.relative_to(project_path)})" - ) - - # Copy any doc specs from the standard job to .deepwork/doc_specs/ - doc_specs_source = standard_jobs_dir / "doc_specs" - doc_specs_target = project_path / ".deepwork" / "doc_specs" - if doc_specs_source.exists(): - for doc_spec_file in doc_specs_source.glob("*.md"): - target_doc_spec = doc_specs_target / doc_spec_file.name - shutil.copy(doc_spec_file, target_doc_spec) - # Fix permissions for copied doc spec - fix_permissions(target_doc_spec) - console.print( - f" [green]✓[/green] Installed doc spec {doc_spec_file.name} ({target_doc_spec.relative_to(project_path)})" - ) - except Exception as e: - raise InstallError(f"Failed to install {job_name}: {e}") from e - - -def _inject_deepwork_jobs(jobs_dir: Path, project_path: Path) -> None: - """ - Inject the deepwork_jobs job definition into the project. - - Args: - jobs_dir: Path to .deepwork/jobs directory - project_path: Path to project root (for relative path display) - - Raises: - InstallError: If injection fails - """ - _inject_standard_job("deepwork_jobs", jobs_dir, project_path) - def _create_deepwork_gitignore(deepwork_dir: Path) -> None: """ From 32b2d07d661139375910d703d50978bc5bc6a430 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 13 Feb 2026 18:57:14 +0000 Subject: [PATCH 4/7] style: ruff format https://claude.ai/code/session_01KU818enCNqHLbrqtdyCXUV --- src/deepwork/cli/install.py | 1 - tests/unit/test_jobs.py | 20 +++++--------------- 2 files changed, 5 insertions(+), 16 deletions(-) diff --git a/src/deepwork/cli/install.py b/src/deepwork/cli/install.py index ceb2ed7c..d30a6a3a 100644 --- a/src/deepwork/cli/install.py +++ b/src/deepwork/cli/install.py @@ -54,7 +54,6 @@ def _install_schemas(schemas_dir: Path, project_path: Path) -> None: raise InstallError(f"Failed to install schemas: {e}") from e - def _create_deepwork_gitignore(deepwork_dir: Path) -> None: """ Create .gitignore file in .deepwork/ directory. diff --git a/tests/unit/test_jobs.py b/tests/unit/test_jobs.py index 9a8b6e08..55532c18 100644 --- a/tests/unit/test_jobs.py +++ b/tests/unit/test_jobs.py @@ -57,9 +57,7 @@ def test_default_folders_include_standard_jobs(self, tmp_path: Path) -> None: folders = get_job_folders(tmp_path) assert _STANDARD_JOBS_DIR in folders - def test_env_var_appends_folders( - self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch - ) -> None: + def test_env_var_appends_folders(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None: monkeypatch.setenv(ENV_ADDITIONAL_JOBS_FOLDERS, "/extra/a:/extra/b") folders = get_job_folders(tmp_path) assert Path("/extra/a") in folders @@ -87,9 +85,7 @@ def test_env_var_strips_whitespace( class TestLoadAllJobs: """Tests for load_all_jobs.""" - def test_loads_from_project_jobs( - self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch - ) -> None: + def test_loads_from_project_jobs(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None: jobs_dir = tmp_path / ".deepwork" / "jobs" _create_minimal_job(jobs_dir, "my_job") monkeypatch.setattr( @@ -146,9 +142,7 @@ def test_skips_nonexistent_folders( jobs = load_all_jobs(tmp_path) assert len(jobs) == 0 - def test_skips_invalid_jobs( - self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch - ) -> None: + def test_skips_invalid_jobs(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None: folder = tmp_path / "jobs" bad_job = folder / "bad_job" bad_job.mkdir(parents=True) @@ -164,9 +158,7 @@ def test_skips_invalid_jobs( class TestFindJobDir: """Tests for find_job_dir.""" - def test_finds_in_first_folder( - self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch - ) -> None: + def test_finds_in_first_folder(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None: folder = tmp_path / "jobs" _create_minimal_job(folder, "target") monkeypatch.setattr( @@ -176,9 +168,7 @@ def test_finds_in_first_folder( result = find_job_dir(tmp_path, "target") assert result == folder / "target" - def test_finds_in_second_folder( - self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch - ) -> None: + def test_finds_in_second_folder(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None: folder_a = tmp_path / "a" folder_b = tmp_path / "b" folder_a.mkdir() From 5d69dd933e28dfb9323d12694658c47534c5792c Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 13 Feb 2026 19:01:29 +0000 Subject: [PATCH 5/7] style: migrate str+Enum to StrEnum (UP042) https://claude.ai/code/session_01KU818enCNqHLbrqtdyCXUV --- src/deepwork/core/adapters.py | 4 ++-- src/deepwork/hooks/wrapper.py | 6 +++--- src/deepwork/mcp/schemas.py | 4 ++-- 3 files changed, 7 insertions(+), 7 deletions(-) diff --git a/src/deepwork/core/adapters.py b/src/deepwork/core/adapters.py index 8bdd8321..2cd078fd 100644 --- a/src/deepwork/core/adapters.py +++ b/src/deepwork/core/adapters.py @@ -4,7 +4,7 @@ import json from abc import ABC, abstractmethod -from enum import Enum +from enum import StrEnum from pathlib import Path from typing import Any, ClassVar @@ -15,7 +15,7 @@ class AdapterError(Exception): pass -class SkillLifecycleHook(str, Enum): +class SkillLifecycleHook(StrEnum): """Generic skill lifecycle hook events supported by DeepWork. These represent hook points in the AI agent's skill execution lifecycle. diff --git a/src/deepwork/hooks/wrapper.py b/src/deepwork/hooks/wrapper.py index 96dba3a9..fb0e0eb3 100644 --- a/src/deepwork/hooks/wrapper.py +++ b/src/deepwork/hooks/wrapper.py @@ -41,18 +41,18 @@ def my_hook(input_data: HookInput) -> HookOutput: import sys from collections.abc import Callable from dataclasses import dataclass, field -from enum import Enum +from enum import StrEnum from typing import Any -class Platform(str, Enum): +class Platform(StrEnum): """Supported AI CLI platforms.""" CLAUDE = "claude" GEMINI = "gemini" -class NormalizedEvent(str, Enum): +class NormalizedEvent(StrEnum): """Normalized hook event names.""" AFTER_AGENT = "after_agent" diff --git a/src/deepwork/mcp/schemas.py b/src/deepwork/mcp/schemas.py index 347852b6..0e210698 100644 --- a/src/deepwork/mcp/schemas.py +++ b/src/deepwork/mcp/schemas.py @@ -6,7 +6,7 @@ the implementation. """ -from enum import Enum +from enum import StrEnum from typing import Any from pydantic import BaseModel, Field @@ -16,7 +16,7 @@ # ============================================================================= -class StepStatus(str, Enum): +class StepStatus(StrEnum): """Status returned from finished_step.""" NEEDS_WORK = "needs_work" From dc194c3f578b4b3eb08b3c13c2d24d97a788809a Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 13 Feb 2026 19:19:43 +0000 Subject: [PATCH 6/7] chore: update coverage to 79.91% from test_job_flow run Artifacts from running the test_job_flow workflow which exercised the full job creation pipeline end-to-end. https://claude.ai/code/session_01KU818enCNqHLbrqtdyCXUV --- README.md | 2 +- coverage_report.md | 48 ++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 49 insertions(+), 1 deletion(-) create mode 100644 coverage_report.md diff --git a/README.md b/README.md index 59bdfdf8..cbd51241 100644 --- a/README.md +++ b/README.md @@ -275,4 +275,4 @@ We're iterating fast. [Open an issue](https://github.com/Unsupervisedcom/deepwor Inspired by [GitHub's spec-kit](https://github.com/github/spec-kit) -**Code Coverage**: 78.99% (as of 2026-02-09) +**Code Coverage**: 79.91% (as of 2026-02-13) diff --git a/coverage_report.md b/coverage_report.md new file mode 100644 index 00000000..37ec328f --- /dev/null +++ b/coverage_report.md @@ -0,0 +1,48 @@ +# Code Coverage Report + +**Date**: 2026-02-13 +**Overall Coverage**: 79.91% + +## Per-File Coverage + +| File | Stmts | Miss | Cover | +|------|-------|------|-------| +| src/deepwork/__init__.py | 8 | 4 | 40.00% | +| src/deepwork/cli/__init__.py | 0 | 0 | 100.00% | +| src/deepwork/cli/hook.py | 27 | 17 | 32.26% | +| src/deepwork/cli/install.py | 154 | 9 | 94.21% | +| src/deepwork/cli/main.py | 17 | 1 | 89.47% | +| src/deepwork/cli/serve.py | 37 | 19 | 41.86% | +| src/deepwork/cli/sync.py | 174 | 50 | 70.72% | +| src/deepwork/core/__init__.py | 0 | 0 | 100.00% | +| src/deepwork/core/adapters.py | 204 | 58 | 67.16% | +| src/deepwork/core/detector.py | 32 | 5 | 86.84% | +| src/deepwork/core/doc_spec_parser.py | 75 | 4 | 95.51% | +| src/deepwork/core/generator.py | 42 | 8 | 78.00% | +| src/deepwork/core/hooks_syncer.py | 106 | 67 | 27.78% | +| src/deepwork/core/jobs.py | 43 | 2 | 92.31% | +| src/deepwork/core/parser.py | 287 | 54 | 78.73% | +| src/deepwork/hooks/__init__.py | 2 | 0 | 100.00% | +| src/deepwork/hooks/wrapper.py | 127 | 5 | 94.77% | +| src/deepwork/mcp/__init__.py | 4 | 2 | 50.00% | +| src/deepwork/mcp/claude_cli.py | 43 | 0 | 100.00% | +| src/deepwork/mcp/quality_gate.py | 189 | 6 | 95.88% | +| src/deepwork/mcp/schemas.py | 120 | 0 | 100.00% | +| src/deepwork/mcp/server.py | 54 | 54 | 0.00% | +| src/deepwork/mcp/state.py | 157 | 7 | 93.99% | +| src/deepwork/mcp/tools.py | 154 | 11 | 90.38% | +| src/deepwork/schemas/__init__.py | 0 | 0 | 100.00% | +| src/deepwork/schemas/doc_spec_schema.py | 3 | 0 | 100.00% | +| src/deepwork/schemas/job_schema.py | 11 | 1 | 90.91% | +| src/deepwork/templates/__init__.py | 0 | 0 | 100.00% | +| src/deepwork/utils/__init__.py | 0 | 0 | 100.00% | +| src/deepwork/utils/fs.py | 60 | 0 | 98.84% | +| src/deepwork/utils/git.py | 43 | 3 | 91.84% | +| src/deepwork/utils/validation.py | 11 | 0 | 100.00% | +| src/deepwork/utils/yaml_utils.py | 47 | 6 | 88.52% | + +## Summary + +- Total statements: 2231 +- Total missed: 393 +- Overall coverage: 79.91% From 2cd4bfe8258ab4cb307c0cd86c6d734402568967 Mon Sep 17 00:00:00 2001 From: Noah Horton Date: Fri, 13 Feb 2026 14:50:44 -0700 Subject: [PATCH 7/7] fix: increase e2e Run Workflow timeout from 3 to 6 minutes The merge queue run timed out at 3 minutes due to API latency. Previous successful runs took ~1.5 minutes, but 3 minutes is too tight for flaky conditions. Increasing to 6 minutes for headroom. Co-Authored-By: Claude Opus 4.6 --- .github/workflows/claude-code-test.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/claude-code-test.yml b/.github/workflows/claude-code-test.yml index 405c3ba9..76200bd6 100644 --- a/.github/workflows/claude-code-test.yml +++ b/.github/workflows/claude-code-test.yml @@ -361,7 +361,7 @@ jobs: - name: Run Workflow if: steps.check-key.outputs.has_key == 'true' working-directory: test_project - timeout-minutes: 3 + timeout-minutes: 6 run: | echo "=== Running fruits workflow with test input via /deepwork ==="