deepwork 0.4.0__py3-none-any.whl → 0.7.0__py3-none-any.whl

deepwork/core/parser.py

@@ -1,5 +1,6 @@
 """Job definition parser."""
 
+import logging
 from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Any
@@ -8,6 +9,8 @@ from deepwork.schemas.job_schema import JOB_SCHEMA, LIFECYCLE_HOOK_EVENTS
 from deepwork.utils.validation import ValidationError, validate_against_schema
 from deepwork.utils.yaml_utils import YAMLError, load_yaml
 
+logger = logging.getLogger("deepwork.parser")
+
 
 class ParseError(Exception):
     """Exception raised for job parsing errors."""
@@ -142,6 +145,9 @@ class Step:
     # Declarative quality criteria rendered with standard evaluation framing
     quality_criteria: list[str] = field(default_factory=list)
 
+    # Agent type for this step (e.g., "general-purpose"). When set, skill uses context: fork
+    agent: str | None = None
+
     @property
     def stop_hooks(self) -> list[HookAction]:
         """
@@ -180,6 +186,78 @@ class Step:
             hooks=hooks,
             exposed=data.get("exposed", False),
             quality_criteria=data.get("quality_criteria", []),
+            agent=data.get("agent"),
+        )
+
+
+@dataclass
+class WorkflowStepEntry:
+    """Represents a single entry in a workflow's step list.
+
+    Each entry can be either:
+    - A single step (sequential execution)
+    - A list of steps (concurrent execution)
+    """
+
+    step_ids: list[str]  # Single step has one ID, concurrent group has multiple
+    is_concurrent: bool = False
+
+    @property
+    def first_step(self) -> str:
+        """Get the first step ID in this entry."""
+        return self.step_ids[0] if self.step_ids else ""
+
+    def all_step_ids(self) -> list[str]:
+        """Get all step IDs in this entry."""
+        return self.step_ids
+
+    @classmethod
+    def from_data(cls, data: str | list[str]) -> "WorkflowStepEntry":
+        """Create WorkflowStepEntry from YAML data (string or list)."""
+        if isinstance(data, str):
+            return cls(step_ids=[data], is_concurrent=False)
+        else:
+            return cls(step_ids=list(data), is_concurrent=True)
+
+
+@dataclass
+class Workflow:
+    """Represents a named workflow grouping steps into a multi-step sequence."""
+
+    name: str
+    summary: str
+    step_entries: list[WorkflowStepEntry]  # List of step entries (sequential or concurrent)
+
+    @property
+    def steps(self) -> list[str]:
+        """Get flattened list of all step IDs for backward compatibility."""
+        result: list[str] = []
+        for entry in self.step_entries:
+            result.extend(entry.step_ids)
+        return result
+
+    def get_step_entry_for_step(self, step_id: str) -> WorkflowStepEntry | None:
+        """Get the workflow step entry containing the given step ID."""
+        for entry in self.step_entries:
+            if step_id in entry.step_ids:
+                return entry
+        return None
+
+    def get_entry_index_for_step(self, step_id: str) -> int | None:
+        """Get the index of the entry containing the given step ID."""
+        for i, entry in enumerate(self.step_entries):
+            if step_id in entry.step_ids:
+                return i
+        return None
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "Workflow":
+        """Create Workflow from dictionary."""
+        step_entries = [WorkflowStepEntry.from_data(s) for s in data["steps"]]
+        return cls(
+            name=data["name"],
+            summary=data["summary"],
+            step_entries=step_entries,
         )
 
 
@@ -193,6 +271,7 @@ class JobDefinition:
     description: str | None
     steps: list[Step]
     job_dir: Path
+    workflows: list[Workflow] = field(default_factory=list)
 
     def get_step(self, step_id: str) -> Step | None:
         """
@@ -308,6 +387,190 @@ class JobDefinition:
                     doc_spec_refs.add(output.doc_spec)
         return list(doc_spec_refs)
 
