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

deepwork/core/doc_spec_parser.py

@@ -0,0 +1,205 @@
+"""Doc spec parser."""
+
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from deepwork.schemas.doc_spec_schema import DOC_SPEC_FRONTMATTER_SCHEMA
+from deepwork.utils.validation import ValidationError, validate_against_schema
+from deepwork.utils.yaml_utils import YAMLError, load_yaml_from_string
+
+
+class DocSpecParseError(Exception):
+    """Exception raised for doc spec parsing errors."""
+
+    pass
+
+
+@dataclass
+class QualityCriterion:
+    """Represents a single quality criterion for a doc spec."""
+
+    name: str
+    description: str
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "QualityCriterion":
+        """Create QualityCriterion from dictionary."""
+        return cls(
+            name=data["name"],
+            description=data["description"],
+        )
+
+
+@dataclass
+class DocSpec:
+    """Represents a complete doc spec (document specification)."""
+
+    # Required fields
+    name: str
+    description: str
+    quality_criteria: list[QualityCriterion]
+
+    # Optional fields
+    path_patterns: list[str] = field(default_factory=list)
+    target_audience: str | None = None
+    frequency: str | None = None
+
+    # The example document body (markdown content after frontmatter)
+    example_document: str = ""
+
+    # Source file path for reference
+    source_file: Path | None = None
+
+    @classmethod
+    def from_dict(
+        cls, data: dict[str, Any], example_document: str = "", source_file: Path | None = None
+    ) -> "DocSpec":
+        """
+        Create DocSpec from dictionary.
+
+        Args:
+            data: Parsed YAML frontmatter data
+            example_document: The markdown body content (example document)
+            source_file: Path to the source doc spec file
+
+        Returns:
+            DocSpec instance
+        """
+        return cls(
+            name=data["name"],
+            description=data["description"],
+            quality_criteria=[QualityCriterion.from_dict(qc) for qc in data["quality_criteria"]],
+            path_patterns=data.get("path_patterns", []),
+            target_audience=data.get("target_audience"),
+            frequency=data.get("frequency"),
+            example_document=example_document,
+            source_file=source_file,
+        )
+
+
+# Backward compatibility alias
+DocumentTypeDefinition = DocSpec
+
+
+def _parse_frontmatter_markdown(content: str) -> tuple[dict[str, Any], str]:
+    """
+    Parse frontmatter from markdown content.
+
+    Expects format:
+    ---
+    key: value
+    ---
+    markdown body
+
+    Args:
+        content: Full file content
+
+    Returns:
+        Tuple of (frontmatter dict, body content)
+
+    Raises:
+        DocSpecParseError: If frontmatter is missing or invalid
+    """
+    # Match frontmatter pattern: starts with ---, ends with ---
+    # The (.*?) captures frontmatter content, which may be empty
+    pattern = r"^---[ \t]*\n(.*?)^---[ \t]*\n?(.*)"
+    match = re.match(pattern, content.strip(), re.DOTALL | re.MULTILINE)
+
+    if not match:
+        raise DocSpecParseError(
+            "Doc spec file must have YAML frontmatter (content between --- markers)"
+        )
+
+    frontmatter_yaml = match.group(1)
+    body = match.group(2).strip() if match.group(2) else ""
+
+    try:
+        frontmatter = load_yaml_from_string(frontmatter_yaml)
+    except YAMLError as e:
+        raise DocSpecParseError(f"Failed to parse doc spec frontmatter: {e}") from e
+
+    if frontmatter is None:
+        raise DocSpecParseError("Doc spec frontmatter is empty")
+
+    return frontmatter, body
+
+
+def parse_doc_spec_file(filepath: Path | str) -> DocSpec:
+    """
+    Parse a doc spec file.
+
+    Args:
+        filepath: Path to the doc spec file (markdown with YAML frontmatter)
+
+    Returns:
+        Parsed DocSpec
+
+    Raises:
+        DocSpecParseError: If parsing fails or validation errors occur
+    """
+    filepath = Path(filepath)
+
+    if not filepath.exists():
+        raise DocSpecParseError(f"Doc spec file does not exist: {filepath}")
+
+    if not filepath.is_file():
+        raise DocSpecParseError(f"Doc spec path is not a file: {filepath}")
+
+    # Read content
+    try:
+        content = filepath.read_text(encoding="utf-8")
+    except Exception as e:
+        raise DocSpecParseError(f"Failed to read doc spec file: {e}") from e
+
+    # Parse frontmatter and body
+    frontmatter, body = _parse_frontmatter_markdown(content)
+
+    # Validate against schema
+    try:
+        validate_against_schema(frontmatter, DOC_SPEC_FRONTMATTER_SCHEMA)
+    except ValidationError as e:
+        raise DocSpecParseError(f"Doc spec validation failed: {e}") from e
+
+    # Create doc spec instance
+    return DocSpec.from_dict(frontmatter, body, filepath)
+
+
+def load_doc_specs_from_directory(
+    doc_specs_dir: Path | str,
+) -> dict[str, DocSpec]:
+    """
+    Load all doc spec files from a directory.
+
+    Args:
+        doc_specs_dir: Path to the doc_specs directory
+
+    Returns:
+        Dictionary mapping doc spec filename (without extension) to DocSpec
+
+    Raises:
+        DocSpecParseError: If any doc spec file fails to parse
+    """
+    doc_specs_dir = Path(doc_specs_dir)
+
+    if not doc_specs_dir.exists():
+        return {}
+
+    if not doc_specs_dir.is_dir():
+        raise DocSpecParseError(f"Doc specs path is not a directory: {doc_specs_dir}")
+
+    doc_specs: dict[str, DocSpec] = {}
+
+    for doc_spec_file in doc_specs_dir.glob("*.md"):
+        # Use stem (filename without extension) as key
+        doc_spec_key = doc_spec_file.stem
+
+        try:
+            doc_spec = parse_doc_spec_file(doc_spec_file)
+            doc_specs[doc_spec_key] = doc_spec
+        except DocSpecParseError:
+            # Re-raise with context about which file failed
+            raise
+
+    return doc_specs

