deepwork 0.5.1__py3-none-any.whl → 0.7.0a1__py3-none-any.whl

deepwork/schemas/rules_schema.py

@@ -1,135 +0,0 @@
-"""JSON Schema definition for rule definitions (v2 - frontmatter format)."""
-
-from typing import Any
-
-# Pattern for string or array of strings
-STRING_OR_ARRAY: dict[str, Any] = {
-    "oneOf": [
-        {"type": "string", "minLength": 1},
-        {"type": "array", "items": {"type": "string", "minLength": 1}, "minItems": 1},
-    ]
-}
-
-# JSON Schema for rule frontmatter (YAML between --- delimiters)
-# Rules are stored as individual .md files in .deepwork/rules/
-RULES_FRONTMATTER_SCHEMA: dict[str, Any] = {
-    "$schema": "http://json-schema.org/draft-07/schema#",
-    "type": "object",
-    "required": ["name", "compare_to"],
-    "properties": {
-        "name": {
-            "type": "string",
-            "minLength": 1,
-            "description": "Human-friendly name for the rule (displayed in promise tags)",
-        },
-        # Detection mode: trigger/safety (mutually exclusive with set/pair)
-        "trigger": {
-            **STRING_OR_ARRAY,
-            "description": "Glob pattern(s) for files that trigger this rule",
-        },
-        "safety": {
-            **STRING_OR_ARRAY,
-            "description": "Glob pattern(s) that suppress the rule if changed",
-        },
-        # Detection mode: set (bidirectional correspondence)
-        "set": {
-            "type": "array",
-            "items": {"type": "string", "minLength": 1},
-            "minItems": 2,
-            "description": "Patterns defining bidirectional file correspondence",
-        },
-        # Detection mode: pair (directional correspondence)
-        "pair": {
-            "type": "object",
-            "required": ["trigger", "expects"],
-            "properties": {
-                "trigger": {
-                    "type": "string",
-                    "minLength": 1,
-                    "description": "Pattern that triggers the rule",
-                },
-                "expects": {
-                    **STRING_OR_ARRAY,
-                    "description": "Pattern(s) for expected corresponding files",
-                },
-            },
-            "additionalProperties": False,
-            "description": "Directional file correspondence (trigger -> expects)",
-        },
-        # Detection mode: created (fire when files are created matching patterns)
-        "created": {
-            **STRING_OR_ARRAY,
-            "description": "Glob pattern(s) for newly created files that trigger this rule",
-        },
-        # Action type: command (default is prompt using markdown body)
-        "action": {
-            "type": "object",
-            "required": ["command"],
-            "properties": {
-                "command": {
-                    "type": "string",
-                    "minLength": 1,
-                    "description": "Command to run (supports {file}, {files}, {repo_root})",
-                },
-                "run_for": {
-                    "type": "string",
-                    "enum": ["each_match", "all_matches"],
-                    "default": "each_match",
-                    "description": "Run command for each file or all files at once",
-                },
-            },
-            "additionalProperties": False,
-            "description": "Command action to run instead of prompting",
-        },
-        # Common options
-        "compare_to": {
-            "type": "string",
-            "enum": ["base", "default_tip", "prompt"],
-            "description": "Baseline for detecting file changes",
-        },
-    },
-    "additionalProperties": False,
-    # Detection mode must be exactly one of: trigger, set, pair, or created
-    "oneOf": [
-        {
-            "required": ["trigger"],
-            "not": {
-                "anyOf": [
-                    {"required": ["set"]},
-                    {"required": ["pair"]},
-                    {"required": ["created"]},
-                ]
-            },
-        },
-        {
-            "required": ["set"],
-            "not": {
-                "anyOf": [
-                    {"required": ["trigger"]},
-                    {"required": ["pair"]},
-                    {"required": ["created"]},
-                ]
-            },
-        },
-        {
-            "required": ["pair"],
-            "not": {
-                "anyOf": [
-                    {"required": ["trigger"]},
-                    {"required": ["set"]},
-                    {"required": ["created"]},
-                ]
-            },
-        },
-        {
-            "required": ["created"],
-            "not": {
-                "anyOf": [
-                    {"required": ["trigger"]},
-                    {"required": ["set"]},
-                    {"required": ["pair"]},
-                ]
-            },
-        },
-    ],
-}

