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

deepwork/templates/claude/skill-job-meta.md.jinja

@@ -0,0 +1,70 @@
+{#
+Template: skill-job-meta.md.jinja
+Purpose: Generates the job overview skill file for Claude Code
+
+Template Variables:
+  - job_name: string - Job identifier (e.g., "competitive_research")
+  - job_summary: string - Short one-line summary of the job
+  - job_description: string|null - Full description (optional)
+  - total_steps: int - Number of steps in the job
+  - steps: list - Array of step objects:
+      - id: string - Step identifier
+      - name: string - Human-readable step name
+      - description: string - What the step does
+      - command_name: string - Slash command (e.g., "job_name.step_id")
+      - dependencies: list[string]|null - Required prior steps
+#}
+---
+name: {{ job_name }}
+description: "{{ job_summary }}"
+---
+
+# {{ job_name }}
+
+**Multi-step workflow**: {{ job_summary }}
+
+> **CRITICAL**: Always invoke steps using the Skill tool. Never copy/paste step instructions directly.
+
+{% if job_description %}
+{{ job_description }}
+{% endif %}
+
+## Available Steps
+
+{% for step in steps %}
+{{ loop.index }}. **{{ step.id }}** - {{ step.description }}{% if step.dependencies %} (requires: {{ step.dependencies | join(', ') }}){% endif %}
+
+{% endfor %}
+
+## Execution Instructions
+
+### Step 1: Analyze Intent
+
+Parse any text following `/{{ job_name }}` to determine user intent:
+{% for step in steps %}
+- "{{ step.id }}" or related terms → start at `{{ step.command_name }}`
+{% endfor %}
+
+### Step 2: Invoke Starting Step
+
+Use the Skill tool to invoke the identified starting step:
+```
+Skill tool: {{ steps[0].command_name }}
+```
+
+### Step 3: Continue Workflow Automatically
+
+After each step completes:
+1. Check if there's a next step in the sequence
+2. Invoke the next step using the Skill tool
+3. Repeat until workflow is complete or user intervenes
+
+### Handling Ambiguous Intent
+
+If user intent is unclear, use AskUserQuestion to clarify:
+- Present available steps as numbered options
+- Let user select the starting point
+
+## Context Files
+
+- Job definition: `.deepwork/jobs/{{ job_name }}/job.yml`

deepwork/templates/claude/skill-job-step.md.jinja

@@ -0,0 +1,198 @@
+{#
+Template: skill-job-step.md.jinja
+Purpose: Generates individual step skill files for Claude Code
+
+Template Variables:
+  Job Context:
+    - job_name: string - Job identifier
+    - job_summary: string - Short job summary
+    - job_description: string|null - Full job description
+
+  Step Metadata:
+    - step_id: string - Step identifier
+    - step_description: string - What this step does
+    - step_number: int - Position in workflow (1-indexed)
+    - total_steps: int - Total steps in job
+    - is_standalone: bool - True if step can run independently
+    - exposed: bool - True if user can invoke directly (default: true)
+    - dependencies: list[string]|null - Required prior step IDs
+    - next_step: string|null - Next step ID in workflow
+    - instructions_file: string - Path to step instructions file
+
+  Step Content:
+    - instructions_content: string - Full instructions markdown
+    - user_inputs: list|null - User parameters to gather:
+        - name: string - Parameter name
+        - description: string - What to ask for
+    - file_inputs: list|null - Files from previous steps:
+        - file: string - File path
+        - from_step: string - Source step ID
+    - outputs: list[string]|null - Output file paths
+
+  Quality & Hooks:
+    - quality_criteria: list[string]|null - Criteria for completion
+    - stop_hooks: list|null - Stop hook configurations:
+        - type: "script"|"prompt"
+        - path: string (for script)
+        - content: string (for prompt)
+    - hooks: dict|null - All hooks by event name (Stop, PreToolUse, etc.)
+#}
+---
+name: {{ job_name }}.{{ step_id }}
+description: "{{ step_description }}"
+{% if not exposed %}
+user-invocable: false
+{% endif %}
+{% if quality_criteria or hooks %}
+hooks:
+{% if quality_criteria %}
+  Stop:
+    - hooks:
+        - type: prompt
+          prompt: |
+            You must evaluate whether Claude has met all the below quality criteria for the request.
+
+            ## Quality Criteria
+
+{% for criterion in quality_criteria %}
+            {{ loop.index }}. {{ criterion }}
+{% endfor %}
+
+            ## Instructions
+
+            Review the conversation and determine if ALL quality criteria above have been satisfied.
+            Look for evidence that each criterion has been addressed.
+
+            If the agent has included `<promise>✓ Quality Criteria Met</promise>` in their response AND
+            all criteria appear to be met, respond with: {"ok": true}
+
+            If criteria are NOT met OR the promise tag is missing, respond with:
+            {"ok": false, "reason": "**AGENT: TAKE ACTION** - [which criteria failed and why]"}
+{% endif %}
+{% for event_name, event_hooks in hooks.items() %}
+{% if not (event_name == "Stop" and quality_criteria) %}
+  {{ event_name }}:
+    - hooks:
+{% for hook in event_hooks %}
+{% if hook.type == "script" %}
+        - type: command
+          command: ".deepwork/jobs/{{ job_name }}/{{ hook.path }}"
+{% else %}
+        - type: prompt
+          prompt: |
+            {{ hook.content | indent(12) }}
+{% endif %}
+{% endfor %}
+{% endif %}
+{% endfor %}
+{% endif %}
+---
+
+# {{ job_name }}.{{ step_id }}
+
+{% if is_standalone %}
+**Standalone skill** - can be run anytime
+{% else %}
+**Step {{ step_number }}/{{ total_steps }}** in **{{ job_name }}** workflow
+{% endif %}
+
+> {{ job_summary }}
+
+{% if dependencies %}
+## Prerequisites (Verify First)
+
+Before proceeding, confirm these steps are complete:
+{% for dep in dependencies %}
+- `/{{ job_name }}.{{ dep }}`
+{% endfor %}
+{% endif %}
+
+## Instructions
+
+**Goal**: {{ step_description }}
+
+{{ instructions_content }}
+
+{% if job_description %}
+### Job Context
+
+{{ job_description }}
+{% endif %}
+
+{% if user_inputs or file_inputs %}
+## Required Inputs
+
+{% if user_inputs %}
+**User Parameters** - Gather from user before starting:
+{% for input in user_inputs %}
+- **{{ input.name }}**: {{ input.description }}
+{% endfor %}
+{% endif %}
+
+{% if file_inputs %}
+**Files from Previous Steps** - Read these first:
+{% for input in file_inputs %}
+- `{{ input.file }}` (from `{{ input.from_step }}`)
+{% endfor %}
+{% endif %}
+{% endif %}
+
+## Work Branch
+
+Use branch format: `deepwork/{{ job_name }}-[instance]-YYYYMMDD`
+
+- If on a matching work branch: continue using it
+- If on main/master: create new branch with `git checkout -b deepwork/{{ job_name }}-[instance]-$(date +%Y%m%d)`
+
+## Outputs
+
+{% if outputs %}
+**Required outputs**:
+{% for output in outputs %}
+- `{{ output }}`{% if output.endswith('/') %} (directory){% endif %}
+{% endfor %}
+{% else %}
+No specific file outputs required.
+{% endif %}
+
+{% if quality_criteria or stop_hooks %}
+## Quality Validation
+
+Stop hooks will automatically validate your work. The loop continues until all criteria pass.
+
+{% if quality_criteria %}
+**Criteria (all must be satisfied)**:
+{% for criterion in quality_criteria %}
+{{ loop.index }}. {{ criterion }}
+{% endfor %}
+{% endif %}
+
+{% for hook in stop_hooks %}
+{% if hook.type == "script" %}
+**Validation script**: `.deepwork/jobs/{{ job_name }}/{{ hook.path }}` (runs automatically)
+{% endif %}
+{% endfor %}
+
+**To complete**: Include `<promise>✓ Quality Criteria Met</promise>` in your final response only after verifying ALL criteria are satisfied.
+
+{% endif %}
+## On Completion
+
+{% if is_standalone %}
+1. Verify outputs are created
+2. Inform user: "{{ step_id }} complete{% if outputs %}, outputs: {{ outputs | join(', ') }}{% endif %}"
+
+This standalone skill can be re-run anytime.
+{% else %}
+1. Verify outputs are created
+2. Inform user: "Step {{ step_number }}/{{ total_steps }} complete{% if outputs %}, outputs: {{ outputs | join(', ') }}{% endif %}"
+{% if next_step %}
+3. **Continue workflow**: Use Skill tool to invoke `/{{ job_name }}.{{ next_step }}`
+{% else %}
+3. **Workflow complete**: All steps finished. Consider creating a PR to merge the work branch.
+{% endif %}
+{% endif %}
+
+---
+
+**Reference files**: `.deepwork/jobs/{{ job_name }}/job.yml`, `.deepwork/jobs/{{ job_name }}/{{ instructions_file }}`

deepwork/templates/gemini/skill-job-meta.toml.jinja

@@ -0,0 +1,76 @@
+{#
+Template: skill-job-meta.toml.jinja
+Purpose: Generates the job overview skill file for Gemini CLI
+
+Template Variables:
+  - job_name: string - Job identifier (e.g., "competitive_research")
+  - job_summary: string - Short one-line summary of the job
+  - job_description: string|null - Full description (optional)
+  - total_steps: int - Number of steps in the job
+  - steps: list - Array of step objects:
+      - id: string - Step identifier
+      - name: string - Human-readable step name
+      - description: string - What the step does
+      - command_name: string - Slash command (e.g., "job_name:step_id")
+      - dependencies: list[string]|null - Required prior steps
+
+Note: Gemini uses TOML format with description + prompt fields.
+      Commands use colon separator (/job_name:step_id) not period.
+#}
+# {{ job_name }}
+#
+# {{ job_summary }}
+#
+# Generated by DeepWork - do not edit manually
+
+description = "{{ job_summary | replace('"', '\\"') }}"
+
+prompt = """
+# {{ job_name }}
+
+**Multi-step workflow**: {{ job_summary }}
+
+> **NOTE**: Gemini CLI requires manual command invocation. After each step, tell the user which command to run next.
+
+{% if job_description %}
+{{ job_description }}
+{% endif %}
+
+## Available Steps
+
+{% for step in steps %}
+{{ loop.index }}. **{{ step.id }}** - {{ step.description }}{% if step.dependencies %} (requires: {{ step.dependencies | join(', ') }}){% endif %}
+
+   Command: `/{{ step.command_name }}`
+{% endfor %}
+
+## Execution Instructions
+
+### Step 1: Analyze Intent
+
+Parse any text following `/{{ job_name }}` to determine user intent:
+{% for step in steps %}
+- "{{ step.id }}" or related terms → start at `/{{ step.command_name }}`
+{% endfor %}
+
+### Step 2: Direct User to Starting Step
+
+Tell the user which command to run:
+```
+/{{ steps[0].command_name }}
+```
+
+### Step 3: Guide Through Workflow
+
+After each step completes, tell the user the next command to run until workflow is complete.
+
+### Handling Ambiguous Intent
+
+If user intent is unclear:
+- Present available steps as numbered options
+- Ask user to select the starting point
+
+## Reference
+
+- Job definition: `.deepwork/jobs/{{ job_name }}/job.yml`
+"""

deepwork/templates/gemini/skill-job-step.toml.jinja

@@ -0,0 +1,147 @@
+{#
+Template: skill-job-step.toml.jinja
+Purpose: Generates individual step skill files for Gemini CLI
+
+Template Variables:
+  Job Context:
+    - job_name: string - Job identifier
+    - job_summary: string - Short job summary
+    - job_description: string|null - Full job description
+
+  Step Metadata:
+    - step_id: string - Step identifier
+    - step_description: string - What this step does
+    - step_number: int - Position in workflow (1-indexed)
+    - total_steps: int - Total steps in job
+    - is_standalone: bool - True if step can run independently
+    - dependencies: list[string]|null - Required prior step IDs
+    - next_step: string|null - Next step ID in workflow
+    - instructions_file: string - Path to step instructions file
+
+  Step Content:
+    - instructions_content: string - Full instructions markdown
+    - user_inputs: list|null - User parameters to gather:
+        - name: string - Parameter name
+        - description: string - What to ask for
+    - file_inputs: list|null - Files from previous steps:
+        - file: string - File path
+        - from_step: string - Source step ID
+    - outputs: list[string]|null - Output file paths
+
+  Quality:
+    - quality_criteria: list[string]|null - Criteria for completion
+    - stop_hooks: list|null - Stop hook configurations (note: Gemini
+      does not support automated hooks, so these are for manual verification)
+
+Note: Gemini uses TOML format with description + prompt fields.
+      Commands use colon separator (/job_name:step_id) not period.
+#}
+# {{ job_name }}:{{ step_id }}
+#
+# {{ step_description }}
+#
+# Generated by DeepWork - do not edit manually
+
+description = "{{ step_description | replace('"', '\\"') }}"
+
+prompt = """
+# {{ job_name }}:{{ step_id }}
+
+{% if is_standalone %}
+**Standalone command** - can be run anytime
+{% else %}
+**Step {{ step_number }}/{{ total_steps }}** in **{{ job_name }}** workflow
+{% endif %}
+
+> {{ job_summary }}
+
+{% if dependencies %}
+## Prerequisites (Verify First)
+
+Before proceeding, confirm these steps are complete:
+{% for dep in dependencies %}
+- `/{{ job_name }}:{{ dep }}`
+{% endfor %}
+{% endif %}
+
+## Instructions
+
+**Goal**: {{ step_description }}
+
+{{ instructions_content }}
+
+{% if job_description %}
+### Job Context
+
+{{ job_description }}
+{% endif %}
+
+{% if user_inputs or file_inputs %}
+## Required Inputs
+
+{% if user_inputs %}
+**User Parameters** - Gather from user before starting:
+{% for input in user_inputs %}
+- **{{ input.name }}**: {{ input.description }}
+{% endfor %}
+{% endif %}
+
+{% if file_inputs %}
+**Files from Previous Steps** - Read these first:
+{% for input in file_inputs %}
+- `{{ input.file }}` (from `{{ input.from_step }}`)
+{% endfor %}
+{% endif %}
+{% endif %}
+
+## Work Branch
+
+Use branch format: `deepwork/{{ job_name }}-[instance]-YYYYMMDD`
+
+- If on a matching work branch: continue using it
+- If on main/master: create new branch with `git checkout -b deepwork/{{ job_name }}-[instance]-$(date +%Y%m%d)`
+
+## Outputs
+
+{% if outputs %}
+**Required outputs**:
+{% for output in outputs %}
+- `{{ output }}`{% if output.endswith('/') %} (directory){% endif %}
+{% endfor %}
+{% else %}
+No specific file outputs required.
+{% endif %}
+
+{% if quality_criteria or stop_hooks %}
+## Quality Validation (Manual)
+
+**NOTE**: Gemini CLI does not support automated validation. Manually verify criteria before completing.
+
+{% if quality_criteria %}
+**Criteria (all must be satisfied)**:
+{% for criterion in quality_criteria %}
+{{ loop.index }}. {{ criterion }}
+{% endfor %}
+{% endif %}
+{% endif %}
+## On Completion
+
+{% if is_standalone %}
+1. Verify outputs are created
+2. Inform user: "{{ step_id }} complete{% if outputs %}, outputs: {{ outputs | join(', ') }}{% endif %}"
+
+This standalone command can be re-run anytime.
+{% else %}
+1. Verify outputs are created
+2. Inform user: "Step {{ step_number }}/{{ total_steps }} complete{% if outputs %}, outputs: {{ outputs | join(', ') }}{% endif %}"
+{% if next_step %}
+3. **Tell user next command**: `/{{ job_name }}:{{ next_step }}`
+{% else %}
+3. **Workflow complete**: All steps finished. Consider creating a PR to merge the work branch.
+{% endif %}
+{% endif %}
+
+---
+
+**Reference files**: `.deepwork/jobs/{{ job_name }}/job.yml`, `.deepwork/jobs/{{ job_name }}/{{ instructions_file }}`
+"""

{deepwork-0.2.0.dist-info → deepwork-0.3.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: deepwork
-Version: 0.2.0
+Version: 0.3.1
 Summary: Framework for enabling AI agents to perform complex, multi-step work tasks
 Project-URL: Homepage, https://github.com/deepwork/deepwork
 Project-URL: Documentation, https://github.com/deepwork/deepwork#readme
@@ -50,7 +50,7 @@ DeepWork is a tool for defining and executing multi-step workflows with AI codin
 | OpenCode | Planned | Markdown | No |
 | GitHub Copilot CLI | Planned | Markdown | No (tool permissions only) |
 
-> **Tip:** New to DeepWork? Claude Code has the most complete feature support, including quality validation hooks and automated policies. For browser automation, Claude in Chrome (Anthropic's browser extension) works well with DeepWork workflows.
+> **Tip:** New to DeepWork? Claude Code has the most complete feature support, including quality validation hooks and automated rules. For browser automation, Claude in Chrome (Anthropic's browser extension) works well with DeepWork workflows.
 
 ## Easy Installation
 In your Agent CLI (ex. `claude`), ask:
@@ -96,8 +96,7 @@ This will:
 - Create `.deepwork/` directory structure
 - 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
+- Configure hooks for your AI assistant to enable rules
 
 ## Quick Start
 
@@ -204,7 +203,7 @@ DeepWork follows a **Git-native, installation-only** design:
 
 - **No runtime daemon**: DeepWork is purely a CLI tool
 - **Git-based workflow**: All work happens on dedicated branches
-- **Skills as interface**: AI agents interact via generated markdown skill files
+- **Skills as interface**: AI agents interact via generated skill files
 - **Platform-agnostic**: Works with any AI coding assistant that supports skills
 
 ### Directory Structure
@@ -213,16 +212,20 @@ DeepWork follows a **Git-native, installation-only** design:
 your-project/
 ├── .deepwork/
 │   ├── config.yml          # Platform configuration
+│   ├── rules/              # Rule definitions (v2 format)
+│   │   └── rule-name.md    # Individual rule files
+│   ├── tmp/                # Temporary state (gitignored)
+│   │   └── rules/queue/    # Rule evaluation queue
 │   └── jobs/               # Job definitions
 │       └── job_name/
 │           ├── job.yml     # Job metadata
 │           └── steps/      # Step instructions
-├── .claude/                # Claude Code commands (auto-generated)
-│   └── commands/
+├── .claude/                # Claude Code skills (auto-generated)
+│   └── skills/
 │       ├── deepwork_jobs.define.md
 │       └── job_name.step_name.md
-└── .gemini/                # Gemini CLI commands (auto-generated)
-    └── commands/
+└── .gemini/                # Gemini CLI skills (auto-generated)
+    └── skills/
         └── job_name/
             └── step_name.toml
 ```
@@ -243,49 +246,76 @@ deepwork/
 │   ├── core/             # Core functionality
 │   │   ├── parser.py     # Job definition parsing
 │   │   ├── detector.py   # Platform detection
-│   │   └── generator.py  # Skill file generation
+│   │   ├── generator.py  # Skill file generation
+│   │   ├── rules_parser.py     # Rule parsing
+│   │   ├── pattern_matcher.py  # Variable pattern matching
+│   │   ├── rules_queue.py      # Rule state queue
+│   │   └── command_executor.py # Command action execution
+│   ├── hooks/            # Cross-platform hook wrappers
+│   │   ├── wrapper.py    # Input/output normalization
+│   │   ├── rules_check.py    # Rule evaluation hook
+│   │   ├── claude_hook.sh    # Claude Code adapter
+│   │   └── gemini_hook.sh    # Gemini CLI adapter
 │   ├── templates/        # Jinja2 templates
 │   │   ├── claude/       # Claude Code templates
 │   │   └── gemini/       # Gemini CLI templates
 │   ├── schemas/          # JSON schemas
 │   └── utils/            # Utilities (fs, yaml, git, validation)
 ├── tests/
-│   ├── unit/             # Unit tests (147 tests)
-│   ├── integration/      # Integration tests (19 tests)
+│   ├── unit/             # Unit tests
+│   ├── integration/      # Integration tests
 │   └── fixtures/         # Test fixtures
 └── doc/                  # Documentation
 ```
 
 ## Features
 
-### 📋 Job Definition
+### Job Definition
 Define structured, multi-step workflows where each step has clear requirements and produces specific results.
 - **Dependency Management**: Explicitly link steps with automatic sequence handling and cycle detection.
 - **Artifact Passing**: Seamlessly use file outputs from one step as inputs for future steps.
 - **Dynamic Inputs**: Support for both fixed file references and interactive user parameters.
 - **Human-Readable YAML**: Simple, declarative job definitions that are easy to version and maintain.
 
-### 🌿 Git-Native Workflow
+### Git-Native Workflow
 Maintain a clean repository with automatic branch management and isolation.
 - **Automatic Branching**: Every job execution happens on a dedicated work branch (e.g., `deepwork/my-job-2024`).
 - **Namespace Isolation**: Run multiple concurrent jobs or instances without versioning conflicts.
 - **Full Traceability**: All AI-generated changes, logs, and artifacts are tracked natively in your Git history.
 
-### 🛡️ Automated Policies
-Enforce project standards and best practices without manual oversight. Policies monitor file changes and automatically prompt your AI assistant to follow specific guidelines when relevant code is modified.
-- **Automatic Triggers**: Detect when specific files or directories are changed to fire relevant policies.
+### Automated Rules
+Enforce project standards and best practices without manual oversight. Rules monitor file changes and automatically prompt your AI assistant to follow specific guidelines when relevant code is modified.
+- **Automatic Triggers**: Detect when specific files or directories are changed to fire relevant rules.
+- **File Correspondence**: Define bidirectional (set) or directional (pair) relationships between files.
+- **Command Actions**: Run idempotent commands (formatters, linters) automatically when files change.
 - **Contextual Guidance**: Instructions are injected directly into the AI's workflow at the right moment.
-- **Common Use Cases**: Keep documentation in sync, enforce security reviews, or automate changelog updates.
 
-**Example Policy**:
-```yaml
-# Enforce documentation updates when config changes
-- name: "Update docs on config changes"
-  trigger: "app/config/**/*"
-  instructions: "Configuration files changed. Please update docs/install_guide.md."
+**Example Rule** (`.deepwork/rules/source-test-pairing.md`):
+```markdown
+---
+name: Source/Test Pairing
+set:
+  - src/{path}.py
+  - tests/{path}_test.py
+compare_to: base
+---
+When source files change, corresponding test files should also change.
+Please create or update tests for the modified source files.
+```
+
+**Example Command Rule** (`.deepwork/rules/format-python.md`):
+```markdown
+---
+name: Format Python
+trigger: "**/*.py"
+action:
+  command: "ruff format {file}"
+  run_for: each_match
+compare_to: prompt
+---
 ```
 
-### 🚀 Multi-Platform Support
+### Multi-Platform Support
 Generate native commands and skills tailored for your AI coding assistant.
 - **Native Integration**: Works directly with the skill/command formats of supported agents.
 - **Context-Aware**: Skills include all necessary context (instructions, inputs, and dependencies) for the AI.
@@ -311,3 +341,4 @@ For commercial use or questions about licensing, please contact legal@unsupervis
 ## Credits
 
 - Inspired by [GitHub's spec-kit](https://github.com/github/spec-kit)
+