+    def get_workflow_for_step(self, step_id: str) -> Workflow | None:
+        """
+        Get the workflow containing a step.
+
+        Args:
+            step_id: Step ID to look up
+
+        Returns:
+            Workflow containing the step, or None if step is standalone
+        """
+        for workflow in self.workflows:
+            if step_id in workflow.steps:
+                return workflow
+        return None
+
+    def get_next_step_in_workflow(self, step_id: str) -> str | None:
+        """
+        Get the next step in a workflow after the given step.
+
+        Args:
+            step_id: Current step ID
+
+        Returns:
+            Next step ID, or None if this is the last step or not in a workflow
+        """
+        workflow = self.get_workflow_for_step(step_id)
+        if not workflow:
+            return None
+        try:
+            index = workflow.steps.index(step_id)
+            if index < len(workflow.steps) - 1:
+                return workflow.steps[index + 1]
+        except ValueError:
+            pass
+        return None
+
+    def get_prev_step_in_workflow(self, step_id: str) -> str | None:
+        """
+        Get the previous step in a workflow before the given step.
+
+        Args:
+            step_id: Current step ID
+
+        Returns:
+            Previous step ID, or None if this is the first step or not in a workflow
+        """
+        workflow = self.get_workflow_for_step(step_id)
+        if not workflow:
+            return None
+        try:
+            index = workflow.steps.index(step_id)
+            if index > 0:
+                return workflow.steps[index - 1]
+        except ValueError:
+            pass
+        return None
+
+    def get_step_position_in_workflow(self, step_id: str) -> tuple[int, int] | None:
+        """
+        Get the position of a step within its workflow.
+
+        Args:
+            step_id: Step ID to look up
+
+        Returns:
+            Tuple of (1-based position, total steps in workflow), or None if standalone
+        """
+        workflow = self.get_workflow_for_step(step_id)
+        if not workflow:
+            return None
+        try:
+            index = workflow.steps.index(step_id)
+            return (index + 1, len(workflow.steps))
+        except ValueError:
+            return None
+
+    def get_step_entry_position_in_workflow(
+        self, step_id: str
+    ) -> tuple[int, int, WorkflowStepEntry] | None:
+        """
+        Get the entry-based position of a step within its workflow.
+
+        For concurrent step groups, multiple steps share the same entry position.
+
+        Args:
+            step_id: Step ID to look up
+
+        Returns:
+            Tuple of (1-based entry position, total entries, WorkflowStepEntry),
+            or None if standalone
+        """
+        workflow = self.get_workflow_for_step(step_id)
+        if not workflow:
+            return None
+
+        entry_index = workflow.get_entry_index_for_step(step_id)
+        if entry_index is None:
+            return None
+
+        entry = workflow.step_entries[entry_index]
+        return (entry_index + 1, len(workflow.step_entries), entry)
+
+    def get_concurrent_step_info(self, step_id: str) -> tuple[int, int] | None:
+        """
+        Get information about a step's position within a concurrent group.
+
+        Args:
+            step_id: Step ID to look up
+
+        Returns:
+            Tuple of (1-based position in group, total in group) if step is in
+            a concurrent group, None if step is not in a concurrent group
+        """
+        workflow = self.get_workflow_for_step(step_id)
+        if not workflow:
+            return None
+
+        entry = workflow.get_step_entry_for_step(step_id)
+        if entry is None or not entry.is_concurrent:
+            return None
+
+        try:
+            index = entry.step_ids.index(step_id)
+            return (index + 1, len(entry.step_ids))
+        except ValueError:
+            return None
+
+    def validate_workflows(self) -> None:
+        """
+        Validate workflow definitions.
+
+        Raises:
+            ParseError: If workflow references non-existent steps or has duplicates
+        """
+        step_ids = {step.id for step in self.steps}
+        workflow_names = set()
+
+        for workflow in self.workflows:
+            # Check for duplicate workflow names
+            if workflow.name in workflow_names:
+                raise ParseError(f"Duplicate workflow name: '{workflow.name}'")
+            workflow_names.add(workflow.name)
+
+            # Check all step references exist
+            for step_id in workflow.steps:
+                if step_id not in step_ids:
+                    raise ParseError(
+                        f"Workflow '{workflow.name}' references non-existent step '{step_id}'"
+                    )
+
+            # Check for duplicate steps within a workflow
+            seen_steps = set()
+            for step_id in workflow.steps:
+                if step_id in seen_steps:
+                    raise ParseError(
+                        f"Workflow '{workflow.name}' contains duplicate step '{step_id}'"
+                    )
+                seen_steps.add(step_id)
+
+    def warn_orphaned_steps(self) -> list[str]:
+        """
+        Check for steps not included in any workflow and emit warnings.
+
+        Returns:
+            List of orphaned step IDs
+        """
+        # Collect all step IDs referenced in workflows
+        workflow_step_ids: set[str] = set()
+        for workflow in self.workflows:
+            workflow_step_ids.update(workflow.steps)
+
+        # Find orphaned steps
+        orphaned_steps = [step.id for step in self.steps if step.id not in workflow_step_ids]
+
+        if orphaned_steps:
+            logger.warning(
+                "Job '%s' has steps not included in any workflow: %s. "
+                "These steps are not accessible via the MCP interface.",
+                self.name,
+                ", ".join(orphaned_steps),
+            )
+
+        return orphaned_steps
+
     @classmethod
     def from_dict(cls, data: dict[str, Any], job_dir: Path) -> "JobDefinition":
         """
@@ -320,6 +583,7 @@ class JobDefinition:
         Returns:
             JobDefinition instance
         """