deepwork/standard_jobs/deepwork_jobs/steps/review_job_spec.md

@@ -1,208 +0,0 @@
-# Review Job Specification
-
-## Objective
-
-Review the `job.yml` created in the define step against the doc spec quality criteria using a sub-agent for unbiased evaluation, then iterate on fixes until all criteria pass.
-
-## Why This Step Exists
-
-The define step focuses on understanding user requirements and creating a job specification. This review step ensures the specification meets quality standards before implementation. Using a sub-agent provides an unbiased "fresh eyes" review that catches issues the main agent might miss after being deeply involved in the definition process.
-
-## Task
-
-Use a sub-agent to review the job.yml against all 9 doc spec quality criteria, then fix any failed criteria. Repeat until all criteria pass.
-
-### Step 1: Read the Job Specification
-
-Read the `job.yml` file created in the define step:
-
-```
-.deepwork/jobs/[job_name]/job.yml
-```
-
-Also read the doc spec for reference:
-
-```
-.deepwork/doc_specs/job_spec.md
-```
-
-### Step 2: Spawn Review Sub-Agent
-
-Use the Task tool to spawn a sub-agent that will provide an unbiased review:
-
-```
-Task tool parameters:
-- subagent_type: "general-purpose"
-- model: "haiku"
-- description: "Review job.yml against doc spec"
-- prompt: [see below]
-```
-
-**Sub-agent prompt template:**
-
-```
-Review this job.yml against the following 9 quality criteria from the doc spec.
-
-For each criterion, respond with:
-- PASS or FAIL
-- If FAIL: specific issue and suggested fix
-
-## job.yml Content
-
-[paste the full job.yml content here]
-
-## Quality Criteria
-
-1. **Valid Identifier**: Job name must be lowercase with underscores, no spaces or special characters (e.g., `competitive_research`, `monthly_report`)
-
-2. **Semantic Version**: Version must follow semantic versioning format X.Y.Z (e.g., `1.0.0`, `2.1.3`)
-
-3. **Concise Summary**: Summary must be under 200 characters and clearly describe what the job accomplishes
-
-4. **Rich Description**: Description must be multi-line and explain: the problem solved, the process, expected outcomes, and target users
-
-5. **Changelog Present**: Must include a changelog array with at least the initial version entry
-
-6. **Complete Steps**: Each step must have: id (lowercase_underscores), name, description, instructions_file, outputs (at least one), and dependencies array
-
-7. **Valid Dependencies**: Dependencies must reference existing step IDs with no circular references
-
-8. **Input Consistency**: File inputs with `from_step` must reference a step that is in the dependencies array
-
-9. **Output Paths**: Outputs must be valid filenames or paths (e.g., `report.md` or `reports/analysis.md`)
-
-## Response Format
-
-Respond with a structured evaluation:
-
-### Overall: [X/9 PASS]
-
-### Criterion Results
-
-1. Valid Identifier: [PASS/FAIL]
-   [If FAIL: Issue and fix]
-
-2. Semantic Version: [PASS/FAIL]
-   [If FAIL: Issue and fix]
-
-[... continue for all 9 criteria ...]
-
-### Summary of Required Fixes
-
-[List any fixes needed, or "No fixes required - all criteria pass"]
-```
-
-### Step 3: Review Sub-Agent Findings
-
-Parse the sub-agent's response:
-
-1. **Count passing criteria** - How many of the 9 criteria passed?
-2. **Identify failures** - List specific criteria that failed
-3. **Note suggested fixes** - What changes does the sub-agent recommend?
-
-### Step 4: Fix Failed Criteria
-
-For each failed criterion, edit the job.yml to address the issue:
-
-**Common fixes by criterion:**
-
-| Criterion | Common Issue | Fix |
-|-----------|-------------|-----|
-| Valid Identifier | Spaces or uppercase | Convert to lowercase_underscores |
-| Semantic Version | Missing or invalid format | Set to `"1.0.0"` or fix format |
-| Concise Summary | Too long or vague | Shorten to <200 chars, be specific |
-| Rich Description | Single line or missing context | Add multi-line explanation with problem/process/outcome/users |
-| Changelog Present | Missing changelog | Add `changelog:` with initial version entry |
-| Complete Steps | Missing required fields | Add id, name, description, instructions_file, outputs, dependencies |
-| Valid Dependencies | Non-existent step or circular | Fix step ID reference or reorder dependencies |
-| Input Consistency | from_step not in dependencies | Add the referenced step to dependencies array |
-| Output Paths | Invalid characters or format | Use valid filename/path format |
-
-### Step 5: Re-Run Review (If Needed)
-
-If any criteria failed:
-
-1. **Spawn a new sub-agent** with the updated job.yml content
-2. **Review the new findings**
-3. **Fix any remaining issues**
-4. **Repeat until all 9 criteria pass**
-
-### Step 6: Confirm Completion
-
-When all 9 criteria pass:
-
-1. **Announce success**: "All 9 doc spec quality criteria pass."
-2. **List what was validated**:
-   - Valid Identifier
-   - Semantic Version
-   - Concise Summary
-   - Rich Description
-   - Changelog Present
-   - Complete Steps
-   - Valid Dependencies
-   - Input Consistency
-   - Output Paths
-3. **Include the promise**: `<promise>Quality Criteria Met</promise>`
-4. **Guide to next step**: "Run `/deepwork_jobs.implement` to generate the step instruction files."
-
-## Example Review Cycle
-
-```
-Claude: Let me review the job.yml against the doc spec quality criteria.
-
-[Spawns sub-agent with haiku model]
-
-Sub-agent response:
-### Overall: 7/9 PASS
-
-### Criterion Results
-1. Valid Identifier: PASS
-2. Semantic Version: PASS
-3. Concise Summary: FAIL
-   Issue: Summary is 245 characters, exceeds 200 char limit
-   Fix: Shorten to "Competitive analysis workflow for product positioning"
-4. Rich Description: PASS
-5. Changelog Present: FAIL
-   Issue: No changelog array present
-   Fix: Add changelog with initial version entry
-6. Complete Steps: PASS
-7. Valid Dependencies: PASS
-8. Input Consistency: PASS
-9. Output Paths: PASS
-
-### Summary of Required Fixes
-1. Shorten summary to under 200 characters
-2. Add changelog array with initial version
-
-Claude: I found 2 issues. Let me fix them.
-
-[Edits job.yml to shorten summary and add changelog]
-
-Claude: Let me verify the fixes with another review.
-
-[Spawns new sub-agent]
-
-Sub-agent response:
-### Overall: 9/9 PASS
-
-### Summary of Required Fixes
-No fixes required - all criteria pass
-
-Claude: All 9 doc spec quality criteria pass.
-
-<promise>Quality Criteria Met</promise>
-
-**Next step:** Run `/deepwork_jobs.implement` to generate the step instruction files.
-```
-
-## Quality Criteria
-
-- **Sub-Agent Used**: A sub-agent was spawned to provide unbiased review (not just self-review)
-- **All doc spec Criteria Evaluated**: The sub-agent assessed all 9 quality criteria from the doc spec
-- **Findings Addressed**: All failed criteria were fixed by the main agent
-- **Validation Loop Complete**: The review-fix cycle continued until all criteria passed
-- **Promise Included**: The response includes `<promise>Quality Criteria Met</promise>` when complete
-
-## Output
-
-The validated `job.yml` file at `.deepwork/jobs/[job_name]/job.yml` that passes all 9 doc spec quality criteria.

