CHANGELOG.md

Changelog

All notable changes to DeepWork will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

Unreleased

Added

• review_depth: lightweight annotation for review blocks in job.yml step outputs and .deepreview rules — when set, the workflow's common_job_info preamble is omitted from review instruction files, reducing token overhead for trivial or reversible intermediate steps (closes #86)
• Hung-reviewer retry policy in quality gate guidance: reviewers completing with 0 tool uses are retried up to REVIEWER_MAX_RETRIES (default: 1) times before being skipped with a "manual review recommended" note; fast-fails (elapsed < REVIEWER_FAST_FAIL_SECONDS, default: 30s) are retried immediately (closes #408)

Changed

Fixed

Removed

0.14.0 - 2026-04-20

Added

• New PLUG-REQ-001.15: Hook Script CLI Invocation requirement in doc/specs/deepwork/cli_plugins/PLUG-REQ-001-claude-code-plugin.md

Changed

• claude_plugin_hook_deepwork_invocation review rule now requires plugin hook scripts to invoke the CLI via uvx deepwork instead of merely providing a uvx deepwork fallback (PLUG-REQ-001.15)
• Plugin hook scripts (post_commit_reminder.sh, deepschema_write.sh, post_compact.sh) now invoke the deepwork CLI exclusively via uvx deepwork ..., matching the MCP server launch in plugins/claude/.mcp.json
• Flake shellHook no longer runs uv tool install -e — the editable user-level deepwork install is redundant now that plugin hooks go through uvx

Fixed

• Plugin hooks no longer fail when the end user has a stale user-level deepwork install (e.g., uv tool install deepwork pinned to an older release) that wins PATH lookup but lacks the hook module being requested. The 0.13.9 fallback still used PATH first; this release bypasses PATH entirely so hooks resolve to the same uvx cache that the MCP server populated

Removed

0.13.9 - 2026-04-16

Added

• New claude_plugin_hook_deepwork_invocation review rule in plugins/claude/.deepreview that flags plugin hook scripts which call bare deepwork without a uvx deepwork fallback

0.13.8 - 2026-04-14

Added

Changed

• Renamed default reviewer agent from reviewer to deepwork:reviewer (plugin-namespaced) in review instructions output
• /review skill now checks for deepwork:reviewer agent availability before proceeding and directs users to /reload-plugins if missing

Fixed

Removed

0.13.7 - 2026-04-14

Added

Changed

Fixed

Removed

0.13.6 - 2026-04-14

Added

Changed

• Deprecated the steps/ folder pattern for job definitions — step instructions are now inlined in job.yml; moved supplemental reference files from steps/ to job root directories
• Repair workflow now instructs agents to git rm step instruction files after inlining
• Moved specs/ to doc/specs/ and consolidated docs/ into doc/ to reduce root directory clutter

Removed

• coverage_report.md (stale snapshot)
• job_refactor.md (superseded planning notes)
• CLAUDE_PLUGINS_README.md (redundant with README.md)

Fixed

Removed

0.13.5 - 2026-04-12

Added

Changed

Fixed

Removed

0.13.4 - 2026-04-11

Added

Changed

• Post-commit review reminder hook now short-circuits when all applicable (non-catch-all) review rules for the committed files are already marked as passed, emitting "No re-review needed" instead of nagging
• Renamed all "Task tool" references to "Agent tool" across codebase to match Claude Code's current tool naming
• Review formatter now emits description, subagent_type, and prompt fields (dropped name field) to match Agent tool signature
• Hook wrapper tool mappings updated: Task/task → Agent/agent

Fixed

• Review instruction files now include a ## Project Root directive stating the absolute project root so reviewer subagents read files from the correct working tree — fixes spurious findings in git-worktree setups where the subagent's cwd differed from the worktree the commits actually lived in (REVIEW-REQ-005.1.9)

Removed

• Removed automatic DeepPlan workflow injection from startup_context.sh hook (no longer forces plan mode into DeepPlan)
• Deprecated JOBS-REQ-014.5.1 (startup hook DeepPlan trigger) and REVIEW-REQ-006.3.3a (name field in review output)

0.13.3 - 2026-04-10

Added

• /record skill: "watch and learn" approach to creating DeepWork workflows — users do their work normally, then /deepwork learn turns it into a repeatable job
• /new_user skill: guided onboarding that introduces DeepWork, offers review rule setup for code projects, and offers to record a first workflow
• /deepwork learn now routes to the new_job workflow when invoked after /deepwork:record
• Requirements specs PLUG-REQ-002 (record skill) and PLUG-REQ-003 (new user skill)
• Anonymous DeepSchemas for both new skills

Changed

• README install commands consolidated into a single &&-joined command ending with /deepwork:new_user
• deepwork setup now opens https://www.deepwork.md/success in the default browser after completing configuration

Fixed

Removed

0.13.2 - 2026-04-09

Added

• deepwork setup CLI command that auto-configures Claude Code settings (marketplace, plugin, MCP permissions, auto-update) (#343)
• deepwork setup also grants project-root-relative Read/Write/Edit permissions for /.deepwork/**/* so the plugin can operate on .deepwork/ in every project without per-prompt approval
• Integration tests for quality gate review caching (JOBS-REQ-004.5.7)
• Requirements traceability coverage now at 100% (#346)
  • Added section-level REQ ID annotations to 32 existing test files for traceability
  • Wrote 218 new tests across 5 files for learning-agents requirements (LA-REQ-001, 003, 004, 005, 006, 010, 011)
  • Added 6 anonymous DeepSchemas for judgment-based learning-agents skill requirements (LA-REQ-002, 007, 008, 009, 012)
  • Added new PLUG-REQ-001.12 tests for session/agent identity injection hooks
  • New req-ids-in-comments requirement in the standard DeepSchema definition: requirement IDs must be placed in YAML comments, not requirement body text

Changed

• JOBS-REQ-004.5.7 strengthened to explicit MUST requirement for skipping already-passed reviews

Fixed

• DeepSchema PostToolUse hook (deepschema_write) no longer reports File is not valid JSON for YAML files whose name has no extension (e.g. .deepreview). The hook now parses target files and the referenced JSON Schema as YAML, which is a superset of JSON, so both formats are accepted regardless of file extension. DW-REQ-011.7.3 updated to match. (Mirrors the fix shipped in #338 for the workflow quality gate.)
• review: blocks declared on type: string step outputs are now actually executed. Previously they were silently dropped because the review pipeline only matched against file paths, leaving authors with misconfigured-but-silent quality gates. String output reviews now produce synthetic ReviewTask objects with the string value carried on a new ReviewTask.inline_content field and rendered into the instruction file as a "Content to Review" section. New requirements: JOBS-REQ-004.8, REVIEW-REQ-005.1.8, REVIEW-REQ-009.1.7. (#350)

Removed

0.13.1 - 2026-04-06

Added

Changed

Fixed

Removed

0.13.0 - 2026-04-03

Added

• Add DeepPlan — structured planning workflow that produces executable DeepWork job definitions (#331)
  • New deepplan standard job with create_deep_plan workflow (5 steps: explore, design alternatives, synthesize, enrich, present)
  • New register_session_job and get_session_job MCP tools for transient session-scoped job definitions
  • New /deepplan skill for Claude Code plugin
  • Startup context hook auto-triggers DeepPlan when entering plan mode
  • Session jobs are discoverable by start_workflow and take priority over standard discovery
• /review skill now checks changelog accuracy and PR description during reviews (#331)
• .deepreview rules can now declare a precomputed_info_for_reviewer_bash_command that runs before the review and injects stdout into the instruction file as precomputed context (#337)
  • Commands run in parallel across rules with a 60-second timeout and graceful error handling
  • Applied to requirements_traceability and python_lint rules to eliminate redundant agent tool calls
• New deepreview standard DeepSchema with semantic quality requirements for .deepreview config files (#337)
• Makefile with lint target that auto-fixes formatting/linting and runs type checking (#337)

Changed

Fixed

• Quality gate validate_json_schemas() now uses yaml.safe_load (a JSON superset) instead of json.loads, so YAML output files are validated correctly

Removed

0.12.0 - 2026-04-03

Added

Changed

Fixed

Removed

0.11.0 - 2026-03-31

Added

Changed

Fixed

Removed

0.10.0 - 2026-03-29

Added

Changed

Fixed

Removed

0.9.8 - 2026-03-26

Added

Changed

Fixed

Removed

0.9.7 - 2026-03-24

Added

• Add shared_jobs workflow for installing library jobs from the DeepWork library (#273)
• Add research job to library (moved from standard jobs) (#274)
• Add platform_engineer job to library (#268)
• Add repo job for repository setup and health auditing (#266)
• Add slash command creation guide to shared jobs readme (#277)

Changed

• Rewrite README around "trustworthy agents" framing and enrich Reviews coverage (#271)
• Require DRY and comment accuracy in language convention files (#267)
• Shared_jobs workflow references library jobs instead of copying (#275)

Fixed

Removed

0.9.6 - 2026-03-09

Added

• Add file-based status reporting for external consumers (#257)
• Add AGENTS.md → CLAUDE.md symlink rule and create symlinks for existing files (#259)

Changed

• Refactor state management to use session-scoped persistent storage (#255)
• Harden e2e CI tests and copy job schema at MCP startup (#252)

Fixed

Removed

0.9.5 - 2026-03-03

Added

Changed

Fixed

Removed

0.9.4 - 2026-03-02

Added

Changed

Fixed

Removed

0.9.3 - 2026-02-27

Added

Changed

Fixed

Removed

0.9.2 - 2026-02-24

Added

Changed

Fixed

Removed

0.9.1 - 2026-02-23

Added

Changed

Fixed

Removed

0.9.0 - 2026-02-22

Added

Changed

Fixed

Removed

0.8.0 - 2026-02-16

Added

Changed

Fixed

[0.7.0] - 2026-02-05

Added

• MCP Server Architecture - New Model Context Protocol server for checkpoint-based workflow execution
• Improved deepwork_jobs steps for workflow management
• JSON Schema for job.yml validation (src/deepwork/schemas/job.schema.json)
• Reference documentation for calling Claude in print mode (doc/reference/calling_claude_in_print_mode.md)
• Migrated to uv2nix for reproducible Python builds in flake.nix

Changed

• BREAKING: Simplified skill generation to single /deepwork entry point skill
• BREAKING: Workflow execution now happens through MCP tool calls instead of slash commands
• Streamlined deepwork_jobs.define and deepwork_jobs.implement for MCP workflow
• Updated deepwork_jobs.learn with simplified instructions
• Simplified adapter templates - removed complex skill templates
• MCP server registered in .claude/settings.json during install

Removed

• BREAKING: Rules system removed
• BREAKING: Removed per-step skill generation templates and logic
• Removed per-step skill generation templates and logic
• Removed commit job from library (was example job)
• Removed manual_tests/ directory and manual_tests job
• Removed add_platform bespoke job
• Removed many hook scripts that are no longer needed with MCP architecture
• Removed Gemini per-step skill templates (.gemini/skills/ now only has entry point)

Migration Guide

• Run deepwork install to get the new MCP server configuration
• Workflows are now executed via /deepwork which uses MCP tools internally
• Rules system is completely removed - consider implementing validation logic in quality criteria instead
• Existing job definitions still work but are executed through MCP checkpoints
• The .deepwork/rules/ directory can be safely deleted

0.5.1 - 2026-01-24

Added

Changed

Fixed

Removed

0.5.0 - 2026-01-24

Added

• Installer now auto-adds permission for make_new_job.sh script, allowing Claude to run job creation without manual configuration
• Manual release workflow (create-release.yml) that automates version releases:
  • Takes version number as input, validates format
  • Updates CHANGELOG.md: converts Unreleased section to new version with date
  • Adds fresh Unreleased section with placeholder categories
  • Updates pyproject.toml version and runs uv sync for lock file
  • Commits changes directly to main, creates tag, and publishes GitHub release

Changed

• Commit job now requires changelog entries go to [Unreleased] section and explicitly prohibits modifying version numbers

Fixed

Removed

0.4.2 - 2026-01-24

Changed

• Added closing tag comments to jinja templates for improved readability

0.4.1 - 2026-01-23

Changed

• Disabled prompt-based stop hooks in Claude templates due to upstream bug (#20221)
• Quality validation now uses sub-agent review pattern instead of prompt hooks

0.4.0 - 2026-01-23

Added

• Doc specs (document specifications) as a first-class feature for formalizing document quality criteria
  • New src/deepwork/schemas/doc_spec_schema.py with JSON schema validation
  • New src/deepwork/core/doc_spec_parser.py with parser for frontmatter markdown doc spec files
  • Doc spec files stored in .deepwork/doc_specs/ directory with quality criteria and example documents
  • Auto-creates .deepwork/doc_specs/ directory during deepwork install
• Extended job.yml output schema to support doc spec references
  • Outputs can now be strings (backward compatible) or objects with file and optional doc_spec fields
  • Example: outputs: [{file: "report.md", doc_spec: ".deepwork/doc_specs/monthly_report.md"}]
  • The doc_spec uses the full path to the doc spec file, making references self-documenting
• Doc spec-aware skill generation
  • Step skills now include doc spec quality criteria, target audience, and example documents
  • Both Claude and Gemini templates updated for doc spec rendering
• Document detection workflow in deepwork_jobs.define
  • Steps 1.5, 1.6, 1.7 guide users through creating doc specs for document-oriented jobs
  • Pattern indicators: "report", "summary", "create", "monthly", "for stakeholders"
• Doc spec improvement workflow in deepwork_jobs.learn
  • Steps 3.5, 4.5 capture doc spec-related learnings and update doc spec files
• New OutputSpec dataclass in parser for structured output handling
• Comprehensive doc spec documentation in doc/doc-specs.md
• New test fixtures for doc spec validation and parsing
• Comprehensive tests for generator doc spec integration (9 new tests)
  • test_load_doc_spec_returns_parsed_spec - Verifies doc spec loading
  • test_load_doc_spec_caches_result - Verifies caching behavior
  • test_load_doc_spec_returns_none_for_missing_file - Graceful handling of missing files
  • test_generate_step_skill_with_doc_spec - End-to-end skill generation with doc spec
  • test_build_step_context_includes_doc_spec_info - Context building verification

Changed

• BREAKING: Renamed document_type to doc_spec throughout the codebase
  • Job.yml field: document_type → doc_spec (e.g., outputs: [{file: "report.md", doc_spec: ".deepwork/doc_specs/report.md"}])
  • Class: DocumentTypeDefinition → DocSpec (backward compat alias provided)
  • Methods: has_document_type() → has_doc_spec(), validate_document_type_references() → validate_doc_spec_references()
  • Template variables: has_document_type → has_doc_spec, document_type → doc_spec
  • Internal: _load_document_type() → _load_doc_spec(), _doc_type_cache → _doc_spec_cache
• Step.outputs changed from list[str] to list[OutputSpec] for richer output metadata
• SkillGenerator.generate_all_skills() now accepts project_root parameter for doc spec loading
• Updated deepwork_jobs to v0.6.0 with doc spec-related quality criteria

Fixed

• Fixed COMMAND rules promise handling to properly update queue status
  • When an agent provides a promise tag for a FAILED command rule, the queue entry is now correctly updated to SKIPPED status
  • Previously, FAILED queue entries remained in FAILED state even after being acknowledged via promise
  • This ensures the rules queue accurately reflects rule state throughout the workflow
• Fixed quality criteria validation logic in skill template (#111)
  • Changed promise condition from AND to OR: promise OR all criteria met now passes
  • Changed failure condition from OR to AND: requires both criteria NOT met AND promise missing to fail
  • This corrects the logic so the promise mechanism properly serves as a bypass for quality criteria

Migration Guide

• Update job.yml files: Change document_type: to doc_spec: in output definitions
• Update any code importing DocumentTypeDefinition: Use DocSpec instead (alias still works)
• Run deepwork install to regenerate skills with updated terminology

0.3.1 - 2026-01-20

Added

• created rule mode for matching only newly created files (#76)
  • Rules with mode: created only fire when files are first added, not on modifications
  • Useful for enforcing patterns on new files without triggering on existing file edits

Fixed

• Fixed created mode rules incorrectly firing on modified files (#83)
• Fixed compare_to: prompt mode not detecting files that were committed during agent response
  • Rules like uv-lock-sync now correctly fire even when changes are committed before the Stop hook runs

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/
  • Class renamed: CommandGenerator → SkillGenerator
  • Enum renamed: CommandLifecycleHook → SkillLifecycleHook
  • Class attributes renamed: commands_dir → skills_dir, command_template → skill_template
  • Methods renamed: get_commands_dir() → get_skills_dir(), generate_all_commands() → generate_all_skills(), etc.
  • Template files renamed: command-job-step.md.jinja → skill-job-step.md.jinja, etc.
• BREAKING: Removed uw. prefix convention for hidden steps
  • Step skills now use clean filenames (e.g., job_name.step_id.md instead of uw.job_name.step_id.md)
  • 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
• 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

Removed

• v1 rules format (.deepwork.rules.yml) - now only v2 frontmatter markdown format is supported

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

Added

• compare_to option in rules system for flexible change detection (#34)
  • base (default): Compare to merge-base with default branch
  • default_tip: Two-dot diff against default branch tip
  • prompt: Compare to state captured at prompt submission
• New learn command replacing refine for conversation-driven job improvement (#27)
  • Analyzes conversations where DeepWork jobs were run
  • Classifies learnings as generalizable (→ instructions) or bespoke (→ AGENTS.md)
  • Creates learning_summary.md documenting all changes
• "Think deeply" prompt in learn step for enhanced reasoning (#33)
• Supplementary markdown file support for job steps (#19)
• Browser automation capability consideration in job definition (#32)
• Platform-specific reload instructions in adapters (#31)
• Version and changelog update rule to enforce version tracking on src changes
• Added claude and copilot to CLA allowlist (#26)

Changed

• Moved git diff logic into evaluate_rules.py for per-rule handling (#34)
• Renamed capture_work_tree.sh to capture_prompt_work_tree.sh (#34)
• Updated README with PyPI install instructions using pipx, uv, and pip (#22)
• Updated deepwork_jobs job version to 0.2.0

Fixed

• Stop hooks now correctly return blocking JSON when rules fire
• Added shell script tests to verify stop hook blocking behavior

Removed

• refine step (replaced by learn command) (#27)
• get_changed_files.sh hook (logic moved to Python rule evaluator) (#34)

0.1.0 - Initial Release

Initial version.