Merge branch 'main' into add-update-job

Author: nhorton

CHANGELOG.md

@@ -5,6 +5,14 @@ All notable changes to DeepWork will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.1.2] - 2026-01-15
+
+### Added
+- Default policy template file created during `deepwork install`
+  - Generic, commented-out example policies suitable for any project
+  - Does not include deepwork-specific policies (those remain in the deepwork repo only)
+  - Preserves existing policy files if already present
+
 ## [0.1.1] - 2026-01-15
 
 ### Added
@@ -41,5 +49,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 Initial version.
 
+[0.1.2]: https://github.com/anthropics/deepwork/releases/tag/v0.1.2
 [0.1.1]: https://github.com/anthropics/deepwork/releases/tag/v0.1.1
 [0.1.0]: https://github.com/anthropics/deepwork/releases/tag/v0.1.0

README.md

@@ -62,6 +62,7 @@ This will:
 - Generate core DeepWork jobs
 - Install DeepWork jobs for your AI assistant
 - Configure hooks for your AI assistant to enable policies
+- Create a `.deepwork.policy.yml` template file with example policies
 
 ## Quick Start
 

doc/architecture.md

@@ -116,6 +116,10 @@ def install(platform: str):
     # Inject core job definitions
     inject_deepwork_jobs(".deepwork/jobs/")
 
+    # Create default policy template (if not exists)
+    if not exists(".deepwork.policy.yml"):
+        copy_template("default_policy.yml", ".deepwork.policy.yml")
+
     # Update config (supports multiple platforms)
     config = load_yaml(".deepwork/config.yml") or {}
     config["version"] = "1.0.0"

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "deepwork"
-version = "0.1.1"
+version = "0.1.2"
 description = "Framework for enabling AI agents to perform complex, multi-step work tasks"
 readme = "README.md"
 requires-python = ">=3.11"

src/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"

src/deepwork/templates/default_policy.yml

@@ -0,0 +1,53 @@
+# DeepWork Policy Configuration
+#
+# Policies are automated guardrails that trigger when specific files change.
+# They help ensure documentation stays current, security reviews happen, etc.
+#
+# Use /deepwork_policy.define to create new policies interactively.
+#
+# Format:
+#   - name: "Friendly name for the policy"
+#     trigger: "glob/pattern/**/*"  # or array: ["pattern1", "pattern2"]
+#     safety: "pattern/**/*"        # optional - if these also changed, skip the policy
+#     compare_to: "base"            # optional: "base" (default), "default_tip", or "prompt"
+#     instructions: |
+#       Multi-line instructions for the AI agent...
+#
+# Example policies (uncomment and customize):
+#
+# - name: "README Documentation"
+#   trigger: "src/**/*"
+#   safety: "README.md"
+#   instructions: |
+#     Source code has been modified. Please review README.md for accuracy:
+#     1. Verify the project overview reflects current functionality
+#     2. Check that usage examples are still correct
+#     3. Ensure installation/setup instructions remain valid
+#
+# - name: "API Documentation Sync"
+#   trigger: "src/api/**/*"
+#   safety: "docs/api/**/*.md"
+#   instructions: |
+#     API code has changed. Please verify that API documentation is up to date:
+#     - New or changed endpoints
+#     - Modified request/response schemas
+#     - Updated authentication requirements
+#
+# - name: "Security Review for Auth Changes"
+#   trigger:
+#     - "src/auth/**/*"
+#     - "src/security/**/*"
+#   instructions: |
+#     Authentication or security code has been changed. Please:
+#     1. Review for hardcoded credentials or secrets
+#     2. Check input validation on user inputs
+#     3. Verify access control logic is correct
+#
+# - name: "Test Coverage for New Code"
+#   trigger: "src/**/*.py"
+#   safety: "tests/**/*.py"
+#   instructions: |
+#     New source code was added. Please ensure appropriate test coverage:
+#     1. Add unit tests for new functions/methods
+#     2. Update integration tests if behavior changed
+#     3. Verify all new code paths are tested

tests/integration/test_install_flow.py

@@ -122,6 +122,58 @@ def test_install_is_idempotent(self, mock_claude_project: Path) -> None:
         assert (claude_dir / "deepwork_jobs.define.md").exists()
         assert (claude_dir / "deepwork_jobs.learn.md").exists()
 