deepwork/standard_jobs/deepwork_jobs/templates/doc_spec.md.example

@@ -1,86 +0,0 @@
----
-name: "Monthly AWS Spending Report"
-description: "A Markdown summary of AWS spend across accounts for finance and engineering leadership"
-path_patterns:
-  - "finance/aws-reports/*.md"
-  - "reports/aws/*.md"
-target_audience: "Finance team and Engineering leadership"
-frequency: "Monthly, following AWS invoice arrival"
-quality_criteria:
-  - name: Executive Summary
-    description: Must include a 2-3 sentence summary of total spend, month-over-month change percentage, and top cost driver
-  - name: Visualization
-    description: Must include at least one Mermaid.js chart showing spend breakdown by service (pie chart) or trend over time (line chart)
-  - name: Variance Analysis
-    description: Must compare current month against previous month with percentage changes for top 5 services
-  - name: Cost Attribution
-    description: Must break down costs by team/project using AWS tags where available
-  - name: Action Items
-    description: Must include 2-3 specific, actionable recommendations for cost optimization
----
-
-# Monthly AWS Spending Report: [Month, Year]
-
-## Executive Summary
-
-[2-3 sentences summarizing:
-- Total spend this month
-- Percentage change from last month
-- The primary cost driver]
-
-## Spend Overview
-
-### Total Spend by Service
-
-```mermaid
-pie title AWS Spend by Service
-    "EC2" : 45
-    "RDS" : 25
-    "S3" : 15
-    "Lambda" : 10
-    "Other" : 5
-```
-
-### Month-over-Month Trend
-
-```mermaid
-xychart-beta
-    title "Monthly AWS Spend Trend"
-    x-axis [Jan, Feb, Mar, Apr, May, Jun]
-    y-axis "Spend ($K)" 0 --> 100
-    line [45, 48, 52, 49, 55, 58]
-```
-
-## Variance Analysis
-
-| Service | Last Month | This Month | Change | % Change |
-|---------|-----------|------------|--------|----------|
-| EC2     | $X,XXX    | $X,XXX     | +$XXX  | +X.X%    |
-| RDS     | $X,XXX    | $X,XXX     | -$XXX  | -X.X%    |
-| S3      | $X,XXX    | $X,XXX     | +$XXX  | +X.X%    |
-| Lambda  | $X,XXX    | $X,XXX     | +$XXX  | +X.X%    |
-| Other   | $X,XXX    | $X,XXX     | +$XXX  | +X.X%    |
-
-## Cost Attribution by Team
-
-| Team/Project | Spend | % of Total |
-|--------------|-------|------------|
-| Platform     | $X,XXX | XX%       |
-| Data         | $X,XXX | XX%       |
-| Product      | $X,XXX | XX%       |
-| Shared       | $X,XXX | XX%       |
-
-## Recommendations
-
-1. **[Action Item 1]**: [Specific recommendation with expected savings]
-2. **[Action Item 2]**: [Specific recommendation with expected savings]
-3. **[Action Item 3]**: [Specific recommendation with expected savings]
-
-## Appendix
-
-### Data Sources
-- AWS Cost Explorer
-- AWS Tags: team, project, environment
-
-### Report Methodology
-[Brief explanation of how costs are calculated and attributed]

