Merge branch 'main' into claude/require-compares-to-field-fwDHp

Author: nhorton

AGENTS.md

@@ -0,0 +1,86 @@
+# DeepWork - Agent Instructions
+
+This file contains critical instructions for AI agents working on this codebase.
+
+## CRITICAL: Job Type Classification
+
+When creating or modifying jobs in this repository, you MUST understand which type of job you are working with. There are exactly **three types of jobs**, each with a specific location and purpose.
+
+### 1. Standard Jobs (`src/deepwork/standard_jobs/`)
+
+**What they are**: Core jobs that are part of the DeepWork framework itself. These get automatically installed to every target repository when users run `deepwork install`.
+
+**Location**: `src/deepwork/standard_jobs/[job_name]/`
+
+**Current standard jobs**:
+- `deepwork_jobs` - Core job management (define, implement, learn)
+- `deepwork_rules` - Rules enforcement system
+
+**Editing rules**:
+- Source of truth is ALWAYS in `src/deepwork/standard_jobs/`
+- NEVER edit the installed copies in `.deepwork/jobs/` directly
+- After editing, run `deepwork install --platform claude` to sync
+
+### 2. Library Jobs (`library_jobs/`)
+
+**What they are**: Example or reusable jobs that any repository is welcome to use, but are NOT auto-installed. Users must explicitly copy or import these into their projects.
+
+**Location**: `library_jobs/[job_name]/`
+
+**Examples** (potential):
+- Competitive research workflows
+- Code review processes
+- Documentation generation
+- Release management
+
+**Editing rules**:
+- Edit directly in `library_jobs/[job_name]/`
+- These are templates/examples for users to adopt
+- Should be well-documented and self-contained
+
+### 3. Bespoke/Repo Jobs (`.deepwork/jobs/`)
+
+**What they are**: Jobs that are ONLY for this specific repository (the DeepWork repo itself). These are not distributed to users and exist only for internal development workflows.
+
+**Location**: `.deepwork/jobs/[job_name]/` (but NOT if the job also exists in `src/deepwork/standard_jobs/`)
+
+**Identifying bespoke jobs**: A job in `.deepwork/jobs/` is bespoke ONLY if it does NOT have a corresponding directory in `src/deepwork/standard_jobs/`.
+
+**Editing rules**:
+- Edit directly in `.deepwork/jobs/[job_name]/`
+- These are private to this repository
+- Run `deepwork sync` after changes to regenerate skills
+
+## IMPORTANT: When Creating New Jobs
+
+Before creating any new job, you MUST determine which type it should be. **If there is any ambiguity**, ask the user a structured question to clarify:
+
+```
+Which type of job should this be?
+1. Standard Job - Part of the DeepWork framework, auto-installed to all users
+2. Library Job - Reusable example that users can optionally adopt
+3. Bespoke Job - Only for this repository's internal workflows
+```
+
+### Decision Guide
+
+| Question | If Yes → |
+|----------|----------|
+| Should this be installed automatically when users run `deepwork install`? | Standard Job |
+| Is this a reusable pattern that other repos might want to copy? | Library Job |
+| Is this only useful for developing DeepWork itself? | Bespoke Job |
+
+## File Structure Summary
+
+```
+deepwork/
+├── src/deepwork/standard_jobs/    # Standard jobs (source of truth)
+│   ├── deepwork_jobs/
+│   └── deepwork_rules/
+├── library_jobs/                   # Library/example jobs
+│   └── [example_job]/
+└── .deepwork/jobs/                 # Installed standard jobs + bespoke jobs
+    ├── deepwork_jobs/              # ← Installed copy, NOT source of truth
+    ├── deepwork_rules/             # ← Installed copy, NOT source of truth
+    └── [bespoke_job]/              # ← Source of truth for bespoke only
+```

CHANGELOG.md

@@ -5,8 +5,32 @@ All notable changes to DeepWork will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [0.5.0] - 2026-01-18
+## [0.3.0] - 2026-01-18
 