deepwork/core/generator.py

@@ -6,6 +6,11 @@ from typing import Any
 from jinja2 import Environment, FileSystemLoader, TemplateNotFound
 
 from deepwork.core.adapters import AgentAdapter, SkillLifecycleHook
+from deepwork.core.doc_spec_parser import (
+    DocSpec,
+    DocSpecParseError,
+    parse_doc_spec_file,
+)
 from deepwork.core.parser import JobDefinition, Step
 from deepwork.schemas.job_schema import LIFECYCLE_HOOK_EVENTS
 from deepwork.utils.fs import safe_read, safe_write
@@ -37,6 +42,35 @@ class SkillGenerator:
         if not self.templates_dir.exists():
             raise GeneratorError(f"Templates directory not found: {self.templates_dir}")
 
+        # Cache for loaded doc specs (keyed by absolute file path)
+        self._doc_spec_cache: dict[Path, DocSpec] = {}
+
+    def _load_doc_spec(self, project_root: Path, doc_spec_path: str) -> DocSpec | None:
+        """
+        Load a doc spec by file path with caching.
+
+        Args:
+            project_root: Path to project root
+            doc_spec_path: Relative path to doc spec file (e.g., ".deepwork/doc_specs/report.md")
+
+        Returns:
+            DocSpec if file exists and parses, None otherwise
+        """
+        full_path = project_root / doc_spec_path
+        if full_path in self._doc_spec_cache:
+            return self._doc_spec_cache[full_path]
+
+        if not full_path.exists():
+            return None
+
+        try:
+            doc_spec = parse_doc_spec_file(full_path)
+        except DocSpecParseError:
+            return None
+
+        self._doc_spec_cache[full_path] = doc_spec
+        return doc_spec
+
     def _get_jinja_env(self, adapter: AgentAdapter) -> Environment:
         """
         Get Jinja2 environment for an adapter.
@@ -113,7 +147,12 @@ class SkillGenerator:
         return hook_ctx
 
     def _build_step_context(
-        self, job: JobDefinition, step: Step, step_index: int, adapter: AgentAdapter
+        self,
+        job: JobDefinition,
+        step: Step,
+        step_index: int,
+        adapter: AgentAdapter,
+        project_root: Path | None = None,
     ) -> dict[str, Any]:
         """
         Build template context for a step.
@@ -123,6 +162,7 @@ class SkillGenerator:
             step: Step to generate context for
             step_index: Index of step in job (0-based)
             adapter: Agent adapter for platform-specific hook name mapping
+            project_root: Optional project root for loading doc specs
 
         Returns:
             Template context dictionary
@@ -173,11 +213,40 @@ class SkillGenerator:
                     if hook_contexts:
                         hooks[platform_event_name] = hook_contexts
 
+        # Claude Code has separate Stop and SubagentStop events. When a Stop hook
+        # is defined, also register it for SubagentStop so it triggers for both
+        # the main agent and subagents.
+        if "Stop" in hooks:
+            hooks["SubagentStop"] = hooks["Stop"]
+
         # Backward compatibility: stop_hooks is after_agent hooks
         stop_hooks = hooks.get(
             adapter.get_platform_hook_name(SkillLifecycleHook.AFTER_AGENT) or "Stop", []
         )
 