+        workflows = [Workflow.from_dict(wf_data) for wf_data in data.get("workflows", [])]
         return cls(
             name=data["name"],
             version=data["version"],
@@ -327,6 +591,7 @@ class JobDefinition:
             description=data.get("description"),
             steps=[Step.from_dict(step_data) for step_data in data["steps"]],
             job_dir=job_dir,
+            workflows=workflows,
         )
 
 
@@ -373,8 +638,12 @@ def parse_job_definition(job_dir: Path | str) -> JobDefinition:
     # Parse into dataclass
     job_def = JobDefinition.from_dict(job_data, job_dir_path)
 
-    # Validate dependencies and file inputs
+    # Validate dependencies, file inputs, and workflows
     job_def.validate_dependencies()
     job_def.validate_file_inputs()
+    job_def.validate_workflows()
+
+    # Warn about orphaned steps (not in any workflow)
+    job_def.warn_orphaned_steps()
 
     return job_def

deepwork/hooks/README.md

@@ -15,51 +15,8 @@ The hook system provides:
    - Output denormalization (decision values, JSON structure)
    - Cross-platform compatibility
 
-3. **Hook implementations**:
-   - `rules_check.py` - Evaluates DeepWork rules on `after_agent` events
-
 ## Usage
 
-### Registering Hooks
-
-#### Claude Code (`.claude/settings.json`)
-
-```json
-{
-  "hooks": {
-    "Stop": [
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "command": "path/to/claude_hook.sh deepwork.hooks.rules_check"
-          }
-        ]
-      }
-    ]
-  }
-}
-```
-
-#### Gemini CLI (`.gemini/settings.json`)
-
-```json
-{
-  "hooks": {
-    "AfterAgent": [
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "command": "path/to/gemini_hook.sh deepwork.hooks.rules_check"
-          }
-        ]
-      }
-    ]
-  }
-}
-```
-
 ### Writing Custom Hooks
 
 1. Create a new Python module in `deepwork/hooks/`:
@@ -178,4 +135,3 @@ pytest tests/shell_script_tests/test_hook_wrappers.py -v
 | `wrapper.py` | Cross-platform input/output normalization |
 | `claude_hook.sh` | Shell wrapper for Claude Code |
 | `gemini_hook.sh` | Shell wrapper for Gemini CLI |
-| `rules_check.py` | Cross-platform rule evaluation hook |

deepwork/hooks/__init__.py

@@ -1,4 +1,4 @@
-"""DeepWork hooks package for rules enforcement and lifecycle events.
+"""DeepWork hooks package for lifecycle events.
 
 This package provides:
 
@@ -7,9 +7,6 @@ This package provides:
    - claude_hook.sh: Shell wrapper for Claude Code hooks
    - gemini_hook.sh: Shell wrapper for Gemini CLI hooks
 
-2. Hook implementations:
-   - rules_check.py: Evaluates rules on after_agent events
-
 Usage with wrapper system:
     # Register hook in .claude/settings.json:
     {
@@ -17,7 +14,7 @@ Usage with wrapper system:
         "Stop": [{
           "hooks": [{
             "type": "command",
-            "command": ".deepwork/hooks/claude_hook.sh rules_check"
+            "command": ".deepwork/hooks/claude_hook.sh my_hook"
           }]
         }]
       }
@@ -29,7 +26,7 @@ Usage with wrapper system:
         "AfterAgent": [{
           "hooks": [{
             "type": "command",
-            "command": ".gemini/hooks/gemini_hook.sh rules_check"
+            "command": ".gemini/hooks/gemini_hook.sh my_hook"
           }]
         }]
       }

deepwork/hooks/check_version.sh

@@ -10,17 +10,58 @@
 #
 # Uses hookSpecificOutput.additionalContext to pass messages to Claude's context.
 
