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

deepwork/__init__.py

@@ -1,6 +1,6 @@
 """DeepWork - Framework for enabling AI agents to perform complex, multi-step work tasks."""
 
-__version__ = "0.1.0"
+__version__ = "0.7.0"
 __author__ = "DeepWork Contributors"
 
 __all__ = [

deepwork/cli/hook.py

@@ -5,7 +5,6 @@ instead of `python -m deepwork.hooks.*`, which works regardless of how
 deepwork was installed (flake, pipx, uv, etc.).
 
 Usage:
-    deepwork hook rules_check
     deepwork hook <hook_name>
 
 This is meant to be called from hook wrapper scripts (claude_hook.sh, gemini_hook.sh).
@@ -32,14 +31,14 @@ def hook(hook_name: str) -> None:
     """
     Run a DeepWork hook by name.
 
-    HOOK_NAME: Name of the hook to run (e.g., 'rules_check')
+    HOOK_NAME: Name of the hook to run (e.g., 'check_version')
 
     This command imports and runs the hook module from deepwork.hooks.{hook_name}.
     The hook receives stdin input and outputs to stdout, following the hook protocol.
 
     Examples:
-        deepwork hook rules_check
-        echo '{}' | deepwork hook rules_check
+        deepwork hook check_version
+        echo '{}' | deepwork hook my_hook
     """
     try:
         # Import the hook module

deepwork/cli/install.py

@@ -21,6 +21,39 @@ class InstallError(Exception):
     pass
 
 
+def _install_schemas(schemas_dir: Path, project_path: Path) -> None:
+    """
+    Install JSON schemas to the project's .deepwork/schemas directory.
+
+    Args:
+        schemas_dir: Path to .deepwork/schemas directory
+        project_path: Path to project root (for relative path display)
+
+    Raises:
+        InstallError: If installation fails
+    """
+    # Find the source schemas directory
+    source_schemas_dir = Path(__file__).parent.parent / "schemas"
+
+    if not source_schemas_dir.exists():
+        raise InstallError(
+            f"Schemas directory not found at {source_schemas_dir}. "
+            "DeepWork installation may be corrupted."
+        )
+
+    # Copy JSON schema files
+    try:
+        for schema_file in source_schemas_dir.glob("*.json"):
+            target_file = schemas_dir / schema_file.name
+            shutil.copy(schema_file, target_file)
+            fix_permissions(target_file)
+            console.print(
+                f"  [green]✓[/green] Installed schema {schema_file.name} ({target_file.relative_to(project_path)})"
+            )
+    except Exception as e:
+        raise InstallError(f"Failed to install schemas: {e}") from e
+
+
 def _inject_standard_job(job_name: str, jobs_dir: Path, project_path: Path) -> None:
     """
     Inject a standard job definition into the project.
@@ -88,20 +121,6 @@ def _inject_deepwork_jobs(jobs_dir: Path, project_path: Path) -> None:
     _inject_standard_job("deepwork_jobs", jobs_dir, project_path)
 
 
-def _inject_deepwork_rules(jobs_dir: Path, project_path: Path) -> None:
-    """
-    Inject the deepwork_rules job definition into the project.
-
-    Args:
-        jobs_dir: Path to .deepwork/jobs directory
-        project_path: Path to project root (for relative path display)
-
-    Raises:
-        InstallError: If injection fails
-    """
-    _inject_standard_job("deepwork_rules", jobs_dir, project_path)
-
-
 def _create_deepwork_gitignore(deepwork_dir: Path) -> None:
     """
     Create .gitignore file in .deepwork/ directory.
@@ -149,89 +168,6 @@ def _create_tmp_directory(deepwork_dir: Path) -> None:
         )
 
 