deepwork/standard_jobs/deepwork_rules/hooks/capture_prompt_work_tree.sh

@@ -1,38 +0,0 @@
-#!/bin/bash
-# capture_prompt_work_tree.sh - Captures the git work tree state at prompt submission
-#
-# This script creates a snapshot of ALL tracked files at the time the prompt
-# is submitted. This baseline is used for rules with compare_to: prompt and
-# created: mode to detect truly NEW files (not modifications to existing ones).
-#
-# The baseline contains ALL tracked files (not just changed files) so that
-# the rules_check hook can determine which files are genuinely new vs which
-# files existed before and were just modified.
-#
-# It also captures the HEAD commit ref so that committed changes can be detected
-# by comparing HEAD at Stop time to the captured ref.
-
-set -e
-
-# Ensure .deepwork directory exists
-mkdir -p .deepwork
-
-# Save the current HEAD commit ref for detecting committed changes
-# This is used by get_changed_files_prompt() to detect files changed since prompt,
-# even if those changes were committed during the agent response.
-git rev-parse HEAD > .deepwork/.last_head_ref 2>/dev/null || echo "" > .deepwork/.last_head_ref
-
-# Save ALL tracked files (not just changed files)
-# This is critical for created: mode rules to distinguish between:
-# - Newly created files (not in baseline) -> should trigger created: rules
-# - Modified existing files (in baseline) -> should NOT trigger created: rules
-git ls-files > .deepwork/.last_work_tree 2>/dev/null || true
-
-# Also include untracked files that exist at prompt time
-# These are files the user may have created before submitting the prompt
-git ls-files --others --exclude-standard >> .deepwork/.last_work_tree 2>/dev/null || true
-
-# Sort and deduplicate
-if [ -f .deepwork/.last_work_tree ]; then
-    sort -u .deepwork/.last_work_tree -o .deepwork/.last_work_tree
-fi

