Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
21 commits
Select commit Hold shift + click to select a range
4bf6037
Add policy system v2 design documentation
claude Jan 16, 2026
cf8b7e2
Feedback from review
nhorton Jan 16, 2026
64d994a
Simplify policy system design based on feedback
claude Jan 16, 2026
cd0597e
Remove idempotency verification and unused output_mode config
claude Jan 16, 2026
4d9b5e9
Implement policy system v2 with sets, pairs, and command actions
claude Jan 16, 2026
d4bb783
Update documentation and version for policy system v2
claude Jan 16, 2026
1f95c13
Update policy_stop_hook.sh to support both v1 and v2 policy formats
claude Jan 16, 2026
3c47aa7
Remove v1 policy format support
claude Jan 16, 2026
84eb741
Format policy_parser.py with ruff
claude Jan 16, 2026
76f138c
Update uv.lock
claude Jan 16, 2026
e209e6f
Rename policy system to rules system
nhorton Jan 17, 2026
aa77a79
Remove stale deepwork_policy hook entries from settings.json
nhorton Jan 17, 2026
5911dcb
Add comprehensive test coverage and fix security/linting issues
nhorton Jan 17, 2026
5051f79
Complete migration from v1 to v2 rules format
nhorton Jan 17, 2026
34484a3
Fix hook exit code to always return 0 with JSON format
nhorton Jan 17, 2026
53a3202
Add critical contract warning comments to hook test files
nhorton Jan 17, 2026
0ce890e
Merge hook test files into single test_hooks.py
nhorton Jan 17, 2026
ead2c2b
Format code with ruff
nhorton Jan 17, 2026
78ed5d9
Fix ruff linting errors (unused imports, import sorting)
nhorton Jan 17, 2026
cf756dd
Cleanup hooks and wrappers
nhorton Jan 17, 2026
66f2032
Create manual test files for rule styles (#61)
nhorton Jan 17, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions .claude/commands/add_platform.verify.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ hooks:
2. Running `deepwork install --platform <platform>` completes without errors
3. Expected command files are created in the platform's command directory
4. Command file content matches the templates and job definitions
5. Established DeepWork jobs (deepwork_jobs, deepwork_policy) are installed correctly
5. Established DeepWork jobs (deepwork_jobs, deepwork_rules) are installed correctly
6. The platform can be used alongside existing platforms without conflicts

If ALL criteria are met, include `<promise>✓ Quality Criteria Met</promise>`.
Expand Down Expand Up @@ -121,7 +121,7 @@ Ensure the implementation step is complete:
- `deepwork_jobs.define.md` exists (or equivalent for the platform)
- `deepwork_jobs.implement.md` exists
- `deepwork_jobs.refine.md` exists
- `deepwork_policy.define.md` exists
- `deepwork_rules.define.md` exists
- All expected step commands exist

4. **Validate command file content**
Expand Down Expand Up @@ -151,7 +151,7 @@ Ensure the implementation step is complete:
- `deepwork install --platform <platform_name>` completes without errors
- All expected command files are created:
- deepwork_jobs.define, implement, refine
- deepwork_policy.define
- deepwork_rules.define
- Any other standard job commands
- Command file content is correct:
- Matches platform's expected format
Expand Down Expand Up @@ -218,7 +218,7 @@ Verify the installation meets ALL criteria:
2. Running `deepwork install --platform <platform>` completes without errors
3. Expected command files are created in the platform's command directory
4. Command file content matches the templates and job definitions
5. Established DeepWork jobs (deepwork_jobs, deepwork_policy) are installed correctly
5. Established DeepWork jobs (deepwork_jobs, deepwork_rules) are installed correctly
6. The platform can be used alongside existing platforms without conflicts

If ALL criteria are met, include `<promise>✓ Quality Criteria Met</promise>`.
Expand Down
50 changes: 25 additions & 25 deletions .claude/commands/deepwork_jobs.implement.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,9 +19,9 @@ hooks:
6. **Ask Structured Questions**: Do step instructions that gather user input explicitly use the phrase "ask structured questions"?
7. **Sync Complete**: Has `deepwork sync` been run successfully?
8. **Commands Available**: Are the slash-commands generated in `.claude/commands/`?
9. **Policies Considered**: Have you thought about whether policies would benefit this job?
- If relevant policies were identified, did you explain them and offer to run `/deepwork_policy.define`?
- Not every job needs policies - only suggest when genuinely helpful.
9. **Rules Considered**: Have you thought about whether rules would benefit this job?
- If relevant rules were identified, did you explain them and offer to run `/deepwork_rules.define`?
- Not every job needs rules - only suggest when genuinely helpful.

If ANY criterion is not met, continue working to address it.
If ALL criteria are satisfied, include `<promise>✓ Quality Criteria Met</promise>` in your response.
Expand Down Expand Up @@ -200,48 +200,48 @@ This will:

After running `deepwork sync`, look at the "To use the new commands" section in the output. **Relay these exact reload instructions to the user** so they know how to pick up the new commands. Don't just reference the sync output - tell them directly what they need to do (e.g., "Type 'exit' then run 'claude --resume'" for Claude Code, or "Run '/memory refresh'" for Gemini CLI).

### Step 7: Consider Policies for the New Job
### Step 7: Consider Rules for the New Job

After implementing the job, consider whether there are **policies** that would help enforce quality or consistency when working with this job's domain.
After implementing the job, consider whether there are **rules** that would help enforce quality or consistency when working with this job's domain.

**What are policies?**
**What are rules?**

Policies are automated guardrails defined in `.deepwork.policy.yml` that trigger when certain files change during an AI session. They help ensure:
Rules are automated guardrails stored as markdown files in `.deepwork/rules/` that trigger when certain files change during an AI session. They help ensure:
- Documentation stays in sync with code
- Team guidelines are followed
- Architectural decisions are respected
- Quality standards are maintained

**When to suggest policies:**
**When to suggest rules:**

Think about the job you just implemented and ask:
- Does this job produce outputs that other files depend on?
- Are there documentation files that should be updated when this job's outputs change?
- Are there quality checks or reviews that should happen when certain files in this domain change?
- Could changes to the job's output files impact other parts of the project?

**Examples of policies that might make sense:**
**Examples of rules that might make sense:**

| Job Type | Potential Policy |
|----------|------------------|
| Job Type | Potential Rule |
|----------|----------------|
| API Design | "Update API docs when endpoint definitions change" |
| Database Schema | "Review migrations when schema files change" |
| Competitive Research | "Update strategy docs when competitor analysis changes" |
| Feature Development | "Update changelog when feature files change" |
| Configuration Management | "Update install guide when config files change" |

**How to offer policy creation:**
**How to offer rule creation:**

If you identify one or more policies that would benefit the user, explain:
1. **What the policy would do** - What triggers it and what action it prompts
If you identify one or more rules that would benefit the user, explain:
1. **What the rule would do** - What triggers it and what action it prompts
2. **Why it would help** - How it prevents common mistakes or keeps things in sync
3. **What files it would watch** - The trigger patterns

Then ask the user:

> "Would you like me to create this policy for you? I can run `/deepwork_policy.define` to set it up."
> "Would you like me to create this rule for you? I can run `/deepwork_rules.define` to set it up."

If the user agrees, invoke the `/deepwork_policy.define` command to guide them through creating the policy.
If the user agrees, invoke the `/deepwork_rules.define` command to guide them through creating the rule.

**Example dialogue:**

Expand All @@ -250,15 +250,15 @@ Based on the competitive_research job you just created, I noticed that when
competitor analysis files change, it would be helpful to remind you to update
your strategy documentation.

I'd suggest a policy like:
I'd suggest a rule like:
- **Name**: "Update strategy when competitor analysis changes"
- **Trigger**: `**/positioning_report.md`
- **Action**: Prompt to review and update `docs/strategy.md`

Would you like me to create this policy? I can run `/deepwork_policy.define` to set it up.
Would you like me to create this rule? I can run `/deepwork_rules.define` to set it up.
```

**Note:** Not every job needs policies. Only suggest them when they would genuinely help maintain consistency or quality. Don't force policies where they don't make sense.
**Note:** Not every job needs rules. Only suggest them when they would genuinely help maintain consistency or quality. Don't force rules where they don't make sense.

## Example Implementation

Expand Down Expand Up @@ -292,8 +292,8 @@ Before marking this step complete, ensure:
- [ ] `deepwork sync` executed successfully
- [ ] Commands generated in platform directory
- [ ] User informed to follow reload instructions from `deepwork sync`
- [ ] Considered whether policies would benefit this job (Step 7)
- [ ] If policies suggested, offered to run `/deepwork_policy.define`
- [ ] Considered whether rules would benefit this job (Step 7)
- [ ] If rules suggested, offered to run `/deepwork_rules.define`

## Quality Criteria

Expand All @@ -305,7 +305,7 @@ Before marking this step complete, ensure:
- Steps with user inputs explicitly use "ask structured questions" phrasing
- Sync completed successfully
- Commands available for use
- Thoughtfully considered relevant policies for the job domain
- Thoughtfully considered relevant rules for the job domain


## Inputs
Expand Down Expand Up @@ -355,9 +355,9 @@ Verify the implementation meets ALL quality criteria before completing:
6. **Ask Structured Questions**: Do step instructions that gather user input explicitly use the phrase "ask structured questions"?
7. **Sync Complete**: Has `deepwork sync` been run successfully?
8. **Commands Available**: Are the slash-commands generated in `.claude/commands/`?
9. **Policies Considered**: Have you thought about whether policies would benefit this job?
- If relevant policies were identified, did you explain them and offer to run `/deepwork_policy.define`?
- Not every job needs policies - only suggest when genuinely helpful.
9. **Rules Considered**: Have you thought about whether rules would benefit this job?
- If relevant rules were identified, did you explain them and offer to run `/deepwork_rules.define`?
- Not every job needs rules - only suggest when genuinely helpful.

If ANY criterion is not met, continue working to address it.
If ALL criteria are satisfied, include `<promise>✓ Quality Criteria Met</promise>` in your response.
Expand Down
Loading