-def _create_rules_directory(project_path: Path) -> bool:
-    """
-    Create the v2 rules directory structure with example templates.
-
-    Creates .deepwork/rules/ with example rule files that users can customize.
-    Only creates the directory if it doesn't already exist.
-
-    Args:
-        project_path: Path to the project root
-
-    Returns:
-        True if the directory was created, False if it already existed
-    """
-    rules_dir = project_path / ".deepwork" / "rules"
-
-    if rules_dir.exists():
-        return False
-
-    # Create the rules directory
-    ensure_dir(rules_dir)
-
-    # Copy example rule templates from the deepwork_rules standard job
-    example_rules_dir = Path(__file__).parent.parent / "standard_jobs" / "deepwork_rules" / "rules"
-
-    if example_rules_dir.exists():
-        # Copy all .example files
-        for example_file in example_rules_dir.glob("*.md.example"):
-            dest_file = rules_dir / example_file.name
-            shutil.copy(example_file, dest_file)
-            # Fix permissions for copied rule template
-            fix_permissions(dest_file)
-
-    # Create a README file explaining the rules system
-    readme_content = """# DeepWork Rules
-
-Rules are automated guardrails that trigger when specific files change during
-AI agent sessions. They help ensure documentation stays current, security reviews
-happen, and team guidelines are followed.
-
-## Getting Started
-
-1. Copy an example file and rename it (remove the `.example` suffix):
-   ```
-   cp readme-documentation.md.example readme-documentation.md
-   ```
-
-2. Edit the file to match your project's patterns
-
-3. The rule will automatically trigger when matching files change
-
-## Rule Format
-
-Rules use YAML frontmatter in markdown files:
-
-```markdown
----
-name: Rule Name
-trigger: "pattern/**/*"
-safety: "optional/pattern"
----
-Instructions in markdown here.
-```
-
-## Detection Modes
-
-- **trigger/safety**: Fire when trigger matches, unless safety also matches
-- **set**: Bidirectional file correspondence (e.g., source + test)
-- **pair**: Directional correspondence (e.g., API code -> docs)
-
-## Documentation
-
-See `doc/rules_syntax.md` in the DeepWork repository for full syntax documentation.
-
-## Creating Rules Interactively
-
-Use `/deepwork_rules.define` to create new rules with guidance.
-"""
-    readme_path = rules_dir / "README.md"
-    readme_path.write_text(readme_content)
-
-    return True
-
-
 class DynamicChoice(click.Choice):
     """A Click Choice that gets its values dynamically from AgentAdapter."""
 
@@ -346,30 +282,29 @@ def _install_deepwork(platform_name: str | None, project_path: Path) -> None:
     deepwork_dir = project_path / ".deepwork"
     jobs_dir = deepwork_dir / "jobs"
     doc_specs_dir = deepwork_dir / "doc_specs"
+    schemas_dir = deepwork_dir / "schemas"
     ensure_dir(deepwork_dir)
     ensure_dir(jobs_dir)
     ensure_dir(doc_specs_dir)
+    ensure_dir(schemas_dir)
     console.print(f"  [green]✓[/green] Created {deepwork_dir.relative_to(project_path)}/")
 
-    # Step 3b: Inject standard jobs (core job definitions)
+    # Step 3b: Install schemas
+    console.print("[yellow]→[/yellow] Installing schemas...")
+    _install_schemas(schemas_dir, project_path)
+
+    # Step 3c: Inject standard jobs (core job definitions)
     console.print("[yellow]→[/yellow] Installing core job definitions...")
     _inject_deepwork_jobs(jobs_dir, project_path)
-    _inject_deepwork_rules(jobs_dir, project_path)
 
-    # Step 3c: Create .gitignore for temporary files
+    # Step 3d: Create .gitignore for temporary files
     _create_deepwork_gitignore(deepwork_dir)
     console.print("  [green]✓[/green] Created .deepwork/.gitignore")
 
-    # Step 3d: Create tmp directory with .gitkeep file for version control
+    # Step 3e: Create tmp directory with .gitkeep file for version control
     _create_tmp_directory(deepwork_dir)
     console.print("  [green]✓[/green] Created .deepwork/tmp/.gitkeep")
 
-    # Step 3e: Create rules directory with v2 templates
-    if _create_rules_directory(project_path):
-        console.print("  [green]✓[/green] Created .deepwork/rules/ with example templates")
-    else:
-        console.print("  [dim]•[/dim] .deepwork/rules/ already exists")
-
     # Step 4: Load or create config.yml
     console.print("[yellow]→[/yellow] Updating configuration...")
     config_file = deepwork_dir / "config.yml"