deepwork/standard_jobs/deepwork_rules/hooks/global_hooks.yml

@@ -1,8 +0,0 @@
-# DeepWork Rules Hooks Configuration
-# Maps lifecycle events to hook scripts or Python modules
-
-UserPromptSubmit:
-  - user_prompt_submit.sh
-
-Stop:
-  - module: deepwork.hooks.rules_check

deepwork/standard_jobs/deepwork_rules/hooks/user_prompt_submit.sh

@@ -1,16 +0,0 @@
-#!/bin/bash
-# user_prompt_submit.sh - Runs on every user prompt submission
-#
-# This script captures the work tree state at each prompt submission.
-# This baseline is used for policies with compare_to: prompt to detect
-# what changed during an agent response.
-
-set -e
-
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-
-# Capture work tree state at each prompt for compare_to: prompt policies
-"${SCRIPT_DIR}/capture_prompt_work_tree.sh"
-
-# Exit successfully - don't block the prompt
-exit 0

deepwork/standard_jobs/deepwork_rules/job.yml

@@ -1,49 +0,0 @@
-name: deepwork_rules
-version: "0.4.0"
-summary: "Creates file-change rules that enforce guidelines during AI sessions. Use when automating documentation sync or code review triggers."
-description: |
-  Manages rules that automatically trigger when certain files change during an AI agent session.
-  Rules help ensure that code changes follow team guidelines, documentation is updated,
-  and architectural decisions are respected.
-
-  IMPORTANT: Rules are evaluated at the "Stop" hook, which fires when an agent finishes its turn.
-  This includes when sub-agents complete their work. Rules are NOT evaluated immediately after
-  each file edit - they batch up and run once at the end of the agent's response cycle.
-  - Command action rules: Execute their command (e.g., `uv sync`) when the agent stops
-  - Prompt action rules: Display instructions to the agent, blocking until addressed
-
-  Rules are stored as individual markdown files with YAML frontmatter in the `.deepwork/rules/`
-  directory. Each rule file specifies:
-  - Detection mode: trigger/safety, set (bidirectional), or pair (directional)
-  - Patterns: Glob patterns for matching files, with optional variable capture
-  - Action type: prompt (default) to show instructions, or command to run a shell command
-  - Instructions: Markdown content describing what the agent should do
-
-  Example use cases:
-  - Update installation docs when configuration files change
-  - Require security review when authentication code is modified
-  - Ensure API documentation stays in sync with API code
-  - Enforce source/test file pairing
-  - Auto-run `uv sync` when pyproject.toml changes (command action)
-
-changelog:
-  - version: "0.1.0"
-    changes: "Initial version"
-  - version: "0.2.0"
-    changes: "Standardized on 'ask structured questions' phrasing for user input"
-  - version: "0.3.0"
-    changes: "Migrated to v2 format - individual markdown files in .deepwork/rules/"
-  - version: "0.4.0"
-    changes: "Improved skill descriptions with third-person voice and 'Use when...' triggers for better discoverability"
-
-steps:
-  - id: define
-    name: "Define Rule"
-    description: "Creates a rule file that triggers when specified files change. Use when setting up documentation sync, code review requirements, or automated commands."
-    instructions_file: steps/define.md
-    inputs:
-      - name: rule_purpose
-        description: "What guideline or constraint should this rule enforce?"
-    outputs:
-      - .deepwork/rules/{rule-name}.md
-    dependencies: []