+    def test_install_creates_policy_template(self, mock_claude_project: Path) -> None:
+        """Test that install creates a policy template file."""
+        runner = CliRunner()
+
+        result = runner.invoke(
+            cli,
+            ["install", "--platform", "claude", "--path", str(mock_claude_project)],
+            catch_exceptions=False,
+        )
+
+        assert result.exit_code == 0
+        assert ".deepwork.policy.yml template" in result.output
+
+        # Verify policy file was created
+        policy_file = mock_claude_project / ".deepwork.policy.yml"
+        assert policy_file.exists()
+
+        # Verify it's the template (has comment header, no active policies)
+        content = policy_file.read_text()
+        assert "# DeepWork Policy Configuration" in content
+        assert "# Use /deepwork_policy.define" in content
+
+        # Verify it does NOT contain deepwork-specific policies
+        assert "Standard Jobs Source of Truth" not in content
+        assert "Version and Changelog Update" not in content
+        assert "pyproject.toml" not in content
+
+    def test_install_preserves_existing_policy_file(self, mock_claude_project: Path) -> None:
+        """Test that install doesn't overwrite existing policy file."""
+        runner = CliRunner()
+
+        # Create a custom policy file before install
+        policy_file = mock_claude_project / ".deepwork.policy.yml"
+        custom_content = """- name: "My Custom Policy"
+  trigger: "src/**/*"
+  instructions: |
+    Custom instructions here.
+"""
+        policy_file.write_text(custom_content)
+
+        result = runner.invoke(
+            cli,
+            ["install", "--platform", "claude", "--path", str(mock_claude_project)],
+            catch_exceptions=False,
+        )
+
+        assert result.exit_code == 0
+        assert ".deepwork.policy.yml already exists" in result.output
+
+        # Verify original content is preserved
+        assert policy_file.read_text() == custom_content
+
 
 class TestCLIEntryPoint:
     """Tests for CLI entry point."""

tests/shell_script_tests/README.md

@@ -0,0 +1,76 @@
+# Shell Script Tests
+
+Automated tests for DeepWork shell scripts, with a focus on validating Claude Code hooks JSON response formats.
+
+## Scripts Tested
+
+| Script | Type | Description |
+|--------|------|-------------|
+| `policy_stop_hook.sh` | Stop Hook | Evaluates policies and blocks agent stop if policies are triggered |
+| `user_prompt_submit.sh` | UserPromptSubmit Hook | Captures work tree state when user submits a prompt |
+| `capture_prompt_work_tree.sh` | Helper | Records current git state for `compare_to: prompt` policies |
+| `make_new_job.sh` | Utility | Creates directory structure for new DeepWork jobs |
+
+## Claude Code Hooks JSON Format
+
+Hook scripts must return valid JSON responses. The tests enforce these formats:
+
+### Stop Hooks (`hooks.after_agent`)
+```json
+{}                                          // Allow stop
+{"decision": "block", "reason": "..."}      // Block stop with reason
+```
+
+### UserPromptSubmit Hooks (`hooks.before_prompt`)
+```json
+{}    // No output or empty object (side-effect only hooks)
+```
+
+### All Hooks
+- Must return valid JSON if producing output
+- Non-JSON output on stdout is **not allowed** (stderr is ok)
+- Exit code 0 indicates success (even when blocking)
+
+## Running Tests
+
+```bash
+# Run all shell script tests
+uv run pytest tests/shell_script_tests/ -v
+
+# Run tests for a specific script
+uv run pytest tests/shell_script_tests/test_policy_stop_hook.py -v
+
+# Run with coverage
+uv run pytest tests/shell_script_tests/ --cov=src/deepwork
+```
+
+## Test Structure
+
+```
+tests/shell_script_tests/
+├── conftest.py                      # Shared fixtures and helpers
+├── test_policy_stop_hook.py         # Stop hook blocking/allowing tests
+├── test_user_prompt_submit.py       # Prompt submission hook tests
+├── test_capture_prompt_work_tree.py # Work tree capture tests
+├── test_hooks_json_format.py        # JSON format validation tests
+└── test_make_new_job.py             # Job directory creation tests
+```
+
+## Shared Fixtures
+
+Available in `conftest.py`:
+
+| Fixture | Description |
+|---------|-------------|
+| `git_repo` | Basic git repo with initial commit |
+| `git_repo_with_policy` | Git repo with a Python file policy |
+| `policy_hooks_dir` | Path to policy hooks scripts |
+| `jobs_scripts_dir` | Path to job management scripts |
+
+## Adding New Tests
+
+1. Use shared fixtures from `conftest.py` when possible
+2. Use `run_shell_script()` helper for running scripts
+3. Validate JSON output with `validate_json_output()` and `validate_stop_hook_response()`
+4. Test both success and failure cases
+5. Verify exit codes (hooks should exit 0 even when blocking)