@@ -402,7 +337,17 @@ def _install_deepwork(platform_name: str | None, project_path: Path) -> None:
     save_yaml(config_file, config_data)
     console.print(f"  [green]✓[/green] Updated {config_file.relative_to(project_path)}")
 
-    # Step 5: Run sync to generate skills
+    # Step 5: Register MCP server for each platform
+    console.print("[yellow]→[/yellow] Registering MCP server...")
+    for adapter in detected_adapters:
+        if adapter.register_mcp_server(project_path):
+            console.print(f"  [green]✓[/green] Registered MCP server for {adapter.display_name}")
+        else:
+            console.print(
+                f"  [dim]•[/dim] MCP server already registered for {adapter.display_name}"
+            )
+
+    # Step 6: Run sync to generate skills
     console.print()
     console.print("[yellow]→[/yellow] Running sync to generate skills...")
     console.print()
@@ -410,18 +355,26 @@ def _install_deepwork(platform_name: str | None, project_path: Path) -> None:
     from deepwork.cli.sync import sync_skills
 
     try:
-        sync_skills(project_path)
+        sync_result = sync_skills(project_path)
     except Exception as e:
         raise InstallError(f"Failed to sync skills: {e}") from e
 
-    # Success message
+    # Success or warning message
     console.print()
     platform_names = ", ".join(a.display_name for a in detected_adapters)
-    console.print(
-        f"[bold green]✓ DeepWork installed successfully for {platform_names}![/bold green]"
-    )
-    console.print()
-    console.print("[bold]Next steps:[/bold]")
-    console.print("  1. Start your agent CLI (ex. [cyan]claude[/cyan] or [cyan]gemini[/cyan])")
-    console.print("  2. Define your first job using the command [cyan]/deepwork_jobs.define[/cyan]")
+
+    if sync_result.has_warnings:
+        console.print("[bold yellow]⚠ You should repair your DeepWork install[/bold yellow]")
+        console.print()
+        console.print("[bold]To fix issues:[/bold]")
+        console.print("  1. Start your agent CLI (ex. [cyan]claude[/cyan] or [cyan]gemini[/cyan])")
+        console.print("  2. Run [cyan]/deepwork repair[/cyan]")
+    else:
+        console.print(
+            f"[bold green]✓ DeepWork installed successfully for {platform_names}![/bold green]"
+        )
+        console.print()
+        console.print("[bold]Next steps:[/bold]")
+        console.print("  1. Start your agent CLI (ex. [cyan]claude[/cyan] or [cyan]gemini[/cyan])")
+        console.print("  2. Define your first job using the command [cyan]/deepwork_jobs[/cyan]")
     console.print()

deepwork/cli/main.py

@@ -16,13 +16,13 @@ def cli() -> None:
 # Import commands
 from deepwork.cli.hook import hook  # noqa: E402
 from deepwork.cli.install import install  # noqa: E402
-from deepwork.cli.rules import rules  # noqa: E402
+from deepwork.cli.serve import serve  # noqa: E402
 from deepwork.cli.sync import sync  # noqa: E402
 
 cli.add_command(install)
 cli.add_command(sync)
 cli.add_command(hook)
-cli.add_command(rules)
+cli.add_command(serve)
 
 
 if __name__ == "__main__":

deepwork/cli/serve.py