+### Added
+- Cross-platform hook wrapper system for writing hooks once and running on multiple platforms
+  - `wrapper.py`: Normalizes input/output between Claude Code and Gemini CLI
+  - `claude_hook.sh` and `gemini_hook.sh`: Platform-specific shell wrappers
+  - `rules_check.py`: Cross-platform rule evaluation hook
+- Platform documentation in `doc/platforms/` with hook references and learnings
+- Claude Code platform documentation (`doc/platforms/claude/`)
+- `update.job` for maintaining standard jobs (#41)
+- `make_new_job.sh` script and templates directory for job scaffolding (#37)
+- Default rules template file created during `deepwork install` (#42)
+- Full e2e test suite: define → implement → execute workflow (#45)
+- Automated tests for all shell scripts and hook wrappers (#40)
+- Rules system v2 with frontmatter markdown format in `.deepwork/rules/`
+  - Detection modes: trigger/safety (default), set (bidirectional), pair (directional)
+  - Action types: prompt (show instructions), command (run idempotent commands)
+  - Variable pattern matching with `{path}` (multi-segment) and `{name}` (single-segment)
+  - Queue system in `.deepwork/tmp/rules/queue/` for state tracking and deduplication
+- New core modules:
+  - `pattern_matcher.py`: Variable pattern matching with regex-based capture
+  - `rules_queue.py`: Queue system for rule state persistence
+  - `command_executor.py`: Command action execution with variable substitution
+- Updated `rules_check.py` hook to use v2 system with queue-based deduplication
+
+### Changed
 - **BREAKING**: Refactored "commands" terminology to "skills" throughout the codebase
   - Directory structure changed from `.claude/commands/` to `.claude/skills/`
   - Directory structure changed from `.gemini/commands/` to `.gemini/skills/`
@@ -20,63 +44,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - Hidden steps use `user-invocable: false` in YAML frontmatter instead
   - The `exposed` field in job.yml now controls the `user-invocable` frontmatter setting
 - CLI output messages updated to use "skills" terminology
-
-### Migration Guide
-- Run `deepwork install --platform claude` to regenerate skills in the new location
-- Remove old `.claude/commands/` and `.gemini/commands/` directories manually
-- Update any custom code that imports `CommandGenerator` or `CommandLifecycleHook`
-
-## [0.4.1] - 2026-01-18
+- Standardized on "ask structured questions" phrasing across all jobs (#48)
+- deepwork_jobs bumped to v0.5.0, deepwork_rules to v0.2.0
+- Documentation updated with v2 rules examples and configuration
 
 ### Fixed
+- Stop hooks now properly return blocking JSON (#38)
+- Various CI workflow fixes (#35, #46, #47, #51, #52)
 - Command rule errors now include promise skip instructions with the exact rule name
   - Previously, failed command rules only showed "Command failed" with no guidance
   - Now each failed rule shows: `To skip, include <promise>Rule Name</promise> in your response`
   - This allows agents to understand how to proceed when a command rule fails
 
-
-## [0.4.0] - 2026-01-16
-
-### Added
-- Rules system v2 with frontmatter markdown format in `.deepwork/rules/`
-  - Detection modes: trigger/safety (default), set (bidirectional), pair (directional)
-  - Action types: prompt (show instructions), command (run idempotent commands)
-  - Variable pattern matching with `{path}` (multi-segment) and `{name}` (single-segment)
-  - Queue system in `.deepwork/tmp/rules/queue/` for state tracking and deduplication
-- New core modules:
-  - `pattern_matcher.py`: Variable pattern matching with regex-based capture
-  - `rules_queue.py`: Queue system for rule state persistence
-  - `command_executor.py`: Command action execution with variable substitution
-- Updated `rules_check.py` hook to use v2 system with queue-based deduplication
-
-### Changed
-- Documentation updated with v2 rules examples and configuration
-
 ### Removed
 - v1 rules format (`.deepwork.rules.yml`) - now only v2 frontmatter markdown format is supported
 
-## [0.3.0] - 2026-01-16
-
-### Added
-- Cross-platform hook wrapper system for writing hooks once and running on multiple platforms
-  - `wrapper.py`: Normalizes input/output between Claude Code and Gemini CLI
-  - `claude_hook.sh` and `gemini_hook.sh`: Platform-specific shell wrappers
-  - `rules_check.py`: Cross-platform rule evaluation hook
-- Platform documentation in `doc/platforms/` with hook references and learnings
-- Claude Code platform documentation (`doc/platforms/claude/`)
-- `update.job` for maintaining standard jobs (#41)
-- `make_new_job.sh` script and templates directory for job scaffolding (#37)
-- Default rules template file created during `deepwork install` (#42)
-- Full e2e test suite: define → implement → execute workflow (#45)
-- Automated tests for all shell scripts and hook wrappers (#40)
-
-### Changed
-- Standardized on "ask structured questions" phrasing across all jobs (#48)
-- deepwork_jobs bumped to v0.5.0, deepwork_rules to v0.2.0
-
-### Fixed
-- Stop hooks now properly return blocking JSON (#38)
-- Various CI workflow fixes (#35, #46, #47, #51, #52)
+### Migration Guide
+- Run `deepwork install --platform claude` to regenerate skills in the new location
+- Remove old `.claude/commands/` and `.gemini/commands/` directories manually
+- Update any custom code that imports `CommandGenerator` or `CommandLifecycleHook`
 
 ## [0.1.1] - 2026-01-15
 
@@ -114,8 +100,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 Initial version.
 
-[0.4.1]: https://github.com/anthropics/deepwork/releases/tag/0.4.1
-[0.4.0]: https://github.com/anthropics/deepwork/releases/tag/0.4.0
 [0.3.0]: https://github.com/anthropics/deepwork/releases/tag/0.3.0
 [0.1.1]: https://github.com/anthropics/deepwork/releases/tag/0.1.1
 [0.1.0]: https://github.com/anthropics/deepwork/releases/tag/0.1.0

claude.md

@@ -42,10 +42,12 @@ deepwork/
 │   │   ├── claude/
 │   │   ├── gemini/
 │   │   └── copilot/
-│   ├── standard_jobs/    # Built-in job definitions
-│   │   └── deepwork_jobs/
+│   ├── standard_jobs/    # Built-in job definitions (auto-installed)
+│   │   ├── deepwork_jobs/
+│   │   └── deepwork_rules/
 │   ├── schemas/          # Job definition schemas
 │   └── utils/            # Utilities (fs, git, yaml, validation)
+├── library_jobs/         # Reusable example jobs (not auto-installed)
 ├── tests/                # Test suite
 ├── doc/                  # Documentation
 └── doc/architecture.md   # Detailed architecture document
@@ -182,16 +184,24 @@ my-project/
 6. **No Auto-Commit**: DO NOT automatically commit changes to git. Let the user review and commit changes themselves.
 7. **Documentation Sync**: CRITICAL - When making implementation changes, always update `doc/architecture.md` and `README.md` to reflect those changes. The architecture document must stay in sync with the actual codebase (terminology, file paths, structure, behavior, etc.).
 
-## CRITICAL: Editing Standard Jobs
+## CRITICAL: Job Types and Where to Edit
+
+**See `AGENTS.md` for the complete job classification guide.** This repository has THREE types of jobs:
+
+| Type | Location | Purpose |
+|------|----------|---------|
+| **Standard Jobs** | `src/deepwork/standard_jobs/` | Framework core, auto-installed to users |
+| **Library Jobs** | `library_jobs/` | Reusable examples users can adopt |
+| **Bespoke Jobs** | `.deepwork/jobs/` (if not in standard_jobs) | This repo's internal workflows only |
+
+### Editing Standard Jobs
 
 **Standard jobs** (like `deepwork_jobs` and `deepwork_rules`) are bundled with DeepWork and installed to user projects. They exist in THREE locations:
 
 1. **Source of truth**: `src/deepwork/standard_jobs/[job_name]/` - The canonical source files
 2. **Installed copy**: `.deepwork/jobs/[job_name]/` - Installed by `deepwork install`
 3. **Generated skills**: `.claude/skills/[job_name].[step].md` - Generated from installed jobs
 
-### Editing Workflow for Standard Jobs
-
 **NEVER edit files in `.deepwork/jobs/` or `.claude/skills/` for standard jobs directly!**
 
 Instead, follow this workflow:
@@ -205,13 +215,13 @@ Instead, follow this workflow:
 
 3. **Verify** the changes propagated correctly to all locations
 
-### How to Identify Standard Jobs
+### How to Identify Job Types
 
-Standard jobs are defined in `src/deepwork/standard_jobs/`. Currently:
-- `deepwork_jobs` - Core job management commands (define, implement, refine)
-- `deepwork_rules` - Rules enforcement system
+- **Standard jobs**: Exist in `src/deepwork/standard_jobs/` (currently: `deepwork_jobs`, `deepwork_rules`)
+- **Library jobs**: Exist in `library_jobs/`
+- **Bespoke jobs**: Exist ONLY in `.deepwork/jobs/` with no corresponding standard_jobs entry
 
-If a job exists in `src/deepwork/standard_jobs/`, it is a standard job and MUST be edited there.
+**When creating a new job, always clarify which type it should be.** If uncertain, ask the user.
 
 ## Success Metrics
 

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "deepwork"
-version = "0.5.0"
+version = "0.3.0"
 description = "Framework for enabling AI agents to perform complex, multi-step work tasks"
 readme = "README.md"
 requires-python = ">=3.11"