+# ============================================================================
+# READ STDIN INPUT
+# ============================================================================
+# SessionStart hooks receive JSON input via stdin with session information.
+# We need to read this to check the session source (startup, resume, clear).
+
+HOOK_INPUT=""
+if [ ! -t 0 ]; then
+    HOOK_INPUT=$(cat)
+fi
+
+# ============================================================================
+# SKIP NON-INITIAL SESSIONS
+# ============================================================================
+# SessionStart hooks can be triggered for different reasons:
+# - "startup": Initial session start (user ran `claude` or similar)
+# - "resume": Session resumed (user ran `claude --resume`)
+# - "clear": Context was cleared/compacted
+#
+# We only want to run the full check on initial startup. For resumed or
+# compacted sessions, return immediately with empty JSON to avoid redundant
+# checks and noise.
+
+get_session_source() {
+    # Extract the "source" field from the JSON input
+    # Returns empty string if not found or not valid JSON
+    if [ -n "$HOOK_INPUT" ]; then
+        # Use grep and sed for simple JSON parsing (avoid jq dependency)
+        echo "$HOOK_INPUT" | grep -o '"source"[[:space:]]*:[[:space:]]*"[^"]*"' | sed 's/.*:.*"\([^"]*\)"/\1/' | head -1
+    fi
+}
+
+SESSION_SOURCE=$(get_session_source)
+
+# If source is anything other than "startup" (or empty/missing for backwards compat),
+# skip this hook entirely. Empty source means older Claude Code version that doesn't
+# send the source field - we treat that as an initial session to maintain backwards compat.
+if [ -n "$SESSION_SOURCE" ] && [ "$SESSION_SOURCE" != "startup" ]; then
+    # Non-initial session (resume, clear, etc.) - skip all checks
+    echo '{}'
+    exit 0
+fi
+
 # ============================================================================
 # DEEPWORK INSTALLATION CHECK (BLOCKING)
 # ============================================================================
-# This check runs on EVERY hook invocation (no re-entry guard) because if
-# deepwork is not installed, nothing else will work.
+# This check runs on initial session start because if deepwork is not installed,
+# nothing else will work.
 
 check_deepwork_installed() {
-    # Run 'deepwork rules clear_queue' instead of just '--version' for double utility:
-    # 1. Verifies that the 'deepwork' command is installed and directly invokable
-    # 2. Clears any stale rules from the queue, ensuring a clean slate for the session
-    if ! deepwork rules clear_queue >/dev/null 2>&1; then
+    # Run 'deepwork --version' to verify the command is installed and directly invokable
+    if ! deepwork --version >/dev/null 2>&1; then
         return 1
     fi
     return 0
@@ -36,11 +77,13 @@ print_deepwork_error() {
   ERROR: The 'deepwork' command is not available or cannot be directly invoked.
 
   DeepWork must be installed such that running 'deepwork' directly works.
-  For example, running 'deepwork rules clear_queue' should succeed.
+  For example, running 'deepwork --version' should succeed.
 
   IMPORTANT: Do NOT use 'uv run deepwork' or similar wrappers.
   The command must be directly invokable as just 'deepwork'.
 
+  To verify: 'deepwork --version' should succeed.
+
   ------------------------------------------------------------------------
   |                                                                      |
   |   Please fix your deepwork installation before proceeding.           |
@@ -70,20 +113,10 @@ if ! check_deepwork_installed; then
     exit 2  # Blocking error - prevent session from continuing
 fi
 
-# ============================================================================
-# RE-ENTRY GUARD (for version check only)
-# ============================================================================
-# SessionStart hooks can be triggered multiple times in a session (on resume,
-# clear, etc.). We only want to show the version warning once per session to
-# avoid spamming the user. We use an environment variable to track whether
-# we've already run. Note: This relies on the parent process preserving env
-# vars across hook invocations within the same session.
-if [ -n "$DEEPWORK_VERSION_CHECK_DONE" ]; then
-    # Already checked version this session, exit silently with empty JSON
-    echo '{}'
-    exit 0
-fi
-export DEEPWORK_VERSION_CHECK_DONE=1
+# Note: We previously had a re-entry guard using DEEPWORK_VERSION_CHECK_DONE
+# environment variable, but that was unreliable across session resumptions.
+# Now we use the source field in the hook input JSON to detect initial sessions
+# vs resumed/compacted sessions (see SKIP NON-INITIAL SESSIONS section above).
 
 # ============================================================================
 # MINIMUM VERSION CONFIGURATION

deepwork/mcp/__init__.py

@@ -0,0 +1,23 @@
+"""DeepWork MCP Server module.
+
+This module provides an MCP (Model Context Protocol) server that guides AI agents
+through DeepWork workflows via checkpoint calls with quality gate enforcement.
+
+The server exposes three main tools:
+- get_workflows: List all available workflows
+- start_workflow: Initialize a workflow session
+- finished_step: Report step completion and get next instructions
+
+Example usage:
+    deepwork serve --path /path/to/project
+"""
+
+
+def create_server(*args, **kwargs):  # type: ignore
+    """Lazy import to avoid loading fastmcp at module import time."""
+    from deepwork.mcp.server import create_server as _create_server
+
+    return _create_server(*args, **kwargs)
+
+
+__all__ = ["create_server"]