@@ -0,0 +1,133 @@
+"""Serve command for DeepWork MCP server."""
+
+from pathlib import Path
+
+import click
+from rich.console import Console
+
+from deepwork.utils.yaml_utils import load_yaml
+
+console = Console()
+
+
+class ServeError(Exception):
+    """Exception raised for serve errors."""
+
+    pass
+
+
+def _load_config(project_path: Path) -> dict:
+    """Load DeepWork config from project.
+
+    Args:
+        project_path: Path to project root
+
+    Returns:
+        Config dictionary
+
+    Raises:
+        ServeError: If config not found or invalid
+    """
+    config_file = project_path / ".deepwork" / "config.yml"
+    if not config_file.exists():
+        raise ServeError(f"DeepWork not installed in {project_path}. Run 'deepwork install' first.")
+
+    config = load_yaml(config_file)
+    if config is None:
+        config = {}
+
+    return config
+
+
+@click.command()
+@click.option(
+    "--path",
+    type=click.Path(exists=True, file_okay=False, path_type=Path),
+    default=".",
+    help="Path to project directory (default: current directory)",
+)
+@click.option(
+    "--no-quality-gate",
+    is_flag=True,
+    default=False,
+    help="Disable quality gate evaluation",
+)
+@click.option(
+    "--transport",
+    type=click.Choice(["stdio", "sse"]),
+    default="stdio",
+    help="MCP transport protocol (default: stdio)",
+)
+@click.option(
+    "--port",
+    type=int,
+    default=8000,
+    help="Port for SSE transport (default: 8000)",
+)
+def serve(
+    path: Path,
+    no_quality_gate: bool,
+    transport: str,
+    port: int,
+) -> None:
+    """Start the DeepWork MCP server.
+
+    Exposes workflow management tools to AI agents via MCP protocol.
+    By default uses stdio transport for local integration with Claude Code.
+
+    Quality gate is enabled by default and uses Claude Code to evaluate
+    step outputs against quality criteria.
+
+    Examples:
+
+        # Start server for current directory
+        deepwork serve
+
+        # Start with quality gate disabled
+        deepwork serve --no-quality-gate
+
+        # Start for a specific project
+        deepwork serve --path /path/to/project
+    """
+    try:
+        _serve_mcp(path, not no_quality_gate, transport, port)
+    except ServeError as e:
+        console.print(f"[red]Error:[/red] {e}")
+        raise click.Abort() from e
+    except Exception as e:
+        console.print(f"[red]Unexpected error:[/red] {e}")
+        raise
+
+
+def _serve_mcp(
+    project_path: Path,
+    enable_quality_gate: bool,
+    transport: str,
+    port: int,
+) -> None:
+    """Start the MCP server.
+
+    Args:
+        project_path: Path to project directory
+        enable_quality_gate: Whether to enable quality gate evaluation
+        transport: Transport protocol (stdio or sse)
+        port: Port for SSE transport
+
+    Raises:
+        ServeError: If server fails to start
+    """
+    # Validate project has DeepWork installed
+    _load_config(project_path)
+
+    # Create and run server
+    from deepwork.mcp.server import create_server
+
+    server = create_server(
+        project_root=project_path,
+        enable_quality_gate=enable_quality_gate,
+    )
+
+    if transport == "stdio":
+        server.run(transport="stdio")
+    else:
+        server.run(transport="sse", port=port)

deepwork/cli/sync.py

@@ -1,5 +1,6 @@
 """Sync command for DeepWork CLI."""
 
+from dataclasses import dataclass, field
 from pathlib import Path
 
 import click
@@ -22,6 +23,21 @@ class SyncError(Exception):
     pass
 
 
