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

deepwork-0.7.0.dist-info/METADATA

@@ -0,0 +1,317 @@
+Metadata-Version: 2.4
+Name: deepwork
+Version: 0.7.0
+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
+Project-URL: Repository, https://github.com/deepwork/deepwork
+Project-URL: Issues, https://github.com/deepwork/deepwork/issues
+Author: DeepWork Contributors
+License: Business Source License 1.1
+License-File: LICENSE.md
+Keywords: agents,ai,automation,cli,workflow
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: Other/Proprietary License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Requires-Python: >=3.11
+Requires-Dist: aiofiles>=24.0.0
+Requires-Dist: click>=8.1.0
+Requires-Dist: fastmcp>=2.0
+Requires-Dist: gitpython>=3.1.0
+Requires-Dist: jinja2>=3.1.0
+Requires-Dist: jsonschema>=4.17.0
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.0.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest-mock>=3.10; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Requires-Dist: types-aiofiles; extra == 'dev'
+Requires-Dist: types-pyyaml; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Teach Claude to Automate *Anything*
+
+Triage email, give feedback to your team, make tutorials/documentation, QA your product every day, do competitive research... *anything*.
+
+## Install
+```bash
+brew tap unsupervisedcom/deepwork && brew install deepwork
+```
+
+Then in your project folder (must be a Git repository):
+```bash
+deepwork install
+claude
+```
+
+> **Note:** DeepWork requires a Git repository. If your folder isn't already a repo, run `git init` first.
+
+Now inside claude, define your first job using the `/deepwork_jobs` command. Ex.
+```
+/deepwork_jobs Make a job for doing competitive research. It will take the URL of the competitor as an input, and should make report including a SWOT analysis for that competitor.
+```
+
+See below for additional installation options
+
+DeepWork is an open-source plugin for Claude Code (and other CLI agents). It:
+- teaches Claude to follow strict workflows consistently
+- makes it easy for you to define them 
+- learns and updates automatically
+
+## Example
+
+You can make a DeepWork job that uses Claude Code to automatically run a deep competitive research workflow. To do this you:
+- Run `/deepwork_jobs` in Claude Code and select `define`
+- Explain your process _e.g. "Go look at my company's website and social channels to capture any new developments, look at our existing list of competitors, do broad web searches to identify any new competitiors, and then do deep research on each competitor and produce a comprehensive set of md reports including a summary report for me._
+
+Deepwork will ask you questions to improve the plan and make a hardened automation workflow. This usually takes ~10 minutes. 
+
+When this is done, it will create a .yml file that details the plan and then will use templates to document how Claude should execute each individual step in the workflow. This usually takes 2-5 minutes.
+
+After that, it will create a new skill for you in Claude, something like `/competitive_research` that you can run at any time (or automate). 
+
+Running that `/competitive_research` command will get you output that looks something like this:
+```
+deepwork-output/competitive_research/
+├── competitors.md           # Who they are, what they do
+├── competitor_profiles/     # Deep dive on each
+├── primary_research.md      # What they say about themselves
+└── strategic_overview.md    # Your positioning recommendations
+```
+
+You only have to build a skill once. Then: run it whenever you need it.
+
+_Note: all of these skills are composable. You can call skills inside of other jobs. As an example, you could create a `make_comparison_document` skill and call it at the end of the `/competitive_research` skill — automating the process of going from research to having final breifings and materials on competitiors for your sales team._
+
+---
+
+## Who This Is For
+
+**If you can use Claude Code and describe a process, you can automate it.**
+
+| You | What You'd Automate |
+|-----|---------------------|
+| **Founders** | Competitive research, automatically discover bugs/issues and open tickets, reports or investor updates pulling from multiple sources |
+| **Ops** | Daily briefs, SEO analysis, git summaries |
+| **Product Managers** | Tutorial writing, QA reports, simulated user testing, updating process docs or sales materials |
+| **Engineers** | Automate standup summary, git summaries, reports |
+| **Data/Analytics** | Pull data from multiple sources, ETL, create custom reports and dashboards |
+
+One user used DeepWork to automatically research email performance across hundreds of millions of marketing emails. It accessed data from a data warehouse, came up with research questions, queried to answer those questions, and then produced a several page, comprehensive report. The process ran autonomously for ~90 minutes and produced a report better than internal dashboards that had been refined for months.
+
+DeepWork is a free, open-source tool — if you're already paying for a Claude Max subscription, each of these automations costs you nothing additional.
+
+Similar to how vibe coding makes easier for anyone to produce software, this is **vibe automation**: describe what you want, let it run, and then iterate on what works.
+
+---
+
+## Quick Start
+
+### 1. Install
+
+```bash
+brew tap unsupervisedcom/deepwork
+brew install deepwork
+```
+
+Then in any project folder (must be a Git repository):
+
+```bash
+deepwork install
+```
+
+> **Note:** If your folder isn't a Git repo yet, run `git init` first.
+
+**After install, load Claude.** Then verify you see this command: `/deepwork_jobs`
+
+### 2. Define Your First Workflow
+
+Start simple—something you do manually in 15-30 minutes. Here's an example:
+
+```
+/deepwork_jobs write a tutorial for how to use a new feature we just launched
+```
+
+DeepWork asks you questions (this usually takes about 10 minutes) then writes the steps. You're creating a **reusable skill** — after you do this process you can run that skill any time you want without repeating this process.
+
+### 3. Run It
+
+Once the skill is created, type the name of your job (e.g. `/tutorial`) in Claude and you'll see the skill show up in your suggestions (e.g. `/tutorial_writer`).
+
+Hit enter to run the skill. Claude will follow the workflow step by step. 
+
+## Some Examples of What Other People Are Building with DeepWork
+=======
+To start the process, just run:
+
+```
+/deepwork_jobs
+```
+
+| Workflow | What It Does | Why it matters|
+|----------|--------------|--------------|
+| **Email triage** | Scan inbox, categorize, archive, and draft replies | Save time processing email |
+| **Competitive research** | Track competitors weekly, generate diff reports | Fast feedback on how your competition is changing |
+| **Tutorial writer** | Turn your expertise into docs | Rapidly build docs, guides, etc. |
+| **SaaS user audit** | Quarterly audit of who has access to various services | Save money on forgotten SaaS licenses |
+
+---
+
+## Why It Works Well
+
+**1. Strict workflows** — Claude follows step-by-step instructions with quality checks. No more going off-script.
+
+**2. Easy to define** — Describe what you want in plain English. DeepWork knows how to ask you the right questions to refine your plan.
+```
+/deepwork_jobs
+```
+
+**3. Learns automatically** — Run `/deepwork_jobs.learn` (or ask claude to `run the deepwork learn job`) after any job to automatically capture what worked and improve for next time.
+
+**4. All work happens on Git branches** — Every change can be version-controlled and tracked. You can roll-back to prior versions of the skill or keep skills in-sync and up-to-date across your team.
+
+---
+
+## Supported Platforms
+
+| Platform | Status | Notes |
+|----------|--------|-------|
+| **Claude Code** | Full Support | Recommended. Quality hooks, best DX. |
+| **Gemini CLI** | Partial Support | TOML format, global hooks only |
+| OpenCode | Planned | |
+| GitHub Copilot CLI | Planned | |
+| Others | Planned | We are nailing Claude and Gemini first, then adding others according ot demand |
+
+**Tip:** Use the terminal (Claude Code CLI), not the VS Code extension. The terminal has full feature support.
+
+---
+
+## Browser Automation
+
+For workflows that need to interact with websites, you can use any browser automation tool that works in Claude Code. We generally recommend [Claude in Chrome](https://www.anthropic.com/claude-in-chrome).
+
+**⚠️ Safety note:** Browser automation is still something models can be hit-or-miss on. We recommend using a dedicated Chrome profile for automation.
+
+---
+
+## Troubleshooting
+
+Here are some known issues that affect some early users — we're working on improving normal performance on these, but here are some known workarounds.
+
+### Slash Commands don't appear after install
+
+Exit Claude completely and restart.
+
+### Stop hooks firing unexpectedly
+
+Occasionally, especially after updating a job or running the `deepwork_jobs learn` process after completing a task, Claude will get confused about which workflow it's running checks for. For now, if stop hooks fire when they shouldn't, you can either:
+- Ask claude `do we need to address any of these stop hooks or can we ignore them for now?` 
+- Ignore the stop hooks and keep going until the workflow steps are complete
+- Run the `/clear` command to start a new context window (you'll have to re-run the job after this)
+
+### Claude "just does the task" instead of using DeepWork
+
+If Claude attempts to bypass the workflow and do the task on it's own, tell it explicitly to use the skill. You can also manually run the step command:
+```
+/your_job
+```
+
+Tip: Don't say things like "can you do X" while in **defining** a new `/deepwork_jobs` — Claude has a bias towards action and workarounds and may abandon the skill creation workflow and attempt to do your task as a one off. Instead, say something like "create a workflow that..."
+
+### If you can't solve your issues using the above and need help
+
+Send [@tylerwillis](https://x.com/tylerwillis) a message on X.
+
+---
+
+<details>
+<summary><strong>Advanced: Directory Structure</strong></summary>
+
+```
+your-project/
+├── .deepwork/
+│   ├── config.yml          # Platform configuration
+│   └── jobs/               # Job definitions
+│       └── job_name/
+│           ├── job.yml     # Job metadata
+│           └── steps/      # Step instructions
+├── .claude/                # Generated Claude skills
+│   └── skills/
+└── deepwork-output/        # Job outputs (gitignored)
+```
+
+</details>
+
+<details>
+<summary><strong>Alternative Installation Methods</strong></summary>
+
+**Prerequisites** (for non-Homebrew installs): Python 3.11+, Git
+
+Homebrew is recommended, but you can also use:
+
+```bash
+# uv (Recommended)
+uv tool install deepwork
+
+# pipx
+pipx install deepwork
+
+# pip
+pip install deepwork
+```
+
+Then in your project folder (in terminal, not in Claude Code):
+
+```bash
+deepwork install
+```
+
+</details>
+
+<details>
+<summary><strong>Advanced: Nix Flakes</strong></summary>
+
+```bash
+# Development environment
+nix develop
+
+# Install from flake
+nix profile install github:Unsupervisedcom/deepwork
+
+# Run without installing
+nix run github:Unsupervisedcom/deepwork -- --help
+```
+
+</details>
+
+---
+
+## License
+
+Business Source License 1.1 (BSL 1.1). Free for non-competing use. Converts to Apache 2.0 on January 14, 2030.
+
+See [LICENSE.md](LICENSE.md) for details.
+
+---
+
+## Feedback
+
+We're iterating fast. [Open an issue](https://github.com/Unsupervisedcom/deepwork/issues) or reach out on Twitter [@tylerwillis](https://twitter.com/tylerwillis).
+
+---
+
+*DeepWork is in active development. Expect rough edges—and rapid improvement.*
+
+---
+
+<sub>Inspired by [GitHub's spec-kit](https://github.com/github/spec-kit)</sub>

deepwork-0.7.0.dist-info/RECORD

@@ -0,0 +1,64 @@
+deepwork/__init__.py,sha256=0Hf2rcJ94XxP2GKJUYlgAhlfagnYfpRIaqt-nM7kzgQ,748
+deepwork/cli/__init__.py,sha256=3SqmfcP2xqutiCYAbajFDJTjr2pOLydqTN0NN-FTsIE,33
+deepwork/cli/hook.py,sha256=ATZJLV-J_GAHyly24lVIMvpsEY1o_-njbFrqrYg1NoM,2059
+deepwork/cli/install.py,sha256=yrtT5k8x2CgUtdvNwjPJcSbaqKblC9cF1kGspYJXjTQ,13846
+deepwork/cli/main.py,sha256=InzlQcFoY0aQrY13cK1k6aI7nbF5XOMBNcqf8qCmegU,616
+deepwork/cli/serve.py,sha256=GGc1gkVkFG3X_1B1qVxB7nPQ3yVfO_hgCJVexPD6_1A,3192
+deepwork/cli/sync.py,sha256=DAmV6EcFEK5XgCW_mYxVjGwxvTg1LrGc5PZe7-Wza0s,8877
+deepwork/core/__init__.py,sha256=1g869QuwsYzNjQONneng2OMc6HKt-tlBCaxJbMMfoho,36
+deepwork/core/adapters.py,sha256=PfQFcp8m5wC4b5SM7PpUjtXBcMaIE5UmWoJ4-NYEDhI,21178
+deepwork/core/detector.py,sha256=PThpFLH-ZVL8UqjVdGSnGA0mFbhc6_rp6V3_Yzw97kI,2466
+deepwork/core/doc_spec_parser.py,sha256=DF1B3Ku9XHxTjRN12b1DatkwTa0HlwpPbeJCL4teobU,5739
+deepwork/core/generator.py,sha256=LE11uECWduyUw3V1FaZVDVCEom2veEd7ibeFt4XHdiY,3559
+deepwork/core/hooks_syncer.py,sha256=LR89s_50KqzcPX5KmARxy9Ju3SUEUzrZhRx2cCz301A,7482
+deepwork/core/parser.py,sha256=_x7LN_KnOgV6inUFgbeCIRHWohURgUKdFuNf165-vJ4,20945
+deepwork/hooks/README.md,sha256=V1sBcgbnF-BDL3wxcyayzL91cANsrjx6eMriLpQk9UA,3655
+deepwork/hooks/__init__.py,sha256=biE0wPFmUcuV5YtwffbNUxMZb7s1SQ_mS7PuiSPyXQc,1904
+deepwork/hooks/check_version.sh,sha256=X6fw97pMk6Yu1-w5UDzvZtKmpKVzsh1cum_RWp3b90g,10032
+deepwork/hooks/claude_hook.sh,sha256=ViV8Cc9eLRwsyZ7T1tNP-kK3leAmFjbcjOOSU3NN-eE,1321
+deepwork/hooks/gemini_hook.sh,sha256=eUczJ3VUL5-q5Ic8V_WYpn5Ff_m2oliJ0FXMWaHi9jM,1316
+deepwork/hooks/wrapper.py,sha256=HX_LtS5vfv-ZUhtR5jZqZCNBe90QPwW4ij9q-aRqbic,12956
+deepwork/mcp/__init__.py,sha256=cqnLb_PW8ouGHOI-fw52efwVkFjRS0ttMZi_bVgNSVs,720
+deepwork/mcp/quality_gate.py,sha256=sURtwC3CaoWEZXHK_d68B__WEnyaPKIEZgPM9Hg3VQc,11340
+deepwork/mcp/schemas.py,sha256=IusmeXK8TMLbiuxbIaYBMQy4zBvGveDWqOi-TJpftIY,10124
+deepwork/mcp/server.py,sha256=iXw35DW9dUhXhleY0LV2yP3wbNS_aRY1uIZu9SNrSB8,9228
+deepwork/mcp/state.py,sha256=DcUt6j6zczfMTihkwDamFkHjouROCHiX31lSYZSaD0M,13721
+deepwork/mcp/tools.py,sha256=-pROXOeK1Gc7UgZ-TZH1yo49z6Rr0ZoND7yCGOZDso4,13449
+deepwork/schemas/__init__.py,sha256=PpydKb_oaTv8lYapN_nV-Tl_OUCoSM_okvsEJ8gNTpI,41
+deepwork/schemas/doc_spec_schema.py,sha256=qByBtd86vQaLNsLfMr4iwVdpmyowvVLzYOnXY7RnqLY,2049
+deepwork/schemas/job.schema.json,sha256=a5gPAyoaBtVnu7U7aNa9iL2g5Bwa1S8Atjo6rD10l50,11095
+deepwork/schemas/job_schema.py,sha256=FT9Xn3Em85YEc2aTu71TGzdmunNhIztRymSG5N4vuhs,925
+deepwork/standard_jobs/deepwork_jobs/AGENTS.md,sha256=Y6I4jZ8DfN0RFY3UF5bgQRZvL7wQD9P0lgE7EZM6CGI,2252
+deepwork/standard_jobs/deepwork_jobs/job.yml,sha256=wQgbjblsDCWmaKWoBM81HuFX0aBsWtXv8c-dKTfQ-6g,12268
+deepwork/standard_jobs/deepwork_jobs/make_new_job.sh,sha256=JArfFU9lEaJPRsXRL3rU1IMt2p6Bq0s2C9f98aJ7Mxg,3878
+deepwork/standard_jobs/deepwork_jobs/doc_specs/job_spec.md,sha256=n9s70pSOjG1p6YX_72-TZ16pKIHaljeM2LnwOlrAfo0,7317
+deepwork/standard_jobs/deepwork_jobs/steps/define.md,sha256=K0eKBDze7CKwC8uKBwTOXLT7Ya46g3GdGxyqyn3CfVI,19856
+deepwork/standard_jobs/deepwork_jobs/steps/errata.md,sha256=1SjLCLc8xHlxGzFXZHn9Ch2tDTxZOyKKQ-B7RI651jw,4807
+deepwork/standard_jobs/deepwork_jobs/steps/fix_jobs.md,sha256=OHFX1ZuBjo_gWyFfC_HICay6J6eNZrm2IxzGT3IPxec,6074
+deepwork/standard_jobs/deepwork_jobs/steps/fix_settings.md,sha256=SJqeO_wuxcr7IzwFSlf3CmZ5ILivbvQK8YyYUc-FD4E,5361
+deepwork/standard_jobs/deepwork_jobs/steps/implement.md,sha256=6RVnS5sJpyrtGFhti5c2Dfzy6obvGJHWPHe3Hrc9SbM,5731
+deepwork/standard_jobs/deepwork_jobs/steps/iterate.md,sha256=JQkP-RMlbsnLpA3YH_yULUgHTOQx2ilSqI2gRsjPBhc,8405
+deepwork/standard_jobs/deepwork_jobs/steps/learn.md,sha256=moPKLTtYK4TGMTWmBKZO-OX__l52Cri3B6ecMoFB9kM,11630
+deepwork/standard_jobs/deepwork_jobs/steps/supplemental_file_references.md,sha256=uKDEwB3TxMLK-Zim3QQfkvaW5W6AVWHjWnH25aY6wCw,1478
+deepwork/standard_jobs/deepwork_jobs/steps/test.md,sha256=MNoVqo9CC-lnvWvllkOtIRopHvYMSR8yJrMZa02x1i0,6816
+deepwork/standard_jobs/deepwork_jobs/templates/agents.md.template,sha256=SUJL862C6-DnT9lK3sNIZ5T2wVgXN4YRph4FrKtFnLo,739
+deepwork/standard_jobs/deepwork_jobs/templates/doc_spec.md.template,sha256=OXpkFTsEm4CVkJQmx7f6rUZ9My5rHeY_ncaygARjEpA,764
+deepwork/standard_jobs/deepwork_jobs/templates/job.yml.example,sha256=roRi6sIGFGmPCkoVW26HfuTBjAO8-pPsxI5-Gfg3rc0,2361
+deepwork/standard_jobs/deepwork_jobs/templates/job.yml.template,sha256=rlanRupKN73XUR48nF93Mm4pdL35Wa4IeZSKQs7QEWo,1912
+deepwork/standard_jobs/deepwork_jobs/templates/step_instruction.md.example,sha256=HXcjVaQz2HsDiA4ClnIeLvysVOGrFJ_5Tr-pm6dhdwc,2706
+deepwork/standard_jobs/deepwork_jobs/templates/step_instruction.md.template,sha256=6n9jFFuda4r549Oo-LBPKixFD3NvDl5MwEg5V7ItQBg,1286
+deepwork/templates/__init__.py,sha256=APvjx_u7eRUerw9yA_fJ1ZqCzYA-FWUCV9HCz0RgjOc,50
+deepwork/templates/claude/AGENTS.md,sha256=7ickAhY8fNWhNCXPMG5nm6Jmv-XJvDM0PKC41EiQKyU,1828
+deepwork/templates/claude/settings.json,sha256=jdaMq_vXnOA-Gto8pXAawIO09egV_-rTIX3DyJJr8RQ,401
+deepwork/templates/claude/skill-deepwork.md.jinja,sha256=3ZXerM_RipAGmEbubsrVB0NLGID5MP-SBCcPJvRWpmg,1487
+deepwork/templates/gemini/skill-deepwork.md.jinja,sha256=LGe6wEnG1_XGU6NkOV0oDm7lG1w4s7B3EnQddlnsER4,1491
+deepwork/utils/__init__.py,sha256=AtvE49IFI8Rg36O4cNIlzB-oxvkW3apFgXExn8GSk6s,38
+deepwork/utils/fs.py,sha256=TbkcGGqck4lborFerbBLrpVMDUz3E5ZaW6X0_B2t76k,4821
+deepwork/utils/git.py,sha256=J4tAB1zE6-WMAEHbarevhmSvvPLkeKBpiRv1UxUVwYk,3748
+deepwork/utils/validation.py,sha256=SyFg9fIu1JCDMbssQgJRCTUNToDNcINccn8lje-tjts,851
+deepwork/utils/yaml_utils.py,sha256=INHhOmzC38fh7HYKLrq7vmS3dcuNsigH7_U71erS-hw,3127
+deepwork-0.7.0.dist-info/METADATA,sha256=DXJFmPAwoz51ydikLv-kQEiKFf6NOFeeqr0oxeAeb3k,12368
+deepwork-0.7.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+deepwork-0.7.0.dist-info/entry_points.txt,sha256=RhJBySzm619kh-yIdsAyfFXInAlY8Jm-39FLIBcOj2s,51
+deepwork-0.7.0.dist-info/licenses/LICENSE.md,sha256=W0EtJVYf0cQ_awukOCW1ETwNSpV2RKqnAGfoOjyz_K8,4126
+deepwork-0.7.0.dist-info/RECORD,,

deepwork/cli/rules.py

@@ -1,32 +0,0 @@
-"""Rules command for DeepWork CLI."""
-
-import click
-from rich.console import Console
-
-from deepwork.core.rules_queue import RulesQueue
-
-console = Console()
-
-
-@click.group()
-def rules() -> None:
-    """Manage DeepWork rules and queue."""
-    pass
-
-
-@rules.command(name="clear_queue")
-def clear_queue() -> None:
-    """
-    Clear all entries from the rules queue.
-
-    Removes all JSON files from .deepwork/tmp/rules/queue/.
-    This is useful for resetting the queue between tests or after
-    manual verification of rule states.
-    """
-    queue = RulesQueue()
-    count = queue.clear()
-
-    if count == 0:
-        console.print("[yellow]Queue is already empty[/yellow]")
-    else:
-        console.print(f"[green]Cleared {count} queue entry/entries[/green]")

deepwork/core/command_executor.py

@@ -1,190 +0,0 @@
-"""Execute command actions for rules."""
-
-import shlex
-import subprocess
-from dataclasses import dataclass
-from pathlib import Path
-
-from deepwork.core.rules_parser import CommandAction
-
-
-@dataclass
-class CommandResult:
-    """Result of executing a command."""
-
-    success: bool
-    exit_code: int
-    stdout: str
-    stderr: str
-    command: str  # The actual command that was run
-
-
-def substitute_command_variables(
-    command_template: str,
-    file: str | None = None,
-    files: list[str] | None = None,
-    repo_root: Path | None = None,
-) -> str:
-    """
-    Substitute template variables in a command string.
-
-    Variables:
-    - {file} - Single file path
-    - {files} - Space-separated file paths
-    - {repo_root} - Repository root directory
-
-    Args:
-        command_template: Command string with {var} placeholders
-        file: Single file path (for run_for: each_match)
-        files: List of file paths (for run_for: all_matches)
-        repo_root: Repository root path
-
-    Returns:
-        Command string with variables substituted
-    """
-    result = command_template
-
-    if file is not None:
-        # Quote file path to prevent command injection
-        result = result.replace("{file}", shlex.quote(file))
-
-    if files is not None:
-        # Quote each file path individually
-        quoted_files = " ".join(shlex.quote(f) for f in files)
-        result = result.replace("{files}", quoted_files)
-
-    if repo_root is not None:
-        result = result.replace("{repo_root}", shlex.quote(str(repo_root)))
-
-    return result
-
-
-def execute_command(
-    command: str,
-    cwd: Path | None = None,
-    timeout: int = 60,
-) -> CommandResult:
-    """
-    Execute a command and capture output.
-
-    Args:
-        command: Command string to execute
-        cwd: Working directory (defaults to current directory)
-        timeout: Timeout in seconds
-
-    Returns:
-        CommandResult with execution details
-    """
-    try:
-        # Run command as shell to support pipes, etc.
-        result = subprocess.run(
-            command,
-            shell=True,
-            cwd=cwd,
-            capture_output=True,
-            text=True,
-            timeout=timeout,
-        )
-
-        return CommandResult(
-            success=result.returncode == 0,
-            exit_code=result.returncode,
-            stdout=result.stdout,
-            stderr=result.stderr,
-            command=command,
-        )
-
-    except subprocess.TimeoutExpired:
-        return CommandResult(
-            success=False,
-            exit_code=-1,
-            stdout="",
-            stderr=f"Command timed out after {timeout} seconds",
-            command=command,
-        )
-    except Exception as e:
-        return CommandResult(
-            success=False,
-            exit_code=-1,
-            stdout="",
-            stderr=str(e),
-            command=command,
-        )
-
-
-def run_command_action(
-    action: CommandAction,
-    trigger_files: list[str],
-    repo_root: Path | None = None,
-) -> list[CommandResult]:
-    """
-    Run a command action for the given trigger files.
-
-    Args:
-        action: CommandAction configuration
-        trigger_files: Files that triggered the rule
-        repo_root: Repository root path
-
-    Returns:
-        List of CommandResult (one per command execution)
-    """
-    results: list[CommandResult] = []
-
-    if action.run_for == "each_match":
-        # Run command for each file individually
-        for file_path in trigger_files:
-            command = substitute_command_variables(
-                action.command,
-                file=file_path,
-                repo_root=repo_root,
-            )
-            result = execute_command(command, cwd=repo_root)
-            results.append(result)
-
-    elif action.run_for == "all_matches":
-        # Run command once with all files
-        command = substitute_command_variables(
-            action.command,
-            files=trigger_files,
-            repo_root=repo_root,
-        )
-        result = execute_command(command, cwd=repo_root)
-        results.append(result)
-
-    return results
-
-
-def all_commands_succeeded(results: list[CommandResult]) -> bool:
-    """Check if all command executions succeeded."""
-    return all(r.success for r in results)
-
-
-def format_command_errors(
-    results: list[CommandResult],
-    rule_name: str | None = None,
-) -> str:
-    """Format detailed error messages from failed commands.
-
-    Args:
-        results: List of command execution results
-        rule_name: Optional rule name to include in error message
-
-    Returns:
-        Formatted error message with command, exit code, stdout, and stderr
-    """
-    errors: list[str] = []
-    for result in results:
-        if not result.success:
-            parts: list[str] = []
-            if rule_name:
-                parts.append(f"Rule: {rule_name}")
-            parts.append(f"Command: {result.command}")
-            parts.append(f"Exit code: {result.exit_code}")
-            if result.stdout and result.stdout.strip():
-                parts.append(f"Stdout:\n{result.stdout.strip()}")
-            if result.stderr and result.stderr.strip():
-                parts.append(f"Stderr:\n{result.stderr.strip()}")
-            if not result.stdout.strip() and not result.stderr.strip():
-                parts.append("(no output)")
-            errors.append("\n".join(parts))
-    return "\n\n".join(errors)