deepwork 0.1.0__py3-none-any.whl → 0.2.0__py3-none-any.whl

deepwork/cli/install.py

@@ -113,6 +113,48 @@ def _create_deepwork_gitignore(deepwork_dir: Path) -> None:
         gitignore_path.write_text(gitignore_content)
 
 
+def _create_default_policy_file(project_path: Path) -> bool:
+    """
+    Create a default policy file template in the project root.
+
+    Only creates the file if it doesn't already exist.
+
+    Args:
+        project_path: Path to the project root
+
+    Returns:
+        True if the file was created, False if it already existed
+    """
+    policy_file = project_path / ".deepwork.policy.yml"
+
+    if policy_file.exists():
+        return False
+
+    # Copy the template from the templates directory
+    template_path = Path(__file__).parent.parent / "templates" / "default_policy.yml"
+
+    if template_path.exists():
+        shutil.copy(template_path, policy_file)
+    else:
+        # Fallback: create a minimal template inline
+        policy_file.write_text(
+            """# DeepWork Policy Configuration
+#
+# Policies are automated guardrails that trigger when specific files change.
+# Use /deepwork_policy.define to create new policies interactively.
+#
+# Format:
+#   - name: "Policy name"
+#     trigger: "glob/pattern/**/*"
+#     safety: "optional/pattern/**/*"
+#     instructions: |
+#       Instructions for the AI agent...
+"""
+        )
+
+    return True
+
+
 class DynamicChoice(click.Choice):
     """A Click Choice that gets its values dynamically from AgentAdapter."""
 
@@ -238,6 +280,12 @@ def _install_deepwork(platform_name: str | None, project_path: Path) -> None:
     _create_deepwork_gitignore(deepwork_dir)
     console.print("  [green]✓[/green] Created .deepwork/.gitignore")
 
+    # Step 3d: Create default policy file template
+    if _create_default_policy_file(project_path):
+        console.print("  [green]✓[/green] Created .deepwork.policy.yml template")
+    else:
+        console.print("  [dim]•[/dim] .deepwork.policy.yml already exists")
+
     # Step 4: Load or create config.yml
     console.print("[yellow]→[/yellow] Updating configuration...")
     config_file = deepwork_dir / "config.yml"

deepwork/cli/sync.py

@@ -117,6 +117,7 @@ def sync_commands(project_path: Path) -> None:
     # Sync each platform
     generator = CommandGenerator()
     stats = {"platforms": 0, "commands": 0, "hooks": 0}
+    synced_adapters: list[AgentAdapter] = []
 
     for platform_name in platforms:
         try:
@@ -157,6 +158,7 @@ def sync_commands(project_path: Path) -> None:
                 console.print(f"    [red]✗[/red] Failed to sync hooks: {e}")
 
         stats["platforms"] += 1
+        synced_adapters.append(adapter)
 
     # Summary
     console.print()
@@ -174,3 +176,10 @@ def sync_commands(project_path: Path) -> None:
 
     console.print(table)
     console.print()
+
+    # Show reload instructions for each synced platform
+    if synced_adapters and stats["commands"] > 0:
+        console.print("[bold]To use the new commands:[/bold]")
+        for adapter in synced_adapters:
+            console.print(f"  [cyan]{adapter.display_name}:[/cyan] {adapter.reload_instructions}")
+        console.print()

deepwork/core/adapters.py

@@ -57,6 +57,12 @@ class AgentAdapter(ABC):
     commands_dir: ClassVar[str] = "commands"
     command_template: ClassVar[str] = "command-job-step.md.jinja"
 
+    # Instructions for reloading commands after sync (shown to users)
+    # Subclasses should override with platform-specific instructions.
+    reload_instructions: ClassVar[str] = (
+        "Restart your AI assistant session to use the new commands."
+    )
+
     # Mapping from generic CommandLifecycleHook to platform-specific event names.
     # Subclasses should override this to provide platform-specific mappings.
     hook_name_mapping: ClassVar[dict[CommandLifecycleHook, str]] = {}
@@ -253,6 +259,12 @@ class ClaudeAdapter(AgentAdapter):
     display_name = "Claude Code"
     config_dir = ".claude"
 