+@dataclass
+class SyncResult:
+    """Result of a sync operation."""
+
+    platforms_synced: int = 0
+    skills_generated: int = 0
+    hooks_synced: int = 0
+    warnings: list[str] = field(default_factory=list)
+
+    @property
+    def has_warnings(self) -> bool:
+        """Return True if there were any warnings during sync."""
+        return len(self.warnings) > 0
+
+
 @click.command()
 @click.option(
     "--path",
@@ -46,13 +62,16 @@ def sync(path: Path) -> None:
         raise
 
 
-def sync_skills(project_path: Path) -> None:
+def sync_skills(project_path: Path) -> SyncResult:
     """
     Sync skills to all configured platforms.
 
     Args:
         project_path: Path to project directory
 
+    Returns:
+        SyncResult with statistics and any warnings
+
     Raises:
         SyncError: If sync fails
     """
@@ -80,6 +99,43 @@ def sync_skills(project_path: Path) -> None:
 
     console.print("[bold cyan]Syncing DeepWork Skills[/bold cyan]\n")
 
+    # Generate /deepwork skill FIRST for all platforms (before parsing jobs)
+    # This ensures the skill is available even if some jobs fail to parse
+    generator = SkillGenerator()
+    result = SyncResult()
+    platform_adapters: list[AgentAdapter] = []
+    all_skill_paths_by_platform: dict[str, list[Path]] = {}
+
+    console.print("[yellow]→[/yellow] Generating /deepwork skill...")
+    for platform_name in platforms:
+        try:
+            adapter_cls = AgentAdapter.get(platform_name)
+        except Exception:
+            warning = f"Unknown platform '{platform_name}', skipping"
+            console.print(f"  [yellow]⚠[/yellow] {warning}")
+            result.warnings.append(warning)
+            continue
+
+        adapter = adapter_cls(project_path)
+        platform_adapters.append(adapter)
+
+        platform_dir = project_path / adapter.config_dir
+        skills_dir = platform_dir / adapter.skills_dir
+        ensure_dir(skills_dir)
+
+        all_skill_paths: list[Path] = []
+        try:
+            deepwork_skill_path = generator.generate_deepwork_skill(adapter, platform_dir)
+            all_skill_paths.append(deepwork_skill_path)
+            result.skills_generated += 1
+            console.print(f"  [green]✓[/green] {adapter.display_name}: deepwork (MCP entry point)")
+        except Exception as e:
+            warning = f"{adapter.display_name}: Failed to generate /deepwork skill: {e}"
+            console.print(f"  [red]✗[/red] {warning}")
+            result.warnings.append(warning)
+
+        all_skill_paths_by_platform[platform_name] = all_skill_paths
+
     # Discover jobs
     jobs_dir = deepwork_dir / "jobs"
     if not jobs_dir.exists():
@@ -87,7 +143,7 @@ def sync_skills(project_path: Path) -> None:
     else:
         job_dirs = [d for d in jobs_dir.iterdir() if d.is_dir() and (d / "job.yml").exists()]
 
-    console.print(f"[yellow]→[/yellow] Found {len(job_dirs)} job(s) to sync")
+    console.print(f"\n[yellow]→[/yellow] Found {len(job_dirs)} job(s) to sync")
 
     # Parse all jobs
     jobs = []
@@ -98,68 +154,48 @@ def sync_skills(project_path: Path) -> None:
             jobs.append(job_def)
             console.print(f"  [green]✓[/green] Loaded {job_def.name} v{job_def.version}")
         except Exception as e:
-            console.print(f"  [red]✗[/red] Failed to load {job_dir.name}: {e}")
+            warning = f"Failed to load {job_dir.name}: {e}"
+            console.print(f"  [red]✗[/red] {warning}")
             failed_jobs.append((job_dir.name, str(e)))
+            result.warnings.append(warning)
 
-    # Fail early if any jobs failed to parse
+    # Warn about failed jobs but continue (skill already installed)
     if failed_jobs:
         console.print()
-        console.print("[bold red]Sync aborted due to job parsing errors:[/bold red]")
+        console.print("[bold yellow]Warning: Some jobs failed to parse:[/bold yellow]")
         for job_name, error in failed_jobs:
             console.print(f"  • {job_name}: {error}")
-        raise SyncError(f"Failed to parse {len(failed_jobs)} job(s)")
+        console.print(
+            "[dim]The /deepwork skill is installed. Fix the job errors and run 'deepwork sync' again.[/dim]"
+        )
 
-    # Collect hooks from all jobs
+    # Collect hooks from jobs (hooks collection is independent of job.yml parsing)
     job_hooks_list = collect_job_hooks(jobs_dir)
     if job_hooks_list:
-        console.print(f"[yellow]→[/yellow] Found {len(job_hooks_list)} job(s) with hooks")
-
-    # Sync each platform
-    generator = SkillGenerator()
-    stats = {"platforms": 0, "skills": 0, "hooks": 0}
-    synced_adapters: list[AgentAdapter] = []
-
-    for platform_name in platforms:
-        try:
-            adapter_cls = AgentAdapter.get(platform_name)
-        except Exception:
-            console.print(f"[yellow]⚠[/yellow] Unknown platform '{platform_name}', skipping")
-            continue
+        console.print(f"\n[yellow]→[/yellow] Found {len(job_hooks_list)} job(s) with hooks")
 
-        adapter = adapter_cls(project_path)
-        console.print(f"\n[yellow]→[/yellow] Syncing to {adapter.display_name}...")
-
-        platform_dir = project_path / adapter.config_dir
-        skills_dir = platform_dir / adapter.skills_dir
-
-        # Create skills directory
-        ensure_dir(skills_dir)
+    # Sync hooks and permissions for each platform
+    for adapter in platform_adapters:
+        console.print(
+            f"\n[yellow]→[/yellow] Syncing hooks and permissions to {adapter.display_name}..."
+        )
 
-        # Generate skills for all jobs
-        all_skill_paths: list[Path] = []
-        if jobs:
-            console.print("  [dim]•[/dim] Generating skills...")
-            for job in jobs:
-                try:
-                    job_paths = generator.generate_all_skills(
-                        job, adapter, platform_dir, project_root=project_path
-                    )
-                    all_skill_paths.extend(job_paths)
-                    stats["skills"] += len(job_paths)
-                    console.print(f"    [green]✓[/green] {job.name} ({len(job_paths)} skills)")
-                except Exception as e:
-                    console.print(f"    [red]✗[/red] Failed for {job.name}: {e}")
+        # NOTE: Job skills (meta-skills and step skills) are no longer generated.
+        # The MCP server now handles workflow orchestration directly.
+        # Only the /deepwork skill is installed as the entry point.
 
         # Sync hooks to platform settings
         if job_hooks_list:
             console.print("  [dim]•[/dim] Syncing hooks...")
             try:
                 hooks_count = sync_hooks_to_platform(project_path, adapter, job_hooks_list)
-                stats["hooks"] += hooks_count
+                result.hooks_synced += hooks_count
                 if hooks_count > 0:
                     console.print(f"    [green]✓[/green] Synced {hooks_count} hook(s)")
             except Exception as e:
-                console.print(f"    [red]✗[/red] Failed to sync hooks: {e}")
+                warning = f"Failed to sync hooks: {e}"
+                console.print(f"    [red]✗[/red] {warning}")
+                result.warnings.append(warning)
 
         # Sync required permissions to platform settings
         console.print("  [dim]•[/dim] Syncing permissions...")
@@ -170,9 +206,12 @@ def sync_skills(project_path: Path) -> None:
             else:
                 console.print("    [dim]•[/dim] Base permissions already configured")
         except Exception as e:
-            console.print(f"    [red]✗[/red] Failed to sync permissions: {e}")
+            warning = f"Failed to sync permissions: {e}"
+            console.print(f"    [red]✗[/red] {warning}")
+            result.warnings.append(warning)
 
         # Add skill permissions for generated skills (if adapter supports it)
+        all_skill_paths = all_skill_paths_by_platform.get(adapter.name, [])
         if all_skill_paths and hasattr(adapter, "add_skill_permissions"):
             try:
                 skill_perms_count = adapter.add_skill_permissions(project_path, all_skill_paths)
@@ -181,10 +220,11 @@ def sync_skills(project_path: Path) -> None:
                         f"    [green]✓[/green] Added {skill_perms_count} skill permission(s)"
                     )
             except Exception as e:
