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

deepwork/standard_jobs/deepwork_rules/steps/define.md

@@ -1,249 +0,0 @@
-# Define Rule
-
-## Objective
-
-Create a new rule file in the `.deepwork/rules/` directory to enforce team guidelines, documentation requirements, or other constraints when specific files change.
-
-## Task
-
-Guide the user through defining a new rule by asking structured questions. **Do not create the rule without first understanding what they want to enforce.**
-
-**Important**: Use the AskUserQuestion tool to ask structured questions when gathering information from the user. This provides a better user experience with clear options and guided choices.
-
-### Step 1: Understand the Rule Purpose
-
-Start by asking structured questions to understand what the user wants to enforce:
-
-1. **What guideline or constraint should this rule enforce?**
-   - What situation triggers the need for action?
-   - What files or directories, when changed, should trigger this rule?
-   - Examples: "When config files change", "When API code changes", "When database schema changes"
-
-2. **What action should be taken?**
-   - What should the agent do when the rule triggers?
-   - Update documentation? Perform a security review? Update tests?
-   - Is there a specific file or process that needs attention?
-
-3. **Are there any "safety" conditions?**
-   - Are there files that, if also changed, mean the rule doesn't need to fire?
-   - For example: If config changes AND install_guide.md changes, assume docs are already updated
-   - This prevents redundant prompts when the user has already done the right thing
-
-### Step 2: Choose the Detection Mode
-
-Help the user select the appropriate detection mode:
-
-**Trigger/Safety Mode** (most common):
-- Fires when trigger patterns match AND no safety patterns match
-- Use for: "When X changes, check Y" rules
-- Example: When config changes, verify install docs
-
-**Set Mode** (bidirectional correspondence):
-- Fires when files that should change together don't all change
-- Use for: Source/test pairing, model/migration sync
-- Example: `src/foo.py` and `tests/foo_test.py` should change together
-
-**Pair Mode** (directional correspondence):
-- Fires when a trigger file changes but expected files don't
-- Changes to expected files alone do NOT trigger
-- Use for: API code requires documentation updates (but docs can update independently)
-
-### Step 3: Define the Patterns
-
-Help the user define glob patterns for files.
-
-**Common patterns:**
-- `src/**/*.py` - All Python files in src directory (recursive)
-- `app/config/**/*` - All files in app/config directory
-- `*.md` - All markdown files in root
-- `src/api/**/*` - All files in the API directory
-- `migrations/**/*.sql` - All SQL migrations
-
-**Variable patterns (for set/pair modes):**
-- `src/{path}.py` - Captures path variable (e.g., `foo/bar` from `src/foo/bar.py`)
-- `tests/{path}_test.py` - Uses same path variable in corresponding file
-- `{name}` matches single segment, `{path}` matches multiple segments
-
-**Pattern syntax:**
-- `*` - Matches any characters within a single path segment
-- `**` - Matches any characters across multiple path segments (recursive)
-- `?` - Matches a single character
-
-### Step 4: Choose the Comparison Mode (Optional)
-
-The `compare_to` field controls what baseline is used when detecting "changed files":
-
-**Options:**
-- `base` (default) - Compares to the base of the current branch (merge-base with main/master). Best for feature branches.
-- `default_tip` - Compares to the current tip of the default branch. Useful for seeing difference from production.
-- `prompt` - Compares to the state at the start of each prompt. For rules about very recent changes.
-
-Most rules should use the default (`base`) and don't need to specify `compare_to`.
-
-### Step 5: Write the Instructions
-
-Create clear, actionable instructions for what the agent should do when the rule fires.
-
-**Good instructions include:**
-- What to check or review
-- What files might need updating
-- Specific actions to take
-- Quality criteria for completion
-
-**Template variables available in instructions:**
-- `{trigger_files}` - Files that triggered the rule
-- `{expected_files}` - Expected corresponding files (for set/pair modes)
-
-### Step 6: Create the Rule File
-
-Create a new file in `.deepwork/rules/` with a kebab-case filename:
-
-**File Location**: `.deepwork/rules/{rule-name}.md`
-
-**Format for Trigger/Safety Mode:**
-```markdown
----
-name: Friendly Name for the Rule
-trigger: "glob/pattern/**/*"  # or array: ["pattern1", "pattern2"]
-safety: "optional/pattern"    # optional, or array
-compare_to: base              # optional: "base" (default), "default_tip", or "prompt"
----
-Instructions for the agent when this rule fires.
-
-Multi-line markdown content is supported.
-```
-
-**Format for Set Mode (bidirectional):**
-```markdown
----
-name: Source/Test Pairing
-set:
-  - src/{path}.py
-  - tests/{path}_test.py
----
-Source and test files should change together.
-
-Modified: {trigger_files}
-Expected: {expected_files}
-```
-
-**Format for Pair Mode (directional):**
-```markdown
----
-name: API Documentation
-pair:
-  trigger: api/{path}.py
-  expects: docs/api/{path}.md
----
-API code requires documentation updates.
-
-Changed API: {trigger_files}
-Update docs: {expected_files}
-```
-
-### Step 7: Verify the Rule
-
-After creating the rule:
-
-1. **Check the YAML frontmatter** - Ensure valid YAML formatting
-2. **Test trigger patterns** - Verify patterns match intended files
-3. **Review instructions** - Ensure they're clear and actionable
-4. **Check for conflicts** - Ensure the rule doesn't conflict with existing ones
-
-## Example Rules
-
-### Update Documentation on Config Changes
-`.deepwork/rules/config-docs.md`:
-```markdown
----
-name: Update Install Guide on Config Changes
-trigger: app/config/**/*
-safety: docs/install_guide.md
----
-Configuration files have been modified. Please review docs/install_guide.md
-and update it if any installation instructions need to change based on the
-new configuration.
-```
-
-### Security Review for Auth Code
-`.deepwork/rules/security-review.md`:
-```markdown
----
-name: Security Review for Authentication Changes
-trigger:
-  - src/auth/**/*
-  - src/security/**/*
-safety:
-  - SECURITY.md
-  - docs/security_audit.md
----
-Authentication or security code has been changed. Please:
-
-1. Review for hardcoded credentials or secrets
-2. Check input validation on user inputs
-3. Verify access control logic is correct
-4. Update security documentation if needed
-```
-
-### Source/Test Pairing
-`.deepwork/rules/source-test-pairing.md`:
-```markdown
----
-name: Source/Test Pairing
-set:
-  - src/{path}.py
-  - tests/{path}_test.py
----
-Source and test files should change together.
-
-When modifying source code, ensure corresponding tests are updated.
-When adding tests, ensure they test actual source code.
-
-Modified: {trigger_files}
-Expected: {expected_files}
-```
-
-### API Documentation Sync
-`.deepwork/rules/api-docs.md`:
-```markdown
----
-name: API Documentation Update
-pair:
-  trigger: src/api/{path}.py
-  expects: docs/api/{path}.md
----
-API code has changed. Please verify that API documentation in docs/api/
-is up to date with the code changes. Pay special attention to:
-
-- New or changed endpoints
-- Modified request/response schemas
-- Updated authentication requirements
-
-Changed API: {trigger_files}
-Update: {expected_files}
-```
-
-## Output Format
-
-### .deepwork/rules/{rule-name}.md
-Create a new file with the rule definition using YAML frontmatter and markdown body.
-
-## Quality Criteria
-
-- Asked structured questions to understand user requirements
-- Rule name is clear and descriptive (used in promise tags)
-- Correct detection mode selected for the use case
-- Patterns accurately match the intended files
-- Safety patterns prevent unnecessary triggering (if applicable)
-- Instructions are actionable and specific
-- YAML frontmatter is valid
-
-## Context
-
-Rules are evaluated automatically when the agent finishes a task. The system:
-1. Determines which files have changed based on each rule's `compare_to` setting
-2. Evaluates rules based on their detection mode (trigger/safety, set, or pair)
-3. Skips rules where the correspondence is satisfied (for set/pair) or safety matched
-4. Prompts you with instructions for any triggered rules
-
-You can mark a rule as addressed by including `<promise>Rule Name</promise>` in your response (replace Rule Name with the actual rule name from the `name` field). This tells the system you've already handled that rule's requirements.

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