+    # Claude Code doesn't have a reload command - must restart session
+    reload_instructions: ClassVar[str] = (
+        "Type 'exit' to leave your current session, then run "
+        "'claude --resume' (your history will be maintained)."
+    )
+
     # Claude Code uses PascalCase event names
     hook_name_mapping: ClassVar[dict[CommandLifecycleHook, str]] = {
         CommandLifecycleHook.AFTER_AGENT: "Stop",
@@ -333,6 +345,11 @@ class GeminiAdapter(AgentAdapter):
     config_dir = ".gemini"
     command_template = "command-job-step.toml.jinja"
 
+    # Gemini CLI can reload with /memory refresh
+    reload_instructions: ClassVar[str] = (
+        "Run '/memory refresh' to reload commands, or restart your Gemini CLI session."
+    )
+
     # Gemini CLI does NOT support command-level hooks
     # Hooks are global/project-level in settings.json, not per-command
     hook_name_mapping: ClassVar[dict[CommandLifecycleHook, str]] = {}

deepwork/core/policy_parser.py

@@ -17,6 +17,11 @@ class PolicyParseError(Exception):
     pass
 
 
+# Valid compare_to values
+COMPARE_TO_VALUES = frozenset({"base", "default_tip", "prompt"})
+DEFAULT_COMPARE_TO = "base"
+
+
 @dataclass
 class Policy:
     """Represents a single policy definition."""
@@ -25,6 +30,7 @@ class Policy:
     triggers: list[str]  # Normalized to list
     safety: list[str] = field(default_factory=list)  # Normalized to list, empty if not specified
     instructions: str = ""  # Resolved content (either inline or from file)
+    compare_to: str = DEFAULT_COMPARE_TO  # What to compare against: base, default_tip, or prompt
 
     @classmethod
     def from_dict(cls, data: dict[str, Any], base_dir: Path | None = None) -> "Policy":
@@ -74,11 +80,15 @@ class Policy:
                 f"Policy '{data['name']}' must have either 'instructions' or 'instructions_file'"
             )
 
+        # Get compare_to (defaults to DEFAULT_COMPARE_TO)
+        compare_to = data.get("compare_to", DEFAULT_COMPARE_TO)
+
         return cls(
             name=data["name"],
             triggers=triggers,
             safety=safety,
             instructions=instructions,
+            compare_to=compare_to,
         )
 
 

deepwork/hooks/evaluate_policies.py

@@ -6,12 +6,16 @@ should fire based on changed files and conversation context.
 
 Usage:
     python -m deepwork.hooks.evaluate_policies \
-        --policy-file .deepwork.policy.yml \
-        --changed-files "file1.py\nfile2.py"
+        --policy-file .deepwork.policy.yml
 
 The conversation context is read from stdin and checked for <promise> tags
 that indicate policies have already been addressed.
 
+Changed files are computed based on each policy's compare_to setting:
+- base: Compare to merge-base with default branch (default)
+- default_tip: Two-dot diff against default branch tip
+- prompt: Compare to state captured at prompt submission
+
 Output is JSON suitable for Claude Code Stop hooks:
     {"decision": "block", "reason": "..."}  # Block stop, policies need attention
     {}  # No policies fired, allow stop
@@ -20,16 +24,223 @@ Output is JSON suitable for Claude Code Stop hooks:
 import argparse
 import json
 import re
+import subprocess
 import sys
 from pathlib import Path
 
 from deepwork.core.policy_parser import (
+    Policy,
     PolicyParseError,
-    evaluate_policies,
+    evaluate_policy,
     parse_policy_file,
 )
 
 