-                console.print(f"    [red]✗[/red] Failed to sync skill permissions: {e}")
+                warning = f"Failed to sync skill permissions: {e}"
+                console.print(f"    [red]✗[/red] {warning}")
+                result.warnings.append(warning)
 
-        stats["platforms"] += 1
-        synced_adapters.append(adapter)
+        result.platforms_synced += 1
 
     # Summary
     console.print()
@@ -195,17 +235,12 @@ def sync_skills(project_path: Path) -> None:
     table.add_column("Metric", style="cyan")
     table.add_column("Count", style="green")
 
-    table.add_row("Platforms synced", str(stats["platforms"]))
-    table.add_row("Total skills", str(stats["skills"]))
-    if stats["hooks"] > 0:
-        table.add_row("Hooks synced", str(stats["hooks"]))
+    table.add_row("Platforms synced", str(result.platforms_synced))
+    table.add_row("Total skills", str(result.skills_generated))
+    if result.hooks_synced > 0:
+        table.add_row("Hooks synced", str(result.hooks_synced))
 
     console.print(table)
     console.print()
 
-    # Show reload instructions for each synced platform
-    if synced_adapters and stats["skills"] > 0:
-        console.print("[bold]To use the new skills:[/bold]")
-        for adapter in synced_adapters:
-            console.print(f"  [cyan]{adapter.display_name}:[/cyan] {adapter.reload_instructions}")
-        console.print()
+    return result