+        # Build rich outputs context with doc spec information
+        outputs_context = []
+        for output in step.outputs:
+            output_ctx: dict[str, Any] = {
+                "file": output.file,
+                "has_doc_spec": output.has_doc_spec(),
+            }
+            if output.has_doc_spec() and output.doc_spec and project_root:
+                doc_spec = self._load_doc_spec(project_root, output.doc_spec)
+                if doc_spec:
+                    output_ctx["doc_spec"] = {
+                        "path": output.doc_spec,
+                        "name": doc_spec.name,
+                        "description": doc_spec.description,
+                        "target_audience": doc_spec.target_audience,
+                        "quality_criteria": [
+                            {"name": c.name, "description": c.description}
+                            for c in doc_spec.quality_criteria
+                        ],
+                        "example_document": doc_spec.example_document,
+                    }
+            outputs_context.append(output_ctx)
+
         return {
             "job_name": job.name,
             "job_version": job.version,
@@ -192,7 +261,7 @@ class SkillGenerator:
             "instructions_content": instructions_content,
             "user_inputs": user_inputs,
             "file_inputs": file_inputs,
-            "outputs": step.outputs,
+            "outputs": outputs_context,
             "dependencies": step.dependencies,
             "next_step": next_step,
             "prev_step": prev_step,
@@ -315,6 +384,7 @@ class SkillGenerator:
         step: Step,
         adapter: AgentAdapter,
         output_dir: Path | str,
+        project_root: Path | str | None = None,
     ) -> Path:
         """
         Generate skill file for a single step.
@@ -324,6 +394,7 @@ class SkillGenerator:
             step: Step to generate skill for
             adapter: Agent adapter for the target platform
             output_dir: Directory to write skill file to
+            project_root: Optional project root for loading doc specs (defaults to output_dir)
 
         Returns:
             Path to generated skill file
@@ -332,6 +403,7 @@ class SkillGenerator:
             GeneratorError: If generation fails
         """
         output_dir = Path(output_dir)
+        project_root_path = Path(project_root) if project_root else output_dir
 
         # Create skills subdirectory if needed
         skills_dir = output_dir / adapter.skills_dir
@@ -344,7 +416,7 @@ class SkillGenerator:
             raise GeneratorError(f"Step '{step.id}' not found in job '{job.name}'") from e
 
         # Build context (include exposed for template user-invocable setting)
-        context = self._build_step_context(job, step, step_index, adapter)
+        context = self._build_step_context(job, step, step_index, adapter, project_root_path)
         context["exposed"] = step.exposed
 
         # Load and render template
@@ -378,6 +450,7 @@ class SkillGenerator:
         job: JobDefinition,
         adapter: AgentAdapter,
         output_dir: Path | str,
+        project_root: Path | str | None = None,
     ) -> list[Path]:
         """
         Generate all skill files for a job: meta-skill and step skills.
@@ -386,6 +459,7 @@ class SkillGenerator:
             job: Job definition
             adapter: Agent adapter for the target platform
             output_dir: Directory to write skill files to
+            project_root: Optional project root for loading doc specs (defaults to output_dir)
 
         Returns:
             List of paths to generated skill files (meta-skill first, then steps)
@@ -394,6 +468,7 @@ class SkillGenerator:
             GeneratorError: If generation fails
         """
         skill_paths = []
+        project_root_path = Path(project_root) if project_root else Path(output_dir)
 
         # Generate meta-skill first (job-level entry point)
         meta_skill_path = self.generate_meta_skill(job, adapter, output_dir)
@@ -401,7 +476,7 @@ class SkillGenerator:
 
         # Generate step skills
         for step in job.steps:
-            skill_path = self.generate_step_skill(job, step, adapter, output_dir)
+            skill_path = self.generate_step_skill(job, step, adapter, output_dir, project_root_path)
             skill_paths.append(skill_path)
 
         return skill_paths

deepwork/core/hooks_syncer.py

@@ -35,8 +35,10 @@ class HookEntry:
             Command string to execute
         """
         if self.module:
-            # Python module - run directly with python -m
-            return f"python -m {self.module}"
+            # Python module - use deepwork hook CLI for portability
+            # Extract hook name from module path (e.g., "deepwork.hooks.rules_check" -> "rules_check")
+            hook_name = self.module.rsplit(".", 1)[-1]
+            return f"deepwork hook {hook_name}"
         elif self.script:
             # Script path is: .deepwork/jobs/{job_name}/hooks/{script}
             script_path = self.job_dir / "hooks" / self.script
@@ -187,6 +189,17 @@ def merge_hooks_for_platform(
                 if not _hook_already_present(merged[event], command):
                     merged[event].append(hook_config)
 
+    # Claude Code has separate Stop and SubagentStop events. When a Stop hook
+    # is defined, also register it for SubagentStop so it triggers for both
+    # the main agent and subagents.
+    if "Stop" in merged:
+        if "SubagentStop" not in merged:
+            merged["SubagentStop"] = []
+        for hook_config in merged["Stop"]:
+            command = hook_config.get("hooks", [{}])[0].get("command", "")
+            if not _hook_already_present(merged["SubagentStop"], command):
+                merged["SubagentStop"].append(hook_config)
+
     return merged
 
 

deepwork/core/parser.py

@@ -46,6 +46,34 @@ class StepInput:
         )
 
 
+@dataclass
+class OutputSpec:
+    """Represents a step output specification, optionally with doc spec reference."""
+
+    file: str
+    doc_spec: str | None = None
+
+    def has_doc_spec(self) -> bool:
+        """Check if this output has a doc spec reference."""
+        return self.doc_spec is not None
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any] | str) -> "OutputSpec":
+        """
+        Create OutputSpec from dictionary or string.
+
+        Supports both formats:
+        - String: "output.md" -> OutputSpec(file="output.md")
+        - Dict: {"file": "output.md", "doc_spec": ".deepwork/doc_specs/report.md"}
+        """
+        if isinstance(data, str):
+            return cls(file=data)
+        return cls(
+            file=data["file"],
+            doc_spec=data.get("doc_spec"),
+        )
+
+
 @dataclass
 class HookAction:
     """Represents a hook action configuration.