+def get_default_branch() -> str:
+    """
+    Get the default branch name (main or master).
+
+    Returns:
+        Default branch name, or "main" if cannot be determined.
+    """
+    # Try to get the default branch from remote HEAD
+    try:
+        result = subprocess.run(
+            ["git", "symbolic-ref", "refs/remotes/origin/HEAD"],
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+        # Output is like "refs/remotes/origin/main"
+        return result.stdout.strip().split("/")[-1]
+    except subprocess.CalledProcessError:
+        pass
+
+    # Try common default branch names
+    for branch in ["main", "master"]:
+        try:
+            subprocess.run(
+                ["git", "rev-parse", "--verify", f"origin/{branch}"],
+                capture_output=True,
+                check=True,
+            )
+            return branch
+        except subprocess.CalledProcessError:
+            continue
+
+    # Fall back to main
+    return "main"
+
+
+def get_changed_files_base() -> list[str]:
+    """
+    Get files changed relative to the base of the current branch.
+
+    This finds the merge-base between the current branch and the default branch,
+    then returns all files changed since that point.
+
+    Returns:
+        List of changed file paths.
+    """
+    default_branch = get_default_branch()
+
+    try:
+        # Get the merge-base (where current branch diverged from default)
+        result = subprocess.run(
+            ["git", "merge-base", "HEAD", f"origin/{default_branch}"],
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+        merge_base = result.stdout.strip()
+
+        # Stage all changes so they appear in diff
+        subprocess.run(["git", "add", "-A"], capture_output=True, check=False)
+
+        # Get files changed since merge-base (including staged)
+        result = subprocess.run(
+            ["git", "diff", "--name-only", merge_base, "HEAD"],
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+        committed_files = set(result.stdout.strip().split("\n")) if result.stdout.strip() else set()
+
+        # Also get staged changes not yet committed
+        result = subprocess.run(
+            ["git", "diff", "--name-only", "--cached"],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+        staged_files = set(result.stdout.strip().split("\n")) if result.stdout.strip() else set()
+
+        # Get untracked files
+        result = subprocess.run(
+            ["git", "ls-files", "--others", "--exclude-standard"],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+        untracked_files = set(result.stdout.strip().split("\n")) if result.stdout.strip() else set()
+
+        all_files = committed_files | staged_files | untracked_files
+        return sorted([f for f in all_files if f])
+
+    except subprocess.CalledProcessError:
+        return []
+
+
+def get_changed_files_default_tip() -> list[str]:
+    """
+    Get files changed compared to the tip of the default branch.
+
+    This does a two-dot diff: what's different between HEAD and origin/default.
+
+    Returns:
+        List of changed file paths.
+    """
+    default_branch = get_default_branch()
+
+    try:
+        # Stage all changes so they appear in diff
+        subprocess.run(["git", "add", "-A"], capture_output=True, check=False)
+
+        # Two-dot diff against default branch tip
+        result = subprocess.run(
+            ["git", "diff", "--name-only", f"origin/{default_branch}..HEAD"],
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+        committed_files = set(result.stdout.strip().split("\n")) if result.stdout.strip() else set()
+
+        # Also get staged changes not yet committed
+        result = subprocess.run(
+            ["git", "diff", "--name-only", "--cached"],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+        staged_files = set(result.stdout.strip().split("\n")) if result.stdout.strip() else set()
+
+        # Get untracked files
+        result = subprocess.run(
+            ["git", "ls-files", "--others", "--exclude-standard"],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+        untracked_files = set(result.stdout.strip().split("\n")) if result.stdout.strip() else set()
+
+        all_files = committed_files | staged_files | untracked_files
+        return sorted([f for f in all_files if f])
+
+    except subprocess.CalledProcessError:
+        return []
+
+
+def get_changed_files_prompt() -> list[str]:
+    """
+    Get files changed since the prompt was submitted.
+
+    This compares against the baseline captured by capture_prompt_work_tree.sh.
+
+    Returns:
+        List of changed file paths.
+    """
+    baseline_path = Path(".deepwork/.last_work_tree")
+
+    try:
+        # Stage all changes so we can see them with --cached
+        subprocess.run(["git", "add", "-A"], capture_output=True, check=False)
+
+        # Get all staged files (includes what was just staged)
+        result = subprocess.run(
+            ["git", "diff", "--name-only", "--cached"],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+        current_files = set(result.stdout.strip().split("\n")) if result.stdout.strip() else set()
+        current_files = {f for f in current_files if f}
+
+        if baseline_path.exists():
+            # Read baseline and find new files
+            baseline_files = set(baseline_path.read_text().strip().split("\n"))
+            baseline_files = {f for f in baseline_files if f}
+            # Return files that are in current but not in baseline
+            new_files = current_files - baseline_files
+            return sorted(new_files)
+        else:
+            # No baseline, return all current changes
+            return sorted(current_files)
+
+    except (subprocess.CalledProcessError, OSError):
+        return []
+
+
+def get_changed_files_for_mode(mode: str) -> list[str]:
+    """
+    Get changed files for a specific compare_to mode.
+
+    Args:
+        mode: One of 'base', 'default_tip', or 'prompt'
+
+    Returns:
+        List of changed file paths.
+    """
+    if mode == "base":
+        return get_changed_files_base()
+    elif mode == "default_tip":
+        return get_changed_files_default_tip()
+    elif mode == "prompt":
+        return get_changed_files_prompt()
+    else:
+        # Unknown mode, fall back to base
+        return get_changed_files_base()
+
+
 def extract_promise_tags(text: str) -> set[str]:
     """
     Extract policy names from <promise> tags in text.
@@ -87,23 +298,9 @@ def main() -> None:
         required=True,
         help="Path to .deepwork.policy.yml file",
     )
-    parser.add_argument(
-        "--changed-files",
-        type=str,
-        required=True,
-        help="Newline-separated list of changed files",
-    )
 
     args = parser.parse_args()
 
-    # Parse changed files (newline-separated)
-    changed_files = [f.strip() for f in args.changed_files.split("\n") if f.strip()]
-
-    if not changed_files:
-        # No files changed, nothing to evaluate
-        print("{}")
-        return
-
     # Check if policy file exists
     policy_path = Path(args.policy_file)
     if not policy_path.exists():
@@ -122,7 +319,7 @@ def main() -> None:
     # Extract promise tags from conversation
     promised_policies = extract_promise_tags(conversation_context)
 
-    # Parse and evaluate policies
+    # Parse policies
     try:
         policies = parse_policy_file(policy_path)
     except PolicyParseError as e:
@@ -136,8 +333,28 @@ def main() -> None:
         print("{}")
         return
 
-    # Evaluate which policies fire
-    fired_policies = evaluate_policies(policies, changed_files, promised_policies)
+    # Group policies by compare_to mode to minimize git calls
+    policies_by_mode: dict[str, list[Policy]] = {}
+    for policy in policies:
+        mode = policy.compare_to
+        if mode not in policies_by_mode:
+            policies_by_mode[mode] = []
+        policies_by_mode[mode].append(policy)
+
+    # Get changed files for each mode and evaluate policies
+    fired_policies: list[Policy] = []
+    for mode, mode_policies in policies_by_mode.items():
+        changed_files = get_changed_files_for_mode(mode)
+        if not changed_files:
+            continue
+
+        for policy in mode_policies:
+            # Skip if already promised
+            if policy.name in promised_policies:
+                continue
+            # Evaluate this policy
+            if evaluate_policy(policy, changed_files):
+                fired_policies.append(policy)
 
     if not fired_policies:
         # No policies fired

deepwork/schemas/policy_schema.py

@@ -58,6 +58,16 @@ POLICY_SCHEMA: dict[str, Any] = {
                 "minLength": 1,
                 "description": "Path to a file containing instructions (alternative to inline instructions)",
             },
+            "compare_to": {
+                "type": "string",
+                "enum": ["base", "default_tip", "prompt"],
+                "description": (
+                    "What to compare against when detecting changed files. "
+                    "'base' (default) compares to the base of the current branch. "
+                    "'default_tip' compares to the tip of the default branch. "
+                    "'prompt' compares to the state at the start of the prompt."
+                ),
+            },
         },
         "oneOf": [
             {"required": ["instructions"]},

deepwork/standard_jobs/deepwork_jobs/AGENTS.md

@@ -0,0 +1,60 @@
+# 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 `deepwork sync` to generate commands
+
+After making changes to the source, copy files to the working 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
+│   ├── 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
+```
+
+## 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-01-15
+- From conversation about: Adding make_new_job.sh script and templates directory

deepwork/standard_jobs/deepwork_jobs/job.yml

@@ -1,20 +1,27 @@
 name: deepwork_jobs
-version: "0.1.0"
+version: "0.4.0"
 summary: "DeepWork job management commands"
 description: |
   Core commands for managing DeepWork jobs. These commands help you define new multi-step
-  workflows and refine existing ones.
+  workflows and learn from running them.
 
   The `define` command guides you through an interactive process to create a new job by
   asking detailed questions about your workflow, understanding each step's inputs and outputs,
   and generating all necessary files.
 
-  The `refine` command helps you modify existing jobs safely by understanding what you want
-  to change, validating the impact, and ensuring consistency across your workflow.
+  The `learn` command 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.
 
 changelog:
   - 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"
 
 steps:
   - id: define
@@ -51,7 +58,7 @@ steps:
       - file: job.yml
         from_step: define
     outputs:
-      - implementation_summary.md
+      - steps/
     dependencies:
       - define
     hooks:
@@ -66,37 +73,38 @@ steps:
             5. **Quality Criteria**: Does each instruction file define quality criteria for its outputs?
             6. **Sync Complete**: Has `deepwork sync` been run successfully?
             7. **Commands Available**: Are the slash-commands generated in `.claude/commands/`?
-            8. **Summary Created**: Has `implementation_summary.md` been created?
-            9. **Policies Considered**: Have you thought about whether policies would benefit this job?
+            8. **Policies Considered**: Have you thought about whether policies would benefit this job?
                - If relevant policies were identified, did you explain them and offer to run `/deepwork_policy.define`?
                - Not every job needs policies - only suggest when genuinely helpful.
 
             If ANY criterion is not met, continue working to address it.
             If ALL criteria are satisfied, include `<promise>✓ Quality Criteria Met</promise>` in your response.
 
-  - id: refine
-    name: "Refine Existing Job"
-    description: "Modify an existing job definition"
-    instructions_file: steps/refine.md
+  - id: learn
+    name: "Learn from Job Execution"
+    description: "Reflect on conversation to improve job instructions and capture learnings"
+    instructions_file: steps/learn.md
     inputs:
       - name: job_name
-        description: "Name of the job to refine"
+        description: "Name of the job that was run (optional - will auto-detect from conversation)"
     outputs:
-      - job.yml
+      - AGENTS.md
     dependencies: []
     hooks:
       after_agent:
         - prompt: |
-            Verify the refinement meets ALL quality criteria before completing:
+            Verify the learning process meets ALL quality criteria before completing:
 
-            1. **Job Consistency**: Do the changes maintain overall job consistency?
-            2. **Valid Dependencies**: Are all step dependencies logically valid (no circular refs)?
-            3. **Semantic Versioning**: Was the version bumped appropriately (major/minor/patch)?
-            4. **Changelog Updated**: Is the changelog updated with a description of changes?
-            5. **User Understanding**: Does the user understand the impact of the changes?
-            6. **Breaking Changes**: Were any breaking changes clearly communicated?
-            7. **Files Updated**: Are all affected files (job.yml, step files) updated?
-            8. **Sync Complete**: Has `deepwork sync` been run to regenerate commands?
+            1. **Conversation Analyzed**: Did you review the conversation for DeepWork job executions?
+            2. **Confusion Identified**: Did you identify points of confusion, errors, or inefficiencies?
+            3. **Instructions Improved**: Were job instructions updated to address identified issues?
+            4. **Instructions Concise**: Are instructions free of redundancy and unnecessary verbosity?
+            5. **Shared Content Extracted**: Is lengthy/duplicated content extracted into referenced files?
+            6. **Bespoke Learnings Captured**: Were run-specific learnings added to AGENTS.md?
+            7. **File References Used**: Do AGENTS.md entries reference other files where appropriate?
+            8. **Working Folder Correct**: Is AGENTS.md in the correct working folder for the job?
+            9. **Generalizable Separated**: Are generalizable improvements in instructions, not AGENTS.md?
+            10. **Sync Complete**: Has `deepwork sync` been run if instructions were modified?
 
             If ANY criterion is not met, continue working to address it.
             If ALL criteria are satisfied, include `<promise>✓ Quality Criteria Met</promise>` in your response.