@@ -1,77 +0,0 @@
-{#
-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
-
-## Guardrails
-
-- Do NOT copy/paste step instructions directly; always use the Skill tool to invoke steps
-- Do NOT skip steps in the workflow unless the user explicitly requests it
-- Do NOT proceed to the next step if the current step's outputs are incomplete
-- Do NOT make assumptions about user intent; ask for clarification when ambiguous
-
-## Context Files
-
-- Job definition: `.deepwork/jobs/{{ job_name }}/job.yml`

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

@@ -1,251 +0,0 @@
-{#
-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 %}
-{% for event_name in ["Stop", "SubagentStop"] %}
-  {{ event_name }}:
-    - 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 OR
-            all criteria appear to be met, respond with: {"ok": true}
-
-            If criteria are NOT met AND the promise tag is missing, respond with:
-            {"ok": false, "reason": "**AGENT: TAKE ACTION** - [which criteria failed and why]"}
-{% endfor %}
-{% endif %}
-{% for event_name, event_hooks in hooks.items() %}
-{% if not (event_name == "Stop" and quality_criteria) and not (event_name == "SubagentStop" and "Stop" in hooks) %}
-{# For Stop events, generate both Stop and SubagentStop blocks #}
-{% if event_name == "Stop" %}
-{% for stop_event in ["Stop", "SubagentStop"] %}
-  {{ stop_event }}:
-    - 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 %}
-{% endfor %}
-{% else %}
-  {{ 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 %}
-{% 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.file }}`{% if output.file.endswith('/') %} (directory){% endif %}
-
-{% if output.has_doc_spec and output.doc_spec %}
-  **Doc Spec**: {{ output.doc_spec.name }}
-  > {{ output.doc_spec.description }}
-  **Definition**: `{{ output.doc_spec.path }}`
-{% if output.doc_spec.target_audience %}
-  **Target Audience**: {{ output.doc_spec.target_audience }}
-{% endif %}
-{% if output.doc_spec.quality_criteria %}
-  **Quality Criteria**:
-{% for criterion in output.doc_spec.quality_criteria %}
-  {{ loop.index }}. **{{ criterion.name }}**: {{ criterion.description }}
-{% endfor %}
-{% endif %}
-{% if output.doc_spec.example_document %}
-
-  <details>
-  <summary>Example Document Structure</summary>
-
-  ```markdown
-  {{ output.doc_spec.example_document | indent(2) }}
-  ```
-
-  </details>
-{% endif %}
-{% endif %}
-{% endfor %}
-{% else %}
-No specific file outputs required.
-{% endif %}
-
-## Guardrails
-
-- Do NOT skip prerequisite verification if this step has dependencies
-- Do NOT produce partial outputs; complete all required outputs before finishing
-- Do NOT proceed without required inputs; ask the user if any are missing
-- Do NOT modify files outside the scope of this step's defined outputs
-
-{% 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 | map(attribute='file') | 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 | map(attribute='file') | 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

@@ -1,76 +0,0 @@
-{#
-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`
-"""