@@ -101,7 +129,7 @@ class Step:
     description: str
     instructions_file: str
     inputs: list[StepInput] = field(default_factory=list)
-    outputs: list[str] = field(default_factory=list)
+    outputs: list[OutputSpec] = field(default_factory=list)
     dependencies: list[str] = field(default_factory=list)
 
     # New: hooks dict mapping lifecycle event names to HookAction lists
@@ -147,7 +175,7 @@ class Step:
             description=data["description"],
             instructions_file=data["instructions_file"],
             inputs=[StepInput.from_dict(inp) for inp in data.get("inputs", [])],
-            outputs=data["outputs"],
+            outputs=[OutputSpec.from_dict(out) for out in data["outputs"]],
             dependencies=data.get("dependencies", []),
             hooks=hooks,
             exposed=data.get("exposed", False),
@@ -246,6 +274,40 @@ class JobDefinition:
                             f"but '{inp.from_step}' is not in dependencies"
                         )
 
+    def validate_doc_spec_references(self, project_root: Path) -> None:
+        """
+        Validate that doc spec references in outputs point to existing files.
+
+        Args:
+            project_root: Path to the project root directory
+
+        Raises:
+            ParseError: If doc spec references are invalid
+        """
+        for step in self.steps:
+            for output in step.outputs:
+                if output.has_doc_spec():
+                    doc_spec_file = project_root / output.doc_spec
+                    if not doc_spec_file.exists():
+                        raise ParseError(
+                            f"Step '{step.id}' references non-existent doc spec "
+                            f"'{output.doc_spec}'. Expected file at {doc_spec_file}"
+                        )
+
+    def get_doc_spec_references(self) -> list[str]:
+        """
+        Get all unique doc spec file paths referenced in this job's outputs.
+
+        Returns:
+            List of doc spec file paths (e.g., ".deepwork/doc_specs/report.md")
+        """
+        doc_spec_refs = set()
+        for step in self.steps:
+            for output in step.outputs:
+                if output.has_doc_spec() and output.doc_spec:
+                    doc_spec_refs.add(output.doc_spec)
+        return list(doc_spec_refs)
+
     @classmethod
     def from_dict(cls, data: dict[str, Any], job_dir: Path) -> "JobDefinition":
         """

deepwork/hooks/__init__.py

@@ -17,7 +17,7 @@ Usage with wrapper system:
         "Stop": [{
           "hooks": [{
             "type": "command",
-            "command": ".deepwork/hooks/claude_hook.sh deepwork.hooks.rules_check"
+            "command": ".deepwork/hooks/claude_hook.sh rules_check"
           }]
         }]
       }
@@ -29,12 +29,15 @@ Usage with wrapper system:
         "AfterAgent": [{
           "hooks": [{
             "type": "command",
-            "command": ".gemini/hooks/gemini_hook.sh deepwork.hooks.rules_check"
+            "command": ".gemini/hooks/gemini_hook.sh rules_check"
           }]
         }]
       }
     }
 
+The shell wrappers call `deepwork hook <hook_name>` which works regardless
+of how deepwork was installed (pipx, uv, nix flake, etc.).
+
 Writing custom hooks:
     from deepwork.hooks.wrapper import (
         HookInput,
@@ -50,10 +53,13 @@ Writing custom hooks:
                 return HookOutput(decision="block", reason="Complete X first")
         return HookOutput()
 
-    if __name__ == "__main__":
+    def main():
         import os, sys
         platform = Platform(os.environ.get("DEEPWORK_HOOK_PLATFORM", "claude"))
         sys.exit(run_hook(my_hook, platform))
+
+    if __name__ == "__main__":
+        main()
 """
 
 from deepwork.hooks.wrapper import (