Fix Nix flake package to include Python with deepwork in PYTHONPATH

Co-authored-by: ncrmro <8276365+ncrmro@users.noreply.github.com>

Author: Copilot

doc/nix-flake.md

@@ -321,6 +321,51 @@ If you get an error about flakes not being recognized:
 echo "experimental-features = nix-command flakes" >> ~/.config/nix/nix.conf
 ```
 
+### Hooks Not Finding DeepWork Module
+
+When using DeepWork from a Nix flake in your project, hooks may fail with "No module named 'deepwork'" because they run outside of `nix develop`. The flake package includes wrapper scripts that solve this:
+
+**Solution:**
+
+Instead of using `python -m deepwork.hooks.rules_check` directly in hooks, use the provided wrapper commands:
+
+- For Claude Code: Use `deepwork-python -m deepwork.hooks.rules_check`
+- For Gemini CLI: Use `deepwork-python -m deepwork.hooks.rules_check`
+
+Or use the dedicated hook wrappers:
+- `deepwork-claude-hook deepwork.hooks.rules_check`
+- `deepwork-gemini-hook deepwork.hooks.rules_check`
+
+These wrappers ensure the Python environment has access to the deepwork module even when running outside of the Nix development shell.
+
+**In your flake.nix:**
+
+```nix
+{
+  inputs = {
+    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
+    deepwork.url = "github:Unsupervisedcom/deepwork";
+  };
+
+  outputs = { self, nixpkgs, deepwork }:
+    let
+      system = "x86_64-linux";
+      pkgs = import nixpkgs { inherit system; };
+    in {
+      devShells.${system}.default = pkgs.mkShell {
+        buildInputs = [
+          deepwork.packages.${system}.default
+        ];
+        
+        # Optional: Add deepwork binaries to PATH for easier hook usage
+        shellHook = ''
+          export PATH="${deepwork.packages.${system}.default}/bin:$PATH"
+        '';
+      };
+    };
+}
+```
+
 ### direnv Not Working
 
 1. Make sure direnv is installed:

flake.nix

@@ -11,35 +11,83 @@
       let
         pkgs = import nixpkgs {
           inherit system;
-          # Allow unfree packages to support the Business Source License 1.1
-          config.allowUnfree = true;
         };
-        deepwork = pkgs.python311Packages.buildPythonPackage {
-          pname = "deepwork";
-          version = "0.3.0";
+        
+        # Create a wrapped Python environment with deepwork available
+        pythonWithDeepwork = pkgs.python311.withPackages (ps: [
+          (ps.buildPythonPackage {
+            pname = "deepwork";
+            version = "0.3.0";
+            src = ./.;
+            format = "pyproject";
+            
+            nativeBuildInputs = with ps; [
+              hatchling
+            ];
+            
+            propagatedBuildInputs = with ps; [
+              jinja2
+              pyyaml
+              gitpython
+              click
+              rich
+              jsonschema
+            ];
+
+            # Skip tests during build (they can be run in devShell)
+            doCheck = false;
+
+            meta = with pkgs.lib; {
+              description = "Framework for enabling AI agents to perform complex, multi-step work tasks";
+              homepage = "https://github.com/Unsupervisedcom/deepwork";
+              # Business Source License 1.1 - not OSI approved
+              license = {
+                fullName = "Business Source License 1.1";
+                url = "https://github.com/Unsupervisedcom/deepwork/blob/main/LICENSE.md";
+                free = false;
+              };
+            };
+          })
+        ]);
+
+        # Create the main deepwork package with proper wrappers
+        deepwork = pkgs.stdenv.mkDerivation {
+          name = "deepwork-0.3.0";
           src = ./.;
-          format = "pyproject";
-          
-          nativeBuildInputs = with pkgs.python311Packages; [
-            hatchling
-          ];
-          
-          propagatedBuildInputs = with pkgs.python311Packages; [
-            jinja2
-            pyyaml
-            gitpython
-            click
-            rich
-            jsonschema
-          ];
 
-          # Skip tests during build (they can be run in devShell)
-          doCheck = false;
+          nativeBuildInputs = [ pkgs.makeWrapper ];
+
+          buildPhase = ''
+            # Nothing to build, we just need to wrap the Python package
+          '';
+
+          installPhase = ''
+            mkdir -p $out/bin
+
+            # Create wrapper for deepwork CLI
+            makeWrapper ${pythonWithDeepwork}/bin/deepwork $out/bin/deepwork \
+              --set PYTHONPATH "${pythonWithDeepwork}/${pythonWithDeepwork.sitePackages}"
+
+            # Create wrapper scripts for claude hook
+            makeWrapper ${pythonWithDeepwork}/bin/python $out/bin/deepwork-claude-hook \
+              --add-flags "-m" \
+              --set PYTHONPATH "${pythonWithDeepwork}/${pythonWithDeepwork.sitePackages}" \
+              --set DEEPWORK_HOOK_PLATFORM "claude"
+
+            # Create wrapper scripts for gemini hook
+            makeWrapper ${pythonWithDeepwork}/bin/python $out/bin/deepwork-gemini-hook \
+              --add-flags "-m" \
+              --set PYTHONPATH "${pythonWithDeepwork}/${pythonWithDeepwork.sitePackages}" \
+              --set DEEPWORK_HOOK_PLATFORM "gemini"
+
+            # Also create a python wrapper that has deepwork in PYTHONPATH
+            makeWrapper ${pythonWithDeepwork}/bin/python $out/bin/deepwork-python \
+              --set PYTHONPATH "${pythonWithDeepwork}/${pythonWithDeepwork.sitePackages}"
+          '';
 
           meta = with pkgs.lib; {
             description = "Framework for enabling AI agents to perform complex, multi-step work tasks";
             homepage = "https://github.com/Unsupervisedcom/deepwork";
-            # Business Source License 1.1 - not OSI approved
             license = {
               fullName = "Business Source License 1.1";
               url = "https://github.com/Unsupervisedcom/deepwork/blob/main/LICENSE.md";