deepwork/standard_jobs/deepwork_rules/rules/.gitkeep

@@ -1,13 +0,0 @@
-# This directory contains example rule templates.
-# Copy and customize these files to create your own rules.
-#
-# Rule files use YAML frontmatter in markdown format:
-#
-# ---
-# name: Rule Name
-# trigger: "pattern/**/*"
-# safety: "optional/pattern"
-# ---
-# Instructions in markdown here.
-#
-# See doc/rules_syntax.md for full documentation.

deepwork/standard_jobs/deepwork_rules/rules/api-documentation-sync.md.example

@@ -1,10 +0,0 @@
----
-name: API Documentation Sync
-trigger: src/api/**/*
-safety: docs/api/**/*.md
----
-API code has changed. Please verify that API documentation is up to date:
-
-- New or changed endpoints
-- Modified request/response schemas
-- Updated authentication requirements

deepwork/standard_jobs/deepwork_rules/rules/readme-documentation.md.example

@@ -1,10 +0,0 @@
----
-name: README Documentation
-trigger: src/**/*
-safety: README.md
----
-Source code has been modified. Please review README.md for accuracy:
-
-1. Verify the project overview reflects current functionality
-2. Check that usage examples are still correct
-3. Ensure installation/setup instructions remain valid

deepwork/standard_jobs/deepwork_rules/rules/security-review.md.example

@@ -1,11 +0,0 @@
----
-name: Security Review for Auth Changes
-trigger:
-  - src/auth/**/*
-  - src/security/**/*
----
-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

deepwork/standard_jobs/deepwork_rules/rules/skill-md-validation.md

@@ -1,46 +0,0 @@
----
-name: SKILL.md Validation
-trigger: "**/SKILL.md"
-compare_to: base
----
-A SKILL.md file has been created or modified. Please validate that it follows the required format:
-
-## Required Structure
-
-The file MUST have valid YAML frontmatter at the start, enclosed between `---` markers:
-
-```markdown
----
-name: my-skill-name
-description: A description of what this skill does
----
-
-# Rest of the skill documentation...
-```
-
-## Validation Checklist
-
-1. **YAML Frontmatter**: Verify the file starts with `---` followed by valid YAML and ends with `---`
-
-2. **`name` field** (required):
-   - Must be present in the frontmatter
-   - Must contain only lowercase letters, numbers, and hyphens (`a-z`, `0-9`, `-`)
-   - Must be 64 characters or fewer
-   - Example valid names: `my-skill`, `code-review-2`, `lint`
-   - Example invalid names: `My Skill` (uppercase/spaces), `skill_name` (underscores), `SKILL` (uppercase)
-
-3. **`description` field** (required):
-   - Must be present in the frontmatter
-   - Must be 1024 characters or fewer
-   - Should clearly describe what the skill does
-
-## What to Check
-
-For the modified file: {trigger_files}
-
-1. Parse the YAML frontmatter and verify it is valid YAML
-2. Check that `name` exists and matches the pattern `^[a-z0-9-]+$` with max length 64
-3. Check that `description` exists and is at most 1024 characters
-4. Report any validation errors to the user
-
-If the file does not pass validation, help the user fix the issues.

deepwork/standard_jobs/deepwork_rules/rules/source-test-pairing.md.example

@@ -1,13 +0,0 @@
----
-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 source: {trigger_files}
-Expected tests: {expected_files}