deepwork-rulesdefine

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):

---
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:

---
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:

---
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:

---
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:

---
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.

Job Context

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)

Required Inputs

User Parameters - Gather from user before starting:

• rule_purpose: What guideline or constraint should this rule enforce?

Work Branch

Use branch format: deepwork/deepwork_rules-[instance]-YYYYMMDD

• If on a matching work branch: continue using it
• If on main/master: create new branch with git checkout -b deepwork/deepwork_rules-[instance]-$(date +%Y%m%d)

Outputs

Required outputs:

• .deepwork/rules/{rule-name}.md

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

On Completion

1. Verify outputs are created
2. Inform user: "define complete, outputs: .deepwork/rules/{rule-name}.md"

This standalone skill can be re-run anytime.

Reference files: .deepwork/jobs/deepwork_rules/job.yml, .deepwork/jobs/deepwork_rules/steps/define.md