From 208fbd9cbba0dd185a40ff053f1bda0eb49aa6e5 Mon Sep 17 00:00:00 2001 From: Noah Horton Date: Wed, 21 Jan 2026 16:55:38 -0700 Subject: [PATCH 1/3] fix: Use correct JSON format for Claude Code stop hooks The stop hook quality criteria validation was using incorrect JSON response format that Claude Code doesn't recognize: - {"ok": true} - Ignored by Claude Code - {"ok": false, "reason": "..."} - Not recognized as blocking Changed to the correct format per Claude Code documentation: - {} - Allow stop (empty JSON) - {"decision": "block", "reason": "..."} - Block and continue This fixes the issue where agents could declare quality criteria met without proper validation blocking incorrect completions. Co-Authored-By: Claude Opus 4.5 --- src/deepwork/templates/claude/skill-job-step.md.jinja | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/deepwork/templates/claude/skill-job-step.md.jinja b/src/deepwork/templates/claude/skill-job-step.md.jinja index c76aa1ac..570fc7d4 100644 --- a/src/deepwork/templates/claude/skill-job-step.md.jinja +++ b/src/deepwork/templates/claude/skill-job-step.md.jinja @@ -65,10 +65,10 @@ hooks: Look for evidence that each criterion has been addressed. If the agent has included `✓ Quality Criteria Met` in their response AND - all criteria appear to be met, respond with: {"ok": true} + all criteria appear to be met, respond with: {} If criteria are NOT met OR the promise tag is missing, respond with: - {"ok": false, "reason": "**AGENT: TAKE ACTION** - [which criteria failed and why]"} + {"decision": "block", "reason": "**AGENT: TAKE ACTION** - [which criteria failed and why]"} {% endfor %} {% endif %} {% for event_name, event_hooks in hooks.items() %} From 78633affd3ca8dcf1258498103752341b5b385f6 Mon Sep 17 00:00:00 2001 From: Noah Horton Date: Wed, 21 Jan 2026 17:18:12 -0700 Subject: [PATCH 2/3] docs: Update stop hook JSON format in documentation and rules - Update skill-template-best-practices rule with correct response format guidance - Fix hooks_system.md examples to use {} and {"decision": "block", ...} - Bump version to 0.5.1 and add changelog entry - Regenerate skill files with updated templates Co-Authored-By: Claude Opus 4.5 --- .claude/skills/deepwork_jobs.define/SKILL.md | 8 ++++---- .claude/skills/deepwork_jobs.implement/SKILL.md | 8 ++++---- .claude/skills/deepwork_jobs.learn/SKILL.md | 8 ++++---- .../skills/deepwork_jobs.review_job_spec/SKILL.md | 8 ++++---- .../skills/manual_tests.run_fire_tests/SKILL.md | 8 ++++---- .../manual_tests.run_not_fire_tests/SKILL.md | 8 ++++---- .deepwork/rules/skill-template-best-practices.md | 11 +++++++++++ CHANGELOG.md | 12 ++++++++++++ doc/platforms/claude/hooks_system.md | 14 ++++++-------- pyproject.toml | 2 +- 10 files changed, 54 insertions(+), 33 deletions(-) diff --git a/.claude/skills/deepwork_jobs.define/SKILL.md b/.claude/skills/deepwork_jobs.define/SKILL.md index c77c043a..f3ab572c 100644 --- a/.claude/skills/deepwork_jobs.define/SKILL.md +++ b/.claude/skills/deepwork_jobs.define/SKILL.md @@ -30,10 +30,10 @@ hooks: Look for evidence that each criterion has been addressed. If the agent has included `✓ Quality Criteria Met` in their response AND - all criteria appear to be met, respond with: {"ok": true} + all criteria appear to be met, respond with: {} If criteria are NOT met OR the promise tag is missing, respond with: - {"ok": false, "reason": "**AGENT: TAKE ACTION** - [which criteria failed and why]"} + {"decision": "block", "reason": "**AGENT: TAKE ACTION** - [which criteria failed and why]"} SubagentStop: - hooks: - type: prompt @@ -61,10 +61,10 @@ hooks: Look for evidence that each criterion has been addressed. If the agent has included `✓ Quality Criteria Met` in their response AND - all criteria appear to be met, respond with: {"ok": true} + all criteria appear to be met, respond with: {} If criteria are NOT met OR the promise tag is missing, respond with: - {"ok": false, "reason": "**AGENT: TAKE ACTION** - [which criteria failed and why]"} + {"decision": "block", "reason": "**AGENT: TAKE ACTION** - [which criteria failed and why]"} --- # deepwork_jobs.define diff --git a/.claude/skills/deepwork_jobs.implement/SKILL.md b/.claude/skills/deepwork_jobs.implement/SKILL.md index 9ad9bdcf..1d1f4f9b 100644 --- a/.claude/skills/deepwork_jobs.implement/SKILL.md +++ b/.claude/skills/deepwork_jobs.implement/SKILL.md @@ -27,10 +27,10 @@ hooks: Look for evidence that each criterion has been addressed. If the agent has included `✓ Quality Criteria Met` in their response AND - all criteria appear to be met, respond with: {"ok": true} + all criteria appear to be met, respond with: {} If criteria are NOT met OR the promise tag is missing, respond with: - {"ok": false, "reason": "**AGENT: TAKE ACTION** - [which criteria failed and why]"} + {"decision": "block", "reason": "**AGENT: TAKE ACTION** - [which criteria failed and why]"} SubagentStop: - hooks: - type: prompt @@ -55,10 +55,10 @@ hooks: Look for evidence that each criterion has been addressed. If the agent has included `✓ Quality Criteria Met` in their response AND - all criteria appear to be met, respond with: {"ok": true} + all criteria appear to be met, respond with: {} If criteria are NOT met OR the promise tag is missing, respond with: - {"ok": false, "reason": "**AGENT: TAKE ACTION** - [which criteria failed and why]"} + {"decision": "block", "reason": "**AGENT: TAKE ACTION** - [which criteria failed and why]"} --- # deepwork_jobs.implement diff --git a/.claude/skills/deepwork_jobs.learn/SKILL.md b/.claude/skills/deepwork_jobs.learn/SKILL.md index cecc8e6f..36e1085f 100644 --- a/.claude/skills/deepwork_jobs.learn/SKILL.md +++ b/.claude/skills/deepwork_jobs.learn/SKILL.md @@ -29,10 +29,10 @@ hooks: Look for evidence that each criterion has been addressed. If the agent has included `✓ Quality Criteria Met` in their response AND - all criteria appear to be met, respond with: {"ok": true} + all criteria appear to be met, respond with: {} If criteria are NOT met OR the promise tag is missing, respond with: - {"ok": false, "reason": "**AGENT: TAKE ACTION** - [which criteria failed and why]"} + {"decision": "block", "reason": "**AGENT: TAKE ACTION** - [which criteria failed and why]"} SubagentStop: - hooks: - type: prompt @@ -60,10 +60,10 @@ hooks: Look for evidence that each criterion has been addressed. If the agent has included `✓ Quality Criteria Met` in their response AND - all criteria appear to be met, respond with: {"ok": true} + all criteria appear to be met, respond with: {} If criteria are NOT met OR the promise tag is missing, respond with: - {"ok": false, "reason": "**AGENT: TAKE ACTION** - [which criteria failed and why]"} + {"decision": "block", "reason": "**AGENT: TAKE ACTION** - [which criteria failed and why]"} --- # deepwork_jobs.learn diff --git a/.claude/skills/deepwork_jobs.review_job_spec/SKILL.md b/.claude/skills/deepwork_jobs.review_job_spec/SKILL.md index 25915621..77e6d07e 100644 --- a/.claude/skills/deepwork_jobs.review_job_spec/SKILL.md +++ b/.claude/skills/deepwork_jobs.review_job_spec/SKILL.md @@ -22,10 +22,10 @@ hooks: Look for evidence that each criterion has been addressed. If the agent has included `✓ Quality Criteria Met` in their response AND - all criteria appear to be met, respond with: {"ok": true} + all criteria appear to be met, respond with: {} If criteria are NOT met OR the promise tag is missing, respond with: - {"ok": false, "reason": "**AGENT: TAKE ACTION** - [which criteria failed and why]"} + {"decision": "block", "reason": "**AGENT: TAKE ACTION** - [which criteria failed and why]"} SubagentStop: - hooks: - type: prompt @@ -45,10 +45,10 @@ hooks: Look for evidence that each criterion has been addressed. If the agent has included `✓ Quality Criteria Met` in their response AND - all criteria appear to be met, respond with: {"ok": true} + all criteria appear to be met, respond with: {} If criteria are NOT met OR the promise tag is missing, respond with: - {"ok": false, "reason": "**AGENT: TAKE ACTION** - [which criteria failed and why]"} + {"decision": "block", "reason": "**AGENT: TAKE ACTION** - [which criteria failed and why]"} --- # deepwork_jobs.review_job_spec diff --git a/.claude/skills/manual_tests.run_fire_tests/SKILL.md b/.claude/skills/manual_tests.run_fire_tests/SKILL.md index 65bb5a9b..172f8d25 100644 --- a/.claude/skills/manual_tests.run_fire_tests/SKILL.md +++ b/.claude/skills/manual_tests.run_fire_tests/SKILL.md @@ -24,10 +24,10 @@ hooks: Look for evidence that each criterion has been addressed. If the agent has included `✓ Quality Criteria Met` in their response AND - all criteria appear to be met, respond with: {"ok": true} + all criteria appear to be met, respond with: {} If criteria are NOT met OR the promise tag is missing, respond with: - {"ok": false, "reason": "**AGENT: TAKE ACTION** - [which criteria failed and why]"} + {"decision": "block", "reason": "**AGENT: TAKE ACTION** - [which criteria failed and why]"} SubagentStop: - hooks: - type: prompt @@ -49,10 +49,10 @@ hooks: Look for evidence that each criterion has been addressed. If the agent has included `✓ Quality Criteria Met` in their response AND - all criteria appear to be met, respond with: {"ok": true} + all criteria appear to be met, respond with: {} If criteria are NOT met OR the promise tag is missing, respond with: - {"ok": false, "reason": "**AGENT: TAKE ACTION** - [which criteria failed and why]"} + {"decision": "block", "reason": "**AGENT: TAKE ACTION** - [which criteria failed and why]"} --- # manual_tests.run_fire_tests diff --git a/.claude/skills/manual_tests.run_not_fire_tests/SKILL.md b/.claude/skills/manual_tests.run_not_fire_tests/SKILL.md index c3f2248c..1242fe18 100644 --- a/.claude/skills/manual_tests.run_not_fire_tests/SKILL.md +++ b/.claude/skills/manual_tests.run_not_fire_tests/SKILL.md @@ -23,10 +23,10 @@ hooks: Look for evidence that each criterion has been addressed. If the agent has included `✓ Quality Criteria Met` in their response AND - all criteria appear to be met, respond with: {"ok": true} + all criteria appear to be met, respond with: {} If criteria are NOT met OR the promise tag is missing, respond with: - {"ok": false, "reason": "**AGENT: TAKE ACTION** - [which criteria failed and why]"} + {"decision": "block", "reason": "**AGENT: TAKE ACTION** - [which criteria failed and why]"} SubagentStop: - hooks: - type: prompt @@ -47,10 +47,10 @@ hooks: Look for evidence that each criterion has been addressed. If the agent has included `✓ Quality Criteria Met` in their response AND - all criteria appear to be met, respond with: {"ok": true} + all criteria appear to be met, respond with: {} If criteria are NOT met OR the promise tag is missing, respond with: - {"ok": false, "reason": "**AGENT: TAKE ACTION** - [which criteria failed and why]"} + {"decision": "block", "reason": "**AGENT: TAKE ACTION** - [which criteria failed and why]"} --- # manual_tests.run_not_fire_tests diff --git a/.deepwork/rules/skill-template-best-practices.md b/.deepwork/rules/skill-template-best-practices.md index ff33ecfd..fda59c04 100644 --- a/.deepwork/rules/skill-template-best-practices.md +++ b/.deepwork/rules/skill-template-best-practices.md @@ -34,6 +34,17 @@ The description appears in skill search results and helps users find the right s 2. **Focus on outcomes** - What the output should achieve, not process steps 3. **Keep actionable** - Agent should be able to self-evaluate against criteria +## Stop Hook Response Format (Claude Code) + +When generating stop hooks with prompt validation, use the correct JSON format: + +- **Allow stop (criteria met)**: `{}` +- **Block and continue (criteria not met)**: `{"decision": "block", "reason": "[explanation]"}` + +**Incorrect formats to avoid**: +- `{"ok": true}` - Not recognized by Claude Code +- `{"ok": false, "reason": "..."}` - Not recognized as blocking + ## Platform Considerations - **Claude**: Supports hooks for automated validation; use Skill tool for step invocation diff --git a/CHANGELOG.md b/CHANGELOG.md index 60406257..30e1313e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,17 @@ 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.1] - 2026-01-21 + +### Fixed +- Stop hook prompt validation now uses correct JSON format recognized by Claude Code + - Changed from `{"ok": true}` / `{"ok": false, "reason": "..."}` to `{}` / `{"decision": "block", "reason": "..."}` + - This fixes quality criteria validation not properly blocking agent completion + +### Changed +- Updated skill template best practices rule with stop hook response format guidance +- Updated Claude Code hooks documentation with correct JSON format examples + ## [0.5.0] - 2026-01-20 ### Changed @@ -164,6 +175,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 Initial version. +[0.5.1]: https://github.com/anthropics/deepwork/releases/tag/0.5.1 [0.5.0]: https://github.com/anthropics/deepwork/releases/tag/0.5.0 [0.4.0]: https://github.com/anthropics/deepwork/releases/tag/0.4.0 [0.3.1]: https://github.com/anthropics/deepwork/releases/tag/0.3.1 diff --git a/doc/platforms/claude/hooks_system.md b/doc/platforms/claude/hooks_system.md index 037e253d..c3b980b1 100644 --- a/doc/platforms/claude/hooks_system.md +++ b/doc/platforms/claude/hooks_system.md @@ -67,8 +67,8 @@ hooks: - type: prompt prompt: | Verify all acceptance criteria are met. - If met, respond: {"ok": true} - If not met, respond: {"ok": false, "reason": "..."} + If met, respond: {} + If not met, respond: {"decision": "block", "reason": "..."} ``` **Blocking behavior**: Return JSON with `{"decision": "block", "reason": "..."}` or exit code 2 with stderr message. @@ -133,9 +133,7 @@ All hooks receive JSON via stdin: Hooks return JSON via stdout: ```json -{ - "ok": true -} +{} ``` Or to block: @@ -191,7 +189,7 @@ hooks: - type: prompt prompt: | Evaluate whether the response meets all criteria. - Respond with {"ok": true} or {"ok": false, "reason": "..."} + Respond with {} or {"decision": "block", "reason": "..."} ``` ## Quality Validation Loop Pattern @@ -219,9 +217,9 @@ hooks: 3. Documentation updated Review the conversation. If ALL criteria met and - tag present, respond: {"ok": true} + tag present, respond: {} - Otherwise respond: {"ok": false, "reason": "..."} + Otherwise respond: {"decision": "block", "reason": "..."} ``` ## Comparison with Other Platforms diff --git a/pyproject.toml b/pyproject.toml index a76599d4..c2bc3e4a 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "deepwork" -version = "0.5.0" +version = "0.5.1" description = "Framework for enabling AI agents to perform complex, multi-step work tasks" readme = "README.md" requires-python = ">=3.11" From 6e08e20d6c45e2039d47096aba372d46b79bacdf Mon Sep 17 00:00:00 2001 From: Noah Horton Date: Wed, 21 Jan 2026 17:35:36 -0700 Subject: [PATCH 3/3] more jobs for PR that will die --- .claude/settings.json | 6 +- .../skills/make_release.create_pr/SKILL.md | 167 +++++++++++++++++ .../make_release.gather_changes/SKILL.md | 163 +++++++++++++++++ .../make_release.prepare_release/SKILL.md | 172 ++++++++++++++++++ .claude/skills/make_release/SKILL.md | 72 ++++++++ .deepwork/jobs/make_release/AGENTS.md | 30 +++ .deepwork/jobs/make_release/hooks/.gitkeep | 0 .deepwork/jobs/make_release/job.yml | 56 ++++++ .../jobs/make_release/steps/create_pr.md | 97 ++++++++++ .../jobs/make_release/steps/gather_changes.md | 97 ++++++++++ .../make_release/steps/prepare_release.md | 95 ++++++++++ .../jobs/make_release/templates/.gitkeep | 0 .gemini/skills/make_release/create_pr.toml | 164 +++++++++++++++++ .../skills/make_release/gather_changes.toml | 160 ++++++++++++++++ .gemini/skills/make_release/index.toml | 70 +++++++ .../skills/make_release/prepare_release.toml | 169 +++++++++++++++++ uv.lock | 2 +- 17 files changed, 1518 insertions(+), 2 deletions(-) create mode 100644 .claude/skills/make_release.create_pr/SKILL.md create mode 100644 .claude/skills/make_release.gather_changes/SKILL.md create mode 100644 .claude/skills/make_release.prepare_release/SKILL.md create mode 100644 .claude/skills/make_release/SKILL.md create mode 100644 .deepwork/jobs/make_release/AGENTS.md create mode 100644 .deepwork/jobs/make_release/hooks/.gitkeep create mode 100644 .deepwork/jobs/make_release/job.yml create mode 100644 .deepwork/jobs/make_release/steps/create_pr.md create mode 100644 .deepwork/jobs/make_release/steps/gather_changes.md create mode 100644 .deepwork/jobs/make_release/steps/prepare_release.md create mode 100644 .deepwork/jobs/make_release/templates/.gitkeep create mode 100644 .gemini/skills/make_release/create_pr.toml create mode 100644 .gemini/skills/make_release/gather_changes.toml create mode 100644 .gemini/skills/make_release/index.toml create mode 100644 .gemini/skills/make_release/prepare_release.toml diff --git a/.claude/settings.json b/.claude/settings.json index b7190a76..776c59f2 100644 --- a/.claude/settings.json +++ b/.claude/settings.json @@ -119,7 +119,11 @@ "Skill(manual_tests.run_not_fire_tests)", "Skill(manual_tests.run_fire_tests)", "Skill(deepwork_rules)", - "Skill(deepwork_rules.define)" + "Skill(deepwork_rules.define)", + "Skill(make_release)", + "Skill(make_release.gather_changes)", + "Skill(make_release.prepare_release)", + "Skill(make_release.create_pr)" ] }, "hooks": { diff --git a/.claude/skills/make_release.create_pr/SKILL.md b/.claude/skills/make_release.create_pr/SKILL.md new file mode 100644 index 00000000..bd7607e1 --- /dev/null +++ b/.claude/skills/make_release.create_pr/SKILL.md @@ -0,0 +1,167 @@ +--- +name: make_release.create_pr +description: "Create a pull request with the release changes targeting main" +user-invocable: false +--- + +# make_release.create_pr + +**Step 3/3** in **make_release** workflow + +> Automate release preparation with changelog, version bump, and PR creation + +## Prerequisites (Verify First) + +Before proceeding, confirm these steps are complete: +- `/make_release.prepare_release` + +## Instructions + +**Goal**: Create a pull request with the release changes targeting main + +# Create Release PR + +## Objective + +Create a pull request with the release changes targeting the main branch. + +## Task + +Commit the updated release files and create a pull request using the GitHub CLI. + +### Process + +1. **Create a release branch** + ```bash + git checkout -b release/vX.Y.Z + ``` + Where X.Y.Z is the new version from the previous step. + +2. **Stage the release files** + ```bash + git add CHANGELOG.md pyproject.toml uv.lock + ``` + +3. **Commit the changes** + ```bash + git commit -m "chore: Release vX.Y.Z" + ``` + +4. **Push the branch** + ```bash + git push -u origin release/vX.Y.Z + ``` + +5. **Create the pull request** + ```bash + gh pr create --title "Release vX.Y.Z" --body "$(cat <<'EOF' + ## Summary + + Release version X.Y.Z + + ## Changes + + [Copy the changelog entry for this version here] + + ## Checklist + + - [ ] CHANGELOG.md updated + - [ ] pyproject.toml version bumped + - [ ] uv.lock synced + EOF + )" --base main + ``` + +6. **Record the PR URL** + Save the PR URL to `release/pr_url.md` for reference. + +## Output Format + +### release/pr_url.md + +A simple file containing the PR URL for easy reference. + +**Structure**: +```markdown +# Release PR + +**Version**: X.Y.Z +**PR URL**: https://github.com/owner/repo/pull/123 +**Created**: YYYY-MM-DD + +## Next Steps + +1. Review the PR +2. Ensure CI passes +3. Merge to main +4. Create GitHub release with tag vX.Y.Z +``` + +## Quality Criteria + +- Release branch is created with correct naming (`release/vX.Y.Z`) +- All three files are committed (CHANGELOG.md, pyproject.toml, uv.lock) +- Commit message follows conventional format +- PR is created targeting main branch +- PR body includes the changelog entry +- PR URL is saved to `release/pr_url.md` +- When all criteria are met, include `✓ Quality Criteria Met` in your response + +## Context + +This is the final step of the release workflow. After this step completes, the user should: +1. Review the PR +2. Wait for CI to pass +3. Merge the PR +4. Create a GitHub release with a tag matching the version + +The PR provides a review checkpoint before the release is finalized. + + +### Job Context + +A streamlined workflow for preparing releases of the DeepWork project. This job +automates the tedious parts of releasing: finding the latest version tag, gathering +commits since that tag, updating the changelog, bumping the version in pyproject.toml, +syncing uv.lock, and creating a pull request. + +The workflow analyzes commit history to recommend an appropriate version bump +(patch, minor, or major) based on the changes, then asks for confirmation before +proceeding. + +Outputs: +- Updated CHANGELOG.md with a new version entry +- Updated pyproject.toml with the new version +- Updated uv.lock +- A pull request targeting main + + + +## Work Branch + +Use branch format: `deepwork/make_release-[instance]-YYYYMMDD` + +- If on a matching work branch: continue using it +- If on main/master: create new branch with `git checkout -b deepwork/make_release-[instance]-$(date +%Y%m%d)` + +## Outputs + +**Required outputs**: +- `release/pr_url.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: "Step 3/3 complete, outputs: release/pr_url.md" +3. **Workflow complete**: All steps finished. Consider creating a PR to merge the work branch. + +--- + +**Reference files**: `.deepwork/jobs/make_release/job.yml`, `.deepwork/jobs/make_release/steps/create_pr.md` \ No newline at end of file diff --git a/.claude/skills/make_release.gather_changes/SKILL.md b/.claude/skills/make_release.gather_changes/SKILL.md new file mode 100644 index 00000000..c93f63d9 --- /dev/null +++ b/.claude/skills/make_release.gather_changes/SKILL.md @@ -0,0 +1,163 @@ +--- +name: make_release.gather_changes +description: "Find the latest version tag and collect all commits since then" +user-invocable: false +--- + +# make_release.gather_changes + +**Step 1/3** in **make_release** workflow + +> Automate release preparation with changelog, version bump, and PR creation + + +## Instructions + +**Goal**: Find the latest version tag and collect all commits since then + +# Gather Changes Since Last Release + +## Objective + +Find the latest version tag and collect all commits since then, analyzing them to recommend an appropriate version bump. + +## Task + +Query git to find the most recent release tag, gather all commits since that tag, and create a summary document with change categorization and a recommended version bump. + +### Process + +1. **Find the latest version tag** + ```bash + git describe --tags --abbrev=0 + ``` + This returns the most recent tag (e.g., `0.5.1`) + +2. **Get all commits since that tag** + ```bash + git log ..HEAD --oneline --no-merges + ``` + +3. **Categorize the changes** + Review each commit and categorize: + - **Breaking Changes**: API changes, renamed fields, removed features + - **Added**: New features, new files, new capabilities + - **Changed**: Modified behavior, refactoring + - **Fixed**: Bug fixes + - **Removed**: Deprecated features removed + +4. **Recommend a version bump** + Based on semantic versioning: + - **Major (X.0.0)**: Breaking changes that require migration + - **Minor (0.X.0)**: New features that are backward compatible + - **Patch (0.0.X)**: Bug fixes and small improvements + +5. **Ask structured questions to confirm** + Present the recommended version to the user and ask them to confirm or choose a different bump level. + +## Output Format + +### release/changes_summary.md + +A markdown document summarizing all changes and the version recommendation. + +**Structure**: +```markdown +# Release Changes Summary + +## Current Version +- **Latest Tag**: [tag name, e.g., 0.5.1] +- **Commits Since Tag**: [number] + +## Recommended Version +- **New Version**: [e.g., 0.6.0] +- **Bump Type**: [major/minor/patch] +- **Rationale**: [why this bump level] + +## Changes by Category + +### Breaking Changes +- [List any breaking changes, or "None"] + +### Added +- [List new features] + +### Changed +- [List modifications] + +### Fixed +- [List bug fixes] + +### Removed +- [List removed features, or "None"] + +## Commit Log +| Hash | Message | +|------|---------| +| abc1234 | feat: Add new feature | +| def5678 | fix: Fix bug in parser | +[... all commits since last tag] +``` + +## Quality Criteria + +- Latest version tag is correctly identified +- All commits since the tag are captured +- Changes are properly categorized (Added/Changed/Fixed/etc.) +- Version recommendation follows semantic versioning principles +- User is asked structured questions to confirm the version bump +- Output file is created at `release/changes_summary.md` +- When all criteria are met, include `✓ Quality Criteria Met` in your response + +## Context + +This is the first step in the release workflow. The changes summary produced here will be used by the `prepare_release` step to update the CHANGELOG and bump the version. Accurate categorization is important because it determines the changelog entry format and helps the user understand what's in the release. + + +### Job Context + +A streamlined workflow for preparing releases of the DeepWork project. This job +automates the tedious parts of releasing: finding the latest version tag, gathering +commits since that tag, updating the changelog, bumping the version in pyproject.toml, +syncing uv.lock, and creating a pull request. + +The workflow analyzes commit history to recommend an appropriate version bump +(patch, minor, or major) based on the changes, then asks for confirmation before +proceeding. + +Outputs: +- Updated CHANGELOG.md with a new version entry +- Updated pyproject.toml with the new version +- Updated uv.lock +- A pull request targeting main + + + +## Work Branch + +Use branch format: `deepwork/make_release-[instance]-YYYYMMDD` + +- If on a matching work branch: continue using it +- If on main/master: create new branch with `git checkout -b deepwork/make_release-[instance]-$(date +%Y%m%d)` + +## Outputs + +**Required outputs**: +- `release/changes_summary.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: "Step 1/3 complete, outputs: release/changes_summary.md" +3. **Continue workflow**: Use Skill tool to invoke `/make_release.prepare_release` + +--- + +**Reference files**: `.deepwork/jobs/make_release/job.yml`, `.deepwork/jobs/make_release/steps/gather_changes.md` \ No newline at end of file diff --git a/.claude/skills/make_release.prepare_release/SKILL.md b/.claude/skills/make_release.prepare_release/SKILL.md new file mode 100644 index 00000000..911528ee --- /dev/null +++ b/.claude/skills/make_release.prepare_release/SKILL.md @@ -0,0 +1,172 @@ +--- +name: make_release.prepare_release +description: "Update changelog, bump version in pyproject.toml, and sync uv.lock" +user-invocable: false +--- + +# make_release.prepare_release + +**Step 2/3** in **make_release** workflow + +> Automate release preparation with changelog, version bump, and PR creation + +## Prerequisites (Verify First) + +Before proceeding, confirm these steps are complete: +- `/make_release.gather_changes` + +## Instructions + +**Goal**: Update changelog, bump version in pyproject.toml, and sync uv.lock + +# Prepare Release Files + +## Objective + +Update the CHANGELOG.md with a new version entry, bump the version in pyproject.toml, and sync uv.lock. + +## Task + +Read the changes summary from the previous step and use it to update the release files with the confirmed version number. + +### Process + +1. **Read the changes summary** + Load `release/changes_summary.md` to get: + - The confirmed new version number + - The categorized changes + +2. **Update CHANGELOG.md** + Add a new version entry at the top of the changelog (after the header), following the Keep a Changelog format: + + ```markdown + ## [X.Y.Z] - YYYY-MM-DD + + ### Added + - [features from changes summary] + + ### Changed + - [modifications from changes summary] + + ### Fixed + - [bug fixes from changes summary] + ``` + + Also add the version link at the bottom: + ```markdown + [X.Y.Z]: https://github.com/anthropics/deepwork/releases/tag/X.Y.Z + ``` + +3. **Update pyproject.toml** + Change the `version` field to the new version: + ```toml + version = "X.Y.Z" + ``` + +4. **Sync uv.lock** + Run: + ```bash + uv lock + ``` + This updates the lock file with the new version. + +## Output Format + +The outputs are modifications to existing files: + +### CHANGELOG.md + +Add a new version section following Keep a Changelog format. Only include categories that have entries (don't include empty "### Removed" sections). + +**Example entry**: +```markdown +## [0.6.0] - 2026-01-21 + +### Added +- New `make_release` job for automating release preparation + +### Fixed +- Fixed edge case in version parsing +``` + +### pyproject.toml + +Update the version field: +```toml +version = "0.6.0" +``` + +### uv.lock + +This is auto-generated by `uv lock`. No manual edits needed. + +## Quality Criteria + +- CHANGELOG.md has a new version entry with today's date +- Version entry follows Keep a Changelog format +- Only non-empty categories are included in the changelog entry +- pyproject.toml version is updated to match +- `uv lock` ran successfully +- Version link is added at the bottom of CHANGELOG.md +- Changes in CHANGELOG match what was in the changes summary +- When all criteria are met, include `✓ Quality Criteria Met` in your response + +## Context + +This step transforms the raw change data into properly formatted release files. The CHANGELOG.md follows the Keep a Changelog format used by this project, which organizes changes into categories like Added, Changed, Fixed, etc. The next step will create a PR with these changes. + + +### Job Context + +A streamlined workflow for preparing releases of the DeepWork project. This job +automates the tedious parts of releasing: finding the latest version tag, gathering +commits since that tag, updating the changelog, bumping the version in pyproject.toml, +syncing uv.lock, and creating a pull request. + +The workflow analyzes commit history to recommend an appropriate version bump +(patch, minor, or major) based on the changes, then asks for confirmation before +proceeding. + +Outputs: +- Updated CHANGELOG.md with a new version entry +- Updated pyproject.toml with the new version +- Updated uv.lock +- A pull request targeting main + + +## Required Inputs + + +**Files from Previous Steps** - Read these first: +- `release/changes_summary.md` (from `gather_changes`) + +## Work Branch + +Use branch format: `deepwork/make_release-[instance]-YYYYMMDD` + +- If on a matching work branch: continue using it +- If on main/master: create new branch with `git checkout -b deepwork/make_release-[instance]-$(date +%Y%m%d)` + +## Outputs + +**Required outputs**: +- `CHANGELOG.md` +- `pyproject.toml` +- `uv.lock` + +## 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: "Step 2/3 complete, outputs: CHANGELOG.md, pyproject.toml, uv.lock" +3. **Continue workflow**: Use Skill tool to invoke `/make_release.create_pr` + +--- + +**Reference files**: `.deepwork/jobs/make_release/job.yml`, `.deepwork/jobs/make_release/steps/prepare_release.md` \ No newline at end of file diff --git a/.claude/skills/make_release/SKILL.md b/.claude/skills/make_release/SKILL.md new file mode 100644 index 00000000..281ccbc4 --- /dev/null +++ b/.claude/skills/make_release/SKILL.md @@ -0,0 +1,72 @@ +--- +name: make_release +description: "Automate release preparation with changelog, version bump, and PR creation" +--- + +# make_release + +**Multi-step workflow**: Automate release preparation with changelog, version bump, and PR creation + +> **CRITICAL**: Always invoke steps using the Skill tool. Never copy/paste step instructions directly. + +A streamlined workflow for preparing releases of the DeepWork project. This job +automates the tedious parts of releasing: finding the latest version tag, gathering +commits since that tag, updating the changelog, bumping the version in pyproject.toml, +syncing uv.lock, and creating a pull request. + +The workflow analyzes commit history to recommend an appropriate version bump +(patch, minor, or major) based on the changes, then asks for confirmation before +proceeding. + +Outputs: +- Updated CHANGELOG.md with a new version entry +- Updated pyproject.toml with the new version +- Updated uv.lock +- A pull request targeting main + + +## Available Steps + +1. **gather_changes** - Find the latest version tag and collect all commits since then +2. **prepare_release** - Update changelog, bump version in pyproject.toml, and sync uv.lock (requires: gather_changes) +3. **create_pr** - Create a pull request with the release changes targeting main (requires: prepare_release) + +## Execution Instructions + +### Step 1: Analyze Intent + +Parse any text following `/make_release` to determine user intent: +- "gather_changes" or related terms → start at `make_release.gather_changes` +- "prepare_release" or related terms → start at `make_release.prepare_release` +- "create_pr" or related terms → start at `make_release.create_pr` + +### Step 2: Invoke Starting Step + +Use the Skill tool to invoke the identified starting step: +``` +Skill tool: make_release.gather_changes +``` + +### Step 3: Continue Workflow Automatically + +After each step completes: +1. Check if there's a next step in the sequence +2. Invoke the next step using the Skill tool +3. Repeat until workflow is complete or user intervenes + +### Handling Ambiguous Intent + +If user intent is unclear, use AskUserQuestion to clarify: +- Present available steps as numbered options +- Let user select the starting point + +## Guardrails + +- Do NOT copy/paste step instructions directly; always use the Skill tool to invoke steps +- Do NOT skip steps in the workflow unless the user explicitly requests it +- Do NOT proceed to the next step if the current step's outputs are incomplete +- Do NOT make assumptions about user intent; ask for clarification when ambiguous + +## Context Files + +- Job definition: `.deepwork/jobs/make_release/job.yml` \ No newline at end of file diff --git a/.deepwork/jobs/make_release/AGENTS.md b/.deepwork/jobs/make_release/AGENTS.md new file mode 100644 index 00000000..15f0271b --- /dev/null +++ b/.deepwork/jobs/make_release/AGENTS.md @@ -0,0 +1,30 @@ +# Job Management + +This folder and its subfolders are managed using the `deepwork_jobs` slash commands. + +## Recommended Commands + +- `/deepwork_jobs.define` - Create or modify the job.yml specification +- `/deepwork_jobs.implement` - Generate step instruction files from the specification +- `/deepwork_jobs.learn` - Improve instructions based on execution learnings + +## Directory Structure + +``` +. +├── AGENTS.md # This file - project context and guidance +├── job.yml # Job specification (created by /deepwork_jobs.define) +├── steps/ # Step instruction files (created by /deepwork_jobs.implement) +│ └── *.md # One file per step +├── hooks/ # Custom validation scripts and prompts +│ └── *.md|*.sh # Hook files referenced in job.yml +└── templates/ # Example file formats and templates + └── *.md|*.yml # Templates referenced in step instructions +``` + +## Editing Guidelines + +1. **Use slash commands** for structural changes (adding steps, modifying job.yml) +2. **Direct edits** are fine for minor instruction tweaks +3. **Run `/deepwork_jobs.learn`** after executing job steps to capture improvements +4. **Run `deepwork sync`** after any changes to regenerate commands diff --git a/.deepwork/jobs/make_release/hooks/.gitkeep b/.deepwork/jobs/make_release/hooks/.gitkeep new file mode 100644 index 00000000..e69de29b diff --git a/.deepwork/jobs/make_release/job.yml b/.deepwork/jobs/make_release/job.yml new file mode 100644 index 00000000..c2728951 --- /dev/null +++ b/.deepwork/jobs/make_release/job.yml @@ -0,0 +1,56 @@ +name: make_release +version: "1.0.0" +summary: "Automate release preparation with changelog, version bump, and PR creation" +description: | + A streamlined workflow for preparing releases of the DeepWork project. This job + automates the tedious parts of releasing: finding the latest version tag, gathering + commits since that tag, updating the changelog, bumping the version in pyproject.toml, + syncing uv.lock, and creating a pull request. + + The workflow analyzes commit history to recommend an appropriate version bump + (patch, minor, or major) based on the changes, then asks for confirmation before + proceeding. + + Outputs: + - Updated CHANGELOG.md with a new version entry + - Updated pyproject.toml with the new version + - Updated uv.lock + - A pull request targeting main + +changelog: + - version: "1.0.0" + changes: "Initial job creation" + +steps: + - id: gather_changes + name: "Gather Changes Since Last Release" + description: "Find the latest version tag and collect all commits since then" + instructions_file: steps/gather_changes.md + inputs: [] + outputs: + - release/changes_summary.md + dependencies: [] + + - id: prepare_release + name: "Prepare Release Files" + description: "Update changelog, bump version in pyproject.toml, and sync uv.lock" + instructions_file: steps/prepare_release.md + inputs: + - file: release/changes_summary.md + from_step: gather_changes + outputs: + - CHANGELOG.md + - pyproject.toml + - uv.lock + dependencies: + - gather_changes + + - id: create_pr + name: "Create Release PR" + description: "Create a pull request with the release changes targeting main" + instructions_file: steps/create_pr.md + inputs: [] + outputs: + - release/pr_url.md + dependencies: + - prepare_release diff --git a/.deepwork/jobs/make_release/steps/create_pr.md b/.deepwork/jobs/make_release/steps/create_pr.md new file mode 100644 index 00000000..ffdba18c --- /dev/null +++ b/.deepwork/jobs/make_release/steps/create_pr.md @@ -0,0 +1,97 @@ +# Create Release PR + +## Objective + +Create a pull request with the release changes targeting the main branch. + +## Task + +Commit the updated release files and create a pull request using the GitHub CLI. + +### Process + +1. **Create a release branch** + ```bash + git checkout -b release/vX.Y.Z + ``` + Where X.Y.Z is the new version from the previous step. + +2. **Stage the release files** + ```bash + git add CHANGELOG.md pyproject.toml uv.lock + ``` + +3. **Commit the changes** + ```bash + git commit -m "chore: Release vX.Y.Z" + ``` + +4. **Push the branch** + ```bash + git push -u origin release/vX.Y.Z + ``` + +5. **Create the pull request** + ```bash + gh pr create --title "Release vX.Y.Z" --body "$(cat <<'EOF' + ## Summary + + Release version X.Y.Z + + ## Changes + + [Copy the changelog entry for this version here] + + ## Checklist + + - [ ] CHANGELOG.md updated + - [ ] pyproject.toml version bumped + - [ ] uv.lock synced + EOF + )" --base main + ``` + +6. **Record the PR URL** + Save the PR URL to `release/pr_url.md` for reference. + +## Output Format + +### release/pr_url.md + +A simple file containing the PR URL for easy reference. + +**Structure**: +```markdown +# Release PR + +**Version**: X.Y.Z +**PR URL**: https://github.com/owner/repo/pull/123 +**Created**: YYYY-MM-DD + +## Next Steps + +1. Review the PR +2. Ensure CI passes +3. Merge to main +4. Create GitHub release with tag vX.Y.Z +``` + +## Quality Criteria + +- Release branch is created with correct naming (`release/vX.Y.Z`) +- All three files are committed (CHANGELOG.md, pyproject.toml, uv.lock) +- Commit message follows conventional format +- PR is created targeting main branch +- PR body includes the changelog entry +- PR URL is saved to `release/pr_url.md` +- When all criteria are met, include `✓ Quality Criteria Met` in your response + +## Context + +This is the final step of the release workflow. After this step completes, the user should: +1. Review the PR +2. Wait for CI to pass +3. Merge the PR +4. Create a GitHub release with a tag matching the version + +The PR provides a review checkpoint before the release is finalized. diff --git a/.deepwork/jobs/make_release/steps/gather_changes.md b/.deepwork/jobs/make_release/steps/gather_changes.md new file mode 100644 index 00000000..4a00e079 --- /dev/null +++ b/.deepwork/jobs/make_release/steps/gather_changes.md @@ -0,0 +1,97 @@ +# Gather Changes Since Last Release + +## Objective + +Find the latest version tag and collect all commits since then, analyzing them to recommend an appropriate version bump. + +## Task + +Query git to find the most recent release tag, gather all commits since that tag, and create a summary document with change categorization and a recommended version bump. + +### Process + +1. **Find the latest version tag** + ```bash + git describe --tags --abbrev=0 + ``` + This returns the most recent tag (e.g., `0.5.1`) + +2. **Get all commits since that tag** + ```bash + git log ..HEAD --oneline --no-merges + ``` + +3. **Categorize the changes** + Review each commit and categorize: + - **Breaking Changes**: API changes, renamed fields, removed features + - **Added**: New features, new files, new capabilities + - **Changed**: Modified behavior, refactoring + - **Fixed**: Bug fixes + - **Removed**: Deprecated features removed + +4. **Recommend a version bump** + Based on semantic versioning: + - **Major (X.0.0)**: Breaking changes that require migration + - **Minor (0.X.0)**: New features that are backward compatible + - **Patch (0.0.X)**: Bug fixes and small improvements + +5. **Ask structured questions to confirm** + Present the recommended version to the user and ask them to confirm or choose a different bump level. + +## Output Format + +### release/changes_summary.md + +A markdown document summarizing all changes and the version recommendation. + +**Structure**: +```markdown +# Release Changes Summary + +## Current Version +- **Latest Tag**: [tag name, e.g., 0.5.1] +- **Commits Since Tag**: [number] + +## Recommended Version +- **New Version**: [e.g., 0.6.0] +- **Bump Type**: [major/minor/patch] +- **Rationale**: [why this bump level] + +## Changes by Category + +### Breaking Changes +- [List any breaking changes, or "None"] + +### Added +- [List new features] + +### Changed +- [List modifications] + +### Fixed +- [List bug fixes] + +### Removed +- [List removed features, or "None"] + +## Commit Log +| Hash | Message | +|------|---------| +| abc1234 | feat: Add new feature | +| def5678 | fix: Fix bug in parser | +[... all commits since last tag] +``` + +## Quality Criteria + +- Latest version tag is correctly identified +- All commits since the tag are captured +- Changes are properly categorized (Added/Changed/Fixed/etc.) +- Version recommendation follows semantic versioning principles +- User is asked structured questions to confirm the version bump +- Output file is created at `release/changes_summary.md` +- When all criteria are met, include `✓ Quality Criteria Met` in your response + +## Context + +This is the first step in the release workflow. The changes summary produced here will be used by the `prepare_release` step to update the CHANGELOG and bump the version. Accurate categorization is important because it determines the changelog entry format and helps the user understand what's in the release. diff --git a/.deepwork/jobs/make_release/steps/prepare_release.md b/.deepwork/jobs/make_release/steps/prepare_release.md new file mode 100644 index 00000000..6bc48246 --- /dev/null +++ b/.deepwork/jobs/make_release/steps/prepare_release.md @@ -0,0 +1,95 @@ +# Prepare Release Files + +## Objective + +Update the CHANGELOG.md with a new version entry, bump the version in pyproject.toml, and sync uv.lock. + +## Task + +Read the changes summary from the previous step and use it to update the release files with the confirmed version number. + +### Process + +1. **Read the changes summary** + Load `release/changes_summary.md` to get: + - The confirmed new version number + - The categorized changes + +2. **Update CHANGELOG.md** + Add a new version entry at the top of the changelog (after the header), following the Keep a Changelog format: + + ```markdown + ## [X.Y.Z] - YYYY-MM-DD + + ### Added + - [features from changes summary] + + ### Changed + - [modifications from changes summary] + + ### Fixed + - [bug fixes from changes summary] + ``` + + Also add the version link at the bottom: + ```markdown + [X.Y.Z]: https://github.com/anthropics/deepwork/releases/tag/X.Y.Z + ``` + +3. **Update pyproject.toml** + Change the `version` field to the new version: + ```toml + version = "X.Y.Z" + ``` + +4. **Sync uv.lock** + Run: + ```bash + uv lock + ``` + This updates the lock file with the new version. + +## Output Format + +The outputs are modifications to existing files: + +### CHANGELOG.md + +Add a new version section following Keep a Changelog format. Only include categories that have entries (don't include empty "### Removed" sections). + +**Example entry**: +```markdown +## [0.6.0] - 2026-01-21 + +### Added +- New `make_release` job for automating release preparation + +### Fixed +- Fixed edge case in version parsing +``` + +### pyproject.toml + +Update the version field: +```toml +version = "0.6.0" +``` + +### uv.lock + +This is auto-generated by `uv lock`. No manual edits needed. + +## Quality Criteria + +- CHANGELOG.md has a new version entry with today's date +- Version entry follows Keep a Changelog format +- Only non-empty categories are included in the changelog entry +- pyproject.toml version is updated to match +- `uv lock` ran successfully +- Version link is added at the bottom of CHANGELOG.md +- Changes in CHANGELOG match what was in the changes summary +- When all criteria are met, include `✓ Quality Criteria Met` in your response + +## Context + +This step transforms the raw change data into properly formatted release files. The CHANGELOG.md follows the Keep a Changelog format used by this project, which organizes changes into categories like Added, Changed, Fixed, etc. The next step will create a PR with these changes. diff --git a/.deepwork/jobs/make_release/templates/.gitkeep b/.deepwork/jobs/make_release/templates/.gitkeep new file mode 100644 index 00000000..e69de29b diff --git a/.gemini/skills/make_release/create_pr.toml b/.gemini/skills/make_release/create_pr.toml new file mode 100644 index 00000000..1a7bce88 --- /dev/null +++ b/.gemini/skills/make_release/create_pr.toml @@ -0,0 +1,164 @@ +# make_release:create_pr +# +# Create a pull request with the release changes targeting main +# +# Generated by DeepWork - do not edit manually + +description = "Create a pull request with the release changes targeting main" + +prompt = """ +# make_release:create_pr + +**Step 3/3** in **make_release** workflow + +> Automate release preparation with changelog, version bump, and PR creation + +## Prerequisites (Verify First) + +Before proceeding, confirm these steps are complete: +- `/make_release:prepare_release` + +## Instructions + +**Goal**: Create a pull request with the release changes targeting main + +# Create Release PR + +## Objective + +Create a pull request with the release changes targeting the main branch. + +## Task + +Commit the updated release files and create a pull request using the GitHub CLI. + +### Process + +1. **Create a release branch** + ```bash + git checkout -b release/vX.Y.Z + ``` + Where X.Y.Z is the new version from the previous step. + +2. **Stage the release files** + ```bash + git add CHANGELOG.md pyproject.toml uv.lock + ``` + +3. **Commit the changes** + ```bash + git commit -m "chore: Release vX.Y.Z" + ``` + +4. **Push the branch** + ```bash + git push -u origin release/vX.Y.Z + ``` + +5. **Create the pull request** + ```bash + gh pr create --title "Release vX.Y.Z" --body "$(cat <<'EOF' + ## Summary + + Release version X.Y.Z + + ## Changes + + [Copy the changelog entry for this version here] + + ## Checklist + + - [ ] CHANGELOG.md updated + - [ ] pyproject.toml version bumped + - [ ] uv.lock synced + EOF + )" --base main + ``` + +6. **Record the PR URL** + Save the PR URL to `release/pr_url.md` for reference. + +## Output Format + +### release/pr_url.md + +A simple file containing the PR URL for easy reference. + +**Structure**: +```markdown +# Release PR + +**Version**: X.Y.Z +**PR URL**: https://github.com/owner/repo/pull/123 +**Created**: YYYY-MM-DD + +## Next Steps + +1. Review the PR +2. Ensure CI passes +3. Merge to main +4. Create GitHub release with tag vX.Y.Z +``` + +## Quality Criteria + +- Release branch is created with correct naming (`release/vX.Y.Z`) +- All three files are committed (CHANGELOG.md, pyproject.toml, uv.lock) +- Commit message follows conventional format +- PR is created targeting main branch +- PR body includes the changelog entry +- PR URL is saved to `release/pr_url.md` +- When all criteria are met, include `✓ Quality Criteria Met` in your response + +## Context + +This is the final step of the release workflow. After this step completes, the user should: +1. Review the PR +2. Wait for CI to pass +3. Merge the PR +4. Create a GitHub release with a tag matching the version + +The PR provides a review checkpoint before the release is finalized. + + +### Job Context + +A streamlined workflow for preparing releases of the DeepWork project. This job +automates the tedious parts of releasing: finding the latest version tag, gathering +commits since that tag, updating the changelog, bumping the version in pyproject.toml, +syncing uv.lock, and creating a pull request. + +The workflow analyzes commit history to recommend an appropriate version bump +(patch, minor, or major) based on the changes, then asks for confirmation before +proceeding. + +Outputs: +- Updated CHANGELOG.md with a new version entry +- Updated pyproject.toml with the new version +- Updated uv.lock +- A pull request targeting main + + + +## Work Branch + +Use branch format: `deepwork/make_release-[instance]-YYYYMMDD` + +- If on a matching work branch: continue using it +- If on main/master: create new branch with `git checkout -b deepwork/make_release-[instance]-$(date +%Y%m%d)` + +## Outputs + +**Required outputs**: +- `release/pr_url.md` + +## On Completion + +1. Verify outputs are created +2. Inform user: "Step 3/3 complete, outputs: release/pr_url.md" +3. **Workflow complete**: All steps finished. Consider creating a PR to merge the work branch. + +--- + +**Reference files**: `.deepwork/jobs/make_release/job.yml`, `.deepwork/jobs/make_release/steps/create_pr.md` +""" \ No newline at end of file diff --git a/.gemini/skills/make_release/gather_changes.toml b/.gemini/skills/make_release/gather_changes.toml new file mode 100644 index 00000000..d293d528 --- /dev/null +++ b/.gemini/skills/make_release/gather_changes.toml @@ -0,0 +1,160 @@ +# make_release:gather_changes +# +# Find the latest version tag and collect all commits since then +# +# Generated by DeepWork - do not edit manually + +description = "Find the latest version tag and collect all commits since then" + +prompt = """ +# make_release:gather_changes + +**Step 1/3** in **make_release** workflow + +> Automate release preparation with changelog, version bump, and PR creation + + +## Instructions + +**Goal**: Find the latest version tag and collect all commits since then + +# Gather Changes Since Last Release + +## Objective + +Find the latest version tag and collect all commits since then, analyzing them to recommend an appropriate version bump. + +## Task + +Query git to find the most recent release tag, gather all commits since that tag, and create a summary document with change categorization and a recommended version bump. + +### Process + +1. **Find the latest version tag** + ```bash + git describe --tags --abbrev=0 + ``` + This returns the most recent tag (e.g., `0.5.1`) + +2. **Get all commits since that tag** + ```bash + git log ..HEAD --oneline --no-merges + ``` + +3. **Categorize the changes** + Review each commit and categorize: + - **Breaking Changes**: API changes, renamed fields, removed features + - **Added**: New features, new files, new capabilities + - **Changed**: Modified behavior, refactoring + - **Fixed**: Bug fixes + - **Removed**: Deprecated features removed + +4. **Recommend a version bump** + Based on semantic versioning: + - **Major (X.0.0)**: Breaking changes that require migration + - **Minor (0.X.0)**: New features that are backward compatible + - **Patch (0.0.X)**: Bug fixes and small improvements + +5. **Ask structured questions to confirm** + Present the recommended version to the user and ask them to confirm or choose a different bump level. + +## Output Format + +### release/changes_summary.md + +A markdown document summarizing all changes and the version recommendation. + +**Structure**: +```markdown +# Release Changes Summary + +## Current Version +- **Latest Tag**: [tag name, e.g., 0.5.1] +- **Commits Since Tag**: [number] + +## Recommended Version +- **New Version**: [e.g., 0.6.0] +- **Bump Type**: [major/minor/patch] +- **Rationale**: [why this bump level] + +## Changes by Category + +### Breaking Changes +- [List any breaking changes, or "None"] + +### Added +- [List new features] + +### Changed +- [List modifications] + +### Fixed +- [List bug fixes] + +### Removed +- [List removed features, or "None"] + +## Commit Log +| Hash | Message | +|------|---------| +| abc1234 | feat: Add new feature | +| def5678 | fix: Fix bug in parser | +[... all commits since last tag] +``` + +## Quality Criteria + +- Latest version tag is correctly identified +- All commits since the tag are captured +- Changes are properly categorized (Added/Changed/Fixed/etc.) +- Version recommendation follows semantic versioning principles +- User is asked structured questions to confirm the version bump +- Output file is created at `release/changes_summary.md` +- When all criteria are met, include `✓ Quality Criteria Met` in your response + +## Context + +This is the first step in the release workflow. The changes summary produced here will be used by the `prepare_release` step to update the CHANGELOG and bump the version. Accurate categorization is important because it determines the changelog entry format and helps the user understand what's in the release. + + +### Job Context + +A streamlined workflow for preparing releases of the DeepWork project. This job +automates the tedious parts of releasing: finding the latest version tag, gathering +commits since that tag, updating the changelog, bumping the version in pyproject.toml, +syncing uv.lock, and creating a pull request. + +The workflow analyzes commit history to recommend an appropriate version bump +(patch, minor, or major) based on the changes, then asks for confirmation before +proceeding. + +Outputs: +- Updated CHANGELOG.md with a new version entry +- Updated pyproject.toml with the new version +- Updated uv.lock +- A pull request targeting main + + + +## Work Branch + +Use branch format: `deepwork/make_release-[instance]-YYYYMMDD` + +- If on a matching work branch: continue using it +- If on main/master: create new branch with `git checkout -b deepwork/make_release-[instance]-$(date +%Y%m%d)` + +## Outputs + +**Required outputs**: +- `release/changes_summary.md` + +## On Completion + +1. Verify outputs are created +2. Inform user: "Step 1/3 complete, outputs: release/changes_summary.md" +3. **Tell user next command**: `/make_release:prepare_release` + +--- + +**Reference files**: `.deepwork/jobs/make_release/job.yml`, `.deepwork/jobs/make_release/steps/gather_changes.md` +""" \ No newline at end of file diff --git a/.gemini/skills/make_release/index.toml b/.gemini/skills/make_release/index.toml new file mode 100644 index 00000000..e74105ff --- /dev/null +++ b/.gemini/skills/make_release/index.toml @@ -0,0 +1,70 @@ +# make_release +# +# Automate release preparation with changelog, version bump, and PR creation +# +# Generated by DeepWork - do not edit manually + +description = "Automate release preparation with changelog, version bump, and PR creation" + +prompt = """ +# make_release + +**Multi-step workflow**: Automate release preparation with changelog, version bump, and PR creation + +> **NOTE**: Gemini CLI requires manual command invocation. After each step, tell the user which command to run next. + +A streamlined workflow for preparing releases of the DeepWork project. This job +automates the tedious parts of releasing: finding the latest version tag, gathering +commits since that tag, updating the changelog, bumping the version in pyproject.toml, +syncing uv.lock, and creating a pull request. + +The workflow analyzes commit history to recommend an appropriate version bump +(patch, minor, or major) based on the changes, then asks for confirmation before +proceeding. + +Outputs: +- Updated CHANGELOG.md with a new version entry +- Updated pyproject.toml with the new version +- Updated uv.lock +- A pull request targeting main + + +## Available Steps + +1. **gather_changes** - Find the latest version tag and collect all commits since then + Command: `/make_release:gather_changes` +2. **prepare_release** - Update changelog, bump version in pyproject.toml, and sync uv.lock (requires: gather_changes) + Command: `/make_release:prepare_release` +3. **create_pr** - Create a pull request with the release changes targeting main (requires: prepare_release) + Command: `/make_release:create_pr` + +## Execution Instructions + +### Step 1: Analyze Intent + +Parse any text following `/make_release` to determine user intent: +- "gather_changes" or related terms → start at `/make_release:gather_changes` +- "prepare_release" or related terms → start at `/make_release:prepare_release` +- "create_pr" or related terms → start at `/make_release:create_pr` + +### Step 2: Direct User to Starting Step + +Tell the user which command to run: +``` +/make_release:gather_changes +``` + +### Step 3: Guide Through Workflow + +After each step completes, tell the user the next command to run until workflow is complete. + +### Handling Ambiguous Intent + +If user intent is unclear: +- Present available steps as numbered options +- Ask user to select the starting point + +## Reference + +- Job definition: `.deepwork/jobs/make_release/job.yml` +""" \ No newline at end of file diff --git a/.gemini/skills/make_release/prepare_release.toml b/.gemini/skills/make_release/prepare_release.toml new file mode 100644 index 00000000..3cd8e4ff --- /dev/null +++ b/.gemini/skills/make_release/prepare_release.toml @@ -0,0 +1,169 @@ +# make_release:prepare_release +# +# Update changelog, bump version in pyproject.toml, and sync uv.lock +# +# Generated by DeepWork - do not edit manually + +description = "Update changelog, bump version in pyproject.toml, and sync uv.lock" + +prompt = """ +# make_release:prepare_release + +**Step 2/3** in **make_release** workflow + +> Automate release preparation with changelog, version bump, and PR creation + +## Prerequisites (Verify First) + +Before proceeding, confirm these steps are complete: +- `/make_release:gather_changes` + +## Instructions + +**Goal**: Update changelog, bump version in pyproject.toml, and sync uv.lock + +# Prepare Release Files + +## Objective + +Update the CHANGELOG.md with a new version entry, bump the version in pyproject.toml, and sync uv.lock. + +## Task + +Read the changes summary from the previous step and use it to update the release files with the confirmed version number. + +### Process + +1. **Read the changes summary** + Load `release/changes_summary.md` to get: + - The confirmed new version number + - The categorized changes + +2. **Update CHANGELOG.md** + Add a new version entry at the top of the changelog (after the header), following the Keep a Changelog format: + + ```markdown + ## [X.Y.Z] - YYYY-MM-DD + + ### Added + - [features from changes summary] + + ### Changed + - [modifications from changes summary] + + ### Fixed + - [bug fixes from changes summary] + ``` + + Also add the version link at the bottom: + ```markdown + [X.Y.Z]: https://github.com/anthropics/deepwork/releases/tag/X.Y.Z + ``` + +3. **Update pyproject.toml** + Change the `version` field to the new version: + ```toml + version = "X.Y.Z" + ``` + +4. **Sync uv.lock** + Run: + ```bash + uv lock + ``` + This updates the lock file with the new version. + +## Output Format + +The outputs are modifications to existing files: + +### CHANGELOG.md + +Add a new version section following Keep a Changelog format. Only include categories that have entries (don't include empty "### Removed" sections). + +**Example entry**: +```markdown +## [0.6.0] - 2026-01-21 + +### Added +- New `make_release` job for automating release preparation + +### Fixed +- Fixed edge case in version parsing +``` + +### pyproject.toml + +Update the version field: +```toml +version = "0.6.0" +``` + +### uv.lock + +This is auto-generated by `uv lock`. No manual edits needed. + +## Quality Criteria + +- CHANGELOG.md has a new version entry with today's date +- Version entry follows Keep a Changelog format +- Only non-empty categories are included in the changelog entry +- pyproject.toml version is updated to match +- `uv lock` ran successfully +- Version link is added at the bottom of CHANGELOG.md +- Changes in CHANGELOG match what was in the changes summary +- When all criteria are met, include `✓ Quality Criteria Met` in your response + +## Context + +This step transforms the raw change data into properly formatted release files. The CHANGELOG.md follows the Keep a Changelog format used by this project, which organizes changes into categories like Added, Changed, Fixed, etc. The next step will create a PR with these changes. + + +### Job Context + +A streamlined workflow for preparing releases of the DeepWork project. This job +automates the tedious parts of releasing: finding the latest version tag, gathering +commits since that tag, updating the changelog, bumping the version in pyproject.toml, +syncing uv.lock, and creating a pull request. + +The workflow analyzes commit history to recommend an appropriate version bump +(patch, minor, or major) based on the changes, then asks for confirmation before +proceeding. + +Outputs: +- Updated CHANGELOG.md with a new version entry +- Updated pyproject.toml with the new version +- Updated uv.lock +- A pull request targeting main + + +## Required Inputs + + +**Files from Previous Steps** - Read these first: +- `release/changes_summary.md` (from `gather_changes`) + +## Work Branch + +Use branch format: `deepwork/make_release-[instance]-YYYYMMDD` + +- If on a matching work branch: continue using it +- If on main/master: create new branch with `git checkout -b deepwork/make_release-[instance]-$(date +%Y%m%d)` + +## Outputs + +**Required outputs**: +- `CHANGELOG.md` +- `pyproject.toml` +- `uv.lock` + +## On Completion + +1. Verify outputs are created +2. Inform user: "Step 2/3 complete, outputs: CHANGELOG.md, pyproject.toml, uv.lock" +3. **Tell user next command**: `/make_release:create_pr` + +--- + +**Reference files**: `.deepwork/jobs/make_release/job.yml`, `.deepwork/jobs/make_release/steps/prepare_release.md` +""" \ No newline at end of file diff --git a/uv.lock b/uv.lock index 564a99f6..5c61745e 100644 --- a/uv.lock +++ b/uv.lock @@ -126,7 +126,7 @@ toml = [ [[package]] name = "deepwork" -version = "0.5.0" +version = "0.5.1" source = { editable = "." } dependencies = [ { name = "click" },